Virtual Machine Installation

    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.
    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 , WORK_DIR , VM_NAMESPACE, and SERVICE_ACCOUNT on your machine that you’re using to setup the cluster. (e.g., WORK_DIR="${HOME}/vmintegration"):

      1. $ VM_APP="<the name of the application this VM will run>"
      2. $ VM_NAMESPACE="<the name of your service namespace>"
      3. $ WORK_DIR="<a certificate working directory>"
      4. $ SERVICE_ACCOUNT="<name of the Kubernetes service account you want to use for your VM>"
      5. $ # Customize values for multi-cluster/multi-network as needed
      6. $ CLUSTER_NETWORK="kube-network"
      7. $ VM_NETWORK="vm-network"
      8. $ CLUSTER="cluster1"

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

      1. $ 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.

      1. $ cat <<EOF > ./vm-cluster.yaml
      2. apiVersion: install.istio.io/v1alpha1
      3. kind: IstioOperator
      4. metadata:
      5.   name: istio
      6. spec:
      7.   values:
      8.     global:
      9.       meshID: mesh1
      10.       multiCluster:
      11.         clusterName: "${CLUSTER}"
      12.       network: "${CLUSTER_NETWORK}"
      13. EOF

    2. Install Istio.

      1. $ istioctl install -f vm-cluster.yaml

      This feature is actively in development and is considered .

      1. $ istioctl install -f vm-cluster.yaml --set values.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION=true --set values.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_HEALTHCHECKS=true

    3. Deploy the east-west gateway:

      If the control-plane was installed with a revision, add the --revision rev flag to the gen-eastwest-gateway.sh command.

      Zip

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

      1. $ @samples/multicluster/gen-eastwest-gateway.sh@ \
      2. --mesh mesh1 --cluster "${CLUSTER}" --network "${CLUSTER_NETWORK}" | \
      3. istioctl install -y -f -

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

      Expose the control plane:

      Zip

      1. $ kubectl apply -n istio-system -f @samples/multicluster/expose-istiod.yaml@

      Expose the control plane:

      1. $ kubectl apply -n istio-system -f @samples/multicluster/expose-istiod.yaml@

      Expose cluster services:

      1. $ kubectl apply -n istio-system -f @samples/multicluster/expose-services.yaml@

    1. Create a serviceaccount for the virtual machine:

    Create files to transfer to the virtual machine

    First, create a template WorkloadGroup for the VM(s):

    1. $ cat <<EOF > workloadgroup.yaml
    2. apiVersion: networking.istio.io/v1alpha3
    3. kind: WorkloadGroup
    4. metadata:
    5.   name: "${VM_APP}"
    6.   namespace: "${VM_NAMESPACE}"
    7. spec:
    8.   metadata:
    9.     labels:
    10.       app: "${VM_APP}"
    11.   template:
    13.     network: "${VM_NETWORK}"
    14. EOF

    First, create a template WorkloadGroup for the VM(s):

    This feature is actively in development and is considered experimental.

    1. $ cat <<EOF > workloadgroup.yaml
    2. apiVersion: networking.istio.io/v1alpha3
    3. kind: WorkloadGroup
    4. metadata:
    5.   name: "${VM_APP}"
    6.   namespace: "${VM_NAMESPACE}"
    7. spec:
    8.   metadata:
    9.     labels:
    10.       app: "${VM_APP}"
    11.   template:
    12.     serviceAccount: "${SERVICE_ACCOUNT}"
    13.     network: "${VM_NETWORK}"
    14. EOF

    Then, to allow automated WorkloadEntry creation, push the WorkloadGroup to the cluster:

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

    Using the Automated WorkloadEntry Creation feature, application health checks are also available. These share the same API and behavior as .

    For example, to configure a probe on the /ready endpoint of your application:

    1. $ cat <<EOF > workloadgroup.yaml
    2. apiVersion: networking.istio.io/v1alpha3
    3. kind: WorkloadGroup
    4. metadata:
    5.   name: "${VM_APP}"
    6.   namespace: "${VM_NAMESPACE}"
    7. spec:
    8.   metadata:
    9.     labels:
    10.       app: "${VM_APP}"
    11.   template:
    12.     serviceAccount: "${SERVICE_ACCOUNT}"
    13.     network: "${NETWORK}"
    14.   probe:
    15.     periodSeconds: 5
    16.     initialDelaySeconds: 1
    17.     httpGet:
    18.       port: 8080
    19.       path: /ready
    20. EOF

    With this configuration, the automatically generated WorkloadEntry will not be marked “Ready” until the probe succeeds.

    Before proceeding to generate the istio-token, as part of istioctl x workload entry, you should verify third party tokens are enabled in your cluster by following the steps describe here. If third party tokens are not enabled, you should add the option --set values.global.jwtPolicy=first-party-jwt to the Istio install commands.

    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.
    • 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.*

    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.

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

    This feature is actively in development and is considered .

    1. $ 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:

      1. $ sudo mkdir -p /etc/certs
      2. $ sudo cp "${HOME}"/root-cert.pem /etc/certs/root-cert.pem
      1. $ sudo  mkdir -p /var/run/secrets/tokens
      2. $ sudo cp "${HOME}"/istio-token /var/run/secrets/tokens/istio-token

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

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

      Note: only CentOS 8 is currently supported.

      1. $ curl -LO https://storage.googleapis.com/istio-release/releases/1.10.0/rpm/istio-sidecar.rpm
      2. $ sudo rpm -i istio-sidecar.rpm

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

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

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

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

      1. $ 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:

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

    1. Start the Istio agent:

      1. $ 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:

      1. $ 2020-08-21T01:32:17.748413Z info sds resource:default pushed key/cert pair to proxy
      2. $ 2020-08-21T01:32:20.270073Z info sds resource:ROOTCA new connection
      3. $ 2020-08-21T01:32:20.270142Z info sds Skipping waiting for gateway secret
      4. $ 2020-08-21T01:32:20.270279Z info cache adding watcher for file ./etc/certs/root-cert.pem
      5. $ 2020-08-21T01:32:20.270347Z info cache GenerateSecret from file ROOTCA
      6. $ 2020-08-21T01:32:20.270494Z info sds resource:ROOTCA pushed root cert to proxy
      7. $ 2020-08-21T01:32:20.270734Z info sds resource:default new connection
      8. $ 2020-08-21T01:32:20.270763Z info sds Skipping waiting for gateway secret
      9. $ 2020-08-21T01:32:20.695478Z info cache GenerateSecret default
      10. $ 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:

      1. $ kubectl create namespace sample
      2. $ kubectl label namespace sample istio-injection=enabled

    3. Deploy the HelloWorld Service:

      1. $ kubectl apply -n sample -f @samples/helloworld/helloworld.yaml@

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

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

    Next Steps

    For more information about virtual machines:

    Stop Istio on the virtual machine:

    1. $ sudo systemctl stop istio

    Then, remove the Istio-sidecar package:

    1. $ sudo dpkg -r istio-sidecar
    2. $ dpkg -s istio-sidecar
    1. $ sudo rpm -e istio-sidecar

    To uninstall Istio, run the following command:

    Zip

    1. $ kubectl delete -n istio-system -f @samples/multicluster/expose-istiod.yaml@
    2. $ istioctl manifest generate | kubectl delete -f -