Install with a customer-managed registry (Beta)

This topic describes how to install with Replicated Embedded Cluster using a customer-managed OCI registry (also known as a bring-your-own, or BYO, registry) instead of the Replicated proxy registry or the internal air gap registry.

Overview

By default, Embedded Cluster pulls application images from the Replicated proxy registry for online installations, and from an internal Docker registry that Embedded Cluster deploys to the cluster for air gap installations.

When BYO registry is enabled, Embedded Cluster pulls all images from a single OCI registry that the customer controls. This includes:

• Vendor application images
• Embedded Cluster infrastructure images (k0s, OpenEBS, and any images for Helm extensions declared in the Embedded Cluster Config)

BYO registry is supported for both online and air gap installations. In air gap installations with BYO registry, Embedded Cluster does not deploy its internal image registry or SeaweedFS to the cluster, because all images are served from the customer's registry.

When to use a customer-managed registry

A customer-managed registry is useful for customers with strict network or compliance policies that require all container images to come from a registry they control. Use cases include:

• Customers that block outbound traffic to proxy.replicated.com and cannot run the internal air gap registry that Embedded Cluster deploys.
• Customers that scan and sign images in their own registry before they reach the cluster.
• Customers that already mirror third-party images to a central registry and want application images to follow the same path.

Limitations

• The BYO registry must use a single flat namespace rooted at the registry address that you provide. See Registry layout requirements below.
• The noProxy hint that chart authors can pass to the ReplicatedImageName and ReplicatedImageRegistry template functions is ignored in BYO mode. This hint normally tells the function to leave a public image pointing at its upstream registry instead of routing it through the Replicated proxy registry. In BYO mode every image must come from the customer's registry, so the image is rewritten regardless of the hint. This is separate from HTTP proxy configuration: if the BYO registry is reachable only through an HTTP or HTTPS proxy, use the standard --http-proxy, --https-proxy, and --no-proxy install flags.

Prerequisites

Before a customer can install with BYO registry, the following must be in place:

• An OCI-compliant registry that is reachable from every Embedded Cluster host. Authentication can be anonymous, username and password, or mTLS (--registry-tls-cert and --registry-tls-key). If the registry's TLS certificate is signed by a private CA, pass it with --registry-ca-cert; otherwise the host's system root CAs are used.

• All images required for the release are pushed to the registry using the layout described in Registry layout requirements below.

• Application Helm charts use the ReplicatedImageName and ReplicatedImageRegistry template functions to render image references, so that images are rewritten to the BYO registry at install time. See Author charts for a BYO registry below.

Get the list of images to mirror

Customers get the complete list of images for the release, including Embedded Cluster infrastructure images, from the Replicated Enterprise Portal. The image list separates online-install images from the additional images needed for air gap installs (which include images that are normally preloaded onto each node by the air gap bundle). Each entry includes the full image reference (tag or digest) that must be pushed to the BYO registry.

Registry layout requirements

Embedded Cluster rewrites every image reference so that it is served from the address you pass with --registry. The address is treated as a literal prefix. It must be in the form host[:port][/namespace] and must not include a scheme or a trailing slash.

When an image is rewritten, the upstream registry host is dropped and the BYO registry address is substituted in its place. The repository path under the upstream host is preserved exactly as written. Any Replicated proxy prefix on the input (for example, proxy.replicated.com/proxy/<app-slug>/) is also stripped first.

For example, with --registry registry.example.com/acme:

Original image	Rewritten image
nginx:latest	registry.example.com/acme/nginx:latest
ghcr.io/myorg/myimage:v1	registry.example.com/acme/myorg/myimage:v1
proxy.replicated.com/proxy/my-app/docker.io/library/nginx:latest	registry.example.com/acme/library/nginx:latest
ghcr.io/myorg/myimage@sha256:abc…	registry.example.com/acme/myorg/myimage@sha256:abc…

Push each image to the rewritten path so that the reference resolves at install time. The image list in the Enterprise Portal already uses this layout.

If --registry is set to a bare host (for example, registry.example.com), the rewritten paths have no namespace prefix: registry.example.com/myorg/myimage:v1.

Install with a BYO registry

The procedures below apply to Embedded Cluster v3 (Beta). The Embedded Cluster CLI exposes the following install flags for BYO registry:

Flag	Description
--registry	OCI registry address in the form host[:port][/namespace]. When set, Embedded Cluster pulls all application and infrastructure images from this registry.
--registry-username	Username for the BYO registry. Optional for anonymous registries.
--registry-password	Password for the BYO registry. Optional for anonymous registries.
--registry-ca-cert	Path to a PEM-encoded CA certificate file used to verify the registry's TLS certificate. Required only when the registry uses a private CA that is not in the host's system trust store.
--registry-tls-cert	Path to a PEM-encoded client certificate that Embedded Cluster presents to the registry for mTLS authentication.
--registry-tls-key	Path to a PEM-encoded private key that pairs with --registry-tls-cert.

