On this page
meshctl external-workload onboard
Reference for the ‘meshctl external-workload onboard’ command.
meshctl external-workload onboard
Onboard the external workload instance to the mesh.
Synopsis
Onboard the external workload instance to the mesh. This command must be run as root because it installs packages and configures services that require root privileges. To install the agent software as a part of the onboarding, use the –install, –istio, –spire, –otel flags in addition to the onboard options.
meshctl external-workload onboard [flags]
Examples
# Onboard a GCP instance corresponding to the ExternalWorkload 'my-workload' in the 'dev' namespace by allowing it to connect to the Kubernetes cluster 'test' via the Kubernetes 'istio-eastwest/istio-eastwestgateway' gateway with address '30.10.20.40', trust domain 'cluster.local':
sudo meshctl external-workload onboard --attestor gcp --ext-workload dev/my-workload --cluster test --gateway istio-eastwest/istio-eastwestgateway --gateway-addr 30.10.20.40 --trust-domain cluster.local"
# Onboard an AWS instance corresponding to the ExternalWorkload 'my-workload' in the 'dev' namespace by allowing it to connect to the Kubernetes cluster 'test' via the Kubernetes 'istio-eastwest/istio-eastwestgateway' gateway with address '30.10.20.40', trust domain 'cluster.local':
sudo meshctl external-workload onboard --attestor aws --ext-workload dev/my-workload --cluster test --gateway istio-eastwest/istio-eastwestgateway --gateway-addr 30.10.20.40 --trust-domain cluster.local
# Onboard an AWS instance corresponding to the ExternalWorkload 'my-workload' in the 'dev' namespace, in the Istio network 'vpc-123', by allowing it to connect to the cluster 'test' in a different Istio network 'vpc-456' via the cluster's 'istio-eastwest/istio-eastwestgateway' gateway with address '30.10.20.40', trust domain 'cluster.local':
sudo meshctl external-workload onboard --attestor aws --ext-workload dev/my-workload --network vpc-123 --cluster test --gateway istio-eastwest/istio-eastwestgateway --gateway-addr 30.10.20.40 --trust-domain cluster.local
# Onboard an instance corresponding to the ExternalWorkload 'my-workload' in the 'dev' namespace by allowing it to connect to the cluster 'test' by using a one-time join-token 'e471c564-71e8-4a38-8bbd-02b0e267f971' via the cluster's 'istio-eastwest/istio-eastwestgateway' gateway with address '30.10.20.40', trust domain 'cluster.local':
sudo meshctl external-workload onboard --ext-workload dev/my-workload --attestor token --join-token e471c564-71e8-4a38-8bbd-02b0e267f971 --cluster test --gateway istio-eastwest/istio-eastwestgateway --gateway-addr 30.10.20.40 --trust-domain cluster.local
# Install the agent packages as a part of the onboarding:
sudo meshctl external-workload onboard [OPTIONS] --install --istio https://storage.test.com/istio-sidecar.deb --gloo https://storage.test.com/gloo-workload-agent.deb
Options
--admin-bootstrap-port uint16 Mesh admin API port to fetch the bootstrap config (default 31339)
--admin-cacert-port uint16 Mesh admin API port to fetch the trust bundle (default 31338)
--agent-flags string Additional flags to pass as-is to Istio's pilot agent
--attestor string One of: aws, azure, gcp, token
--aws-metadata-endpoint string AWS endpoint to retrieve instance metadata (default "http://169.254.169.254/latest")
--az-resource-id string Azure resource ID (or audience) to request for the MSI token
-t, --bootstrap-timeout duration Timeout for the agent to bootstrap. If unspecified, timeout is disabled.
--cluster string Kubernetes cluster the external workload will connect to
--custom-dns Use custom DNS (external, hosts file, etc.) to resolve the hostnames for Istiod, SPIRE, and OTel services
--dual-stack Enable IPv4/IPv6 dual-stack networking
--exclude-inbound-ports strings List of inbound ports to exclude from traffic interception.
--exclude-interfaces strings List of network interfaces to exclude from traffic interception.
--exclude-outbound-cidr strings List of outbound CIDR ranges to exclude from traffic interception.
--exclude-outbound-ports strings List of outbound ports to exclude from traffic interception.
-e, --ext-workload string Namespace and name of the ExternalWorkload resource, in the form <namespace>/<name>. The namespace must correspond to the workload cluster namespace in the 'connectedClusters' field of the ExternalWorkload resource, not the namespace that the ExternalWorkload resource is applied in.
--external-ip string External IP address of the external workload. If set, traffic to the workload will be directed to this address.
--gateway string Namespace and name of the Kubernetes gateway service used to connect to the cluster, in the form <namespace>/<name>
--gateway-addr string IP address of the gateway used to connect to the Kubernetes cluster
--gcp-id-token-host string GCP where an identity token can be retrieved from (default "metadata.google.internal")
--gcp-service-account string GCP service account to fetch an identity token from (default "default")
-g, --gloo string URL or file path of Gloo agent package
-h, --help help for onboard
-w, --identity-socket-path string Path of the unix domain socket used to obtain workload identity credentials (default "unix:///var/run/secrets/workload-spiffe-uds/socket")
--install Install the agent packages as a part of the onboarding
--intercept-inbound-ports strings List of inbound ports to include for traffic interception. Defaults to all ports. (default [*])
--intercept-outbound-cidr strings List of outbound CIDR ranges to include for traffic interception. Defaults to all CIDR ranges. (default [*])
--intercept-outbound-ports strings List of outbound ports to include for traffic interception. Defaults to all ports.
-i, --istio string URL or file path of Istio agent package
--istio-ns string Istio control plane namespace (default "istio-system")
--istio-rev string Istio control plane revision
--istio-service-port uint16 Istio service port to connect to (default 15012)
--join-token string One-time join token to use to attest the workload when using the token attestor.
--network string Istio network that the external workload belongs to. Required when the workload connects to a cluster in a different network.
--otel-env stringToString Environment variables to pass to the OTel agent (default [])
--otel-log-level string Log level for the OTel agent (default "INFO")
--otel-service string Hostname or IP address of the OpenTelemetry collector service to connect to (default "gloo-metrics-gateway.gloo-mesh")
--otel-service-port uint16 OpenTelemetry collector service port to connect to (default 4317)
--spire-env stringToString Environment variables to pass to the SPIRE agent (default [])
--spire-log-level string Log level for the SPIRE agent (default "INFO")
--spire-service string Hostname or IP address of the SPIRE service to connect to (default "gloo-spire-server.gloo-mesh.svc")
--spire-service-port uint16 SPIRE service port to connect to (default 8081)
--trust-bundle string Trust bundle file path
--trust-domain string Trust domain of the cluster the workload will connect to. (default "cluster.local")
Options inherited from parent commands
--kubeconfig string Path to the kubeconfig file for the cluster.
--kubecontext string Kubernetes context for the cluster to run the command in.
-n, --namespace string Namespace to run the command in. (default "gloo-mesh")
--plain Disable styling for terminal output.
-v, --verbose Enable verbose logging.
SEE ALSO
- meshctl external-workload - Operations on external workloads that are onboarded to the service mesh.