Quickstart

Quickstart

Let’s get started with ambient mesh. In this tutorial, you explore how to quickly set up an ambient mesh, add sample microservices, and enable secure mutual TLS (mTLS) communication between workloads.

Best of all, no changes are needed in your apps, because the mesh is ambient, or just there, working in the background. No config changes or app downtime to worry about.

Want to dive deeper? Try out the Quickstart lab for an interactive, browser-based experience. Or read up about the benefits of ambient mesh on the About page.

Before you begin

Create or use an existing Kubernetes or OpenShift cluster.

Install ambient mesh

Install the Kubernetes Gateway API custom resources

Ambient mesh is configured using the Gateway API, the next-generation API for routing built by the Kubernetes project. The APIs are not installed by default on most clusters, so install the latest version:

Install the Kubernetes Gateway API
$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  { kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; }

Install the Istio CLI

Get the latest version of the Istio command line tool (CLI) istioctl. You use this CLI later to set up ambient mesh in your cluster.

$ curl -L https://istio.io/downloadIstio | sh -
$ cd istio-1.23.2
$ export PATH=$PWD/bin:$PATH

Check your version of the istioctl CLI. Don’t worry if you see a message about Istio not present. That error goes away when you install ambient mesh later.

$ istioctl version
Istio is not present in the cluster: no running Istio pods in namespace "istio-system"
client version: 1.23.2

Set up an ambient mesh

Now that you installed the istioctl CLI, you can go ahead and set up your ambient mesh.

$ istioctl install --set profile=ambient --skip-confirmation

It might take a minute to install the ambient mesh components. Wait until you see the checkmarks in the CLI output.

✔ Istio core installed
✔ Istiod installed
✔ CNI installed
✔ Ztunnel installed
✔ Installation complete

Congratulations! You successfully installed an ambient mesh!

Deploy a sample application

Let’s deploy the Bookinfo sample application to explore the traffic management, security, and resiliency features in your ambient mesh. This app has four microservices that work together to create an online bookstore catalog. Separate microservices focus on sharing basic details about the book, user reviews, ratings, and the product page itself.

Deploy Bookinfo

Create the deployment and services for the Bookinfo microservices.

$ kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/platform/kube/bookinfo.yaml

Make sure the Bookinfo pods are running.

$ 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

Create an ingress gateway

The Bookinfo pods are running, but how can you reach them?

Let’s create an ingress Gateway with the Kubernetes Gateway API. We’ll also create an HTTPRoute to set up routes to each of the Bookinfo microservices.

$ kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/gateway-api/bookinfo-gateway.yaml

A brief note on the service types:

  • Using a cloud provider? You should be good to go. Istio creates a LoadBalancer service to expose the Gateway. Usually, your cloud provider assigns a public IP address or hostname for the LoadBalancer for you.

  • Don’t have or don’t want public access on a LoadBalancer service? You can annotate the Gateway to change the service type to ClusterIP. This setup is common when you are testing locally, such as with kind.

$ kubectl annotate gateway bookinfo-gateway networking.istio.io/service-type=ClusterIP --namespace=default

Before moving on, let’s make sure the Gateway has an address.

$ kubectl get gateway
NAME               CLASS   ADDRESS                                            PROGRAMMED   AGE
bookinfo-gateway   istio   bookinfo-gateway-istio.default.svc.cluster.local   True         42s

Access Bookinfo

Connect to the Bookinfo services through the Gateway that you just created.

Access the Gateway by port-forwarding its service.

$ kubectl port-forward svc/bookinfo-gateway-istio 8080:80

In your web browser, open the productpage route: http://localhost:8080/productpage

Bookinfo Application

Refresh the page a couple times. You’ll see the book reviews and ratings change as the Gateway load balances your requests across the different versions of the reviews service.

To end the port forward session in your terminal, enter Ctrl-C.

Nice job! Your Bookinfo app is up and running.

Add Bookinfo to the mesh

Adding applications to an ambient mesh is as simple as labeling the namespace where the application resides. By adding the applications to the mesh, you automatically secure the communication between them via mutual TLS (mTLS). No restart or redeployment of your applications are needed. As traffic is routed through your ambient mesh, TCP telemetry data is automatically collected for you.

Enable ambient mesh for Bookinfo

Ready to add an app to your ambient mesh? It’s as simple as labeling the app’s namespace.

$ kubectl label namespace default istio.io/dataplane-mode=ambient
namespace/default labeled

That’s it! You successfully added all pods in the default namespace to the ambient mesh. 🎉

What does that mean?

When apps join the mesh, ambient mode automatically secures the communication between them via mutual TLS (mTLS). It also automatically collects TCP telemetry data for you. And no, you don’t need to update any config or redeploy your apps!

If you open the Bookinfo application in your browser, you see the product page, just like before. But this time, the communication between the Bookinfo application pods is encrypted by using mTLS.

Verify mTLS

There are multiple ways for how you can verify the mTLS connection between the Bookinfo microservices. Check out Verify mutual TLS is enabled to see your options.

Next steps

Just by setting up ambient mesh, you’ve already unlocked many benefits like automatic mTLS across apps. Now, explore all the other things you can do with ambient mesh.