diff --git a/docs/use-cases/deploy-prebuilt-image.mdx b/docs/use-cases/deploy-prebuilt-image.mdx index fe2bfc8..a208ac7 100644 --- a/docs/use-cases/deploy-prebuilt-image.mdx +++ b/docs/use-cases/deploy-prebuilt-image.mdx @@ -1,6 +1,6 @@ --- title: Deploy a Prebuilt Container Image -description: Deploy your existing container images to OpenChoreo without using the Build Plane. +description: Deploy your existing container images to OpenChoreo from public or private registries without using the Build Plane. sidebar_position: 5 --- @@ -13,7 +13,10 @@ This guide walks you through deploying a prebuilt container image to OpenChoreo. ## Overview -OpenChoreo supports deploying applications from prebuilt container images, commonly referred to as "Bring Your Own Image" (BYOI). +OpenChoreo supports deploying applications from prebuilt container images, commonly referred to as "Bring Your Own Image" (BYOI). You can deploy images from: + +- **Public registries** - No additional configuration needed +- **Private registries** - Requires setting up image pull credentials ## Prerequisites @@ -23,9 +26,9 @@ Before you begin, ensure you have: - **kubectl** configured to access your cluster - **A container image** to deploy -## Deploy an Image +## Deploy from a Public Registry -Deploying an image is straightforward - simply create the Component and Workload resources. +Deploying an image from a public registry is straightforward - simply create the Component and Workload resources. ### Example @@ -104,9 +107,111 @@ curl http://development.openchoreoapis.localhost:19080/my-app/ --- +## Deploy from a Private Registry + +In addition to creating the Component and Workload resources as shown above, pulling images from a private registry requires setting up authentication. You need to: + +1. Store your registry credentials in your secret store +2. Add an ExternalSecret resource to your ComponentType to sync the credentials +3. Add `imagePullSecrets` to the Deployment in your ComponentType + +### Store Registry Credentials + +:::note +This example uses the `default` ClusterSecretStore included with the default OpenChoreo installation. For production environments, see [Secret Management](../operations/secret-management.mdx) to configure a proper secret backend. +::: + +Here's an example using Docker Hub: + +**1. Generate the auth string** (base64-encoded `username:password`): + +```bash +echo -n "your-dockerhub-username:your-access-token" | base64 +``` + +**2. Create the Docker config JSON:** + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "" + } + } +} +``` + +**3. Store the credentials in the ClusterSecretStore:** + +```bash +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "registry-credentials", + "value": "{\"auths\":{\"https://index.docker.io/v1/\":{\"auth\":\"\"}}}" + } + } +]' +``` + +Replace `` with the value generated in step 1. + +### Update Your ComponentType + +Add an ExternalSecret resource to sync the registry credentials: + +```yaml +- id: registry-pull-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: registry-pull-secret + namespace: ${metadata.namespace} + spec: + refreshInterval: 15s + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: registry-pull-secret + creationPolicy: Owner + template: + type: kubernetes.io/dockerconfigjson + data: + - secretKey: .dockerconfigjson + remoteRef: + key: registry-credentials +``` + +Then add `imagePullSecrets` to your Deployment template: + +```yaml +- id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + spec: + template: + spec: + imagePullSecrets: + - name: registry-pull-secret + containers: + - name: main + image: ${workload.containers.main.image} + # ... rest of container config +``` + +--- + ## Summary -You've learned how to deploy prebuilt container images using the OpenChoreo BYOI (Bring Your Own Image) flow. +You've learned how to deploy prebuilt container images using the OpenChoreo BYOI (Bring Your Own Image) flow from both public and private registries. ## Next Steps