Document our airgap example

Fully explain how to use the airgap example bundle to validate how
Porter publishes bundles in airgapped environments.

Signed-off-by: Carolyn Van Slyck <[email protected]>

docs/config.toml

@@ -212,8 +212,8 @@ pygmentsStyle = "friendly"
         parent = "tasks-administrators"
       [[menu.main]]
         name = "Move a bundle across an airgap"
-        identifier = "archive-bundles"
-        url = "/archive-bundles/"
+        identifier = "administrators-airgap"
+        url = "/administrators/airgap/"
         weight = 6
         parent = "tasks-administrators"
       [[menu.main]]

docs/content/administrators/airgap.md

@@ -0,0 +1,21 @@
+---
+title: Move a bundle across an airgap
+description: How to deploy in an airgapped or disconnected environment
+---
+
+An airgapped environment is an environment that doesn't have full access to common networks such as the internet and as such some actions such as pulling Docker images from Docker Hub, or downloading a build artifact, may not be possible.
+These disconnected environments are common in secure environments that handle sensitive data.
+Porter can help deploy across an airgap by including everything that your bundle needs to deploy, including Docker images referenced by the bundle.
+
+todo: picture of moving something across an airgap
+
+At a high level, this involves the following steps:
+
+1. Archive the bundle to a compressed file (tgz).
+2. Move the archive across the airgap on physical media such as a disc or USB drive.
+3. Publish the bundle to a registry on the other side of the airgap.
+4. Install the bundle referencing the new location of the bundle inside the airgapped network.
+
+## Next Steps
+* [Example: Airgapped Environments](/examples/airgap/)
+* [Understand how Porter publishes archived bundles to a registry](/archive-bundles/)

docs/content/archive-bundles.md

