From 55de1c8dec92d51e60f875fbfaf9cb9b2d35e2f7 Mon Sep 17 00:00:00 2001
From: Steven Landow <steven@stlcomputerservices.com>
Date: Thu, 12 Nov 2020 13:58:03 -0800
Subject: [PATCH] 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
---
 DOC_OWNERS.md                                 |   5 +-
 .../autoregistration/index.md                 | 164 ----------------
 .../virtual-machines/single-network/index.md  |   4 +
 .../setup/install/virtual-machine/index.md    | 176 +++++++++++-------
 4 files changed, 115 insertions(+), 234 deletions(-)
 delete mode 100644 content/en/docs/examples/virtual-machines/autoregistration/index.md

diff --git a/DOC_OWNERS.md b/DOC_OWNERS.md
index f72483c861..d91db8d8ed 100644
--- a/DOC_OWNERS.md
+++ b/DOC_OWNERS.md
@@ -1,7 +1,7 @@
 <!-- WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. UPDATE THE OWNER ATTRIBUTE IN THE DOCUMENT FILES, INSTEAD -->
 # Istio.io Document Owners
 
-There are 157 owned istio.io docs.
+There are 156 owned istio.io 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/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/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)
diff --git a/content/en/docs/examples/virtual-machines/autoregistration/index.md b/content/en/docs/examples/virtual-machines/autoregistration/index.md
deleted file mode 100644
index d0893d6f94..0000000000
--- a/content/en/docs/examples/virtual-machines/autoregistration/index.md
+++ /dev/null
@@ -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.
diff --git a/content/en/docs/examples/virtual-machines/single-network/index.md b/content/en/docs/examples/virtual-machines/single-network/index.md
index 1b989dc074..e1039db9f8 100644
--- a/content/en/docs/examples/virtual-machines/single-network/index.md
+++ b/content/en/docs/examples/virtual-machines/single-network/index.md
@@ -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:
 
+    {{< tip >}}
+    This step can be skipped if you followed the VM auto-registration steps during install.
+    {{< /tip >}}
+
     {{< text bash >}}
     $ cat <<EOF | kubectl -n <vm-namespace> 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 2cc9e69b05..47760bc6ed 100644
--- a/content/en/docs/setup/install/virtual-machine/index.md
+++ b/content/en/docs/setup/install/virtual-machine/index.md
@@ -27,12 +27,12 @@ This guide is tested and validated but note that VM support is still an alpha fe
 ## Prepare the guide environment
 
 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`
     (e.g., `WORK_DIR="${HOME}/vmintegration"`):
 
     {{< 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>"
     $ WORK_DIR="<a certificate working directory>"
     $ 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.
 
+    {{< tabset category-name="registration-mode" >}}
+
+    {{< tab name="Default" category-value="default" >}}
+
     {{< text bash >}}
     $ istioctl install
     {{< /text >}}
 
-    {{< tip >}}
-    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 >}}
+    {{< /tab >}}
 
-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 >}}
     $ 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
 
-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 >}}
-    $ tokenexpiretime=3600
-    $ 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
+    $ istioctl x workload group create --name "${VM_APP}" --namespace "${VM_NAMESPACE}" --labels app="${VM_APP}" --serviceAccount "${SERVICE_ACCOUNT}" > workloadgroup.yaml
     {{< /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 >}}
-    $ 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 >}}
 
-1. Generate a `cluster.env` configuration file that informs the virtual machine
-   deployment which network CIDR to capture and redirect to the Kubernetes
-   cluster:
+    1. Push the `WorkloadGroup` to the cluster:
 
     {{< 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 //')
-    $ touch "${WORK_DIR}"/cluster.env
-    $ echo ISTIO_SERVICE_CIDR=$ISTIO_SERVICE_CIDR > "${WORK_DIR}"/cluster.env
+    $ kubectl --namespace ${VM_NAMESPACE} apply -f workloadgroup.yaml`
     {{< /text >}}
 
-1. Optionally 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.
+    {{< /tab >}}
 
-    {{< text bash >}}
-    $ echo "ISTIO_INBOUND_PORTS=3306,8080" >> "${WORK_DIR}"/cluster.env
-    {{< /text >}}
+    {{< /tabset >}}
 
-1. Add an IP address that represents Istiod. Replace `${INGRESS_HOST}` with the
-    ingress gateway service of istiod. Revisit
-    [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}`.
-
-    {{< text bash >}}
-    $ touch "${WORK_DIR}"/hosts-addendum
-    $ echo "${INGRESS_HOST} istiod.istio-system.svc" > "${WORK_DIR}"/hosts-addendum
-    {{< /text >}}
+1. 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.
+       * `mesh.yaml`: Provides additional Istio metadata including, network name, trust domain and other values.
+       * `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.*
 
     {{< idea >}}
     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.
     {{< /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 >}}
-    $ touch "${WORK_DIR}"/sidecar.env
-    $ 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
+    $ istioctl x workload entry configure -f workloadgroup.yaml -o "${WORK_DIR}"
     {{< /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
 
 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
     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 >}}
-    $ sudo apt -y update
-    {{< /text >}}
-
-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
+    $ sudo mkdir -p /etc/certs
+    $ sudo cp "${HOME}"/root-cert.pem /etc/certs/root-cert.pem
     {{< /text >}}
 
 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
     {{< /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 >}}
     $ curl -LO https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/deb/istio-sidecar.deb
     $ sudo dpkg -i istio-sidecar.deb
     {{< /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/`:
 
     {{< text bash >}}
     $ sudo cp "${HOME}"/cluster.env /var/lib/istio/envoy/cluster.env
     {{< /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 >}}
-    $ sudo cp "${HOME}"/sidecar.env /var/lib/istio/envoy/sidecar.env
+    $ sudo cp "${HOME}"/mesh.yaml /etc/istio/config/mesh
     {{< /text >}}
 
 1. Add the istiod host to `/etc/hosts`:
 
     {{< 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 >}}
 
 1. Transfer ownership of the files in `/etc/certs/` and `/var/lib/istio/envoy/` to the Istio proxy:
 
     {{< text bash >}}
     $ 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 >}}
 
 ## 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:
 
-    {{< text bash >}}
-    $ sudo systemctl stop istio
-    {{< /text >}}
+{{< text bash >}}
+$ sudo systemctl stop istio
+{{< /text >}}
 
 Then, remove the Istio-sidecar package:
 
-    {{< text bash >}}
-    $ sudo dpkg -r istio-sidecar
-    $ dpkg -s istio-sidecar
-    {{< /text >}}
+{{< text bash >}}
+$ sudo dpkg -r istio-sidecar
+$ dpkg -s istio-sidecar
+{{< /text >}}
 
 To uninstall Istio, run the following command: