# Flux GitOps Stack

> Flux CD for GitOps with Weave GitOps UI.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: flux, kind, weave-gitops
- Tags: flux, gitops, kubernetes, cd
- Source: https://docker.recipes/devops/flux-gitops-stack

## Overview

Flux is a Cloud Native Computing Foundation (CNCF) graduated project that implements GitOps principles for Kubernetes, treating Git repositories as the single source of truth for cluster configuration and application deployment. Originally developed by Weaveworks, Flux automates the deployment process by continuously monitoring Git repositories and synchronizing changes to Kubernetes clusters, eliminating manual kubectl commands and ensuring declarative infrastructure management. Flux CD operates on a pull-based model where controllers running inside the cluster detect configuration drift and automatically reconcile the desired state defined in Git.

This GitOps stack combines Flux CD with Kind (Kubernetes in Docker) for local cluster simulation and Weave GitOps UI for visual management and monitoring. Kind provides a lightweight Kubernetes environment that runs entirely in Docker containers, making it perfect for GitOps development and testing without requiring cloud resources. The integrated container registry enables storing and managing custom images locally, while Weave GitOps delivers a web-based dashboard for visualizing GitOps workflows, monitoring deployments, and troubleshooting synchronization issues across multiple clusters.

This configuration targets DevOps engineers and platform teams implementing GitOps practices in development environments, CI/CD pipelines, or proof-of-concept deployments. The stack eliminates the complexity of setting up separate Kubernetes clusters, Git repositories, and monitoring tools by providing a unified development environment where teams can experiment with GitOps workflows, test Flux configurations, and validate deployment strategies before promoting to production clusters.

## Features

- Pull-based GitOps reconciliation with Flux controllers monitoring Git repository changes
- Multi-tenancy support with Flux namespace isolation and RBAC integration
- Helm and Kustomize native support for complex application deployment patterns
- Kind cluster with containerd runtime optimized for local Kubernetes development
- Weave GitOps dashboard for visualizing application deployments and Git synchronization status
- Built-in container registry for storing custom images without external dependencies
- Flux image automation for updating container tags based on registry scanning
- Git webhook support for immediate synchronization triggers beyond polling intervals

## Use cases

- Local GitOps development environment for testing Flux configurations before production deployment
- CI/CD pipeline integration for validating GitOps workflows in ephemeral test clusters
- Multi-environment application promotion workflows using Git branching strategies
- Kubernetes manifest validation and drift detection in containerized development setups
- Training and education platform for teams learning GitOps principles and Flux operations
- Proof-of-concept deployments demonstrating GitOps benefits to stakeholders and management
- Custom controller development and testing in isolated Kubernetes environments

## Prerequisites

- Docker Engine 20.10+ with privileged container support for Kind cluster operation
- Git repository with Kubernetes manifests and Flux configuration files
- Minimum 4GB RAM and 2 CPU cores for stable Kind cluster with Flux controllers
- Network access to GitHub/GitLab for Flux source controller Git repository synchronization
- Basic Kubernetes knowledge including pods, services, and namespace concepts
- Understanding of YAML syntax and Kubernetes manifest structure for GitOps workflows

## docker-compose.yml

```yaml
services:
  kind:
    image: kindest/node:v1.28.0
    container_name: flux-cluster
    privileged: true
    ports:
      - "${API_PORT:-6443}:6443"
    volumes:
      - kind_data:/var/lib/containerd

  registry:
    image: registry:2
    container_name: flux-registry
    restart: unless-stopped
    ports:
      - "${REGISTRY_PORT:-5000}:5000"
    volumes:
      - registry_data:/var/lib/registry

  weave-gitops:
    image: ghcr.io/weaveworks/wego-app:latest
    container_name: weave-gitops
    restart: unless-stopped
    ports:
      - "${GITOPS_PORT:-9001}:9001"

volumes:
  kind_data:
  registry_data:
```

## .env

```bash
# Flux GitOps
API_PORT=6443
REGISTRY_PORT=5000
GITOPS_PORT=9001
GITHUB_TOKEN=your_github_token
```

## Usage notes

- Weave GitOps UI at http://localhost:9001
- Bootstrap Flux with flux CLI
- Point Flux to your Git repo

## Troubleshooting

- Flux source controller fails to clone repository: Verify Git credentials and repository URL in Flux GitRepository resource, check network connectivity to Git provider
- Kind cluster fails to start with 'failed to create cluster': Ensure Docker daemon is running with privileged container support and sufficient disk space available
- Weave GitOps UI shows empty clusters: Run 'flux bootstrap' command to install Flux controllers and configure Git repository connection properly
- Kustomization reconciliation suspended with authentication errors: Generate and configure deploy keys or personal access tokens with appropriate repository permissions
- Container registry push failures: Verify registry service is running on port 5000 and Docker daemon trusts localhost:5000 as insecure registry
- Flux controllers consuming high CPU: Reduce Git polling frequency in source controller configuration and optimize Kustomization resource specifications

