Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs for Flux v0.26.0 #727

Merged
merged 2 commits into from
Feb 1, 2022
Merged

Update docs for Flux v0.26.0 #727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1f2056
Update docs for Flux v0.26.0
stefanprodan Jan 26, 2022
e2d265a
Add "Multi-tenancy lockdown" section to install docs
stefanprodan Jan 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion content/en/docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
4 changes: 2 additions & 2 deletions content/en/docs/guides/cron-job-image-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand Down
94 changes: 42 additions & 52 deletions content/en/docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
79 changes: 64 additions & 15 deletions content/en/docs/security/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ linkTitle: "Security"
description: "Flux Security documentation."
---

<!-- For doc writers: Step-by-step security instructions should live on the appropriate documentation pages. To fulfil our promise to end users, we should briefly outline the context here, and link to the more detailed instruction pages from each relevant part of this outline. -->
<!-- For doc writers: Step-by-step security instructions should live on the appropriate documentation pages.
To fulfil our promise to end users, we should briefly outline the context here,
and link to the more detailed instruction pages from each relevant part of this outline. -->

{{% alert color="info" title="✍️⏳ Work in progress" %}}
This document is a work in progress.
Expand All @@ -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.
Comment on lines +20 to +22
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sold on hard-wrapping lines in Markdown but that's just a personal preference as I find it much easier to diff changes when paragraphs are not hard-wrapped.


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

<!-- See [Flux RBAC manifests](https://github.com/fluxcd/flux2/tree/main/manifests/rbac)
- Scott: spell out here in high-level human-readable terms -->

Flux installs a set of [RBAC manifests](https://github.com/fluxcd/flux2/tree/main/manifests/rbac).
These include:

Expand All @@ -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: <https://github.com/fluxcd/flux2-multi-tenancy>.
The roles and permissions for this multi-tenancy approach
are described in detail here: <https://github.com/fluxcd/flux2-multi-tenancy>.

[^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).