diff --git a/docs/common/images/kiali-dashboard.png b/docs/common/images/kiali-dashboard.png new file mode 100644 index 000000000..755c8690e Binary files /dev/null and b/docs/common/images/kiali-dashboard.png differ diff --git a/docs/common/images/kiali-security.png b/docs/common/images/kiali-security.png new file mode 100644 index 000000000..cd028de51 Binary files /dev/null and b/docs/common/images/kiali-security.png differ diff --git a/docs/common/images/kiali-traffic-map.png b/docs/common/images/kiali-traffic-map.png new file mode 100644 index 000000000..aa6dec115 Binary files /dev/null and b/docs/common/images/kiali-traffic-map.png differ diff --git a/docs/common/istio-ambient-mode.md b/docs/common/istio-ambient-mode.md new file mode 100644 index 000000000..54320292f --- /dev/null +++ b/docs/common/istio-ambient-mode.md @@ -0,0 +1,366 @@ + +## Introduction to Istio Ambient mode + +Ambient mesh was announced in September 2022 and reached a stable state in the Istio 1.24 release. It's core innovation is the separation of Layer 4 (L4) and Layer 7 (L7) processing into two distinct layers. It uses lightweight, shared L4 node proxies and optional L7 proxies, eliminating the need for traditional sidecar proxies in the data plane. + +The lightweight, shared L4 node proxy is called ztunnel (zero-trust tunnel). It significantly reduces the overhead of running a mesh by eliminating the need to over-provision memory and CPU while still ensuring security through mutual TLS, simple L4 authorization policies, and telemetry. + +The L7 proxies, known as waypoints, handle functions like traffic routing, authorization policy enforcement, and resilience. They run separately from application deployments and can scale independently based on demand. + +In contrast to the Istio Sidecar mode. Users can start with the secure L4 overlay, which offers features such as mTLS, authorization policy, and telemetry. Complex L7 handling such as retries, traffic splitting, load balancing, and observability collection can then be enabled on a case-by-case basis. + +## Component version + +To install Istio Ambient mode using Sail Operator on OpenShift, use version `v1.24.0` or later and deploy the `Istio`, `IstioCNI`, and `ZTunnel` resources. + +## Concepts + +### ZTunnel resource + +The `ZTunnel` resource manages the L4 node proxy and is a cluster-wide resource. It deploys a DaemonSet that runs on all nodes in the cluster. You can specify the version using the `spec.version` field, as shown in the example below. Similar to the `Istio` resource, it also includes a `values` field that allows you to configure options available in the ztunnel helm chart. + +```yaml +apiVersion: sailoperator.io/v1alpha1 +kind: ZTunnel +metadata: + name: default +spec: + profile: ambient + version: v1.24.0 + namespace: ztunnel + values: + ztunnel: + image: docker.io/istio/ztunnel:1.24.0 +``` + +### API Reference documentation + +The ZTunnel resource API reference documentation can be found [here](https://github.com/istio-ecosystem/sail-operator/blob/main/docs/api-reference/sailoperator.io.md#ztunnel). + +## Core features + +- Secure application access using mTLS encryption. +- Enforce Layer 4 authorization policies for enhanced security. +- Apply Layer 7 authorization policies using a waypoint proxy. +- Route and split traffic between services with a waypoint proxy. +- Collect TCP telemetry and visualize traffic flow between pods using Kiali. + +## Getting Started + +### Installation on OpenShift + +*Prerequisites* + +* You have access to the cluster as a user with the `cluster-admin` cluster role. + +*Steps* + +1. Install the Sail Operator using the CLI or through the web console. The steps can be found [here](https://github.com/istio-ecosystem/sail-operator/blob/main/docs/README.md#installation-on-openshift). + +2. Create the `istio-system` namespace and add a label `istio-discovery=enabled`. + +```bash +$ kubectl create namespace istio-system +$ kubectl label namespace istio-system istio-discovery=enabled +``` + +3. Create the `Istio` resource. +> **NOTE**: +> The Istio resource `.spec.values.pilot.trustedZtunnelNamespace` value should match the namespace that we will install a `ZTunnel` resource at. + +```bash +$ cat < **NOTE**: +> We need to label both the `Istio` resource's namespace e.g. `istio-system` and the `ZTunnel` resource's namespace when using a `discoverySelectors` mesh config. Those two labels should be added before installing a `ZTunnel` instance. This approach is used to avoid a [TLS signing error](https://github.com/istio/istio/issues/52057). + +```bash +$ kubectl create namespace ztunnel +$ kubectl label namespace ztunnel istio-discovery=enabled +``` + +8. Create the `ZTunnel` resource. + +```bash +$ cat < /dev/null || \ +{ kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; } +$ kubectl apply -n bookinfo -f https://raw.githubusercontent.com/istio/istio/release-1.24/samples/bookinfo/gateway-api/bookinfo-gateway.yaml +``` + +Wait for the `bookinfo-gateway` pod running and then get the `productpage` service URL. The wait time depends on your cluster cloud provider. It takes me about one minute from an AWS ELB to be able to access it. + +```bash +$ export INGRESS_HOST=$(kubectl get -n bookinfo gtw bookinfo-gateway -o jsonpath='{.status.addresses[0].value}') +$ export INGRESS_PORT=$(kubectl get -n bookinfo gtw bookinfo-gateway -o jsonpath='{.spec.listeners[?(@.name=="http")].port}') +$ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT +$ echo "http://${GATEWAY_URL}/productpage" +``` + +5. Access the application. + +Open your browser and navigate to `http://${GATEWAY_URL}/productpage` to view the Bookinfo application. +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. + +6. Add Bookinfo to the Ambient mesh. + +```bash +$ kubectl label namespace bookinfo istio.io/dataplane-mode=ambient +``` + +> **Note**: +> You don't need to restart or redeploy any of the application pods. +> Unlike the sidecar mode, each pod's container count will remain the same even after adding them to the ambient mesh. + +If you refresh the previous browser page, you should see the same display. + +7. To confirm that `ztunnel` successfully opened listening sockets inside the pod network ns, use the following command. + +```console +$: kubectl exec -it -n bookinfo deploy/productpage -- netstat -tulpn +Active Internet connections (only servers) +Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name +tcp 0 0 127.0.0.1:15053 0.0.0.0:* LISTEN - +tcp 0 0 ::1:15053 :::* LISTEN - +tcp 0 0 :::15008 :::* LISTEN - +tcp 0 0 :::15001 :::* LISTEN - +tcp 0 0 :::15006 :::* LISTEN - +udp 0 0 127.0.0.1:15053 0.0.0.0:* - +udp 0 0 ::1:15053 :::* - +``` + +## Visualize the application using Kiali dashboard + +Using Kiali dashboard and Prometheus metrics engine, you can visualize the Bookinfo application traffic and mTLS encryption. + +Deploy Prometheus in `istio-system` namespace. + +```bash +$ kubectl apply -n istio-system -f https://raw.githubusercontent.com/istio/istio/master/samples/addons/prometheus.yaml +``` + +Deploy a Kiali dashboard using a community Kiali operator on OpenShift. + +```bash +$ cat < **NOTE**: +> You must remove workloads from the ambient data plane before uninstalling Istio. + +#### Remove the sample application + +```bash +kubectl delete -n bookinfo -f https://raw.githubusercontent.com/istio/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml +kubectl delete -n bookinfo -f https://raw.githubusercontent.com/istio/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo-versions.yaml +kubectl delete -n bookinfo -f https://raw.githubusercontent.com/istio/istio/release-1.24/samples/bookinfo/gateway-api/bookinfo-gateway.yaml +``` + +#### Remove the Kubernetes Gateway API CRDs + +```bash +kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml +```