Skip to content

Latest commit

 

History

History
291 lines (206 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

291 lines (206 loc) · 11.5 KB

Contributing

Flux Operator is AGPL-3.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on how to make it easier to get your contribution accepted.

We gratefully welcome improvements to code and documentation!

Certificate of Origin

By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.

You must sign-off your commits with your name and email address using git commit -s.

Project Overview

The project is structured as a Go module with the following components:

The documentation structure is described in the following section:

Source Code Structure

Flux Operator Kubernetes Controller

The Flux Operator is built using the Kubernetes controller-runtime framework and the Flux runtime SDK.

The test framework is based on controller-runtime's envtest and Gomega.

Packages:

  • api - contains the API definitions for the Flux Operator Kubernetes CRDs
  • cmd/operator - contains the entrypoint of the Kubernetes controller
  • internal/controller - contains the reconcilers for FluxInstance, FluxReport, ResourceSet, and ResourceSetInputProvider resources
  • internal/builder - contains utilities for building and templating Flux manifests
  • internal/entitlement - contains metering and entitlement validation logic
  • internal/gitprovider - contains integrations for GitHub, GitLab, and Azure DevOps
  • internal/inventory - contains inventory management for tracking applied resources
  • internal/reporter - contains cluster reporting and metrics collection utilities
  • internal/schedule - contains scheduling utilities for automated operations

To test and build the operator binary, run:

make test build

The build command writes the binary at bin/flux-operator relative to the repository root.

To run the controller locally, first create a Kubernetes cluster using kind:

kind create cluster

To run the integration tests against the kind cluster, run:

make test-e2e

For more information on how to run the controller locally and perform manual testing, refer to the development guide.

Flux Operator CLI

The Flux Operator command-line interface (CLI) is built using the Cobra library.

Packages:

  • cmd/cli - contains the commands for the Flux Operator CLI

To test and build the CLI binary, run:

make cli-test cli-build

The build command writes the binary at bin/flux-operator-cli relative to the repository root.

To run the CLI locally, use the binary built in the previous step:

./bin/flux-operator-cli --help

The CLI commands documentation is maintained in the cmd/cli/README.md file.

Flux Operator MCP Server

The Flux Operator MCP Server is built using the mcp-go library.

Packages:

To test and build the MCP Server binary, run:

make mcp-test mcp-build

The build command writes the binary at bin/flux-operator-mcp relative to the repository root.

To run the MCP Server using stdio, add the following configuration to your AI assistant's settings:

{
  "mcpServers": {
    "flux-operator-mcp": {
      "command": "/path/to/bin/flux-operator-mcp",
      "args": ["serve"],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

Replace /path/to/bin/flux-operator-mcp with the absolute path to the binary and /path/to/.kube/config with the absolute path to your kubeconfig file.

After rebuilding the MCP Server binary, you need to restart the AI assistant app to test the new build.

To run the MCP Server using SSE, use the following command:

export KUBECONFIG=$HOME/.kube/config
./bin/flux-operator-mcp serve --transport sse --port 8080

To connect to the server from VS Code, use the following configuration:

{
  "mcp": {
    "servers": {
      "flux-operator-mcp": {
        "type": "sse",
        "url": "http://localhost:8080/sse"
      }
    }
  }
}

After rebuilding the MCP Server binary, you need to restart the server to test the new build.

Flux Status Page

The Flux Status Web UI is a single-page application (SPA) built using Preact, Tailwind CSS, and Vite.

The test framework is based on Vitest with jsdom for DOM simulation and @testing-library/preact for component testing.

Packages:

  • web/src - contains the Preact components and utilities
  • web/src/components - contains the UI components
  • web/src/utils - contains utility functions for theming, time formatting, etc.
  • web/src/mock - contains mock data for development
  • web/dist - build output embedded in the Go binary via web/embed.go
  • internal/web - contains the Go HTTP server, API routes, and embedded frontend serving

To test and build the web UI, run:

make web-test web-build

The build command writes the production assets to the web/dist/ directory, which is embedded into the Go binary and served by the status web server.

To run the web UI locally with mock data:

make web-dev-mock

This starts a Vite dev server with hot module replacement at http://localhost:5173.

To run the web UI with a live backend connected to Kubernetes:

# Terminal 1: Start the status web server
make web-run

# Terminal 2: Start the Vite dev server
make web-dev

The Vite dev server will proxy API requests to the Go backend running on port 35000.

To run the web server as cluster-admin (for testing user actions that require elevated permissions), first create a web-config.yaml file with the following content:

apiVersion: web.fluxcd.controlplane.io/v1
kind: Config
spec:
  baseURL: http://localhost:9080
  authentication:
    type: Anonymous
    anonymous:
      username: cluster-admin
      groups:
        - system:masters

Then run the web server with the config:

make web-run WEB_RUN_ARGS=--web-config=web-config.yaml

Project Documentation Structure

The project documentation is written in Markdown. Each Markdown file must include YAML front matter with title and description fields:

---
title: Page Title
description: A brief description of the page content
---

To contribute to the documentation, you can edit the Markdown files in the following locations:

The documentation is automatically published to fluxoperator.dev/docs after a new release.

Acceptance policy

These things will make a PR more likely to be accepted:

  • a well-described requirement
  • tests for new code
  • tests for old code!
  • new code and tests follow the conventions in old code and tests
  • a good commit message (see below)
  • all code must abide Go Code Review Comments
  • names should abide What's in a name
  • code must build on Linux, macOS and Windows via plain go build
  • code should have appropriate test coverage, and tests should be written to work with go test

Before opening a PR, please check that your code passes the following:

make all

In general, we will merge a PR once one maintainer has endorsed it. For significant changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR.

Format of the Commit Message

For this project, we prefer the following rules for good commit messages:

  • Limit the subject to 50 characters and write as the continuation of the sentence "If applied, this commit will ..."
  • Explain what and why in the body, if more than a trivial change; wrap it at 72 characters.

The following article has some more helpful advice on documenting your work.