fluxcd / flux2-kustomize-helm-example

GitOps for https://github.com/fluxcd/flux2-kustomize-helm-example/

This repository demonstrates a multi-cluster GitOps setup using Flux and Kustomize. It leverages the principle of Infrastructure as Code by managing Kubernetes resources through Git.

The repository is structured into the following main directories:

  • apps: Contains Helm releases with cluster-specific configurations.

    • base: Defines base configurations for Helm releases shared across clusters.
    • production: Contains production-specific Helm release values.
    • staging: Contains staging-specific Helm release values.

  • infrastructure: Houses common infrastructure tools like Ingress-Nginx and Cert-Manager.

    • configs: Contains Kubernetes resources like Let’s Encrypt issuer.
    • controllers: Holds controller definitions.

  • clusters: Contains Flux configurations for each cluster.

    • production: Holds the Flux Kustomization definitions for the production cluster.
    • staging: Holds the Flux Kustomization definitions for the staging cluster.

GitOps Workflow

  1. Bootstrap Flux:

    • Run the flux bootstrap github command in each cluster with the appropriate context and path to the relevant cluster directory within the clusters folder.
    • This creates Flux components in the specified cluster directory (e.g., clusters/staging/flux-system) and generates a deploy key with read-only access on GitHub for pulling changes.
    • Source: README.md

  2. Apply Kustomization Definitions:

    • Flux uses Kustomization definitions to manage deployments.
    • clusters/staging/apps.yaml defines the Kustomization for the staging cluster.
    • dependsOn ensures the infrastructure items (infra-configs) are created before deploying applications.
    • Source: README.md

  3. Manage Helm Releases:

    • Flux utilizes HelmRepository and HelmRelease custom resources to manage Helm deployments.
    • apps/base/podinfo/repository.yaml defines the Helm repository for the podinfo chart.
    • apps/base/podinfo/release.yaml defines the HelmRelease for podinfo with common values for both clusters.
    • apps/staging/kustomization.yaml includes a Kustomize patch with staging-specific values.
    • apps/production/kustomization.yaml includes a Kustomize patch with production-specific values.
    • Source: README.md

  4. Sync and Update Resources:

    • Flux continuously monitors the Git repository and automatically reconciles changes in the cluster.
    • The interval property in Kustomization and HelmRepository definitions controls the frequency of reconciliation.
    • Source: README.md

Adding a New Cluster:

  1. Clone the repository:

  2. Create a cluster directory:

  3. Copy sync manifests:

    • Copy the infrastructure.yaml and apps.yaml files from a existing cluster directory (e.g., staging) to the new cluster directory.
    • Source: README.md

  4. Update cluster configuration:

    • Adapt the spec.path in the apps.yaml file to point to the appropriate directory under the apps folder for your new cluster.
    • Source: README.md

  5. Bootstrap Flux:

    • Bootstrap Flux in the new cluster using the flux bootstrap github command with the updated context and path.
    • Source: README.md

Excluding Files from Git:

  • The .sourceignore file defines files and directories to exclude from the repository when syncing with Flux.
  • Source: .sourceignore

Key Concepts:

  • Flux: A GitOps tool that automates the delivery and management of Kubernetes resources.
  • Kustomize: A tool that allows customizing and layering Kubernetes configurations.
  • Helm: A package manager for Kubernetes applications.
  • Infrastructure as Code (IaC): Managing infrastructure using code, enabling version control, automation, and consistency.

Example Kustomization Configurations:

  • clusters/staging/apps.yaml: Source
  • clusters/production/apps.yaml: Source
  • clusters/staging/infrastructure.yaml: Source
  • clusters/production/infrastructure.yaml: Source

Example HelmRelease Configuration:

  • apps/base/podinfo/release.yaml: Source

Example HelmRepository Configuration:

  • apps/base/podinfo/repository.yaml: Source

Top-Level Directory Explanations

apps/ - This directory contains the application definitions and configurations. It includes base, production, staging directories.

apps/base/ - This directory contains the base application configurations. It includes podinfo directory.

apps/production/ - This directory contains the production application configurations.

apps/staging/ - This directory contains the staging application configurations.

clusters/ - This directory contains the Kubernetes cluster configurations. It includes production and staging directories.

clusters/production/ - This directory contains the production Kubernetes cluster configurations. It includes flux-system directory.

clusters/staging/ - This directory contains the staging Kubernetes cluster configurations. It includes flux-system directory.

infrastructure/ - This directory contains the infrastructure configurations and scripts.

infrastructure/configs/ - This directory contains the configuration files for the infrastructure.

infrastructure/controllers/ - This directory contains the Kubernetes controllers for managing the infrastructure.

scripts/ - This directory contains the scripts used for automating tasks.