Skip to content

Latest commit

 

History

History
334 lines (271 loc) · 18.3 KB

README.md

File metadata and controls

334 lines (271 loc) · 18.3 KB
Raw

OSM Manual Demo Guide

Table of Contents

Overview

The OSM Manual Install Demo Guide is designed to quickly allow you to demo and experience the OSM mesh.

Configure Prerequisites

  • Kubernetes cluster running Kubernetes v1.15.0 or greater
  • Have kubectl CLI installed - Install and Set Up Kubectl
  • kubectl current context is configured for the target cluster install
    • kubectl config current-context
  • Have a local clone of the OSM GitHub Repo
    • git clone https://github.com/openservicemesh/osm.git
    • cd osm

Install OSM CLI

Use the installation guide to install the osm cli.

Install OSM Control Plane

For the purpose of this demo, it is recommended to install OSM with permissive traffic policy mode enabled. By default, OSM will install with permissive traffic policy mode disabled and SMI Traffic Policy Mode enabled.

Note: By default, osm CLI does not enable Prometheus, Grafana, and Jaegar as a part of control plane installation.

  1. Install OSM in permissive traffic policy mode:

    osm install --enable-permissive-traffic-policy

  2. Install OSM in SMI traffic policy mode:

    osm install

  3. To enable Prometheus and Grafana, use their respective flags

    osm install --deploy-prometheus true --deploy-grafana true

    See the metrics documentation for more details.

Deploying the Bookstore Demo Applications

The demo consists of the following resources:

  • bookbuyer application that makes requests to the bookstore service to buy books
  • bookthief application that makes requests to the bookstore service to steal books
  • bookstore service that allows clients to purchase books
  • bookwarehouse service that the bookstore service reaches out to restock books

When we demonstrate traffic splitting using SMI Traffic Split, we will deploy two additional services:

  • bookstore-v1 service representing version v1 of the bookstore service
  • bookstore-v2 service representing version v2 of the bookstore service

The bookbuyer, bookthief, bookstore, and bookwarehouse demo applications will be installed in their respective Kubernetes Namespaces. In order for these applications to be injected with a Envoy sidecar automatically, we must add the Namespaces to be monitored by the mesh.

Create the Bookstore Application Namespaces

for i in bookstore bookbuyer bookthief bookwarehouse; do kubectl create ns $i; done

Onboard the Namespaces to the OSM Mesh and enable sidecar injection on the namespaces

osm namespace add bookstore bookbuyer bookthief bookwarehouse

Deploy the Bookstore Application

Deploy bookbuyer, bookthief, bookstore, bookwarehouse applications:

kubectl apply -f docs/example/manifests/apps/bookbuyer.yaml
kubectl apply -f docs/example/manifests/apps/bookthief.yaml
kubectl apply -f docs/example/manifests/apps/bookstore.yaml
kubectl apply -f docs/example/manifests/apps/bookwarehouse.yaml

Checkpoint: What Got Installed?

A Kubernetes Service, Deployment, and ServiceAccount for applications bookbuyer, bookthief, bookstore and bookwarehouse.

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

kubectl get svc --all-namespaces
kubectl get deployment --all-namespaces

View the Application UIs

We will now setup client port forwarding, so we can access the services 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 variables. The ".env" creates the necessary variables that target the previously created namespaces. We will use the reference .env.examples 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.

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.

Verify the Traffic Policy Mode

Check whether permissive traffic policy mode is enabled or not by retrieving the value for the permissive_traffic_policy_mode key in the osm-config ConfigMap.

# Replace osm-system with osm-controller's namespace if using a non default namespace
kubectl get configmap -n osm-system osm-config -o json | jq -r '.data["permissive_traffic_policy_mode"]'
# 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 --enable-permissive-traffic-policy
  1. Post install by updating the osm-config ConfigMap in the control plane's namespace (osm-system by default)
# Replace osm-system with osm-controller's namespace if using a non default namespace
kubectl patch ConfigMap osm-config -n osm-system -p '{"data":{"permissive_traffic_policy_mode":"true"}}' --type=merge

Verify traffic in permissive traffic policy mode

Before proceeding, verify the traffic policy mode and ensure the permissive_traffic_policy_mode key is set to true in the osm-config ConfigMap. 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 spec docs/example/manifests/apps/bookstore.yaml. 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 service with identity bookstore-v1 because permissive traffic policy mode is enabled, thereby allowing connectivity between applications without the need for SMI traffic policies.

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

# Replace osm-system with osm-controller's namespace if using a non default namespace
kubectl patch ConfigMap osm-config -n osm-system -p '{"data":{"permissive_traffic_policy_mode":"false"}}' --type=merge

*Note:

  1. When you disable permissive traffic policy mode, SMI traffic policy mode is implicitly enabled, so if counters for the books are incrementing then it could be because some SMI policies have been applied previously to allow such traffic.
  2. In permissive traffic policy mode, a Kubernetes service must be created even for client pods that do not expose a service.

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 permissive_traffic_policy_mode key is set to false in the osm-config ConfigMap.

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

# Replace osm-system with osm-controller's namespace if using a non default namespace
kubectl patch ConfigMap osm-config -n osm-system -p '{"data":{"permissive_traffic_policy_mode":"false"}}' --type=merge

Deploy bookstore v1 and v2 services

To demonstrate usage of SMI traffic access and split policies, we will deploy now deploy two versions of the bookstore application - bookstore-v1 and bookstore-v2.

kubectl apply -f docs/example/manifests/apps/bookstore-v1.yaml
kubectl apply -f docs/example/manifests/apps/bookstore-v2.yaml

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

A simple topology view of the Bookstore application now looks like the following: Bookstore Application Topology

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-v1, and bookstore-v2 UI are incrementing.

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

# Deploy SMI TrafficTarget and HTTPRouteGroup policy
kubectl apply -f docs/example/manifests/access/traffic-access-v1.yaml

Note: At the moment, you must configure a TrafficSplit resource to get your applications set up correctly for inbound traffic because it helps us properly configure the dataplane. We are working on removing the need for this entirely. #1370

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

kubectl apply -f docs/example/manifests/split/traffic-split-v1.yaml

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

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-v1. 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-v1
    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-v1
   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 docs/example/manifests/access/traffic-access-v1.yaml

The counter in the bookthief window will start 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-v1 service and bookstore-v2 service.

Split Traffic to v2 of Bookstore

Deploy an SMI TrafficTarget policy to allow bookbuyer and bookthief to access the bookstore-v2 service:

kubectl apply -f docs/example/manifests/access/traffic-access-v2.yaml

Browse to http://localhost:8082. You should see the bookstore-v2 heading in your browser window.

The count for the books sold should remain at 0, this is because the current traffic split policy is currently weighted 100 for bookstore-v1. You can verify the traffic split policy by running the following and viewing the Backends properties:

kubectl describe trafficsplit bookstore-split -n bookstore

Update Traffic Split

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

kubectl apply -f docs/example/manifests/split/traffic-split-v2.yaml

Wait for the changes to propagate and observe the counters increment for bookstore-v2 in your browser windows. Modify the weight fields in manifests/split-v2/traffic-split-v2.yaml and re-apply changes to experiment.

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.