Configure the Docker Client for Use with vSphere Integrated Containers

If your container development environment uses vSphere Integrated Containers, you must run Docker commands with the appropriate options, and configure your Docker client accordingly.

vSphere Integrated Containers Engine 1.5 supports Docker client 1.13.0. The supported version of the Docker API is 1.25.

• Connecting to the VCH
• Using Docker Environment Variables
• Using docker-compose with TLS
• Install the vSphere Integrated Containers Registry Certificate
  • Obtain the vSphere Integrated Containers Registry CA Certificate
  • Configure the Docker Client on Linux
  • Configure the Docker Client on Windows
• Using vSphere Integrated Containers Registry with Content Trust

Connecting to the VCH

How you connect to your virtual container host (VCH) depends on the security options with which the vSphere administrator deployed the VCH.

• If the VCH implements any level of TLS authentication, you connect to the VCH at vch_address:2376 when you run Docker commands.
• If the VCH implements mutual authentication between the Docker client and the VCH by using both client and server certificates, you must provide a client certificate to the Docker client so that the VCH can verify the client's identity. This configuration is commonly referred to as tlsverify in documentation about containers and Docker. You must obtain a copy of the client certificate that was either used or generated when the vSphere administrator deployed the VCH. You can provide the client certificate to the Docker client in either of the following ways:
  • By using the --tlsverify, --tlscert, and --tlskey options when you run Docker commands. You must also add --tlscacert if the server certificate is signed by a custom Certificate Authority (CA). For example:

    docker -H vch_address:2376 
    --tlsverify 
    --tlscert=path_to_client_cert/cert.pem 
    --tlskey=path_to_client_key/key.pem 
    --tlscacert=path/ca.pem 
    info

  • By setting Docker environment variables:

    DOCKER_CERT_PATH=client_certificate_path
    DOCKER_TLS_VERIFY=1

    The client_certificate_path should contain the cert.pem and key.pem files, as well as the ca.pem file for the CA chain that signed the VCH server certificate. If server certificates are not signed by a trusted certificate authority, you might also require the server-cert.pem and server-key.pem server certificate files in client_certificate_path.
• If the VCH uses server certificates but does not authenticate the Docker client, no client certificate is required and any client can connect to the VCH. This configuration is commonly referred to as no-tlsverify in documentation about containers and Docker. In this configuration, the VCH has a server certificate and connections are encrypted, requiring you to run Docker commands with the --tls option. For example:

  docker -H vch_address:2376 --tls info

  In this case, do not set the DOCKER_TLS_VERIFY environment variable. Setting DOCKER_TLS_VERIFY to 0 or to false has no effect.
• If TLS is completely disabled on the VCH, you connect to the VCH at vch_address:2375. Any Docker client can connect to the VCH and communications are not encrypted. As a consequence, you do not need to specify any additional TLS options in Docker commands or set any environment variables. This configuration is not recommended in production environments. For example:

  docker -H vch_address:2375 info

Using Docker Environment Variables

If the vSphere administrator deploys the VCHs with TLS authentication, vic-machine create generates a file named vch_name.env. The env file contains Docker environment variables that are specific to the VCH. You can use the env file to set environment variables in your Docker client.

The contents of the env files are different depending on the level of authentication with which the VCH was deployed.

• Mutual TLS authentication with client and server certificates:

  DOCKER_TLS_VERIFY=1 
  DOCKER_CERT_PATH=client_certificate_path\vch_name 
  DOCKER_HOST=vch_address:2376
  COMPOSE_TLS_VERSION=TLSv1_2

• TLS authentication with server certificates without client authentication:

  DOCKER_HOST=vch_address:2376
  COMPOSE_TLS_VERSION=TLSv1_2

• No env file is generated if the VCH does not implement TLS authentication.

For information about how to obtain the env file, see Obtain a VCH. For information about the env files in Docker, see docker-machine env in the Docker documentation.

Using docker-compose with TLS

vSphere Integrated Containers supports TLS v1.2, so you must configure docker-compose to use TLS 1.2. However, docker-compose does not allow you to specify the TLS version on the command line. You must use environment variables to set the TLS version for docker-compose. For more information, see docker-compose issue 4651. Furthermore, docker-compose has a limitation that requires you to set TLS options either by using command line options or by using environment variables. You cannot use a mixture of both command line options and environment variables.

To use docker-compose with vSphere Integrated Containers and TLS, set the following environment variables:

COMPOSE_TLS_VERSION=TLSv1_2
DOCKER_TLS_VERIFY=1
DOCKER_CERT_PATH="path to your certificate files"

You can find the exact variables to set in the vch_name.env file that is generated during VCH deployment. The certificate file path must lead to CA.pem, key.pem, and cert.pem. You can run docker-compose with the following command:

docker-compose -H vch_address up

Install the vSphere Integrated Containers Registry Certificate

