Merge pull request #77 from agardnerIT/codespaces-docs

Codespaces and website docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,29 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v1
+
+      - name: Install Python and Pip Packages
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11.4'
+          cache: 'pip'
+
+      - name: "Install Dependencies"
+        run: pip install -r requirements.txt
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -2,7 +2,7 @@
 
 This masterclass shows how to set up a full progressive delivery platform using open source tooling
 
-The massterclass uses a very simple node.js demo application
+The masterclass uses a very simple node.js demo application
 
 You can find the detailed walkthrough instructions [here](/walkthrough/readme.md)
 

demoapp/gitops/manifests/demo-application/deployment.yaml

@@ -18,7 +18,7 @@ spec:
         app.kubernetes.io/version: 1.2.0
         app: demoapp
         keptn.sh/post-deployment-tasks: load-test
-        keptn.sh/post-deployment-evaluations: demoapp-healty-check
+        keptn.sh/post-deployment-evaluations: demoapp-healthy-check
       # This is the annotation for OpenFeature Operator
       annotations:     
         openfeature.dev/enabled: "true"

docs/1-create-codespace.md

@@ -0,0 +1,13 @@
+# 1. Create a Codespace
+
+In your fork, go to "Code" then switch to the "Codespaces" tab and click "Create codespace on main"
+
+![start codespaces](assets/start-codespace.png)
+
+A new tab will open and codespace creation will begin.
+
+![codespace setup](assets/codespace-setup.png)
+
+When the codespace is active, you will see a VSCode user interface. All code and tools are preinstalled into this environment. You are now ready to begin.
+
+➡️ Next: [Create a Kubernetes Cluster and Install Software](2-create-cluster.md) ➡️

docs/2-create-cluster.md

@@ -0,0 +1,48 @@
+# 2. Create a Kubernetes Cluster and Install Software
+
+Click the magifying glass icon in the left hand menu and perform a find and replace
+
+- Find: `{{ temp_site_url }}`
+
+- Replace with: `YourGitHubUsernameHere/progressivedelivery-masterclass`
+
+![find and replace](assets/find-replace.png)
+
+Click the replace icon ![replace icon](assets/replace-icon.png) and you'll see a warning (the number of occurrences and your text will be different)
+
+![replace warning](assets/replace-warning.png)
+
+Commit your changes to your repository:
+
+```shell
+git add -A
+git commit -m "use my forked repo"
+git push
+```
+
+In the terminal window, type:
+
+```
+make create
+```
+
+This command will:
+
+- Create a new kubernetes cluster, exposing all the required ports
+- Install ArgoCD
+- Patch the ArgoCD ConfigMap so that Argo and Keptn work together to properly inform of Argo application health status
+  - Add a NodePort service so we can access the Argo user interface
+  - Trigger the installation of an Argo "App of Apps" to install our applications using ArgoCD. This will be explained in detail later.
+  - Print the ArgoCD user interface password to the terminal
+
+![make create](assets/make-create.png)
+
+When the installation process is complete, you should see the Argo password (a random string of characters) and the following message:
+
+```shell
+🎉 Installation Complete! 🎉
+```
+
+Copy the ArgoCD password and proceed with the next steps.
+
+➡️ Next: [Access ArgoCD](3-access-argo.md) ➡️

docs/3-access-argo.md

@@ -0,0 +1,75 @@
+# 3. Access ArgoCD
+
+Switch to the "Ports" tab in the terminal window. Hover over the entry for ArgoCD and click the "globe" icon
+
+A new tab will open and the ArgoCD login screen will be displayed
+
+## Log into ArgoCD.
+
+The username is `admin` and the password is the random string you copied before.
+
+If you forget the Argo password, it can be retrieved with:
+
+```
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
+```
+
+![access argo](assets/access-argo.png)
+![argo login](assets/argo-login.png)
+
+## Wait for Installation
+
+The platform stack is being installed and progress can be tracked via the `progressive-delivery-masterclass` application. This application is an "app of apps" meaning it is an application which installs other applications in turn.
+
+The platform stack will not be ready until `progressive-delivery-masterclass` is green.
+
+![pdm app installation](assets/pdm-argo-installing.png)
+
+There are many applications which make up the platform. The installation will take a few moments so let's use the time to understand what's happening.
+
+The platform is built from the following applications:
+
+- Kubernetes
+- ArgoCD
+- Cert Manager
+- Keptn Lifecycle Toolkit
+- Grafana
+- Prometheus
+- Jaeger Operator (installs Jaeger)
+- OpenFeature Operator (installs flagd)
+- OpenTelemetry Collector
+
+These applications are all being deployed at different times, as "bundles" or "waves", as Argo calls them.
+
+The waves are processed in order, lowest first.
+
+### Wave -1
+- Argo configuration
+
+### Wave 0
+- Cert Manager
+- Ingress NGINX
+
+### Wave 2
+- Keptn Lifecycle Toolkit
+- OpenFeature Operator
+
+### Wave 3
+- Jaeger Operator
+- OpenTelemetry Collector
+- Prometheus
+- Grafana
+
+### Wave 4
+- Feature flags configuration
+
+### Wave 10
+- Demo Application
+
+## Wait for green
+
+Wait until the `progressive-delivery-masterclass` application is green. This means that the stack is ready.
+
+![system synced](assets/pdm-synced.png)
+
+➡️ Next: [Explanation of the System](4-explainer.md) ➡️

