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.

Connecting to the VCH
Using Docker Environment Variables
Using vSphere Integrated Containers Registry
Using vSphere Integrated Containers Registry with Notary

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/cert.pem
DOCKER_TLS_VERIFY=1
```
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

TLS authentication with server certificates without client authentication:
```
DOCKER_HOST=vch_address:2376
```
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.

Using vSphere Integrated Containers Registry

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 to obtain the CA certificate from vSphere Integrated Containers Registry and how to deploy a VCH so that it can access a private registry, see Deploy a VCH for Use with vSphere Integrated Containers Registry.

NOTE: 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.

Docker on Linux

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

NOTE: The current version of vSphere Integrated Containers uses the registry's IP address as the Subject Alternate Name when auto-generating certificates for vSphere Integrated Containers Registry. Consequently, when you run docker login, you must use the IP address of the registry rather than the FQDN.

Copy the certificate file to the Linux machine on which you run the Docker client.
Switch to sudo user.
```
$ 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
```

Docker 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.

Copy the ca.crt file to the Windows 10 machine on which you run the Docker client.
Right-click the ca.crt file 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
```

Using vSphere Integrated Containers Registry with Notary

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. For information about Docker Notary, see Content trust in Docker in the Docker documentation.

To use the Docker Notary server from vSphere Integrated Containers Registry, 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.

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"
```

Configure the Docker Client