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 the following modifications on VCHs:

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.

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 those settings 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_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. This example specifies the credentials to log into vCenter Server in the --target option, rather than in --user and --password.

$ vic-machine-operating_system configure
    --target vcenter_server_username:password@vcenter_server_address
    --thumbprint certificate_thumbprint
    --id vch_id
    --ops-user new_operations_user_account
    --ops-password password

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_username:password@vcenter_server_address
    --id vch_id
    --thumbprint new_certificate_thumbprint

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 deployment topologies that would otherwise fail with an error. Do not use --force in production environments.

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_username:password@vcenter_server_address
    --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 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_username:password@vcenter_server_address
    --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 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.

CAVEATS:

  • The vic-machine configure command does not include an equivalent to vic-machine create --tls-ca option.
  • The vic-machine configure --tls-cname option exists in this release of vSphere Integrated Containers, but does not function and does not automatically regenerate certificates. To replace an automatically generated certificate, generate a certificate manually using the OpenSSL command line tool and use vic-machine configure --tls-server-cert and --tls-server-key to upload the new certificate to the VCH.

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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --thumbprint certificate_thumbprint
    --id vch_id
    --no-tlsverify

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_username:password@vcenter_server_address
    --thumbprint certificate_thumbprint
    --id vch_id
    --volume-store datastore_name/datastore_path:default
    --volume-store nfs://datastore_name/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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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.

This example configures a VCH to impose memory and CPU reservations, limits, and shares.

$ vic-machine-operating_system configure
    --target vcenter_server_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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_username:password@vcenter_server_address
    --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.

results matching ""

    No results matching ""