From c95703f30f805858bd0917ee8a5704b132ffb733 Mon Sep 17 00:00:00 2001 From: Joao Pereira Date: Wed, 21 Feb 2024 15:27:03 -0600 Subject: [PATCH] Bump documentation for imgpkg v0.41.x Signed-off-by: Joao Pereira --- site/config.yaml | 5 +- site/content/imgpkg/docs/v0.40.x/_index.md | 2 +- .../docs/v0.40.x/air-gapped-workflow.md | 2 +- site/content/imgpkg/docs/v0.40.x/auth.md | 2 +- .../docs/v0.40.x/automation-workflow.md | 2 +- .../imgpkg/docs/v0.40.x/basic-workflow.md | 2 +- .../imgpkg/docs/v0.40.x/ca-certs-windows.md | 2 +- site/content/imgpkg/docs/v0.40.x/commands.md | 2 +- site/content/imgpkg/docs/v0.40.x/debugging.md | 2 +- .../imgpkg/docs/v0.40.x/faq-generic.md | 2 +- site/content/imgpkg/docs/v0.40.x/install.md | 2 +- site/content/imgpkg/docs/v0.40.x/proxy.md | 2 +- site/content/imgpkg/docs/v0.40.x/resources.md | 2 +- site/content/imgpkg/docs/v0.40.x/security.md | 2 +- .../v0.40.x/working-directly-with-images.md | 2 +- site/content/imgpkg/docs/v0.41.x/_index.md | 21 +++ .../docs/v0.41.x/air-gapped-workflow.md | 154 +++++++++++++++ site/content/imgpkg/docs/v0.41.x/auth.md | 166 ++++++++++++++++ .../docs/v0.41.x/automation-workflow.md | 141 ++++++++++++++ .../imgpkg/docs/v0.41.x/basic-workflow.md | 150 +++++++++++++++ .../imgpkg/docs/v0.41.x/ca-certs-windows.md | 28 +++ site/content/imgpkg/docs/v0.41.x/commands.md | 178 ++++++++++++++++++ site/content/imgpkg/docs/v0.41.x/debugging.md | 46 +++++ .../imgpkg/docs/v0.41.x/faq-generic.md | 30 +++ site/content/imgpkg/docs/v0.41.x/install.md | 58 ++++++ site/content/imgpkg/docs/v0.41.x/proxy.md | 33 ++++ site/content/imgpkg/docs/v0.41.x/resources.md | 145 ++++++++++++++ site/content/imgpkg/docs/v0.41.x/security.md | 8 + .../v0.41.x/working-directly-with-images.md | 8 + site/data/imgpkg/docs/imgpkg-v0-41-x-toc.yml | 43 +++++ site/data/imgpkg/docs/toc-mapping.yml | 1 + 31 files changed, 1227 insertions(+), 16 deletions(-) create mode 100644 site/content/imgpkg/docs/v0.41.x/_index.md create mode 100644 site/content/imgpkg/docs/v0.41.x/air-gapped-workflow.md create mode 100644 site/content/imgpkg/docs/v0.41.x/auth.md create mode 100644 site/content/imgpkg/docs/v0.41.x/automation-workflow.md create mode 100644 site/content/imgpkg/docs/v0.41.x/basic-workflow.md create mode 100644 site/content/imgpkg/docs/v0.41.x/ca-certs-windows.md create mode 100644 site/content/imgpkg/docs/v0.41.x/commands.md create mode 100644 site/content/imgpkg/docs/v0.41.x/debugging.md create mode 100644 site/content/imgpkg/docs/v0.41.x/faq-generic.md create mode 100644 site/content/imgpkg/docs/v0.41.x/install.md create mode 100644 site/content/imgpkg/docs/v0.41.x/proxy.md create mode 100644 site/content/imgpkg/docs/v0.41.x/resources.md create mode 100644 site/content/imgpkg/docs/v0.41.x/security.md create mode 100644 site/content/imgpkg/docs/v0.41.x/working-directly-with-images.md create mode 100644 site/data/imgpkg/docs/imgpkg-v0-41-x-toc.yml diff --git a/site/config.yaml b/site/config.yaml index 10f07d686..1f2c7110f 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -98,15 +98,16 @@ params: name: imgpkg short_name: imgpkg root_link: /imgpkg/ - latest_docs_link: /imgpkg/docs/v0.40.x/ + latest_docs_link: /imgpkg/docs/v0.41.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.40.x + version_latest: v0.41.x versions: - develop + - v0.41.x - v0.40.x - v0.39.x - v0.38.x diff --git a/site/content/imgpkg/docs/v0.40.x/_index.md b/site/content/imgpkg/docs/v0.40.x/_index.md index 4318f05a7..6795752fc 100644 --- a/site/content/imgpkg/docs/v0.40.x/_index.md +++ b/site/content/imgpkg/docs/v0.40.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.40.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.40.x/air-gapped-workflow.md index a3d589126..146fff0b7 100644 --- a/site/content/imgpkg/docs/v0.40.x/air-gapped-workflow.md +++ b/site/content/imgpkg/docs/v0.40.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.40.x/auth.md b/site/content/imgpkg/docs/v0.40.x/auth.md index df015c0a0..f4a10756b 100644 --- a/site/content/imgpkg/docs/v0.40.x/auth.md +++ b/site/content/imgpkg/docs/v0.40.x/auth.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/auth] + title: Authentication --- diff --git a/site/content/imgpkg/docs/v0.40.x/automation-workflow.md b/site/content/imgpkg/docs/v0.40.x/automation-workflow.md index 0e131150c..1fb36d327 100644 --- a/site/content/imgpkg/docs/v0.40.x/automation-workflow.md +++ b/site/content/imgpkg/docs/v0.40.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.40.x/basic-workflow.md b/site/content/imgpkg/docs/v0.40.x/basic-workflow.md index 271cb07e3..dab6abf3a 100644 --- a/site/content/imgpkg/docs/v0.40.x/basic-workflow.md +++ b/site/content/imgpkg/docs/v0.40.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.40.x/ca-certs-windows.md b/site/content/imgpkg/docs/v0.40.x/ca-certs-windows.md index 2f0404248..950141a4e 100644 --- a/site/content/imgpkg/docs/v0.40.x/ca-certs-windows.md +++ b/site/content/imgpkg/docs/v0.40.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.40.x/commands.md b/site/content/imgpkg/docs/v0.40.x/commands.md index 36e39e270..de4129e8a 100644 --- a/site/content/imgpkg/docs/v0.40.x/commands.md +++ b/site/content/imgpkg/docs/v0.40.x/commands.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/commands] + title: Commands --- diff --git a/site/content/imgpkg/docs/v0.40.x/debugging.md b/site/content/imgpkg/docs/v0.40.x/debugging.md index 9000ae487..e669f95e8 100644 --- a/site/content/imgpkg/docs/v0.40.x/debugging.md +++ b/site/content/imgpkg/docs/v0.40.x/debugging.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/debugging] + title: Debugging --- diff --git a/site/content/imgpkg/docs/v0.40.x/faq-generic.md b/site/content/imgpkg/docs/v0.40.x/faq-generic.md index 879d4bd09..5ff292950 100644 --- a/site/content/imgpkg/docs/v0.40.x/faq-generic.md +++ b/site/content/imgpkg/docs/v0.40.x/faq-generic.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/faq-generic] + title: FAQ --- diff --git a/site/content/imgpkg/docs/v0.40.x/install.md b/site/content/imgpkg/docs/v0.40.x/install.md index d74978ec7..0ba30f7a4 100644 --- a/site/content/imgpkg/docs/v0.40.x/install.md +++ b/site/content/imgpkg/docs/v0.40.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/install] + title: Install --- diff --git a/site/content/imgpkg/docs/v0.40.x/proxy.md b/site/content/imgpkg/docs/v0.40.x/proxy.md index 0998e7dc2..cc509f507 100644 --- a/site/content/imgpkg/docs/v0.40.x/proxy.md +++ b/site/content/imgpkg/docs/v0.40.x/proxy.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/proxy] + title: Proxy --- diff --git a/site/content/imgpkg/docs/v0.40.x/resources.md b/site/content/imgpkg/docs/v0.40.x/resources.md index 6a0300834..7ae340dca 100644 --- a/site/content/imgpkg/docs/v0.40.x/resources.md +++ b/site/content/imgpkg/docs/v0.40.x/resources.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/resources] + title: Resources --- diff --git a/site/content/imgpkg/docs/v0.40.x/security.md b/site/content/imgpkg/docs/v0.40.x/security.md index ca69db28d..c70b75d5e 100644 --- a/site/content/imgpkg/docs/v0.40.x/security.md +++ b/site/content/imgpkg/docs/v0.40.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/security] + title: Security --- diff --git a/site/content/imgpkg/docs/v0.40.x/working-directly-with-images.md b/site/content/imgpkg/docs/v0.40.x/working-directly-with-images.md index cdac04918..21dc3ac34 100644 --- a/site/content/imgpkg/docs/v0.40.x/working-directly-with-images.md +++ b/site/content/imgpkg/docs/v0.40.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.41.x/_index.md b/site/content/imgpkg/docs/v0.41.x/_index.md new file mode 100644 index 000000000..72133cfbd --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/_index.md @@ -0,0 +1,21 @@ +--- +aliases: [/imgpkg/docs/latest/] +title: "About imgpkg" +toc: "false" +cascade: + version: v0.41.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.41.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.41.x/air-gapped-workflow.md new file mode 100644 index 000000000..a3d589126 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.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. diff --git a/site/content/imgpkg/docs/v0.41.x/auth.md b/site/content/imgpkg/docs/v0.41.x/auth.md new file mode 100644 index 000000000..df015c0a0 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/auth.md @@ -0,0 +1,166 @@ +--- +aliases: [/imgpkg/docs/latest/auth] +title: Authentication +--- + +# Ordering + +imgpkg has multiple ways to provide authentication details to registries. + +The order at which imgpkg chooses which authentication details to use is the following: + +1. [Via Environment Variables](#via-environment-variables) +1. [Via IaaS](#via-iaas) +1. [Via Command Flags](#via-command-flags) +1. [Via Docker Config](#via-docker-config) + +## Via Environment Variables + +As of v0.7.0+, `imgpkg` can also use following environment variables: + +- `IMGPKG_REGISTRY_HOSTNAME` to specify registry hostname (e.g. gcr.io, docker.io, https://gcr.io, docker.io/v2/) + - As of v0.18.0+ `IMGPKG_REGISTRY_HOSTNAME` also supports providing glob wildcards. for e.g. `*.*.docker.io` will match `bar.foo.docker.io`. + - Note: if there is overlap between 2 HOSTNAMES, one using globbing and the other not, the HOSTNAME not using globbing will be applied. e.g. `IMGPKG_REGISTRY_HOSTNAME_0=*.docker.io` vs `IMGPKG_REGISTRY_HOSTNAME_1=foo.docker.io` for the image `foo.docker.io/image` will result in auth details from `IMGPKG_REGISTRY_HOSTNAME_1` being used. + - As of v0.18.0+ `IMGPKG_REGISTRY_HOSTNAME` also supports providing the fully qualified repository. for e.g. `gcr.io/repo/image`. +- `IMGPKG_REGISTRY_USERNAME` to specify registry username +- `IMGPKG_REGISTRY_PASSWORD` to specify registry password +- `IMGPKG_REGISTRY_IDENTITY_TOKEN` to authenticate the user and get an access token for the registry via an [oauth2 refresh token grant type](https://docs.docker.com/registry/spec/auth/oauth/). +- `IMGPKG_REGISTRY_REGISTRY_TOKEN` to specify the access token to be used in the Authorization Header as a [Bearer Token](https://docs.docker.com/registry/spec/auth/token/#using-the-bearer-token). + +Since you may need to provide multiple registry credentials, the environment variables above may be specified multiple times with a suffix of 1+ alphanumeric characters, + +e.g. If you had 2 registries you wish to provide authentication credentials for, you would require 2 sets of env variables. + +For Registry #1: + +``` +IMGPKG_REGISTRY_HOSTNAME_0=hostname.for.registry.1 +IMGPKG_REGISTRY_USERNAME_0=username +IMGPKG_REGISTRY_PASSWORD_0=password +``` + +For Registry #2: + +``` +IMGPKG_REGISTRY_HOSTNAME_1=hostname.for.registry.2 +IMGPKG_REGISTRY_IDENTITY_TOKEN_1=token +``` + +When imgpkg interacts with `hostname.for.registry.1`, it will use the env variables with the suffix `_0`. And when interacting with `hostname.for.registry.2`, it will use the env variables with the suffix `_1` + + +Note: Credentials provided via an env variable for a specific registry will take precedence over Command Flags. + +## Via IaaS + +By default, `imgpkg` will **NOT** attempt to authenticate itself via the underlying IaaS: + +To activate this behavior you can set the environment variable `IMGPKG_ACTIVE_KEYCHAINS` with the keychains to the IaaS that you are currently using. + +*Note:* To mimic the old behavior of `imgpkg` set the environment variable as follows `export IMGPKG_ACTIVE_KEYCHAINS=gke,aks,ecr` + +Below is a list of IaaS providers that `imgpkg` can authenticate with: + +- [GCP](https://cloud.google.com/compute/docs/metadata/overview) + + To activate it use `export IMGPKG_ACTIVE_KEYCHAINS=gke` + +- [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) + + To activate it use `export IMGPKG_ACTIVE_KEYCHAINS=ecr` + For more information [check the helper](https://github.com/awslabs/amazon-ecr-credential-helper#configuration) + +- [Azure](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-managed-identities-work-vm) + + To activate it use `export IMGPKG_ACTIVE_KEYCHAINS=aks` + For more information check [this library](https://github.com/chrismellard/docker-credential-acr-env) + +- Github + + To activate use `export IMGPKG_ACTIVE_KEYCHAINS=github` + Requires the environment variable `GITHUB_TOKEN` to be set to connect to ghcr.io + +**Deprecation:** The environment variable `IMGPKG_ENABLE_IAAS_AUTH` can be used only to activate all the keychains. +This behavior will be removed in a future version. + + +## Via Command Flags + +You can explicitly specify credentials via command flags or associated environment variables. See `imgpkg push -h` for further details. + +- `--registry-username` (or `$IMGPKG_USERNAME`) +- `--registry-password` (or `$IMGPKG_PASSWORD`) +- `--registry-token` (or `$IMGPKG_TOKEN`): to specify the access token to be used in the Authorization Header as a [Bearer Token](https://docs.docker.com/registry/spec/auth/token/#using-the-bearer-token). +- `--registry-anon` (or `$IMGPKG_ANON=true`): used for anonymous access (commonly for pulling) + +## Via Docker config + +Even though `imgpkg` commands use registry APIs directly, by default it uses credentials stored in `~/.docker/config.json` which are typically generated via a `docker login` command. + +Example generated `~/.docker/config.json`: + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "dXNlcjpwYXNzd29yZA==" + }, + }, + "HttpHeaders": { + "User-Agent": "Docker-Client/18.09.6 (darwin)" + } +} +``` + +where `dXNlcjpwYXNzd29yZA==` is `base64("username:password")`. + +## gcr.io + +- Create a service account with "Storage Admin" permissions for push access + - See [Permissions and Roles](https://cloud.google.com/container-registry/docs/access-control#permissions_and_roles) +- Download a JSON service account key and place it somewhere on filesystem (e.g. `/tmp/key`) + - See [Advanced authentication](https://cloud.google.com/container-registry/docs/advanced-authentication#json_key_file) +- Run `cat /tmp/key | docker login -u _json_key --password-stdin https://gcr.io` to authenticate + +## AWS ECR + +- Create an ECR repository +- Create an IAM user with an ECR policy that allows read/write + - See [Amazon ECR Policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html) +- Run `aws configure` and specify access key ID, secret access key and region + - To install on Ubuntu, run `apt-get install pip3` and `pip3 install awscli` + - See [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) +- Run `eval $(aws ecr get-login --no-include-email)` to authenticate + - See [get-login command](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html) + +Example ECR policy from [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:DescribeImages", + "ecr:BatchGetImage", + "ecr:InitiateLayerUpload", + "ecr:UploadLayerPart", + "ecr:CompleteLayerUpload", + "ecr:PutImage" + ], + "Resource": "*" + } + ] +} +``` + +## Harbor + +You may have to provide `--registry-ca-cert-path` flag with a path to a CA certificate file for Harbor Registry API. diff --git a/site/content/imgpkg/docs/v0.41.x/automation-workflow.md b/site/content/imgpkg/docs/v0.41.x/automation-workflow.md new file mode 100644 index 000000000..0e131150c --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/automation-workflow.md @@ -0,0 +1,141 @@ +--- +aliases: [/imgpkg/docs/latest/automation-workflow] +title: Automation Workflow +--- + +## Scenario + +When using an automated CI tool you might want to promote a given Bundle between steps of the pipeline + +## Prerequisites + +To complete this workflow you will need access to an OCI registry like Docker Hub. + +### Step 1: Creating the Bundle + +1. Prepare bundle contents + + The [examples/basic-step-1/](https://github.com/carvel-dev/imgpkg/tree/develop/examples/basic-step-1) + directory has a `config.yml` file, which contains a very simple Kubernetes application. Your application may have as + many configuration files as necessary in various formats such as plain YAML, ytt templates, Helm templates, etc. + + In our example `config.yml` includes an image reference to `docker.io/dkalinin/k8s-simple-app`. This reference does + not point to an exact image (via digest) meaning that it may change over time. To ensure we get precisely the bits we + expect, we will lock it down to an exact image next. + +1. Add `.imgpkg/` directory + + [examples/basic-step-2](https://github.com/carvel-dev/imgpkg/tree/develop/examples/basic-step-2) shows what + a `.imgpkg/` directory may look like. It contains: + + - **optional** [bundle.yml](resources.md#bundle-metadata): a file which records informational metadata + - **required** [images.yml](resources.md#imageslock): a file which records image references used by the + configuration + + ```bash-plain + examples/basic-step-2 + ├── .imgpkg + │   ├── bundle.yml + │   └── images.yml + └── config.yml + ``` + + Note that `.imgpkg/images.yml` contains a list of images, each with fully resolved digest reference ( + e.g `index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4...`) and a some additional metadata ( + e.g. `annotations` section). See [ImagesLock configuration](resources.md#imageslock-configuration) for details. + + ```yaml + apiVersion: imgpkg.carvel.dev/v1alpha1 + kind: ImagesLock + images: + - image: index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + annotations: + kbld.carvel.dev/id: docker.io/dkalinin/k8s-simple-app + ``` + +--- + +### Step 2: Creating the Bundle + +1. [Authenticate with a registry](auth.md) where we will push our bundle + +2. Push the bundle to the registry + + You can push the bundle with our specified contents to an OCI registry using the following command: + + ```bash-plain + $ imgpkg push -b index.docker.io/user1/simple-app-bundle:v1.0.0 -f examples/basic-step-2 --lock-output /tmp/bundle-lock.yml + + dir: . + dir: .imgpkg + file: .imgpkg/bundle.yml + file: .imgpkg/images.yml + file: config.yml + Pushed 'index.docker.io/user1/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511' + + Succeeded + ``` + + Flags used in the command: + - `-b` (`--bundle`) refers to a location for a bundle within an OCI registry + - `-f` (`--file`) indicates directory contents to include + - `--lock-output` indicates the destination of the [BundleLock](resources.md#bundlelock-configuration) file + +--- + +## Step 3: Promoting the BundleLock file + +Since in the previous step we generated a BundleLock we can promote this file and in the next steps of the pipeline we +can reference it. + +Examples of usage: + +1. Promote the Bundle to a different registry + + ```bash-plain + $ imgpkg copy --lock /tmp/bundle-lock.yml --to-repo production.registry.io/simple-app-bundle + copy | exporting 2 images... + copy | will export index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + copy | will export production.registry.io/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511 + copy | exported 2 images + copy | importing 2 images... + + 3.56 MiB / 3.57 MiB [========================================================================================================================================================================] 99.68% 8.80 MiB/s 0s + + copy | done uploading images + + Succeeded + ``` + + Flags used in the command: + - `--lock` refers to a location for a BundleLock file + - `--to-repo` indicates the destination Repository where the Bundle is copied to + +2. Download the Bundle contents to disk + + ```bash-plain + $ imgpkg pull --lock /tmp/bundle-lock.yml -o /tmp/simple-app-bundle + + Pulling image 'index.docker.io/user1/simple-app-bundle@sha256:ec3f870e958e404476b9ec67f28c598fa8f00f819b8ae05ee80d51bac9f35f5d' + Extracting layer 'sha256:7906b9650be657359ead106e354f2728e16c8f317e1d87f72b05b5c5ec3d89cc' (1/1) + + Locating image lock file images... + The bundle repo (index.docker.io/user1/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511) is hosting every image specified in the bundle's Images Lock file (.imgpkg/images.yml) + + Succeeded + ``` + + Flags used in the command: + - `--lock`e`) refers to a location for a BundleLock file + - `-o` (`--output`) indicates the destination directory on your local machine where the bundle contents will be + placed + + Bundle contents will be extracted into `/tmp/simple-app-bundle` directory: + + ```bash-plain + /tmp/simple-app-bundle + ├── .imgpkg + │   ├── bundle.yml + │   └── images.yml + └── config.yml + ``` diff --git a/site/content/imgpkg/docs/v0.41.x/basic-workflow.md b/site/content/imgpkg/docs/v0.41.x/basic-workflow.md new file mode 100644 index 000000000..271cb07e3 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/basic-workflow.md @@ -0,0 +1,150 @@ +--- +aliases: [/imgpkg/docs/latest/basic-workflow] +title: Basic Workflow +--- + +## Scenario + +You want to create an immutable artifact containing Kubernetes configuration and images used in that configuration. Later, you want to grab that artifact and deploy it to Kubernetes. + +## 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. + +## Step 1: Creating the bundle + +1. Prepare bundle contents + + The [examples/basic-step-1/](https://github.com/carvel-dev/imgpkg/tree/develop/examples/basic-step-1) directory has a `config.yml` file, which contains a very simple Kubernetes application. Your application may have as many configuration files as necessary in various formats such as plain YAML, ytt templates, Helm templates, etc. + + In our example `config.yml` includes an image reference to `docker.io/dkalinin/k8s-simple-app`. This reference does not point to an exact image (via digest) meaning that it may change over time. To ensure we get precisely the bits we expect, we will lock it down to an exact image next. + +1. Add `.imgpkg/` directory + + [examples/basic-step-2](https://github.com/carvel-dev/imgpkg/tree/develop/examples/basic-step-2) shows what a `.imgpkg/` directory may look like. It contains: + + - **optional** [bundle.yml](resources.md#bundle-metadata): a file which records informational metadata + - **required** [images.yml](resources.md#imageslock): a file which records image references used by the configuration + + ```bash-plain + examples/basic-step-2 + ├── .imgpkg + │   ├── bundle.yml + │   └── images.yml + └── config.yml + ``` + + Note that `.imgpkg/images.yml` contains a list of images, each with fully resolved digest reference (e.g `index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4...`) and a little bit of additional metadata (e.g. `annotations` section). See [ImagesLock configuration](resources.md#imageslock-configuration) for details. + + ```yaml + apiVersion: imgpkg.carvel.dev/v1alpha1 + kind: ImagesLock + images: + - image: index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + annotations: + kbld.carvel.dev/id: docker.io/dkalinin/k8s-simple-app + ``` + + This allows us to record the exact image that will be used by our Kubernetes configuration. We expect that `.imgpkg/images.yml` would be created either manually, or in an automated way. Our recommendation is to use [kbld](/kbld) to generate `.imgpkg/images.yml`: + + ```bash-plain + $ cd examples/basic-bundle/ + + $ kbld -f config.yml --imgpkg-lock-output .imgpkg/images.yml + ``` + +--- +## Step 2: Pushing the bundle to a registry + +1. [Authenticate with a registry](auth.md) where we will push our bundle + +1. Push the bundle to the registry + + You can push the bundle with our specified contents to an OCI registry using the following command: + + ```bash-plain + $ imgpkg push -b index.docker.io/user1/simple-app-bundle:v1.0.0 -f examples/basic-step-2 + + dir: . + dir: .imgpkg + file: .imgpkg/bundle.yml + file: .imgpkg/images.yml + file: config.yml + Pushed 'index.docker.io/user1/simple-app-bundle@sha256:ec3f870e958e404476b9ec67f28c598fa8f00f819b8ae05ee80d51bac9f35f5d' + + Succeeded + ``` + + Flags used in the command: + * `-b` (`--bundle`) refers to a location for a bundle within an OCI registry + * `-f` (`--file`) indicates directory contents to include + +1. The pushed bundle is now available at `index.docker.io/user1/simple-app-bundle:v1.0.0` + +--- +## Step 3: Pulling the bundle from registry + +Now that we have pushed a bundle to a registry, other users can pull it. + +1. [Authenticate with the registry](auth.md) from which we'll pull our bundle + +1. Download the bundle by running the following command: + + ```bash-plain + $ imgpkg pull -b index.docker.io/user1/simple-app-bundle:v1.0.0 -o /tmp/simple-app-bundle + + Pulling image 'index.docker.io/user1/simple-app-bundle@sha256:ec3f870e958e404476b9ec67f28c598fa8f00f819b8ae05ee80d51bac9f35f5d' + Extracting layer 'sha256:7906b9650be657359ead106e354f2728e16c8f317e1d87f72b05b5c5ec3d89cc' (1/1) + Locating image lock file images... + One or more images not found in bundle repo; skipping lock file update + + Succeeded + ``` + + Flags used in the command: + * `-b` (`--bundle`) refers to a location for a bundle within an OCI registry + * `-o` (`--output`) indicates the destination directory on your local machine where the bundle contents will be placed + + Bundle contents will be extracted into `/tmp/simple-app-bundle` directory: + + ```bash-plain + /tmp/simple-app-bundle + ├── .imgpkg + │   ├── bundle.yml + │   └── images.yml + └── config.yml + ``` + + __Note:__ The message `One or more images not found in bundle repo; skipping lock file update` is expected, and indicates that `/tmp/simple-app-bundle/.imgpkg/images.yml` (ImagesLock configuration) was not modified. + + If imgpkg had been able to find all images that were referenced in the [ImagesLock configuration](resources.md#imageslock-configuration) in the registry where bundle is located, then it would update `.imgpkg/images.yml` file to point to the registry-local locations. + + See what happens to the lock file if you run the same pull command after [copying](air-gapped-workflow.md#option-1-from-a-location-connected-to-both-registries) the bundle to another registry! + +--- +## Step 4: Use pulled bundle contents + +1. Now that we have have pulled bundle contents to a local directory, we can deploy Kubernetes configuration: + + Before we apply Kubernetes configuration, let's use [kbld](/kbld) to ensure that Kubernetes configuration uses exact image reference from `.imgpkg/images.yml`. (You can of course use other tools to take advantage of data stored in `.imgpkg/images.yml`). + + ```bash-plain + $ cd /tmp/simple-app-bundle/ + + $ kbld -f ./config.yml -f .imgpkg/images.yml | kubectl apply -f- + + resolve | final: docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 -> index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + resolve | final: index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 -> index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + + service/simple-app configured + deployment/simple-app configured + ``` + + kbld found `docker.io/dkalinin/k8s-simple-app` in Kubernetes configuration and replaced it with `index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0` before forwarding configuration to kubectl. + +## Next steps + +In this workflow we saw how to publish and download a bundle to distribute a Kubernetes application. Next, follow the [Air-gapped workflow](air-gapped-workflow.md) to see how we can use the `imgpkg copy` command to copy a bundle between registries. 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 new file mode 100644 index 000000000..2f0404248 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/ca-certs-windows.md @@ -0,0 +1,28 @@ +--- +aliases: [/imgpkg/docs/latest/ca-certs-windows] +title: CA Certs on Windows +--- + +## Known issue verifying certificates on Windows + +If you are using imgpkg v0.19.0 or earlier, and use imgpkg with a registry over https, you will likely encounter the following error: +``` +imgpkg: Error: Fetching image: + Get "https://some.registry/v2/": x509: certificate signed by unknown authority +``` + +imgpkg v0.20.0+ supports loading Windows root ca certs. Meaning, that imgpkg is able to verify registry certificates signed by a trusted certificate authority! + +## Known issue providing custom ca certificates on Windows + +imgpkg allows specifying the `--registry-ca-cert-path` flag as a way to add custom ca certificates to use when verifying a registry server certificate. + +However, on Windows, the entire set of ca certificates to use during verify is loaded from the flag (Windows root ca store is skipped in this case). +Meaning that if you are targeting multiple registries, and some are signed with a trusted certificate authority and others signed with a custom ca certificate, +both ca certificates will need to be provided. (via the `--registry-ca-cert-path` flag) + +An example workflow: +1. Build a single ca certificate file (containing multiple ca certificates) from a trusted source. e.g. [extract ca certs provided by Mozilla](https://github.com/curl/curl/blob/4d2f8006777d6354d9b62eae38ebd0a0256d0f94/lib/firefox-db2pem.sh) +1. Provide that single ca certificate file to imgpkg. `--registry-ca-cert-path ./mozilla-ca-certs.pem` +1. Provide any additional custom ca certificates to imgpkg. `--registry-ca-cert-path ./dev-registry.pem` + diff --git a/site/content/imgpkg/docs/v0.41.x/commands.md b/site/content/imgpkg/docs/v0.41.x/commands.md new file mode 100644 index 000000000..36e39e270 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/commands.md @@ -0,0 +1,178 @@ +--- +aliases: [/imgpkg/docs/latest/commands] +title: Commands +--- + +## Push + +### Overview + +`push` command allows users to create a bundle in the registry from files and/or directories on their local file systems. For example, + +```bash-plain +$ imgpkg push -b index.docker.io/k8slt/sample-bundle -f my-bundle/ +``` + +will push a bundle contents containing in the `my-bundle/` directory to `index.docker.io/k8slt/sample-bundle`. + +Use the `-b`/`--bundle` flag to specify the destination of the push. If the specified destination does not include a tag, the artifact will be pushed with the default tag `:latest`. + +The `-f` flag can be used multiple times to add different files or directories to the bundle. + +Use the flag `--preserve-permissions=true` to preserve the current permission of the files of the image or bundle being pushed. If this flag is not present `imgpkg` will remove the Group and All permissions before uploading the image, when pull is done `imgpkg` will try to copy the User permissions to Group and All, respecting umask + +### Generating a BundleLock + +`push` command can output a [`BundleLock` configuration](resources.md#bundlelock-configuration) for users that would like a deterministic reference to a pushed bundle. For example, running: + +```bash-plain +$ impgpkg push -b index.docker.io/k8slt/sample-bundle:v0.1.0 -f my-bundle/ --lock-output +/tmp/bundle.lock.yml +``` + +will create `/tmp/bundle.lock.yml` with BundleLock configuration. If another bundle image in the repository is later given the same tag (`v0.1.0`), the BundleLock configuration will continue to provide immutable reference (via digest) to the original pushed bundle. + +--- +## Pull + +### Overview + +After pushing bundles to a registry, users can retrieve them with `imgpkg pull`. For example, + +```bash-plain +$ imgpkg pull -b index.docker.io/k8slt/sample-bundle -o my-bundle/ +``` + +will pull a bundle from `index.docker.io/k8slt/sample-bundle` and extract its contents into the `my-bundle/` directory, which gets created if it does not already exist. + +When pulling a bundle, imgpkg ensures that the referenced images are updated to account for any relocations. It will search for each referenced image by digest in the same repository as the bundle. If all referenced digests are found, imgpkg will update image references in the bundle's [`.imgpkg/images.yml` file](resources.md#imgpkg-directory). If any of the digests are not found in the repository, imgpkg will not update any references. + +### Pulling via lock file + +[BundleLock configuration](resources.md#bundlelock-configuration) can be used as input to the pull command via the `--lock` flag. + +```bash-plain +$ imgpkg pull --lock bundle.lock.yml -o my-bundle/ +``` + +### Pulling nested bundles + +If pulling a bundle that references another bundle (via it's ImagesLock file), in order to *also* pull down the contents of every nested bundle, use the `--recursive` flag. + +```bash-plain +$ imgpkg pull --recursive -b bundle-with-nested-bundles +``` + +Contents of *every* nested bundle are written to the 'parent' bundle's `.imgpkg/bundles` directory, namespaced by the bundle's sha256. + +For e.g. pulling a bundle with a nested bundle having sha of `123` would result in: +``` +parent-bundle-path/.imgpkg/bundles/sha256-123/ +``` + +--- +## Copy + +### Overview + +The `copy` command copies a bundle from a registry to another registry (as long as both registries are accessible from where the command is running): + +```bash-plain +$ imgpkg copy -b index.docker.io/k8slt/sample-bundle --to-repo registry.corp.com/user2/sample-bundle-name +``` + +Alternatively `copy` can copy a bundle between registries which are not both accessible from a single location, by creating an intermediate tarball: + +```bash-plain +$ imgpkg copy -b index.docker.io/k8slt/sample-bundle --to-tar=/Volumes/secure-thumb/bundle.tar +# ... take thumb driver to a different location ... +$ imgpkg copy --tar=/Volumes/secure-thumb/bundle.tar --to-repo registry.corp.com/user2/sample-bundle-name +``` + +In either case, the bundle image and all dependent images are copied to the destination location `registry.corp.com/user2/sample-bundle-name`. + +**Note:** To generate tags that provide information on the origin of the images use the flag `--repo-based-tags` + + +### Resume copy of image or bundle to tar + +If the copy to tar was interrupted by a network problem it can be resumed by providing the flag `--resume` to the `copy` command + +```bash-plain +$ imgpkg copy -b index.docker.io/k8slt/sample-bundle --to-tar=/Volumes/secure-thumb/bundle.tar --resume +``` + +### Copying via lock file + +[BundleLock configuration](resources.md#bundlelock-configuration) can be used as input to the copy command via the `--lock` flag. + +```bash-plain +$ imgpkg copy --lock bundle.lock.yml --to-repo registry.corp.com/user2/sample-bundle-name --lock-output /tmp/new-bundle.lock.yml +``` + +### Non-Distributable or Foreign Layers + +Some images contain layers which should not be uploaded when copying, such as a proprietary base image. +Instead, to comply with license requirements, it is expected to get them directly from the source registry. +These layers are interchangeably known as +[Non-Distributable](https://github.com/opencontainers/image-spec/blob/79b036d80240ae530a8de15e1d21c7ab9292c693/layer.md#non-distributable-layers) +(by the OCI) or +[Foreign](https://docs.docker.com/registry/spec/manifest-v2-2/) (by Docker) and denoted in the layer's MediaType. + +By default, imgpkg will not relocate any layers marked as non-distributable. + +This can cause issues when dealing with [air-gapped environments](air-gapped-workflow.md) as they may be unable to reach the external registries. +To allow this use case, imgpkg supports the `--include-non-distributable-layers` flag to copy all layers, even those marked as non-distributable. + +Note that usage of this flag shall not preclude your obligation to comply with the terms of the image license(s). + +### Image Signatures + +`imgpkg` can copy Signature created by [cosign](https://github.com/sigstore/cosign). By +default `imgpkg` will not search for Signatures for Images. To enable the search and copy of the signatures the +flag `--cosign-signatures` needs to be provided to copy command + +```bash-plain +$ imgpkg copy -b index.docker.io/k8slt/sample-bundle --to-repo some.repo.io/some-bundle --cosign-signatures +``` + +This feature will work while copying to a different repository as well as copying to a tarball. + +--- + +## Tag + +`imgpkg tag` supports a `list` subcommand that allows users to list the image tags pushed to registries. The command features an `--image`/`-i` option that allows a user to specify an image name. + +An example of this is shown below: + +```bash-plain +$ imgpkg tag list -i index.docker.io/k8slt/image +``` + +The output shows the names of all non-imgpkg internal tags associated with the image. + +Additionally, you can request to see the tag digests or all tags, to include the imgpkg internally generated tags, using the following flags. + +```bash-plain +$ imgpkg tag list --digests -i index.docker.io/k8slt/image +$ imgpkg tag list --imgpkg-internal-tags -i index.docker.io/k8slt/image +``` + +--- + +## Describe + +`imgpkg describe` Provides a summary of all the images that are part of the provided Bundle. + +An example of this is shown below: + +```bash-plain +$ imgpkg describe -b carvel.dev/app1-bundle +``` + +This command provides 2 different types of output, `yaml` and `text`, that can be selected via the flag `--output-type`. +By default `text` is selected. + +The flag `--cosign-artifacts` provides the user the ability to select if they want or not `imgpkg` to check and display +any [cosign](https://github.com/sigstore/cosign) artifact that is part of the Bundle. diff --git a/site/content/imgpkg/docs/v0.41.x/debugging.md b/site/content/imgpkg/docs/v0.41.x/debugging.md new file mode 100644 index 000000000..9000ae487 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/debugging.md @@ -0,0 +1,46 @@ +--- +aliases: [/imgpkg/docs/latest/debugging] +title: Debugging +--- + +## Debugging + +In the process of communicating with remote OCI registries, it is possible that an error will occur. In order to help debug an error situation, use the `--debug` command line argument. Specifying this argument will output detailed logs of all communications between `imgpkg` and the OCI registries. + +> This feature is available in v0.20.0 and later + +As an example, consider this pull command along with the additional information logged. The record of all HTTP communication will be displayed to assist in resolving a problem or error condition. + +```bash-plain +imgpkg pull -b registry.example.com/foo/bar:latest -o temp --debug + +2021/09/21 20:50:12 --> GET https://registry.example.com/v2/ +2021/09/21 20:50:12 GET /v2/ HTTP/1.1 +Host: registry.example.com +User-Agent: Go-http-client/1.1 +Accept-Encoding: gzip + +2021/09/21 20:50:12 <-- 401 https://registry.example.com/v2/ (207.596107ms) +2021/09/21 20:50:12 HTTP/1.1 401 Unauthorized +Content-Length: 76 +Connection: keep-alive +Content-Type: application/json; charset=utf-8 +Date: Wed, 22 Sep 2021 02:50:12 GMT +Docker-Distribution-Api-Version: registry/2.0 +Set-Cookie: sid=f9752c01ce47ab50791d4a845a78d996; Path=/; HttpOnly; Secure +Strict-Transport-Security: max-age=31536000; includeSubDomains +Www-Authenticate: Bearer realm="https://registry.example.com/service/token",service="harbor-registry" +X-Request-Id: 2fe97b25-ca40-4012-9105-bbf8284995b6 + +{"errors":[{"code":"UNAUTHORIZED","message":"unauthorized: unauthorized"}]} + +2021/09/21 20:50:12 --> GET https://registry.example.com/service/token?scope=repository%3Afoo%2Fbar%3Apull&service=harbor-registry [body redacted: basic token response contains credentials] +2021/09/21 20:50:12 GET /service/token?scope=repository%3Afoo%2Fbar%3Apull&service=harbor-registry HTTP/1.1 +Host: registry.example.com +User-Agent: go-containerregistry/v0.6.0 +Authorization: +Accept-Encoding: gzip +... +``` + +> Note that sensitive information, such as basic authentication parameters and Authorization strings, are not displayed. diff --git a/site/content/imgpkg/docs/v0.41.x/faq-generic.md b/site/content/imgpkg/docs/v0.41.x/faq-generic.md new file mode 100644 index 000000000..879d4bd09 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/faq-generic.md @@ -0,0 +1,30 @@ +--- +aliases: [/imgpkg/docs/latest/faq-generic] +title: FAQ +--- + +## Using `registry:2` and non-distributable layer + +**We do not recommend the usage of `registry:2` in production** + +There is a known issue when using `registry:2` image as the registry and using it as the destination of a Bundle or +Image that contains non-distributable layers. + +The problem is surfaced with an error similar to + +```shell +imgpkg copy \ + -b my.registry.io/some-bundle:0.0.1 \ + --to-repo localhost:5000/some-bundle +imgpkg: Error: PUT http://localhost:5000/v2/some-bundle/manifests/sha256-6195153fbf1af788bb68124fe2e0b016a1d0b6d3d8ca16cc6d23823d8a7b5445.imgpkg: multiple errors returned: + UNKNOWN: unknown error; UNKNOWN: unknown error; map[]; MANIFEST_BLOB_UNKNOWN: blob unknown to registry; sha256:3a78847ea829208edc2d7b320b7e602b9d12e47689499d5180a9cc7790dec4d7 +``` + +This error happens because the `registry:2` registry does a validation on non-distributable layers and checks the URL +against the provided allowed list, which is empty so it fails. + +For local development this validation can be turned off. To do so start the registry using the following command + +```shell +docker run --env REGISTRY_VALIDATION_DISABLED=true -d -p 5000:5000 --restart always --name registry registry:2 +``` diff --git a/site/content/imgpkg/docs/v0.41.x/install.md b/site/content/imgpkg/docs/v0.41.x/install.md new file mode 100644 index 000000000..d74978ec7 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/install.md @@ -0,0 +1,58 @@ +--- +aliases: [/imgpkg/docs/latest/install] +title: Install +--- + +## Via script (macOS or Linux) + +(Note that `install.sh` script installs other Carvel tools as well.) + +Install binaries into specific directory: + +```bash +$ mkdir local-bin/ +$ curl -L https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR=local-bin bash + +$ export PATH=$PWD/local-bin/:$PATH +$ imgpkg version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ imgpkg version +``` + +## Via Homebrew (macOS or Linux) + +Based on [github.com/carvel-dev/homebrew](https://github.com/carvel-dev/homebrew). + +```bash +$ brew tap carvel-dev/carvel +$ brew install imgpkg +$ imgpkg version +``` + +## Specific version from a GitHub release + +To download, click on one of the assets in a [chosen GitHub release](https://github.com/carvel-dev/imgpkg/releases), for example for 'imgpkg-darwin-amd64'. + +```bash +# **Compare binary checksum** against what's specified in the release notes +# (if checksums do not match, binary was not successfully downloaded) +$ shasum -a 256 ~/Downloads/imgpkg-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/imgpkg-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/imgpkg-darwin-amd64 /usr/local/bin/imgpkg + +# Make binary executable +$ chmod +x /usr/local/bin/imgpkg + +# Check its version +$ imgpkg version +``` diff --git a/site/content/imgpkg/docs/v0.41.x/proxy.md b/site/content/imgpkg/docs/v0.41.x/proxy.md new file mode 100644 index 000000000..0998e7dc2 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/proxy.md @@ -0,0 +1,33 @@ +--- +aliases: [/imgpkg/docs/latest/proxy] +title: Proxy +--- + +## Using Proxy + +When using `imgpkg` to connect with a registry via a proxy you will need to provide one of following environment variables + +- `HTTP_PROXY` or `http_proxy` when using the flag `--registry-insecure` +- `HTTPS_PROXY` or `https_proxy` when the communication with the registry need to be using TLS + +### No TLS example + +Assuming the proxy to access the registry is located in `http://proxy.company.com` + +When executing `imgpkg` do the following: +```bash +export http_proxy=http://proxy.company.com + +imgpkg pull -b registry.company.com/my-image@sha256:265d4a5ed8bf0df27d1107edb00b70e658ee9aa5acb3f37336c5a17db634481e -o folder --registry-insecure +``` + +### TLS example + +Assuming the proxy to access the registry is located in `https://proxy.company.com` + +When executing `imgpkg` do the following: +```bash +export https_proxy=https://proxy.company.com + +imgpkg pull -b registry.company.com/my-image@sha256:265d4a5ed8bf0df27d1107edb00b70e658ee9aa5acb3f37336c5a17db634481e -o folder +``` diff --git a/site/content/imgpkg/docs/v0.41.x/resources.md b/site/content/imgpkg/docs/v0.41.x/resources.md new file mode 100644 index 000000000..6a0300834 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/resources.md @@ -0,0 +1,145 @@ +--- +aliases: [/imgpkg/docs/latest/resources] +title: Resources +--- + +## Image + +An OCI image is an artifact that lives within an OCI registry (such as DockerHub). It can contain an arbitrary number of files. + +--- +## Bundle + +A bundle is an OCI image that holds 0+ arbitrary files _and_ 0+ references to dependent OCI images (which *may* also be [bundles](#nested-bundle)). By tracking dependent images, imgpkg can copy bundles across registries. + +Referenced images are stored within the [`.imgpkg` directory](#imgpkg-directory) at the root level of the bundle image. + +![Bundle diagram](/images/imgpkg/bundle-diagram.png) + +Implementation note: A bundle OCI image has the `dev.carvel.imgpkg.bundle` [label](https://docs.docker.com/config/labels-custom-metadata/) set. + +--- +## `.imgpkg` directory + +`.imgpkg` directory contains metadata files describing bundle: + +- `images.yml` (required) contains [ImagesLock configuration](#imageslock-configuration) that describes 0+ dependent OCI images. Consumers of bundles can rely on this file being always present. + +- `bundle.yml` (optional) file contains [Bundle configuration](#bundle-configuration) that contains details about bundle authors, associated websites, etc. + +Restrictions for location of `.imgpkg` directory: + +- Only one `.imgpkg` directory is allowed across all directories provided via `-f` to the `push` command. This restriction ensures there is a single source of bundle metadata and referenced images. + +- The `.imgpkg` directory must be a direct child of one of the input directories. This prevents any confusion around the scope of the `.imgpkg` metadata. + +--- +## Bundle configuration + +Used by bundle creators to store general information about the bundle. Stored in `.imgpkg/bundle.yml`. + +Example: + +```yaml +apiVersion: imgpkg.carvel.dev/v1alpha1 +kind: Bundle +metadata: + name: my-bundle +authors: +- name: Full Name + email: name@example.com +websites: +- url: example.com +``` + +- `authors` (array of structs; optional) + - `name` (string) Author name + - `email` (string) Author email +- `websites` (array of structs; optional) + - `url` (string) Related website URL + +--- +## ImagesLock configuration + +An ImagesLock configuration is used to track a collection of image references. + +Bundle's `.imgpkg/images.yml` contains ImagesLock configuration. That's how bundle knows which OCI images it references. When copying a bundle `imgpkg` uses this configuration to know which images to copy. + +It can be conveniently generated with [kbld](/kbld): + +```bash-plain +$ kbld -f config.yml --imgpkg-lock-output .imgpkg/images.yml +``` + +Example: + +```yaml +apiVersion: imgpkg.carvel.dev/v1alpha1 +kind: ImagesLock +images: +- image: docker.io/user1/my-app@sha256:42462d0cb227497976754bb67348bdd7471c7bd159819d6bd63fdf479eb7eb19 + annotations: + kbld.carvel.dev/id: "my-app:v1" +- image: gcr.io/projectX/controller@sha256:6ecba6f14373a449f8d54fa4286f57fb8ef37c4ffa637969551f2fda52672206 +``` + +- `images` (array of images): 0+ images + - `image` (string; required) digest reference to OCI image (tag references are not allowed) + - `annotations` (map[string]string; optional) arbitrary additional data about image reference. Expected to be used by tools that create or read ImagesLock configuration. Example: [kbld](/kbld) uses annotations to store an identifier that can later tell it which location(s) within a Kubernetes configuration to update with the digest reference. + +Advanced non-bundle use: See [copying via lock files](commands.md#copying-via-lock-file). + +--- +## BundleLock configuration + +Stores a digest reference to a bundle (as well as the tag it was pushed with). + +This configuration is generated by the `--lock-output` flag during a `push` command. + +```yaml +$ imgpkg push -b ... --lock-output /tmp/lock.yml + +$ cat /tmp/lock.yml + +apiVersion: imgpkg.carvel.dev/v1alpha1 +kind: BundleLock +bundle: + image: docker.io/my-app@sha256:b12026c7a0a6a1756a82a2a74ac759e9a7036523faca0e33dbddebc214e097df + tag: v1.0 +``` + +--- +## Nested Bundle + +A nested bundle is a bundle referenced from a 'parent' bundle in its `ImagesLock` configuration. + +Having a bundle 'reference' another bundle is no different from referencing any other OCI image. The copy and pull commands work the same as dealing with any OCI image. + +![Nested Bundle diagram](/images/imgpkg/nested-bundle-diagram.png) + +One key difference between nested bundles and other OCI images, is the directory structure when `imgpkg pull` writes the nested bundle's content to disk. + +Bundles can be nested repeatedly without limits on depth or breadth. +Imgpkg optimizes both network requests and storage on the destination, so we +would not expect any issues short of hard storage limits at the destination +repository. + +For further details refer to [pulling a nested bundle.](commands.md#pulling-nested-bundles) + +--- +## Locations OCI Image + +`imgpkg` when copying Bundles and Images now creates a new OCI Images that will act as a Cache that contain information +about the Images that were copied and if these Images are a Bundle or not. This OCI Image will contain a single layer +with a single file `image-locations.yml` at the root of the image. This is the file structure + +```yaml +apiVersion: imgpkg.carvel.dev/v1alpha1 +kind: ImageLocations +images: +- image: some.image.io/test@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + isBundle: true +``` + +The OCI Image will be pushed into the same repository as the Bundle and will have the tag +`sha256-{Bundle SHA}.image-locations.imgpkg` diff --git a/site/content/imgpkg/docs/v0.41.x/security.md b/site/content/imgpkg/docs/v0.41.x/security.md new file mode 100644 index 000000000..ca69db28d --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/imgpkg/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `imgpkg`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). 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 new file mode 100644 index 000000000..cdac04918 --- /dev/null +++ b/site/content/imgpkg/docs/v0.41.x/working-directly-with-images.md @@ -0,0 +1,8 @@ +--- +aliases: [/imgpkg/docs/latest/working-directly-with-images] +title: Working directly with images +--- + +In rare cases imgpkg's [bundle](resources.md#bundle) concept is not wanted (or necessary). imgpkg provides a `--image` flag for push, pull and copy commands. When the `--image` flag is used, there is no need for a `.imgpkg` directory to store metadata. + +For most use cases, we suggest using the bundle concept and `--bundle` flag. diff --git a/site/data/imgpkg/docs/imgpkg-v0-41-x-toc.yml b/site/data/imgpkg/docs/imgpkg-v0-41-x-toc.yml new file mode 100644 index 000000000..a04ec6eeb --- /dev/null +++ b/site/data/imgpkg/docs/imgpkg-v0-41-x-toc.yml @@ -0,0 +1,43 @@ +toc: + - title: Introduction + subfolderitems: + - page: About imgpkg + url: / + - page: Install + url: /install + - title: Workflows + subfolderitems: + - page: Basic workflow + url: /basic-workflow + - page: Air-gapped workflow + url: /air-gapped-workflow + - page: Automation workflow + url: /automation-workflow + - title: Reference + subfolderitems: + - page: Authentication + url: /auth + - page: Resources + url: /resources + - page: Commands + url: /commands + - page: Working directly with images + url: /working-directly-with-images + - page: Proxy + url: /proxy + - title: FAQ + subfolderitems: + - page: General + url: /faq-generic + - page: Code of Conduct + shared_url: /code-of-conduct + - page: Contributing + shared_url: /contributing + - page: Carvel Development Guidelines + shared_url: /development_guidelines + - page: Security + shared_url: /security-policy + - page: CA Certs on Windows + url: /ca-certs-windows + - page: Debugging + url: /debugging diff --git a/site/data/imgpkg/docs/toc-mapping.yml b/site/data/imgpkg/docs/toc-mapping.yml index d3ee25d5c..e201693e6 100644 --- a/site/data/imgpkg/docs/toc-mapping.yml +++ b/site/data/imgpkg/docs/toc-mapping.yml @@ -16,3 +16,4 @@ v0.37.x: imgpkg-v0-37-x-toc v0.38.x: imgpkg-v0-38-x-toc v0.39.x: imgpkg-v0-39-x-toc v0.40.x: imgpkg-v0-40-x-toc +v0.41.x: imgpkg-v0-41-x-toc