Version: 1.2

Query definitions with the API

Use the Insights API to check for schema drift before you roll out a change that depends on a field being the same on every control plane.

Before you begin

A hub kubectl context. See Configure kubectl for the Hub.
Permission to read control planes in at least one realm. See the Roles reference.
At least one connected control plane or space.
jq.

Several steps send query parameters with kubectl get --raw. Use Hub APIs with kubectl explains why, and how paging, sorting, and counts work.

List definitions

Definitions are typedefinitions in the inventory.hub.upbound.io/v1beta1 API group. They're globally scoped, so the path has no namespace.

kubectl --context=hub get --raw \
  '/apis/inventory.hub.upbound.io/v1beta1/typedefinitions?pageSize=25' \
  | jq -r '.items[] | [.metadata.name, .definition.kind, .summary.controlPlaneCount, .summary.resourceCount] | @tsv'

Each item has three parts:

Field	Contains
`definition`	The type's identity: `group`, `kind`, `names`, `scope`, and `categories`.
`definedBy`	How many control planes define the type through each source: `CompositeResourceDefinition`, `ManagedResourceDefinition`, or `CustomResourceDefinition`. `CustomResourceDefinition` counts only control planes that define the type with a CRD alone.
`summary`	`controlPlaneCount`, `resourceCount`, `versionCount`, `hasSchemaVariants`, and `hasDeprecationMismatch`.

A type defined by an XRD also has a composite field, with its claim names and default composition.

Search with search, which matches part of the API group, kind, or plural name. Sort with sort, using name, group, kind, controlPlaneCount, resourceCount, versionCount, createdAt, or updatedAt. Prefix a field with - to sort in descending order:

kubectl --context=hub get --raw \
  '/apis/inventory.hub.upbound.io/v1beta1/typedefinitions?search=webapp&sort=-resourceCount&pageSize=25'

Find schema drift

Filter with an expression on these fields, and URL-encode it. See Encode a filter expression.

Filter field	Type	Matches
`schemaVariants`	boolean	Types where a version has more than one schema.
`deprecationMismatch`	boolean	Types where control planes disagree on which versions are deprecated.
`sourceKind`	string	Types defined through `CompositeResourceDefinition`, `ManagedResourceDefinition`, or `CustomResourceDefinition` on any control plane. A type can match more than one.
`controlPlane`	string	Types served by the named control plane.
`realm`	string	Types served by a control plane in the named realm.

List the types with schema variants in one realm:

FILTER=$(jq -rn --arg f 'schemaVariants && realm in ["default"]' '$f|@uri')
kubectl --context=hub get --raw \
  "/apis/inventory.hub.upbound.io/v1beta1/typedefinitions?pageSize=100&filter=$FILTER" \
  | jq -r '.items[].metadata.name'

Get one definition

A definition's name is its plural and API group, the same as its CRD name:

kubectl --context=hub get --raw \
  '/apis/inventory.hub.upbound.io/v1beta1/typedefinitions/webapps.platform.example.com'

See which control planes serve each version

The distribution subresource breaks a type down by version:

kubectl --context=hub get --raw \
  '/apis/inventory.hub.upbound.io/v1beta1/typedefinitions/webapps.platform.example.com/distribution' \
  | jq -r '.versions[] | .name as $v | .controlPlanes[] | [$v, .realm, .name, .served, .deprecated, .schemaRef.name] | @tsv'

Each entry in versions has:

Field	Contains
`name`	The API version, such as `v1beta1`.
`controlPlaneCount`, `resourceCount`, `servedCount`, `storageVersionCount`	Counts for this version across the fleet.
`deprecation`	`deprecatedCount`, and `hasMismatch`, which is `true` when some control planes mark the version deprecated and others don't.
`schema.variants`	One entry per distinct schema, with its `schemaHash`, a `schemaRef`, and how many control planes and resources use it. The most widely used variant comes first.
`controlPlanes`	One row per control plane: its `name` and `realm`, the `schemaRef` it serves, whether the version is `served`, `isStorageVersion`, and `deprecated`, its `resourceCount`, and the package that installed the type in `source`.

Two control planes serve the same schema when their schemaRef matches. The API returns schema hashes, not the schemas themselves. To read or compare two schemas, use the Console.

Narrow the rows with query parameters: version, realm (comma-separated), sourceKind, served, deprecated, and isStorageVersion. The counts then cover only the matching rows. Find the control planes that still serve a deprecated version:

kubectl --context=hub get --raw \
  '/apis/inventory.hub.upbound.io/v1beta1/typedefinitions/webapps.platform.example.com/distribution?deprecated=true&served=true' \
  | jq -r '.versions[] | .name as $v | .controlPlanes[] | "\($v)\t\(.realm)/\(.name)"'

Troubleshoot

Status	Cause
`404` on every request	Your platform team turned off the `AggregatedTypes` feature flag.
`404` for one definition	No control plane you have permission to read serves the type. See Access-scoped results.
`400` with `must be in the format {plural}.{group}`	The name is missing its API group.
`400` on a list	The filter expression doesn't parse, or names a field or sort key the API doesn't accept.

Before you begin​

List definitions​

Find schema drift​

Get one definition​

See which control planes serve each version​

Troubleshoot​

Next steps​