istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

use istioctl x workload in vm installation doc (#8418) 

* use istioctl x workload command in vm installation doc

* final fixups

* move cert to etc/certs

* remove separate auto-register doc

* lint

* fix lint

* add -y

* use tabs

* backticks

* lint

* split expose item

* default wle cmd

* fix category names

* centos install

* the

* command doesn't generate sidecar.env

* env var list
This commit is contained in:
Steven Landow 2020-11-12 13:58:03 -08:00 committed by GitHub
parent 113c5c4c50
commit 55de1c8dec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 115 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
DOC_OWNERS.md
View File

@ -1,7 +1,7 @@
<!-- WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. UPDATE THE OWNER ATTRIBUTE IN THE DOCUMENT FILES, INSTEAD --> <!-- WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. UPDATE THE OWNER ATTRIBUTE IN THE DOCUMENT FILES, INSTEAD -->
# Istio.io Document Owners # Istio.io Document Owners
There are 157 owned istio.io docs. There are 156 owned istio.io docs.
## istio/wg-docs-maintainers: 15 docs ## istio/wg-docs-maintainers: 15 docs
@ -21,9 +21,8 @@ There are 157 owned istio.io docs.
- [docs/examples/microservices-istio/single/index.md](https://preliminary.istio.io/latest/docs/examples/microservices-istio/single) - [docs/examples/microservices-istio/single/index.md](https://preliminary.istio.io/latest/docs/examples/microservices-istio/single)
- [docs/reference/glossary/index.md](https://preliminary.istio.io/latest/docs/reference/glossary) - [docs/reference/glossary/index.md](https://preliminary.istio.io/latest/docs/reference/glossary)
## istio/wg-environments-maintainers: 47 docs ## istio/wg-environments-maintainers: 46 docs
- [docs/examples/virtual-machines/autoregistration/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/autoregistration)
- [docs/examples/virtual-machines/bookinfo/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/bookinfo) - [docs/examples/virtual-machines/bookinfo/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/bookinfo)
- [docs/examples/virtual-machines/multi-network/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/multi-network) - [docs/examples/virtual-machines/multi-network/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/multi-network)
- [docs/examples/virtual-machines/single-network/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/single-network) - [docs/examples/virtual-machines/single-network/index.md](https://preliminary.istio.io/latest/docs/examples/virtual-machines/single-network)

164
content/en/docs/examples/virtual-machines/autoregistration/index.md
View File

@ -1,164 +0,0 @@
---
title: Automated Workload Entry Creation [experimental]
description: Learn how to use the experimental automated VM registration feature.
Istio mesh.
weight: 70
keywords:
- kubernetes
- vms
- virtual-machines
owner: istio/wg-environments-maintainers
test: no
---
{{< warning >}}
This feature is actively in [development](https://github.com/istio/community/blob/master/FEATURE-LIFECYCLE.md) and is
considered `pre-alpha`.
{{< /warning >}}
Istio 1.8 introduces a new configuration resource, [Workload Group](/docs/reference/config/networking/workload-group/), that can be used to automate
the creation of [Workload Entries](/docs/reference/config/networking/workload-entry/).
This example shows how to use a `WorkloadGroup` to integrate a virtual machine, or a bare metal host into a
single network Istio mesh deployed on Kubernetes without manual `WorkloadEntry` creation. This approach requires L3 connectivity
between the virtual machine, and the Kubernetes cluster.
## Prerequisites
- One or more Kubernetes clusters with versions: {{< supported_kubernetes_versions >}}.
- Virtual machines must have L3 IP connectivity to the endpoints in the mesh.
This typically requires a VPC or a VPN, as well as a container network that
provides direct (without NAT or firewall deny) routing to the endpoints. The
machine is not required to have access to the cluster IP addresses assigned by
Kubernetes.
- Installation must be completed using [virtual machine installation](/docs/setup/install/virtual-machine) instructions.
## Prepare the guide environment
Set the environment variables `VM_NAMESPACE` and `SERVICE_ACCOUNT` (use the same values that you used during installation):
{{< text bash >}}
$ VM_NAMESPACE="<the name of your service namespace>"
$ SERVICE_ACCOUNT="<name of the Kubernetes service account you want to use for your VM>"
{{< /text >}}
### Running services on the virtual machine
1. Setup an HTTP server on the virtual machine to serve HTTP traffic on port 8080:
{{< text bash >}}
$ python -m SimpleHTTPServer 8080
{{< /text >}}
{{< warning >}}
You may have to open firewalls to be able to access the 8080 port on your virtual machine
{{< /warning >}}
1. Add an associated Service to the mesh:
{{< text bash >}}
$ cat <<EOF | kubectl -n "${VM_NAMESPACE}" apply -f -
apiVersion: v1
kind: Service
metadata:
name: auto-cloud-vm
labels:
app: auto-cloud-vm
spec:
ports:
- port: 8080
name: http
targetPort: 8080
selector:
app: auto-cloud-vm
EOF
{{< /text >}}
## Configure VM for Auto-Registration
1. Create the auto-registration group.
`WorkloadGroup` provides a template to automatically create a `WorkloadEntry` for each connected VM instance.
{{< text bash >}}
$ cat <<EOF | kubectl -n "${VM_NAMESPACE}" apply -f -
apiVersion: networking.istio.io/v1alpha3
kind: WorkloadGroup
metadata:
name: auto-cloud-vm
spec:
template:
serviceAccount: vm-sa
labels:
app: auto-cloud-vm
EOF
{{< /text >}}
1. The proxy must be provided with the name and namespace to find the `WorkloadGroup` on connection.
While logged on to the Virtual Machine:
{{< text bash >}}
$ sudo echo "ISTIO_NAMESPACE=${VM_NAMESPACE}" >> /var/lib/istio/envoy/sidecar.env
$ sudo echo "ISTIO_META_AUTO_REGISTER_GROUP=auto-cloud-vm" >> /var/lib/istio/envoy/sidecar.env
{{< /text >}}
1. Reconnect with new configuration.
{{< text bash >}}
$ sudo systemctl restart istio
{{< /text >}}
## Verify
1. If successful, a new `WorkloadEntry` should exist in your `${VM_NAMESPACE}`:
{{< text bash >}}
$ kubectl -n "${VM_NAMESPACE}" get workloadentry
NAME AGE ADDRESS
auto-cloud-vm-10.128.15.202 11s 10.128.15.202
{{< /text >}}
1. Deploy a pod running the `sleep` service in the Kubernetes cluster, and wait until it is ready:
{{< text bash >}}
$ kubectl apply -f @samples/sleep/sleep.yaml@
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
sleep-88ddbcfdd-rm42k 2/2 Running 0 1s
...
{{< /text >}}
1. Send a request from the `sleep` service on the pod to the virtual machine:
{{< text bash >}}
$ kubectl exec -it sleep-88ddbcfdd-rm42k -c sleep -- curl auto-cloud-vm.${VM_NAMESPACE}.svc.cluster.local:8080
{{< /text >}}
You will see output similar to this:
{{< text html >}}
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html>
<title>Directory listing for /</title>
<body>
<h2>Directory listing for /</h2>
<hr>
<ul>
<li><a href=".bashrc">.bashrc</a></li>
<li><a href=".ssh/">.ssh/</a></li>
...
</body>
{{< /text >}}
**Congratulations!** You successfully configured a service running in a pod within the cluster to
send traffic to a service running on a VM outside of the cluster and tested that
the configuration worked. Adding additional VMs will only require setting up the proxy, including configuring it with
the `WorkloadGroup` and Namespace.
## Cleanup
At this point, you can remove the virtual machine resources from the Kubernetes cluster in the `<vm-namespace>` namespace.
Removing the `WorkloadGroup` will not delete associated `WorkloadEntry` resources. Even without deleting the `WorkloadGroup`,
simply shutdown the `istio` service on the VM, or tear down the VM entirely. After a short grace period, the `WorkloadEntry` will be cleaned up
automatically.

4
content/en/docs/examples/virtual-machines/single-network/index.md
View File

@ -96,6 +96,10 @@ $ curl -v httpbin.default.svc.cluster.local:8000/headers
Create a `WorkloadEntry` with the external IP of the virtual machine. Substitute `VM_IP` with the IP of your virtual machine: Create a `WorkloadEntry` with the external IP of the virtual machine. Substitute `VM_IP` with the IP of your virtual machine:
{{< tip >}}
This step can be skipped if you followed the VM auto-registration steps during install.
{{< /tip >}}
{{< text bash >}} {{< text bash >}}
$ cat <<EOF | kubectl -n <vm-namespace> apply -f - $ cat <<EOF | kubectl -n <vm-namespace> apply -f -
apiVersion: networking.istio.io/v1beta1 apiVersion: networking.istio.io/v1beta1

176
content/en/docs/setup/install/virtual-machine/index.md
View File

@ -27,12 +27,12 @@ This guide is tested and validated but note that VM support is still an alpha fe
## Prepare the guide environment ## Prepare the guide environment
1. Create a virtual machine 1. Create a virtual machine
1. Set the environment variables `VM_NAME`, `WORK_DIR` , `VM_NAMESPACE`, 1. Set the environment variables `VM_APP`, `WORK_DIR` , `VM_NAMESPACE`,
and `SERVICE_ACCOUNT` and `SERVICE_ACCOUNT`
(e.g., `WORK_DIR="${HOME}/vmintegration"`): (e.g., `WORK_DIR="${HOME}/vmintegration"`):
{{< text bash >}} {{< text bash >}}
$ VM_NAME="<the name of your vm instance you created>" $ VM_APP="<the name of the application this VM will run>"
$ VM_NAMESPACE="<the name of your service namespace>" $ VM_NAMESPACE="<the name of your service namespace>"
$ WORK_DIR="<a certificate working directory>" $ WORK_DIR="<a certificate working directory>"
$ SERVICE_ACCOUNT="<name of the Kubernetes service account you want to use for your VM>" $ SERVICE_ACCOUNT="<name of the Kubernetes service account you want to use for your VM>"
@ -50,15 +50,38 @@ Install Istio and expose the control plane so that your virtual machine can acce
1. Install Istio. 1. Install Istio.
{{< tabset category-name="registration-mode" >}}
{{< tab name="Default" category-value="default" >}}
{{< text bash >}} {{< text bash >}}
$ istioctl install $ istioctl install
{{< /text >}} {{< /text >}}
{{< tip >}} {{< /tab >}}
To enable experimental [VM auto-registration](/docs/examples/virtual-machines/autoregistration): `istioctl install --set values.global.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION=true`.
{{< /tip >}}
1. Expose the control plane using the provided sample configuration. {{< tab name="Automated WorkloadEntry Creation" category-value="autoreg" >}}
{{< warning >}}
This feature is actively in [development](https://github.com/istio/community/blob/master/FEATURE-LIFECYCLE.md) and is
considered `pre-alpha`.
{{< /warning >}}
{{< text bash >}}
$ istioctl install --set values.global.pilot.env.PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION=true
{{< /text >}}
{{< /tab >}}
{{< /tabset >}}
1. Deploy the east-west gateway:
{{< text bash >}}
$ @samples/multicluster/gen-eastwest-gateway.sh@ --single-cluster | istioctl install -y -f -
{{< /text >}}
1. Expose the control plane using the provided sample configuration:
{{< text bash >}} {{< text bash >}}
$ kubectl apply -f @samples/multicluster/expose-istiod.yaml@ $ kubectl apply -f @samples/multicluster/expose-istiod.yaml@
@ -80,49 +103,47 @@ Install Istio and expose the control plane so that your virtual machine can acce
## Create files to transfer to the virtual machine ## Create files to transfer to the virtual machine
1. Create a Kubernetes token. This example sets the token expire time to 1 hour: 1. Create a template `WorkloadGroup` for the VM(s)
{{< tabset category-name="registration-mode" >}}
{{< tab name="Default" category-value="default" >}}
{{< text bash >}} {{< text bash >}}
$ tokenexpiretime=3600 $ istioctl x workload group create --name "${VM_APP}" --namespace "${VM_NAMESPACE}" --labels app="${VM_APP}" --serviceAccount "${SERVICE_ACCOUNT}" > workloadgroup.yaml
$ echo '{"kind":"TokenRequest","apiVersion":"authentication.k8s.io/v1","spec":{"audiences":["istio-ca"],"expirationSeconds":'$tokenexpiretime'}}' | kubectl create --raw /api/v1/namespaces/$VM_NAMESPACE/serviceaccounts/$SERVICE_ACCOUNT/token -f - | jq -j '.status.token' > "${WORK_DIR}"/istio-token
{{< /text >}} {{< /text >}}
1. Get the root certificate: {{< /tab >}}
{{< tab name="Automated WorkloadEntry Creation" category-value="autoreg" >}}
{{< warning >}}
This feature is actively in [development](https://github.com/istio/community/blob/master/FEATURE-LIFECYCLE.md) and is
considered `pre-alpha`.
{{< /warning >}}
1. Generate the `WorkloadGroup`:
{{< text bash >}} {{< text bash >}}
$ kubectl -n "${VM_NAMESPACE}" get configmaps istio-ca-root-cert -o json | jq -j '."data"."root-cert.pem"' > "${WORK_DIR}"/root-cert.pem $ istioctl x workload group create --name "${VM_APP}" --namespace "${VM_NAMESPACE}" --labels app="${VM_APP}" --serviceAccount "${SERVICE_ACCOUNT}" > workloadgroup.yaml
{{< /text >}} {{< /text >}}
1. Generate a `cluster.env` configuration file that informs the virtual machine 1. Push the `WorkloadGroup` to the cluster:
deployment which network CIDR to capture and redirect to the Kubernetes
cluster:
{{< text bash >}} {{< text bash >}}
$ 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 //') $ kubectl --namespace ${VM_NAMESPACE} apply -f workloadgroup.yaml`
$ touch "${WORK_DIR}"/cluster.env
$ echo ISTIO_SERVICE_CIDR=$ISTIO_SERVICE_CIDR > "${WORK_DIR}"/cluster.env
{{< /text >}} {{< /text >}}
1. Optionally configure a select set of ports for exposure from the {{< /tab >}}
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.
{{< text bash >}} {{< /tabset >}}
$ echo "ISTIO_INBOUND_PORTS=3306,8080" >> "${WORK_DIR}"/cluster.env
{{< /text >}}
1. Add an IP address that represents Istiod. Replace `${INGRESS_HOST}` with the 1. Use the `istioctl x workload entry` command to generate:
ingress gateway service of istiod. Revisit * `cluster.env`: Contains metadata that identifies what namespace, service account, network CIDR and (optionally) what inbound ports to capture.
[Determining the ingress host and ports](/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) to set the environment variable `${INGRESS_HOST}`. * `istio-token`: A Kubernetes token used to get certs from the CA.
* `mesh.yaml`: Provides additional Istio metadata including, network name, trust domain and other values.
{{< text bash >}} * `root-cert.pem`: The root certificate used to authenticate.
$ touch "${WORK_DIR}"/hosts-addendum * `hosts`: An addendum to `/etc/hosts` that the proxy will use to reach istiod for xDS.*
$ echo "${INGRESS_HOST} istiod.istio-system.svc" > "${WORK_DIR}"/hosts-addendum
{{< /text >}}
{{< idea >}} {{< idea >}}
A sophisticated option involves configuring DNS within the virtual A sophisticated option involves configuring DNS within the virtual
@ -130,15 +151,31 @@ Install Istio and expose the control plane so that your virtual machine can acce
the scope of this guide. the scope of this guide.
{{< /idea >}} {{< /idea >}}
1. Create `sidecar.env` file to import the required environment variables: {{< tabset category-name="registration-mode" >}}
{{< tab name="Default" category-value="default" >}}
{{< text bash >}} {{< text bash >}}
$ touch "${WORK_DIR}"/sidecar.env $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}"
$ echo "PROV_CERT=/var/run/secrets/istio" >>"${WORK_DIR}"/sidecar.env
$ echo "OUTPUT_CERTS=/var/run/secrets/istio" >> "${WORK_DIR}"/sidecar.env
$ echo "ISTIO_NAMESPACE=${VM_NAMESPACE}" >> "${WORK_DIR}"/sidecar.env
{{< /text >}} {{< /text >}}
{{< /tab >}}
{{< tab name="Automated WorkloadEntry Creation" category-value="autoreg" >}}
{{< warning >}}
This feature is actively in [development](https://github.com/istio/community/blob/master/FEATURE-LIFECYCLE.md) and is
considered `pre-alpha`.
{{< /warning >}}
{{< text bash >}}
$ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}" --autoregister
{{< /text >}}
{{< /tab >}}
{{< /tabset >}}
## Configure the virtual machine ## Configure the virtual machine
Run the following commands on the virtual machine you want to add to the Istio mesh: Run the following commands on the virtual machine you want to add to the Istio mesh:
@ -147,23 +184,11 @@ Run the following commands on the virtual machine you want to add to the Istio m
to the virtual machine. How you choose to securely transfer those files should be done with consideration for 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. your information security policies. For convenience in this guide, transfer all of the required files to `"${HOME}"` in the virtual machine.
1. Update the cache of package updates for your `deb` packaged distro. 1. Install the root certificate at `/etc/certs`:
{{< text bash >}} {{< text bash >}}
$ sudo apt -y update $ sudo mkdir -p /etc/certs
{{< /text >}} $ sudo cp "${HOME}"/root-cert.pem /etc/certs/root-cert.pem
1. Upgrade the `deb` packaged distro to ensure all latest security packages are applied.
{{< text bash >}}
$ sudo apt -y upgrade
{{< /text >}}
1. Install the root certificate at `/var/run/secrets/istio`:
{{< text bash >}}
$ sudo mkdir -p /var/run/secrets/istio
$ sudo cp "${HOME}"/root-cert.pem /var/run/secrets/istio/root-cert.pem
{{< /text >}} {{< /text >}}
1. Install the token at `/var/run/secrets/tokens`: 1. Install the token at `/var/run/secrets/tokens`:
@ -173,36 +198,53 @@ Run the following commands on the virtual machine you want to add to the Istio m
$ sudo cp "${HOME}"/istio-token /var/run/secrets/tokens/istio-token $ sudo cp "${HOME}"/istio-token /var/run/secrets/tokens/istio-token
{{< /text >}} {{< /text >}}
1. Install the `deb` package containing the Istio virtual machine integration runtime: 1. Install the package containing the Istio virtual machine integration runtime:
{{< tabset category-name="vm-os" >}}
{{< tab name="Debian" category-value="debian" >}}
{{< text bash >}} {{< text bash >}}
$ curl -LO https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/deb/istio-sidecar.deb $ curl -LO https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/deb/istio-sidecar.deb
$ sudo dpkg -i istio-sidecar.deb $ sudo dpkg -i istio-sidecar.deb
{{< /text >}} {{< /text >}}
{{< /tab >}}
{{< tab name="CentOS" category-value="centos" >}}
{{< text bash >}}
$ curl -LO https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/rpm/istio-sidecar.rpm
$ sudo rpm -i istio-sidecar.deb
{{< /text >}}
{{< /tab >}}
{{< /tabset >}}
1. Install `cluster.env` within the directory `/var/lib/istio/envoy/`: 1. Install `cluster.env` within the directory `/var/lib/istio/envoy/`:
{{< text bash >}} {{< text bash >}}
$ sudo cp "${HOME}"/cluster.env /var/lib/istio/envoy/cluster.env $ sudo cp "${HOME}"/cluster.env /var/lib/istio/envoy/cluster.env
{{< /text >}} {{< /text >}}
1. Install `sidecar.env` within the directory `/var/lib/istio/envoy/`: 1. Install the [Mesh Config](/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) to `/etc/istio/config/mesh`:
{{< text bash >}} {{< text bash >}}
$ sudo cp "${HOME}"/sidecar.env /var/lib/istio/envoy/sidecar.env $ sudo cp "${HOME}"/mesh.yaml /etc/istio/config/mesh
{{< /text >}} {{< /text >}}
1. Add the istiod host to `/etc/hosts`: 1. Add the istiod host to `/etc/hosts`:
{{< text bash >}} {{< text bash >}}
$ sudo sh -c 'cat $(eval echo ~$SUDO_USER)/hosts-addendum >> /etc/hosts' $ sudo sh -c 'cat $(eval echo ~$SUDO_USER)/hosts >> /etc/hosts'
{{< /text >}} {{< /text >}}
1. Transfer ownership of the files in `/etc/certs/` and `/var/lib/istio/envoy/` to the Istio proxy: 1. Transfer ownership of the files in `/etc/certs/` and `/var/lib/istio/envoy/` to the Istio proxy:
{{< text bash >}} {{< text bash >}}
$ sudo mkdir -p /etc/istio/proxy $ sudo mkdir -p /etc/istio/proxy
$ sudo chown -R istio-proxy /var/lib/istio /etc/certs /etc/istio/proxy /var/run/secrets $ sudo chown -R istio-proxy /var/lib/istio /etc/certs /etc/istio/proxy /etc/istio/config /var/run/secrets /etc/certs/root-cert.pem
{{< /text >}} {{< /text >}}
## Start Istio within the virtual machine ## Start Istio within the virtual machine
@ -234,16 +276,16 @@ Run the following commands on the virtual machine you want to add to the Istio m
Stop Istio on the virtual machine: Stop Istio on the virtual machine:
{{< text bash >}} {{< text bash >}}
$ sudo systemctl stop istio $ sudo systemctl stop istio
{{< /text >}} {{< /text >}}
Then, remove the Istio-sidecar package: Then, remove the Istio-sidecar package:
{{< text bash >}} {{< text bash >}}
$ sudo dpkg -r istio-sidecar $ sudo dpkg -r istio-sidecar
$ dpkg -s istio-sidecar $ dpkg -s istio-sidecar
{{< /text >}} {{< /text >}}
To uninstall Istio, run the following command: To uninstall Istio, run the following command: