From d8ec1371e000d45f5d059d35da2ebf2ee070fd33 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 4 Apr 2024 06:41:02 -0700 Subject: [PATCH] docs: clarify Argo vs Keptn applications (#3385) Signed-off-by: Meg McRoberts Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Co-authored-by: Florian Bacher --- .../multi-stage-delivery-using-gitops.md | 85 ++++++++++--------- 1 file changed, 47 insertions(+), 38 deletions(-) diff --git a/docs/blog/posts/multi-stage-delivery-using-gitops.md b/docs/blog/posts/multi-stage-delivery-using-gitops.md index 44696f2b22..2e256fbc2e 100644 --- a/docs/blog/posts/multi-stage-delivery-using-gitops.md +++ b/docs/blog/posts/multi-stage-delivery-using-gitops.md @@ -19,7 +19,7 @@ when something goes wrong in one of the deployment stages. Keptn helps to address this challenge by providing a distributed OpenTelemetry trace that encompasses all deployment stages and contains all relevant information, -such as the git commit ID that triggered the deployment of a workload. +such as the Git commit ID that triggered the deployment of a workload. For example, if the evaluation of a load test in one of the deployment stages is failing, the distributed trace generated by Keptn contains details about the result of the evaluation, as well as a link to the @@ -42,18 +42,19 @@ For this, we are using the following technologies: - The new [KeptnAppContext](../../docs/reference/crd-reference/appcontext.md) resource - that allows to pass metadata to the generated deployment traces, and define a `promotion` - task that is executed once the application is deployed and all post deployment checks have been + that can pass metadata to the generated deployment traces + and define a `promotion` task that is executed + once the application is deployed and all post deployment checks have been executed successfully. - [ArgoCD](https://argoproj.github.io/cd/) as a GitOps tool. In addition to automatically synchronising the cluster with the desired - state of the cluster, ArgoCD also adds metadata (such as the git commit ID - that triggered the last sync) to the `KeptnAppContext` CRD. + state of the cluster, ArgoCD also adds metadata (such as the Git commit ID + that triggered the last sync) to the `KeptnAppContext` resource. - [GitHub Actions](https://github.com/features/actions): The GitOps repository is hosted on GitHub so we can use GitHub Actions to implement the promotion of an artifact from one stage to the next. We do this by running a workflow that creates the pull requests for updating the - application manifests in the different stages. + ArgoCD `Application` resource in the different stages. - [Helm](https://helm.sh): The configuration of the application for each stage is maintained via two separate Helm charts, one for each stage. - [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)/[Jaeger](https://www.jaegertracing.io): @@ -70,7 +71,8 @@ We are going to do the following: 1. Set up the environment by: 1. Setting up a GitHub repository with an access token, GitHub, workflows, and GitHub actions 1. Preparing a Kubernetes namespace for each stage (`dev` and `prod`) - 1. Preparing the ArgoCD applications with an appropriate Helm chart for each + 1. Preparing the ArgoCD `Application` resources + with an appropriate Helm chart for each 1. Applying labels to associate the `Deployment` resource with the `KeptnWorkload` resource 1. Defining Keptn pre-/post-deployment checks and tasks 1. Defining the metadata to be passed through the deployment traces @@ -89,7 +91,7 @@ with each other. ### Set up the GitHub repository First things first, since we talk about GitOps in this article, we need -a git repository to host the Helm chart of our application. +a Git repository to host the Helm chart of our application. We use GitHub in this example, which allows us to use GitHub Actions to implement the promotion from `dev` to `production`. @@ -113,8 +115,9 @@ step lets us avoid granting the container any write permissions to the repository. Instead, we use an access token with a restricted set of permissions, -so we can use of GitHub's [fine-grained access tokens](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/) -to restrict the permissions to only be able to trigger workflow actions, +so we can use GitHub's +[fine-grained access tokens](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/) +to restrict the permissions to only allow triggering workflow actions, exclusively within our GitOps repository. The required permissions are highlighted in the screenshot below: @@ -156,7 +159,7 @@ kubectl annotate namespace simple-go-prod keptn.sh/lifecycle-toolkit=enabled ``` The promotion task that triggers the action to -create a pull request for promoting an application version +create a pull request for promoting an ArgoCD `Application` from `dev` to `production` will be executed in the `simple-go` namespace. Therefore, we need to create a secret containing the GitHub personal access token we created earlier, using the following command: @@ -168,36 +171,39 @@ GH_API_TOKEN= kubectl create secret generic github-token -n simple-go --from-literal=SECURE_DATA="{\"githubRepo\":\"${GH_REPO}\",\"githubRepoOwner\":\"${GH_REPO_OWNER}\",\"apiToken\":\"${GH_API_TOKEN}\"}" ``` -### Prepare the ArgoCD applications +### Prepare the ArgoCD Application resources The next step is to -create the ArgoCD applications in our cluster. +create the ArgoCD +[Application](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#applications) +resources in our cluster. Each stage of our application (`dev` and `prod`) is -represented by a separate ArgoCD application that points to -a Helm chart for the respective stage. -The Helm charts can be found in our [GitOps repository](https://github.com/bacherfl/keptn-analysis-demo) +represented by a separate ArgoCD `Application` resource +that points to a Helm chart for the respective stage. +The Helm charts can be found in our +[GitOps repository](https://github.com/bacherfl/keptn-analysis-demo) in the following sub folders: - `simple-app/chart-dev`: Contains the Helm chart for the application in the `dev` stage - `simple-app/chart-prod`: Contains the Helm chart for the application in the `prod` stage -The ArgoCD applications are created by applying the following manifest: +The ArgoCD `Applications` are created by applying the following manifest: ```yaml title="argo-apps.yaml" {% include "./multi-stage-delivery-using-gitops/argo-apps.yaml" %} ``` -This manifest contains the definitions for the two ArgoCD applications +This manifest contains the definitions for the two ArgoCD `Applications`, each of which points to one of the helm charts mentioned earlier. In addition to that, the `$ARGOCD_APP_REVISION` environment variable -is used to get access to the git commit ID that triggered -a new deployment of our applications. +is used to get access to the Git commit ID that triggered +a new deployment of our ArgoCD `Applications`. This ID is passed through to the Helm chart. Keptn uses this as metadata for a `KeptnApp` deployment. After applying the file, using `kubectl apply -f argo-apps.yaml`, -ArgoCD begins to synchronize the state of the applications, -meaning that the Helm charts for the applications are applied to the +ArgoCD begins to synchronize the state of the `Applications`, +meaning that the Helm charts for the `Applications` are applied to the cluster. While this is happening, let's have a closer look at the actual content of the Helm charts. @@ -220,35 +226,39 @@ To correctly associate the `Deployment` resource with the `KeptnWorkload` resour the following labels are set: - `app.kubernetes.io/name`: The name of the `KeptnWorkload` that should be associated with the `Deployment`. -- `app.kubernetes.io/part-of`: The name of the `KeptnApp` containing the two workloads. +- `app.kubernetes.io/part-of`: The name of the `KeptnApp` resource containing the two workloads. - `app.kubernetes.io/version`: The version for the related `KeptnWorkload`. +For more information about setting these labels for Keptn, see +[Basic annotations](../../docs/guides/integrate.md#basic-annotations). + #### Pre and post-deployment tasks In addition to the labels which define the `KeptnWorkload`, we also use -the `keptn.sh/post-deployment-tasks` to define a post-deployment task for the -workload. +the `keptn.sh/post-deployment-tasks` label +to define a post-deployment task for the workload. The task defined here (`wait-for-monitoring`) ensures that the Prometheus target for the workload is available, before proceeding with -the execution of the load tests of the overall application. +the execution of the load tests of the overall Keptn application. #### KeptnAppContext The `KeptnAppContext` provides two important capabilities for multi-stage delivery: -- Define tasks and evaluations that run before or after the application deployment -- Add metadata and links to traces for a specific application. +- Define tasks and evaluations that run before or after the Keptn application deployment +- Add metadata and links to traces for a specific ArgoCD `Application`. This enables you to enrich your traces with additional information that you can use to understand and analyze the performance of your applications -which looks as follows: + +The `KeptnAppContext` manifest looks as follows: ```yaml {% include "./multi-stage-delivery-using-gitops/keptnappcontext.yaml" %} ``` This resource contains a list of pre- and post-deployment checks -for the complete application. +for the complete `KeptnWorkload` application. In the `pre-deployment` phase, the task `wait-for-monitoring` ensures the Prometheus installation in our cluster is available. If this is not the case, it would not be wise to deploy a new @@ -295,7 +305,7 @@ by ArgoCD, using the `$ARGOCD_APP_REVISION` environment variable. The Helm chart of the `prod` stage is rather similar to the one for the `dev` stage, but differs in the `values.yaml`, and the -`KeptnAppContext`. +`KeptnAppContext` resource. First, let's inspect the `values.yaml` in `prod`: ```yaml @@ -316,8 +326,7 @@ specify the workload versions that should be deployed in `prod`. In our example, the value of the `traceParent` is the span ID of the `promotion` phase of the `dev` stage. -To pass this property to Keptn, the `spanLinks` property of the `KeptnAppContext` -below is used: +To pass this property to Keptn, we use the `spanLinks` property of the `KeptnAppContext` resource: ```yaml {% include "./multi-stage-delivery-using-gitops/keptnappcontext-prod.yaml" %} @@ -333,7 +342,7 @@ Now that the GitOps repository and the ArgoCD application are set up, let's have a closer look at how a new service version would make its way into `dev` and then into `prod`. To do this, the `values.yaml` file for the `dev` stage is edited to -change th service version from `v1` to `v2`: +change the service version from `v1` to `v2`: ![Updating the dev stage](./multi-stage-delivery-using-gitops/updating-dev.png) @@ -371,8 +380,8 @@ Jaeger as well: ![Deployment trace prod](./multi-stage-delivery-using-gitops/deployment-trace-prod.png) As we can see in the deployment trace, we also have the commitID that triggered -the deployment in that stage, just like we also had in `dev`, but -in addition to that the trace also contains a reference +the deployment in that stage, just like we also had in `dev`, +but the trace also contains a reference to the span ID of the `promotion` phase in `dev`. This ultimately allows us to trace back the deployment of a particular service version across multiple stages, right to the commit that @@ -383,8 +392,8 @@ introduced a change to the affected service. Time to wrap up what we have learned in this example. We have seen how the `KeptnAppContext` resource can be used to define pre-/post-deployment checks and to -pass important metadata - in our example, using ArgoCD, -the git commit ID that triggered a new deployment - +pass important metadata -- in our example, using ArgoCD, +the Git commit ID that triggered a new deployment -- to be added as attributes to the deployment traces generated by Keptn. Then, to gain observability not only for an isolated stage,