Exposing the Registry

Use the internal Service for workloads inside the cluster. Expose Alauda Container Platform Registry only when developer machines, CI systems, or other external clients need to push or pull images.

Prerequisites

  • The Image Registry Operator is installed, and Registry activation is complete.
  • Run commands from an administrator workstation with kubectl configured for the target ACP 4.5 cluster. For external checks, install openssl and authenticate ac to the same cluster.
  • You have permission to update Config/cluster and create or reference TLS Secrets in the Registry operand namespace.
  • The cluster has an Ingress controller that can route traffic to the Registry operand namespace.
  • Prepare a DNS record and a TLS certificate whose Subject Alternative Name matches the Registry hostname.

The Operator runs in image-registry-system. The Ingress, backend Service, and TLS Secret belong in the Registry operand namespace. Read that namespace from the Operator-created configuration:

REGISTRY_NAMESPACE="$(kubectl get configs.imageregistry.operator.alauda.io cluster \
  -o jsonpath='{.metadata.annotations.imageregistry\.operator\.alauda\.io/operand-namespace}')" || exit 1
test -n "$REGISTRY_NAMESPACE" || {
  echo "The Registry operand namespace binding is missing." >&2
  exit 1
}
printf 'Registry operand namespace: %s\n' "$REGISTRY_NAMESPACE"

The examples use REGISTRY_NAMESPACE, which resolves to cpaas-system by default. Replace registry.example.com with the hostname in your DNS record and certificate. Run namespace discovery first and keep REGISTRY_NAMESPACE in the same shell for the remaining commands.

Provide Registry Endpoints

Verify the internal Service address before giving it to developers:

kubectl -n "$REGISTRY_NAMESPACE" get service image-registry \
  -o jsonpath='{.metadata.name}.{.metadata.namespace}.svc:{.spec.ports[?(@.port==5000)].port}{"\n"}'

Expected result when REGISTRY_NAMESPACE=cpaas-system: image-registry.cpaas-system.svc:5000. For a custom binding, use image-registry.$REGISTRY_NAMESPACE.svc:5000. Clients need access to the cluster network and DNS, and must trust the Registry service CA.

The managed Registry Service exposes these ports:

PortProtocolUse
5000HTTPSDefault address for workload image references and Registry administration.
443HTTPSThe same Registry endpoint on the standard HTTPS port.
80HTTPInternal clients that require an HTTP endpoint. Restrict access to trusted internal networks because credentials can be sent without transport encryption.

Use HTTPS for normal operations. These are ClusterIP Service ports; they do not create an external listener or NodePort.

For external clients, configure and verify a secure host using the procedure below. Give developers the verified host, port, and CA trust requirements.

The Operator grants authenticated clients limited read access to the named Registry Service and Image API registration for discovery. This access does not grant Registry configuration, Secret, or image-content permissions.

Expose a Custom Secure Registry Host

Configure Config.spec.routes[] with a TLS Secret in the Registry operand namespace.

Create the Secret from a certificate whose Subject Alternative Name matches the custom hostname. Replace the certificate and private key paths with the files supplied by your certificate administrator:

kubectl -n "$REGISTRY_NAMESPACE" create secret tls registry-tls \
  --cert=/path/to/registry.example.com.crt \
  --key=/path/to/registry.example.com.key

The TLS Secret must exist in the Registry operand namespace when secretName is set. Create a DNS record for registry.example.com that resolves to the Ingress controller.

The generated Ingress routes traffic to the Registry Service over HTTPS.

Patch Config/cluster with the custom route. The merge patch preserves other Config/cluster.spec fields, including storage and pull-secret settings. It replaces the routes array, so include every custom route you need to retain:

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge \
  -p '{
    "spec": {
      "defaultRoute": false,
      "routes": [
        {
          "name": "public-registry",
          "hostname": "registry.example.com",
          "secretName": "registry-tls"
        }
      ]
    }
  }'
