Using a Private Docker Registry

Creating an archive for a private Docker registry

To supply credentials to pull from a private Docker registry, create an archive of your Docker credentials, then add it as a URI in your service or pod definition. In DC/OS Enterprise, you can also upload your private Docker registry credentials to the DC/OS Secret store and reference it in your service or pod definition.

Referencing private Docker registry credentials as a URI

Step 1: Compress Docker credentials

  1. Log in to the private registry manually. Login creates a .docker folder and a .docker/config.json file in your home directory.

    docker login some.docker.host.com
    Username: foo
    Password:
    Email: foo@bar.com
    
  2. Compress the .docker folder and its contents.

    cd ~
    tar -czf docker.tar.gz .docker
    
  3. 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
    
  4. Put the archive file in a location that is accessible to your application definition.

    cp docker.tar.gz /etc/
    

IMPORTANT: 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 Amazon S3. Consider the security implications of your chosen approach carefully.

Step 2: Add URI path to service definition

  1. Add the path to the archive file login credentials to your service definition.

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

    For example:

    {  
      "id": "/some/name/or/id",
      "cpus": 1,
      "mem": 1024,
      "instances": 1,
      "container": {
        "type": "DOCKER",
        "docker": {
          "image": "some.docker.host.com/namespace/repo"
        }
      },
      "fetch": [
        {
          "uri": "file:///etc/docker.tar.gz"
        }
      ]
    }
    

    The Docker image will now pull using the provided security credentials.

Referencing private Docker registry credentials in the secrets store Enterprise

Follow these steps to add your Docker registry credentials to the DC/OS Enterprise secrets store, and then reference that secret in your service definition.

IMPORTANT: This functionality is available only with the Universal Container Runtime). If you need to use the Docker Engine, follow the URI instructions above.

Step 1: Create a credentials file

  1. Manually log in to your private registry. This creates 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 base64-encoded username:password string.

    {
      "auths": {
          "https://index.docker.io/v1/": {
              "auth": "XXXXX",
              "email": "<your-email>"
          }
      }
    }
    

    If you are using Mac OS, you will need to manually encode your username:password string and modify your config.json to match the snippet above. Be sure to omit a trailing new-line when base64 encoding the pair:

    echo -n myuser@domain.com:hard-to-guess-password | base64
    
  3. Add the config.json file to the DC/OS secret store. Learn more about creating secrets.

    NOTE: As of DC/OS version 1.10.0, you can add a file to the secret store only using the DC/OS CLI.

    dcos security secrets create --file=config.json <path/to/secret>
    

    If you plan to follow the example below, enter the following command to add the secret:

    dcos security secrets create --file=config.json mesos-docker/pullConfig
    

Step 2: Add the secret to your service or pod definition

For a service

  1. Add a location for the secret in the secrets parameter and a reference to the secret in the docker.pullConfig parameter.

    IMPORTANT: This functionality is only supported with the Universal Container Runtime: container.type must be MESOS.

    {
       "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
    }
    
  2. Add the service to DC/OS. If you are using the example above, <svc-name> is mesos-docker.

    dcos marathon app add <svc-name>.json
    

    The Docker image will now pull using the provided security credentials.

For a pod

  1. Add a location for the secret in the secrets parameter and a reference to the secret in the containers.image.pullConfig parameter.

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

    {
         "id":"/simple-pod",
         "containers":[
            {
              "name":"simpletask1",
              "exec":{
                  "command":{
                    "shell":"env && sleep 1000"
                  }
                },
              "resources":{
                "cpus":0.1,
                "mem":32
            },
            "image":{
                "kind":"DOCKER",
                "id":"<your/private/image>",
                "pullConfig":{
                  "secret":"pullConfigSecret"
               }
            }
         }
      ],
      "networks":[
          {
            "mode":"host"
          }
      ],
      "secrets":{
          "pullConfigSecret":{
            "source":"/pod/pullConfig"
         }
      }
    }
    
  2. Add the pod to DC/OS. If you are using the example above, <pod-name> is simple-pod.

    dcos marathon pod add <pod-name>.json
    

    The Docker image will now pull using the provided security credentials.

