Deploy a Virtual Container Host with a Volume Store and vSphere Integrated Containers Registry Access
It is possible deploy a very basic virtual container host (VCH) with a minimal configuration for testing purposes. For example, configuring access to an image registry or designating a volume store is not mandatory when you deploy a VCH. For an example of the most minimal possible deployment, without registry access or a volume store, see Deploy a VCH to an ESXi Host with No vCenter Server.
However, in real-world deployments, you usually need to access private registries, and commonly used container images very often need to create volumes. Consequently, to create a useful test VCH, you should configure it for private registry access and add at least one volume store. In environments in which DHCP is not available, you must also configure a static IP address for the VCH endpoint VM on at least the public network.
This example shows how to use both the Create Virtual Container Host wizard and
vic-machine to create a VCH with the following configuration:
- A static IP address for the VCH endpoint VM on the public network.
- A volume store named
default, in which containers can create anonymous volumes.
- Access to a vSphere Integrated Containers Registry instance, from which to pull images.
For simplicity, this example deploys a VCH without client certificate verification, so that container application developers do not need to use a TLS certificate to connect a Docker client to the VCH. However, the connection between the VCH and the registry still requires certificate authentication, so you must download the root certificate for vSphere Integrated Containers Registry and upload it to the VCH.
NOTE: If this is the first time that you are deploying a VCH, it is recommended to use the Create Virtual Container Host wizard rather than
- Deploy the vSphere Integrated Containers appliance. For information about deploying the appliance, see Deploy the vSphere Integrated Containers Appliance.
- Download the vSphere Integrated Containers Engine bundle from the appliance and unpack it on your usual working machine. For information about how to download the bundle, see Download the vSphere Integrated Containers Engine Bundle.
- If you did not do so when deploying the appliance, install the vSphere Client plug-in. For information, see Reinitialize the vSphere Integrated Containers Appliance. By default, the plug-in is installed automatically.
- Create or obtain a vCenter Server instance with the following configuration:
- At least one datacenter
- At least one cluster with at least two ESXi hosts. You can use nested ESXi hosts for this example. VMware recommends that you enable VMware vSphere Distributed Resource Scheduler (DRS) on clusters whenever possible.
- At least one shared datastore, that is accessible by both of the ESXi hosts.
- One VMware vSphere Distributed Switch with two port groups named
Verify that your vCenter Server instance and all of the ESXi hosts in the cluster meet the requirements in Environment Prerequisites for VCH Deployment.
IMPORTANT: Pay particular attention to the Networking Requirements for VCH Deployment.
- Make sure that the correct firewall ports are open on the ESXi hosts. For information about how to open ports on ESXi hosts, see Open the Required Ports on ESXi Hosts.
- Obtain the vCenter Server certificate thumbprint. For information about how to obtain the certificate thumbprint, see Obtain vSphere Certificate Thumbprints.
- If you intend to use the CLI utility to deploy the VCH, familiarize yourself with the basic options of the
vic-machine createcommand described in Using the
- Familiarize yourself with the bridge network, public network, image store, and volume store as described in Configure Bridge Networks, Configure the Public Network, and Virtual Container Host Storage Capacity.
- Familiarize yourself with the way in which VCHs use certificates to authenticate connections from clients. For information about certificate use by VCHs and Docker, see the Virtual Container Host Certificate Requirements.
- Obtain the root certificate for vSphere Integrated Containers Registry. For information about how to obtain the certificate, see Obtain the vSphere Integrated Containers Registry Certificate.
- If you intend to use the Create Virtual Container Host wizard in the vSphere Client, create a vSphere user account for the operations user. For information about creating the operations user account, see Create the Operations User Account.
- Install a Docker client so that you can test the deployment.
Create VCH Wizard
- Log in to the HTML5 vSphere Client, click the vSphere Client logo in the top left corner, and click vSphere Integrated Containers.
- Click vSphere Integrated Containers in the main panel, select the Virtual Container Hosts tab, and click + New Virtual Container Host.
- On the General Settings page, enter a name for the VCH, for example,
test_vch, and click Next.
- On the Compute Capacity page, expand the Compute resource inventory hierarchy, select the cluster on to which to deploy the VCH, and click Next.
- On the Storage Capacity page, select a datastore to use as the Image Datastore.
- Remain on the Storage Capacity page and configure the volume datastore.
- Set the Enable anonymous volumes switch to the green ON position.
- Select a datastore to use as a volume datastore. This does not have to be the same datastore as you used for the image store.
- Optionally provide the path to a folder in that datastore.
- Click Next.
- On the Configure Networks page, select the existing
vic-publicport groups for use as the bridge and public networks.
- Remain on the Configure Networks page and configure a static IP address for the VCH endpoint VM on the public network.
- Select the Static radio button.
- Enter an IP address with a network mask in the IP Address text box, for example
- Enter the IP address of the gateway in the Gateway text box, for example
- Enter a comma-separated list of DNS server addresses in the DNS server text box, for example
- Click Next.
- On the Security page, for simplicity, set the Client Certificates switch to the gray OFF position to disable client certificate verification, leave the default options for automatic server certificate generation, and click Next.
- On the Registry Access page, under Additional registry certificates, click Select to upload the certificate for vSphere Integrated Containers Registry, then click Next.
- On the Operations User page, enter the user name and password for an existing vSphere account, select the Grant this user any necessary permissions check box, and click Next.
- On the Summary page, scroll down to view the generated
vic-machine createcommand, and optionally copy it for future use.
- Click Finish.
At the end of a successful deployment, the Virtual Container Hosts tab displays connection information for the new VCH.
- Open a terminal on the system on which you downloaded and unpacked the vSphere Integrated Containers Engine binary bundle.
- Navigate to the directory that contains the
vic-machine createcommand that corresponds to your working system.
In these examples, the user name is wrapped in quotes because it contains
@. The password is also wrapped in quotes because passwords usually contain special characters. Note that you use single quotes on Linux and Mac OS, and double quotes on Windows.
vic-machine-linux create \ --target vcenter_server_address/dc1 \ --user 'Administrator@vsphere.local' \ --password 'p@ssword123!' \ --compute-resource cluster1 \ --image-store datastore1 \ --bridge-network vch-bridge \ --public-network vic-public \ --public-network-ip 192.168.1.10/24 \ --public-network-gateway 192.168.0.1 \ --dns-server 192.168.10.10 \ --dns-server 192.168.10.11 \ --name test_vch \ --thumbprint vcenter_server_certificate_thumbprint \ --no-tlsverify \ --registry-ca cert_path/ca.crt \ --volume-store datastore2:default
vic-machine-windows create ^ --target vcenter_server_address/dc1 ^ --user "Administrator@vsphere.local" ^ --password "p@ssword123!" ^ --compute-resource cluster1 ^ --image-store datastore1 ^ --bridge-network vch-bridge ^ --public-network vic-public ^ --public-network-ip 192.168.1.10/24 ^ --public-network-gateway 192.168.0.1 ^ --dns-server 192.168.10.10 ^ --dns-server 192.168.10.11 ^ --name test_vch ^ --thumbprint vcenter_server_certificate_thumbprint ^ --no-tlsverify ^ --registry-ca cert_path/ca.crt ^ --volume-store datastore2:default
- Mac OS:
vic-machine-darwin create \ --target vcenter_server_address/dc1 \ --user 'Administrator@vsphere.local' \ --password 'p@ssword123!' \ --compute-resource cluster1 --image-store datastore1 --bridge-network vch-bridge --public-network vic-public --public-network-ip 192.168.1.10/24 \ --public-network-gateway 192.168.0.1 \ --dns-server 192.168.10.10 \ --dns-server 192.168.10.11 \ --name test_vch \ --thumbprint vcenter_server_certificate_thumbprint \ --no-tlsverify \ --registry-ca cert_path/ca.crt \ --volume-store datastore2:default
vic-machine create command in this example specifies the following options:
- The address of the vCenter Server instance on which to deploy the VCH and datacenter
- The vCenter Single Sign-On user and password for a vSphere administrator account in the
- The cluster
cluster1, as the location in the vCenter Server inventory in which to deploy the VCH.
- The port group named
vic-bridge, for use as the container bridge network.
- The port group named
vic-public, for use as the public network.
- A static IP address with a network mask for the VCH endpoint VM on the public network in the
--public-network-ipoption, along with the addresses for the gateway and two DNS servers in the
- The shared datastore named
datastore1, for use as the image store, in which to store container images, in the
- For simplicity, disables the verification of client certificates by specifying the
- Names the VCH
- The thumbprint of the vCenter Server host certificate by specifying the
- The path to the certificate for vSphere Integrated Containers Registry in the
- A volume store named
--volume-storeoption. In this example, the datastore to use as the volume store is
datastore2that is not the same datastore as is used for the image store.
You could also specify
--volume-store nfs://nfs_server/path_to_share_point:default to designate an NFS share point as the default volume store.
At the end of a successful deployment,
vic-machine displays information about the new VCH:
Initialization of appliance successful VCH ID: vch_id VCH Admin Portal: https://vch_address:2378 Published ports can be reached at: vch_address Docker environment variables: DOCKER_HOST=vch_address:2376 Environment saved in test_vch/test_vch.env Connect to docker: docker -H vch_address:2376 --tls info Installer completed successfully
Now you can Test the Deployment of the VCH.
If you see errors during deployment, see Troubleshoot Virtual Container Host Deployment.
For information about how to access VCH logs, including the deployment log, see Access Virtual Container Host Log Bundles.
After you deploy a VCH, you can pull container images from a public repository, such as Docker Hub, and deploy container VMs from them in the VCH. In this way, you can see how deploying and running container VMs affects your vSphere environment.
You can also use vSphere Integrated Containers Management Portal and Registry to test your VCH. This version of vSphere Integrated Containers includes an image repository named
dch-photon, that is pre-loaded in the
default-project in vSphere Integrated Containers Registry. The
dch-photon image requires that the VCHs on which it is deployed have a specific minimum configuration:
- The VCH must be able to pull the
dch-photonimage from the vSphere Integrated Containers Registry instance. You must provide the registry's CA certificate to the VCH so that it can connect to the registry.
dch-photoncontainer creates an anonymous volume, and as such requires a volume store named
The VCH that you deployed in the Example above meets these requirements, so you can use the
dch-photon image to test it.
This example uses the
dch-photon image for demonstration purposes only. For information about how container developers can actually use
dch-photon, see Building and Pushing Images with the dch-photon Docker Engine in Developing Applications with vSphere Integrated Containers.
vSphere Integrated Containers 1.5.x supports
dch-photon version 17.06.
Log in to the vSphere Client, go to Hosts and Clusters, and select the cluster on which you deployed the VCH.
You should see a resource pool with the name that you set for the VCH. The resource pool contains the VCH endpoint VM.
In a Docker client, run the
docker infocommand to confirm that you can connect to the VCH.
docker -H vch_address:2376 --tls info
You should see confirmation that the Storage Driver is
vSphere Integrated Containers Backend Engine.
In your Docker client terminal, pull a Docker container image from Docker Hub into the VCH.
For example, pull the
docker -H vch_address:2376 --tls pull busybox
In the vSphere Client, go to Storage, right-click the datastore that you designated as the image store, and select Browse Files.
You should see that vSphere Integrated Containers Engine has created a folder that has the same name as the VCH. This folder contains the VCH endpoint VM files and a folder named
VIC. Expand this folder and navigate to the
imagesfolder contains folders for each container image that you pull into the VCH. The folders contain the container image files.
In your Docker client terminal, run the container that you pulled into the VCH.
docker -H vch_address:2376 --tls run --name test busybox
In the vSphere Client, go to Hosts and Clusters and expand the VCH resource pool.
You should see a VM named
test-container_id. This is the container VM that you created from the
In the vSphere Client, go to Storage and select the datastore that you designated as the image store.
At the top-level of the datastore, you should see a folder that uses the container ID as its name. The folder contains the files for the container VM that you just created.
- In a browser, log in to the vSphere Integrated Containers Management Portal at https://vic_appliance_address with a vSphere administrator, Management Portal administrator, or DevOps administrator user account.
- Select Home and make sure that the Project drop-down menu is set to
Under Infrastructure, select Container Hosts and click +Container Host to register the VCH with the management portal.
- Enter a name for the VCH, for example,
- Leave Type set to
- For URL, enter the address of the VCH in the format https://vch_ip_address:2376, click Save, and click Yes to accept the VCH certificate.
- Enter a name for the VCH, for example,
Under Deployments, select Containers and click +Container.
dchin the Image search box and select the
dch-photonimage that is pre-loaded in vSphere Integrated Containers Registry:
- Click in the Search for tags box and select 17.06.
- Enter a name for the container VM, for example
dch-photon-test, and click Provision.
dch-photon-testcontainer deploys correctly, it shows up as running in the Containers view, alongside the stopped
testcontainer that you ran in the VCH from the Docker client.
Go back to the vSphere Client, navigate to the vSphere Integrated Containers view, and select the Containers tab.
You should see the
dch-photon-testcontainer in the list of container VMs that are running in this vCenter Server instance.
Go to Hosts and Clusters and expand the resource pool for the
You should see the
dch-photon-testcontainer VM running in the resource pool.
Go back to Storage, right-click the datastore that you designated as the volume store, and select Browse Files.
You should see that vSphere Integrated Containers Engine has created a folder named
VICat the top level of the datastore. This folder contains a subfolder named
volumes, that contains folders for the volumes created by the
dch-photoncontainer VM. These folders contain the VDMK files for those volumes.
What to Do Next
The VCH and the
dch-photon container VM are ready for container developers to use. For information about how developers connect to vSphere Integrated Containers Registry from Docker clients, and how they can use
dch-photon, see the following topics in Developing Applications with vSphere Integrated Containers: