Restrict Access to the Docker API with Custom Certificates

To exercise fine control over the certificates that VCHs use, you must obtain or generate custom certificates yourself before you deploy a VCH. You can create a VCH that uses a custom server certificate, for example a server certificate that has been signed by Verisign or another public root. For information about how to create custom certificates for use with Docker, see Protect the Docker daemon socket in the Docker documentation.

When you have created or obtained custom certificates, you use the --tls-server-key, --tls-server-cert, and --tls-ca options to pass the custom server certificates to vic-machine create.

You can deploy a VCH to use custom server certificates in combination with auto-generated client certificates, as demonstrated in the example Combine Custom Server Certificates and Auto-Generated Client Certificates below.

IMPORTANT: PKCS#7 certificates do not work with vic-machine. For information about how to convert certificates to the correct format, see Converting Certificates for Use with vSphere Integrated Containers Engine.

vic-machine Options

The vic-machine create options in this section allow you to deploy a VCH that uses custom certificates.

Certain options in this section are exposed in the vic-machine create help if you run vic-machine create --extended-help, or vic-machine create -x.

--tls-server-cert

Short name: none

The path to a custom X.509 server certificate. This certificate identifies the VCH endpoint VM both to Docker clients and to browsers that connect to the VCH Admin portal.

  • This certificate should have the following certificate usages:
    • KeyEncipherment
    • DigitalSignature
    • KeyAgreement
    • ServerAuth
  • This option is mandatory if you use custom TLS certificates, rather than auto-generated certificates.
  • Use this option in combination with the --tls-server-key option, that provides the path to the private key file for the custom certificate.
  • Include the names of the certificate and key files in the paths.

If you use custom certificates, container developers run Docker commands with the --tlsverify, --tlscacert, --tlscert, and --tlskey options. For more information about how to connect Docker clients to VCHs, see Configure the Docker Client for Use with vSphere Integrated Containers.

Usage:

--tls-server-cert path_to_certificate_file/certificate_file_name.pem

--tls-server-key

Short name: none

The path to the private key file to use with a custom server certificate. This option is mandatory if you specify the --tls-server-cert option, that provides the path to a custom X.509 certificate file. Include the names of the certificate and key files in the paths.

IMPORTANT: The key must not be encrypted.

Usage:

--tls-server-key path_to_key_file/key_file_name.pem

--tls-ca

Short name: --ca

You can specify --tls-ca multiple times, to point vic-machine create to a file that contains the public portion of a CA. vic-machine create uses these CAs to validate client certificates that are offered as credentials for Docker API access. This does not need to be the same CA that you use to sign the server certificate.

Usage:

--tls-ca path_to_ca_file

Example vic-machine Commands

Use Custom Server Certificates

You use the --tls-server-cert and --tls-server-key options to provide the paths to a custom X.509 server certificate and its key when you deploy a VCH. The paths to the certificate and key files must be relative to the location from which you are running vic-machine create.

This example deploys a VCH with the following configuration:

  • Specifies the user name, password, image store, cluster, bridge network, and name for the VCH.
  • Provides the paths relative to the current location of the *.pem files for the custom server certificate and key files.
vic-machine-operating_system create
--target 'Administrator@vsphere.local':password@vcenter_server_address/dc1
--compute-resource cluster1
--image-store datastore1
--bridge-network vch1-bridge
--tls-server-cert ../some/relative/path/certificate_file.pem
--tls-server-key ../some/relative/path/key_file.pem
--name vch1
--thumbprint certificate_thumbprint

Combine Custom Server Certificates and Auto-Generated Client Certificates

You can create a VCH with a custom server certificate by specifying the paths to custom server-cert.pem and server-key.pem files in the --tls-server-cert and --tls-server-key options. The key should be un-encrypted. Specifying the --tls-server-cert and --tls-server-key options for the server certificate does not affect the automatic generation of client certificates. If you specify the --tls-cname option to match the common name value of the server certificate, vic-machine create generates self-signed certificates for Docker client authentication and deployment of the VCH succeeds.

This example deploys a VCH with the following configuration:

  • Specifies the user name, password, image store, cluster, bridge network, and name for the VCH.
  • Provides the paths relative to the current location of the *.pem files for the custom server certificate and key files.
  • Specifies the common name from the server certificate in the --tls-cname option. The --tls-cname option is used in this case to ensure that the auto-generated client certificate is valid for the resulting VCH, given the network configuration.
vic-machine-operating_system create
--target 'Administrator@vsphere.local':password@vcenter_server_address/dc1
--compute-resource cluster1
--image-store datastore1
--bridge-network vch1-bridge
--tls-server-cert ../some/relative/path/certificate_file.pem
--tls-server-key ../some/relative/path/key_file.pem
--tls-cname cname_from_server_cert
--name vch1
--thumbprint certificate_thumbprint

results matching ""

    No results matching ""