Virtual Machine Installation

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

This guide is tested and validated but note that VM support is still an alpha feature not recommended for production.

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.

Prepare the guide environment

  1. Create a virtual machine

  2. Set the environment variables VM_NAME, WORK_DIR , VM_NAMESPACE, and SERVICE_ACCOUNT (e.g., WORK_DIR="${HOME}/vmintegration"):

    $ VM_NAME="<the name of your vm instance you created>" $ 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>"

  3. Create the working directory:

    $ mkdir -p "${WORK_DIR}"

Install the Istio control plane

Install Istio with the installation setting values.global.meshExpansion.enabled: true.

  1. Create the IstioOperator custom resource:

    $ cat <<EOF> "${WORK_DIR}"/vmintegration.yaml apiVersion: install.istio.io/v1alpha1 kind: IstioOperator spec: values: global: meshExpansion: enabled: true EOF

  2. Install or upgrade Istio with virtual machine integration features enabled.

    $ istioctl install -f "${WORK_DIR}"/vmintegration.yaml

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

  1. Create a Kubernetes token. This example sets the token expire time to 1 hour:

    $ tokenexpiretime=3600 $ echo '{"kind":"TokenRequest","apiVersion":"authentication.k8s.io/v1","spec":{"audiences":["istio-ca"],"expirationSeconds":'$tokenexpiretime'}}' | kubectl create --raw /api/v1/namespaces/$VM_NAMESPACE/serviceaccounts/$SERVICE_ACCOUNT/token -f - | jq -j '.status.token' > "${WORK_DIR}"/istio-token

  2. Get the root certificate:

    $ kubectl -n "${VM_NAMESPACE}" get configmaps istio-ca-root-cert -o json | jq -j '."data"."root-cert.pem"' > "${WORK_DIR}"/root-cert

  3. Generate a cluster.env configuration file that informs the virtual machine deployment which network CIDR to capture and redirect to the Kubernetes cluster:

    $ ISTIO_SERVICE_CIDR=$(echo '{"apiVersion":"v1","kind":"Service","metadata":{"name":"tst"},"spec":{"clusterIP":"1.1.1.1","ports":[{"port":443}]}}' | kubectl apply -f - 2>&1 | sed 's/.*valid IPs is //') $ touch "${WORK_DIR}"/cluster.env $ echo ISTIO_SERVICE_CIDR=$ISTIO_SERVICE_CIDR > "${WORK_DIR}"/cluster.env

  4. Optionally configure configure a select set of ports for exposure from the virtual machine. If you do not apply this optional step, all outbound traffic on all ports is sent to the Kubernetes cluster. You may wish to send some traffic on specific ports to other destinations. This example shows enabling ports 3306 and 8080 for capture by Istio virtual machine integration and transmission to Kubernetes. All other ports are sent over the default gateway of the virtual machine.

    $ echo "ISTIO_INBOUND_PORTS=3306,8080" >> "${WORK_DIR}"/cluster.env

  5. Add an IP address that represents Istiod. Replace ${INGRESS_HOST} with the ingress gateway service of istiod. Revisit Determining the ingress host and ports to set the environment variable ${INGRESS_HOST}.

    $ touch "${WORK_DIR}"/hosts-addendum $ echo "${INGRESS_HOST} istiod.istio-system.svc" > "${WORK_DIR}"/hosts-addendum

    A sophisticated option involves configuring DNS within the virtual machine to reference an external DNS server. This option is beyond the scope of this guide.

  6. Create sidecar.env file to import the required environment variables:

    $ touch "${WORK_DIR}"/sidecar.env $ echo "PROV_CERT=/var/run/secrets/istio" >>"${WORK_DIR}"/sidecar.env $ echo "OUTPUT_CERTS=/var/run/secrets/istio" >> "${WORK_DIR}"/sidecar.env

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. Update the cache of package updates for your deb packaged distro.

    $ sudo apt -y update

  3. Upgrade the deb packaged distro to ensure all latest security packages are applied.

    $ sudo apt -y upgrade

  4. Install the root certificate at /var/run/secrets/istio:

    $ sudo mkdir -p /var/run/secrets/istio $ sudo cp "${HOME}"/root-cert.pem /var/run/secrets/istio/root-cert.pem

  5. 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

  6. Install the deb package containing the Istio virtual machine integration runtime:

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

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

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

  8. Install sidecar.env within the directory /var/lib/istio/envoy/:

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

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

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

  10. Install the root certificate in the directory /var/run/secrets/istio

    $ sudo cp "${HOME}"/root-cert.pem /var/run/secrets/istio/root-cert.pem

  11. 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 /var/run/secrets

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

Uninstall

Stop Istio on the virtual machine:

` ``` $ sudo systemctl stop istio

  2. Then, remove the Istio-sidecar package:
  4. `

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

To uninstall Istio, run the following command:

$ istioctl manifest generate -f "${WORK_DIR}"/vmintegration.yaml | kubectl delete -f -

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

See also

Virtual Machines in Multi-Network Meshes

Learn how to add a service running on a virtual machine to your multi-network Istio mesh.

Bookinfo with a Virtual Machine

Run the Bookinfo application with a MySQL service running on a virtual machine within your mesh.

Virtual Machines in Single-Network Meshes

Learn how to add a service running on a virtual machine to your single network Istio mesh.

DNS Certificate Management

Provision and manage DNS certificates in Istio.

Secure Webhook Management

A more secure way to manage Istio webhooks.

Demystifying Istio’s Sidecar Injection Model

De-mystify how Istio manages to plugin its data-plane components into an existing deployment.