Merge pull request #993 from fluxcd/air-gapped-install

Document air-gapped install procedure

docs/guides/installation.md

@@ -58,8 +58,7 @@ You can choose what components to install and for which cluster with:
 flux bootstrap <GIT-PROVIDER> \
   --components=source-controller,kustomize-controller,helm-controller,notification-controller \
   --components-extra=image-reflector-controller,image-automation-controller \
-  --path=clusters/my-cluster \
+  --path=clusters/my-cluster
-  --version=latest
 ```
 
 !!! hint "Multi-arch images"
@@ -68,7 +67,7 @@ flux bootstrap <GIT-PROVIDER> \
     architectures.
 
 If you wish to install a specific version, use the Flux
-[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.2.0`.
+[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.9.0`.
 
 If you wish to deploy the Flux components onto
 [tainted Kubernetes nodes](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/),
@@ -226,55 +225,77 @@ flux bootstrap gitlab \
   --path=clusters/my-cluster
 ```
 
-### Generic Git Server
+### Air-gapped Environments
 
-For other Git providers such as Bitbucket, Gogs, Gitea, Azure DevOps, etc you can manually setup the repository and the deploy key.
+To bootstrap Flux on air-gapped environments without access to github.com and ghcr.io, first you'll need 
+to download the `flux` binary, and the container images from a computer with access to internet.
 
-Create a Git repository and clone it locally:
+List all container images:
 
-```sh
+```console
-git clone ssh://<host>/<org>/my-repository
+$ flux install --export | grep ghcr.io
-cd my-repository
+
+image: ghcr.io/fluxcd/helm-controller:v0.8.0
+image: ghcr.io/fluxcd/kustomize-controller:v0.9.0
+image: ghcr.io/fluxcd/notification-controller:v0.9.0
+image: ghcr.io/fluxcd/source-controller:v0.9.0
 ```
 
-Create a directory inside the repository:
+Pull the images locally and push them to your container registry:
 
 ```sh
-mkdir -p ./clusters/my-cluster/flux-system
+docker pull ghcr.io/fluxcd/source-controller:v0.9.0
+docker tag ghcr.io/fluxcd/source-controller:v0.9.0 registry.internal/fluxcd/source-controller:v0.9.0
+docker push registry.internal/fluxcd/source-controller:v0.9.0
 ```
 
-Generate the Flux manifests with:
+Copy `flux` binary to a computer with access to your air-gapped cluster,
+and create the pull secret in the `flux-system` namespace:
 
 ```sh
-flux install --version=latest \
+kubectl create ns flux-system
-  --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
+
+kubectl -n flux-system create secret generic regcred \
+    --from-file=.dockerconfigjson=/.docker/config.json \
+    --type=kubernetes.io/dockerconfigjson
 ```
 
-If your cluster must pull images from a private container registry, first you should pull
+Finally, bootstrap Flux using the images from your private registry:
-the toolkit images from GitHub Container Registry and push them to your registry, for example:
 
 ```sh
-docker pull ghcr.io/fluxcd/source-controller:v0.2.0
+flux bootstrap <GIT-PROVIDER> \
-docker tag ghcr.io/fluxcd/source-controller:v0.2.0 registry.internal/fluxcd/source-controller:v0.2.0
+  --registry=registry.internal/fluxcd \
-docker push registry.internal/fluxcd/source-controller:v0.2.0
+  --image-pull-secret=regcred \
+  --hostname=my-git-server.internal
 ```
 
-Create the pull secret in the `flux-system` namespace:
+Note that when running `flux bootstrap` without specifying a `--version`,
+the CLI will use the manifests embedded in its binary instead of downloading
+them from GitHub. You can determine which version you'll be installing,
+with `flux --version`.
+
+### Generic Git Server
+
+For other Git providers such as Bitbucket, Gogs, Gitea, Azure DevOps, etc
+you can manually setup the repository and deploy key.
+
+Create a Git repository and clone it locally:
 
 ```sh
-kubectl create ns flux-system
+git clone ssh://<host>/<org>/my-repository
+cd my-repository
+```
 
-kubectl -n flux-system create secret generic regcred \
+Create a directory inside the repository:
-    --from-file=.dockerconfigjson=/.docker/config.json \
+
-    --type=kubernetes.io/dockerconfigjson
+```sh
+mkdir -p ./clusters/my-cluster/flux-system
 ```
 
-Set your registry domain, and the pull secret when generating the manifests:
+Generate the Flux manifests with:
 
 ```sh
-flux install --version=latest \
+flux install \
-  --registry=registry.internal/fluxcd \
-  --image-pull-secret=regcred \
   --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
 ```
 
@@ -380,10 +401,11 @@ cd ./clusters/my-cluster/flux-system && kustomize create --autodetect
 git add -A && git commit -m "add sync manifests" && git push
 ```
 
-To upgrade the Flux components to a newer version, run the install command and commit the changes:
+To upgrade the Flux components to a newer version, download the latest `flux` binary,
+run the install command and commit the changes:
 
 ```sh
-flux install --version=latest \
+flux install \
   --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
 
 git add -A && git commit -m "update flux" && git push
@@ -484,7 +506,7 @@ Flux will detect the change and will update itself on the production cluster.
 For testing purposes you can install Flux without storing its manifests in a Git repository:
 
 ```sh
-flux install --arch=amd64
+flux install
 ```
 
 Or using kubectl:
@@ -592,11 +614,10 @@ kubectl annotate --overwrite gitrepository/flux-system reconcile.fluxcd.io/reque
 If you've installed Flux directly on the cluster, then rerun the install command:
 
 ```sh
-flux install --version=latest
+flux install
 ```
 
-The above command will download the latest manifests from
+The above command will  apply the new manifests on your cluster.
-[GitHub](https://github.com/fluxcd/flux2/releases) and it will apply them on your cluster.
 You can verify that the controllers have been upgraded to the latest version with `flux check`.
 
 If you've installed Flux directly on the cluster with kubectl,