Small improvements to the ambient mode quickstart (#16007)

* Small improvements to the ambient mode quickstart

* catch a couple more "we" to "you"

* ...and then make the same change in the snips...

content/en/docs/ambient/getting-started/_index.md

@@ -29,8 +29,8 @@ Check that you are able to run `istioctl` by printing the version of the command
 
 {{< text syntax=bash snip_id=none >}}
 $ istioctl version
-no ready Istio pods in "istio-system"
-{{< istio_full_version >}}
+Istio is not present in the cluster: no running Istio pods in namespace "istio-system"
+client version: {{< istio_full_version >}}
 {{< /text >}}
 
 ## Install Istio on to your cluster
@@ -41,7 +41,7 @@ no ready Istio pods in "istio-system"
 $ 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.
+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
@@ -53,10 +53,10 @@ It might take a minute for the Istio components to be installed. Once the instal
 
 ## Install the Kubernetes Gateway API CRDs
 
-{{< boilerplate gateway-api-install-crds >}}
-
 You will use the Kubernetes Gateway API to configure traffic routing.
 
+{{< boilerplate gateway-api-install-crds >}}
+
 ## 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/).
+Congratulations! You've successfully installed Istio with support for ambient mode. Continue to the next step to [install a sample application](/docs/ambient/getting-started/deploy-sample-app/).

content/en/docs/ambient/getting-started/cleanup/index.md

@@ -1,5 +1,5 @@
 ---
-title: Cleanup
+title: Clean up
 description: Delete Istio and associated resources.
 weight: 6
 owner: istio/wg-networking-maintainers
@@ -8,21 +8,37 @@ 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
+## Remove waypoint proxies
 
-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:
+To remove all waypoint proxies run the following commands:
+
+{{< text bash >}}
+$ kubectl label namespace default istio.io/use-waypoint-
+$ istioctl waypoint delete --all
+{{< /text >}}
+
+## Remove the namespace from the ambient data plane
+
+The label that instructs Istio to automatically include applications in the `default` namespace to the ambient mesh is not removed when you remove Istio. 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
+You must remove workloads from the ambient data plane before uninstalling Istio.
 
-To remove waypoint proxies, installed policies, and uninstall Istio, run the following commands:
+## Remove the sample application
+
+To delete the Bookinfo sample application and the `curl` deployment, run the following:
 
 {{< text bash >}}
-$ istioctl waypoint delete --all
+$ kubectl delete httproute reviews
+$ kubectl delete authorizationpolicy productpage-viewer
+$ kubectl delete -f samples/curl/curl.yaml
+$ kubectl delete -f samples/bookinfo/platform/kube/bookinfo.yaml
+$ kubectl delete -f samples/bookinfo/platform/kube/bookinfo-versions.yaml
+$ kubectl delete -f samples/bookinfo/gateway-api/bookinfo-gateway.yaml
+
 {{< /text >}}
 
 ## Uninstall Istio
@@ -34,16 +50,6 @@ $ istioctl uninstall -y --purge
 $ kubectl delete namespace istio-system
 {{< /text >}}
 
-## Remove the sample application
-
-To delete the Bookinfo sample application and the `curl` deployment, run the following:
-
-{{< text bash >}}
-$ kubectl delete -f samples/bookinfo/platform/kube/bookinfo.yaml
-$ kubectl delete -f samples/bookinfo/platform/kube/bookinfo-versions.yaml
-$ kubectl delete -f samples/curl/curl.yaml
-{{< /text >}}
-
 ## Remove the Kubernetes Gateway API CRDs
 
 {{< boilerplate gateway-api-remove-crds >}}

content/en/docs/ambient/getting-started/cleanup/snips.sh

@@ -21,17 +21,24 @@
 ####################################################################################################
 source "content/en/boilerplates/snips/gateway-api-remove-crds.sh"
 
-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_1() {
+kubectl label namespace default istio.io/use-waypoint-
 istioctl waypoint delete --all
 }
 
+snip_remove_the_namespace_from_the_ambient_data_plane_1() {
+kubectl label namespace default istio.io/dataplane-mode-
+}
+
 snip_remove_the_sample_application_1() {
+kubectl delete httproute reviews
+kubectl delete authorizationpolicy productpage-viewer
+kubectl delete -f samples/curl/curl.yaml
 kubectl delete -f samples/bookinfo/platform/kube/bookinfo.yaml
 kubectl delete -f samples/bookinfo/platform/kube/bookinfo-versions.yaml
-kubectl delete -f samples/curl/curl.yaml
+kubectl delete -f samples/bookinfo/gateway-api/bookinfo-gateway.yaml
 }
+
+! IFS=$'\n' read -r -d '' snip_remove_the_sample_application_1_out <<\ENDSNIP
+
+ENDSNIP

content/en/docs/ambient/getting-started/deploy-sample-app/index.md

@@ -1,5 +1,5 @@
 ---
-title: Deploy the application
+title: Deploy a sample application
 description: Deploy the Bookinfo sample application.
 weight: 2
 owner: istio/wg-networking-maintainers
@@ -44,7 +44,7 @@ You will use the Kubernetes Gateway API to deploy a gateway called `bookinfo-gat
 $ 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:
+By default, Istio creates a `LoadBalancer` service for a gateway. As you will access this gateway by a tunnel, you 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
@@ -58,6 +58,8 @@ NAME               CLASS   ADDRESS                                            PR
 bookinfo-gateway   istio   bookinfo-gateway-istio.default.svc.cluster.local   True         42s
 {{< /text >}}
 
+Wait for the gateway to show as programmed before continuing.
+
 ## 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:
@@ -70,7 +72,7 @@ Open your browser and navigate to `http://localhost:8080/productpage` to view th
 
 {{< 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.
+If you refresh the page, you should see the display of the book ratings changing as the requests are distributed across the different versions of the `reviews` service.
 
 ## Next steps
 

content/en/docs/ambient/getting-started/enforce-auth-policies/index.md

@@ -13,7 +13,7 @@ identities that are automatically issued to all workloads in the mesh.
 
 ## Enforce Layer 4 authorization policy
 
-Let's create an [authorization policy](/docs/reference/config/security/authorization-policy/) that restricts which services can communicate with the `productpage` service. The policy is applied to pods with the `app: productpage` label, and it allows calls only from the the service account `cluster.local/ns/default/sa/bookinfo-gateway-istio`. (This is the service account that is used by the Bookinfo gateway you deployed in the previous step.)
+Let's create an [authorization policy](/docs/reference/config/security/authorization-policy/) that restricts which services can communicate with the `productpage` service. The policy is applied to pods with the `app: productpage` label, and it allows calls only from the the service account `cluster.local/ns/default/sa/bookinfo-gateway-istio`. This is the service account that is used by the Bookinfo gateway you deployed in the previous step.
 
 {{< text syntax=bash snip_id=deploy_l4_policy >}}
 $ kubectl apply -f - <<EOF
@@ -37,7 +37,7 @@ EOF
 
 If you open the Bookinfo application in your browser (`http://localhost:8080/productpage`), you will see the product page, just as before. However, if you try to access the `productpage` service from a different service account, you should see an error.
 
-Let's try accessing Bookinfo application from a `curl` pod:
+Let's try accessing Bookinfo application from a different client in the cluster:
 
 {{< text syntax=bash snip_id=deploy_curl >}}
 $ kubectl apply -f samples/curl/curl.yaml
@@ -94,7 +94,7 @@ spec:
 EOF
 {{< /text >}}
 
-Note the `targetRefs` field is used to specify the target service for the authorization policy of a waypoint proxy. The rules section is similar as before, but this time we added the `to` section to specify the operation that is allowed.
+Note the `targetRefs` field is used to specify the target service for the authorization policy of a waypoint proxy. The rules section is similar as before, but this time you added the `to` section to specify the operation that is allowed.
 
 {{< tip >}}
 To learn about how to enable more Istio's features, read the [Use Layer 7 features user guide](/docs/ambient/usage/l7-features/).
@@ -103,7 +103,7 @@ To learn about how to enable more Istio's features, read the [Use Layer 7 featur
 Confirm the new waypoint proxy is enforcing the updated authorization policy:
 
 {{< text bash >}}
-$ # This fails with an RBAC error because we're not using a GET operation
+$ # This fails with an RBAC error because you're not using a GET operation
 $ kubectl exec deploy/curl -- curl -s "http://productpage:9080/productpage" -X DELETE
 RBAC: access denied
 {{< /text >}}
@@ -115,11 +115,11 @@ RBAC: access denied
 {{< /text >}}
 
 {{< text bash >}}
-$ # This works as we're explicitly allowing GET requests from the curl pod
+$ # This works as you're explicitly allowing GET requests from the curl pod
 $ kubectl exec deploy/curl -- curl -s http://productpage:9080/productpage | grep -o "<title>.*</title>"
 <title>Simple Bookstore App</title>
 {{< /text >}}
 
 ## Next steps
 
-With the waypoint proxy in place, you can now enforce Layer 7 policies in the namespace. In addition to authorization policies, [we can use the waypoint proxy to split traffic between services](../manage-traffic/). This is useful when doing canary deployments or A/B testing.
+With the waypoint proxy in place, you can now enforce Layer 7 policies in the namespace. In addition to authorization policies, [you can use the waypoint proxy to split traffic between services](../manage-traffic/). This is useful when doing canary deployments or A/B testing.

content/en/docs/ambient/getting-started/enforce-auth-policies/snips.sh

@@ -95,7 +95,7 @@ EOF
 }
 
 snip_enforce_layer_7_authorization_policy_4() {
-# This fails with an RBAC error because we're not using a GET operation
+# This fails with an RBAC error because you're not using a GET operation
 kubectl exec deploy/curl -- curl -s "http://productpage:9080/productpage" -X DELETE
 }
 
@@ -113,7 +113,7 @@ RBAC: access denied
 ENDSNIP
 
 snip_enforce_layer_7_authorization_policy_6() {
-# This works as we're explicitly allowing GET requests from the curl pod
+# This works as you're explicitly allowing GET requests from the curl pod
 kubectl exec deploy/curl -- curl -s http://productpage:9080/productpage | grep -o "<title>.*</title>"
 }
 

content/en/docs/ambient/getting-started/manage-traffic/index.md

@@ -6,7 +6,7 @@ owner: istio/wg-networking-maintainers
 test: yes
 ---
 
-Now we have a waypoint proxy installed, we will learn how to split traffic between services.
+Now you have a waypoint proxy installed, you will learn how to split traffic between services.
 
 ## Split traffic between services
 
@@ -47,4 +47,4 @@ You'll notice the majority of requests go to `reviews-v1`. You can confirm the s
 
 ## Next steps
 
-This section concludes the Getting Started guide for ambient mode. You can continue to the [Cleanup](/docs/ambient/getting-started/cleanup) section to remove Istio or continue exploring the [ambient mode user guides](/docs/ambient/usage/) to learn more about Istio's features and capabilities.
+This section concludes the Getting Started guide for Istio's ambient mode. You can continue to the [Cleanup](/docs/ambient/getting-started/cleanup) section to remove Istio or continue exploring the [ambient mode user guides](/docs/ambient/usage/) to learn more about Istio's features and capabilities.

content/en/docs/ambient/getting-started/secure-and-visualize/index.md

@@ -43,10 +43,10 @@ $ istioctl dashboard kiali
 Let's send some traffic to the Bookinfo application, so Kiali generates the traffic graph:
 
 {{< text bash >}}
-$ for i in $(seq 1 100); do curl -s http://localhost:8080/productpage; done
+$ for i in $(seq 1 100); do curl -sSI -o /dev/null http://localhost:8080/productpage; done
 {{< /text >}}
 
-Next, click on the Traffic Graph and you should see the Bookinfo application:
+Next, click on the Traffic Graph and select "Default" from the "Select Namespaces" drop-down. You should see the Bookinfo application:
 
 {{< image link="./kiali-ambient-bookinfo.png" caption="Kiali dashboard" >}}
 
@@ -64,4 +64,4 @@ In addition to the TCP metrics, Istio has created a strong identity for each ser
 
 ## Next steps
 
-Now that we have identities assigned to the services, let's [enforce authorization policies](/docs/ambient/getting-started/enforce-auth-policies/) to secure access to the application.
+Now that you have identities assigned to the services, let's [enforce authorization policies](/docs/ambient/getting-started/enforce-auth-policies/) to secure access to the application.

content/en/docs/ambient/getting-started/secure-and-visualize/snips.sh

@@ -29,5 +29,5 @@ namespace/default labeled
 ENDSNIP
 
 snip_visualize_the_application_and_metrics_3() {
-for i in $(seq 1 100); do curl -s http://localhost:8080/productpage; done
+for i in $(seq 1 100); do curl -sSI -o /dev/null http://localhost:8080/productpage; done
 }

content/en/docs/ambient/getting-started/test.sh

@@ -63,8 +63,8 @@ _verify_lines snip_test_traffic_split "
 "
 
 # @cleanup
-snip_remove_the_ambient_and_waypoint_labels_1
 snip_remove_waypoint_proxies_1
+snip_remove_the_namespace_from_the_ambient_data_plane_1
 snip_remove_the_sample_application_1
 samples/bookinfo/platform/kube/cleanup.sh
 bpsnip_gateway_api_remove_crds_remove_crds