Configuring agents to use a custom certificate for the Docker registry

Some organizations require both user credentials and valid secure socket layer (SSL) certificates to authorize access to the Docker registry. For example, some registry configurations require a certificate to encrypt the communications between the client and the registry, while user credentials determine who gets to access to the registry after the connection to the registry is successful.

If your private registry uses a certificate to secure communications, you can configure the agent nodes to trust the certificate you use to access the private Docker registry.

To configure a custom certificate for accessing the private Docker registry and DC/OS UCR, complete the following steps:

  1. Create or identify a custom certificate that you want to use as a trusted certificate for accessing the Docker registry.

    You can use OpenSSL, DC/OS Enterprise CLI, or another program for generating public and private keys, certificate requests, and encrypted client and server certificates.

    After you create or identify a certificate, you can configure the registry to use this certificate by following the instructions provided by the registry provider.

  2. Download or copy the certificate to the following two locations on each agent.

    /etc/docker/certs.d/<registry_name>:<registry_port>/ca.crt
    /var/lib/dcos/pki/tls/certs/<something>.crt
    

    For the path to the trusted CA certificate on each agent, replace the <registry_name> and <registry_port> with the specific registry name and port number appropriate for your installation.

    For example, if you are configuring the DC/OS ca.crt certificate as a trusted certificate and the local Docker registry is referenced as registry.mycompany.com:5000, you can download a copy of the ca.crt file and set it as trusted using a command similar to the following:

    sudo mkdir -p /etc/docker/certs.d/registry.mycompany.com:5000
    sudo cp /path/to/ca.crt etc/docker/certs.d/registry.mycompany.com:5000/ca.crt
    sudo cp /etc/docker/certs.d/registry.mycompany.com:5000/ca.crt /var/lib/dcos/pki/tls/certs/docker-registry-ca.crt
    
  3. Generate a hash for the file by running a command similar to the following:

    cd /var/lib/dcos/pki/tls/certs/
    openssl x509 -hash -noout -in docker-registry-ca.crt
    
    
  4. Create a symbolic link from the trusted certificate to the /var/lib/dcos/pki/tls/certs directory on the public agent.

    sudo ln -s /var/lib/dcos/pki/tls/certs/docker-registry-ca.crt /var/lib/dcos/pki/tls/certs/<hash_number>.0
    

Pushing a custom image to a private registry from a tarball

If you asked your sales representative for an enterprise version of Marathon, you may have been given a Docker image in a .tar archive. Follow these steps to deploy it to your registry:

Step 1: Import in the local machine

  1. Load the tarball into your local Docker client, passing the path to your custom tarball. For example, marathon-dcos-ee.<version>.tar:

    docker load -i marathon-dcos-ee.<version>.tar
    

    Tip: You can view the Marathon image with this command.

    docker images
    

    You should see output similar to this:

    REPOSITORY                    TAG                 IMAGE ID            CREATED             SIZE
    mesosphere/marathon-dcos-ee   1.4.0-RC4_1.9.4     d1ffa68a50c0        3 months ago        926.4 MB
    

Step 2: Push the image to the repository

  1. Re-tag the file to match the repository that you are using in your private Docker registry:

    docker tag \
     mesosphere/marathon-dcos-ee:<mesosphere-tag> \
     <your-repo>/marathon-dcos-ee:<your-tag>
    

    Where:

    • <mesosphere-tag> is the tag of the image from Mesosphere. Typically, this will match the version number in the filename.
    • <your-repo> is the name of the private repository that you want to store the image in.
    • <your-tag> is the tag for the image. It is recommended that you use the same tag as the Mesosphere image.
  2. Push the new image to your private Docker registry:

    docker push <your-repo>/marathon-dcos-ee:<your-tag>