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.

results matching ""

    No results matching ""