diff --git a/content/en/docs/faq.md b/content/en/docs/faq.md index 4286f5f3a..185ddee3c 100644 --- a/content/en/docs/faq.md +++ b/content/en/docs/faq.md @@ -212,7 +212,8 @@ metadata: spec: field1: null field2: {} - field3: + field3: [] + field4: ``` The kustomize-controller detects drift between the manifests and the in-cluster resources diff --git a/content/en/docs/get-started.md b/content/en/docs/get-started.md index 64d560e55..0e582c1c2 100644 --- a/content/en/docs/get-started.md +++ b/content/en/docs/get-started.md @@ -53,7 +53,7 @@ The output is similar to: ``` ► checking prerequisites -✔ kubernetes 1.22.2 >=1.19.0 +✔ kubernetes 1.22.2 >=1.20.6 ✔ prerequisites checks passed ``` diff --git a/content/en/docs/guides/cron-job-image-auth.md b/content/en/docs/guides/cron-job-image-auth.md index 355f6b7eb..2d443bc02 100644 --- a/content/en/docs/guides/cron-job-image-auth.md +++ b/content/en/docs/guides/cron-job-image-auth.md @@ -1,6 +1,6 @@ --- -title: "How to use cron jobs to sync image repository credentials" -linkTitle: "cron jobs for image repository cretentions" +title: "Configure image automation authentication" +linkTitle: "Configure image automation authentication" description: "How to use cron jobs to sync image repository credentials." weight: 90 --- diff --git a/content/en/docs/installation.md b/content/en/docs/installation.md index 85b6e8b8f..225ca555d 100644 --- a/content/en/docs/installation.md +++ b/content/en/docs/installation.md @@ -10,25 +10,17 @@ manage one or more Kubernetes clusters. ## Prerequisites -You will need a Kubernetes cluster version **1.19** or newer. +You will need a Kubernetes cluster that matches one of the following versions: -Older versions are also supported, but we don't recommend running EOL Kubernetes versions in production: +| Kubernetes version | Minimum required | +|--------------------|------------------| +| `v1.20` | `>= 1.20.6` | +| `v1.21` | `>= 1.21.0` | +| `v1.22` | `>= 1.22.0` | +| `v1.23` and later | `>= 1.23.0` | -| Kubernetes version | Minimum required\* | -| --- | --- | -| `v1.16` | `>= 1.16.11` | -| `v1.17` | `>= 1.17.7` | -| `v1.18` | `>= 1.18.4` | -| `v1.19` and later | `>= 1.19.0` | - -*\* Update 2021-10-11:* - -If you are using `APIService` objects (for example -[metrics-server](https://github.com/kubernetes-sigs/metrics-server)), -you will need to update to `1.18.18`, `1.19.10`, `1.20.6` or `1.21.0` -at least. See [this -post](https://github.com/fluxcd/flux2/discussions/1916#discussioncomment-1458041) -for more information. +Note that Flux may work on Kubernetes 1.19, +but we don't recommend running EOL versions in production. ## Install the Flux CLI @@ -564,52 +556,50 @@ the customisations from `gotk-patches.yaml`. You can make changes to the patches after bootstrap and Flux will apply them in-cluster on its own. -### Pod Security Policy - -Assuming you want to make the Flux controllers conform to Pod Security Policy or equivalent webhooks, -create a file at `clusters/my-cluster/flux-system/psp-patch.yaml` with the following content: +### Multi-tenancy lockdown -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: all-flux-components -spec: - template: - metadata: - annotations: - # Required by Kubernetes node autoscaler - cluster-autoscaler.kubernetes.io/safe-to-evict: "true" - spec: - securityContext: - runAsUser: 10000 - fsGroup: 1337 - containers: - - name: manager - securityContext: - readOnlyRootFilesystem: true - allowPrivilegeEscalation: false - runAsNonRoot: true - capabilities: - drop: - - ALL -``` - -Edit `clusters/my-cluster/flux-system/kustomization.yaml` and enable the patch: +Assuming you want to lock down Flux on multi-tenant clusters, +add the following patches to `clusters/my-cluster/flux-system/kustomization.yaml`: ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: -- gotk-components.yaml -- gotk-sync.yaml + - gotk-components.yaml + - gotk-sync.yaml patches: - - path: psp-patch.yaml + - patch: | + - op: add + path: /spec/template/spec/containers/0/args/0 + value: --no-cross-namespace-refs=true target: kind: Deployment + name: "(kustomize-controller|helm-controller|notification-controller|image-reflector-controller|image-automation-controller)" + - patch: | + - op: add + path: /spec/template/spec/containers/0/args/0 + value: --default-service-account=default + target: + kind: Deployment + name: "(kustomize-controller|helm-controller)" + - patch: | + - op: add + path: /spec/serviceAccountName + value: kustomize-controller + target: + kind: Kustomization + name: "flux-system" ``` -Push the changes to the main branch and run `flux bootstrap`. +With the above configuration, Flux will: + +- Deny cross-namespace access to Flux custom resources, thus ensuring that a tenant can't use another tenant's sources or subscribe to their events. +- All `Kustomizations` and `HelmReleases` which don't have `spec.serviceAccountName` specified, will use the `default` account from the tenant's namespace. + Tenants have to specify a service account in their Flux resources to be able to deploy workloads in their namespaces as the `default` account has no permissions. +- The flux-system `Kustomization` is set to reconcile under a service account with cluster-admin role, + allowing platform admins to configure cluster-wide resources and provision the tenant's namespaces, service accounts and RBAC. + +To apply these patches, push the changes to the main branch and run `flux bootstrap`. ## Dev install diff --git a/content/en/docs/security/_index.md b/content/en/docs/security/_index.md index 4ff7d6e3a..fd21b14d7 100644 --- a/content/en/docs/security/_index.md +++ b/content/en/docs/security/_index.md @@ -4,7 +4,9 @@ linkTitle: "Security" description: "Flux Security documentation." --- - + {{% alert color="info" title="✍️⏳ Work in progress" %}} This document is a work in progress. @@ -15,17 +17,58 @@ Please follow [this GitHub issue](https://github.com/fluxcd/website/issues/598) Flux has a multi-component design, and integrates with many other systems. -This document outlines an overview of security considerations for Flux components, project processes, artifacts, as well as Flux configurable options and what they enable for both Kubernetes cluster and external system security. +This document outlines an overview of security considerations for Flux components, +project processes, artifacts, as well as Flux configurable options and +what they enable for both Kubernetes cluster and external system security. -See our [security processes document](/security) for vulnerability reporting, handling, and disclosure of information for the Flux project and community. +See our [security processes document](/security) for vulnerability reporting, handling, +and disclosure of information for the Flux project and community. + +## Signed container images + +The Flux CLI and the controllers' images are signed using [Sigstore](https://www.sigstore.dev/) Cosign and GitHub OIDC. +The container images along with their signatures are published on GitHub Container Registry and Docker Hub. + +To verify the authenticity of Flux's container images, +install [cosign](https://docs.sigstore.dev/cosign/installation/) and run: + +```console +$ COSIGN_EXPERIMENTAL=1 cosign verify ghcr.io/fluxcd/source-controller:v0.21.1 + +Verification for ghcr.io/fluxcd/source-controller:v0.21.1 -- +The following checks were performed on each of these signatures: + - The cosign claims were validated + - Existence of the claims in the transparency log was verified offline + - Any certificates were verified against the Fulcio roots. +``` + +## Software Bill of Materials + +For the Flux project we publish a Software Bill of Materials (SBOM) with each release. +The SBOM is generated with [Syft](https://github.com/anchore/syft) in the [SPDX](https://spdx.dev/) format. + +The `spdx.json` file is available for download on the GitHub release page e.g.: + +```shell +curl -sL https://github.com/fluxcd/flux2/releases/download/v0.25.3/flux_0.25.3_sbom.spdx.json | jq +``` + +## Pod security standard + +The controller deployments are configured in conformance with the +Kubernetes [restricted pod security standard](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted): + +- all Linux capabilities are dropped +- the root filesystem is set to read-only +- the seccomp profile is set to the runtime default +- run as non-root is enabled +- the filesystem group is set to 1337 +- the user and group ID is set to 65534 ## Controller permissions While Flux integrates with other systems it is built on Kubernetes core controller-runtime and properly adheres to Kubernetes security model including RBAC [^1]. - - Flux installs a set of [RBAC manifests](https://github.com/fluxcd/flux2/tree/main/manifests/rbac). These include: @@ -41,18 +84,24 @@ These include: - References `cluster-admin` `ClusterRole` - Bound to service accounts for only `kustomize-controller` and `helm-controller` -Flux uses these two `ClusterRoleBinding` strategies in order to allow for clear access separation using tools purpose-built for policy enforcement (OPA, Kyverno, admission controllers). +Flux uses these two `ClusterRoleBinding` strategies in order to allow for clear access separation using tools +purpose-built for policy enforcement (OPA, Kyverno, admission controllers). -For example, the design allows all controllers to access Flux CRDs (binds to `crd-controller` `ClusterRole`), but only binds the Flux reconciler controllers for Kustomize and Helm to `cluster-admin` `ClusterRole`, as these are the only two controllers that manage resources in the cluster. +For example, the design allows all controllers to access Flux CRDs (binds to `crd-controller` `ClusterRole`), +but only binds the Flux reconciler controllers for Kustomize and Helm to `cluster-admin` `ClusterRole`, +as these are the only two controllers that manage resources in the cluster. -However in a [soft multi-tenancy setup]({{< relref "../get-started#multi-cluster-setup" >}}), Flux does not reconcile a tenant's repo under the `cluster-admin` role. -Instead you specify a different service account in your manifest, and the Flux controllers will use the Kubernetes Impersonation API under `cluster-admin` to impersonate that service account for most operations [^2]. +However in a [soft multi-tenancy setup]({{< relref "../get-started#multi-cluster-setup" >}}), +Flux does not reconcile a tenant's repo under the `cluster-admin` role. +Instead, you specify a different service account in your manifest, and the Flux controllers will use +the Kubernetes Impersonation API under `cluster-admin` to impersonate that service account [^2]. In this way, policy restrictions for this service account are applied to the manifests being reconciled. If the binding is not defined for the correct service account and namespace, it will fail. -The roles and permissions for this multi-tenancy approach are described in detail here: . +The roles and permissions for this multi-tenancy approach +are described in detail here: . [^1]: However, by design cross-namespace references are an exception to RBAC. -See how these are handled in [ImagePolicy](https://fluxcd.io/docs/components/image/imagepolicies/#specification) and [ImageRepository](https://fluxcd.io/docs/components/image/imagerepositories/#allow-cross-namespace-references). -Also see [RFC-0002](https://github.com/fluxcd/flux2/pull/2092) about making all Flux APIs handle cross-namespace references to sources consistent with this approach. -[^2]: Impersonation is used for most operations except accessing sources. -For additional details on the impersonation mechanism, see [RFC-0001 Memorandum on Flux Authorization](https://github.com/fluxcd/flux2/tree/main/rfcs/0001-authorization#impersonation). +Platform admins have to option to turnoff cross-namespace references as described in the +[installation documentation](../installation/_index.md#multi-tenancy-lockdown). +[^2]: Platform admins have to option to enforce impersonation as described in the +[installation documentation](../installation/_index.md#multi-tenancy-lockdown).