If your development environment uses vSphere Integrated Containers Registry or another private registry server that uses CA server certificates, you must pass the registry's CA certificate to the Docker client. The vSphere administrator must also have configured the VCH to access the registry.

For information about how vSphere administrators deploy VCHs so that they can access a private registry, see Connect Virtual Container Hosts to Registries.

The level of security of the connection between the Docker client and the VCH is independent from the level of security of the connection between the Docker client and the registry. Connections between the Docker client and the registry can be secure while connections between the Docker client and the VCH are insecure, and the reverse.

NOTE: VCHs cannot to connect to vSphere Integrated Containers Registry instances as insecure registries. Connections to vSphere Integrated Containers Registry always require HTTPS and a certificate.

Obtain the vSphere Integrated Containers Registry CA Certificate

To access the vSphere Integrated Containers Registry CA certificate, log in to vSphere Integrated Containers Management Portal with an account that has at least the Management Portal administrator role. For information about logging in to vSphere Integrated Containers Management Portal, see Logging In to the Management Portal.

1. Go to Administration -> Configuration.
2. Click the download link for Registry Root Certificate.

Configure the Docker Client on Linux

This example configures a Linux Docker client so that you can log into vSphere Integrated Containers Registry by using its IP address.

1. Copy the certificate file to the Linux machine on which you run the Docker client.
2. Switch to sudo user.

   $ sudo su

3. Create a subfolder in the Docker certificates folder, using the registry's IP address as the folder name.

   $ mkdir -p /etc/docker/certs.d/registry_ip

4. Copy the registry's CA certificate into the folder.

   $ cp ca.crt /etc/docker/certs.d/registry_ip/

5. Open a new terminal and attempt to log in to the registry server, specifying the IP address of the registry server.

   $ docker login registry_ip

6. If the login fails with a certificate error, restart the Docker daemon.

   $ sudo systemctl daemon-reload

   $ sudo systemctl restart docker

Configure the Docker Client on Windows

To pass the registry's CA certificate to a Docker client that is running on Windows 10, use the Windows Certificate Import Wizard.

1. Copy the ca.crt file to the Windows 10 machine on which you run the Docker client.
2. Right-click the ca.crt file and select Install Certificate.
3. Follow the prompts of the wizard to install the certificate.
4. Restart the Docker daemon:
   • Click the up arrow in the task bar to show running tasks.
   • Right-click the Docker icon and select Settings.
   • Select Reset and click Restart Docker.
5. Log in to the registry server.

   docker login registry_ip

Using vSphere Integrated Containers Registry with Content Trust

vSphere Integrated Containers Registry provides a Docker Notary server that allows you to implement content trust by signing and verifying the images in the registry. Management Portal administrators enable or disable content trust at the project level in vSphere Integrated Containers Management Portal.

If you the project that you are working on implements content trust, you must pass the registry's CA certificate to your Docker client and set up Docker Content Trust. By default, the vSphere Integrated Containers Registry Notary server runs on port 4443 on the vSphere Integrated Containers appliance.

Enabling content trust on a project automatically modifies the registry whitelist settings of any VCHs that are registered with the project. Consequently, when content trust is enabled, the VCHs in the project can only pull signed and verified images from the registry instance that is running in the vSphere Integrated Containers appliance.

• For general information about Docker Notary and content trust, see Content trust in Docker in the Docker documentation.
• For information about content trust in vSphere Integrated Containers, see Enabling Content Trust in Projects in vSphere Integrated Containers Management Portal Administration.
• For information about how enabling content trust affects VCHs, see VCH Whitelists and Content Trust in vSphere Integrated Containers for vSphere Administrators.

Procedure

1. If you are using a self-signed certificate, copy the CA root certificate to the Docker certificates folder.

   To pass the certificate to the Docker client, follow the procedure in Using vSphere Integrated Containers Registry above.

2. If you are using a self-signed certificate, copy the CA certificate to the Docker TLS service.

   $ cp ca.crt ~/.docker/tls/registry_ip:4443/

3. Enable Docker Content Trust by setting environment variables.

   export DOCKER_CONTENT_TRUST=1
   export DOCKER_CONTENT_TRUST_SERVER=https://registry_ip:4443
   

4. (Optional) Set an alias for Notary.

   By default, the local directory for storing meta files for the Notary client is different from the folder for the Docker client. Set an alias to make it easier to use the Notary client to manipulate the keys and meta files that Docker Content Trust generates.

   alias notary="notary -s https//registry_ip:4443 -d ~/.docker/trust --tlscacert  /etc/docker/certs.d/registry_ip/ca.crt"

5. When you push an image for the first time, define and confirm passphrases for the root key and the repository key for that image.

   The root key is generated at:

   /root/.docker/trust/private/root_keys

   The repository key is generated at:

   /root/.docker/trust/private/tuf_keys/[registry_name]/[image_path]

You can see that the signed image that you pushed is marked with a green check on the Project Repositories page in the Management Portal.