docs/4-explainer.md

@@ -0,0 +1,87 @@
+# 4. What Just Happened?
+
+The system is now successfully running. If you look at the `demo-application` in Argo you will see a few things:
+
+1. The `demoapp` pod is runnning
+1. The `demoapp` pod belongs to a deployment
+1. The deployment is healthy and has a service attached and an ingress
+
+All of this means that the application is accessible.
+
+In the codespace, go to the `Ports` tab again, hover over the `DemoApp` and click the Globe icon to view the demo application user interface.
+
+![access demo app](assets/access-demo-app.png)
+![demo app UI](assets/demo-app-ui.png)
+
+Inside `demo-application` the Argo application, you will also notice a some Keptn related items:
+
+1. A `KeptnWorkload` has been created
+1. An instance of a `KeptnWorkload` (a `KeptnWorkloadInstance`) also exists
+1. A `KeptnTask` entity called `post-load-test` exists
+1. The `post-load-test` created a `Job` and that `Job` created a `pod`
+1. A `KeptnEvaluation` entity called `post-eval-demoapp-healthy` exists
+
+![demo app argo keptn resources](assets/demo-app-argo-keptn.png)
+
+## So what is going on?
+
+The progressive delivery stack includes the Keptn.
+
+Keptn performs multiple functions:
+
+1. Automatically calculating deployment DORA metrics for deployments it "manages"
+1. Automatically creates OpenTelemetry traces for deployments it "manages"
+1. Adds the ability to perform pre-deployment and post-deployment SLO evaluations and tasks (explained below)
+1. Acts as a central on-cluster metrics cache so operators can retrieve metrics without the need to know their source and other on-cluster tools (such as HPA) can utilise these metrics in a generic way
+
+An application is "managed" by Keptn as such:
+
+1. The namespace of the application is annotated ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/namespace.yaml#L7))
+1. 3x annotations (or labels) are added to the application. These are the Kubernetes recommended labels `part-of`, `name` and `version` ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/deployment.yaml#L16-L18))
+
+![demo app namespace annotated](assets/demo-app-ns-annotated.png)
+![demo app 3 annotations](assets/demo-app-part-of-version-name-annotations.png)
+
+With these 4 annotations, Keptn is able to customise the Kubernetes scheduler and thus "know" when a pod is ready to be schedule and then when a pod is successfully schedule. This is how Keptn generates DORA metrics.
+
+Keptn calculates the length of time each "managed" deployment takes. Later you will see these DORA metrics in Grafana.
+
+## KeptnTasks
+
+Another capability of Keptn are pre and post deployment evaluations and tasks. These also rely on annotations and CRDs. First, let's explore `KeptnTasks`
+
+* Define a `KeptnTask` which is a custom piece of logic that you want to perform during the pod scheduling lifecycle ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/keptn.yaml#L1)).
+    This task starts a `k6` container and executes a load test.
+
+![keptn task](assets/keptn-task.png)
+
+* Add an annotation or label to the deployment which denotes *when* this task should occur, before pod scheduling or after pod scheduling ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/deployment.yaml#L20)).
+    This configuration tells Keptn that a `KeptnTask` called `load-test` should be executed after the deployment has completed.
+
+![keptn post tasks](assets/keptn-post-tasks.png)
+
+`KeptnTask`s are executed as Kubernetes Jobs so the above configuration explains why we see the `KeptnTask`, `Job` and a `Pod` in ArgoCD.
+
+
+
+## KeptnEvaluations
+
+As explained previously the Keptn Lifecycle Toolkit also provides a way to run SLO evaluations of metrics before and / or  after deployment.
+
+* Create a `KeptnMetricsProvider` which defines *where* the metric should be retrieved from ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/keptn.yaml#L15))
+
+![keptn metrics provider](assets/keptn-metrics-provider.png)
+
+* Create a `KeptnMetric` which defines *which* metric should be pulled and how often ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/keptn.yaml#L24))
+
+![keptn metric](assets/keptn-metric.png)
+
+* Create a `KeptnEvaluationDefinition` to define the acceptance criteria. In other words, for a metric, what is the acceptable threshold ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/keptn.yaml#L35))
+
+![keptn metric](assets/keptn-evaluation-definition.png)
+
+* Add a label to the deployment to inform Keptn that a given `KeptnEvaluationDefinition` should occur either before or after deployment. In this case, after (post) deployment ([see this here](https://github.com/dynatrace-oss/progressiveDelivery-masterclass/blob/main/gitops/manifests/demo-application/deployment.yaml#L21))
+
+![keptn evaluation label](assets/keptn-eval-label.png)
+
+➡️ Next: [View Telemetry](5-view-telemetry.md) ➡️

docs/5-view-telemetry.md

@@ -0,0 +1,30 @@
+# View Deployment Telemetry
+
+Keptn emits DORA metrics and OpenTelemetry traces for every deployment.
+
+In the codespace, go to the `Ports` tab and open Grafana.
+
+Login with these details:
+
+- Username: `admin`
+- Password: `admin`
+
+* Go to "Dashboards > Browse"
+* Open the "Keptn Applications" dashboard in the "Default" folder
+
+You should see:
+
+* 1 successful deployment
+* Zero failed deployments
+* Zero active deployments (this metrics tracks currently-in-progress deployments)
+* Zero data for "time between deployments" (this is calculated when there are > 1 deployments)
+* A deployment time (in seconds) for `V1.1`
+* An OpenTelemetry trace for the `V1.1` deployment
+
+![telemetry 1](assets/telemetry-1.png)
+
+Clicking the OpenTelemetry trace displays the end-to-end timings of the deployment as ArgoCD actioned it.
+
+![telemetry 2](assets/telemetry-2.png)
+
+➡️ Next: [Deploy a Slow Version of the Application](6-deploy-slow-version.md) ➡️

docs/6-deploy-slow-version.md

@@ -0,0 +1,40 @@
+# 5. Deploy a Slow Version of the Application
+
+A slow version of the application, `V2` will now be deployed.
+
+The same sequence of events will occur:
+
+* The pod will be scheduled
+* A post-deployment task (load test) will run
+* A post-deployment evaluation will be requested
+
+This time though, the application is too slow, causing the `k6` response time conditions in the load test to fail.
+
+Because the load test fails, the post-deployment evaluation will not be executed.
+
+The pod will be running successfully (we have not tampered with the pod scheduling) but we now know that the application is unhealthy and can take action.
+
+You will see this in argo, the `V2` pod will be running, but the Keptn resources will be unhealthy.
+
+![application v2 failure](assets/app-v2-failure.png)
+
+## Rollout V2
+
+In the codespace:
+
+* Open the file `gitops/manifests/demo-application/deployment.yaml`
+* Update the `app.kubernetes.io/version` label to `V2` and the image tag from `V1.1` to `V2`
+
+Commit the changes to GitHub (use the commands below if you don't know how).
+
+```shell
+git add gitops/manifests/demo-application/deployment.yaml
+git commit -m "rollout V2"
+git push
+```
+
+In ArgoCD, find the `demo-application` and click `Refresh`.
+
+The change will be detected and Argo will automatically begin the rollout of your update.
+
+![demo app sync](assets/demo-app-syncing.png)

docs/index.md

@@ -0,0 +1,25 @@
+# Progressive Delivery Masterclass
+
+## Introduction
+
+This masterclass guides illustrates how to use various cloud-native tools to gain better observability and management of your cloud-native software deployment.
+
+- [Kubernetes](https://kubernetes.io)
+- [ArgoCD](https://argo-cd.readthedocs.io/en/stable/)
+- [Keptn](https://keptn.sh)
+- [OpenFeature](https://openfeature.dev)
+- [flagd](https://flagd.dev)
+
+The class will be executed from a GitHub Codespace, so there is nothing to install on your machine.
+
+You will need a GitHub.com account to follow this class.
+
+## Preparation
+
+Start the masterclass by forking [this repository](https://github.com/dynatrace-oss/progressivedelivery-masterclass) into your GitHub account.
+
+All commands should be executed in **your fork**.
+
+## Create a Codespace
+
+Start the tutorial by creating a [codespace in your fork](1-create-codespace.md).

gitops/manifests/demo-application/deployment.yaml

@@ -18,7 +18,7 @@ spec:
         app.kubernetes.io/version: 1.2.0
         app: demoapp
         keptn.sh/post-deployment-tasks: load-test
-        keptn.sh/post-deployment-evaluations: demoapp-healty-check
+        keptn.sh/post-deployment-evaluations: demoapp-healthy-check
       # This is the annotation for OpenFeature Operator
       annotations:     
         openfeature.dev/enabled: "true"

gitops/manifests/demo-application/keptn.yaml

@@ -37,7 +37,7 @@ spec:
 apiVersion: lifecycle.keptn.sh/v1alpha3
 kind: KeptnEvaluationDefinition
 metadata:
-  name: demoapp-healty-check
+  name: demoapp-healthy-check
   namespace: demo
 spec:
   objectives: