Flux – Toolkit Dev Guides

Flux: Using the GitOps Toolkit APIs with Go

Mon, 01 Jan 0001 00:00:00 +0000

While you can use the GitOps Toolkit APIs in a declarative manner with kubectl apply, we provide client library code for all our toolkit APIs that makes it easier to access them from Go.

Go Packages

The GitOps Toolkit Go modules and controllers are released by following the semver conventions.

The API schema definitions modules have the following dependencies:

The APIs can be consumed with the controller-runtime client.

source.toolkit.fluxcd.io

Download package

go get github.com/fluxcd/source-controller/api

Import package

import sourcev1 "github.com/fluxcd/source-controller/api/v1"

API Types

Name	Version
GitRepository	v1
HelmRepository	v1
HelmChart	v1
OCIRepository	v1
Bucket	v1

kustomize.toolkit.fluxcd.io

Download package

go get github.com/fluxcd/kustomize-controller/api

Import package

import kustomizev1 "github.com/fluxcd/kustomize-controller/api/v1"

API Types

Name	Version
Kustomization	v1

helm.toolkit.fluxcd.io

Download package

go get github.com/fluxcd/helm-controller/api

Import package

import helmv2 "github.com/fluxcd/helm-controller/api/v2"

API Types

Name	Version
HelmRelease	v2

notification.toolkit.fluxcd.io

Download package

go get github.com/fluxcd/notification-controller/api

Import package

import notificationv1b3 "github.com/fluxcd/notification-controller/api/v1beta3"

and for Receiver objects:

import notificationv1 "github.com/fluxcd/notification-controller/api/v1"

API Types

Name	Version
Receiver	v1
Provider	v1beta3
Alert	v1beta3

image.toolkit.fluxcd.io

Download package

go get github.com/fluxcd/image-reflector-controller/api
go get github.com/fluxcd/image-automation-controller/api

Import package

import (
 imagev1 "github.com/fluxcd/image-reflector-controller/api/v1beta2"
 autov1 "github.com/fluxcd/image-automation-controller/api/v1beta2"
)

API Types

Name	Version
ImageRepository	v1beta2
ImagePolicy	v1beta2
ImageUpdateAutomation	v1beta2

CRUD Example

Here is an example of how to create a Helm release, wait for it to install, then delete it:

package main

import (
 "context"
 "fmt"
 "time"

 apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 "k8s.io/apimachinery/pkg/api/meta"
 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 "k8s.io/apimachinery/pkg/runtime"
 "k8s.io/apimachinery/pkg/types"
 "k8s.io/apimachinery/pkg/util/wait"
 _ "k8s.io/client-go/plugin/pkg/client/auth"
 ctrl "sigs.k8s.io/controller-runtime"
 "sigs.k8s.io/controller-runtime/pkg/client"

 helmv2 "github.com/fluxcd/helm-controller/api/v2"
 apimeta "github.com/fluxcd/pkg/apis/meta"
 sourcev1 "github.com/fluxcd/source-controller/api/v1"
)

func main() {
 // register the GitOps Toolkit schema definitions
 scheme := runtime.NewScheme()
 _ = sourcev1.AddToScheme(scheme)
 _ = helmv2.AddToScheme(scheme)

 // init Kubernetes client
 kubeClient, err := client.New(ctrl.GetConfigOrDie(), client.Options{Scheme: scheme})
 if err != nil {
 panic(err)
 }

 // set a deadline for the Kubernetes API operations
 ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 defer cancel()

 // create a Helm repository pointing to Bitnami
 helmRepository := &sourcev1.HelmRepository{
 ObjectMeta: metav1.ObjectMeta{
 Name: "bitnami",
 Namespace: "default",
 },
 Spec: sourcev1.HelmRepositorySpec{
 URL: "https://charts.bitnami.com/bitnami",
 Interval: metav1.Duration{
 Duration: 30 * time.Minute,
 },
 },
 }
 if err := kubeClient.Create(ctx, helmRepository); err != nil {
 fmt.Println(err)
 } else {
 fmt.Println("HelmRepository bitnami created")
 }

 // create a Helm release for nginx
 helmRelease := &helmv2.HelmRelease{
 ObjectMeta: metav1.ObjectMeta{
 Name: "nginx",
 Namespace: "default",
 },
 Spec: helmv2.HelmReleaseSpec{
 ReleaseName: "nginx",
 Interval: metav1.Duration{
 Duration: 5 * time.Minute,
 },
 Chart: helmv2.HelmChartTemplate{
 Spec: helmv2.HelmChartTemplateSpec{
 Chart: "nginx",
 Version: "8.x",
 SourceRef: helmv2.CrossNamespaceObjectReference{
 Kind: sourcev1.HelmRepositoryKind,
 Name: "bitnami",
 },
 },
 },
 Values: &apiextensionsv1.JSON{Raw: []byte(`{"service": {"type": "ClusterIP"}}`)},
 },
 }
 if err := kubeClient.Create(ctx, helmRelease); err != nil {
 fmt.Println(err)
 } else {
 fmt.Println("HelmRelease nginx created")
 }

 // wait for the a Helm release to be reconciled
 fmt.Println("Waiting for nginx to be installed")
 if err := wait.PollImmediate(2*time.Second, 1*time.Minute,
 func() (done bool, err error) {
 namespacedName := types.NamespacedName{
 Namespace: helmRelease.GetNamespace(),
 Name: helmRelease.GetName(),
 }
 if err := kubeClient.Get(ctx, namespacedName, helmRelease); err != nil {
 return false, err
 }
 return meta.IsStatusConditionTrue(helmRelease.Status.Conditions, apimeta.ReadyCondition), nil
 }); err != nil {
 fmt.Println(err)
 }

 // print the reconciliation status
 fmt.Println(meta.FindStatusCondition(helmRelease.Status.Conditions, apimeta.ReadyCondition).Message)

 // uninstall the release and delete the repository
 if err := kubeClient.Delete(ctx, helmRelease); err != nil {
 fmt.Println(err)
 }
 if err := kubeClient.Delete(ctx, helmRepository); err != nil {
 fmt.Println(err)
 }
 fmt.Println("Helm repository and release deleted")
}

