Project: Sonobuoy (Provisioning / Security & Compliance)
File: airgap.md

In air-gapped deployments where there is no access to the public Docker registries Sonobuoy supports running the end-to-end tests with custom registries. This enables you to test your air-gapped deployment once you've loaded the necessary images into a registry that is reachable by your cluster. You will need to make the Sonobuoy image available as well as the images for any plugins you wish to run. Below, you will find the details of how to use the Sonobuoy image, as well as the images for the `e2e` and `systemd-logs` plugins in this kind of deployment. To run any Sonobuoy plugin in an air-gapped deployment, you must ensure that the Sonobuoy image is available in a registry that is reachable by your cluster. You will need to pull, tag, and then push the image as follows: ``` PRIVATE_REG=<your private registry> SONOBUOY_VERSION=<version of Sonobuoy you are targeting; e.g. v0.16.0> docker pull sonobuoy/sonobuoy:$SONOBUOY_VERSION docker tag sonobuoy/sonobuoy:$SONOBUOYVERSION $PRIVATEREG/sonobuoy:$SONOBUOY_VERSION docker push $PRIVATEREG/sonobuoy:$SONOBUOYVERSION ``` By default, Sonobuoy will attempt to use the image available in the public registry. To use the image in your own registry, you will need to override it when using the `gen` or `run` command with the `--sonobuoy-image` flag as follows: ``` sonobuoy run --sonobuoy-image $PRIVATEREG/sonobuoy:$SONOBUOYVERSION ``` To use the `e2e` plugin, the conformance test image and the images the tests use must be available in your registry. The process for making the conformance image available in your registry is the same as the Sonobuoy image. You need to pull, tag, and then push the image. To ensure you use the correct version of the conformance image, check your server version using `kubectl version`. ``` PRIVATE_REG=<private registry> CLUSTER_VERSION=<version of k8s you are targeting; e.g. v1.16.0> docker pull k8s.gcr.io/conformance:$CLUSTER_VERSION docker tag k8s.gcr.io/conformance:$CLUSTERVERSION $PRIVATEREG/conformance:$CLUSTER_VERSION docker push $PRIVATEREG/conformance:$CLUSTERVERSION ``` To use the conformance image in your registry, you will need to override the default when using the `gen` or `run` commands with the `--kube-conformance-image` flag as follows: ``` sonobuoy run --kube-conformance-image $PRIVATEREG/conformance:$CLUSTERVERSION ``` The end-to-end tests use a number of different images across multiple registries. When running the `e2e` plugin, you must provide a mapping that details which custom registries should be used instead of the public registries. If you need only a single, custom registry, use the `--e2e-repo` flag to specify that all test registry should be set to the same, given value. If you need multiple registries, you must provide a mapping that the upstream Kubernetes tests

It is provided via a YAML file which maps the registry category to the corresponding registry URL. The keys in this file are specified in the Kubernetes test framework. The tests for each minor version of Kubernetes use a different set of registries so the mapping you create will depend on which Kubernetes version you are testing against. To create this mapping, you can use the `gen default-image-config` command to provide the mapping with the default registry values for your cluster version. The following is an example of using this command with a v1.16 cluster: ``` $ sonobuoy gen default-image-config dockerLibraryRegistry: docker.io/library e2eRegistry: gcr.io/kubernetes-e2e-test-images gcRegistry: k8s.gcr.io googleContainerRegistry: gcr.io/google-containers sampleRegistry: gcr.io/google-samples ``` You can save this output to a file and modify it to specify your own registries instead. You can modify all of the registry values or just a subset. If you specify only a subset, the defaults will be used instead. Sonobuoy provides the command `images` to help you easily pull the test images and push them to your own custom registries. First, you must pull the images to your local machine using the following command: ``` sonobuoy images pull ``` NOTE: Some versions of Kubernetes reference images that do not exist or cannot be pulled without authentication. You may see these errors when running the above command. This is expected behaviour. These images are referenced by some end-to-end tests, but not by the conformance tests. To push the images, you must provide the mapping using the `--e2e-repo` or `--e2e-repo-config` flag as follows: ``` sonobuoy images push --e2e-repo <your registry> // OR sonobuoy images push --e2e-repo-config <path/to/custom-repo-config.yaml> ``` If you are pushing to a single registry; use the first flag; if you need fine-grained controle over which images go to which registry, use the second. When running the `e2e` plugin, you will need to provide this information using the same flag as follows: ``` sonobuoy run --e2e-repo <your registry> // OR sonobuoy run --e2e-repo-config <path/to/custom-repo-config.yaml> ``` If you want to run the `systemd-logs` plugin you will again need to pull, tag, and push the image. ``` PRIVATE_REG=<private registry> docker pull gcr.io/heptio-images/sonobuoy-plugin-systemd-logs:latest docker tag gcr.io/heptio-images/sonobuoy-plugin-systemd-logs:latest $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest docker push $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest ``` To use the image in your own registry, you will need to override the default when using the `gen` or `run` commands with the `--systemd-logs-image` flag as follows: ``` sonobuoy run --systemd-logs-image $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest ``` If you do not wish to run this plugin, you can remove it from the list of to be run within the manifest, or you can explicitly specify which plugin you with to run with the `--plugin` flag.