Using a Private Docker Registry

As of Marathon 1.5, you can upload your private Docker registry credentials to a secret store, then reference them in your app or pod definition. This functionality is only available if you are using the Mesos containerizer. If you are using the Docker containerizer, follow these instructions to use a private Docker registry. If you want to learn how to configure credentials to pull images from the Amazon Elastic Container Registry (AWS ECR) please refer to this blog post.

Step 1: Create a Credentials File

  1. Log in to your private registry manually. This will create a ~/.docker directory and a ~/.docker/config.json file.

    $ docker login some.docker.host.com
    Username: foo
    Password:
    Email: foo@bar.com
    
  2. Check that you have the ~/.docker/config.json file.

    $ ls ~/.docker
    config.json
    

    Your config.json file should look like this, where value of auth is a based64-encoded username:password string.

    {
      "auths": {
          "https://index.docker.io/v1/": {
              "auth": "XXXXX",
              "email": "<your-email>"
          }
      }
    }
    
  3. Add the config.json file to a secret store. If you are using Enterprise DC/OS, follow these instructions to add the file to the DC/OS secret store.

Step 2: Add the Secret to your App or Pod Definition

For an Application

Add the following two parameters to your app definition.

  1. A location for the secret in the secrets parameter:

    "secrets": {
      "pullConfigSecret": {
        "source": "/mesos-docker/pullConfig"
      }
    }
    
  2. A reference to the secret in the docker.pullConfig parameter:

    "docker": {
      "image": "mesosphere/inky",
      "pullConfig": {
        "secret": "pullConfigSecret"
      }
    }
    

    Note: This functionality is only supported with the Mesos containerizer: container.type must be MESOS.

  3. A complete example:

    {
      "id": "/mesos-docker",
      "container": {
        "docker": {
          "image": "your/private/image",
          "pullConfig": {
            "secret": "pullConfigSecret"
          }
        },
        "type": "MESOS"
      },
      "secrets": {
        "pullConfigSecret": {
          "source": "/mesos-docker/pullConfig"
        }
      },
      "args": ["hello"],
      "cpus": 0.2,
      "mem": 16.0,
      "instances": 1
    }
    
  4. The Docker image will now pull using the provided security credentials given.

For a Pod

Add the following two parameters to your pod definition.

  1. A location for the secret in the secrets parameter:

    "secrets": {
      "pullConfigSecret": {
        "source": "/pod/pullConfig"
      }
    }
    
  2. A reference to the secret in the containers.image.pullConfig parameter:

    "containers": [
      {
        "image": {
          "id": "nginx",
          "pullConfig": {
            "secret": "pullConfigSecret"
          },
          "kind": "DOCKER"
        }
      }
    ]
    

    Note: This functionality is only supported if image.kind is set to DOCKER.

  3. A complete example:

    {
      "id": "/pod",
      "scaling": { "kind": "fixed", "instances": 1 },
      "containers": [
        {
          "name": "sleep1",
          "exec": { "command": { "shell": "sleep 1000" } },
          "resources": { "cpus": 0.1, "mem": 32 },
          "image": {
            "id": "nginx",
            "pullConfig": {
              "secret": "pullConfigSecret"
            },
            "kind": "DOCKER"
          },
          "endpoints": [ { "name": "web", "containerPort": 80, "protocol": [ "http" ] } ],
          "healthCheck": { "http": { "endpoint": "web", "path": "/ping" } }
        }
      ],
      "networks": [ { "mode": "container", "name": "my-virtual-network-name" } ],
      "secrets": { "pullConfigSecret": { "source": "/pod/pullConfig" } }
    }
    

Use a Private Docker Registry with the Docker Containerizer

Registry 1.0 - Docker pre 1.6

To supply credentials to pull from a private registry, add a .dockercfg to the uris field of your app. The $HOME environment variable will then be set to the same value as $MESOS_SANDBOX so Docker can automatically pick up the config file.

Registry 2.0 - Docker 1.6 and up

To supply credentials to pull from a private registry, add a docker.tar.gz file to the uris field of your app. The docker.tar.gz file should include the .docker directory and the contained .docker/config.json

Step 1: Compress Docker credentials

  1. Log in to the private registry manually. Login creates a ~/.docker directory and a ~/.docker/config.json file in your home directory.
Info: Executing docker login will append credentials to the file and won't replace the old ones. Credentialas will be stored unencrypted.
```bash
$ docker login some.docker.host.com
  Username: foo
  Password:
  Email: foo@bar.com
```
  1. Compress the ~/.docker directory and its contents.

    $ cd ~
    $ tar -czf docker.tar.gz .docker
    
  2. Verify that both files are in the archive.

    $ tar -tvf ~/docker.tar.gz
    
      drwx------ root/root         0 2015-07-28 02:54 .docker/
      -rw------- root/root       114 2015-07-28 01:31 .docker/config.json
    
  3. Put the archive file in a location that is accessible to your application definition.

    $ cp docker.tar.gz /etc/
    

    Note: The URI must be accessible by all nodes that will start your application. You can distribute the file to the local filesystem of all nodes, for example via RSYNC/SCP, or store it on a shared network drive like Google Cloud Storage or Amazon S3. Consider the security implications of your chosen approach carefully.

Careful: If you run these commands locally with already installed docker, the resulting tar archive might contain credentials to other registries.

Step 2: Add URI path to app definition

  1. Add the path to the archive file login credentials to the fetch parameter of your app definition.

    "fetch": [
      {
        "uri": "file:///etc/docker.tar.gz"
      }
    ]
    
  2. For example:

    {  
      "id": "/some/name/or/id",
      "cpus": 1,
      "mem": 1024,
      "instances": 1,
      "container": {
        "type": "DOCKER",
        "docker": {
          "image": "some.docker.host.com/namespace/repo",
          "network": "HOST"
        }
      },
      "fetch": [
        {
          "uri": "file:///etc/docker.tar.gz"
        }
      ]
    }
    
  3. The Docker image will now pull using the provided security credentials given.

More information

Find out how to set up a private Docker registry with DC/OS.