These flags can be combined with --airgap, --headless, and the other install flags.

Online install

To install with a BYO registry in an online environment:

1. Push all images for the release to your registry. See Get the list of images to mirror above.

2. On a Linux host, download and extract the Embedded Cluster installation assets using the commands from the Enterprise Portal. For more detail, see Online installation with Embedded Cluster.

3. Run the install command with the BYO registry flags. For example:

   sudo ./APP_SLUG install \
     --license license.yaml \
     --registry registry.example.com/acme \
     --registry-username USERNAME \
     --registry-password PASSWORD

   For a registry that uses a private CA:

   sudo ./APP_SLUG install \
     --license license.yaml \
     --registry registry.example.com/acme \
     --registry-ca-cert /path/to/ca.pem

4. Complete the install in the UI, or pass --headless and --config-values for a non-interactive install.

Air gap install

To install with a BYO registry in an air-gapped environment:

1. Push all images for the release, including the air gap infrastructure images, to your registry. See Get the list of images to mirror above and use the air gap image list.

2. On a host with internet access, download the Embedded Cluster air gap assets and copy them to the air-gapped host. The air gap bundle files (ec-<version>.airgap and <app-slug>.airgap) are still required when using BYO registry, because they contain the Embedded Cluster binaries, addon Helm charts, application charts, and manifests. The bundles also remove the need to host the internal image registry in the cluster: the application and addons pull their images from the BYO registry instead. For more detail, see Air gap installation with Embedded Cluster.

3. On the air-gapped host, run install with both --airgap and the BYO registry flags. The --airgap flag expects ec-<version>.airgap and <app-slug>.airgap to be in the current working directory. For example:

   sudo ./APP_SLUG install \
     --license license.yaml \
     --airgap \
     --registry registry.example.com/acme \
     --registry-username USERNAME \
     --registry-password PASSWORD

In air gap installs with BYO registry, Embedded Cluster does not deploy its internal image registry or SeaweedFS. The cluster pulls all images directly from the customer registry.

Add nodes to a BYO registry cluster

Nodes that join a cluster installed with BYO registry automatically inherit the registry address, credentials, and CA certificate from the cluster. Customers do not pass the --registry* flags when running join.

Join-time host preflights skip the BYO registry image checks, because the initial install already validated that the images are reachable from the registry.

Author charts for a BYO registry

To work with BYO registry, application Helm charts must produce image references through Replicated template functions rather than hardcoding registry hosts. Embedded Cluster rewrites the output of these functions at install time based on the install mode (proxy, airgap, or byo).

ReplicatedImageName

ReplicatedImageName returns a fully-qualified image reference. In BYO mode, it drops the upstream registry host from the input image, preserves the repository path, and prepends the value of --registry.

image: '{{ ReplicatedImageName "ghcr.io/myorg/myimage:v1" }}'
# BYO with --registry registry.example.com/acme renders to:
#   registry.example.com/acme/myorg/myimage:v1

Use ReplicatedImageName when you want Embedded Cluster to fully control the image path. This is the default and recommended pattern.

ReplicatedImageRegistry

ReplicatedImageRegistry returns the bare registry address with no rewriting of the input. In BYO mode, it returns the literal value of --registry. Use it when you need to compose your own path under the BYO registry, for example with split registry, repository, and tag fields:

image:
  registry: '{{ ReplicatedImageRegistry "ghcr.io" }}'
  repository: subchart/myimage
  tag: v1
# BYO renders to:
#   registry.example.com/acme/subchart/myimage:v1

Image pull secrets

In BYO mode, Embedded Cluster configures containerd on every node with the credentials passed to --registry-username/--registry-password (or the mTLS material from --registry-tls-cert/--registry-tls-key). Containerd authenticates pulls from the BYO registry on the cluster's behalf, so pods do not need an imagePullSecrets entry that targets the BYO registry.

Patterns that do not work

• Hardcoding proxy.replicated.com/... strings in non-templated chart values. Only template-function output is rewritten. Raw strings pass through unchanged and fail to pull in BYO mode.

Preflight checks

When --registry is set, Embedded Cluster runs an additional host preflight that pulls each image in the release manifest from the BYO registry. This validates connectivity, authentication, and that all required images have been mirrored to the registry before the install proceeds.

The image references checked by the preflight are the same references that the charts will resolve at runtime, so a successful preflight confirms that the registry layout matches the chart-authoring contract.