Skip to content

Commit a22df1c

Browse files
stefanprodanstefanprodan
authored
Merge pull request #379 from controlplaneio-fluxcd/air-gapped-install
docs: Add Air-Gapped Installation guide
2 parents 482fe14 + 4f0d643 commit a22df1c

2 files changed

Lines changed: 163 additions & 80 deletions

File tree

‎docs/distribution/install.md‎

Lines changed: 160 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,166 @@ description: FluxCD Enterprise installation guide
77

88
ControlPlane offers a seamless transition from CNCF Flux to the enterprise distribution with no
99
impact to Flux availability. The hardened container images provided by ControlPlane are fully
10-
compatible with the upstream Flux installation and bootstrap procedure.
10+
compatible with the upstream Flux installation.
11+
12+
## Flux Operator
13+
14+
The ControlPlane distribution includes the [Flux Operator](https://fluxoperator.dev),
15+
which provides a declarative API for the lifecycle management of the Flux controllers, including
16+
automated CVE patching and upgrades.
17+
18+
The operator offers an alternative to the Flux CLI bootstrap, with the option to configure the
19+
reconciliation of the cluster state from OCI artifacts or S3-compatible storage, besides Git repositories.
20+
One of the key features is the ability bootstrap clusters without requiring write access to Git,
21+
which is a common requirement for enterprise customers.
22+
23+
After [installing](https://fluxoperator.dev/docs/guides/install/) the Flux Operator with Helm, Terraform or OLM,
24+
customers can create a [FluxInstance](https://fluxoperator.dev/docs/crd/fluxinstance/)
25+
to deploy the enterprise distribution of Flux:
26+
27+
```yaml
28+
apiVersion: fluxcd.controlplane.io/v1
29+
kind: FluxInstance
30+
metadata:
31+
name: flux
32+
namespace: flux-system
33+
spec:
34+
distribution:
35+
version: "2.8.x"
36+
artifact: "oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests"
37+
registry: "ghcr.io/controlplaneio-fluxcd/distroless"
38+
imagePullSecret: "flux-enterprise-auth"
39+
cluster:
40+
type: kubernetes
41+
multitenant: true
42+
networkPolicy: true
43+
```
44+
45+
To access the ControlPlane registry, the `flux-enterprise-auth` Kubernetes secret must be
46+
created in the `flux-system` namespace and should contain the credentials to pull the enterprise images:
47+
48+
```shell
49+
echo $ENTERPRISE_TOKEN | flux-operator create secret registry flux-enterprise-auth \
50+
--namespace flux-system \
51+
--server=ghcr.io \
52+
--username=flux \
53+
--password-stdin
54+
```
55+
56+
For more information on configuring the cluster sync from various sources and the reconciliation options,
57+
see the [Flux Cluster Sync documentation](https://fluxoperator.dev/docs/instance/sync/).
58+
59+
### Air-Gapped Installation
60+
61+
On air-gapped environments, customers can mirror the ControlPlane distribution
62+
(controller images, Flux Operator image and Helm chart) to a private registry using
63+
the Flux Operator CLI:
64+
65+
```shell
66+
echo $ENTERPRISE_TOKEN | flux-operator distro mirror registry.example.com/fluxcd \
67+
--version=2.8.x \
68+
--variant=enterprise-distroless \
69+
--pull-token-stdin
70+
```
71+
72+
To preview which images will be mirrored without writing to the destination registry,
73+
use the `--dry-run` flag. To verify the provenance of the mirrored images,
74+
use the `--verify` flag to check the signatures of the source images
75+
in the ControlPlane registry with Cosign before copying.
76+
77+
Once the distribution is mirrored, point the [FluxInstance](https://fluxoperator.dev/docs/crd/fluxinstance/)
78+
to the private registry:
79+
80+
```yaml
81+
apiVersion: fluxcd.controlplane.io/v1
82+
kind: FluxInstance
83+
metadata:
84+
name: flux
85+
namespace: flux-system
86+
spec:
87+
distribution:
88+
version: "2.8.x"
89+
registry: "registry.example.com/fluxcd"
90+
variant: "enterprise-distroless"
91+
cluster:
92+
type: kubernetes
93+
multitenant: true
94+
networkPolicy: true
95+
```
96+
97+
When running in an air-gapped environment, the `.spec.distribution.artifact` field must be
98+
omitted and the `spec.distribution.variant` field must be set to a distribution variant
99+
(e.g., `enterprise-distroless` or `enterprise-alpine`) to ensure the operator uses the
100+
correct image digests from the private registry.
101+
102+
### Air-Gapped Automated Updates
103+
104+
The `flux-operator distro mirror` command should be run on a regular basis to keep the mirrored
105+
distribution up-to-date with the latest security patches and updates from ControlPlane.
106+
107+
The upgrade process for air-gapped environments requires for Flux Operator to be updated first,
108+
then the distribution minor version can be bumped in the `FluxInstance` to trigger
109+
the update of the Flux controllers.
110+
111+
To automate the update of patch releases and CVE fixes, customers can leverage
112+
the [ResourceSet](https://fluxoperator.dev/docs/crd/resourceset/) APIs.
113+
114+
In the Git repository synced by Flux, define a ResourceSet that points to the private registry:
115+
116+
```yaml
117+
apiVersion: fluxcd.controlplane.io/v1
118+
kind: ResourceSet
119+
metadata:
120+
name: flux-operator
121+
namespace: flux-system
122+
spec:
123+
inputs:
124+
- interval: "1h"
125+
version: "*"
126+
registry: "registry.example.com/fluxcd"
127+
resources:
128+
- apiVersion: source.toolkit.fluxcd.io/v1
129+
kind: OCIRepository
130+
metadata:
131+
name: << inputs.provider.name >>
132+
namespace: << inputs.provider.namespace >>
133+
spec:
134+
interval: << inputs.interval | quote >>
135+
url: oci://<< inputs.registry >>/charts/flux-operator
136+
layerSelector:
137+
mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
138+
operation: copy
139+
ref:
140+
semver: << inputs.version | quote >>
141+
- apiVersion: helm.toolkit.fluxcd.io/v2
142+
kind: HelmRelease
143+
metadata:
144+
name: << inputs.provider.name >>
145+
namespace: << inputs.provider.namespace >>
146+
spec:
147+
interval: 12h
148+
releaseName: << inputs.provider.name >>
149+
serviceAccountName: << inputs.provider.name >>
150+
upgrade:
151+
strategy:
152+
name: RetryOnFailure
153+
chartRef:
154+
kind: OCIRepository
155+
name: << inputs.provider.name >>
156+
```
157+
158+
The above configuration will scan the private registry for new versions of the Flux Operator chart every hour,
159+
and automatically upgrade the operator to the latest version available in the registry.
160+
Once the operator is updated, it will reconcile the FluxInstance and update the Flux controllers to the latest
161+
patch version of the enterprise distribution.
11162

12163
## Flux Bootstrap
13164

14165
Customers can bootstrap Flux with the enterprise distribution using the Flux CLI or the Flux Terraform provider.
15166
To access the ControlPlane images, customers need to provide the registry address and their
16167
credentials.
17168

18-
Example of Flux CLI bootstrap with the FIPS-compliant images:
169+
Example of Flux CLI bootstrap with the distroless images:
19170

20171
```bash
21172
flux bootstrap github \
@@ -28,6 +179,10 @@ flux bootstrap github \
28179
--registry=ghcr.io/controlplaneio-fluxcd/distroless
29180
```
30181

182+
> It is recommended to migrate from Flux CLI bootstrap to the Flux Operator to take
183+
> advantage of the enterprise distribution features, such as automated CVE patching and upgrades.
184+
> For more information, see the [Flux Operator migration guide](https://fluxoperator.dev/docs/guides/migration/).
185+
31186
Example of Flux Terraform Provider bootstrap with the mainline images:
32187

33188
```hcl
@@ -40,10 +195,10 @@ resource "flux_bootstrap_git" "this" {
40195
}
41196
```
42197

43-
Running the bootstrap command for a cluster with an existing Flux installation will trigger
44-
an in-place upgrade of the Flux controllers to the ControlPlane distribution.
198+
> It is recommended to migrate from Flux TF provider to the Flux Operator TF module.
199+
> For more information, see the [Flux Operator Terraform migration guide](https://github.com/controlplaneio-fluxcd/terraform-kubernetes-flux-operator-bootstrap/blob/main/docs/migration-from-flux-provider.md).
45200

46-
## Automated Updates to Bootstrap Repositories
201+
### Automated Updates to Bootstrap Repositories
47202

48203
For keeping the Flux controllers images digests
49204
and manifests up-to-date with the latest version of the Enterprise Distribution, ControlPlane
@@ -56,75 +211,3 @@ update of the Flux manifests in their bootstrap repositories. For more informati
56211

57212
For customers using other Git providers, ControlPlane provides support for configuring
58213
automated updates for the Flux enterprise distribution.
59-
60-
## Migration to ControlPlane Distribution
61-
62-
Migration to the ControlPlane distribution is straightforward and requires minimal changes to the
63-
existing tooling used for deploying the Flux controllers. Having access to the ControlPlane
64-
registry, you can start using the enterprise distribution by changing the container image references
65-
from `ghcr.io/fluxcd/<controller-name>` to `<control-plane-registry>/<controller-name>`.
66-
67-
On air-gapped environments, customers can copy the ControlPlane container images and the
68-
OCI artifacts (SBOMs and signatures) to their private registry using
69-
the [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) CLI.
70-
71-
Example script for copying the ControlPlane FIPS-compliant images to a private registry:
72-
73-
```bash
74-
FLUX_CONTROLLERS=(
75-
"source-controller"
76-
"kustomize-controller"
77-
"helm-controller"
78-
"notification-controller"
79-
"image-reflector-controller"
80-
"image-automation-controller"
81-
)
82-
83-
crane auth login ghcr.io -u flux -p $ENTERPRISE_TOKEN
84-
85-
for controller in "${FLUX_CONTROLLERS[@]}"; do
86-
crane copy --all-tags ghcr.io/controlplaneio-fluxcd/distroless/$controller <your-registry>/$controller
87-
done
88-
```
89-
90-
## Flux Operator
91-
92-
The ControlPlane distribution includes the [Flux Operator](../operator/index.md),
93-
which provides a declarative API for the lifecycle management of the Flux controllers, including
94-
automated CVE patching and upgrades.
95-
96-
The operator offers an alternative to bootstrap, with the option to configure the
97-
reconciliation of the cluster state from OCI artifacts or S3-compatible storage, besides Git repositories.
98-
99-
To deploy the enterprise distribution of Flux, point the operator to the ControlPlane registry:
100-
101-
```yaml
102-
apiVersion: fluxcd.controlplane.io/v1
103-
kind: FluxInstance
104-
metadata:
105-
name: flux
106-
namespace: flux-system
107-
spec:
108-
distribution:
109-
version: "2.8.x"
110-
registry: "ghcr.io/controlplaneio-fluxcd/distroless"
111-
imagePullSecret: "flux-enterprise-auth"
112-
cluster:
113-
type: kubernetes
114-
domain: "cluster.local"
115-
multitenant: true
116-
networkPolicy: true
117-
```
118-
119-
To access the ControlPlane registry, the `flux-enterprise-auth` Kubernetes secret must be
120-
created in the `flux-system` namespace and should contain the credentials to pull the enterprise images:
121-
122-
```shell
123-
kubectl create secret docker-registry flux-enterprise-auth \
124-
--namespace flux-system \
125-
--docker-server=ghcr.io \
126-
--docker-username=flux \
127-
--docker-password=$ENTERPRISE_TOKEN
128-
```
129-
130-
For more information, see the Flux Operator [documentation](../operator/index.md).

‎docs/distribution/upgrade.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,12 +55,12 @@ spec:
5555
interval: 12h
5656
releaseName: << inputs.provider.name >>
5757
serviceAccountName: << inputs.provider.name >>
58+
upgrade:
59+
strategy:
60+
name: RetryOnFailure
5861
chartRef:
5962
kind: OCIRepository
6063
name: << inputs.provider.name >>
61-
values:
62-
reporting:
63-
interval: 30s
6464
```
6565
6666
If you installed the operator with [Terraform/OpenTofu](https://github.com/controlplaneio-fluxcd/flux-operator/tree/main/config/terraform),

0 commit comments

Comments
 (0)