> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/resources/secret/container-registries.md).

# Container registries

Use this Secret when a Workflow, Service, Worker, or App needs to pull a container image from a private registry (for example, Docker Hub, AWS ECR, GCP Artifact Registry, or a self-hosted registry). The Secret stores the registry authentication in the same format as a Docker `config.json`, and is referenced by name from the consuming Resource's `imagePullSecret` field.

## Prerequisites

To create a Secret for securing container registry credentials, you need the following information from your registry.

### Source system requirements

* **Registry server**: the registry hostname (for example, `https://index.docker.io/v1/` for Docker Hub, or `<account>.dkr.ecr.<region>.amazonaws.com` for AWS ECR).
* **Username** and **Password** (or token): credentials DataOS uses to authenticate with the registry.
* **auth**: base64 encoding of `username:password`. Most registries read this field first, so leaving it empty can cause the pull to fail even if `username`/`password` are filled in.

Get these credentials from the registry provider's account settings, or from an administrator.

{% hint style="info" %}
For AWS ECR, the password is a short-lived token from `aws ecr get-login-password`. Since it expires (typically in 12 hours), the Secret needs to be refreshed and re-applied periodically, or image pulls will start failing again once the token expires.
{% endhint %}

## Create a Secret to secure container registry credentials

### Step 1: Create a manifest file

Create a manifest file with the configuration details for your container registry Secret.

{% tabs %}
{% tab title="Secret Manifest File" %}

```yaml
name: ${{secret-name}}
version: v2alpha
type: secret
tags:
  - ${{tag-1}}
  - ${{tag-2}}
description: ${{secret-description}}
owner: ${{owner-id}}
secret:
  type: image-pull
  data:
    .dockerconfigjson: |
      {
        "auths": {
          "${{registry-server}}": {
            "auth": "${{base64-of-username:password}}",
            "username": "${{username}}",
            "password": "${{password}}"
          }
        }
      }
```

{% endtab %}

{% tab title="Example" %}

```yaml
name: docker-secrets
version: v2alpha
type: secret
tags:
  - dataos:type:resource
  - dataos:resource:secret
description: Secret for pulling private images from Docker Hub
owner: iamgroottmdcio
secret:
  type: image-pull
  data:
    .dockerconfigjson: |
      {
        "auths": {
          "https://index.docker.io/v1/": {
            "auth": "**********",
            "username": "**********",
            "password": "**********"
          }
        }
      }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`secret.data` must contain exactly one key, `.dockerconfigjson`, holding the Docker `config.json` auth block as a YAML block scalar (`|`). DataOS base64-encodes this value automatically when the manifest is applied. Do not base64-encode it yourself in the manifest.
{% endhint %}

For more information about each attribute, refer to the [configurations section](/references/resources/secret/manifest-configuration.md).

### Step 2: Apply the manifest

Use the `apply` command to create the container registry Secret in DataOS.

```bash
dataos-ctl resource apply -f ${{manifest-file-path}}
```

**Example usage:**

```bash
dataos-ctl resource apply -f secret.yaml

#output
time="2026-07-22T14:59:05+05:30" level=info msg="🛠 apply... "
time="2026-07-22T14:59:06+05:30" level=info msg="🔧 applying docker-secrets:v2alpha:secret..."
time="2026-07-22T14:59:08+05:30" level=info msg="🔧 applying docker-secrets:v2alpha:secret...created"
time="2026-07-22T14:59:08+05:30" level=info msg="🛠 apply...complete"
```

### Step 3: Validate the Secret

Use the `get` command to verify the Secret in DataOS.

```bash
dataos-ctl resource get -t secret -n ${{secret-name}}
```

**Expected output:**

```bash
time="2026-07-22T14:59:12+05:30" level=info msg="🔍 resource get..."
time="2026-07-22T14:59:12+05:30" level=info msg="🔍 resource get...complete"

        NAME         | VERSION |  TYPE  | STATUS | RUNTIME |       OWNER
---------------------+---------+--------+--------+---------+-------------------
 docker-secrets      | v2alpha | secret | active |         | iamgroottmdcio
```

## Consume the Secret

Reference the Secret by name from `spec.service.imagePullSecret` in the Resource that needs to pull the private image (for example, an App):

```yaml
spec:
  service:
    image: ${{registry-server}}/${{image}}:${{tag}}
    imagePullSecret: docker-secrets
```

See [Deploy a data application](/references/interfaces/apps/deploy-a-data-application.md) for the full App manifest.

## Delete the Secret

{% hint style="warning" %}
Before deleting a Secret, remove any Resources that depend on it. Deletion fails while a dependent Resource (for example, a Workflow, Service, Worker, or App) still references it.
{% endhint %}

To delete the container registry Secret, use one of the following commands:

{% tabs %}
{% tab title="Command 1" %}

```bash
dataos-ctl resource delete -t secret -n ${{secret-name}}
```

{% endtab %}

{% tab title="Command 2" %}

```bash
dataos-ctl resource delete -i "${{secret-name}}|v2alpha|secret"
```

{% endtab %}

{% tab title="Command 3" %}

```bash
dataos-ctl resource delete -f ${{manifest-file-path}}
```

{% endtab %}
{% endtabs %}

**Example usage:**

```bash
dataos-ctl resource delete -t secret -n docker-secrets

#output
time="2026-07-22T14:59:16+05:30" level=info msg="🗑 delete..."
time="2026-07-22T14:59:17+05:30" level=info msg="🗑 deleting docker-secrets:v2alpha:secret..."
time="2026-07-22T14:59:18+05:30" level=info msg="🗑 deleting docker-secrets:v2alpha:secret...deleted"
time="2026-07-22T14:59:18+05:30" level=info msg="🗑 delete...complete"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/resources/secret/container-registries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.