Version: 1.2

Query the catalog with the API

Use the Catalog API to look up a package's APIs and schemas from your own tooling, such as checking which APIs a new provider version introduces before you roll it out.

Before you begin

A hub kubectl context. See Configure kubectl for the Hub.
Your platform team turns on the Catalog feature flag.
Permission to read catalog images.
jq.

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

Search the catalog

Searches are imagesearches in the catalog.hub.upbound.io/v1alpha1 API group. Create one with a query, and Hub returns the matching images in its status. Search matches the same fields as the Console: repository, title, description, and the kind, group, version, short names, and categories of each API.

kubectl --context=hub create -o json -f - <<'EOF' | jq -r '.status.results.items[] | [.repository, .tag, .packageType] | @tsv'
apiVersion: catalog.hub.upbound.io/v1alpha1
kind: ImageSearch
spec:
  query: bucket
  pageSize: 25
EOF

Add facets to count the results by packageType or deploymentStatus. Hub returns the counts in status.facets:

spec:
  query: bucket
  facets: [packageType, deploymentStatus]

List images

Images are images in the same API group. Images are shared across all realms in Hub, so the path has no namespace.

kubectl --context=hub get --raw \
  '/apis/catalog.hub.upbound.io/v1alpha1/images?pageSize=25' \
  | jq -r '.items[] | [.metadata.name, .repository, .tag, .deploymentStatus, .usageCount] | @tsv'

Filter with an expression, and URL-encode it. See Encode a filter expression. These fields are the ones you're most likely to filter on:

Filter field	Matches
`repository`, `tag`, `packageName`	The image's repository, tag, and package name.
`packageType`	`Provider`, `Configuration`, `Function`, `AddOn`, or `Container`.
`deploymentStatus`	`deployed` or `available`.
`usageCount`	How many control planes deploy the image.
`enrichmentStatus`	`pending`, `in_progress`, `succeeded`, or `failed`.
`discoveredAt`, `lastSeenAt`	When Hub first and last saw the image.

The API reference at https://<hub-host>/docs lists every filter and sort field. List the images that no control plane deploys:

FILTER=$(jq -rn --arg f 'deploymentStatus == "available"' '$f|@uri')
kubectl --context=hub get --raw \
  "/apis/catalog.hub.upbound.io/v1alpha1/images?pageSize=100&filter=$FILTER" \
  | jq -r '.items[] | "\(.repository):\(.tag)"'

Get one image

An image's name is its digest, with : replaced by ~, such as sha256~5f3c…. Each image lists the APIs it introduces in apis:

kubectl --context=hub get --raw \
  '/apis/catalog.hub.upbound.io/v1alpha1/images/sha256~<digest>' \
  | jq -r '.apis[] | [.group, .version, .kind, .scope] | @tsv'

Read an API's schema

The openapi subresource returns the schema of one API the image introduces. Pass its group, version, and kind:

kubectl --context=hub get --raw \
  '/apis/catalog.hub.upbound.io/v1alpha1/images/sha256~<digest>/openapi?group=platform.example.com&version=v1alpha1&kind=WebApp' \
  | jq '.schema'

See where an image runs

The usage subresource lists the control planes that deploy the image, and how many resources use each of its APIs:

kubectl --context=hub get --raw \
  '/apis/catalog.hub.upbound.io/v1alpha1/images/sha256~<digest>/usage' \
  | jq '{deployedOn: [.items[] | "\(.realm)/\(.controlPlane)"], apis: [.apis[] | {kind, totalObjects}]}'

Field	Contains
`items`	One entry per control plane: its `realm` and `controlPlane`, the package object's name in `crName`, and the `packageRef` it declares.
`apis`	One entry per API: its `group`, `version`, and `kind`, the `totalObjects` across your fleet, and the count on each control plane in `byControlPlane`.

Approve and annotate an image

Mark an image as approved, and give it a category, notes, and labels, by replacing its curated subresource. Hub returns them in the image's curated field, and approved appears on every list and search result.

kubectl --context=hub replace --raw \
  /apis/catalog.hub.upbound.io/v1alpha1/images/sha256~<digest>/curated \
  -f - <<'EOF'
{
  "apiVersion": "catalog.hub.upbound.io/v1alpha1",
  "kind": "ImageCurated",
  "approved": true,
  "category": "networking",
  "notes": "Approved for production control planes.",
  "labels": ["platform-team"]
}
EOF

Filter on approved to list only approved images.

Troubleshoot

Status	Cause
`404` on every request	Your platform team hasn't turned on the `Catalog` feature flag.
`404` from `openapi`	The image doesn't introduce that group, version, and kind.
`400` on a get	The image name isn't `sha256~<digest>`.
`400` from `openapi`	The request is missing `group`, `version`, or `kind`.
`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​

Search the catalog​

List images​

Get one image​

Read an API's schema​

See where an image runs​

Approve and annotate an image​

Troubleshoot​

Next steps​