> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull Images from Registries

> Configure workloads to pull container images from public and private registries.

Control Plane can pull container images from any Docker-compatible registry. Public images work out of the box, while private registries require [pull secrets](/concepts/gvc#pull-secrets).

## When to use this

<CardGroup cols={2}>
  <Card title="Private registries" icon="key">
    Pull from Docker Hub private repos, ECR, GCR, ACR, or GHCR
  </Card>

  <Card title="Cross-org images" icon="building">
    Use images from another Control Plane organization
  </Card>

  <Card title="Enterprise registries" icon="building-columns">
    Connect to self-hosted or enterprise container registries
  </Card>

  <Card title="Secure supply chain" icon="shield-check">
    Control access to private images with pull secrets
  </Card>
</CardGroup>

## Prerequisites

<AccordionGroup>
  <Accordion title="Required permissions">
    * `create` and `use` on [Secrets](/reference/secret)
    * `edit` on [GVC](/reference/gvc)
    * `edit` or `create` on [Workload](/reference/workload)
  </Accordion>

  <Accordion title="CLI installed (optional)">
    The CLI is optional but helpful. See [Installation](/cli-reference/installation).
  </Accordion>
</AccordionGroup>

## Pull from public registries

Public images don't require pull secrets. Use these formats:

| Registry                  | Format                                           |
| ------------------------- | ------------------------------------------------ |
| Docker Hub                | `IMAGE_NAME:TAG`                                 |
| Amazon ECR Public         | `public.ecr.aws/REGISTRY-ALIAS/IMAGE:TAG`        |
| Google Artifact Registry  | `LOCATION-docker.pkg.dev/PROJECT/REPO/IMAGE:TAG` |
| GitHub Container Registry | `ghcr.io/OWNER/IMAGE:TAG`                        |

## Pull from private registries

<Steps>
  <Step title="Create a pull secret">
    <Tabs>
      <Tab title="Console">
        1. Navigate to **Secrets** in the left menu
        2. Click **New** or use the **Create** dropdown
        3. Enter a name for the secret
        4. Select the secret type:
           * **Docker** for Docker Hub, ACR, GAR, GHCR, or another Control Plane org
           * **ECR** for Amazon ECR
           * **GCP** for Google Container Registry
        5. Enter the credentials
        6. Click **Create**
      </Tab>

      <Tab title="CLI">
        For Docker Hub or compatible registries:

        ```bash theme={null}
        cpln secret create-docker --name my-docker-secret \
          --file /path/to/auths.json
        ```

        For Amazon ECR:

        ```bash theme={null}
        cpln secret create-ecr --name my-ecr-secret \
          --access-key AKIAXXXXXXXX \
          --secret-key xxxxxxxxxxxxx \
          --repo AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/REPO_NAME \
          --role-arn arn:aws:iam::123456789:role/ecr-role
        ```

        For GCP:

        ```bash theme={null}
        cpln secret create-gcp --name my-gcp-secret \
          --file /path/to/service-account.json
        ```
      </Tab>
    </Tabs>

    <Info>
      Images from your own org's Control Plane registry don't need a pull secret.
    </Info>
  </Step>

  <Step title="Associate with a GVC">
    <Tabs>
      <Tab title="Console">
        1. Navigate to your GVC
        2. Click the **Pull Secrets** link
        3. Click **Add** and select your secret
        4. Click **Save**
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        cpln gvc update my-gvc --set spec.pullSecretLinks+=my-docker-secret
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure your workload">
    Reference the image in your workload using the appropriate format:

    | Registry                  | Image Format                                     |
    | ------------------------- | ------------------------------------------------ |
    | Control Plane (same org)  | `//image/IMAGE:TAG`                              |
    | Control Plane (cross-org) | `ORG.registry.cpln.io/IMAGE:TAG`                 |
    | Docker Hub                | `IMAGE:TAG`                                      |
    | Amazon ECR                | `ACCOUNT.dkr.ecr.REGION.amazonaws.com/IMAGE:TAG` |
    | Azure CR                  | `REGISTRY.azurecr.io/IMAGE:TAG`                  |
    | GCR                       | `gcr.io/PROJECT/IMAGE:TAG`                       |
    | GitHub CR                 | `ghcr.io/OWNER/IMAGE:TAG`                        |
  </Step>
</Steps>

## Pull from Control Plane registry

### Same organization

No pull secret needed:

```yaml theme={null}
containers:
  - name: my-container
    image: //image/my-app:v1
```

### Cross-organization

1. [Create a Docker secret](/reference/secret#control-plane) with the other org's credentials
2. Add it as a pull secret to your GVC
3. Reference the image:

```yaml theme={null}
containers:
  - name: my-container
    image: other-org.registry.cpln.io/my-app:v1
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    1. Verify the secret credentials are correct
    2. Check the secret is associated with the GVC
    3. Ensure the secret type matches your registry
  </Accordion>

  <Accordion title="Image not found">
    Verify the image name and tag are correct. Check the registry for the exact image path.
  </Accordion>

  <Accordion title="Cross-org pull fails">
    Ensure the source org has granted access and your Docker secret has the correct credentials. Learn more about [configuring a secret](/reference/secret#control-plane) for pulling images from other Control Plane orgs.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Push Images" href="/guides/push-image" icon="upload">
    Push images to Control Plane registry
  </Card>

  <Card title="Copy Images" href="/guides/copy-image" icon="copy">
    Copy images between organizations
  </Card>

  <Card title="Create a Workload" href="/guides/create-workload" icon="cube">
    Deploy containers with your images
  </Card>

  <Card title="Secrets Reference" href="/reference/secret" icon="book">
    Learn about secret types
  </Card>
</CardGroup>