fluxcd / flux2

Building, Installing, and Setting up Flux

This document outlines the steps required to build, install, and set up Flux.

Development Environment

To build and run Flux from source, you’ll need a Go development environment.

  1. Install Go:

    • Download and install the latest Go version from the official website: https://go.dev/

  2. Set up Environment Variables:

    • Set the GOPATH environment variable to the desired location for your Go workspace.
    • Add the bin directory within your GOPATH to your system’s PATH.

Building Flux

  1. Clone the repository:

    git clone https://github.com/fluxcd/flux2.git
          cd flux2

  2. Install dependencies:

    make install-envtest

  3. Build the project:

    make build

    This will create a binary file in the _output/bin directory.

Installing Flux

To install Flux on your system, you can use the provided binary file or install it via Homebrew.

  1. Install from binary:

    • Copy the binary file from the _output/bin directory to a location in your system’s PATH.

  2. Install via Homebrew:

    • Add the Flux tap to your Homebrew configuration:
      brew tap fluxcd/tap
    • Install Flux using Homebrew:
      brew install flux

Setting Up Flux

  1. Initialize Flux:

    • Run the following command to initialize Flux:
      flux --target-namespace=flux-system init

  2. Configure Flux:

    • Create a Kubernetes secret containing your Git provider credentials:
      apiVersion: v1
          kind: Secret
          metadata:
            name: flux-system-git-credentials
          type: Opaque
          data:
            username: <your-username>
            password: <your-password>
    • Apply the secret to your cluster:
      kubectl apply -f secret.yaml
    • Configure Flux using the flux command:
      flux --target-namespace=flux-system bootstrap \
            --git-url=https://github.com/your-org/your-repo \
            --git-branch=main \
            --git-sync-interval=1m \
            --git-secret-name=flux-system-git-credentials \
            --image-automation.policy=auto

Running Flux

Once Flux is set up, it will automatically monitor your Git repository and deploy changes to your cluster.

Running Tests

  1. Run unit tests:

    make test

  2. Run end-to-end tests:

    make e2e

Building for Development

  1. Build for development:

    make build-dev

    This will build a development version of Flux with debugging symbols.

Installing for Development

  1. Install for development:

    make install-dev

    This will install the development version of Flux in your system’s PATH.

Using Docker

  1. Build a Docker image:

    docker build -t fluxcd/flux:latest .

  2. Run the Docker image:

    docker run -it fluxcd/flux:latest

Cleaning Up

  1. Remove build artifacts:
    make tidy

Example Usage

  1. Deploy a Kubernetes manifest:

    flux --target-namespace=flux-system deploy \
            --manifest=path/to/your/manifest.yaml

  2. Create a new Helm release:

    flux --target-namespace=flux-system helm-release create \
            --name=my-release \
            --namespace=my-namespace \
            --chart=path/to/your/chart \
            --version=1.2.3

  3. Update an existing Helm release:

    flux --target-namespace=flux-system helm-release update \
            --name=my-release \
            --namespace=my-namespace \
            --chart=path/to/your/chart \
            --version=1.2.4

Additional Resources

Top-Level Directory Explanations

manifests/ - This directory contains Kubernetes manifests used by Flux. It includes various subdirectories for different types of manifests, such as bases/ for base manifests, crds/ for Custom Resource Definitions, and policies/ for policy manifests.

pkg/ - This directory contains the Go packages for Flux. It includes various subdirectories for different packages, such as bootstrap/ for bootstrapping, log/ for logging, manifestgen/ for manifest generation, and printers/ for printing manifests.