From aaebf9798e04a9966327285f6960d45d54ca8c29 Mon Sep 17 00:00:00 2001 From: Steven Landow Date: Fri, 8 Jan 2021 10:50:57 -0800 Subject: [PATCH] update virtual machine docs and fix multi-network doc (#8746) * undocument workload group command * multi-network changes * address comments * missing brace * trailing spaces * revert zh docs * fold multi-network instructions into main doc * include --clusterID flag * lint --- .../virtual-machines/multi-network/index.md | 99 +------------ .../setup/install/virtual-machine/index.md | 136 ++++++++++++++++-- 2 files changed, 128 insertions(+), 107 deletions(-) diff --git a/content/en/docs/examples/virtual-machines/multi-network/index.md b/content/en/docs/examples/virtual-machines/multi-network/index.md index 690234c87d..3c881ce1a6 100644 --- a/content/en/docs/examples/virtual-machines/multi-network/index.md +++ b/content/en/docs/examples/virtual-machines/multi-network/index.md @@ -24,100 +24,11 @@ bare metal and the clusters. - One or more Kubernetes clusters with versions: {{< supported_kubernetes_versions >}}. -- Virtual machines (VMs) must have IP connectivity to the Ingress gateways in the mesh. +- Virtual machines (VMs) must have IP connectivity to the east-west gateways in the mesh. -- Services in the cluster must be accessible through the Ingress gateway. +- Services in the cluster must be accessible through the east-west gateway. -## Installation steps - -Setup consists of preparing the mesh for expansion and installing and configuring each VM. - -### Preparing your environment - -When expanding Istio's mesh capabilities to VMs across multiple networks (where the VM is in a network where traffic cannot directly route to pods in the Kubernetes cluster, for example), we'll need to take advantage of Istio's split-horizon DNS capabilities. - -Before we get started, you should prepare a VM and connect it to the Istio control plane through the Ingress Gateway. These steps are detailed in [Setup: Install: Virtual Machine Installation](/docs/setup/install/virtual-machine/). - -**Note** There are a few alterations to that document as follows: - -{{< warning >}} -You must alter the VM set up instructions based on the suggestions in this section! -{{< /warning >}} - -1. When we create the `IstioOperator` resource, we need to specify which networks we expect, and how to treat them -1. When creating the `cluster.env` we need to specify which network in which the VM belongs -1. We need to create a `Gateway` resource to allow application traffic from the VM to the workload items running in the mesh - -### Installing the Istio Control Plane - -When following the [Virtual Machine Installation](/docs/setup/install/virtual-machine/) setup guide to install the control plane, we will need to tweak the installation as follows: - -1. Specify the expected networks in the mesh, including the `vm-network` - - {{< text bash yaml >}} - $ cat < ./vmintegration.yaml - apiVersion: install.istio.io/v1alpha1 - kind: IstioOperator - spec: - values: - global: - meshExpansion: - enabled: true - multiCluster: - clusterName: kube-cluster - network: main-network - meshNetworks: - main-network: - endpoints: - - fromRegistry: kube-cluster - gateways: - - registryServiceName: istio-ingressgateway.istio-system.svc.cluster.local - port: 443 - - EOF - {{< /text >}} - -1. Install with the virtual-machine features enabled: - - {{< text bash >}} - $ istioctl install -f ./vmintegration.yaml - {{< /text >}} - -### Specify the network for the VM sidecar - -When following the [Virtual Machine Installation](/docs/setup/install/virtual-machine/) setup guide for creating the `cluster.env` file we need to tweak the installation by adding the following entry: - - {{< text bash >}} - $ echo "ISTIO_META_NETWORK=vm-network" >> cluster.env - {{< /text >}} - -### Create Gateway for application traffic - -The last step is to create a `Gateway` resource that allows application traffic from the VMs to route correctly. - - {{< text yaml >}} - apiVersion: networking.istio.io/v1alpha3 - kind: Gateway - metadata: - name: cluster-aware-gateway - namespace: istio-system - spec: - selector: - istio: ingressgateway - servers: - - port: - number: 443 - name: tls - protocol: TLS - tls: - mode: AUTO_PASSTHROUGH - hosts: - - "*.local" - {{< /text >}} - -Applying this gateway will route any of the traffic from the VM destined for the workloads in the mesh running on `*.local` - -At this point, you can continue with the [Setup Virtual Machine documentation](/docs/setup/install/virtual-machine/). +- Installation must be completed using [virtual machine installation](/docs/setup/install/virtual-machine) instructions, following steps for Multi-Network. ## Verify setup @@ -183,6 +94,10 @@ At this point we should be able to send traffic to `httpbin.default.svc.cluster. Lastly create a workload with the external IP of the VM (substitute `VM_IP` with the IP of your VM): + {{< tip >}} + You can skip this step if using Automated WorkloadEntry Creation. + {{< /tip >}} + {{< text bash >}} $ cat < apply -f - apiVersion: networking.istio.io/v1beta1 diff --git a/content/en/docs/setup/install/virtual-machine/index.md b/content/en/docs/setup/install/virtual-machine/index.md index f11774e93f..59a00ec987 100644 --- a/content/en/docs/setup/install/virtual-machine/index.md +++ b/content/en/docs/setup/install/virtual-machine/index.md @@ -31,13 +31,37 @@ This guide is tested and validated but note that VM support is still an alpha fe and `SERVICE_ACCOUNT` (e.g., `WORK_DIR="${HOME}/vmintegration"`): + {{< tabset category-name="network-mode" >}} + + {{< tab name="Single-Network" category-value="single" >}} + {{< text bash >}} $ VM_APP="" $ VM_NAMESPACE="" $ WORK_DIR="" $ SERVICE_ACCOUNT="" + $ NETWORK="" + $ CLUSTER="Kubernetes" {{< /text >}} + {{< tab name="Multi-Network" category-value="multiple" >}} + + {{< /tab >}} + + {{< text bash >}} + $ VM_APP="" + $ VM_NAMESPACE="" + $ WORK_DIR="" + $ SERVICE_ACCOUNT="" + # Customize values for multi-cluster/multi-network as needed + $ NETWORK="kube-network" + $ CLUSTER="cluster1" + {{< /text >}} + + {{< /tab >}} + + {{< /tabset >}} + 1. Create the working directory: {{< text bash >}} @@ -48,6 +72,22 @@ and `SERVICE_ACCOUNT` Install Istio and expose the control plane so that your virtual machine can access it. +1. Create the `IstioOperator` spec for installation. + + {{< text bash yaml >}} + $ cat < ./vm-cluster.yaml + apiVersion: install.istio.io/v1alpha1 + kind: IstioOperator + spec: + values: + global: + meshID: mesh1 + multiCluster: + clusterName: "${CLUSTER}}" + network: "${NETWORK}" + EOF + {{< /text >}} + 1. Install Istio. {{< tabset category-name="registration-mode" >}} @@ -55,7 +95,7 @@ Install Istio and expose the control plane so that your virtual machine can acce {{< tab name="Default" category-value="default" >}} {{< text bash >}} - $ istioctl install + $ istioctl install -f vm-cluster.yaml {{< /text >}} {{< /tab >}} @@ -68,7 +108,7 @@ Install Istio and expose the control plane so that your virtual machine can acce {{< /warning >}} {{< text bash >}} - $ istioctl install --set values.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION=true + $ istioctl install -f vm-cluster.yaml --set values.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION=true {{< /text >}} {{< /tab >}} @@ -77,20 +117,65 @@ Install Istio and expose the control plane so that your virtual machine can acce 1. Deploy the east-west gateway: + {{< warning >}} + If the control-plane was installed with a revision, add the `--revision rev` flag to the `gen-eastwest-gateway.sh` command. + {{< /warning >}} + + {{< tabset category-name="network-mode" >}} + + {{< tab name="Single-Network" category-value="single" >}} + {{< text bash >}} $ @samples/multicluster/gen-eastwest-gateway.sh@ --single-cluster | istioctl install -y -f - {{< /text >}} -{{< warning >}} -If the control-plane was installed with a revision, add the `--revision rev` flag to the `gen-eastwest-gateway.sh` command. -{{< /warning >}} + {{< /tab >}} -1. Expose the control plane using the provided sample configuration: + {{< tab name="Multi-Network" category-value="multiple" >}} + + {{< text bash >}} + $ @samples/multicluster/gen-eastwest-gateway.sh@ \ + --mesh mesh1 --cluster "${CLUSTER}" --network "${NETWORK}" | \ + istioctl install -y -f - + {{< /text >}} + + {{< /tab >}} + + {{< /tabset >}} + +1. Expose services inside the cluster via the east-west gateway: + + {{< tabset category-name="network-mode" >}} + + {{< tab name="Single-Network" category-value="single" >}} + + Expose the control plane: {{< text bash >}} $ kubectl apply -f @samples/multicluster/expose-istiod.yaml@ {{< /text >}} + {{< /tab >}} + + {{< tab name="Multi-Network" category-value="multiple" >}} + + Expose the control plane: + + {{< text bash >}} + $ kubectl apply -f @samples/multicluster/expose-istiod.yaml@ + {{< /text >}} + + Expose cluster services: + + {{< text bash >}} + $ kubectl --context="${CTX_CLUSTER1}" apply -n istio-system -f \ + @samples/multicluster/expose-services.yaml@ + {{< /text >}} + + {{< /tab >}} + + {{< /tabset >}} + ## Configure the VM namespace 1. Create the namespace that will host the virtual machine: @@ -114,7 +199,20 @@ If the control-plane was installed with a revision, add the `--revision rev` fla {{< tab name="Default" category-value="default" >}} {{< text bash >}} - $ istioctl x workload group create --name "${VM_APP}" --namespace "${VM_NAMESPACE}" --labels app="${VM_APP}" --serviceAccount "${SERVICE_ACCOUNT}" > workloadgroup.yaml + $ cat < workloadgroup.yaml + apiVersion: networking.istio.io/v1alpha3 + kind: WorkloadGroup + metadata: + name: "${VM_APP}" + namespace: "${VM_NAMESPACE}" + spec: + metadata: + labels: + app: "${VM_APP}" + template: + serviceAccount: "${SERVICE_ACCOUNT}" + network: "${NETWORK}" + EOF {{< /text >}} {{< /tab >}} @@ -129,7 +227,20 @@ If the control-plane was installed with a revision, add the `--revision rev` fla 1. Generate the `WorkloadGroup`: {{< text bash >}} - $ istioctl x workload group create --name "${VM_APP}" --namespace "${VM_NAMESPACE}" --labels app="${VM_APP}" --serviceAccount "${SERVICE_ACCOUNT}" > workloadgroup.yaml + $ cat < workloadgroup.yaml + apiVersion: networking.istio.io/v1alpha3 + kind: WorkloadGroup + metadata: + name: "${VM_APP}" + namespace: "${VM_NAMESPACE}" + spec: + metadata: + labels: + app: "${VM_APP}" + template: + serviceAccount: "${SERVICE_ACCOUNT}" + network: "${NETWORK}" + EOF {{< /text >}} 1. Push the `WorkloadGroup` to the cluster: @@ -160,7 +271,7 @@ If the control-plane was installed with a revision, add the `--revision rev` fla {{< tab name="Default" category-value="default" >}} {{< text bash >}} - $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" + $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --clusterID "${CLUSTER}" {{< /text >}} {{< /tab >}} @@ -173,18 +284,13 @@ If the control-plane was installed with a revision, add the `--revision rev` fla {{< /warning >}} {{< text bash >}} - $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --autoregister + $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --clusterID "${CLUSTER}" --autoregister {{< /text >}} {{< /tab >}} {{< /tabset >}} - {{< warning >}} - When connecting a VM to a multicluster Istio mesh, you will need to add the `--clusterID` argument to - the above command. Set the value to the name of the cluster corresponding to the `istioctl` context. - {{< /warning >}} - ## Configure the virtual machine Run the following commands on the virtual machine you want to add to the Istio mesh: