How to run the OSM manual demo

The OSM manual demo install guide is a step by step set of instructions to quickly demo OSM’s key features.

Prerequisites

This demo of OSM v0.9.1 requires:

Note: This document assumes you have already installed credentials for a Kubernetes cluster in ~/.kube/config and kubectl cluster-info executes successfully.

Download and install the OSM command-line tool

The osm command-line tool contains everything needed to install and configure Open Service Mesh. The binary is available on the OSM GitHub releases page.

For GNU/Linux and macOS

Download the 64-bit GNU/Linux or macOS binary of OSM v0.9.1:

system=$(uname -s)
release=v0.9.1
curl -L https://github.com/openservicemesh/osm/releases/download/${release}/osm-${release}-${system}-amd64.tar.gz | tar -vxzf -
./${system}-amd64/osm version

For Windows

Download the 64-bit Windows OSM v0.9.1 binary via Powershell:

wget  https://github.com/openservicemesh/osm/releases/download/v0.9.1/osm-v0.9.1-windows-amd64.zip -o osm.zip
unzip osm.zip
.\windows-amd64\osm.exe version

The osm CLI can be compiled from source using this guide.

Installing OSM on Kubernetes

With the osm binary downloaded and unzipped, we are ready to install Open Service Mesh on a Kubernetes cluster:

The command below shows how to install OSM on your Kubernetes cluster. This command enables Prometheus, Grafana, and Jaeger integrations. The OpenServiceMesh.enablePermissiveTrafficPolicy chart parameter in the values.yaml file instructs OSM to ignore any policies and let traffic flow freely between the pods. With Permissive Traffic Policy mode enabled, new pods will be injected with Envoy, but traffic will flow through the proxy and will not be blocked.

Note: Permissive Traffic Policy mode is an important feature for brownfield deployments, where it may take some time to craft SMI policies. While operators design the SMI policies, existing services will continue to operate as they have been before OSM was installed.

osm install \
    --set=OpenServiceMesh.enablePermissiveTrafficPolicy=true \
    --set=OpenServiceMesh.deployPrometheus=true \
    --set=OpenServiceMesh.deployGrafana=true \
    --set=OpenServiceMesh.deployJaeger=true

This installed OSM Controller in the osm-system namespace.

Read more on OSM’s integrations with Prometheus, Grafana, and Jaeger in the observability documentation.

Deploy Applications

In this section we will deploy 4 different Pods, and we will apply policies to control the traffic between them.

  • bookbuyer is an HTTP client making requests to bookstore. This traffic is permitted.
  • bookthief is an HTTP client and much like bookbuyer also makes HTTP requests to bookstore. This traffic should be blocked.
  • bookstore is a server, which responds to HTTP requests. It is also a client making requests to the bookwarehouse service.
  • bookwarehouse is a server and should respond only to bookstore. Both bookbuyer and bookthief should be blocked.

We are going to craft SMI policies, which will bring us to this final desired state of allowed and blocked traffic between pods:

from / to: bookbuyer bookthief bookstore bookwarehouse
bookbuyer \ ❌ ✔ ❌
bookthief ❌ \ ❌ ❌
bookstore ❌ ❌ \ ✔
bookwarehouse ❌ ❌ ❌ \

To show SMI Traffic Split, we will deploy an additional application:

  • bookstore-v2 - this is the same container as the first bookstore we deployed, but for this demo we will assume that it is a new version of the app we need to upgrade to.

The bookbuyer, bookthief, bookstore, and bookwarehouse Pods will be in separate Kubernetes Namespaces with the same names. Each new Pod in the service mesh will be injected with an Envoy sidecar container.

Create the Namespaces

kubectl create namespace bookstore
kubectl create namespace bookbuyer
kubectl create namespace bookthief
kubectl create namespace bookwarehouse

Add the new namespaces to the OSM control plane

osm namespace add bookstore
osm namespace add bookbuyer
osm namespace add bookthief
osm namespace add bookwarehouse

Now each one of the four namespaces is labelled with openservicemesh.io/monitored-by: osm and also annotated with openservicemesh.io/sidecar-injection: enabled. The OSM Controller, noticing the label and annotation on these namespaces, will start injecting all new pods with Envoy sidecars.

Create Pods, Services, ServiceAccounts

Create the bookbuyer service account and deployment:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/apps/bookbuyer.yaml

Create the bookthief service account and deployment:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/apps/bookthief.yaml

Create the bookstore service account, service, and deployment:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/apps/bookstore.yaml

Create the bookwarehouse service account, service, and deployment:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/apps/bookwarehouse.yaml

Checkpoint: What Got Installed?

A Kubernetes Deployment and Pods for each of bookbuyer, bookthief, bookstore and bookwarehouse. Also, Kubernetes Services and Endpoints for bookstore and bookwarehouse.

To view these resources on your cluster, run the following commands:

kubectl get deployments -n bookbuyer
kubectl get deployments -n bookthief
kubectl get deployments -n bookstore
kubectl get deployments -n bookwarehouse

kubectl get pods -n bookbuyer
kubectl get pods -n bookthief
kubectl get pods -n bookstore
kubectl get pods -n bookwarehouse

kubectl get services -n bookstore
kubectl get services -n bookwarehouse

kubectl get endpoints -n bookstore
kubectl get endpoints -n bookwarehouse

In addition, a Kubernetes Service Account was also created for each application. The Service Account serves as the application’s identity which will be used later in the demo to create service-to-service access control policies.

View the Application UIs

Set up client port forwarding with the following steps to access the applications in the Kubernetes cluster. It is best to start a new terminal session for running the port forwarding script to maintain the port forwarding session, while using the original terminal to continue to issue commands. The port-forward-all.sh script will look for a .env file for environment variables needed to run the script. The .env creates the necessary variables that target the previously created namespaces. We will use the reference .env.example file and then run the port forwarding script.

In a new terminal session, run the following commands to enable port forwarding into the Kubernetes cluster from the root of the project directory (your local clone of https://github.com/openservicemesh/osm).

cp .env.example .env
./scripts/port-forward-all.sh

Note: To override the default ports, prefix the BOOKBUYER_LOCAL_PORT, BOOKSTORE_LOCAL_PORT, BOOKSTOREv1_LOCAL_PORT, BOOKSTOREv2_LOCAL_PORT, and/or BOOKTHIEF_LOCAL_PORT variable assignments to the port-forward scripts. For example:

BOOKBUYER_LOCAL_PORT=7070 BOOKSTOREv1_LOCAL_PORT=7071 BOOKSTOREv2_LOCAL_PORT=7072 BOOKTHIEF_LOCAL_PORT=7073 BOOKSTORE_LOCAL_PORT=7074 ./scripts/port-forward-all.sh

In a browser, open up the following urls:

Position the windows so that you can see all four at the same time. The header at the top of the webpage indicates the application and version.

Traffic Encryption

All traffic is encrypted via mTLS regardless of whether you’re using access control policies or have enabled permissive traffic policy mode.

Traffic Policy Modes

Once the applications are up and running, they can interact with each other using permissive traffic policy mode or SMI traffic policy mode. In permissive traffic policy mode, traffic between application services is automatically configured by osm-controller, and SMI policies are not enforced. In the SMI policy mode, all traffic is denied by default unless explicitly allowed using a combination of SMI access and routing policies.

How to Check Traffic Policy Mode

Check whether permissive traffic policy mode is enabled or not by retrieving the value for the enablePermissiveTrafficPolicyMode key in the osm-mesh-config MeshConfig resource.

# Replace osm-system with osm-controller's namespace if using a non default namespace
kubectl get meshconfig osm-mesh-config -n osm-system -o jsonpath='{.spec.traffic.enablePermissiveTrafficPolicyMode}{"\n"}'
# Output:
# false: permissive traffic policy mode is disabled, SMI policy mode is enabled
# true: permissive traffic policy mode is enabled, SMI policy mode is disabled

The following sections demonstrate using OSM with permissive traffic policy mode and SMI Traffic Policy Mode.

Permissive Traffic Policy Mode

In permissive traffic policy mode, application connectivity within the mesh is automatically configured by osm-controller. It can be enabled in the following ways.

  1. During install using osm CLI:
osm install --set=OpenServiceMesh.enablePermissiveTrafficPolicy=true
  1. Post install by patching the osm-mesh-config custom resource in the control plane’s namespace (osm-system by default)
kubectl patch meshconfig osm-mesh-config -n osm-system -p '{"spec":{"traffic":{"enablePermissiveTrafficPolicyMode":true}}}'  --type=merge

Verify OSM is in permissive traffic policy mode

Before proceeding, verify the traffic policy mode and ensure the enablePermissiveTrafficPolicyMode key is set to true in the osm-mesh-config MeshConfig resource. Refer to the section above to enable permissive traffic policy mode.

In step Deploy the Bookstore Application, we have already deployed the applications needed to verify traffic flow in permissive traffic policy mode. The bookstore service we previously deployed is encoded with an identity of bookstore-v1 for demo purpose, as can be seen in the Deployment’s manifest. The identity reflects which counter increments in the bookbuyer and bookthief UI, and the identity displayed in the bookstore UI.

The counter in the bookbuyer, bookthief UI for the books bought and stolen respectively from bookstore v1 should now be incrementing:

The counter in the bookstore UI for the books sold should also be incrementing:

The bookbuyer and bookthief applications are able to buy and steal books respectively from the newly deployed bookstore application because permissive traffic policy mode is enabled, thereby allowing connectivity between applications without the need for SMI traffic access policies.

This can be demonstrated further by disabling permissive traffic policy mode and verifying that the counter for books bought from bookstore is not incrementing anymore:

kubectl patch meshconfig osm-mesh-config -n osm-system -p '{"spec":{"traffic":{"enablePermissiveTrafficPolicyMode":false}}}'  --type=merge

Note: When you disable permissive traffic policy mode, SMI traffic access mode is implicitly enabled. If counters for the books are incrementing then it could be because some SMI Traffic Access policies have been applied previously to allow such traffic.

SMI Traffic Policy Mode

SMI traffic policies can be used for the following:

  1. SMI access control policies to authorize traffic access between service identities
  2. SMI traffic specs policies to define routing rules to associate with access control policies
  3. SMI traffic split policies to direct client traffic to multiple backends based on weights

The following sections describe how to leverage each of these policies to enforce fine grained control over traffic flowing within the service mesh. Before proceeding, verify the traffic policy mode and ensure the enablePermissiveTrafficPolicyMode key is set to false in the osm-mesh-config MeshConfig resource.

SMI traffic policy mode can be enabled by disabling permissive traffic policy mode:

kubectl patch meshconfig osm-mesh-config -n osm-system -p '{"spec":{"traffic":{"enablePermissiveTrafficPolicyMode":false}}}'  --type=merge

Deploy SMI Access Control Policies

At this point, applications do not have access to each other because no access control policies have been applied. Confirm this by verifying that none of the counters in the bookbuyer, bookthief, bookstore, and bookstore-v2 UI are incrementing.

Apply the SMI Traffic Target and SMI Traffic Specs resources to define access control and routing policies for the applications to communicate:

Deploy SMI TrafficTarget and HTTPRouteGroup policy:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/access/traffic-access-v1.yaml

The counters should now be incrementing for the bookbuyer, and bookstore applications:

Note that the counter is not incrementing for the bookthief application:

That is because the SMI Traffic Target SMI HTTPRouteGroup resources deployed only allow bookbuyer to communicate with the bookstore.

Allowing the Bookthief Application to access the Mesh

Currently the Bookthief application has not been authorized to participate in the service mesh communication. We will now uncomment out the lines in the docs/example/manifests/access/traffic-access-v1.yaml to allow bookthief to communicate with bookstore. Then, re-apply the manifest and watch the change in policy propagate.

Current TrafficTarget spec with commented bookthief kind:

kind: TrafficTarget
apiVersion: access.smi-spec.io/v1alpha3
metadata:
  name: bookstore-v1
  namespace: bookstore
spec:
  destination:
    kind: ServiceAccount
    name: bookstore
    namespace: bookstore
  rules:
  - kind: HTTPRouteGroup
    name: bookstore-service-routes
    matches:
    - buy-a-book
    - books-bought
  sources:
  - kind: ServiceAccount
    name: bookbuyer
    namespace: bookbuyer
  #- kind: ServiceAccount
    #name: bookthief
    #namespace: bookthief

Updated TrafficTarget spec with uncommented bookthief kind:

kind: TrafficTarget
apiVersion: access.smi-spec.io/v1alpha3
metadata:
 name: bookstore-v1
 namespace: bookstore
spec:
 destination:
   kind: ServiceAccount
   name: bookstore
   namespace: bookstore
 rules:
 - kind: HTTPRouteGroup
   name: bookstore-service-routes
   matches:
   - buy-a-book
   - books-bought
 sources:
 - kind: ServiceAccount
   name: bookbuyer
   namespace: bookbuyer
 - kind: ServiceAccount
   name: bookthief
   namespace: bookthief

Re-apply the access manifest with the updates.

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/access/traffic-access-v1-allow-bookthief.yaml

The counter in the bookthief window will start incrementing.

Comment out the bookthief source lines in the Traffic Target object and re-apply the Traffic Access policies:

# Re-apply original SMI TrafficTarget and HTTPRouteGroup resources
kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/access/traffic-access-v1.yaml

The counter in the bookthief window will stop incrementing.

Configure Traffic Split between Two Services

We will now demonstrate how to balance traffic between two Kubernetes services, commonly known as a traffic split. We will be splitting the traffic directed to the root bookstore service between the backends bookstore service and bookstore-v2 service.

Deploy bookstore v2 application

To demonstrate usage of SMI traffic access and split policies, we will now deploy version v2 of the bookstore application (bookstore-v2) - remember that if you are using openshift, you must add the security context constraint to the bookstore-v2 service account as specified in the installation guide.

# Contains the bookstore-v2 Kubernetes Service, Service Account, Deployment and SMI Traffic Target resource to allow
# bookbuyer to communicate with `bookstore-v2` pods
kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/apps/bookstore-v2.yaml

Wait for the bookstore-v2 pod to be running in the bookstore namespace. Next, exit and restart the ./scripts/port-forward-all.sh script in order to access v2 of bookstore.

The counter should not be incrementing because no traffic is flowing yet to the bookstore-v2 service.

Create SMI Traffic Split

Deploy the SMI traffic split policy to direct 100 percent of the traffic sent to the root bookstore service to the bookstore service backend:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/split/traffic-split-v1.yaml

Note: The root service can be any Kubernetes service. It does not have any label selectors. It also doesn’t need to overlap with any of the Backend services specified in the Traffic Split resource. The root service can be referred to in the SMI Traffic Split resource as the name of the service with or without the .<namespace> suffix.

The count for the books sold from the bookstore-v2 browser window should remain at 0. This is because the current traffic split policy is currently weighted 100 for bookstore in addition to the fact that bookbuyer is sending traffic to the bookstore service and no application is sending requests to the bookstore-v2 service. You can verify the traffic split policy by running the following and viewing the Backends properties:

kubectl describe trafficsplit bookstore-split -n bookstore

Split Traffic to Bookstore v2

Update the SMI Traffic Split policy to direct 50 percent of the traffic sent to the root bookstore service to the bookstore service and 50 perfect to bookstore-v2 service by adding the bookstore-v2 backend to the spec and modifying the weight fields.

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/split/traffic-split-50-50.yaml

Wait for the changes to propagate and observe the counters increment for bookstore and bookstore-v2 in your browser windows. Both counters should be incrementing:

Split All Traffic to Bookstore v2

Update the SMI TrafficSplit policy for bookstore Service configuring all traffic to go to bookstore-v2:

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v0.9/docs/example/manifests/split/traffic-split-v2.yaml

Wait for the changes to propagate and observe the counters increment for bookstore-v2 and freeze for bookstore in your browser windows:

Now, all traffic directed to the bookstore service is flowing to bookstore-v2.

Inspect Dashboards

OSM can be configured to deploy Grafana dashboards using the --deploy-grafana flag in osm install. NOTE If you still have the additional terminal still running the ./scripts/port-forward-all.sh script, go ahead and CTRL+C to terminate the port forwarding. The osm dashboard port redirection will not work simultaneously with the port forwarding script still running. The osm dashboard can be viewed with the following command:

osm dashboard

Simply navigate to http://localhost:3000 to access the Grafana dashboards. The default user name is admin and the default password is admin. On the Grafana homepage click on the Home icon, you will see a folders containing dashboards for both OSM Control Plan and OSM Data Plane.

Cleanup

To cleanup all resources created for the demo, the OSM control plane, SMI resources, and the sample applications need to be deleted.

To uninstall the sample applications and SMI resources, delete their namespaces with the following command:

kubectl delete ns bookbuyer bookthief bookstore bookwarehouse

To uninstall OSM, run

osm uninstall

For more details about uninstalling OSM, see the uninstallation guide.