|
| 1 | +# Air gap installation |
| 2 | + |
| 3 | +This guide will show you how to install Kubewarden in air-gapped environments. In an air-gapped installation of Kubewarden, |
| 4 | +you will need a private OCI registry accessible by your Kubernetes cluster. Kubewarden Policies |
| 5 | +are WebAssembly modules; therefore, they can be stored inside an OCI-compliant registry as OCI artifacts. |
| 6 | +You need to add Kubewarden's images and policies to this OCI registry. Let's see how to do that. |
| 7 | + |
| 8 | +## Requirements |
| 9 | + |
| 10 | +1. Private registry that supports OCI artifacts, [here](../../distributing-policies/oci-registries-support) you can find a list of supported OCI registries. It will be used for storing the container images and policies. |
| 11 | +2. [kwctl](https://github.com/kubewarden/kwctl) 1.3.1 or above |
| 12 | +3. docker v20.10.6 or above |
| 13 | + |
| 14 | +## Save container images in your workstation |
| 15 | + |
| 16 | +1. Download `kubewarden-images.txt` from the Kubewarden [release page](https://github.com/kubewarden/helm-charts/releases/). Alternatively, the `imagelist.txt` and `policylist.txt` files are shipped inside the helm charts containing the used container images and policy wasm modules, respectively. |
| 17 | + |
| 18 | +>**Note:** Optionally, you can verify the signatures of the [helm charts](../../security/verifying-kubewarden#helm-charts) and [container images](../../security/verifying-kubewarden#container-images) |
| 19 | +
|
| 20 | +2. Add `cert-manager` if it is not available in your private registry. |
| 21 | + |
| 22 | +``` |
| 23 | +helm repo add jetstack https://charts.jetstack.io |
| 24 | +helm repo update |
| 25 | +helm pull jetstack/cert-manager |
| 26 | +helm template ./cert-manager-<Version>.tgz | \ |
| 27 | + awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./kubewarden-images.txt |
| 28 | +``` |
| 29 | + |
| 30 | +3. Download `kubewarden-save-images.sh` and `kubewarden-load-images.sh` from the [utils repository](https://github.com/kubewarden/utils). |
| 31 | +4. Save Kubewarden container images into a .tar.gz file: |
| 32 | + |
| 33 | +``` |
| 34 | +./kubewarden-save-images.sh \ |
| 35 | + --image-list ./kubewarden-images.txt \ |
| 36 | + --images kubewarden-images.tar.gz |
| 37 | +``` |
| 38 | + |
| 39 | +Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. |
| 40 | +When the process completes, your current directory will output a tarball named `kubewarden-images.tar.gz`. It will be present in the same directory where you executed the command. |
| 41 | + |
| 42 | +## Save policies in your workstation |
| 43 | + |
| 44 | +1. Add all the policies you want to use in a `policies.txt` file. A file with a list of the default policies can be found in the Kubewarden defaults [release page](https://github.com/kubewarden/helm-charts/releases/) |
| 45 | +2. Download `kubewarden-save-policies.sh` and `kubewarden-load-policies.sh` from the [kwctl repository](https://github.com/kubewarden/kwctl/tree/main/scripts) |
| 46 | +3. Save policies into a .tar.gz file: |
| 47 | + |
| 48 | +``` |
| 49 | +./kubewarden-save-policies.sh --policies-list policies.txt |
| 50 | +``` |
| 51 | + |
| 52 | +kwctl downloads all the policies and stores them as `kubewarden-policies.tar.gz` archive. |
| 53 | + |
| 54 | +## Helm charts |
| 55 | + |
| 56 | +You need to download the following helm charts in your workstation: |
| 57 | + |
| 58 | +``` |
| 59 | +helm pull kubewarden/kubewarden-crds |
| 60 | +helm pull kubewarden/kubewarden-controller |
| 61 | +helm pull kubewarden/kubewarden-defaults |
| 62 | +``` |
| 63 | + |
| 64 | +Download `cert-manager` if it is not installed in the air gap cluster. |
| 65 | + |
| 66 | +``` |
| 67 | +helm pull jetstack/cert-manager |
| 68 | +``` |
| 69 | + |
| 70 | +## Populate private registry |
| 71 | + |
| 72 | +Move `kubewarden-policies.tar.gz`, `kubewarden-images.tar.gz`, `kubewarden-load-images.sh`, `kubewarden-load-policies.sh` and `policies.txt` |
| 73 | +to the air gap environment. |
| 74 | + |
| 75 | +1. Load Kubewarden images into the private registry. Docker client must be authenticated against the local registry |
| 76 | +``` |
| 77 | +./kubewarden-load-images.sh \ |
| 78 | + --image-list ./kubewarden-images.txt \ |
| 79 | + --images kubewarden-images.tar.gz \ |
| 80 | + --registry <REGISTRY.YOURDOMAIN.COM:PORT> |
| 81 | +``` |
| 82 | +2. Load Kubewarden policies into the private registry. Kwctl must be authenticated against the local registry (`kwctl` uses the same mechanism to authenticate as `docker`, a `~/.docker/config.json` file) |
| 83 | +``` |
| 84 | +./kubewarden-load-policies.sh \ |
| 85 | + --policies-list policies.txt \ |
| 86 | + --policies kubewarden-policies.tar.gz \ |
| 87 | + --registry <REGISTRY.YOURDOMAIN.COM:PORT> \ |
| 88 | + --sources-path sources.yml |
| 89 | +``` |
| 90 | + |
| 91 | +>***Caution:*** |
| 92 | +>The `sources.yaml` file is needed by kwctl to connect to registries that fall into these categories: |
| 93 | +> |
| 94 | +>* Authentication is required |
| 95 | +>* Self signed certificate is being used |
| 96 | +>* No TLS termination is done |
| 97 | +> |
| 98 | +>Please refer to [the section on custom certificate authorities](../../distributing-policies/custom-certificate-authorities.md) in our documentation to learn more about configuring the `sources.yaml` file |
| 99 | +
|
| 100 | + |
| 101 | +## Install Kubewarden |
| 102 | + |
| 103 | +Let's install Kubewarden now that we have everything we need in our private registry. The only difference with a normal |
| 104 | +Kubewarden installation is that we need to change the registry in the container images and policies to our private registry. |
| 105 | + |
| 106 | +Install `cert-manager` if it is not already installed in the air gap cluster: |
| 107 | + |
| 108 | +``` |
| 109 | +helm install --create-namespace cert-manager ./cert-manager-<Version>.tgz \ |
| 110 | + -n kubewarden \ |
| 111 | + --set installCRDs=true \ |
| 112 | + --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-controller \ |
| 113 | + --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-webhook \ |
| 114 | + --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-cainjector \ |
| 115 | + --set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-ctl |
| 116 | +``` |
| 117 | + |
| 118 | +Let's install the Kubewarden stack: |
| 119 | + |
| 120 | +``` |
| 121 | +helm install --wait -n kubewarden \ |
| 122 | + kubewarden-crds kubewarden-crds.tgz |
| 123 | +``` |
| 124 | + |
| 125 | +``` |
| 126 | +helm install --wait -n kubewarden \ |
| 127 | + kubewarden-controller kubewarden-controller.tgz \ |
| 128 | + --set global.cattle.systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> |
| 129 | +``` |
| 130 | + |
| 131 | +``` |
| 132 | +helm install --wait -n kubewarden \ |
| 133 | + kubewarden-defaults kubewarden-defaults.tgz \ |
| 134 | + --set global.cattle.systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> |
| 135 | +``` |
| 136 | + |
| 137 | +>***Caution*** |
| 138 | +>To download the recommended policies installed by the `kubewarden-defaults` Helm |
| 139 | +>Chart from a registry other than `global.cattle.systemDefaultRegistry`, you can |
| 140 | +>utilize the `recommendedPolicies.defaultPoliciesRegistry` configuration. This |
| 141 | +>configuration allows users to specify a registry dedicated to pulling the OCI |
| 142 | +>artifacts of the policies. It is particularly useful when their container image |
| 143 | +>repository does not support OCI artifacts. |
| 144 | +> |
| 145 | +>To install and wait for the installation to complete, use the following command: |
| 146 | +> |
| 147 | +>```console |
| 148 | +>helm install --wait -n kubewarden \ |
| 149 | +> kubewarden-defaults kubewarden-defaults.tgz \ |
| 150 | +> --set global.cattle.systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ |
| 151 | +> --set recommendedPolicies.defaultPoliciesRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> |
| 152 | +>``` |
| 153 | +> |
| 154 | +>If the `recommendedPolicies.defaultPoliciesRegistry` configuration is not set, |
| 155 | +>the `global.cattle.systemDefaultRegistry` will be used as the default registry. |
0 commit comments