Skip to content

Docs for bookinfo-ambient #16500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Docs for bookinfo-ambient #16500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 107 additions & 4 deletions content/en/docs/examples/bookinfo/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,12 @@ in the [installation guide](/docs/setup/).

To run the sample with Istio requires no changes to the
application itself. Instead, you simply need to configure and run the services in an
Istio-enabled environment, with Envoy sidecars injected along side each service.
The resulting deployment will look like this:
Istio-enabled environment.
{{< tabset category-name="dataplane-mode" >}}

{{< tab name="Sidecar Mode" category-value="sidecar-mode" >}}

In Sidecar mode, Envoy sidecars are injected along side each workload, and the resulting deployment will look like this:

{{< image width="80%" link="./withistio.svg" caption="Bookinfo Application" >}}

Expand All @@ -67,29 +71,88 @@ and outgoing calls for the services, providing the hooks needed to externally co
via the Istio control plane, routing, telemetry collection, and policy enforcement
for the application as a whole.

{{< /tab >}}

{{< tab name="Ambient Mode" category-value="ambient-mode" >}}

In Ambient mode, ztunnel proxies are deployed on each node.
We can also put Waypoint proxies in front of each service
The resulting deployment will look like this:

FIXMEFIXMEFIXME ADD IMAGE

All of the microservices incoming and outgoing traffic will be intercepted by the ztunnel proxies,
providing the hooks needed to externally control, L4 routing, telemetry collection, and policy enforcement

Further, the ztunnel proxy will forward the traffic to a Waypoint proxy,
which provide the hooks needed to externally control, L7 routing, telemetry collection, and policy enforcement.

{{< /tab >}}

{{< /tabset >}}

### Start the application services

{{< tip >}}
If you use GKE, please ensure your cluster has at least 4 standard GKE nodes. If you use Minikube, please ensure you have at least 4GB RAM.
If you using a cloud provider, please ensure your cluster has at least 4 nodes, each with 4GB of memory and 4 CPUS.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you using a cloud provider, please ensure your cluster has at least 4 nodes, each with 4GB of memory and 4 CPUS.
If you using a cloud provider, please ensure your cluster has at least 4 nodes, each with at least 4GB of memory and 4 CPUS.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"CPUs".

TBH this is really high for an app that does ~nothing. Is this still a relevant recommendation, and is it to do with reservations?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Honestly, I just threw a number out there that I thought would be around that of a "Standard GKE Node". Open to suggestions

If you use Minikube, please ensure you have at least 4GB RAM.
{{< /tip >}}

1. Change directory to the root of the Istio installation.

1. The default Istio installation uses [automatic sidecar injection](/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection).
1. Label your default namespace to enable Istio.

{{< tabset category-name="dataplane-mode" >}}

{{< tab name="Sidecar Mode" category-value="sidecar-mode" >}}

The default Istio installation uses [automatic sidecar injection](/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection).
Label the namespace that will host the application with `istio-injection=enabled`:

{{< text bash >}}
$ kubectl label namespace default istio-injection=enabled
{{< /text >}}

{{< /tab >}}

{{< tab name="Ambient Mode" category-value="ambient-mode" >}}

Label the namespace that will host the application with `istio.io/dataplane-mode=ambient` to automatically redirect traffic from your applications to ztunnel proxies:

{{< text bash >}}
$ kubectl label namespace default istio.io/dataplane-mode=ambient
{{< /text >}}

{{< /tab >}}

{{< /tabset >}}

1. Deploy your application using the `kubectl` command:


{{< tabset category-name="dataplane-mode" >}}

{{< tab name="Sidecar Mode" category-value="sidecar-mode" >}}

{{< text bash >}}
$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@
{{< /text >}}

The command launches all four services shown in the `bookinfo` application architecture diagram.
All 3 versions of the reviews service, v1, v2, and v3, are started.
{{< /tab >}}

{{< tab name="Ambient Mode" category-value="ambient-mode" >}}

{{< text bash >}}
$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo-waypoints.yaml@
{{< /text >}}

The command launches all four services shown in the `bookinfo` application architecture diagram, as well as a Waypoint proxy for each service.
All 3 versions of the reviews service, v1, v2, and v3, are started.
{{< /tab >}}

{{< /tabset >}}

{{< tip >}}
In a realistic deployment, new versions of a microservice are deployed
Expand All @@ -98,6 +161,9 @@ If you use GKE, please ensure your cluster has at least 4 standard GKE nodes. If

1. Confirm all services and pods are correctly defined and running:

{{< tabset category-name="dataplane-mode" >}}

{{< tab name="Sidecar Mode" category-value="sidecar-mode" >}}
{{< text bash >}}
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
Expand All @@ -121,6 +187,43 @@ If you use GKE, please ensure your cluster has at least 4 standard GKE nodes. If
reviews-v3-1813607990-8ch52 2/2 Running 0 6m
{{< /text >}}

{{< /tab >}}

{{< tab name="Ambient Mode" category-value="ambient-mode" >}}
{{< text bash >}}
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details ClusterIP 10.96.30.105 <none> 9080/TCP 61m
details-svc-waypoint ClusterIP 10.96.250.18 <none> 15021/TCP,15008/TCP 43m
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 63m
productpage ClusterIP 10.96.66.208 <none> 9080/TCP 61m
productpage-svc-waypoint ClusterIP 10.96.249.175 <none> 15021/TCP,15008/TCP 43m
ratings ClusterIP 10.96.141.216 <none> 9080/TCP 61m
ratings-svc-waypoint ClusterIP 10.96.233.85 <none> 15021/TCP,15008/TCP 43m
reviews ClusterIP 10.96.113.136 <none> 9080/TCP 61m
reviews-svc-waypoint ClusterIP 10.96.50.232 <none> 15021/TCP,15008/TCP 43m
{{< /text >}}

