docs: break apart the ambient getting start guide (WIP) (istio#15168)

* break apart the ambient getting start guide Signed-off-by: Peter Jausovec <[email protected]> * wip Signed-off-by: Peter Jausovec <[email protected]> * wip Signed-off-by: Peter Jausovec <[email protected]> * fix linter issues Signed-off-by: Peter Jausovec <[email protected]> * wip Signed-off-by: Peter Jausovec <[email protected]> * add tests Signed-off-by: Peter Jausovec <[email protected]> * Craig's first edits * lint fixes * Fix tests * fix tests * test for istio#15200 workaround * fix tests (thanks Faseela for helping me get them running locally!) * Fix the snip generator? * remove Wasm test because it depends on snips we're moving around * rebase go.mod properly * remove spelling * new screenshots + pr fixes Signed-off-by: Peter Jausovec <[email protected]> * can't test locally so let's hope * lint fixes * make gen & fix test * fixy testy * Fix snip * fix tests as we learn more * Update content/en/docs/ambient/getting-started/secure-and-visualize/index.md Co-authored-by: Daniel Hawton <[email protected]> * fixing the wasm tests Signed-off-by: Peter Jausovec <[email protected]> --------- Signed-off-by: Peter Jausovec <[email protected]> Co-authored-by: Craig Box <[email protected]> Co-authored-by: Daniel Hawton <[email protected]>
verysonglaa · Jun 2, 2024 · 8b3072f · 8b3072f
1 parent f5aa03d
commit 8b3072f
Show file tree

Hide file tree

Showing 24 changed files with 820 additions and 670 deletions.
diff --git a/content/en/docs/ambient/getting-started/_index.md b/content/en/docs/ambient/getting-started/_index.md
@@ -0,0 +1,71 @@
+---
+title: Getting Started
+description: How to deploy and install Istio in ambient mode.
+weight: 2
+aliases:
+  - /docs/ops/ambient/getting-started
+  - /latest/docs/ops/ambient/getting-started
+owner: istio/wg-networking-maintainers
+skip_list: true
+test: yes
+---
+
+This guide lets you quickly evaluate Istio's {{< gloss "ambient" >}}ambient mode{{< /gloss >}}. You'll need a Kubernetes cluster to proceed. If you don't have a cluster, you can use [kind](/docs/setup/platform-setup/kind) or any other [supported Kubernetes platform](/docs/setup/platform-setup).
+
+These steps require you to have a {{< gloss >}}cluster{{< /gloss >}} running a
+[supported version](/docs/releases/supported-releases#support-status-of-istio-releases) of Kubernetes ({{< supported_kubernetes_versions >}}).
+
+## Download the Istio CLI
+
+Istio is configured using a command line tool called `istioctl`.  Download it, and the Istio sample applications:
+
+{{< text syntax=bash snip_id=none >}}
+$ curl -L https://istio.io/downloadIstio | sh -
+$ cd istio-{{< istio_full_version >}}
+$ export PATH=$PWD/bin:$PATH
+{{< /text >}}
+
+Check that you are able to run `istioctl` by printing the version of the command. At this point, Istio is not installed in your cluster, so you will see that there are no pods ready.
+
+{{< text syntax=bash snip_id=none >}}
+$ istioctl version
+no ready Istio pods in "istio-system"
+{{< istio_full_version >}}
+{{< /text >}}
+
+## Install Istio on to your cluster
+
+`istioctl` supports a number of [configuration profiles](/docs/setup/additional-setup/config-profiles/) that include different default options, and can be customized for your production needs. Support for ambient mode is included in the `ambient` profile. Install Istio with the following command:
+
+{{< text syntax=bash snip_id=install_ambient >}}
+$ istioctl install --set profile=ambient --skip-confirmation
+{{< /text >}}
+
+It might take a minute for the Istio components to be installed. Once the installation completes, you’ll get the following output that indicates all components have been installed successfully.
+
+{{< text syntax=plain snip_id=none >}}
+✔ Istio core installed
+✔ Istiod installed
+✔ CNI installed
+✔ Ztunnel installed
+✔ Installation complete
+{{< /text >}}
+
+{{< tip >}}
+You can verify the installed components using the command `istioctl verify-install`.
+{{< /tip >}}
+
+## Install the Kubernetes Gateway API CRDs
+
+You need to install the Kubernetes Gateway API CRDs, which don’t come installed by default on most Kubernetes clusters:
+
+{{< text syntax=bash snip_id=install_k8s_gateway_api >}}
+$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
+  { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.1.0" | kubectl apply -f -; }
+{{< /text >}}
+
+You will use the Kubernetes Gateway API to configure traffic routing.
+
+## Next steps
+
+Congratulations! You've successfully installed Istio with support for ambient mode. Continue to the next step to [install the demo application and add it to the ambient mesh](/docs/ambient/getting-started/deploy-sample-app/).
diff --git a/content/en/docs/ambient/getting-started/cleanup/index.md b/content/en/docs/ambient/getting-started/cleanup/index.md
@@ -0,0 +1,47 @@
+
+---
+title: Cleanup
+description: Delete Istio and associated resources.
+weight: 6
+owner: istio/wg-networking-maintainers
+test: yes
+---
+
+If you no longer need Istio and associated resources, you can delete them by following the steps in this section.
+
+## Remove the ambient and waypoint labels
+
+The label to instruct Istio to automatically include applications in the `default` namespace to an ambient mesh is not removed by default. If no longer needed, use the following command to remove it:
+
+{{< text bash >}}
+$ kubectl label namespace default istio.io/dataplane-mode-
+$ kubectl label namespace default istio.io/use-waypoint-
+{{< /text >}}
+
+## Remove waypoint proxies and uninstall Istio
+
+To remove waypoint proxies, installed policies, and uninstall Istio, run the following commands:
+
+{{< text bash >}}
+$ istioctl x waypoint delete --all
+$ istioctl uninstall -y --purge
+$ kubectl delete namespace istio-system
+{{< /text >}}
+
+## Remove the sample application
+
+To delete the Bookinfo sample application and the `sleep` deployment, run the following:
+
+{{< text bash >}}
+$ kubectl delete -f {{< github_file >}}/samples/bookinfo/platform/kube/bookinfo.yaml
+$ kubectl delete -f {{< github_file >}}/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+$ kubectl delete -f {{< github_file >}}/samples/sleep/sleep.yaml
+{{< /text >}}
+
+## Remove the Kubernetes Gateway API CRDs
+
+If you installed the Gateway API CRDs, remove them:
+
+{{< text bash >}}
+$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl delete -f -
+{{< /text >}}
diff --git a/content/en/docs/ambient/getting-started/cleanup/snips.sh b/content/en/docs/ambient/getting-started/cleanup/snips.sh
@@ -0,0 +1,42 @@
+#!/bin/bash
+# shellcheck disable=SC2034,SC2153,SC2155,SC2164
+
+# Copyright Istio Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+####################################################################################################
+# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
+#          docs/ambient/getting-started/cleanup/index.md
+####################################################################################################
+
+snip_remove_the_ambient_and_waypoint_labels_1() {
+kubectl label namespace default istio.io/dataplane-mode-
+kubectl label namespace default istio.io/use-waypoint-
+}
+
+snip_remove_waypoint_proxies_and_uninstall_istio_1() {
+istioctl x waypoint delete --all
+istioctl uninstall -y --purge
+kubectl delete namespace istio-system
+}
+
+snip_remove_the_sample_application_1() {
+kubectl delete -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo.yaml
+kubectl delete -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+kubectl delete -f https://raw.githubusercontent.com/istio/istio/master/samples/sleep/sleep.yaml
+}
+
+snip_remove_the_kubernetes_gateway_api_crds_1() {
+kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.1.0" | kubectl delete -f -
+}
diff --git a/content/en/docs/ambient/getting-started/deploy-sample-app/bookinfo-browser.png b/content/en/docs/ambient/getting-started/deploy-sample-app/bookinfo-browser.png
diff --git a/content/en/docs/ambient/getting-started/deploy-sample-app/bookinfo.svg b/content/en/docs/ambient/getting-started/deploy-sample-app/bookinfo.svg
diff --git a/content/en/docs/ambient/getting-started/deploy-sample-app/index.md b/content/en/docs/ambient/getting-started/deploy-sample-app/index.md
@@ -0,0 +1,77 @@
+---
+title: Deploy the application
+description: Deploy the Bookinfo sample application.
+weight: 2
+owner: istio/wg-networking-maintainers
+test: yes
+---
+
+To explore Istio, you will install the sample [Bookinfo application](/docs/examples/bookinfo/), composed of four separate microservices used to demonstrate various Istio features.
+
+{{< image width="50%" link="./bookinfo.svg" caption="Istio's Bookinfo sample application is written in many different languages" >}}
+
+As part of this guide, you'll deploy the Bookinfo application and expose the `productpage` service using an ingress gateway.
+
+## Deploy the Bookinfo application
+
+Start by deploying the application:
+
+{{< text bash >}}
+$ kubectl apply -f {{< github_file >}}/samples/bookinfo/platform/kube/bookinfo.yaml
+$ kubectl apply -f {{< github_file >}}/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+{{< /text >}}
+
+To verify that the application is running, check the status of the pods:
+
+{{< text syntax=bash snip_id=none >}}
+$ kubectl get pods
+NAME                             READY   STATUS    RESTARTS   AGE
+details-v1-cf74bb974-nw94k       1/1     Running   0          42s
+productpage-v1-87d54dd59-wl7qf   1/1     Running   0          42s
+ratings-v1-7c4bbf97db-rwkw5      1/1     Running   0          42s
+reviews-v1-5fd6d4f8f8-66j45      1/1     Running   0          42s
+reviews-v2-6f9b55c5db-6ts96      1/1     Running   0          42s
+reviews-v3-7d99fd7978-dm6mx      1/1     Running   0          42s
+{{< /text >}}
+
+To access the `productpage` service from outside the cluster, you need to configure an ingress gateway.
+
+## Deploy and configure the ingress gateway
+
+You will use the Kubernetes Gateway API to deploy a gateway called `bookinfo-gateway`:
+
+{{< text syntax=bash snip_id=deploy_bookinfo_gateway >}}
+$ kubectl apply -f {{< github_file >}}/samples/bookinfo/gateway-api/bookinfo-gateway.yaml
+{{< /text >}}
+
+By default, Istio creates a `LoadBalancer` service for a gateway. As we will access this gateway by a tunnel, we don't need a load balancer. Change the service type to `ClusterIP` by annotating the gateway:
+
+{{< text syntax=bash snip_id=annotate_bookinfo_gateway >}}
+$ kubectl annotate gateway bookinfo-gateway networking.istio.io/service-type=ClusterIP --namespace=default
+{{< /text >}}
+
+To check the status of the gateway, run:
+
+{{< text bash >}}
+$ kubectl get gateway
+NAME               CLASS   ADDRESS                                            PROGRAMMED   AGE
+bookinfo-gateway   istio   bookinfo-gateway-istio.default.svc.cluster.local   True         42s
+{{< /text >}}
+
+## Access the application
+
+You will connect to the Bookinfo `productpage` service through the gateway you just provisioned. To access the gateway, you need to use the `kubectl port-forward` command:
+
+{{< text syntax=bash snip_id=none >}}
+$ kubectl port-forward svc/bookinfo-gateway-istio 8080:80
+{{< /text >}}
+
+Open your browser and navigate to `http://localhost:8080/productpage` to view the Bookinfo application.
+
+{{< image width="80%" link="./bookinfo-browser.png" caption="Bookinfo Application" >}}
+
+If you refresh the page, you should see the book reviews and ratings changing as the requests are distributed across the different versions of the `reviews` service.
+
+## Next steps
+
+[Continue to the next section](../secure-and-visualize/) to add the application to the mesh, and learn how to secure and visualize the communication between the applications.
diff --git a/content/en/docs/ambient/getting-started/deploy-sample-app/snips.sh b/content/en/docs/ambient/getting-started/deploy-sample-app/snips.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+# shellcheck disable=SC2034,SC2153,SC2155,SC2164
+
+# Copyright Istio Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+####################################################################################################
+# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
+#          docs/ambient/getting-started/deploy-sample-app/index.md
+####################################################################################################
+
+snip_deploy_the_bookinfo_application_1() {
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo.yaml
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+}
+
+snip_deploy_bookinfo_gateway() {
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/gateway-api/bookinfo-gateway.yaml
+}
+
+snip_annotate_bookinfo_gateway() {
+kubectl annotate gateway bookinfo-gateway networking.istio.io/service-type=ClusterIP --namespace=default
+}
+
+snip_deploy_and_configure_the_ingress_gateway_3() {
+kubectl get gateway
+}
+
+! IFS=$'\n' read -r -d '' snip_deploy_and_configure_the_ingress_gateway_3_out <<\ENDSNIP
+NAME               CLASS   ADDRESS                                            PROGRAMMED   AGE
+bookinfo-gateway   istio   bookinfo-gateway-istio.default.svc.cluster.local   True         42s
+ENDSNIP