Using the vic-machine CLI Utility

After you deploy the vSphere Integrated Containers appliance, you 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.

The vSphere Integrated Containers Engine bundle includes the vic-machine CLI utility. You use vic-machine to deploy and manage virtual container hosts (VCHs) at the command line.

Running vic-machine Commands

You run vic-machine commands by specifying the appropriate binary for the platform on which you are using vic-machine, the vic-machine command to run, and multiple options for that command.

You use the vic-machine create command to deploy VCHs:

vic-machine-windows create --option argument --option argument
vic-machine-linux create --option argument --option argument
vic-machine-darwin create --option argument --option argument

Enabling Autocomplete

vSphere Integrated Containers provides an autocomplete feature for vic-machine commands and options. The autocomplete feature is available for the bash and zsh shells, for all of the Windows, Linux, and MacOS versions of vic-machine.

To enable autocomplete, download the vSphere Integrated Containers bundle and unpack it on your working machine.

  1. Open a bash or zsh shell and navigate to the vic folder of the unpacked vSphere Integrated Containers bundle.

  2. Run the source command to configure the autocomplete function of the current shell instance, according to your shell and OS.

    • Windows and bash:
      source autocomplete/bash/vic-machine-windows.exe
    • Linux and bash:
      source autocomplete/bash/vic-machine-linux
    • MacOS and bash:
      source autocomplete/bash/vic-machine-darwin
    • Windows and zsh:
      source autocomplete/zsh/vic-machine-windows.exe
    • Linux and zsh:
      source autocomplete/zsh/vic-machine-linux

    • MacOS and zsh:

      source autocomplete/zsh/vic-machine-darwin

      Using the source command enables autocomplete for the current session. For information about how to enable autocomplete persistently, see documentation for your shell and OS combination.

  3. Start typing a vic-machine command and hit the tab key.

    The autocomplete utility lists all of the possible commands that match what you typed. For example if you type vic-machine-windows c and hit tab, the autocomplete proposes the following commands:

    $ vic-machine-windows c
configure  create
    If you start typing an option and hit tab, the autocomplete utility lists all of the possible options. For example: 
    $ vic-machine-windows create --t
--target           --timeout          --tls-cert-path    --tls-server-cert
--thumbprint       --tls-ca           --tls-cname        --tls-server-key

Specifying Option Arguments

Wrap any option arguments that include spaces or special characters in quotes. Use single quotes if you are using vic-machine on a Linux or Mac OS system and double quotes on a Windows system.

Option arguments that might require quotation marks include the following:

  • User names and passwords in --target, or in --user and --password.
  • Datacenter names in --target.
  • VCH names in --name.
  • Datastore names and paths in --image-store and --volume-store.
  • Network and port group names in all networking options.
  • Cluster and resource pool names in --compute-resource.
  • Folder names in the paths for --tls-cert-path, --tls-server-cert, --tls-server-key, --appliance-iso, and --bootstrap-iso.

For example, to deploy a VCH into a cluster named cluster 1 in a vCenter Server instance that requires the vSphere administrator account Administrator@vsphere.local, you must wrap the corresponding option arguments in quotes:

vic-machine-linux 
--target vcenter_server_address
--user 'Administrator@vsphere.local'
--compute-resource 'cluster 1'
[...]

vic-machine-windows 
--target vcenter_server_address
--user "Administrator@vsphere.local"
--compute-resource "cluster 1"
[...]

Basic vic-machine create Options

The vic-machine options in this section are common to all vic-machine commands.

You can set environment variables so that you do not have to specify the --target, --user, --password, and --thumbprint options in every vic-machine command. For information about setting vic-machine environment variables, see Set Environment Variables for Common vic-machine Options.

If you use the Create Virtual Container Host wizard, it deploys VCHs to the vCenter Server instance with which the vSphere Integrated Containers appliance is registered, and uses the vSphere credentials with which you are logged in to the vSphere Client. Consequently, when using the Create Virtual Container Host wizard, you do not need to provide any information about the deployment target, vSphere administrator credentials, or vSphere certificate thumbprints.

--target

Short name: -t

