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.

Prepare the guide environment

  1. Set the environment variables "${ISTIO_DIR}", "${WORK_DIR}", your cluster name, and the service namespace. Ensure "${WORK_DIR}" is prefixed with "${HOME}" (e.g. WORK_DIR="${HOME}"/vmintegration).

    $ ISTIO_DIR="<the directory containing an unarchived version of Istio>"
    $ CLUSTER_NAME="<the name of your cluster>"
    $ SERVICE_NAMESPACE="<the name of your service namespace>"
    $ WORK_DIR="<a certificate working directory>"
    
  2. Create the "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}" working directories.

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

Create certificates for use with the virtual machine and Istio control plane

  1. Execute the following commands to create certificates for use by Istio. See Certificate Authority (CA) certificates 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}"/tools/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}"/ca-key.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
    apiVersion: install.istio.io/v1alpha1
    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
    

Create files to transfer to the virtual machine

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

    $ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/ca-cert.pem "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/
    $ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/key.pem "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/
    $ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/root-cert.pem "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/
    $ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/workload-cert-chain.pem "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/cert-chain.pem
    
  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. 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_NAME}"/"${SERVICE_NAMESPACE}"/cluster.env
    
  4. 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}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/hosts-addendum
    $ echo "${INGRESS_HOST} istiod.istio-system.svc" > "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/hosts-addendum
    

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.

    $ curl -LO https://storage.googleapis.com/istio-release/releases/1.6.8/deb/istio-sidecar.deb
    $ sudo dpkg -i istio-sidecar.deb
    
  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 sh -c '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
    

Uninstall

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
Was this information useful?
Do you have any suggestions for improvement?

Thanks for your feedback!