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.
TOC
PrerequisitesProvide Registry EndpointsExpose a Custom Secure Registry HostUnderstand the Default IngressConfigure Client TrustVerify External AccessTroubleshootingPrerequisites
- The Image Registry Operator is installed, and Registry activation is complete.
- Run commands from an administrator workstation with
kubectlconfigured for the target ACP 4.5 cluster. For external checks, installopenssland authenticateacto the same cluster. - You have permission to update
Config/clusterand 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:
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:
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:
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:
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:
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:
Expected results:
Config/cluster.spec.routes[]containspublic-registry.- The
public-registryIngress usesregistry.example.com. - The Ingress references the
registry-tlsSecret.
Configure client trust as described in Configure Client Trust, then verify the certificate chain and hostname:
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:
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:
--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:
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.