About

As you build your ambient mesh, you might want to add a workload that runs on an external machine to your cluster environment. For example, you might run an app or service in a virtual machine (VM) that must communicate with services in the Istio ambient mesh that runs in your Kubernetes cluster.

To extend the mesh to include workloads running on VMs, you leverage the istioctl bootstrap command to generate a bootstrap token, and deploy a ztunnel instance on the VM that uses that token to onboard to your mesh. Then, the workloads on your VM can communicate with in-mesh services in your cluster via the ztunnel.

Before you begin

  1. Set up an ambient mesh in a single or multicluster setup.

  2. Deploy the bookinfo sample app.

  3. If you have not already, get the Solo distribution of Istio binary and install istioctl, which you use for the bootstrap command in this guide. 3. Save the Solo distribution of Istio version that you installed.

    • Istio 1.29 and later:
        export ISTIO_VERSION=1.28.1-patch0
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
    • Istio 1.28 and earlier: Save the repo key for the minor version of the Solo distribution of Istio. This is the 12-character hash at the end of the repo URL us-docker.pkg.dev/gloo-mesh/istio-<repo-key>, which you can find in the Istio images built by Solo.io support article.
        # 12-character hash at the end of the repo URL
export REPO_KEY=<repo_key>
export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}

    1. Get the OS and architecture that you use on your machine.

        OS=$(uname | tr '[:upper:]' '[:lower:]' | sed -E 's/darwin/osx/')
ARCH=$(uname -m | sed -E 's/aarch/arm/; s/x86_64/amd64/; s/armv7l/armv7/')
echo $OS
echo $ARCH

    2. Download the Solo distribution of Istio binary and install istioctl.

      • Istio 1.29 and later:
          mkdir -p ~/.istioctl/bin
curl -sSL https://storage.googleapis.com/soloio-istio-binaries/release/$ISTIO_IMAGE/istio-$ISTIO_IMAGE-$OS-$ARCH.tar.gz | tar xzf - -C ~/.istioctl/bin
mv ~/.istioctl/bin/istio-$ISTIO_IMAGE/bin/istioctl ~/.istioctl/bin/istioctl
chmod +x ~/.istioctl/bin/istioctl

export PATH=${HOME}/.istioctl/bin:${PATH}
      • Istio 1.28 and earlier:
          mkdir -p ~/.istioctl/bin
curl -sSL https://storage.googleapis.com/istio-binaries-$REPO_KEY/$ISTIO_IMAGE/istioctl-$ISTIO_IMAGE-$OS-$ARCH.tar.gz | tar xzf - -C ~/.istioctl/bin
chmod +x ~/.istioctl/bin/istioctl

export PATH=${HOME}/.istioctl/bin:${PATH}

    3. Verify that the istioctl client runs the Solo distribution of Istio that you installed.

        istioctl version --remote=false

      Example output:

        client version: 1.28.1-patch0-solo

  4. Install docker to run a ztunnel instance on the VM.

Onboard a VM to the ambient mesh

  1. In your cluster, update your istiod installation to enable the REQUIRE_3P_TOKEN="false" environment variable on istiod, which is required for the ztunnel that you deploy to the VM in later steps to connect to istiod. In a multicluster mesh setup, enable this environment variable on the istiod installation in the cluster you want to connect the VM to.

    Create the following gloo-extensions-config configmap.

      kubectl apply -n gloo-mesh -f -<<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: gloo-extensions-config
  namespace: gloo-mesh
data:
  values.istiod: |
    env:
      REQUIRE_3P_TOKEN: false
EOF
    1. Get the current values for the istiod Helm release in your cluster.
        helm get values istiod -n istio-system -o yaml > istiod.yaml
open istiod.yaml
    2. Upgrade your Helm release with the --set env.REQUIRE_3P_TOKEN="false" setting.
        helm upgrade istiod oci://${HELM_REPO}/istiod \
-n istio-system \
-f istiod.yaml \
--set env.REQUIRE_3P_TOKEN="false"

  2. In your cluster, generate an Istio bootstrap configuration.

    • This command creates a bootstrap token that includes the necessary certificates and metadata for the VM to join the ambient mesh. The VM later uses this token to authenticate with the mesh.
    • The --namespace vm-ns and --service-account vm-sa flags create a namespace and service account of those names, respectively. The service account represents the VM in the cluster, so that istiod treats it the same way as any other pod in the mesh. If you later want to apply Istio resources to your VM workload, you can use this service account and namespace in the configuration. You can replace the placeholder vm-ns and vm-sa values as needed.
    • For more information about this command, run istioctl bootstrap --help.
      istioctl bootstrap --namespace vm-ns --service-account vm-sa

  3. Log in to your VM, such as by using SSH.

  4. On your VM, copy and save the bootstrap token that you generated as an environment variable.

      export BOOTSTRAP_TOKEN=<generated_token>

  5. Start a ztunnel instance on the VM. A ztunnel is a lightweight data plane component that enables the VM to participate in the ambient mesh. This command pulls the ztunnel container image and starts it with the necessary configuration to connect to the mesh.

      docker run -d -e BOOTSTRAP_TOKEN=${BOOTSTRAP_TOKEN} -e ALWAYS_TRAVERSE_NETWORK_GATEWAY=true --network=host us-docker.pkg.dev/gloo-mesh/istio-e038d180f90a/ztunnel:1.28.1-patch0-solo-distroless

  6. Test connectivity from the VM to services in the mesh, such as to the productpage service in the bookinfo namespace. For example, the following curl commands test connectivity by using productpage’s Kubernetes DNS name and mesh-internal DNS name. Two 200 OK responses indicate that the VM has successfully joined the mesh and can communicate with other in-mesh services.

      export ALL_PROXY=socks5h://127.0.0.1:15080
curl productpage.bookinfo:9080
curl productpage.bookinfo.mesh.internal:9080