and

{{< text bash >}}
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
details-svc-waypoint-766c4b6b86-qlt7j 1/1 Running 0 44m
details-v1-766844796b-bwbzt 1/1 Running 0 61m
productpage-svc-waypoint-84c9c55bb8-6pgbz 1/1 Running 0 44m
productpage-v1-54bb874995-54b2b 1/1 Running 0 61m
ratings-svc-waypoint-6f9559f994-x6w94 1/1 Running 0 44m
ratings-v1-5dc79b6bcd-qhdld 1/1 Running 0 61m
reviews-svc-waypoint-788d467dcf-qhm7v 1/1 Running 0 44m
reviews-v1-598b896c9d-lrf6v 1/1 Running 0 61m
reviews-v2-556d6457d-t2qtq 1/1 Running 0 61m
reviews-v3-564544b4d6-6dn2m 1/1 Running 0 61m
{{< /text >}}
{{< /tab >}}

{{< /tabset >}}

1. To confirm that the Bookinfo application is running, send a request to it by a `curl` command from some pod, for
example from `ratings`:

Expand Down
55 changes: 49 additions & 6 deletions content/en/docs/examples/bookinfo/snips.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,22 @@ kubectl label namespace default istio-injection=enabled
}

snip_start_the_application_services_2() {
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml
kubectl label namespace default istio.io/dataplane-mode=ambient
}

snip_start_the_application_services_3() {
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml
}

snip_start_the_application_services_4() {
kubectl apply -f samples/bookinfo/platform/kube/bookinfo-waypoints.yaml
}

snip_start_the_application_services_5() {
kubectl get services
}

! IFS=$'\n' read -r -d '' snip_start_the_application_services_3_out <<\ENDSNIP
! IFS=$'\n' read -r -d '' snip_start_the_application_services_5_out <<\ENDSNIP
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details ClusterIP 10.0.0.31 <none> 9080/TCP 6m
kubernetes ClusterIP 10.0.0.1 <none> 443/TCP 7d
Expand All @@ -42,11 +50,11 @@ ratings ClusterIP 10.0.0.15 <none> 9080/TCP 6m
reviews ClusterIP 10.0.0.170 <none> 9080/TCP 6m
ENDSNIP

snip_start_the_application_services_4() {
snip_start_the_application_services_6() {
kubectl get pods
}

! IFS=$'\n' read -r -d '' snip_start_the_application_services_4_out <<\ENDSNIP
! IFS=$'\n' read -r -d '' snip_start_the_application_services_6_out <<\ENDSNIP
NAME READY STATUS RESTARTS AGE
details-v1-1520924117-48z17 2/2 Running 0 6m
productpage-v1-560495357-jk1lz 2/2 Running 0 6m
Expand All @@ -56,11 +64,46 @@ reviews-v2-1343845940-b34q5 2/2 Running 0 6m
reviews-v3-1813607990-8ch52 2/2 Running 0 6m
ENDSNIP

snip_start_the_application_services_5() {
snip_start_the_application_services_7() {
kubectl get services
}

! IFS=$'\n' read -r -d '' snip_start_the_application_services_7_out <<\ENDSNIP
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details ClusterIP 10.96.30.105 <none> 9080/TCP 61m
details-svc-waypoint ClusterIP 10.96.250.18 <none> 15021/TCP,15008/TCP 43m
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 63m
productpage ClusterIP 10.96.66.208 <none> 9080/TCP 61m
productpage-svc-waypoint ClusterIP 10.96.249.175 <none> 15021/TCP,15008/TCP 43m
ratings ClusterIP 10.96.141.216 <none> 9080/TCP 61m
ratings-svc-waypoint ClusterIP 10.96.233.85 <none> 15021/TCP,15008/TCP 43m
reviews ClusterIP 10.96.113.136 <none> 9080/TCP 61m
reviews-svc-waypoint ClusterIP 10.96.50.232 <none> 15021/TCP,15008/TCP 43m
ENDSNIP

snip_start_the_application_services_8() {
kubectl get pods
}

! IFS=$'\n' read -r -d '' snip_start_the_application_services_8_out <<\ENDSNIP
NAME READY STATUS RESTARTS AGE
details-svc-waypoint-766c4b6b86-qlt7j 1/1 Running 0 44m
details-v1-766844796b-bwbzt 1/1 Running 0 61m
productpage-svc-waypoint-84c9c55bb8-6pgbz 1/1 Running 0 44m
productpage-v1-54bb874995-54b2b 1/1 Running 0 61m
ratings-svc-waypoint-6f9559f994-x6w94 1/1 Running 0 44m
ratings-v1-5dc79b6bcd-qhdld 1/1 Running 0 61m
reviews-svc-waypoint-788d467dcf-qhm7v 1/1 Running 0 44m
reviews-v1-598b896c9d-lrf6v 1/1 Running 0 61m
reviews-v2-556d6457d-t2qtq 1/1 Running 0 61m
reviews-v3-564544b4d6-6dn2m 1/1 Running 0 61m
ENDSNIP

snip_start_the_application_services_9() {
kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" -c ratings -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"
}

! IFS=$'\n' read -r -d '' snip_start_the_application_services_5_out <<\ENDSNIP
! IFS=$'\n' read -r -d '' snip_start_the_application_services_9_out <<\ENDSNIP
<title>Simple Bookstore App</title>
ENDSNIP

Expand Down