diff --git a/README.md b/README.md index 8f0fc49..66245de 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/flux-operator)](https://artifacthub.io/packages/helm/flux-operator/flux-operator) [![e2e](https://github.com/controlplaneio-fluxcd/flux-operator/actions/workflows/e2e.yaml/badge.svg)](https://github.com/controlplaneio-fluxcd/flux-operator/actions/workflows/e2e.yaml) [![license](https://img.shields.io/github/license/controlplaneio-fluxcd/flux-operator.svg)](https://github.com/controlplaneio-fluxcd/flux-operator/blob/main/LICENSE) -[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](#supply-chain-security) +[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://fluxcd.control-plane.io/distribution/security/) The Flux Operator is a Kubernetes CRD controller that manages the lifecycle of CNCF [Flux CD](https://fluxcd.io) and the @@ -17,47 +17,44 @@ the lifecycle of CNCF [Flux CD](https://fluxcd.io) and the ## Features -- Provide a declarative API for the installation, sync configuration and upgrade of the Flux distribution. -- Automate patching for hotfixes and CVEs affecting the Flux controllers container images. -- Support for syncing the cluster state from Git repositories, OCI artifacts and S3-compatible storage. -- Provide first-class support for OpenShift, Azure, AWS, GCP and other marketplaces. -- Simplify the configuration of multi-tenancy lockdown on shared Kubernetes clusters. -- Provide a security-first approach to the Flux deployment and FIPS compliance. -- Incorporate best practices for running Flux at scale with persistent storage, sharding and horizontal scaling. -- Manage the update of Flux custom resources and prevent disruption during the upgrade process. -- Facilitate a clean uninstall and reinstall process without affecting the Flux-managed workloads. +- Provides a declarative API for the installation, configuration and upgrade of Flux. +- Automates the patching of hotfixes and CVEs affecting the Flux controllers container images. +- Simplifies the configuration of multi-tenancy lockdown on shared Kubernetes clusters. +- Allows syncing the cluster state from Git repositories, OCI artifacts and S3-compatible storage. +- Provides a security-first approach to the Flux deployment and FIPS compliance. +- Incorporates best practices for running Flux at scale with persistent storage and vertical scaling. +- Manages the update of Flux custom resources and prevents disruption during the upgrade process. +- Facilitates a clean uninstall and reinstall process without affecting the Flux-managed workloads. +- Provides first-class support for OpenShift, Azure, AWS, GCP and other marketplaces. -## Installation +## Documentation -The Flux Operator can be installed using the -[Helm chart](https://github.com/controlplaneio-fluxcd/charts/tree/main/charts/flux-operator) -available in the ControlPlane registry: +- [Flux operator installation](https://fluxcd.control-plane.io/operator/install/) +- [Flux controllers configuration](https://fluxcd.control-plane.io/operator/flux-config/) +- [Cluster sync configuration](https://fluxcd.control-plane.io/operator/flux-sync/) +- [Migration of bootstrapped clusters](https://fluxcd.control-plane.io/operator/flux-bootstrap-migration/) +- [FluxInstance API reference](https://fluxcd.control-plane.io/operator/fluxinstance/) -```shell -helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \ - --namespace flux-system \ - --create-namespace -``` +## Quickstart Guide -Or by using the Kubernetes manifests published on the releases page: +### Install the Flux Operator + +Install the Flux Operator in the `flux-system` namespace, for example using Helm: ```shell -kubectl apply -f https://github.com/controlplaneio-fluxcd/flux-operator/releases/latest/download/install.yaml +helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \ + --namespace flux-system ``` -## Usage - -The Flux Operator comes with a Kubernetes CRD called `FluxInstance`. A single custom resource of this kind -can exist in a Kubernetes cluster with the name `flux` that must be created in the same -namespace where the operator is deployed. - > [!NOTE] -> The `FluxInstance` API documentation is available at -> [docs/api/v1](https://github.com/controlplaneio-fluxcd/flux-operator/blob/main/docs/api/v1/fluxinstance.md). +> The Flux Operator can be installed using Helm, OperatorHub, kubectl and other methods. +> For more information, refer to the +> [installation guide](https://fluxcd.control-plane.io/operator/install/). -### Upstream Distribution +### Install the Flux Controllers -To install the upstream distribution of Flux, create the following `FluxInstance` resource: +Create a [FluxInstance](https://fluxcd.control-plane.io/operator/fluxinstance/) resource +in the `flux-system` namespace to install the latest Flux stable version: ```yaml apiVersion: fluxcd.controlplane.io/v1 @@ -65,6 +62,9 @@ kind: FluxInstance metadata: name: flux namespace: flux-system + annotations: + fluxcd.controlplane.io/reconcileEvery: "1h" + fluxcd.controlplane.io/reconcileTimeout: "5m" spec: distribution: version: "2.x" @@ -78,7 +78,9 @@ spec: - image-automation-controller cluster: type: kubernetes + multitenant: false networkPolicy: true + domain: "cluster.local" kustomize: patches: - target: @@ -93,69 +95,12 @@ spec: value: --requeue-dependency=5s ``` -The operator will reconcile the `FluxInstance` resource and install -the latest Flux stable version with the specified components. - -### Enterprise Distribution - -To install the FIPS-compliant distribution of Flux, create the following `FluxInstance` resource: - -```yaml -apiVersion: fluxcd.controlplane.io/v1 -kind: FluxInstance -metadata: - name: flux - namespace: flux-system - annotations: - fluxcd.controlplane.io/reconcileEvery: "1h" - fluxcd.controlplane.io/reconcileTimeout: "5m" -spec: - distribution: - version: "2.3.x" - registry: "ghcr.io/controlplaneio-fluxcd/distroless" - imagePullSecret: "flux-enterprise-auth" - components: - - source-controller - - kustomize-controller - - helm-controller - - notification-controller - cluster: - type: openshift - multitenant: true - networkPolicy: true - domain: "cluster.local" - storage: - class: "standard" - size: "10Gi" -``` - -Every hour, the operator will check for updates in the ControlPlane -[distribution repository](https://github.com/controlplaneio-fluxcd/distribution). -If a new patch version is available, the operator will update the Flux components by pinning the -container images to the latest digest published in the ControlPlane registry. - -Note that the `flux-enterprise-auth` Kubernetes secret must be created in the `flux-system` namespace -and should contain the credentials to pull the enterprise images: - -```shell -kubectl create secret docker-registry flux-enterprise-auth \ - --namespace flux-system \ - --docker-server=ghcr.io \ - --docker-username=flux \ - --docker-password=$ENTERPRISE_TOKEN -``` - -### Cluster Sync - -The `FluxInstance` resource can be configured to instruct the operator to generate -a Flux source (`GitRepository`, `OCIRepository` or `Bucket`) and a Flux `Kustomization` -to sync the cluster state with the source repository. +> [!NOTE] +> The Flux instance can be customized in various ways. +> For more information, refer to the +> [configuration guide](https://fluxcd.control-plane.io/operator/flux-config/). -The Flux objects are created in the same namespace where the `FluxInstance` is deployed -using the namespace name as the Flux source and Kustomization name. The naming convention -matches the one used by `flux bootstrap` to ensure compatibility with upstream, and -to allow [transitioning](#migration-of-a-bootstrapped-cluster) -a bootstrapped cluster to a `FluxInstance` managed one. +### Sync from a Git Repository To sync the cluster state from a Git repository, add the following configuration to the `FluxInstance`: @@ -185,76 +130,13 @@ flux create secret git flux-system \ ``` > [!NOTE] -> For more information on how to configure the cluster sync, refer to the -> [FluxInstance API documentation](https://github.com/controlplaneio-fluxcd/flux-operator/blob/main/docs/api/v1/fluxinstance.md#sync-configuration). - -### Migration of a bootstrapped cluster - -To migrate a cluster that was bootstrapped, after the flux-operator is installed -and the `FluxInstance` resource is created with a [sync source](#cluster-sync), -the following steps can be followed: - -1. Checkout the branch of the Flux repository that was used to bootstrap the cluster. -2. Delete the `flux-system` directory from the repository `clusters/my-cluster` directory. -3. Optionally, place the `FluxInstance` YAML manifest in the `clusters/my-cluster` directory. -4. Commit and push the changes to the Flux repository. - -## Supply Chain Security - -The build, release and provenance portions of the ControlPlane distribution supply chain meet -[SLSA Build Level 3](https://slsa.dev/spec/v1.0/levels). - -### Software Bill of Materials - -The ControlPlane images come with SBOMs in SPDX format for each CPU architecture. - -Example of extracting the SBOM from the flux-operator image: - -```shell -docker buildx imagetools inspect \ - ghcr.io/controlplaneio-fluxcd/flux-operator:v0.2.0 \ - --format "{{ json (index .SBOM \"linux/amd64\").SPDX}}" -``` - -### Signature Verification - -The ControlPlane images are signed using Sigstore Cosign and GitHub OIDC. - -Example of verifying the signature of the flux-operator image: - -```shell -cosign verify ghcr.io/controlplaneio-fluxcd/flux-operator:v0.2.0 \ - --certificate-identity-regexp=^https://github\\.com/controlplaneio-fluxcd/.*$ \ - --certificate-oidc-issuer=https://token.actions.githubusercontent.com -``` - -### SLSA Provenance Verification +> For more information on how to configure syncing from Git repositories, +> container registries and S3-compatible storage, refer to the +> [cluster sync guide](https://fluxcd.control-plane.io/operator/flux-sync/). -The provenance attestations are generated at build time with Docker Buildkit and -include facts about the build process such as: +## License -- Build timestamps -- Build parameters and environment -- Version control metadata -- Source code details -- Materials (files, scripts) consumed during the build +The Flux Operator is an open-source project licensed under the +[AGPL-3.0 license](https://github.com/controlplaneio-fluxcd/flux-operator/blob/main/LICENSE). -Example of extracting the SLSA provenance JSON for the flux-operator image: - -```shell -docker buildx imagetools inspect \ - ghcr.io/controlplaneio-fluxcd/flux-operator:v0.2.0 \ - --format "{{ json (index .Provenance \"linux/amd64\").SLSA}}" -``` - -The provenance of the build artifacts is generated with the official -[SLSA GitHub Generator](https://github.com/slsa-framework/slsa-github-generator). - -Example of verifying the provenance of the flux-operator image: - -```shell -cosign verify-attestation --type slsaprovenance \ - --certificate-identity-regexp=^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml.*$ \ - --certificate-oidc-issuer=https://token.actions.githubusercontent.com \ - ghcr.io/controlplaneio-fluxcd/flux-operator:v0.2.0 -``` +The project is developed by CNCF Flux core maintainers part of the [ControlPlane](https://control-plane.io) team. diff --git a/docs/api/v1/fluxinstance.md b/docs/api/v1/fluxinstance.md index c24a4f0..f601f90 100644 --- a/docs/api/v1/fluxinstance.md +++ b/docs/api/v1/fluxinstance.md @@ -1,4 +1,4 @@ -# FluxInstance +# Flux Instance CRD **FluxInstance** is a declarative API for the installation, configuration and automatic upgrade of the Flux distribution.