The IPv4 address, fully qualified domain name (FQDN), or URL of the ESXi host or vCenter Server instance on which you are deploying a VCH. This option is always mandatory when using vic-machine.

To facilitate IP address changes in your infrastructure, provide an FQDN whenever possible, rather than an IP address. If vic-machine create cannot resolve the FQDN, it fails with an error.

Usage:

If the target ESXi host is not managed by vCenter Server, provide the address of the ESXi host.

--target esxi_host_address

If the target ESXi host is managed by vCenter Server, or if you are deploying to a cluster, provide the address of vCenter Server.

--target vcenter_server_address

You can include the user name and password in the target URL. If you are deploying a VCH on vCenter Server, specify the user name for an account that has the Administrator role on that vCenter Server instance. 

--target vcenter_or_esxi_username:password@vcenter_or_esxi_address

If you do not include the user name in the target URL, you must specify the --user option. If you do not specify the --password option or include the password in the target URL, vic-machine prompts you to enter the password.

If you are deploying a VCH on a vCenter Server instance that includes more than one datacenter, include the datacenter name in the target URL. If you include an invalid datacenter name, vic-machine create fails and suggests the available datacenters that you can specify. 

--target vcenter_server_address/datacenter_name

--user

Short name: -u

The user name for the ESXi host or vCenter Server instance on which you are deploying a VCH.

If you are deploying a VCH on vCenter Server, specify a user name for an account that has the Administrator role on that vCenter Server instance.

You can also specify the user name in the URL that you pass to vic-machine create in the --target option, in which case the --user option is not required.

You can configure a VCH so that it uses a non-administrator account with reduced privileges for post-deployment operations by specifying the --ops-user option. If you do not specify --ops-user, VCHs use the vSphere administrator account that you specify in --user for general post-deployment operations. For information about using a different account for post-deployment operation, see Create the Operations User Account.

Usage:

--user esxi_or_vcenter_server_username

--password

Short name: -p

The password for the vSphere administrator account on the vCenter Server on which you are deploying the VCH, or the password for the ESXi host if you are deploying directly to an ESXi host. If not specified, vic-machine prompts you to enter the password during deployment.

You can also specify the user name and password in the URL that you pass to vic-machine create in the --target option, in which case the --password option is not required.

Usage:

--password esxi_host_or_vcenter_server_password

--thumbprint

Short name: None

If your vSphere environment uses untrusted, self-signed certificates to authenticate connections, you must specify the thumbprint of the vCenter Server or ESXi host certificate in the --thumbprint option of all vic-machine commands. If your vSphere environment uses trusted certificates that are signed by a known Certificate Authority (CA), you do not need to specify the --thumbprint option.

For information about how to obtain the certificate thumbprint for vCenter Server or an ESXi host, see Obtain vSphere Certificate Thumbprints.

If you run vic-machine without the specifying the --thumbprint option and the operation fails, the resulting error message includes the certificate thumbprint. Always verify that the thumbprint in the error message is valid before attempting to run the command again.

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.

Use upper-case letters and colon delimitation in the thumbprint. Do not use space delimitation.

Usage:

--thumbprint certificate_thumbprint

--force

Short name: -f

Forces vic-machine create to ignore warnings and non-fatal errors and continue with the deployment of a VCH. Errors such as an incorrect compute resource still cause the deployment 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 deployment topologies that would otherwise fail with an error. Do not use --force in production environments.

Usage:

--force

--timeout

Short name: none

The timeout period for uploading the vSphere Integrated Containers Engine files and ISOs to the ESXi host, and for powering on the VCH. Specify a value in the format XmYs if the default timeout of 3m0s is insufficient.

Usage:

--timeout 5m0s

Other vic-machine create Options

The vic-machine create command provides many more options that allow you to customize the deployment of VCHs to correspond to your vSphere environment and to meet your development requirements.

For information about the other VCH deployment options, see the following topics:

The options that these topics describe apply to both the vic-machine CLI utility and to the Create Virtual Container Host wizard in the vSphere Client.

For the full list of vic-machine create options, with links to the relevant sections of the documentation, see vic-machine Options Reference.

results matching ""

    No results matching ""