fluxcd / flux2

This documentation outlines a step-by-step guide to deploying the FluxCD/Flux2 project in a production environment. The deployment process emphasizes best practices for managing Kubernetes clusters and leveraging GitOps principles.

Prerequisites

  • A running Kubernetes cluster.
  • kubectl installed and configured.
  • Access to a Git repository for storing configuration.

Step 1: Build Flux CLI

The first step in deploying Flux is building the Flux CLI. The following Dockerfile is used to create an image with the Flux command line tool.

FROM alpine:3.19 as builder

RUN apk add --no-cache ca-certificates curl

ARG ARCH=linux/amd64
ARG KUBECTL_VER=1.28.6

RUN curl -sL https://storage.googleapis.com/kubernetes-release/release/v${KUBECTL_VER}/bin/${ARCH}/kubectl \
    -o /usr/local/bin/kubectl && chmod +x /usr/local/bin/kubectl && \
    kubectl version --client=true

FROM alpine:3.19 as flux-cli

RUN apk add --no-cache ca-certificates

COPY --from=builder /usr/local/bin/kubectl /usr/local/bin/
COPY --chmod=755 flux /usr/local/bin/

USER 65534:65534
ENTRYPOINT [ "flux" ]

Step 2: Set Up Environment

Utilize the Makefile to set up the necessary environment before deploying Flux. The Makefile contains multiple functions relevant to setting up and managing the Kubernetes cluster.

make setup-kind
make install

Explanation of Functions

  • setup-kind: Sets up a local Kubernetes cluster using Kind.
  • install: Installs the Flux components onto your cluster.

Refer to the Makefile for additional commands like test-with-kind, cleanup-kind, and e2e to perform various tasks as needed.

Step 3: Bootstrap Flux in Your Cluster

With Flux CLI installed, bootstrap Flux to your Kubernetes cluster. This command initializes the Flux system, connecting it to your Git repository.

flux bootstrap github \
  --owner=<GITHUB_USER> \
  --repository=<REPO_NAME> \
  --branch=main \
  --path=clusters/production
  • Replace <GITHUB_USER> with your GitHub username.
  • Replace <REPO_NAME> with the name of your repository.

Step 4: Deploy Your Configuration

Once Flux is bootstrapped, push your Kubernetes manifests to the specified path in your Git repository. Use Kustomize to manage configurations, as demonstrated in the following example Kustomization files.

Example Kustomization File

The following snippet from a Kustomize file for the source controller illustrates the structure necessary:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/fluxcd/source-controller/releases/download/v1.2.4/source-controller.crds.yaml
- https://github.com/fluxcd/source-controller/releases/download/v1.2.4/source-controller.deployment.yaml
- account.yaml
transformers:
- labels.yaml
patches:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: source-controller
  path: patch.yaml

Applying Patches

You may need to apply patches to your deployments to customize their specifications. For instance:

- op: add
  path: /spec/template/spec/containers/0/args/0
  value: --events-addr=http://notification-controller.flux-system.svc.cluster.local./

The above patch modifies the source-controller to set a specific events address.

Step 5: Configure Controllers

Deployments involving controllers such as the image reflector or image automation can also be defined within Kustomize files. Here’s a basic setup for the image-automation-controller:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/fluxcd/image-automation-controller/releases/download/v0.37.1/image-automation-controller.crds.yaml
- https://github.com/fluxcd/image-automation-controller/releases/download/v0.37.1/image-automation-controller.deployment.yaml
- account.yaml
transformers:
- labels.yaml
patches:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: image-automation-controller
  path: patch.yaml

This allows you to customize how Flux interacts with various repositories and handles updates.

Step 6: Verify Installation

Monitor the Flux components to ensure they are running correctly:

kubectl get pods -n flux-system

Conclusion

Deploying FluxCD/Flux2 in a production environment requires careful configuration and monitoring. Following the outlined steps ensures an effective deployment leveraging the strengths of GitOps for continuous delivery within Kubernetes.

References

  • Dockerfile and Makefile associated with the project provide necessary instructions and code examples.
  • Detailed configuration within Kustomization files allows for modular and scalable application deployment.

This documentation synthesizes a clear pathway to successfully deploying Flux in production using standard tools and configurations.