For an example on how to build a Kubernetes controller that interacts with the GitOps Toolkit APIs see source-watcher.

Flux: Watching for source changes

Mon, 01 Jan 0001 00:00:00 +0000

In this guide you’ll be developing a Kubernetes controller with Kubebuilder that subscribes to GitRepository events and reacts to revision changes by downloading the artifact produced by source-controller.

Prerequisites

On your dev machine install the following tools:

go >= 1.22
kubebuilder >= 3.0
kind >= 0.22
kubectl >= 1.29

Install Flux

Install the Flux CLI with Homebrew on macOS or Linux:

brew install fluxcd/tap/flux

Create a cluster for testing:

kind create cluster --name dev

Verify that your dev machine satisfies the prerequisites with:

flux check --pre

Install source-controller on the dev cluster:

flux install \
--namespace=flux-system \
--network-policy=false \
--components=source-controller

Clone the sample controller

You’ll be using fluxcd/source-watcher as a template for developing your own controller. The source-watcher was scaffolded with kubebuilder init.

Clone the source-watcher repository:

git clone https://github.com/fluxcd/source-watcher
cd source-watcher
git checkout release/v1.3.x

Build the controller:

make

Run the controller

Port forward to source-controller artifacts server:

kubectl -n flux-system port-forward svc/source-controller 8181:80

Export the local address as SOURCE_CONTROLLER_LOCALHOST:

export SOURCE_CONTROLLER_LOCALHOST=localhost:8181

Run source-watcher locally:

make run

Create a Git source:

flux create source git test \
--url=https://github.com/fluxcd/flux2 \
--ignore-paths='/*,!/manifests' \
--tag=v2.2.0

The source-watcher will log the revision:

{"level":"info","ts":"2024-05-14T16:43:42.703+0200","msg":"New revision detected","controller":"gitrepository","controllerGroup":"source.toolkit.fluxcd.io","controllerKind":"GitRepository","GitRepository":{"name":"test","namespace":"flux-system"},"namespace":"flux-system","name":"test","reconcileID":"ef0fe80e-3952-4835-ae9d-01760c4eadde","revision":"v2.2.0@sha1:81606709114f6d16a432f9f4bfc774942f054327"}

Change the Git tag:

flux create source git test \
--url=https://github.com/fluxcd/flux2 \
--ignore-paths='/*,!/manifests' \
--tag=v2.3.0

And source-watcher will log the new revision:

{"level":"info","ts":"2024-05-14T16:51:33.499+0200","msg":"New revision detected","controller":"gitrepository","controllerGroup":"source.toolkit.fluxcd.io","controllerKind":"GitRepository","GitRepository":{"name":"test","namespace":"flux-system"},"namespace":"flux-system","name":"test","reconcileID":"cc0f83bb-b7a0-4c19-a254-af9962ae39cd","revision":"v2.3.0@sha1:658925c2c0e6c408597d907a8ebee06a9a6d7f30"}

The source-controller reports the revision under GitRepository.Status.Artifact.Revision in the format: <branch|tag>@sha1:<commit>.

How it works

