Skip to content
This version of the documentation is currently under development. Select the stable version from the version drop down.

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

istioctl vm add-workload

Page as Markdown
Reference for the istioctl vm add-workload command.
istioctl vm add-workload

Add a workload identity to a generic VM in the mesh.
Synopsis

‘istioctl vm add-workload’ configures a generic VM to run a workload identity
in the ambient mesh using per-workload token authentication. This command:
  1. Creates the Kubernetes ServiceAccount for the workload identity.
  2. Generates a long-lived authentication token for the workload.
  3. Creates a WorkloadEntry resource in the cluster.
  4. On the first workload (auto-detected), generates a BOOTSTRAP_TOKEN
to start ztunnel on the VM.
The per-workload token must be placed on the VM at the path:
/etc/ztunnel/tokens///token
istioctl vm add-workload <workload-name> [flags]
Examples

  # Add workload 'web-api' on a VM at 10.0.1.5
  istioctl vm add-workload web-api \
    --address 10.0.1.5 \
    --namespace vm-apps \
    --ports http:80:8080

  # Add a second workload to the same VM
  istioctl vm add-workload grpc-backend \
    --address 10.0.1.5 \
    --namespace vm-apps \
    --ports grpc:9090

  # Force re-generation of the bootstrap token
  istioctl vm add-workload web-api \
    --address 10.0.1.5 \
    --namespace vm-apps \
    --bootstrap

  # Write the workload token to a local file instead of printing
  istioctl vm add-workload web-api \
    --address 10.0.1.5 \
    --namespace vm-apps \
    --output-dir ./vm-config
Options

      --address string              VM IP address (required)
      --bootstrap                   Force re-generation of the bootstrap token, even if the gateway SA already exists.
      --external                    Mark the workload as external to the cluster network (uses east-west gateway).
      --gateway-sa string           Name of the gateway ServiceAccount used for ztunnel XDS/CA authentication. (default "vm-gateway")
      -h, --help                    help for add-workload
      --hostname string             Hostname of the VM (must match the HOSTNAME env var on the VM). Used to reference the gateway WorkloadEntry.
      -o, --output-dir string       Directory to write the workload token file to instead of printing it.
      --ports string                Port configuration as 'protocol:port[:targetPort][/...]' (e.g. 'http:80:8080/grpc:9090'). Defaults to 'http:80'.
      -s, --service-account string  Kubernetes service account for the workload identity. Defaults to the workload name.
Options inherited from parent commands

      --as string                  Username to impersonate for the operation. User could be a regular user or a service account in a namespace
      --as-group stringArray       Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --as-uid string              UID to impersonate for the operation.
      --context string             Kubernetes configuration context
      -i, --istioNamespace string  Istio system namespace (default "istio-system")
      --kubeclient-timeout string  Kubernetes client timeout as a time.Duration string, defaults to 15 seconds. (default "15s")
      -c, --kubeconfig string      Kubernetes configuration file
      -n, --namespace string       Kubernetes namespace
      --out string                 output directory (default "/tmp/istioctl-cli-docs/1.30")
istioctl multicluster linkistioctl ztunnel-config endpoints