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
- Install the vSphere Integrated Containers Registry Certificate
- Using vSphere Integrated Containers Registry with Content Trust
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
tlsverifyin 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
--tlskeyoptions when you run Docker commands. You must also add
--tlscacertif 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=1The client_certificate_path should contain the
key.pemfiles, as well as the
ca.pemfile 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-key.pemserver certificate files in client_certificate_path.
- By using the
- 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-tlsverifyin 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
--tlsoption. For example:
docker -H vch_address:2376 --tls infoIn this case, do not set the
DOCKER_TLS_VERIFYenvironment variable. Setting
DOCKER_TLS_VERIFYto 0 or to
falsehas 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
If the vSphere administrator deploys the VCHs with TLS authentication,
vic-machine create generates a file named
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:
envfile is generated if the VCH does not implement TLS authentication.
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.
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
cert.pem. You can run
docker-compose with the following command:
docker-compose -H vch_address up
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.
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.
- Go to Administration -> Configuration.
- Click the download link for Registry Root Certificate.
This example configures a Linux Docker client so that you can log into vSphere Integrated Containers Registry by using its IP address.
- Copy the certificate file to the Linux machine on which you run the Docker client.
- Switch to
$ sudo su
- 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
- Copy the registry's CA certificate into the folder.
$ cp ca.crt /etc/docker/certs.d/registry_ip/
- 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
- If the login fails with a certificate error, restart the Docker daemon.
$ sudo systemctl daemon-reload
$ sudo systemctl restart docker
To pass the registry's CA certificate to a Docker client that is running on Windows 10, use the Windows Certificate Import Wizard.
- Copy the
ca.crtfile to the Windows 10 machine on which you run the Docker client.
- Right-click the
ca.crtfile and select Install Certificate.
- Follow the prompts of the wizard to install the certificate.
- 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.
- Log in to the registry server.
docker login registry_ip
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.
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.
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/
- Enable Docker Content Trust by setting environment variables.
export DOCKER_CONTENT_TRUST=1 export DOCKER_CONTENT_TRUST_SERVER=https://registry_ip:4443
(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"
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_keysThe repository key is generated at:
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.