mirror of https://github.com/istio/istio.io.git
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
This commit is contained in:
Steven Landow
GitHub
parent
27ef76cb91
commit
aaebf9798e
|
|
@ -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 <<EOF> ./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 <<EOF | kubectl -n <vm-namespace> apply -f -
|
||||
apiVersion: networking.istio.io/v1beta1
|
||||
|
|
|
|||
|
|
@ -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="<the name of the application this VM will run>"
|
||||
$ 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>"
|
||||
$ NETWORK=""
|
||||
$ CLUSTER="Kubernetes"
|
||||
{{< /text >}}
|
||||
|
||||
{{< tab name="Multi-Network" category-value="multiple" >}}
|
||||
|
||||
{{< /tab >}}
|
||||
|
||||
{{< text bash >}}
|
||||
$ VM_APP="<the name of the application this VM will run>"
|
||||
$ 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>"
|
||||
# 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 <<EOF > ./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 <<EOF > 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 <<EOF > 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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue