lab fix

02.application-deployment.md

@@ -0,0 +1,129 @@
+# 02. Application deployment
+
+Follow these few steps to install the Bookinfo use application on your kubernetes cluster.
+
+## Task 1. Create a labeled/protected namespace
+
+APIClarity will use istio to monitor application traffic.
+
+Create a dedicated namespace for the user application.
+Add an istio-injection label so that istio automatically inserts envoy proxy to the user application.
+
+```bash
+kubectl create namespace bookinfo
+kubectl label namespace bookinfo istio-injection=enabled --overwrite
+```
+
+## Task 2. Deploy Bookinfo application
+
+The Bookinfo application displays information about a book, similar to a single catalog entry of an online book store. Displayed on the page is a description of the book, book details (ISBN, number of pages, and so on), and a few book reviews.
+
+The Bookinfo application is broken into four separate microservices:
+
+* productpage. The productpage microservice calls the details and reviews microservices to populate the page.
+* details. The details microservice contains book information.
+* reviews. The reviews microservice contains book reviews. It also calls the ratings microservice.
+* ratings. The ratings microservice contains book ranking information that accompanies a book review.
+
+There are 3 versions of the reviews microservice:
+
+* Version v1 doesn’t call the ratings service.
+* Version v2 calls the ratings service, and displays each rating as 1 to 5 black stars.
+* Version v3 calls the ratings service, and displays each rating as 1 to 5 red stars.
+
+The end-to-end architecture of the application is shown below.
+
+![](images/booinfo-istio.svg)
+
+As the application architecture is based on micro-services which use REST APIs for inter communication,
+APIClarity can analyse it.
+
+Run the following command to install the BookInfo application:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.15/samples/bookinfo/platform/kube/bookinfo.yaml --namespace=bookinfo
+```
+
+You should have a similar output:
+
+```console
+service/details created
+serviceaccount/bookinfo-details created
+deployment.apps/details-v1 created
+service/ratings created
+serviceaccount/bookinfo-ratings created
+deployment.apps/ratings-v1 created
+service/reviews created
+serviceaccount/bookinfo-reviews created
+deployment.apps/reviews-v1 created
+deployment.apps/reviews-v2 created
+deployment.apps/reviews-v3 created
+service/productpage created
+serviceaccount/bookinfo-productpage created
+deployment.apps/productpage-v1 created
+```
+
+## Task 3. Generate traffic
+
+[Locust](https://docs.locust.io/en/stable/#) is deployed next to simulate periodic user requests.
+
+Run the following command:
+
+```bash
+cat > locust.yaml << EOF
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: reviews-inject-config
+data:
+  locustfile.py: |
+    from locust import HttpUser, task
+    class HelloWorldUser(HttpUser):
+        @task
+        def hello_world(self):
+            self.client.get("/productpage?u=normal")
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: reviews-inject-v1
+  labels:
+    app: reviews-inject
+    version: v1
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: reviews-inject
+      version: v1
+  template:
+    metadata:
+      labels:
+        app: reviews-inject
+        version: v1
+      annotations:
+        sidecar.istio.io/inject: "false"
+    spec:
+      volumes:
+      - name: config-volume
+        configMap:
+          name: reviews-inject-config
+      containers:
+      - name: reviews-inject
+        image: locustio/locust
+        volumeMounts:
+        - name: config-volume
+          mountPath: /bookinfo/locustfile.py
+          subPath: locustfile.py
+        command:
+        - /bin/bash
+        - -c
+        - "locust -f /bookinfo/locustfile.py --headless -u 1 -r 1 --host http://productpage.bookinfo.svc.cluster.local:9080"
+EOF
+```
+
+Then apply the locust configuration
+
+```bash
+kubectl apply -f locust.yaml
+```

02.apiclarity-setup.md → 03.apiclarity-setup.md

@@ -1,19 +1,8 @@
-# 02. APIClarity setup
+# 03. APIClarity setup
 
 Follow these few steps to install APIClarity on your kubernetes cluster.
 
-## Task 1. Create a labeled/protected namespace
-
-APIClarity will use istio to monitor application traffic.
-Create a dedicated namespace for the user application.
-Add an istio-injection label so that istio automatically inserts envoy proxy to the user application.
-
-```bash
-kubectl create namespace bookinfo
-kubectl label namespace bookinfo istio-injection=enabled --overwrite
-```
-
-## Task 2. Install APIClarity
+## Task 1. Install APIClarity
 
 ```bash
 helm repo add apiclarity https://openclarity.github.io/apiclarity
@@ -32,7 +21,7 @@ apiclarity \
 apiclarity/apiclarity
 ```
 
-## Task 3. Expose APIClarity UI
+## Task 2. Expose APIClarity UI
 
 Run the following command to install the load balancer MetalLb:
 

04.apiclarity-analysis.md

@@ -0,0 +1,62 @@
+# 04. Analyse API traffic with APIClarity
+
+## Task 1. Analyse API traffic on APIClarity
+
+Open the web UI of APIClarity. Refresh the page if you don't find captured traffic.
+
+Observe the graph. Multiple user requests are automcatically simulated. This generates several hundreds of API calls every second. None of the detected calls are known by APIClarity. Thus, they are defined as *New APIs*.
+
+![](./images/2022-10-26-14-26-51.png)
+
+## Task 2. Reconstruct API schema.
+
+Under the API inventory you will find three discovered APIs:
+
+* reviews.bookinfo
+* ratings.bookinfo
+* details.bookinfo
+
+![](./images/2022-10-26-14-30-47.png)
+
+Use APIClarity's capability to reconstruct an OpenAPI schema based on the captured traffic.
+Reconstruct the schema for the three APIs.
+
+![](./images/2022-10-26-14-28-45.png)
+
+Click all paths and approve review.
+
+![](./images/2022-10-26-14-32-48.png)
+
+Choose OAS V3
+
+![](./images/2022-10-26-14-33-34.png)
+
+Once the schema is generated, you can review it in Swagger. Select `see on Swagger`:
+
+![](./images/2022-11-05-08-06-55.png)
+
+You can then review the response schema:
+
+![](./images/2022-10-26-14-34-23.png)
+
+## Task 3. Analysis of API difference
+
+Once a schema is loaded by the user or reconstructed by APIClarity, the application is using to compare running traffic towards the blueprint.
+
+The general Dashboard shows now:
+
+- New APIs: API calls for which we haven't approve the specification yet
+- Existing APIs: API calls compliant with specification (approved)
+- APIs with diffs: API calls not compliant with specification
+
+![](./images/2022-11-05-08-21-29.png)
+
+You can also use the API Events page to find traffic which does not respect the schema:
+
+![](./images/2022-10-26-14-37-23.png)
+
+You can review and inspect the deviation to the specification:
+
+![](./images/2022-10-26-14-37-52.png)
+
+You will find that this particular API call does not respect the generated schema - several parameters are missing. The specification deviation is due as different `reviews` application releases are deployed and load balanced. One release is missing the stars and color properties and another one is missing the color property.

README.md

@@ -4,6 +4,7 @@
 
 Get your hands on APIClarity. You will find instructions to:
 - [Install a dedicated kubernetes cluster with Istio (service mesh) and Calico (CNI)](01.kubernetes-setup.md)
-- [Install APIClarity](02.apiclarity-setup.md)
-- [Run an application (bookinfo) and analyse the API traffic using APIClarity](03.application-api-analysis.md)
+- [Deploy Bookinfo application](02.application-deployment.md)
+- [Install APIClarity](03.apiclarity-setup.md)
+- [Use APIClarity for API analysis](04.apiclarity-analysis.md)