Updating docs for latest minor releases (#759)

* Updating docs for latest minor releases Signed-off-by: rcmadhankumar <[email protected]> * Update kapp docs to latest version Signed-off-by: rcmadhankumar <[email protected]> --------- Signed-off-by: rcmadhankumar <[email protected]>
carvel-dev · Apr 23, 2024 · 712247c · 712247c
1 parent 02770fb
commit 712247c
Show file tree

Hide file tree

Showing 209 changed files with 15,354 additions and 95 deletions.
diff --git a/site/config.yaml b/site/config.yaml
@@ -23,15 +23,16 @@ params:
   ytt:
     name: ytt
     root_link: /ytt/
-    latest_docs_link: /ytt/docs/v0.48.0/
+    latest_docs_link: /ytt/docs/v0.49.x/
     github_url: https://github.com/carvel-dev/ytt
     search: true
     search_index_name: carvel-ytt
     search_api_key: a38560864c2e9128ae57d5734df438ff
     versioning: true
-    version_latest: v0.48.0
+    version_latest: v0.49.x
     versions:
     - develop
+    - v0.49.x
     - v0.48.0
     - v0.47.x
     - v0.46.x
@@ -47,15 +48,16 @@ params:
     name: kbld
     short_name: kbld
     root_link: /kbld/
-    latest_docs_link: /kbld/docs/v0.42.x/
+    latest_docs_link: /kbld/docs/v0.43.x/
     github_url: https://github.com/carvel-dev/kbld
     search: true
     search_index_name: carvel-kbld
     search_api_key: a38560864c2e9128ae57d5734df438ff
     versioning: true
-    version_latest: v0.42.x
+    version_latest: v0.43.x
     versions:
     - develop
+    - v0.43.x
     - v0.42.x
     - v0.41.x
     - v0.40.x
@@ -71,15 +73,17 @@ params:
     name: kapp
     short_name: kapp
     root_link: /kapp/
-    latest_docs_link: /kapp/docs/v0.60.x/
+    latest_docs_link: /kapp/docs/v0.62.x/
     github_url: https://github.com/carvel-dev/kapp
     search: true
     search_index_name: carvel-kapp
     search_api_key: a38560864c2e9128ae57d5734df438ff
     versioning: true
-    version_latest: v0.60.x
+    version_latest: v0.62.x
     versions:
     - develop
+    - v0.62.x
+    - v0.61.x
     - v0.60.x
     - v0.59.x
     - v0.58.x
@@ -101,15 +105,16 @@ params:
     name: imgpkg
     short_name: imgpkg
     root_link: /imgpkg/
-    latest_docs_link: /imgpkg/docs/v0.41.x/
+    latest_docs_link: /imgpkg/docs/v0.42.x/
     github_url: https://github.com/carvel-dev/imgpkg
     search: true
     search_index_name: carvel-imgpkg
     search_api_key: a38560864c2e9128ae57d5734df438ff
     versioning: true
-    version_latest: v0.41.x
+    version_latest: v0.42.x
     versions:
     - develop
+    - v0.42.x
     - v0.41.x
     - v0.40.x
     - v0.39.x

diff --git a/site/content/imgpkg/docs/v0.41.x/_index.md b/site/content/imgpkg/docs/v0.41.x/_index.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/]
+
 title: "About imgpkg"
 toc: "false"
 cascade:

diff --git a/site/content/imgpkg/docs/v0.41.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.41.x/air-gapped-workflow.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/air-gapped-workflow]
+
 title: Air-gapped Workflow
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/auth.md b/site/content/imgpkg/docs/v0.41.x/auth.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/auth]
+
 title: Authentication
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/automation-workflow.md b/site/content/imgpkg/docs/v0.41.x/automation-workflow.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/automation-workflow]
+
 title: Automation Workflow
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/basic-workflow.md b/site/content/imgpkg/docs/v0.41.x/basic-workflow.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/basic-workflow]
+
 title: Basic Workflow
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/ca-certs-windows.md b/site/content/imgpkg/docs/v0.41.x/ca-certs-windows.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/ca-certs-windows]
+
 title: CA Certs on Windows
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/commands.md b/site/content/imgpkg/docs/v0.41.x/commands.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/commands]
+
 title: Commands
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/debugging.md b/site/content/imgpkg/docs/v0.41.x/debugging.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/debugging]
+
 title: Debugging
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/faq-generic.md b/site/content/imgpkg/docs/v0.41.x/faq-generic.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/faq-generic]
+
 title: FAQ
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/install.md b/site/content/imgpkg/docs/v0.41.x/install.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/install]
+
 title: Install
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/proxy.md b/site/content/imgpkg/docs/v0.41.x/proxy.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/proxy]
+
 title: Proxy
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/resources.md b/site/content/imgpkg/docs/v0.41.x/resources.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/resources]
+
 title: Resources
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/security.md b/site/content/imgpkg/docs/v0.41.x/security.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/security]
+
 title: Security
 ---
 

diff --git a/site/content/imgpkg/docs/v0.41.x/working-directly-with-images.md b/site/content/imgpkg/docs/v0.41.x/working-directly-with-images.md
@@ -1,5 +1,5 @@
 ---
-aliases: [/imgpkg/docs/latest/working-directly-with-images]
+
 title: Working directly with images
 ---
 

diff --git a/site/content/imgpkg/docs/v0.42.x/_index.md b/site/content/imgpkg/docs/v0.42.x/_index.md
@@ -0,0 +1,21 @@
+---
+aliases: [/imgpkg/docs/latest/]
+title: "About imgpkg"
+toc: "false"
+cascade:
+  version: v0.42.x
+  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
diff --git a/site/content/imgpkg/docs/v0.42.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.42.x/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.