Version the documentation for all tools

.github/workflows/fail-due-to-change-in-frozen-doc.yml

@@ -0,0 +1,26 @@
+name: fronzen-doc-check
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  check-for-fronzen-doc-change:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.x
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 2
+      - name: Build Tools
+        run: |
+          set -e -x
+          ./site/hack/build.sh
+      - name: Check if frozen documentation was changed
+        run:  |
+          set -e -x
+          ./site/hack/validate-doc-change.sh

site/README.md

@@ -28,4 +28,16 @@ Serve site at [http://localhost:1313]()
 - `/content/` includes content for tool docs
 - `/data/` includes configuration for docs TOCs
 
-More details: [Directory Structure Explained](https://gohugo.io/getting-started/directory-structure/)
+More details: [Directory Structure Explained](https://gohugo.io/getting-started/directory-structure/)
+
+### Generate documentation for new version
+When creating a new version v0.1.0 of imgpkg
+```bash
+./hack/release-docs.sh imgpkg v0.1.0
+```
+
+### Generate documentation for new patch
+When creating a patch v0.1.1 for the version v0.1.0 of imgpkg
+```bash
+./hack/release-docs.sh imgpkg v0.1.1 v0.1.0
+```

site/config.yaml

@@ -1,97 +1,114 @@
----
-baseURL: "https://carvel.dev"
+baseURL: https://carvel.dev
 disablePathToLower: true
 languageCode: en-us
-DefaultContentLanguage: "en"
-title: "Carvel"
-theme: "carvel"
+DefaultContentLanguage: en
+title: Carvel
+theme: carvel
 frontmatter:
-  date: [":filename", ":default"]
+  date:
+  - :filename
+  - :default
 params:
-  products: [kapp-controller, ytt, kapp, kbld, imgpkg, vendir]
+  products:
+  - kapp-controller
+  - ytt
+  - kapp
+  - kbld
+  - imgpkg
+  - vendir
+  search:
+    app_id: BSVMS0V37R
   ytt:
     name: ytt
     root_link: /ytt/
-    latest_docs_link: /ytt/docs/latest/
+    latest_docs_link: /ytt/docs/v0.38.0/
     github_url: https://github.com/vmware-tanzu/carvel-ytt
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: ytt
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.38.0
     versions:
-      - latest
+    - develop
+    - v0.38.0
   kbld:
     name: kbld
     short_name: kbld
     root_link: /kbld/
-    latest_docs_link: /kbld/docs/latest/
+    latest_docs_link: /kbld/docs/v0.32.0/
     github_url: https://github.com/vmware-tanzu/carvel-kbld
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: kbld
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.32.0
     versions:
-      - latest
+    - develop
+    - v0.32.0
   kapp:
     name: kapp
     short_name: kapp
     root_link: /kapp/
-    latest_docs_link: /kapp/docs/latest/
+    latest_docs_link: /kapp/docs/v0.45.0/
     github_url: https://github.com/vmware-tanzu/carvel-kapp
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: kapp
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.45.0
     versions:
-      - latest
+    - develop
+    - v0.45.0
+    - v0.44.0
   imgpkg:
     name: imgpkg
     short_name: imgpkg
     root_link: /imgpkg/
-    latest_docs_link: /imgpkg/docs/latest/
+    latest_docs_link: /imgpkg/docs/v0.24.0/
     github_url: https://github.com/vmware-tanzu/carvel-imgpkg
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: imgpkg
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.24.0
     versions:
-      - latest
+    - develop
+    - v0.24.0
   kapp-controller:
     name: kapp-controller
     short_name: kc
     root_link: /kapp-controller/
-    latest_docs_link: /kapp-controller/docs/latest/
+    latest_docs_link: /kapp-controller/docs/v0.32.0/
     github_url: https://github.com/vmware-tanzu/carvel-kapp-controller
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: kapp-controller
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.32.0
     versions:
-      - latest
+    - develop
+    - v0.32.0
+    - v0.31.0
   vendir:
     name: vendir
     short_name: vendir
     root_link: /vendir/
-    latest_docs_link: /vendir/docs/latest/
+    latest_docs_link: /vendir/docs/v0.24.0/
     github_url: https://github.com/vmware-tanzu/carvel-vendir
     search: true
     search_index_name: carvel
-    search_api_key: 582b1408d7a3fe145c0f84f48ca03755
+    search_api_key: b20c4201c550557613a0c4771996b6c5
     search_tag: vendir
-    versioning: false
-    version_latest: latest
+    versioning: true
+    version_latest: v0.24.0
     versions:
-      - latest
+    - develop
+    - v0.24.0
   links:
     twitter_url: https://twitter.com/carvel_dev
     github_url: https://github.com/vmware-tanzu/carvel
@@ -110,4 +127,4 @@ markup:
     style: github
     tabWidth: 4
 permalinks:
-  tags: "/blog/tags/:slug"
+  tags: /blog/tags/:slug

site/content/imgpkg/docs/latest/_index.md → site/content/imgpkg/docs/develop/_index.md

@@ -2,7 +2,7 @@
 title: "About imgpkg"
 toc: "false"
 cascade:
-  version: latest
+  version: develop
   toc: "true"
   type: docs
   layout: docs

site/content/imgpkg/docs/v0.24.0/_index.md

@@ -0,0 +1,21 @@
+---
+aliases: [/imgpkg/docs/latest/]
+title: "About imgpkg"
+toc: "false"
+cascade:
+  version: v0.24.0
+  toc: "true"
+  type: docs
+  layout: docs
+---
+
+`imgpkg` is a tool that allows users to store a set of arbitrary files as an OCI image. One of the driving use cases is to store Kubernetes configuration (plain YAML, ytt templates, Helm templates, etc.) in OCI registry as an image.
+
+`imgpkg`'s primary concept is a [bundle](resources.md#bundle), which is an OCI image that holds 0+ arbitrary files and 0+ references to dependent OCI images (which *may* also be [bundles](resources.md/#nested-bundle)). With this concept, `imgpkg` is able to copy bundles and their dependent images across registries (both online and offline).
+
+![Bundle diagram](/images/imgpkg/bundle-diagram.png)
+
+## Workflows
+
+- [Basic Workflow](basic-workflow.md) shows how to create, push, and pull bundles with a simple Kubernetes application
+- [Air-gapped Workflow](air-gapped-workflow.md) shows how to copy bundles from one registry to another, to enable running Kubernetes applications without relying on external (public) registries

site/content/imgpkg/docs/v0.24.0/air-gapped-workflow.md

@@ -0,0 +1,154 @@
+---
+aliases: [/imgpkg/docs/latest/air-gapped-workflow]
+title: Air-gapped Workflow
+---
+
+## Scenario
+
+You want to ensure Kubernetes application does not rely on images from external registries when deployed.
+
+This scenario _also_ applies when trying to ensure that all images are consolidated into a single registry, even if that registry is not air-gapped.
+
+## Prerequisites
+
+To complete this workflow you will need access to an OCI registry like Docker Hub, and optionally, 
+a Kubernetes cluster. (If you would like to use a local registry and Kubernetes cluster, try using [Kind](https://kind.sigs.k8s.io/docs/user/local-registry/))
+
+If you would like to deploy the results of this scenario to your Kubernetes cluster, you will additionally need [`kbld`](/kbld) and kubectl.
+
+If any of your bundles contain [non-distributable layers](commands.md#non-distributable-or-foreign-layers) you will need to include
+the `--include-non-distributable-layers` flag to each copy command in the examples provided.
+
+---
+## Step 1: Finding bundle in source registry
+
+If you have already pushed a bundle to the registry, continue to the next step.
+
+If you are trying to bundle your own or third-part software, you will need to create a bundle. Refer to basic workflow's ["Step 1: Creating the bundle" and "Step 2: Pushing the bundle to registry"](basic-workflow.md#step-1-creating-the-bundle).
+
+---
+## Step 2: Two methods of copying bundles
+
+You have two options how to transfer bundle from one registry to another:
+
+- Option 1: From a common location connected to both registries. This option is more efficient because only changed image layers will be transfered between registries.
+- Option 2: With intermediate tarball. This option works best when registries have no common network access.
+
+### Option 1: From a location connected to both registries
+
+1. Get to a location that can access both registries
+
+    This may be a server that has access to both internal and external networks. If there is no such location, you will have to use "Option 2" below.
+
+1. [Authenticate](auth.md) with both source, and destination registries
+
+1. Run following command to copy bundle from one registry to another:
+
+    ```bash-plain
+    $ imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-repo registry.corp.com/apps/simple-app-bundle
+
+    copy | exporting 2 images...
+    copy | will export index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
+    copy | will export index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb
+    copy | exported 2 images
+    copy | importing 2 images...
+    copy | importing index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb
+           -> registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb...
+    copy | importing index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
+           -> registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0...
+    copy | imported 2 images
+    Succeeded
+    ```
+
+    The bundle, and all images referenced in the bundle, are copied to the destination registry.
+
+    Flags used in the command:
+      * `-b` (`--bundle`) indicates the bundle location in the source registry
+      * `--to-repo` indicates the registry where the bundle and associated images should be copied to
+
+### Option 2: With intermediate tarball
+
+1. Get to a location that can access source registry
+
+1. [Authenticate with the source registry](auth.md)
+
+1. Save the bundle to a tarball
+
+    ```bash-plain
+    $ imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-tar /tmp/my-image.tar
+
+    copy | exporting 2 images...
+    copy | will export index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
+    copy | will export index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb
+    copy | exported 2 images
+    copy | writing layers...
+    copy | done: file 'manifest.json' (13.71µs)
+    copy | done: file 'sha256-233f1d0dbdc8cf675af965df8639b0dfd4ef7542dfc9fcfd03bfc45c570b0e4d.tar.gz' (47.616µs)
+    copy | done: file 'sha256-8ece9ac45f2b7228b2ed95e9f407b4f0dc2ac74f93c62ff1156f24c53042ba54.tar.gz' (43.204905ms)
+    Succeeded
+    ```
+
+    Flags used in the command:
+      * `-b` (`--bundle`) indicates the bundle location in the source registry
+      * `--to-tar` indicates the local location to write a tar file containing the bundle assets
+
+1. Transfer the local tarball `/tmp/my-image.tar` to a location with access to the destination registry
+
+1. [Authenticate with the destination registry](auth.md)
+
+1. Import the bundle from your tarball to the destination registry:
+
+    ```bash-plain
+    $ imgpkg copy --tar /tmp/my-image.tar --to-repo registry.corp.com/apps/simple-app-bundle
+
+    copy | importing 2 images...
+    copy | importing index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb -> registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb...
+    copy | importing index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 -> registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0...
+    copy | imported 2 images
+    Succeeded
+    ```
+
+    The bundle, and all images referenced in the bundle, are copied to the destination registry.
+
+    Flags used in the command:
+      * `--tar` indicates the path to a tar file containing the assets to be copied to a registry
+      * `--to-repo` indicates destination bundle location in the registry
+
+---
+## Step 3: Pulling bundle from destination registry
+
+1. [Authenticate with the destination registry](auth.md)
+
+1. Pull the bundle from the destination registry:
+
+    ```bash-plain
+    $ imgpkg pull -b registry.corp.com/apps/simple-app-bundle:v1.0.0 -o /tmp/bundle
+
+    Pulling image 'registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb'
+    Extracting layer 'sha256:233f1d0dbdc8cf675af965df8639b0dfd4ef7542dfc9fcfd03bfc45c570b0e4d' (1/1)
+    Locating image lock file images...
+    All images found in bundle repo; updating lock file: /tmp/bundle/.imgpkg/images.yml
+
+    Succeeded
+    ```
+
+    Flags used in the command:
+      * `-b` (`--bundle`) indicates to pull a particular bundle from a registry
+      * `-o` (`--output`) indicates the local folder where the bundle will be unpacked
+
+    Note that the `.imgpkg/images.yml` file was updated with the destination registry locations of the images. This happened because, in the prior step, the images referenced by the bundle were copied into the destination registry.
+
+    ```bash-plain
+    $ cat /tmp/bundle/.imgpkg/images.yml
+    apiVersion: imgpkg.carvel.dev/v1alpha1
+    kind: ImagesLock
+    images:
+    - image: registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
+      annotations:
+        kbld.carvel.dev/id: docker.io/dkalinin/k8s-simple-app
+    ```
+
+---
+## Step 4: Use pulled bundle contents
+
+Regardless which location the bundle is downloaded from, source registry or destination registry, use of the pulled bundle contents remains the same. Continue with ["Step 4: Use pulled bundle contents"](basic-workflow.md#step-4-use-pulled-bundle-contents) in the basic workflow.