Skip to main content

​
Overview

Follow the steps below to push an image to your org’s private image registry. When configuring a workload using the UI, the list of available images stored in your private image registry can be viewed by pressing CTRL+I on your keyboard. An image can be pushed by using either Docker, the CLI, or any Docker compatible client.

​
Prerequisites

​
Enable Docker Buildx (CLI 3.7.2+)

Beginning with cpln CLI v3.7.2, the cpln image build command shells out to docker buildx build. If the Docker CLI does not have the Buildx plugin installed or enabled, builds fail with errors such as unknown shorthand flag: 'f' in -f. This is common on minimal or self-hosted CI runners (Bitbucket, Jenkins, GitLab, GitHub, etc.) where Docker was installed without extras. Follow these steps before running cpln image build locally or in CI:
  1. Verify Buildx is available 
    docker buildx version
    The command should print a Buildx version. If it reports “unknown command”, install or enable the plugin.
  2. Install the standalone plugin (Linux runners without Docker Desktop) 
    # Minimal install + enable
BUILDX_VERSION=v0.29.1 # Check https://github.com/docker/buildx/releases for the latest
curl -sSL "https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64" | install -m 0755 -D /dev/stdin ~/.docker/cli-plugins/docker-buildx
docker buildx version
    Use the binary that matches your OS/architecture (for example, darwin-arm64 for Apple Silicon). Once Buildx is detected by docker buildx version, rerun cpln image build.

​
Push using Docker

​
Step 1 - Set up Docker authentication (Required)

Executing the command below will update the local Docker profile to use the CLI to authentication to your private registry when performing the push. 
cpln image docker-login --org ORG_NAME
The cpln profile named default will be used by Docker when authenticating to the private registry before the pushing the image. If a different profile is required for authentication, set the CPLN_PROFILE environment variable to the desired profile name.

​
Step 2 - Build a new image using Docker and a Dockerfile (Optional)

If you have an existing image, skip to step 3. Executing the command below will containerize your application using the defined Dockerfile. The image generated will be tagged in the format required to push it to your private registry. Always build with docker buildx build and target the linux/amd64 platform to ensure workloads run consistently across the Control Plane fleet. 
docker buildx build --platform=linux/amd64 -t ORG_NAME.registry.cpln.io/IMAGE[:TAG] .

​
Step 3 - Tag an existing image (Optional)

Executing the command below will tag an existing local image in the format required to push it to your private registry. Required Image Name Format: ORG_NAME.registry.cpln.io/IMAGE[:TAG] If your image is already tagged in this format, skip to step 4. 
docker tag SOURCE_IMAGE[:TAG] ORG_NAME.registry.cpln.io/IMAGE[:TAG]

​
Step 4 - Push image to your private registry

Executing the command below will authenticate and push the image to your private image registry. 
docker push ORG_NAME.registry.cpln.io/IMAGE[:TAG]
Depending on the size of the image and its dependencies, it might take a few minutes for the push to complete.

​
Step 5 - Use image in a workload

Once an image has been successfully pushed to your org’s private image registry, it can be referred to by a workload’s container. When setting up a workload, the list of available images stored in your private image registry can be viewed and selected by pressing CTRL+I on your keyboard.

​
Push using cpln

Another method to push an image to your private registry is by using the CLI’s image build command.

​
Option 1: Using buildpacks

Executing the command below will: Buildpacks will crawl the application code and try to generate the image. If it is unable to automatically generate the image, you will need to use option 2. 
cpln image build --name IMAGE:TAG --push --org ORG_NAME

​
Option 2: Using a Dockerfile

Executing the command below is similar to option 1, but will build the image using Docker and will follow the instructions in the Dockerfile. 
cpln image build --dockerfile PATH_TO_DOCKERFILE/Dockerfile --name IMAGE:TAG --push --org ORG_NAME
Starting in cpln CLI v3.7.2, this command internally runs docker buildx build. Ensure the Docker Buildx plugin is installed/enabled on the machine that runs the CLI.

​
Authentication using a Service Account

In situations where the CLI cannot be used, authentication to your private image registry is achieved by using a Service Account. Use the following parameters to authenticate using Docker or any Docker compatible client:
  • Registry Server Hostname: ORG_NAME.registry.cpln.io
  • Username: '<token>'
    The username is the literal string '<token>' (See example below).
  • Password: Service Account Key
    Refer to the Create a Service Account guide for instructions on how to generate a new key.
The Service Account Key is a sensitive value and should be stored securely/encrypted.If the key is compromised, it can be deleted and a new one generated.

​
Example using Docker

echo $SERVICE_ACCOUNT_KEY | docker login ORG_NAME.registry.cpln.io -u '<token>' --password-stdin
After successfully authenticating to your private image registry, the service account will be able push images based on a defined Policy. Refer to the Image Policy reference page for instructions on how to configure the minimum policy necessary to push images.

​
Next Steps

Once an image has been successfully pushed to your org’s private image registry, it can be referred to by a workload’s container. When setting up a workload, the list of available images stored in your private image registry can be viewed and selected by pressing CTRL+I on your keyboard.

​
Reference

Refer to the image build command for additional details.