# Use the proxy registry with Replicated installers
This topic describes how to use the Replicated proxy registry for applications deployed with Replicated installers (Embedded Cluster, KOTS existing cluster, or kURL). For more information about the proxy registry, see [About the Replicated Proxy Registry](private-images-about).
## Configure your application to use the proxy registry
These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource.
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below.
### Embedded Cluster v3 (Beta) {#configure-v3}
Follow these steps to use the proxy registry with applications installed with [Embedded Cluster v3 (Beta)](/embedded-cluster/v3/embedded-overview).
Embedded Cluster v3 configures the cluster to automatically authenticate to the Replicated proxy registry for all pods.
For installations Embedded Cluster v3,
1.
1.
1.
1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).
1. Install in a development environment to test your changes. See [Online installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded).
### Embedded Cluster v2, KOTS, or kURL
To configure your application to use the proxy registry for installations with a Replicated installer:
1.
1.
1. For each Helm chart used by your application, in the Helm chart's `values.yaml` file, update the registry and repository for any private or third-party images to use the Replicated proxy registry URL.
The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/UPSTREAM_REGISTRY/IMAGE_PATH`
Where:
- `DOMAIN` is either `proxy.replicated.com` or your custom domain
- `APP_SLUG` is the unique slug of your application
- `UPSTREAM_REGISTRY/IMAGE_PATH` is the full upstream image path. For example, `ghcr.io/my-org/my-image` or `docker.io/bitnami/postgresql`.
The following examples demonstrate how to rewrite the registry depending on if you use separate values for the registry and repository or a single value for the full image name:
Example (Separate values for image registry and repository)
```yaml
# Current values.yaml
api:
image:
registry: ghcr.io
repository: cloudnative-pg/cloudnative-pg
```
```yaml
# New values.yaml
api:
image:
# proxy.replicated.com or your custom domain
registry: proxy.replicated.com
repository: proxy/your-app/ghcr.io/cloudnative-pg/cloudnative-pg
```
Example (Single value for full image name)
```yaml
# Current values.yaml
api:
image: ghcr.io/cloudnative-pg/cloudnative-pg
```
```yaml
# New values.yaml
api:
# proxy.replicated.com or your custom domain
image: proxy.replicated.com/proxy/your-app/ghcr.io/cloudnative-pg/cloudnative-pg
```
1.
1. Repeat steps 3 and 4 for each Helm chart used by your application.
1.
1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).
1. Install in a development environment to test your changes.
## Configure other application types {#other}
If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry.
### HelmChart v1 or standard manifests
:::note
The HelmChart custom resource `apiVersion: kots.io/v1beta1` is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with `apiVersion: kots.io/v1beta2` instead. See [HelmChart v2](/reference/custom-resource-helmchart-v2) and [Confguring the HelmChart Custom Resource v2](/vendor/helm-native-v2-using).
:::
To use the proxy registry with HelmChart v1 or applications packaged with standard manifests:
1.
1.
1.
1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).
1. Install in a development environment to test your changes.
For applications packed with Kubernetes manifests and for Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names.
How does KOTS patch image names?
KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry.
KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
spec:
template:
spec:
containers:
- name: api
image: quay.io/my-org/api:v1.0.1
```
When this application is deployed, KOTS detects that it cannot access
the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml`
file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
bases:
- ../../base
images:
- name: quay.io/my-org/api:v1.0.1
newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api
```
### Kubernetes operators
To use the proxy registry with applications packaged as Kubernetes Operators:
1.
1.
1.
1. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section.
1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).
1. Install in a development environment to test your changes.
## Migrate from the Replicated registry to the proxy registry {#migrate-replicated-registry}
Replicated has deprecated the ability to push images to the Replicated registry. Images that are already hosted on the Replicated registry will continue to be available for pull access.
If you already host any Docker images on the Replicated registry, Replicated recommends that you move your images to an external registry and use the Replicated proxy registry.
To migrate from the Replicated registry to the proxy registry:
1. Push your images to your own external registry. For the full list of supported image registries, see [Supported registries](/vendor/packaging-private-images#supported-registries) in _Add and manage external registries_.
1. In the Vendor Portal, go to **Image Registries > Add External Registry** and add the credentials for your registry. For more information, see [Add and manage external registries](/vendor/packaging-private-images).
1. Configure your application to pull images through the proxy registry. See the instructions for your target install type on this page:
* [Embedded Cluster v3 (Beta)](#configure-v3)
* [Embedded Cluster v2, KOTS, or kURL](#embedded-cluster-v2-kots-or-kurl)