Virtual Machine Installation

This guide has a requirement that the user is using a plugin root CA and has configured Istio as an intermediate CA.

This guide is tested and validated. The Istio authors feel this guide is suitable for experimentation but not production. Like all alpha features, this guide is subject to change.

2. Perform any necessary platform-specific setup
3. Check the requirements
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. Set the environment variables , "${WORK_DIR}", your cluster name, and the service namespace. Ensure "${WORK_DIR}" is prefixed with "${HOME}" (e.g. WORK_DIR="${HOME}"/vmintegration).

2. Create the "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}" working directories.

   $ mkdir -p "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"

This Makefile is limited to creating one virtual machine certificate per cluster. The Istio authors expect operators to read and understand this guide to formulate their own plans for creating and managing virtual machines. It is important for you to read and understand this Makefile for any deployment you place into production.

1. Execute the following commands to create certificates for use by Istio. See for more details on configuring an external CA. The NAME variable is used during certificate generation to uniquely identify clusters. The NAMESPACE variable identifies the namespace where the virtual machine connectivity is hosted.

   $ cd "${WORK_DIR}"
   $ make -f "${ISTIO_DIR}"/samples/certs/Makefile NAME="${CLUSTER_NAME}" NAMESPACE="${SERVICE_NAMESPACE}" "${CLUSTER_NAME}"-certs-wl

Install the Istio control plane

The Istio control plane must be installed with virtual machine integration enabled (values.global.meshExpansion.enabled: true).

1. Register the certificates needed for installation.

   $ kubectl create namespace istio-system
   $ kubectl create secret generic cacerts -n istio-system \
       --from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/ca-cert.pem \
       --from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/root-cert.pem \
       --from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/cert-chain.pem

2. Create the install IstioOperator custom resource:

   $ cat <<EOF> "${WORK_DIR}"/vmintegration.yaml
   metadata:
     namespace: istio-system
     name: example-istiocontrolplane
   kind: IstioOperator
   spec:
     values:
       global:
         meshExpansion:
           enabled: true
   EOF

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

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

1. Make a copy of files to copy to the virtual machine

2. 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_NAME}"/"${SERVICE_NAMESPACE}"/cluster.env
   $ echo ISTIO_SERVICE_CIDR=$ISTIO_SERVICE_CIDR > "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/cluster.env

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

   $ touch "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/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.

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}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}" to the virtual machine. How you choose to securely transfer those files should be done with consideration for your information security policies.

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 deb package containing the Istio virtual machine integration runtime.

5. Install root-cert.pem, key.pem and cert-chain.pem within the directory /etc/certs/.

   $ sudo mkdir -p /etc/certs
   $ sudo cp {root-cert.pem,cert-chain.pem,key.pem} /etc/certs

6. Install cluster.env within /var/lib/istio/envoy/.

   $ sudo cp cluster.env /var/lib/istio/envoy

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

   $ sudo cat hosts-addendum >> /etc/hosts

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

   $ sudo chown -R istio-proxy /etc/certs /var/lib/istio/envoy

9. Start Istio within the virtual machine.

   $ sudo systemctl start istio

The control plane namespace (e.g., ) 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.

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.

Provision and manage DNS certificates in Istio.

Secure Webhook Management

A more secure way to manage Istio webhooks.