This documentation page describes the CI/CD workflow within the FluxCD/Flux2 project. If no CI/CD tools have been established for the project, it will indicate that and suggest next steps.

Overview

FluxCD is a continuous delivery tool that synchronizes Kubernetes clusters with sources of configuration such as Git repositories and OCI artifacts. This integration automates updates to configuration when new code is ready to deploy. The deployment process in FluxCD leverages existing CI/CD tools through CloudEvents and is structured to accommodate repository management.

Setting Up CI/CD Workflow

1. Environment Preparation

The environment must be prepared for FluxCD by setting up required dependencies. This can include ensuring that Kubernetes and your CI/CD platform support the required workflows.

Using a Makefile, you can define various functions to assist in setup:

# Makefile snippet for setting up environment
setup-envtest:
    @echo "Setting up environment for testing"
    # additional setup commands here

2. Container Setup

The deployment often requires a container setup to encapsulate the application and its dependencies. Utilize the following Dockerfile to prepare a Flux CLI container:

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" ]

3. Git Repository Configuration

To enable Flux to watch a Git repository for changes and apply them, use the following command syntax to create a Git repository source:

func createSourceGitCmdRun(cmd *cobra.Command, args []string) error {
    name := args[0]

    if sourceGitArgs.url == "" {
        return fmt.Errorf("url is required")
    }

    u, err := url.Parse(sourceGitArgs.url)
    if err != nil {
        return fmt.Errorf("git URL parse failed: %w", err)
    }

    gitRepository := sourcev1.GitRepository{
        ObjectMeta: metav1.ObjectMeta{
            Name:      name,
            Namespace: *kubeconfigArgs.Namespace,
        },
        Spec: sourcev1.GitRepositorySpec{
            URL:      sourceGitArgs.url,
            Interval: metav1.Duration{Duration: createArgs.interval},
        },
    }

    ctx, cancel := context.WithTimeout(context.Background(), rootArgs.timeout)
    defer cancel()

    kubeClient, err := utils.KubeClient(kubeconfigArgs, kubeclientOptions)
    if err != nil {
        return err
    }

    namespacedName, err := upsertGitRepository(ctx, kubeClient, &gitRepository)
    if err != nil {
        return err
    }
    
    // Wait for reconciliation
    ...
}

4. Integrating CI/CD Tools

FluxCD supports integration with various CI/CD tools using CloudEvents. For instance, you might set up a Tekton pipeline that triggers a reconciliation in your Flux application.

Here’s a conceptual example of how a pipeline could emit a CloudEvent:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: my-trigger-template
spec:
  params:
    - name: git_commit_id
      description: Commit ID to deploy.
  resourceTemplates:
    - apiVersion: eventing.knative.dev/v1
      kind: Event
      metadata:
        name: flux-event
      spec:
        type: dev.knative.example.git
        data:
          commit_id: $(tt.params.git_commit_id)

This event could be sent to the Flux webhook receiver to apply the changes.

5. Testing the Setup

Testing is integral to ensure that your CI/CD setup functions as expected. The project includes tests with specified build constraints.

Run the tests using the Makefile:

make test-with-kind

For detailed testing, the project uses:

// Example of an integration test
func TestIntegration(t *testing.T) {
    // Setup code
}

When running tests, ensure to specify the required constraints, such as the unit and e2e tags, to control the scope of the tests:

go test -tags=unit -v ./...

Next Steps if CI/CD is Not Yet Set Up

If there is no CI/CD workflow currently established in the project, consider the following next steps:

1. Define Your Workflow: Determine the CI/CD tools suitable for your project’s needs (e.g., GitHub Actions, GitLab CI, Tekton).
2. Set Up a Git Repository: Configure a Git repository to manage your flux configurations and application manifests.
3. Integrate CloudEvents: Implement CloudEvents to allow your CI CD tools to communicate with Flux effectively.
4. Implement Testing: Establish a testing framework to verify your deployments and changes.

This documentation serves as a guide to successfully implement a CI/CD workflow using FluxCD and various associated tools. For further information, consult the official documentation or relevant RFCs.