From 3b093bc5b8c020d06d624f008ea18cbc18835ae6 Mon Sep 17 00:00:00 2001 From: odubajDT <93584209+odubajDT@users.noreply.github.com> Date: Fri, 5 Apr 2024 11:47:00 +0200 Subject: [PATCH] docs: create use-case for integration with Flux (#3380) Signed-off-by: odubajDT Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Co-authored-by: Meg McRoberts Co-authored-by: Moritz Wiesinger --- .github/actions/spelling/expect.txt | 3 + docs/docs/use-cases/assets/flux/app.yaml | 57 +++++ .../assets/flux/flux-kustomization.yaml | 17 ++ .../use-cases/assets/flux/gitrepository.yaml | 10 + .../docs/use-cases/assets/flux/kustomize.yaml | 4 + docs/docs/use-cases/flux.md | 204 ++++++++++++++++++ mkdocs.yml | 1 + 7 files changed, 296 insertions(+) create mode 100644 docs/docs/use-cases/assets/flux/app.yaml create mode 100644 docs/docs/use-cases/assets/flux/flux-kustomization.yaml create mode 100644 docs/docs/use-cases/assets/flux/gitrepository.yaml create mode 100644 docs/docs/use-cases/assets/flux/kustomize.yaml create mode 100644 docs/docs/use-cases/flux.md diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index c6cd093058..745390b030 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -186,6 +186,7 @@ fieldpath fieldref finalizer flyout +fluxcd fontawesome ftp fullname @@ -208,6 +209,7 @@ ginkgotypes giscus Gitlab gitops +gitrepository gke glasskube gms @@ -224,6 +226,7 @@ goodanalysis goodmetric goodtaskdefinition google +gotk govulncheck Grabner grafana diff --git a/docs/docs/use-cases/assets/flux/app.yaml b/docs/docs/use-cases/assets/flux/app.yaml new file mode 100644 index 0000000000..aff9344b49 --- /dev/null +++ b/docs/docs/use-cases/assets/flux/app.yaml @@ -0,0 +1,57 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: podtato-kubectl + annotations: + keptn.sh/lifecycle-toolkit: "enabled" +--- +apiVersion: lifecycle.keptn.sh/v1beta1 +kind: KeptnAppContext +metadata: + name: podtato-head +spec: + preDeploymentTasks: + - hello-task +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-entry + labels: + app: podtato-head +spec: + selector: + matchLabels: + component: podtato-head-entry + template: + metadata: + labels: + component: podtato-head-entry + annotations: + keptn.sh/app: podtato-head + keptn.sh/workload: podtato-head-entry + keptn.sh/version: 0.1.0 + keptn.sh/pre-deployment-tasks: hello-task + keptn.sh/post-deployment-tasks: hello-task + spec: + terminationGracePeriodSeconds: 5 + containers: + - name: server + image: ghcr.io/podtato-head/entry:latest + imagePullPolicy: Always + ports: + - containerPort: 9000 + env: + - name: PODTATO_PORT + value: "9000" +--- +apiVersion: lifecycle.keptn.sh/v1beta1 +kind: KeptnTaskDefinition +metadata: + name: hello-task +spec: + deno: + inline: + code: | + console.log('hello'); + retries: 3 diff --git a/docs/docs/use-cases/assets/flux/flux-kustomization.yaml b/docs/docs/use-cases/assets/flux/flux-kustomization.yaml new file mode 100644 index 0000000000..a34c4013ea --- /dev/null +++ b/docs/docs/use-cases/assets/flux/flux-kustomization.yaml @@ -0,0 +1,17 @@ +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: app + namespace: flux-system +spec: + interval: 30m0s + path: ./apps/dev + prune: true + retryInterval: 2m0s + sourceRef: + kind: GitRepository + name: app + namespace: flux-system + targetNamespace: podtato-kubectl + timeout: 3m0s + wait: true diff --git a/docs/docs/use-cases/assets/flux/gitrepository.yaml b/docs/docs/use-cases/assets/flux/gitrepository.yaml new file mode 100644 index 0000000000..138e0040b6 --- /dev/null +++ b/docs/docs/use-cases/assets/flux/gitrepository.yaml @@ -0,0 +1,10 @@ +apiVersion: source.toolkit.fluxcd.io/v1 +kind: GitRepository +metadata: + name: app + namespace: flux-system +spec: + interval: 1m0s + ref: + branch: main + url: diff --git a/docs/docs/use-cases/assets/flux/kustomize.yaml b/docs/docs/use-cases/assets/flux/kustomize.yaml new file mode 100644 index 0000000000..30ecf93b91 --- /dev/null +++ b/docs/docs/use-cases/assets/flux/kustomize.yaml @@ -0,0 +1,4 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: + - app.yaml diff --git a/docs/docs/use-cases/flux.md b/docs/docs/use-cases/flux.md new file mode 100644 index 0000000000..319182f9ba --- /dev/null +++ b/docs/docs/use-cases/flux.md @@ -0,0 +1,204 @@ +--- +comments: true +--- + +# Deploying Applications with Flux and Keptn + +[Flux](https://fluxcd.io/) +is a tool that keeps Kubernetes clusters synchronized with sources +of configuration (such as Git repositories) and automates updates to +the configuration when new code is deployed. + +This section shows how to add Keptn +[pre- and post-deployment tasks](../guides/tasks.md) +to an existing Flux use case that runs +[pre and post-deployment jobs with Flux](https://fluxcd.io/flux/use-cases/running-jobs/). +Adding Keptn makes it simpler and more straight-forward +to run the Flux pre and post-deployment jobs +and provides added observability out of the box. + +## High-level structure of the Git repository + +Flux uses a GitOps approach for continuous delivery. +The Git +repository structure for our use case looks like the following: + +```markdown +├── apps +│ └── dev +│ ├── podtato-head.yaml +│ └── kustomize.yaml +└── clusters + └── dev + ├── flux-system + │ ├── gotk-components.yaml + │ ├── gotk-sync.yaml + │ └── kustomize.yaml + ├── podtato-head-source.yaml + └── podtato-head-kustomization.yaml +``` + +The `apps` directory contains application manifests, that will be deployed. +The `clusters` directory contains Flux configuration manifests and custom +resources, that are needed for the delivery. +The `apps` and `clusters` directories can live in two separate repositories, +but for simplicity of this excercise, we will keep them in a single one. + +You see that the Keptn runs pre/post-deployment tasks +rather than using the Flux `pre-deploy` and `post-deploy` directories in the Git repository. +The Keptn process is easier to implement +and contains more information than the Flux jobs do. + +## Set up your environment + +Before we start, you need to install Flux CLI on your local machine and Keptn on your cluster. +You can find the installation instructions for Keptn [here](../installation/index.md) +and for Flux [here](https://fluxcd.io/flux/installation/). + +After successfully installing Flux CLI and Keptn, you need to +retrieve your Git repository credentials. +You can use any available Git providers, but be sure to store your `token` +for later usage. +For simplicity, we will use GitHub. + +You then need to +[bootstrap the Git repository](https://fluxcd.io/flux/installation/bootstrap/), +supplying the `token` you saved, +to install Flux in your cluster. +This sets up all necessary Flux structures in the repository. +Use the following command to do this: + +```shell +GITHUB_USER= GITHUB_TOKEN= \ +flux bootstrap github \ + --owner=$GITHUB_USER \ + --repository=podtato-head \ + --branch=main \ + --path=./clusters/dev \ + --personal +``` + +The bootstrap command above does the following: + +* Creates a Git repository `podtato-head` on your GitHub account. +* Adds Flux component manifests to the repository and +creates `./clusters/dev/flux-system/*` structure. +* Deploys Flux components to your Kubernetes Cluster. +* Configures Flux components to track the path `./clusters/dev/` in the repository. + +## Creating the application + +Now it's time to add the Keptn application that defines the Keptn pre- and +post-deployment checks to the repository. + +First, clone the `podtato-head` repository to your local machine. + +Add the following manifests that represent the application into the `podtato-head.yaml` file +and store it in the `./apps/dev/` directory of your repository: + +```yaml +{% include "./assets/flux/app.yaml" %} +``` + +See the Keptn +[CRD reference](../reference/crd-reference/index.md) +documentation for more information about the Keptn resources that are used. +See +[Basic annotations](../guides/integrate.md#basic-annotations) +for a description of the labels and annotations that Keptn uses. +Additionally, create a `kustomize.yaml` file right next to it: + +```yaml +{% include "./assets/flux/kustomize.yaml" %} +``` + +You can commit and push these manifests to the Git repository. + +The application has Keptn pre- and post-deployment tasks defined +in the manifests. +This enhances the +[Flux pre and post-deployment jobs](https://fluxcd.io/flux/use-cases/running-jobs/) +setup with added observability out of the box. + +## Set up continuous delivery for the application + +First, we need to create a Flux +[GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) +resource +pointing to a repository where the application manifests are present. +In this case, it will be our `podtato-head` repository. +To create this resource, we use Flux CLI: + +```shell +flux create source git podtato-head \ + --url= \ + --branch=main \ + --interval=1m \ + --export > ./clusters/dev/podtato-head-source.yaml +``` + +This results in output similar to: + +```yaml +{% include "./assets/flux/gitrepository.yaml" %} +``` + +In the last step, create a Flux +[Kustomization](https://fluxcd.io/flux/components/kustomize/kustomizations/) +resource to deploy the `podtato-head` application to the cluster. +You can create it using the Flux CLI: + +```shell +flux create kustomization podtato-head \ + --target-namespace=podtato-kubectl \ + --source=podtato-head \ + --path="./apps/dev" \ + --prune=true \ + --wait=true \ + --interval=30m \ + --retry-interval=2m \ + --health-check-timeout=3m \ + --export > ./clusters/dev/podtato-head-kustomization.yaml +``` + +which results in output similar to: + +```yaml +{% include "./assets/flux/flux-kustomization.yaml" %} +``` + +Now, commit and push the resources you created in the previous steps. +After pushing them, Flux picks up the configuration and +deploys your application into the cluster. + +## Watch Flux sync of the application + +You can watch the synchronization of the application +using the Flux CLI: + +```shell +$ flux get kustomizations --watch + +NAME REVISION SUSPENDED READY MESSAGE +flux-system main@sha1:4e9c917f False True Applied revision: main@sha1:4e9c917f +podtato-head main@sha1:44154333 False True Applied revision: main@sha1:44154333 +``` + +or using `kubectl`: + +```shell +$ kubectl get keptnappversion -n podtato-head + +NAME APPNAME VERSION PHASE +podtato-head-v0.1.0-6b86b273 podtato-head v0.1.0 Completed +``` + +Each time you update the application, the changes are +synced to the cluster. + +## Possible follow-ups + +You can also set up multi-stage delivery with Flux, +following the steps described for `ArgoCD` in the +[ArgoCD multi-stage delivery with Keptn](../guides/multi-stage-application-delivery.md) +user guide. diff --git a/mkdocs.yml b/mkdocs.yml index fe0e264197..ea8d3ee8eb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -146,6 +146,7 @@ nav: - Day 2 Operations: docs/use-cases/day-2-operations.md - Keptn + HorizontalPodAutoscaler: docs/use-cases/hpa.md - Keptn + KEDA: docs/use-cases/keda.md + - Keptn + Flux: docs/use-cases/flux.md - Keptn for non-Kubernetes deployments: docs/use-cases/non-k8s.md - Components: - docs/components/index.md