Skip to main content
Version: 1.2

Connect a registry

Connect Hub to a private registry, such as an Artifactory instance or an air-gapped mirror, so Catalog can pull and index the packages your control planes install from it. You can also have Hub scan a repository for new tags, so packages appear in the catalog before any control plane installs them.

note

Connecting registries is an alpha feature. Its API may change in incompatible ways between releases. See the feature lifecycle. It's off by default. Turn it on with the Registry feature flag.

Before you begin​

  • A hub kubectl context. See Configure kubectl for the Hub.
  • Permission to create connections in the realm, which the realm admin and realm editor roles grant. See the Roles reference.
  • Credentials for the registry that can pull its package images.
  • To scan repositories, your platform team also turns on the RegistryScan feature flag.

How Hub chooses credentials​

A connection tells Hub how to sign in to a registry: its host, an optional path scope, and credentials. Connections belong to a realm, and Hub only uses a realm's connections to pull images for control planes in that realm.

When Hub pulls an image, it picks the connection in the realm that matches the image most closely:

  1. A connection whose scope is exactly the image's repository.
  2. The connection with the longest scope that the repository starts with.
  3. A connection for the image's registry host.

A realm can have several connections for the same host, each scoped to a different path. Anonymous connections are never picked this way.

A repository tells Hub about one repository in a registry, so it can scan it for tags. A repository can name the connection to use, which skips the matching above.

Create a connection​

  1. Create the connection in the realm. Set authMethod to Static and give a username and password, or to Anonymous for a registry that needs no credentials:

    kubectl --context=hub create -f - <<'EOF'
    apiVersion: catalog.hub.upbound.io/v1alpha1
    kind: Connection
    metadata:
      name: platform-registry
      namespace: default
    spec:
      displayName: Platform registry
      host: registry.example.com
      scope: registry.example.com/platform
      authMethod: Static
      static:
        username: catalog-reader
        password: <token>
    EOF

    namespace is the realm. scope defaults to the host. Hub stores the credentials and returns them as *** when you read the connection.

  2. Check that Hub can reach the registry and sign in. Send a verification to the connection's verify subresource, with an image from the registry to test pulling:

    kubectl --context=hub create --raw \
      /apis/catalog.hub.upbound.io/v1alpha1/namespaces/default/connections/platform-registry/verify \
      -f - <<'EOF' | jq '.status'
    {"spec": {"testImage": "registry.example.com/platform/provider-example:v1.0.0"}}
    EOF
    {
      "reachable": true,
      "authenticated": true,
      "authorized": { "testImage": "registry.example.com/platform/provider-example:v1.0.0", "result": "ok" }
    }

    Hub saves the result on the connection, and the Console shows it on the connection's badge.

Scan a repository for new tags​

Create a repository with the connection to use and how often to scan:

kubectl --context=hub create -f - <<'EOF'
apiVersion: catalog.hub.upbound.io/v1alpha1
kind: Repository
metadata:
  name: provider-example
  namespace: default
spec:
  repository: registry.example.com/platform/provider-example
  connectionRef:
    name: platform-registry
  scan:
    interval: 1h
EOF

By default, a scan skips signature, attestation, and SBOM tags, and pre-release versions. Set scan.exclusionList to your own list of patterns to change that. You can't change connectionRef after you create the repository.

Hub also creates repositories for every repository it sees installed on a control plane, with scanning suspended. Set scan.suspend: false on one to start scanning it.

Troubleshoot​

SymptomCause
404 on connections or repositoriesYour platform team hasn't turned on the Registry feature flag.
422 when you create a Static connectionspec.static needs at least one of username, password, auth, identityToken, or registryToken. An Anonymous connection must not set spec.static.
409 when you create a connectionAnother connection for the same host in the realm sets insecure differently, or the name is taken.
400 from verifyThe test image isn't on the connection's registry host.
reachable is falseHub can't reach the registry host from its network.
authenticated is falseThe registry rejected the credentials.
authorized.result is forbiddenThe credentials sign in, but can't pull the test image. Grant them read access to the repository.
A repository never scansYour platform team hasn't turned on the RegistryScan feature flag, or the repository's scan.suspend is true.
Enrichment fails for an image from the registryNo connection in the control plane's realm matches the image. Check the connection's scope.

Next steps​