Feature flags

Hub keeps several features behind feature flags. Each flagged feature is at either the alpha or beta stage of the feature lifecycle, which sets its default state:

• Alpha features are disabled by default. You opt in explicitly.
• Beta features are enabled by default. The flag stays available so you can turn the feature off.

Once a feature reaches general availability its flag is removed and the feature is always on, so GA features don't appear here. See the feature lifecycle for the stability, support, and API-compatibility expectations at each stage.

How feature flags work

Each gate has a built-in default in hub-core, and the chart only passes your overrides. When you override nothing, the built-in defaults stand.

hub-core serves its flags over OFREP. Each gate is named after the capability it controls, as a single PascalCase token such as Catalog or Registry.

hub-core.api.featureFlags.enabled controls the flag server itself, which defaults to true. Leave it on. When it's false, hub-core runs without the flag server: it ignores your gates.* values and every gate keeps its built-in default.

Available feature flags

Set a gate with hub-core.api.featureFlags.gates.<Gate>; drop the leading hub-core. if you install the hub-core subchart on its own. The gate name is also the name that appears in FEATURE_GATES and in the hub-core startup logs. AggregatedTypes is beta and defaults to true. The other gates in this table are alpha and default to false.

Gate	Default	What it enables
AggregatedTypes	true	Fleet-wide typedefinitions and crossplanepackages, and their distribution subresources, under inventory.hub.upbound.io/v1beta1.
Catalog	false	The Catalog feature as a unit: the read API (catalog.hub.upbound.io/v1alpha1) covering Image list and get, usage, curated, OpenAPI subresources, and ImageSearch, plus the ingest and enrichment pipeline that populates it.
Metrics	false	The metrics ingest endpoint and the Query resource at fleet.hub.upbound.io/v1alpha1. Requires hub-core.otelGateway.enabled=true.
Registry	false	The Connection resource (with its verify subresource) and the Repository resource, served at catalog.hub.upbound.io/v1alpha1.
RegistryScan	false	The worker that scans each Repository for new tags and adds them to Catalog.

Aggregated types

The AggregatedTypes gate serves the fleet-wide typedefinitions and crossplanepackages resources, along with their distribution subresources. It defaults to true because the Definitions and Packages views in the Console read those APIs. Setting it to false hides both views and drops both resources from inventory.hub.upbound.io/v1beta1 discovery. The rest of the group keeps working.

Catalog

The Catalog gate turns the feature on as a unit: the read API and the ingest and enrichment pipeline that populates it move together behind the one gate. See Catalog for what the feature does.

Metrics

The Metrics gate turns on the query API and the endpoint connectors push to. It also needs the components that carry the pipeline: set hub-core.otelGateway.enabled=true and a backend, or hub-core refuses to start. Enabling the gate collects nothing until you also turn on the collector in the hub-connector chart. See Metrics and Metrics pipeline.

Registry

The Registry gate serves the connections that give Catalog credentials for private or self-hosted registries, and the repositories Hub can scan. It works with or without the Catalog gate. See Connect a registry.

Registry scan

The RegistryScan gate turns on scanning: Hub lists the tags of each repository on its schedule and adds new ones to Catalog. Without it, you can still create repositories, but Hub doesn't scan them. See Connect a registry.

Enabling a feature gate

Gates go in the same values.yaml you installed with, and a helm upgrade applies them. The hub-core startup logs report the resolved value of every gate, so check them to confirm which gates the running binary picked up.

values.yaml

hub-core:
  api:
    featureFlags:
      gates:
        Catalog: true
        Registry: true
        Metrics: true

  # Required whenever the Metrics gate is on.
  otelGateway:
    enabled: true
    metrics:
      backend: prometheus
      queryURL: http://prometheus-server.monitoring.svc
      prometheus:
        writeEndpoint: http://prometheus-server.monitoring.svc/api/v1/write

Disabling a beta feature works the same way in reverse. Set its gate to false to turn off a feature that defaults to on.

Managing flags outside the chart

For teams that manage flag definitions themselves:

• Targeting overlay. Set hub-core.api.featureFlags.targetingOverlay.configMapRef.name to a ConfigMap you maintain, holding a flagd flags.json under the key named by targetingOverlay.configMapRef.key (default flags.json). The overlay doesn't replace the gates. It layers JSONLogic targeting rules or extra variants on top of them, which is how you roll a feature out per organization or per control plane rather than fleet-wide. hub-core hot-reloads the ConfigMap, so edits take effect without restarting the Pods.
• OFREP endpoint. The flag server serves OFREP on port 8016 for client-side evaluation. Whenever the hub-core HTTPRoute is enabled, through hub-core.httpRoute.enabled or the gateway integration, and hub-core.api.featureFlags.enabled is true, the route also serves it at /ofrep.