Connect a cluster

Connect a cluster once and every namespace can pull your images without imagePullSecrets. Use the full image path, for example registry.kupe.cloud/acme/api:1.0.0. A connection covers the whole cluster.

Connect a cluster

Connecting a cluster needs a tenant admin.

kupe registry connect prod

The command waits until the connection is Ready. See kupe registry connect.

curl -X POST \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/registries/registry/bindings" \
  -d '{"cluster": "prod"}'

See Manage the registry with the API.

resource "kupe_registry_binding" "prod" {
  registry = kupe_registry.this.name
  cluster  = kupe_cluster.prod.name
}

See Manage the registry with Terraform.

Phase	Meaning
`Pending`	The connection is being set up, or something it needs is not ready, such as the cluster or the registry. The message says what it waits on.
`Ready`	Every pod in the cluster can pull, and every push namespace has its Secret.
`Failed`	A push namespace already has a Secret with the push Secret’s name that the platform did not create, or the registry’s connections list more than 20 push namespaces between them. Pulls still work.

Pods that were already running

Pods that were running when you connected the cluster get access the next time they are recreated. Restart a deployment with kubectl rollout restart deployment/<name> if it needs a new image straight away. Pods created after the connection is Ready can pull at once.

Push from inside a cluster

To build or copy images inside the cluster, name up to 10 push namespaces for the connection. The registry’s connections can list up to 20 push namespaces between them. Each push namespace gets a Secret, named kupe-registry-push unless you choose another name when you connect the cluster, that can pull from and push to every repository in your registry, including replacing existing tags. List only the namespaces that build images.

kupe registry connect build --push-namespace ci

The namespace must exist in the cluster before the Secret appears in it. The Secret has the type kubernetes.io/dockerconfigjson, the format of Docker’s config.json, so any tool that reads a Docker configuration can push with it: mount its .dockerconfigjson key as config.json.

Tenant clusters refuse containers that run as root, keep any capability or allow privilege escalation (see Cluster policies). A build tool in a push namespace has to run under those rules. crane, for example, runs as a non-root user and needs no capability. This Job copies a public base image into your registry with the push Secret:

apiVersion: batch/v1
kind: Job
metadata:
  name: copy-base-image
  namespace: ci
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: crane
          image: gcr.io/go-containerregistry/crane:v0.22.1
          args:
            - copy
            - docker.io/library/alpine:3.23
            - registry.kupe.cloud/acme/base/alpine:3.23
          env:
            - name: DOCKER_CONFIG
              value: /docker
            - name: HOME
              value: /tmp
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 128Mi
          volumeMounts:
            - name: docker
              mountPath: /docker
              readOnly: true
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: docker
          secret:
            secretName: kupe-registry-push
            items:
              - key: .dockerconfigjson
                path: config.json
        - name: tmp
          emptyDir: {}

To change the push namespaces later, use kupe registry connection update build --add-push-namespace release (or --remove-push-namespace, or --clear-push-namespaces), Edit on the connection in the console, push_namespaces in Terraform, or PATCH on the connection in the API. A namespace you add gets the Secret. A namespace you remove loses it, and the push credential is replaced, so build jobs in the namespaces that remain must restart to read the new Secret. Pulls are not affected.

The push Secret’s name cannot change. To use another name, disconnect the cluster and connect it again.

Rotate credentials

Rotating a connection issues new pull and push credentials and deletes the old ones. Pulls carry on. Build jobs that read the push Secret need a restart to pick up the new one, and anything that copied the Secret’s value elsewhere must read it again.

kupe registry connection rotate prod

In the console, select Rotate credentials on the connection. The API’s POST .../bindings/{cluster}/rotate does the same; see Manage the registry with the API.

Disconnect

Disconnecting a cluster deletes its pull credential and removes the push Secret from every push namespace. Pods already running keep running. New pods in the cluster can no longer pull the registry’s images.

kupe registry disconnect staging

In the console, select Disconnect on the connection and type the cluster’s name to confirm. Deleting a cluster also removes its connection.

Registry
Access tokens and CI: credentials for systems outside your clusters
Security model
Troubleshooting
kupe registry command reference

Connect a cluster