Configure Running Virtual Container Hosts
You can configure certain settings on an existing virtual container host (VCH) by using the vic-machine configure
command.
When you run vic-machine configure
, you use the options described in Common vic-machine
Options to identify the VCH to configure. In addition to these options, the vic-machine configure
command provides options that allow you to perform modifications on VCHs.
Using vic-machine configure
To see the current configuration of a VCH before you configure it, and to check the new configuration, run vic-machine inspect config
before and after you run vic-machine configure
. For information about running vic-machine inspect config
, see Obtain VCH Configuration Information.
IMPORTANT: Running vic-machine inspect config
before you run vic-machine configure
is especially important if you are adding registry certificates, volume stores, DNS servers, or container networks to a VCH that already includes one or more of those elements. When you add registry certificates, volume stores, DNS servers, or container networks to a VCH, you must specify the existing configuration as well as any new configurations in separate instances of the appropriate vic-machine inspect config
option.
When you run a vic-machine configure
operation, vic-machine
takes a snapshot of the VCH endpoint VM before it makes any modifications to the VCH. However, vic-machine
does not remove the snapshot when the configuration operation finishes. You must manually remove the snapshot, after verifying that the configuration operation was successful.
The vic-machine configure
command includes a --force
option, that forces vic-machine configure
to ignore warnings and non-fatal errors and continue with the configuration of a VCH. Errors such as an incorrect compute resource still cause the configuration to fail.
CAUTION: Specifying the --force
option bypasses safety checks, including certificate thumbprint verification. Using --force
in this way can expose VCHs to the risk of man-in-the-middle attacks, in which attackers can learn vSphere credentials. Using --force
can result in unexpected topologies that would otherwise fail with an error. Do not use --force
in production environments.
Update vCenter Server Credentials
If the vCenter Server credentials change after the deployment of a VCH, you must update that VCH with the new credentials. The VCH will not function until you update the credentials.
You provide the new vCenter Server credentials in the vic-machine configure --ops-user
and --ops-password
options. You use the vic-machine configure --ops-user
and --ops-password
options to update the credentials even if you did not specify the vic-machine create --ops-user
and --ops-password
options during the initial deployment of the VCH. If you did not specify vic-machine create --ops-user
and --ops-password
during the deployment of the VCH, by default the VCH uses the values from vic-machine create --user
and --password
for the --ops-user
and --ops-password
settings, and it uses these credentials for day-to-day, post-deployment operation.
For example, if you specified --user Administrator@vsphere.local
in the vic-machine create
command, and you did not set the vic-machine create --ops-user
and --ops-password
options, the VCH automatically sets --ops-user
to Administrator@vsphere.local and uses this account for post-deployment operations. Consequently, if the password for Administrator@vsphere.local changes, you must specify the vic-machine configure --ops-user
and --ops-password
options to update the password.
This example specifies the --user
and --password
options to log into vCenter Server, and then specifies --ops-user
and --ops-password
to update the password for the Administrator@vsphere.local account in the VCH.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --ops-user Administrator@vsphere.local --ops-password new_admin_password
You can also use the vic-machine configure --ops-user
and --ops-password
options to configure an operations user on a VCH that was not initially deployed with that option. Similarly, you can use --ops-user
and --ops-password
to change the operations user account on a VCH that was deployed with an operations user account, or to update the password for a previously specified operations user account. If you are specifying a new user account for --ops-user
, you can also specify --ops-grant-perms
, to automatically grant the required permissions to the operations user account.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --ops-user new_operations_user_account --ops-password password --ops-grant-perms
For more information about the operations user, see Create the Operations User Account and Configure the Operations User.
Update vCenter Server Certificates
If the vCenter Server certificate changes, you must update any VCHs running on that vCenter Server instance, otherwise they will no longer function.
To update the certificate, provide the new certificate thumbprint to the VCH in the --thumbprint
option. For information about how to obtain the vCenter Server certificate thumbprint, see Obtain vSphere Certificate Thumbprints.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --id vch_id --thumbprint new_certificate_thumbprint
Add or Update Registry Server Certificates
If a VCH requires access to a new vSphere Integrated Containers Registry instance, or to another private registry, you can add new registry CA certificates by using the vic-machine configure --registry-ca
option. You also use the vic-machine configure --registry-ca
option if the certificate for an existing registry changes.
The vic-machine configure --registry-ca
option functions in the same way as the equivalent vic-machine create --registry-ca
option. For information about the vic-machine create --registry-ca
option, see Connect Virtual Container Hosts to Registries.
This example updates the certificate for a registry that this VCH already uses.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --registry-ca path_to_new_ca_cert_for_existing_registry
If you are adding registry certificates to a VCH that already has one or more registry certificates, you must also specify each existing registry certificate in a separate instance of --registry-ca
. This is because the --registry-ca
option replaces certificates instead of just adding them. This example passes the CA certificate for a new registry to a VCH and specifies the existing certificate for a registry that this VCH already uses.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --registry-ca path_to_ca_cert_for_existing_registry --registry-ca path_to_ca_cert_for_new_registry
NOTE: Unlike vic-machine create
, the vic-machine configure
command does not provide an --insecure-registry
option.
Update Security Configuration
You can configure the security settings of a VCH by using the different TLS options of the vic-machine configure
command.
- To configure TLS authentication with automatically generated certificates on a VCH that currently implements no TLS authentication, or to regenerate automatically generated certificates, use the
vic-machine configure --tls-cname
option. - To configure the path to an existing
ca.pem
file for the custom CA that you use to sign client certificates. Include the filename in the path. You can specify--tls-ca
multiple times. - To configure TLS authentication with custom certificates on a VCH that currently implements no TLS authentication, or that uses automatically generated certificates, or to replace existing custom certificates, use the
vic-machine configure --tls-server-cert
and--tls-server-key
options. - To disable verification of client certificates, use the
vic-machine configure --no-tlsverify
option. - To change the location in which to search for and store certificates, use the
vic-machine configure --tls-cert-path
option.
The vic-machine configure
TLS options function in the same way as the equivalent vic-machine create
options. For information about the vic-machine create
security options, see Virtual Container Hosts Security.
This example sets the vic-machine configure --tls-cname
option to implement TLS authentication with automatically generated server and client certificates. Before the configuration, the VCH either has no authentication or uses automatically generated certificates that you want to regenerate. The --tls-cert-path
option specifies the folder in which to store the generated certificate.
$ vic-machine-operating_system configure - --target vcenter_server_address --user Administrator@vsphere.local --password password - --thumbprint certificate_thumbprint - --id vch_id - --tls-cname *.example.com - --tls-cert-path path_to_cert_folder
This example uses the vic-machine configure --tls-cname
and the --tls-ca
options to implement options for the custom CA that you use to sign client certificates. You must specify the --tls-cname
option with the --tls-ca
option when there is no static IP defined for the client network.
$ vic-machine-i>operating_system configure --target wvcenter_server_address --user Administrator@vsphere.local --password 'password --thumbprint certificate_thumbprint --tls-ca path_to_ca_file/ca.pem --tls-cname cname_from_server_cert
This example uses the vic-machine configure --tls-server-cert
and --tls-server-key
options to implement TLS authentication with custom certificates. Before the configuration, the VCH either has no TLS authentication, or it uses automatically generated certificates, or it uses custom certificates that require replacement.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --tls-server-cert path_to_cert/certificate_name.pem --tls-server-key path_to_key/key_name.pem
This example sets --no-tlsverify
to disable the verification of client certificates on a VCH that implements client and server authentication.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --no-tlsverify
Update Affinity Group Settings
After the deployment of a VCH, you can instruct vSphere Integrated Containers to automatically create a DRS VM group in vSphere for the VCH endpoint VM and its container VMs. If you use this option to reconfigure an existing VCH, you can use the resulting VM group in DRS VM-Host affinity rules, to restrict the set of hosts on which the VCH endpoint VM and its container VMs can run.
The vic-machine configure --affinity-vm-group
option functions in the same way as the equivalent vic-machine create
option. For information about the vic-machine create --affinity-vm-group
option, see Virtual Container Host Compute Capacity.
To create a VM group for an existing VCH that was not deployed with this option, use the vic-machine create --affinity-vm-group
option with no arguments.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --affinity-vm-group
To remove a VCH that was deployed with the vic-machine create affinity-vm-group
from its VM group, specify false
as the argument for the vic-machine configure affinity-vm-group
option.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --affinity-vm-group=false
When you specify --affinity-vm-group=false
, vSphere Integrated Containers deletes the automatically created VM group from vSphere.
Set or Update Storage Quotas
If you deployed a VCH with a storage quota, that limits the amount of space that a VCH can consume in the image store, you can modify the quota after deployment. You can also set a storage quota if you did not set one when you deployed the VCH.
The vic-machine configure --storage-quota
option functions in the same way as the equivalent vic-machine create
option. For information about the vic-machine create --storage-quota
option, see Storage Quota in Specify the Image Datastore.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --storage-quota new_limit
To remove an existing storage quota from a VCH, so that the VCH can consume an unlimited amount of storage, set --storage-quota 0
.
Set or Update Container VM Limit
If you deployed a VCH with a limit on the number of container VMs that it can host, you can modify the limit after deployment. You can also set a limit on the number of container VMs if you did not set one when you deployed the VCH.
If you set a new limit on a VCH that is lower than the number of container VMs that already exist on the VCH, all existing container VMs continue to run. For example, if a VCH hosts 60 container VMs and you set a new limit of 50, all 60 container VMs continue to run. However, attempts to deploy additional container VMs fail until you delete enough container VMs to bring the total to below the new limit.
NOTE: This option is available in vSphere Integrated Containers 1.5.2 and later.
The vic-machine configure --containers
option functions in the same way as the equivalent vic-machine create
option. For information about the vic-machine create --containers
option, see Container VM Limit in General Virtual Container Host Settings.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --containers new_limit
To remove an existing container VM limit from a VCH, so that the VCH can host an unlimited number of VMs, set --containers 0
.
Add Volume Stores
You can add volume stores to VCHs by using the vic-machine configure --volume-store
option. You can add volume stores backed by vSphere datastores or by NFSv3 shares.
The vic-machine configure --volume-store
option functions in the same way as the equivalent vic-machine create --volume-store
option. For information about the vic-machine create --volume-store
option, see Specify Volume Stores.
If you are adding volume stores to a VCH that already has one or more volume stores, you must specify each existing volume store in a separate instance of --volume-store
.
Before you add an NFS volume store to a VCH, you can test that the NFS share point is configured correctly so that containers can access it by mounting the NFS share point directly in the VCH endpoint VM. For information about how to perform this test, see Install Packages in the Virtual Container Host Endpoint VM and Mount an NFS Share Point in the VCH Endpoint VM.
This example adds a new NFS volume store to a VCH. The VCH already has an existing volume store with the label default
, that is backed by a vSphere datastore.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --volume-store datastore_name/datastore_path:default --volume-store nfs://nfs_server/path_to_share_point:nfs_volume_store_label
NOTE: The current version of vSphere Integrated Containers does not allow you to remove volume stores from a VCH.
Add and Reset DNS Servers
If you deployed the VCH with a static IP address, you can add DNS servers or reset them to the default by using the vic-machine configure --dns-server
option.
The vic-machine configure --dns-server
option functions in the same way as the equivalent vic-machine create --dns-server
option. For information about the vic-machine create --dns-server
option, see DNS Server in Configure the Public Network.
If you are adding DNS servers to a VCH that already includes one or more DNS servers, you must also specify each existing DNS server in a separate instance of --dns-server
. This example adds a new DNS server, dns_server_2
, to a VCH that already uses dns_server_1
.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --dns-server dns_server_1 --dns-server dns_server_2
To reset the DNS servers on a VCH to the default, set the vic-machine configure --dns-server
option to ""
.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --dns-server ""
NOTE: The vic-machine configure
command does not include options to set a static IP address on a VCH that uses DHCP.
Configure Container Network Settings
If containers that run in a VCH require a dedicated network for external communication, you can add one or more container networks to the VCH by using the vic-machine configure --container-network
options. You can specify --container-network
multiple times to add multiple container networks.
The vic-machine configure --container-network
options function in the same way as the equivalent vic-machine create
options. For information about the vic-machine create
container network options, Configure Container Networks.
This example adds a new container network to a VCH. It designates a port group named vic-containers
for use by container VMs, gives the container network the name vic-container-network
for use by Docker, specifies the gateway, two DNS servers, and a range of IP addresses on the container network for container VMs to use.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --container-network vic-containers:vic-container-network --container-network-gateway vic-containers:gateway_ip_address/24 --container-network-ip-range vic-containers:192.168.100.0/24 --container-network-dns vic-containers:dns1_ip_address --container-network-dns vic-containers:dns2_ip_address
If you are adding container networks to a VCH that already includes one or more container networks, you must also specify each existing container network in separate instances of the --container-network
options. This example adds a new DHCP container network named vic-containers-2
to the VCH from the example above.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --container-network vic-containers:vic-container-network --container-network-gateway vic-containers:gateway_ip_address/24 --container-network-ip-range vic-containers:192.168.100.0/24 --container-network-dns vic-containers:dns1_ip_address --container-network-dns vic-containers:dns2_ip_address --container-network vic-containers-2:vic-container-network-2
You can also configure the trust level of the container network firewall by setting the --container-network-firewall
option. This example opens the firewall for outbound connections on the two container networks from the preceding examples.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --container-network vic-containers:vic-container-network --container-network-gateway vic-containers:gateway_ip_address/24 --container-network-ip-range vic-containers:192.168.100.0/24 --container-network-dns vic-containers:dns1_ip_address --container-network-dns vic-containers:dns2_ip_address --container-network-firewall vic-containers:outbound --container-network vic-containers-2:vic-container-network-2 --container-network-firewall vic-containers-2:outbound
For information about the trust levels that you can set, see --container-network-firewall
in Configure Container Networks.
You cannot modify or delete an existing container network on a VCH.
Add, Configure, or Remove Proxy Servers
If access to the Internet or to private registry servers changes to pass through a proxy server, you configure a VCH to use the new proxy server by using the vic-machine configure --https-proxy
and --http-proxy
options. You also use the vic-machine configure --https-proxy
and --http-proxy
options if an existing proxy server changes.
The vic-machine configure --https-proxy
and --http-proxy
options function in the same way as the equivalent vic-machine create
options. For information about the vic-machine create --https-proxy
and --http-proxy
options, see Configure VCHs to Use Proxy Servers.
This example configures a VCH to use a new HTTPS proxy server.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --https-proxy https://new_proxy_server_address:port
To remove a proxy server from a VCH, set the vic-machine configure --https-proxy
or --http-proxy
options to ""
.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --https-proxy ""
Configure Debug Mode
To enable or disable debug mode on a VCH, you use the vic-machine configure --debug
option. You can also use vic-machine configure --debug
to increase or decrease the level of debugging on a VCH that is already running in debug mode.
The vic-machine configure --debug
option functions in the same way as the equivalent vic-machine create --debug
option. For information about the vic-machine create --debug
option, see Debug in the topic on configuring general VCH settings. By default, vic-machine create
deploys VCHs with debugging level 0.
This example increases the level of debugging to level 3, either on a VCH that is running with a lower level of debugging, or on a VCH that is not running in debug mode.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --debug 3
This example sets the --debug
option to 0, to disable debug mode on a VCH.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --debug 0
Configure CPU and Memory Allocations
If a VCH requires more resources, or if it consumes too many resources, you can configure CPU and memory allocations on the VCH resource pool by using the different vic-machine configure --memory
and --cpu
options.
The vic-machine configure
options for memory and CPU allocations function in the same way as the equivalent vic-machine create
options. For information about the vic-machine create
memory and CPU reservation and shares options, see Virtual Container Host Compute Capacity.
NOTE: Clusters that do not implement DRS do not support resource pools. If you deployed a VCH to a cluster on which DRS is disabled, the VCH is in a VM folder, rather than in a resource pool. Consequently, if you specify any vic-machine configure
options that apply to the memory or CPU configuration of the VCH resource pool, these options are ignored, with a warning in the configuration log.
This example configures a VCH to impose memory and CPU reservations, limits, and shares.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --memory 1024 --memory-reservation 1024 --memory-shares low --cpu 1024 --cpu-reservation 1024 --cpu-shares low
NOTE: If you set limits on memory and CPU usage that are too low, the vic-machine configure
operation might fail because it is unable to restart the VCH.
This example removes all limitations on memory and CPU use from a VCH.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --memory 0 --memory-reservation 0 --memory-shares normal --cpu 0 --cpu-reservation 0 --cpu-shares normal
Reset Upgrade or Configuration Progress
If an attempt to upgrade or configure a VCH was interrupted before it could complete successfully, any further attempts to run vic-machine upgrade
or vic-machine configure
fail with the error another upgrade/configure operation is in progress
. This happens because vic-machine upgrade
and vic-machine configure
set an UpdateInProgress
flag on the VCH endpoint VM that prevents other operations on that VCH while the upgrade or configuration operation is ongoing. If an upgrade or configuration operation is interrupted before it completes, this flag persists on the VCH indefinitely.
To clear the flag so that you can attempt further vic-machine upgrade
or vic-machine configure
operations, run vic-machine configure
with the --reset-progress
option.
$ vic-machine-operating_system configure --target vcenter_server_address --user Administrator@vsphere.local --password password --thumbprint certificate_thumbprint --id vch_id --reset-progress
IMPORTANT: Before you run vic-machine configure --reset-progress
, check in Recent Tasks in the vSphere Client that there are indeed no update or configuration operations in progress on the VCH endoint VM.
Roll Back to Previous Configuration
If the VCH configuration changes and you want to revert the changes, you can roll back the configuration to the previous settings by using the --rollback
option.
Before making changes to the configuration, vic-machine configure
takes a snapshot of the existing VCH configuration. The configuration process deletes older snapshots of any previous settings. The --rollback
option reverts the cofiguration of the VCH to the snapshot of the previous settings. Because vic-machine configure
only retains one snapshot, you can only use --rollback
to revert the VCH to the configuration that immediately precedes the most recent change.
To revert the configuration to the previous settings, run vic-machine configure
with the --rollback
option.
$ vic-machine-operating_system configure --rollback
Note: If you attempt to rollback a VCH that has been upgraded with vic-machine upgrade
and has undergone a configuration change with vic-machine configure
, you must run vic-machine configure --rollback
to roll back the configuration to the previous settings before running vic-machine upgrade --rollback
to roll the VCH back to its previous version.