The GitRepositoryWatcher controller does the following:

subscribes to GitRepository events
detects when the Git revision changes
downloads and extracts the source artifact
writes the extracted dir names to stdout

type GitRepositoryWatcher struct {
 client.Client
 HttpRetry int
 artifactFetcher *fetch.ArchiveFetcher
}

func (r *GitRepositoryWatcher) SetupWithManager(mgr ctrl.Manager) error {
 r.artifactFetcher = fetch.NewArchiveFetcher(
 r.HttpRetry,
 tar.UnlimitedUntarSize,
 os.Getenv("SOURCE_CONTROLLER_LOCALHOST"),
 )

 return ctrl.NewControllerManagedBy(mgr).
 For(&sourcev1.GitRepository{}, builder.WithPredicates(GitRepositoryRevisionChangePredicate{})).
 Complete(r)
}

// +kubebuilder:rbac:groups=source.toolkit.fluxcd.io,resources=gitrepositories,verbs=get;list;watch
// +kubebuilder:rbac:groups=source.toolkit.fluxcd.io,resources=gitrepositories/status,verbs=get

func (r *GitRepositoryWatcher) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 log := ctrl.LoggerFrom(ctx)

 // get source object
 var repository sourcev1.GitRepository
 if err := r.Get(ctx, req.NamespacedName, &repository); err != nil {
 return ctrl.Result{}, client.IgnoreNotFound(err)
 }

 artifact := repository.Status.Artifact
 log.Info("New revision detected", "revision", artifact.Revision)

 // create tmp dir
 tmpDir, err := os.MkdirTemp("", repository.Name)
 if err != nil {
 return ctrl.Result{}, fmt.Errorf("failed to create temp dir, error: %w", err)
 }
 defer os.RemoveAll(tmpDir)

 // download and extract artifact
 if err := r.artifactFetcher.Fetch(artifact.URL, artifact.Digest, tmpDir); err != nil {
 log.Error(err, "unable to fetch artifact")
 return ctrl.Result{}, err
 }

 // list artifact content
 files, err := os.ReadDir(tmpDir)
 if err != nil {
 return ctrl.Result{}, fmt.Errorf("failed to list files, error: %w", err)
 }

 // do something with the artifact content
 for _, f := range files {
 log.Info("Processing " + f.Name())
 }

 return ctrl.Result{}, nil
}

To add the watcher to an existing project, copy the controller and the revision change predicate to your controllers dir:

In your main.go init function, register the Source API schema:

import (
 utilruntime "k8s.io/apimachinery/pkg/util/runtime"
 clientgoscheme "k8s.io/client-go/kubernetes/scheme"

 sourcev1 "github.com/fluxcd/source-controller/api/v1"
)

func init() {
 utilruntime.Must(clientgoscheme.AddToScheme(scheme))
 utilruntime.Must(sourcev1.AddToScheme(scheme)

 // +kubebuilder:scaffold:scheme
}

Start the controller in the main function:

func main() {

 if err = (&controllers.GitRepositoryWatcher{
 Client: mgr.GetClient(),
 HttpRetry: httpRetry,
 }).SetupWithManager(mgr); err != nil {
 setupLog.Error(err, "unable to create controller", "controller", "GitRepositoryWatcher")
 os.Exit(1)
 }

}

Note that the watcher depends on Flux runtime and Kubernetes controller-runtime:

require (
 github.com/fluxcd/pkg/runtime v0.47.1
 sigs.k8s.io/controller-runtime v0.18.2
)

That’s it! Happy hacking!

Flux: Advanced debugging

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers more advanced debugging topics such as collecting runtime profiling data from GitOps Toolkit components.

As a user, this page normally should be a last resort, but you may be asked by a maintainer to share a collected profile to debug e.g. performance issues.

Pprof

The GitOps Toolkit components serve pprof runtime profiling data on their metrics HTTP server (default :8080).

Endpoints

Endpoint	Path
Index	`/debug/pprof/`
CPU profile	`/debug/pprof/profile`
Symbol	`/debug/pprof/symbol`
Trace	`/debug/pprof/trace`

Collecting a profile

To collect a profile, port-forward to the component’s metrics endpoint and collect the data from the endpoint of choice:

$ kubectl port-forward -n <namespace> deploy/<component> 8080
$ curl -Sk -v http://localhost:8080/debug/pprof/heap > heap.out

The collected profile can be analyzed using go, or shared with one of the maintainers.

Resource usage

As kubectl top gives a limited (and at times inaccurate) overview of resource usage, it is often better to make use of the Grafana metrics to gather insights. See Flux Prometheus metrics for a guide on how to visualize this data with a Grafana dashboard.