Skip to content

Commit

Permalink
docs: create use-case for integration with Flux (#3380)
Browse files Browse the repository at this point in the history
Signed-off-by: odubajDT <[email protected]>
Signed-off-by: odubajDT <[email protected]>
Co-authored-by: Meg McRoberts <[email protected]>
Co-authored-by: Moritz Wiesinger <[email protected]>
  • Loading branch information
3 people authored Apr 5, 2024
1 parent 4407d07 commit 3b093bc
Show file tree
Hide file tree
Showing 7 changed files with 296 additions and 0 deletions.
3 changes: 3 additions & 0 deletions .github/actions/spelling/expect.txt
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,7 @@ fieldpath
fieldref
finalizer
flyout
fluxcd
fontawesome
ftp
fullname
Expand All @@ -208,6 +209,7 @@ ginkgotypes
giscus
Gitlab
gitops
gitrepository
gke
glasskube
gms
Expand All @@ -224,6 +226,7 @@ goodanalysis
goodmetric
goodtaskdefinition
google
gotk
govulncheck
Grabner
grafana
Expand Down
57 changes: 57 additions & 0 deletions docs/docs/use-cases/assets/flux/app.yaml
Original file line number Diff line number Diff line change
@@ -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
17 changes: 17 additions & 0 deletions docs/docs/use-cases/assets/flux/flux-kustomization.yaml
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions docs/docs/use-cases/assets/flux/gitrepository.yaml
Original file line number Diff line number Diff line change
@@ -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: <git-repo-url>
4 changes: 4 additions & 0 deletions docs/docs/use-cases/assets/flux/kustomize.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- app.yaml
204 changes: 204 additions & 0 deletions docs/docs/use-cases/flux.md
Original file line number Diff line number Diff line change
@@ -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=<user-name> GITHUB_TOKEN=<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=<git-repo-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.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3b093bc

Please sign in to comment.