@@ -5,6 +5,8 @@ description: Archiving Bundles with Porter
 
 Porter allows you to share bundles by [publishing](/distribute-bundles) them to an OCI registry. Porter also allows you to copy a bundle from one registry to another. Using these commands, bundle users have flexibility in how they leverage published bundles. What if you want to use a published bundle on a disconnected or edge network that has limited connectivity? The `porter archive` command and the `porter publish` commands allow you to take the bundle from a registry on one network, move it to the network or location, and republish it into another registry for use within that environment. The generated bundle archive contains the CNAB `bundle.json`, along with an OCI [image layout](https://github.com/opencontainers/image-spec/blob/master/image-layout.md) containing the invocation image and any images declared in the `images` section of the `bundle.json`. This enables the entire bundle to be easily moved into a private data center or across an air-gapped network, and republished within that environment.
 
+For a working example of how to move a bundle across an airgap, read [Example: Airgapped Environments](/examples/airgap/).
+
 ## Generating a Bundle Archive With Porter
 
 In order to generate the archive, all of the images in the bundle **must** have been published to a registry. For this reason, you must first `publish` your bundle to a registry:
@@ -97,3 +99,7 @@ Outputs:
 Name         Description                                Type     Applies To
 service_ip   IP Address assigned to the Load Balancer   string   All Actions
 ```
+
+## Next Steps
+
+* [Example: Airgapped Environments](/examples/airgap/)

docs/content/examples/airgap.md

@@ -0,0 +1,169 @@
+---
+title: "Example: Airgapped Environments"
+description: "Learn how deploy in a disconnected or airgapped environments with Porter"
+weight: 10
+---
+
+The [getporter/whalegap] bundle demonstrates how to create a bundle for airgapped, or disconnected, environments. 
+
+Source: https://porter.sh/src/examples/airgap
+
+The whalegap bundle distributes the [whalesay app], which is deployed with Helm to a Kubernetes cluster.
+This application serves an endpoint that draws the cowsay CLI output as a whale.
+
+Let's walk through how to create a bundle that can be deployed in an airgapped environment.
+
+```
+ _____________________
+< Challenge Accepted! >
+ ---------------------
+    \
+     \
+      \
+                    ##        .
+              ## ## ##       ==
+           ## ## ## ##      ===
+       /""""""""""""""""___/ ===
+  ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
+       \______ o          __/
+        \    \        __/
+          \____\______/
+```
+
+## Author the bundle
+The bundle must declare any additional images required for installation in order for Porter to include them in the bundle.
+
+Here's the [full working example whalesay bundle][whalesay-bundle] for you to
+follow along with.
+
+[whalesay-bundle]: /src/examples/airgap/
+
+### Declare Images
+
+Add an [images] section and declare every image that your application relies upon:
+
+```yaml
+images:
+  whalesayd:
+      description: "Whalesay as a service"
+      imageType: "docker"
+      repository: "carolynvs/whalesayd"
+      digest: "sha256:8b92b7269f59e3ed824e811a1ff1ee64f0d44c0218efefada57a4bebc2d7ef6f"
+```
+
+The repository field should be the image name, without a tag or digest included, and the digest is the repository digest of the image.
+You can get that information by running the following docker command:
+
+```console
+$ docker image inspect carolynvs/whalesayd:v0.1.0 --format '{{.RepoDigests}}'
+[carolynvs/whalesayd@sha256:8b92b7269f59e3ed824e811a1ff1ee64f0d44c0218efefada57a4bebc2d7ef6f]
+```
+
+### Specify new image location
+
+When a bundle is published, any images listed in this section are published with the bundle as well.
+The new location of the image is made available as a template variable so that you can reference the new location in the bundle actions.
+You must work with the image using its digest and not a tag.
+
+```yaml
+install:
+  - helm3:
+      description: "Install WhaleGap"
+      name: whalegap
+      chart: ./charts/whalegap
+      replace: true
+      set:
+        image.repository: "{{ bundle.images.whalesayd.repository }}"
+        image.digest: "{{ bundle.images.whalesayd.digest }}"
+```
+
+The helm chart must have been written to allow specifying the location of any images in digested form.
+Then in your install step, use the helm \--set flag overriding the image with its location in the airgapped environment.
+Porter handles tracking the image location for you, just use the template variables to swap the image used by the helm chart.
+
+[images]: /author-bundles/#images
+
+## Move the bundle across the airgap
+
+Let's simulate moving the bundle across an airgap by publishing the bundle to a different registry.
+If you _really_ want to practice an airgapped deployment, set up a [local KinD cluster with its own registry](https://kind.sigs.k8s.io/docs/user/local-registry/), and then before installing the bundle, turn off your wifi (or unplug your ethernet cable).
+
+1. Use the archive command to create a tgz file of the bundle, which includes all images referenced in the porter.yaml file.
+    ```console
+     porter archive whalegap.tgz --reference getporter/whalegap:v0.1.1
+    ```
+2. If you have a disconnected network to test with, copy whalegap.tgz over to it now.
+   For this example, we will do the best we can without a real airgap, and check what was deployed to verify it didn't access the original location of the images.
+3. Publish the bundle from the archive file to a different registry, such as your personal Docker Hub account.
+    ```console
+    porter publish --archive whalegap.tgz --reference YOURNAME/whalegap:v0.1.1
+    ```
+
+## Run the bundle
+
+Now that the bundle is ready to use in our "airgapped" environment, let's install the bundle and see what happens.
+
+First, create a credential set that includes the target cluster's kubeconfig.
+Edit the filepath to the kubeconfig with a path to a valid kubeconfig file.
+
+```yaml
+# mycluster-credentials.yaml
+schemaType: CredentialSet
+schemaVersion: 1.0.0
+name: mycluster
+credentials:
+  - name: kubeconfig
+    source:
+      path: $HOME/.kube/config
+```
+
+Apply the credential set so that it can be used when the bundle is installed:
+
+```console
+porter credentials apply mycluster-credentials.yaml
+```
+
+Finally, install the bundle referencing the new location of the bundle:
+
+```console
+porter install airgap-example --reference YOURNAME/whalegap:v0.1.1 -c mycluster
+```
+
+After the bundle finishes installing, inspect the pod created by the bundle to verify that the pod is using the new location that is accessible from within the airgapped environment. 
+
+```console
+$ kubectl get pods
+NAME                            READY   STATUS      RESTARTS   AGE
+whalegap-5bf4dcdb86-zb4rm       1/1     Running     0          40s
+
+$ kubectl describe pod whalegap-5bf4dcdb86-zb4rm
+Name:         whalegap-5bf4dcdb86-zb4rm
+Namespace:    quickstart
+Priority:     0
+Node:         porter-control-plane/172.19.0.3
+Start Time:   Mon, 07 Feb 2022 12:13:46 -0600
+Labels:       app.kubernetes.io/instance=whalegap
+              app.kubernetes.io/name=whalegap
+              pod-template-hash=5bf4dcdb86
+Annotations:  <none>
+Status:       Running
+IP:           10.244.0.19
+IPs:
+  IP:           10.244.0.19
+Controlled By:  ReplicaSet/whalegap-5bf4dcdb86
+Containers:
+  whalegap:
+    Container ID:   containerd://029d836e5b1818b6a99b7b2783087807e4adaa12521011d2870fbaf2ed876a5e
+    Image:          YOURNAME/whalegap@sha256:8b92b7269f59e3ed824e811a1ff1ee64f0d44c0218efefada57a4bebc2d7ef6f
+    Image ID:       docker.io/YOURNAME/whalegap@sha256:8b92b7269f59e3ed824e811a1ff1ee64f0d44c0218efefada57a4bebc2d7ef6f
+```
+
+From the output of kubectl describe, you can see that the image deployed was not the original image referenced in the bundle getporter/whalesayd, and instead it references a new location _inside_ the relocated bundle repository.
+All referenced images are published into the same repository as the bundle, and they are only available using their digest, not the original image name.
+
+## Next Steps
+
+* [Understand how Porter publishes archived bundles to a registry](/archive-bundles/)
+
+[getporter/whalegap]: https://hub.docker.com/r/getporter/whalegap
+[whalesay app]: https://github.com/carolynvs/whalesayd

examples/airgap/README.md

@@ -0,0 +1,3 @@
+# Example: Airgapped Environments
+
+Try out this example at https://release-v1.porter.sh/examples/airgap/.