Skip to main content

Rollout Descriptor Enrichment Providers to Production

This guide provides a checklist for safely rolling out a Descriptor Enrichment Provider to production. Follow these steps to avoid unexpected failures when enabling providers that modify the descriptor passed to governance policies and Tech Adapters.

Rollout checklist​

1. Verify Tech Adapter descriptor tolerance​

When a Descriptor Enrichment Provider is active, Tech Adapters receive a descriptor containing additional fields that were not present before.

warning

Check your Tech Adapters before enabling a provider in production. A Tech Adapter that strictly validates the descriptor against a fixed schema, or that fails on unknown fields, may reject the enriched descriptor and cause provisioning errors.

Recommended checks for each Tech Adapter in your platform:

  • Schema validation: if the adapter validates the incoming descriptor against a JSON Schema or OpenAPI schema, verify that the schema uses additionalProperties: true (or equivalent) so that new top-level fields are accepted.
  • Field mapping: if the adapter deserialises the descriptor into a typed data class, verify that unknown fields are ignored rather than causing a deserialisation error (e.g. Jackson's @JsonIgnoreProperties(ignoreUnknown = true) in Java, or Pydantic's model_config = ConfigDict(extra='ignore') in Python).
  • Explicit allowlists: if the adapter copies descriptor fields into a downstream payload using an explicit allowlist, no action is needed — unknown fields are naturally excluded.

If a Tech Adapter does need updating, coordinate the adapter deployment before enabling the provider for the affected project types. You can use the System Types setting to limit descriptor enrichment to project types whose adapters have already been validated.

2. Review governance policies​

Governance policies that reference fields added by a Descriptor Enrichment Provider should handle the case where the field is absent — for example, when the provider is disabled, when the project has not yet triggered a provider call, or when the Failure Mode is set to Fail Open and an error occurred.

Refer to the individual provider's documentation to confirm which fields it adds and what values they contain.

3. Enable with Fail Open first​

Start with Failure Mode set to Fail Open (the default). This ensures that if the provider is unreachable or times out — for example, due to upstream service availability issues — provisioning operations are not blocked.

Monitor the platform logs for skipped-provider warnings after enabling. Frequent warnings indicate a connectivity or timeout issue that should be resolved before switching to Fail Closed.

See the enable guide for configuration details.

4. Validate enriched descriptors in a lower environment​

Before enabling in production:

  1. Enable the provider in a non-production environment.
  2. Trigger a test deployment or policy evaluation through the Builder.
  3. Inspect the governance evaluation result and confirm that descriptor is enriched.
  4. Verify Tech Adapters in that environment handle the enriched descriptor without errors.

5. Understand cache warm-up behaviour​

The first provider call after enabling (or after cache expiry) incurs a live call to the upstream service. Subsequent calls within the Cache TTL (seconds) window are served from the in-memory cache.

In environments with many concurrent provisioning operations starting at the same time (e.g. after a platform restart), multiple simultaneous cache misses can cause a burst of requests to the upstream service. This is typically harmless for small environment counts (3–5), but worth being aware of at scale.

See the configuration reference for tuning guidance.

6. Optionally switch to Fail Closed​

Once you have confirmed:

  • The provider returns correct data consistently.
  • Tech Adapters handle the enriched descriptor without errors.
  • Governance policies handle the enriched fields correctly.

You can switch Failure Mode to Fail Closed if your use case requires the provider's data and you want provisioning to be blocked rather than proceed with incomplete descriptor enrichment.

Next steps​

After successful production rollout:

  • Monitor provider performance and adjust timeout and cache TTL settings as needed
  • Update governance policies to leverage the newly available enriched data
  • Document which providers are enabled and their configuration for your team