Virtual Machine Installation

Follow this guide to deploy Istio and connect a virtual machine to it.

Prerequisites

1. Download the Istio release⁵
2. Perform any necessary platform-specific setup⁶
3. Check the requirements for Pods and Services⁷
4. Virtual machines must have IP connectivity to the ingress gateway in the connecting mesh, and optionally every pod in the mesh via L3 networking if enhanced performance is desired.
5. Learn about Virtual Machine Architecture⁸ to gain an understanding of the high level architecture of Istio’s virtual machine integration.

Prepare the guide environment

1. Create a virtual machine

2. Set the environment variables VM_APP, WORK_DIR , VM_NAMESPACE, and SERVICE_ACCOUNT on your machine that you’re using to set up the cluster. (e.g., WORK_DIR="${HOME}/vmintegration"):

   Single-Network Multi-Network

   $ VM_APP="<the name of the application this VM will run>"
   $ VM_NAMESPACE="<the name of your service namespace>"
   $ WORK_DIR="<a certificate working directory>"
   $ SERVICE_ACCOUNT="<name of the Kubernetes service account you want to use for your VM>"
   $ CLUSTER_NETWORK=""
   $ VM_NETWORK=""
   $ CLUSTER="Kubernetes"
   

3. Create the working directory on your machine that you’re using to set up the cluster:

   $ mkdir -p "${WORK_DIR}"
   

Install the Istio control plane

If your cluster already has an Istio control plane, you can skip the installation steps, but will still need to expose the control plane for virtual machine access.

Install Istio and expose the control plane on cluster so that your virtual machine can access it.

1. Create the IstioOperator spec for installation.

   $ cat <<EOF > ./vm-cluster.yaml
   apiVersion: install.istio.io/v1alpha1
   kind: IstioOperator
   metadata:
     name: istio
   spec:
     values:
       global:
         meshID: mesh1
         multiCluster:
           clusterName: "${CLUSTER}"
         network: "${CLUSTER_NETWORK}"
   EOF
   

2. Install Istio.

   Default Automated WorkloadEntry Creation

   $ istioctl install -f vm-cluster.yaml
   

3. Deploy the east-west gateway:

   Single-Network Multi-Network

   Zip

   $ samples/multicluster/gen-eastwest-gateway.sh10 --single-cluster | istioctl install -y -f -
   

4. Expose services inside the cluster via the east-west gateway:

   Single-Network Multi-Network

   Expose the control plane:

   Zip

   $ kubectl apply -n istio-system -f samples/multicluster/expose-istiod.yaml11
   

Configure the VM namespace

1. Create the namespace that will host the virtual machine:

   $ kubectl create namespace "${VM_NAMESPACE}"
   

2. Create a serviceaccount for the virtual machine:

   $ kubectl create serviceaccount "${SERVICE_ACCOUNT}" -n "${VM_NAMESPACE}"
   

Create files to transfer to the virtual machine

$ cat <<EOF > workloadgroup.yaml
apiVersion: networking.istio.io/v1
kind: WorkloadGroup
metadata:
  name: "${VM_APP}"
  namespace: "${VM_NAMESPACE}"
spec:
  metadata:
    labels:
      app: "${VM_APP}"
  template:
    serviceAccount: "${SERVICE_ACCOUNT}"
    network: "${VM_NETWORK}"
EOF

$ cat <<EOF > workloadgroup.yaml
apiVersion: networking.istio.io/v1
kind: WorkloadGroup
metadata:
  name: "${VM_APP}"
  namespace: "${VM_NAMESPACE}"
spec:
  metadata:
    labels:
      app: "${VM_APP}"
  template:
    serviceAccount: "${SERVICE_ACCOUNT}"
    network: "${VM_NETWORK}"
EOF

$ kubectl --namespace "${VM_NAMESPACE}" apply -f workloadgroup.yaml

$ cat <<EOF > workloadgroup.yaml
apiVersion: networking.istio.io/v1
kind: WorkloadGroup
metadata:
  name: "${VM_APP}"
  namespace: "${VM_NAMESPACE}"
spec:
  metadata:
    labels:
      app: "${VM_APP}"
  template:
    serviceAccount: "${SERVICE_ACCOUNT}"
    network: "${NETWORK}"
  probe:
    periodSeconds: 5
    initialDelaySeconds: 1
    httpGet:
      port: 8080
      path: /ready
EOF

Next, use the istioctl x workload entry command to generate:

• cluster.env: Contains metadata that identifies what namespace, service account, network CIDR and (optionally) what inbound ports to capture.
• istio-token: A Kubernetes token used to get certs from the CA.
• mesh.yaml: Provides ProxyConfig to configure discoveryAddress, health-checking probes, and some authentication options.
• root-cert.pem: The root certificate used to authenticate.
• hosts: An addendum to /etc/hosts that the proxy will use to reach istiod for xDS.*

$ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --clusterID "${CLUSTER}"

$ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --clusterID "${CLUSTER}" --autoregister

Configure the virtual machine

Run the following commands on the virtual machine you want to add to the Istio mesh:

1. Securely transfer the files from "${WORK_DIR}" to the virtual machine. How you choose to securely transfer those files should be done with consideration for your information security policies. For convenience in this guide, transfer all of the required files to "${HOME}" in the virtual machine.

2. Install the root certificate at /etc/certs:

   $ sudo mkdir -p /etc/certs
   $ sudo cp "${HOME}"/root-cert.pem /etc/certs/root-cert.pem
   

3. Install the token at /var/run/secrets/tokens:

   $ sudo  mkdir -p /var/run/secrets/tokens
   $ sudo cp "${HOME}"/istio-token /var/run/secrets/tokens/istio-token
   

4. Install the package containing the Istio virtual machine integration runtime:

   Debian CentOS

   $ curl -LO https://storage.googleapis.com/istio-release/releases/1.25.1/deb/istio-sidecar.deb
   $ sudo dpkg -i istio-sidecar.deb
   

5. Install cluster.env within the directory /var/lib/istio/envoy/:

   $ sudo cp "${HOME}"/cluster.env /var/lib/istio/envoy/cluster.env
   

6. Install the Mesh Config to /etc/istio/config/mesh:

   $ sudo cp "${HOME}"/mesh.yaml /etc/istio/config/mesh
   

7. Add the istiod host to /etc/hosts:

   $ sudo sh -c 'cat $(eval echo ~$SUDO_USER)/hosts >> /etc/hosts'
   

8. Transfer ownership of the files in /etc/certs/ and /var/lib/istio/envoy/ to the Istio proxy:

   $ sudo mkdir -p /etc/istio/proxy
   $ sudo chown -R istio-proxy /var/lib/istio /etc/certs /etc/istio/proxy /etc/istio/config /var/run/secrets /etc/certs/root-cert.pem
   

Start Istio within the virtual machine

1. Start the Istio agent:

   $ sudo systemctl start istio
   

Verify Istio Works Successfully

1. Check the log in /var/log/istio/istio.log. You should see entries similar to the following:

   $ 2020-08-21T01:32:17.748413Z info sds resource:default pushed key/cert pair to proxy
   $ 2020-08-21T01:32:20.270073Z info sds resource:ROOTCA new connection
   $ 2020-08-21T01:32:20.270142Z info sds Skipping waiting for gateway secret
   $ 2020-08-21T01:32:20.270279Z info cache adding watcher for file ./etc/certs/root-cert.pem
   $ 2020-08-21T01:32:20.270347Z info cache GenerateSecret from file ROOTCA
   $ 2020-08-21T01:32:20.270494Z info sds resource:ROOTCA pushed root cert to proxy
   $ 2020-08-21T01:32:20.270734Z info sds resource:default new connection
   $ 2020-08-21T01:32:20.270763Z info sds Skipping waiting for gateway secret
   $ 2020-08-21T01:32:20.695478Z info cache GenerateSecret default
   $ 2020-08-21T01:32:20.695595Z info sds resource:default pushed key/cert pair to proxy
   

2. Create a Namespace to deploy a Pod-based Service:

   $ kubectl create namespace sample
   $ kubectl label namespace sample istio-injection=enabled
   

3. Deploy the HelloWorld Service:

   Zip

   $ kubectl apply -n sample -f samples/helloworld/helloworld.yaml14
   

4. Send requests from your Virtual Machine to the Service:

   $ curl helloworld.sample.svc:5000/hello
   Hello version: v1, instance: helloworld-v1-578dd69f69-fxwwk

Next Steps

For more information about virtual machines:

• Debugging Virtual Machines¹⁵ to troubleshoot issues with virtual machines.
• Bookinfo with a Virtual Machine¹⁶ to set up an example deployment of virtual machines.

Uninstall

Stop Istio on the virtual machine:

$ sudo systemctl stop istio

Then, remove the Istio-sidecar package:

$ sudo dpkg -r istio-sidecar
$ dpkg -s istio-sidecar

$ sudo rpm -e istio-sidecar

To uninstall Istio, run the following command:

$ kubectl delete -n istio-system -f samples/multicluster/expose-istiod.yaml11
$ istioctl uninstall -y --purge

The control plane namespace (e.g., istio-system) is not removed by default. If no longer needed, use the following command to remove it:

$ kubectl delete namespace istio-system