ValueDescription
public-registryRoute name. The Operator uses it as the generated Ingress name.
registry.example.comRegistry hostname reachable by external clients. The DNS record must resolve to the Ingress controller.
registry-tlsTLS Secret in the Registry operand namespace. The certificate Subject Alternative Name must match the Registry hostname.

If the cluster requires an explicit IngressClass, run kubectl get ingressclass and set ingressClassName to the selected object's name. If omitted, the generated Ingress has no explicit class.

Use proxyReadTimeout, proxySendTimeout, and proxyConnectTimeout to override the upstream timeouts. The defaults are 600 seconds for read and send, and 60 seconds for connect. Values must be positive, whole-second duration strings, such as "20m", no greater than 2147483647s. Set these fields in the same routes[] item. The read timeout measures intervals between upstream reads. Server HTTP deadlines apply separately.

Verify the configuration and generated Ingress:

kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl -n "$REGISTRY_NAMESPACE" get ingress public-registry
kubectl -n "$REGISTRY_NAMESPACE" describe ingress public-registry

Expected results:

  • Config/cluster.spec.routes[] contains public-registry.
  • The public-registry Ingress uses registry.example.com.
  • The Ingress references the registry-tls Secret.

Configure client trust as described in Configure Client Trust, then verify the certificate chain and hostname:

openssl s_client \
  -connect registry.example.com:443 \
  -servername registry.example.com \
  -verify_hostname registry.example.com \
  -verify_return_error </dev/null

Expected result: certificate verification succeeds for registry.example.com. For a private CA, add -CAfile /path/to/registry-ca.crt using the issuing CA bundle supplied by your certificate administrator.

Understand the Default Ingress

spec.defaultRoute: true creates an Ingress named default-route with a catch-all rule. The Operator does not supply a hostname, TLS Secret, or explicit IngressClass. The Ingress load balancer status identifies the controller endpoint; it does not establish a Registry DNS name or certificate.

For an existing default Ingress, inspect its configuration:

kubectl -n "$REGISTRY_NAMESPACE" get ingress default-route -o yaml

Use the custom secure host procedure above for external HTTPS access. It disables the default Ingress with defaultRoute: false; an empty rule host cannot be used as ac registry login --registry.

Configure Client Trust

If a private CA signs the Ingress certificate, add that CA to each external client's trust store before logging in, pushing, or pulling images.

For controlled testing, the following command skips the endpoint probe and writes credentials for the selected host:

REGISTRY_AUTH_DIR="$(mktemp -d "${TMPDIR:-/tmp}/registry-auth.XXXXXX")"
ac registry login \
  --registry registry.example.com \
  --to "$REGISTRY_AUTH_DIR/config.json" \
  --insecure

--insecure does not verify connectivity or configure an OCI client's trust. Configure that client's trust separately before pushing or pulling images.

Verify External Access

Check the Ingress:

kubectl -n "$REGISTRY_NAMESPACE" get ingress
kubectl -n "$REGISTRY_NAMESPACE" describe ingress public-registry

From an external client, authenticate with a dedicated Registry auth file, then publish and inspect a test image. Use an existing image namespace where your account has push and pull permission, and a source image you can read. Both registry endpoints must be reachable from that client.

Expected result: the copy completes, and the published tag and digest resolve to the same manifest or image index. A successful login alone does not establish image permissions.

Troubleshooting

SymptomCheck
Ingress is missingConfig.spec.defaultRoute, Config.spec.routes[], and Operator logs.
Ingress has no addressIngress controller status, ALB project label, and Ingress events.
TLS handshake failsTLS Secret, client trust store, certificate SANs, and private CA configuration.
ac registry info --check reports connection refused on port 443Check the selected host, DNS, controller HTTPS listener, and routing. Use a custom route with a TLS Secret; --insecure on login does not repair endpoint connectivity.
Login fails credentials, namespace RoleBinding, OIDC runtime discovery, and Registry logs.
Push or pull fails after loginImage namespace permissions, repository path, storage backend, and Registry readiness.