From 2251f27e6845d489b869dbb7fb0fafaf8b2bc831 Mon Sep 17 00:00:00 2001 From: Yash Sethiya Date: Wed, 31 Jan 2024 21:06:43 +0530 Subject: [PATCH] Added OSS docs for carvel tools minor versions (#707) Signed-off-by: sethiyash --- site/config.yaml | 19 +- site/content/imgpkg/docs/v0.38.x/_index.md | 2 +- .../docs/v0.38.x/air-gapped-workflow.md | 2 +- site/content/imgpkg/docs/v0.38.x/auth.md | 2 +- .../docs/v0.38.x/automation-workflow.md | 2 +- .../imgpkg/docs/v0.38.x/basic-workflow.md | 2 +- .../imgpkg/docs/v0.38.x/ca-certs-windows.md | 2 +- site/content/imgpkg/docs/v0.38.x/commands.md | 2 +- site/content/imgpkg/docs/v0.38.x/debugging.md | 2 +- .../imgpkg/docs/v0.38.x/faq-generic.md | 2 +- site/content/imgpkg/docs/v0.38.x/install.md | 2 +- site/content/imgpkg/docs/v0.38.x/proxy.md | 2 +- site/content/imgpkg/docs/v0.38.x/resources.md | 2 +- site/content/imgpkg/docs/v0.38.x/security.md | 2 +- .../v0.38.x/working-directly-with-images.md | 2 +- site/content/imgpkg/docs/v0.39.x/_index.md | 21 + .../docs/v0.39.x/air-gapped-workflow.md | 154 +++++ site/content/imgpkg/docs/v0.39.x/auth.md | 166 ++++++ .../docs/v0.39.x/automation-workflow.md | 141 +++++ .../imgpkg/docs/v0.39.x/basic-workflow.md | 150 +++++ .../imgpkg/docs/v0.39.x/ca-certs-windows.md | 28 + site/content/imgpkg/docs/v0.39.x/commands.md | 178 ++++++ site/content/imgpkg/docs/v0.39.x/debugging.md | 46 ++ .../imgpkg/docs/v0.39.x/faq-generic.md | 30 + site/content/imgpkg/docs/v0.39.x/install.md | 58 ++ site/content/imgpkg/docs/v0.39.x/proxy.md | 33 ++ site/content/imgpkg/docs/v0.39.x/resources.md | 145 +++++ site/content/imgpkg/docs/v0.39.x/security.md | 8 + .../v0.39.x/working-directly-with-images.md | 8 + .../kapp-controller/docs/v0.48.x/_index.md | 2 +- .../docs/v0.48.x/air-gapped-workflow.md | 2 +- .../docs/v0.48.x/app-examples.md | 2 +- .../docs/v0.48.x/app-overview.md | 2 +- .../kapp-controller/docs/v0.48.x/app-spec.md | 2 +- .../docs/v0.48.x/authoring-command.md | 2 +- .../docs/v0.48.x/controller-config.md | 2 +- .../docs/v0.48.x/debugging-crs.md | 2 +- .../docs/v0.48.x/debugging-kc.md | 2 +- .../kapp-controller/docs/v0.48.x/dev.md | 2 +- .../kapp-controller/docs/v0.48.x/faq.md | 2 +- .../kapp-controller/docs/v0.48.x/install.md | 2 +- .../kapp-controller/docs/v0.48.x/kctrl-faq.md | 4 +- .../docs/v0.48.x/kctrl-package-authoring.md | 4 +- .../docs/v0.48.x/kctrl-package-tutorial.md | 2 +- .../docs/v0.48.x/management-command.md | 2 +- .../docs/v0.48.x/oss-packages.md | 2 +- .../docs/v0.48.x/package-consumer-concepts.md | 2 +- .../v0.48.x/package-install-extensions.md | 2 +- .../v0.48.x/packaging-artifact-formats.md | 2 +- .../docs/v0.48.x/packaging-gitops.md | 2 +- .../docs/v0.48.x/packaging-tutorial.md | 2 +- .../kapp-controller/docs/v0.48.x/packaging.md | 2 +- .../docs/v0.48.x/private-registry-auth.md | 2 +- .../docs/v0.48.x/security-model.md | 2 +- .../kapp-controller/docs/v0.48.x/security.md | 2 +- .../kapp-controller/docs/v0.48.x/sops.md | 2 +- .../kapp-controller/docs/v0.48.x/startup.md | 2 +- .../docs/v0.48.x/walkthrough.md | 2 +- .../kapp-controller/docs/v0.49.x/_index.md | 38 ++ .../docs/v0.49.x/air-gapped-workflow.md | 92 +++ .../docs/v0.49.x/app-examples.md | 108 ++++ .../docs/v0.49.x/app-overview.md | 73 +++ .../kapp-controller/docs/v0.49.x/app-spec.md | 434 ++++++++++++++ .../docs/v0.49.x/authoring-command.md | 69 +++ .../docs/v0.49.x/controller-config.md | 118 ++++ .../docs/v0.49.x/debugging-crs.md | 126 ++++ .../docs/v0.49.x/debugging-kc.md | 13 + .../kapp-controller/docs/v0.49.x/dev.md | 24 + .../kapp-controller/docs/v0.49.x/faq.md | 97 +++ .../kapp-controller/docs/v0.49.x/install.md | 143 +++++ .../kapp-controller/docs/v0.49.x/kctrl-faq.md | 122 ++++ .../docs/v0.49.x/kctrl-package-authoring.md | 556 ++++++++++++++++++ .../docs/v0.49.x/kctrl-package-tutorial.md | 458 +++++++++++++++ .../docs/v0.49.x/management-command.md | 304 ++++++++++ .../docs/v0.49.x/oss-packages.md | 24 + .../docs/v0.49.x/package-consumer-concepts.md | 171 ++++++ .../v0.49.x/package-install-extensions.md | 65 ++ .../v0.49.x/packaging-artifact-formats.md | 66 +++ .../docs/v0.49.x/packaging-gitops.md | 250 ++++++++ .../docs/v0.49.x/packaging-tutorial.md | 478 +++++++++++++++ .../kapp-controller/docs/v0.49.x/packaging.md | 504 ++++++++++++++++ .../docs/v0.49.x/private-registry-auth.md | 217 +++++++ .../docs/v0.49.x/security-model.md | 67 +++ .../kapp-controller/docs/v0.49.x/security.md | 8 + .../kapp-controller/docs/v0.49.x/sops.md | 146 +++++ .../kapp-controller/docs/v0.49.x/startup.md | 31 + .../docs/v0.49.x/walkthrough.md | 214 +++++++ site/content/vendir/docs/v0.35.x/_index.md | 2 +- .../vendir/docs/v0.35.x/github-release.md | 2 +- site/content/vendir/docs/v0.35.x/install.md | 2 +- site/content/vendir/docs/v0.35.x/security.md | 2 +- site/content/vendir/docs/v0.35.x/sync.md | 2 +- .../vendir/docs/v0.35.x/vendir-lock-spec.md | 2 +- .../vendir/docs/v0.35.x/vendir-spec.md | 2 +- site/content/vendir/docs/v0.35.x/versions.md | 2 +- site/content/vendir/docs/v0.36.x/_index.md | 25 + .../vendir/docs/v0.36.x/github-release.md | 17 + site/content/vendir/docs/v0.36.x/install.md | 58 ++ site/content/vendir/docs/v0.36.x/security.md | 8 + site/content/vendir/docs/v0.36.x/sync.md | 76 +++ .../vendir/docs/v0.36.x/vendir-lock-spec.md | 69 +++ .../vendir/docs/v0.36.x/vendir-spec.md | 266 +++++++++ site/content/vendir/docs/v0.36.x/versions.md | 112 ++++ site/content/vendir/docs/v0.37.x/_index.md | 25 + .../vendir/docs/v0.37.x/github-release.md | 17 + site/content/vendir/docs/v0.37.x/install.md | 58 ++ site/content/vendir/docs/v0.37.x/security.md | 8 + site/content/vendir/docs/v0.37.x/sync.md | 76 +++ .../vendir/docs/v0.37.x/vendir-lock-spec.md | 69 +++ .../vendir/docs/v0.37.x/vendir-spec.md | 266 +++++++++ site/content/vendir/docs/v0.37.x/versions.md | 112 ++++ site/content/vendir/docs/v0.38.x/_index.md | 25 + .../vendir/docs/v0.38.x/github-release.md | 17 + site/content/vendir/docs/v0.38.x/install.md | 58 ++ site/content/vendir/docs/v0.38.x/security.md | 8 + site/content/vendir/docs/v0.38.x/sync.md | 76 +++ .../vendir/docs/v0.38.x/vendir-lock-spec.md | 69 +++ .../vendir/docs/v0.38.x/vendir-spec.md | 266 +++++++++ site/content/vendir/docs/v0.38.x/versions.md | 112 ++++ site/data/imgpkg/docs/imgpkg-v0-39-x-toc.yml | 43 ++ site/data/imgpkg/docs/toc-mapping.yml | 1 + .../docs/kapp-controller-v0-49-x-toc.yml | 75 +++ .../data/kapp-controller/docs/toc-mapping.yml | 1 + site/data/vendir/docs/toc-mapping.yml | 3 + site/data/vendir/docs/vendir-v0-36-x-toc.yml | 29 + site/data/vendir/docs/vendir-v0-37-x-toc.yml | 29 + site/data/vendir/docs/vendir-v0-38-x-toc.yml | 29 + 127 files changed, 8350 insertions(+), 60 deletions(-) create mode 100644 site/content/imgpkg/docs/v0.39.x/_index.md create mode 100644 site/content/imgpkg/docs/v0.39.x/air-gapped-workflow.md create mode 100644 site/content/imgpkg/docs/v0.39.x/auth.md create mode 100644 site/content/imgpkg/docs/v0.39.x/automation-workflow.md create mode 100644 site/content/imgpkg/docs/v0.39.x/basic-workflow.md create mode 100644 site/content/imgpkg/docs/v0.39.x/ca-certs-windows.md create mode 100644 site/content/imgpkg/docs/v0.39.x/commands.md create mode 100644 site/content/imgpkg/docs/v0.39.x/debugging.md create mode 100644 site/content/imgpkg/docs/v0.39.x/faq-generic.md create mode 100644 site/content/imgpkg/docs/v0.39.x/install.md create mode 100644 site/content/imgpkg/docs/v0.39.x/proxy.md create mode 100644 site/content/imgpkg/docs/v0.39.x/resources.md create mode 100644 site/content/imgpkg/docs/v0.39.x/security.md create mode 100644 site/content/imgpkg/docs/v0.39.x/working-directly-with-images.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/_index.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/air-gapped-workflow.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/app-examples.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/app-overview.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/app-spec.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/authoring-command.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/controller-config.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/debugging-crs.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/debugging-kc.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/dev.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/faq.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/install.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/kctrl-faq.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/kctrl-package-authoring.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/kctrl-package-tutorial.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/management-command.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/oss-packages.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/package-consumer-concepts.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/package-install-extensions.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/packaging-artifact-formats.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/packaging-gitops.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/packaging-tutorial.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/packaging.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/private-registry-auth.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/security-model.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/security.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/sops.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/startup.md create mode 100644 site/content/kapp-controller/docs/v0.49.x/walkthrough.md create mode 100644 site/content/vendir/docs/v0.36.x/_index.md create mode 100644 site/content/vendir/docs/v0.36.x/github-release.md create mode 100644 site/content/vendir/docs/v0.36.x/install.md create mode 100644 site/content/vendir/docs/v0.36.x/security.md create mode 100644 site/content/vendir/docs/v0.36.x/sync.md create mode 100644 site/content/vendir/docs/v0.36.x/vendir-lock-spec.md create mode 100644 site/content/vendir/docs/v0.36.x/vendir-spec.md create mode 100644 site/content/vendir/docs/v0.36.x/versions.md create mode 100644 site/content/vendir/docs/v0.37.x/_index.md create mode 100644 site/content/vendir/docs/v0.37.x/github-release.md create mode 100644 site/content/vendir/docs/v0.37.x/install.md create mode 100644 site/content/vendir/docs/v0.37.x/security.md create mode 100644 site/content/vendir/docs/v0.37.x/sync.md create mode 100644 site/content/vendir/docs/v0.37.x/vendir-lock-spec.md create mode 100644 site/content/vendir/docs/v0.37.x/vendir-spec.md create mode 100644 site/content/vendir/docs/v0.37.x/versions.md create mode 100644 site/content/vendir/docs/v0.38.x/_index.md create mode 100644 site/content/vendir/docs/v0.38.x/github-release.md create mode 100644 site/content/vendir/docs/v0.38.x/install.md create mode 100644 site/content/vendir/docs/v0.38.x/security.md create mode 100644 site/content/vendir/docs/v0.38.x/sync.md create mode 100644 site/content/vendir/docs/v0.38.x/vendir-lock-spec.md create mode 100644 site/content/vendir/docs/v0.38.x/vendir-spec.md create mode 100644 site/content/vendir/docs/v0.38.x/versions.md create mode 100644 site/data/imgpkg/docs/imgpkg-v0-39-x-toc.yml create mode 100644 site/data/kapp-controller/docs/kapp-controller-v0-49-x-toc.yml create mode 100644 site/data/vendir/docs/vendir-v0-36-x-toc.yml create mode 100644 site/data/vendir/docs/vendir-v0-37-x-toc.yml create mode 100644 site/data/vendir/docs/vendir-v0-38-x-toc.yml diff --git a/site/config.yaml b/site/config.yaml index 03d332ac3..221576735 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -94,15 +94,16 @@ params: name: imgpkg short_name: imgpkg root_link: /imgpkg/ - latest_docs_link: /imgpkg/docs/v0.38.x/ + latest_docs_link: /imgpkg/docs/v0.39.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.38.x + version_latest: v0.39.x versions: - develop + - v0.39.x - v0.38.x - v0.37.x - v0.36.x @@ -122,15 +123,16 @@ params: name: kapp-controller short_name: kc root_link: /kapp-controller/ - latest_docs_link: /kapp-controller/docs/v0.48.x/ + latest_docs_link: /kapp-controller/docs/v0.49.x/ github_url: https://github.com/carvel-dev/kapp-controller search: true search_index_name: carvel-kapp-controller search_api_key: a38560864c2e9128ae57d5734df438ff versioning: true - version_latest: v0.48.x + version_latest: v0.49.x versions: - develop + - v0.49.x - v0.48.x - v0.47.x - v0.46.0 @@ -176,15 +178,18 @@ params: name: vendir short_name: vendir root_link: /vendir/ - latest_docs_link: /vendir/docs/v0.35.x/ + latest_docs_link: /vendir/docs/v0.38.x/ github_url: https://github.com/carvel-dev/vendir search: true search_index_name: carvel-vendir search_api_key: a38560864c2e9128ae57d5734df438ff versioning: true - version_latest: v0.35.x + version_latest: v0.38.x versions: - develop + - v0.38.x + - v0.37.x + - v0.36.x - v0.35.x - v0.34.x - v0.33.x @@ -218,4 +223,4 @@ permalinks: minify: tdewolff: html: - keepQuotes: true \ No newline at end of file + keepQuotes: true diff --git a/site/content/imgpkg/docs/v0.38.x/_index.md b/site/content/imgpkg/docs/v0.38.x/_index.md index e2b1fd77f..642aa78c6 100644 --- a/site/content/imgpkg/docs/v0.38.x/_index.md +++ b/site/content/imgpkg/docs/v0.38.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.38.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.38.x/air-gapped-workflow.md index a3d589126..146fff0b7 100644 --- a/site/content/imgpkg/docs/v0.38.x/air-gapped-workflow.md +++ b/site/content/imgpkg/docs/v0.38.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.38.x/auth.md b/site/content/imgpkg/docs/v0.38.x/auth.md index df015c0a0..f4a10756b 100644 --- a/site/content/imgpkg/docs/v0.38.x/auth.md +++ b/site/content/imgpkg/docs/v0.38.x/auth.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/auth] + title: Authentication --- diff --git a/site/content/imgpkg/docs/v0.38.x/automation-workflow.md b/site/content/imgpkg/docs/v0.38.x/automation-workflow.md index 0e131150c..1fb36d327 100644 --- a/site/content/imgpkg/docs/v0.38.x/automation-workflow.md +++ b/site/content/imgpkg/docs/v0.38.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.38.x/basic-workflow.md b/site/content/imgpkg/docs/v0.38.x/basic-workflow.md index 271cb07e3..dab6abf3a 100644 --- a/site/content/imgpkg/docs/v0.38.x/basic-workflow.md +++ b/site/content/imgpkg/docs/v0.38.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.38.x/ca-certs-windows.md b/site/content/imgpkg/docs/v0.38.x/ca-certs-windows.md index 2f0404248..950141a4e 100644 --- a/site/content/imgpkg/docs/v0.38.x/ca-certs-windows.md +++ b/site/content/imgpkg/docs/v0.38.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.38.x/commands.md b/site/content/imgpkg/docs/v0.38.x/commands.md index 36e39e270..de4129e8a 100644 --- a/site/content/imgpkg/docs/v0.38.x/commands.md +++ b/site/content/imgpkg/docs/v0.38.x/commands.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/commands] + title: Commands --- diff --git a/site/content/imgpkg/docs/v0.38.x/debugging.md b/site/content/imgpkg/docs/v0.38.x/debugging.md index 9000ae487..e669f95e8 100644 --- a/site/content/imgpkg/docs/v0.38.x/debugging.md +++ b/site/content/imgpkg/docs/v0.38.x/debugging.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/debugging] + title: Debugging --- diff --git a/site/content/imgpkg/docs/v0.38.x/faq-generic.md b/site/content/imgpkg/docs/v0.38.x/faq-generic.md index 879d4bd09..5ff292950 100644 --- a/site/content/imgpkg/docs/v0.38.x/faq-generic.md +++ b/site/content/imgpkg/docs/v0.38.x/faq-generic.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/faq-generic] + title: FAQ --- diff --git a/site/content/imgpkg/docs/v0.38.x/install.md b/site/content/imgpkg/docs/v0.38.x/install.md index d74978ec7..0ba30f7a4 100644 --- a/site/content/imgpkg/docs/v0.38.x/install.md +++ b/site/content/imgpkg/docs/v0.38.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/install] + title: Install --- diff --git a/site/content/imgpkg/docs/v0.38.x/proxy.md b/site/content/imgpkg/docs/v0.38.x/proxy.md index 0998e7dc2..cc509f507 100644 --- a/site/content/imgpkg/docs/v0.38.x/proxy.md +++ b/site/content/imgpkg/docs/v0.38.x/proxy.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/proxy] + title: Proxy --- diff --git a/site/content/imgpkg/docs/v0.38.x/resources.md b/site/content/imgpkg/docs/v0.38.x/resources.md index 6a0300834..7ae340dca 100644 --- a/site/content/imgpkg/docs/v0.38.x/resources.md +++ b/site/content/imgpkg/docs/v0.38.x/resources.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/resources] + title: Resources --- diff --git a/site/content/imgpkg/docs/v0.38.x/security.md b/site/content/imgpkg/docs/v0.38.x/security.md index ca69db28d..c70b75d5e 100644 --- a/site/content/imgpkg/docs/v0.38.x/security.md +++ b/site/content/imgpkg/docs/v0.38.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/imgpkg/docs/latest/security] + title: Security --- diff --git a/site/content/imgpkg/docs/v0.38.x/working-directly-with-images.md b/site/content/imgpkg/docs/v0.38.x/working-directly-with-images.md index cdac04918..21dc3ac34 100644 --- a/site/content/imgpkg/docs/v0.38.x/working-directly-with-images.md +++ b/site/content/imgpkg/docs/v0.38.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.39.x/_index.md b/site/content/imgpkg/docs/v0.39.x/_index.md new file mode 100644 index 000000000..7e96e44a7 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.x/_index.md @@ -0,0 +1,21 @@ +--- +aliases: [/imgpkg/docs/latest/] +title: "About imgpkg" +toc: "false" +cascade: + version: v0.39.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.39.x/air-gapped-workflow.md b/site/content/imgpkg/docs/v0.39.x/air-gapped-workflow.md new file mode 100644 index 000000000..a3d589126 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/auth.md b/site/content/imgpkg/docs/v0.39.x/auth.md new file mode 100644 index 000000000..df015c0a0 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/automation-workflow.md b/site/content/imgpkg/docs/v0.39.x/automation-workflow.md new file mode 100644 index 000000000..0e131150c --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/basic-workflow.md b/site/content/imgpkg/docs/v0.39.x/basic-workflow.md new file mode 100644 index 000000000..271cb07e3 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/ca-certs-windows.md b/site/content/imgpkg/docs/v0.39.x/ca-certs-windows.md new file mode 100644 index 000000000..2f0404248 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/commands.md b/site/content/imgpkg/docs/v0.39.x/commands.md new file mode 100644 index 000000000..36e39e270 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/debugging.md b/site/content/imgpkg/docs/v0.39.x/debugging.md new file mode 100644 index 000000000..9000ae487 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/faq-generic.md b/site/content/imgpkg/docs/v0.39.x/faq-generic.md new file mode 100644 index 000000000..879d4bd09 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/install.md b/site/content/imgpkg/docs/v0.39.x/install.md new file mode 100644 index 000000000..d74978ec7 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/proxy.md b/site/content/imgpkg/docs/v0.39.x/proxy.md new file mode 100644 index 000000000..0998e7dc2 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/resources.md b/site/content/imgpkg/docs/v0.39.x/resources.md new file mode 100644 index 000000000..6a0300834 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/security.md b/site/content/imgpkg/docs/v0.39.x/security.md new file mode 100644 index 000000000..ca69db28d --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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.39.x/working-directly-with-images.md b/site/content/imgpkg/docs/v0.39.x/working-directly-with-images.md new file mode 100644 index 000000000..cdac04918 --- /dev/null +++ b/site/content/imgpkg/docs/v0.39.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/content/kapp-controller/docs/v0.48.x/_index.md b/site/content/kapp-controller/docs/v0.48.x/_index.md index db9104f7f..ce0bce470 100644 --- a/site/content/kapp-controller/docs/v0.48.x/_index.md +++ b/site/content/kapp-controller/docs/v0.48.x/_index.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/] + title: "About kapp-controller" toc: "false" cascade: diff --git a/site/content/kapp-controller/docs/v0.48.x/air-gapped-workflow.md b/site/content/kapp-controller/docs/v0.48.x/air-gapped-workflow.md index 8e993fe3c..01429cae2 100644 --- a/site/content/kapp-controller/docs/v0.48.x/air-gapped-workflow.md +++ b/site/content/kapp-controller/docs/v0.48.x/air-gapped-workflow.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/air-gapped-workflow] + title: Install Packages in an air-gapped (offline) environment --- diff --git a/site/content/kapp-controller/docs/v0.48.x/app-examples.md b/site/content/kapp-controller/docs/v0.48.x/app-examples.md index 256f92f66..9ec1418f3 100644 --- a/site/content/kapp-controller/docs/v0.48.x/app-examples.md +++ b/site/content/kapp-controller/docs/v0.48.x/app-examples.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/app-examples] + title: Example Usage --- diff --git a/site/content/kapp-controller/docs/v0.48.x/app-overview.md b/site/content/kapp-controller/docs/v0.48.x/app-overview.md index f02dc191b..51b80d179 100644 --- a/site/content/kapp-controller/docs/v0.48.x/app-overview.md +++ b/site/content/kapp-controller/docs/v0.48.x/app-overview.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/app-overview] + title: App CR High Level Overview --- diff --git a/site/content/kapp-controller/docs/v0.48.x/app-spec.md b/site/content/kapp-controller/docs/v0.48.x/app-spec.md index 52bd69c9d..206a53bad 100644 --- a/site/content/kapp-controller/docs/v0.48.x/app-spec.md +++ b/site/content/kapp-controller/docs/v0.48.x/app-spec.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/app-spec] + title: App CR spec --- diff --git a/site/content/kapp-controller/docs/v0.48.x/authoring-command.md b/site/content/kapp-controller/docs/v0.48.x/authoring-command.md index 3af8661ba..856706fd8 100644 --- a/site/content/kapp-controller/docs/v0.48.x/authoring-command.md +++ b/site/content/kapp-controller/docs/v0.48.x/authoring-command.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/authoring-command] + title: Authoring Commands Reference --- diff --git a/site/content/kapp-controller/docs/v0.48.x/controller-config.md b/site/content/kapp-controller/docs/v0.48.x/controller-config.md index e504bfb17..71df619ac 100644 --- a/site/content/kapp-controller/docs/v0.48.x/controller-config.md +++ b/site/content/kapp-controller/docs/v0.48.x/controller-config.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/controller-config] + title: Configuring the Controller --- diff --git a/site/content/kapp-controller/docs/v0.48.x/debugging-crs.md b/site/content/kapp-controller/docs/v0.48.x/debugging-crs.md index 8f9a0957d..5630d1d8b 100644 --- a/site/content/kapp-controller/docs/v0.48.x/debugging-crs.md +++ b/site/content/kapp-controller/docs/v0.48.x/debugging-crs.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/debugging-crs] + title: Debugging CRs --- diff --git a/site/content/kapp-controller/docs/v0.48.x/debugging-kc.md b/site/content/kapp-controller/docs/v0.48.x/debugging-kc.md index e6d3a4cf6..60e8751e6 100644 --- a/site/content/kapp-controller/docs/v0.48.x/debugging-kc.md +++ b/site/content/kapp-controller/docs/v0.48.x/debugging-kc.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/debugging-kc] + title: Debugging kapp-controller --- diff --git a/site/content/kapp-controller/docs/v0.48.x/dev.md b/site/content/kapp-controller/docs/v0.48.x/dev.md index 7eed6c3cf..90623a017 100644 --- a/site/content/kapp-controller/docs/v0.48.x/dev.md +++ b/site/content/kapp-controller/docs/v0.48.x/dev.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/dev] + title: Development & Deploy --- diff --git a/site/content/kapp-controller/docs/v0.48.x/faq.md b/site/content/kapp-controller/docs/v0.48.x/faq.md index 8fdb25351..47fbbfe3e 100644 --- a/site/content/kapp-controller/docs/v0.48.x/faq.md +++ b/site/content/kapp-controller/docs/v0.48.x/faq.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/faq] + title: FAQ --- diff --git a/site/content/kapp-controller/docs/v0.48.x/install.md b/site/content/kapp-controller/docs/v0.48.x/install.md index 955da7841..82fbcb115 100644 --- a/site/content/kapp-controller/docs/v0.48.x/install.md +++ b/site/content/kapp-controller/docs/v0.48.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/install] + title: Install --- diff --git a/site/content/kapp-controller/docs/v0.48.x/kctrl-faq.md b/site/content/kapp-controller/docs/v0.48.x/kctrl-faq.md index cba8e80a6..525bf42dc 100644 --- a/site/content/kapp-controller/docs/v0.48.x/kctrl-faq.md +++ b/site/content/kapp-controller/docs/v0.48.x/kctrl-faq.md @@ -1,6 +1,6 @@ --- -aliases: [/kapp-controller/docs/latest/kctrl-faq] -aliases: [/kapp-controller/docs/latest/kctrl-faq] + + title: "`kctrl` FAQ" --- diff --git a/site/content/kapp-controller/docs/v0.48.x/kctrl-package-authoring.md b/site/content/kapp-controller/docs/v0.48.x/kctrl-package-authoring.md index 34103c0f8..47e99efe4 100644 --- a/site/content/kapp-controller/docs/v0.48.x/kctrl-package-authoring.md +++ b/site/content/kapp-controller/docs/v0.48.x/kctrl-package-authoring.md @@ -1,6 +1,6 @@ --- -aliases: [/kapp-controller/docs/latest/kctrl-package-authoring] -aliases: [/kapp-controller/docs/latest/kctrl-package-authoring] + + title: Authoring packages with kctrl --- diff --git a/site/content/kapp-controller/docs/v0.48.x/kctrl-package-tutorial.md b/site/content/kapp-controller/docs/v0.48.x/kctrl-package-tutorial.md index 436ab4190..afe33e0aa 100644 --- a/site/content/kapp-controller/docs/v0.48.x/kctrl-package-tutorial.md +++ b/site/content/kapp-controller/docs/v0.48.x/kctrl-package-tutorial.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/kctrl-package-tutorial] + title: Consuming Packages using the CLI --- diff --git a/site/content/kapp-controller/docs/v0.48.x/management-command.md b/site/content/kapp-controller/docs/v0.48.x/management-command.md index 823fae7f2..f97b76859 100644 --- a/site/content/kapp-controller/docs/v0.48.x/management-command.md +++ b/site/content/kapp-controller/docs/v0.48.x/management-command.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/management-command] + title: Management Commands Reference --- diff --git a/site/content/kapp-controller/docs/v0.48.x/oss-packages.md b/site/content/kapp-controller/docs/v0.48.x/oss-packages.md index 1e323714f..011d10a33 100644 --- a/site/content/kapp-controller/docs/v0.48.x/oss-packages.md +++ b/site/content/kapp-controller/docs/v0.48.x/oss-packages.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/oss-packages] + title: OSS Carvel Packages --- diff --git a/site/content/kapp-controller/docs/v0.48.x/package-consumer-concepts.md b/site/content/kapp-controller/docs/v0.48.x/package-consumer-concepts.md index f87fc1e12..2fe9197a4 100644 --- a/site/content/kapp-controller/docs/v0.48.x/package-consumer-concepts.md +++ b/site/content/kapp-controller/docs/v0.48.x/package-consumer-concepts.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/package-consumer-concepts] + title: Concepts for Package Consumers --- diff --git a/site/content/kapp-controller/docs/v0.48.x/package-install-extensions.md b/site/content/kapp-controller/docs/v0.48.x/package-install-extensions.md index 56d7cf833..48c2ff050 100644 --- a/site/content/kapp-controller/docs/v0.48.x/package-install-extensions.md +++ b/site/content/kapp-controller/docs/v0.48.x/package-install-extensions.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/package-install-extensions] + title: Overlays with PackageInstall --- diff --git a/site/content/kapp-controller/docs/v0.48.x/packaging-artifact-formats.md b/site/content/kapp-controller/docs/v0.48.x/packaging-artifact-formats.md index f7bc5003b..21e03299b 100644 --- a/site/content/kapp-controller/docs/v0.48.x/packaging-artifact-formats.md +++ b/site/content/kapp-controller/docs/v0.48.x/packaging-artifact-formats.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/packaging-artifact-formats] + title: Artifact formats --- diff --git a/site/content/kapp-controller/docs/v0.48.x/packaging-gitops.md b/site/content/kapp-controller/docs/v0.48.x/packaging-gitops.md index 538c3f97c..2ebd2a281 100644 --- a/site/content/kapp-controller/docs/v0.48.x/packaging-gitops.md +++ b/site/content/kapp-controller/docs/v0.48.x/packaging-gitops.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/packaging-gitops] + title: Package Management with GitOps --- diff --git a/site/content/kapp-controller/docs/v0.48.x/packaging-tutorial.md b/site/content/kapp-controller/docs/v0.48.x/packaging-tutorial.md index 816423c65..256e44f9b 100644 --- a/site/content/kapp-controller/docs/v0.48.x/packaging-tutorial.md +++ b/site/content/kapp-controller/docs/v0.48.x/packaging-tutorial.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/packaging-tutorial] + title: "Tutorial: Create and Install a Package" --- diff --git a/site/content/kapp-controller/docs/v0.48.x/packaging.md b/site/content/kapp-controller/docs/v0.48.x/packaging.md index 129f053b0..62a723655 100644 --- a/site/content/kapp-controller/docs/v0.48.x/packaging.md +++ b/site/content/kapp-controller/docs/v0.48.x/packaging.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/packaging] + title: Package Management --- diff --git a/site/content/kapp-controller/docs/v0.48.x/private-registry-auth.md b/site/content/kapp-controller/docs/v0.48.x/private-registry-auth.md index 78ca30c7e..d936d90ad 100644 --- a/site/content/kapp-controller/docs/v0.48.x/private-registry-auth.md +++ b/site/content/kapp-controller/docs/v0.48.x/private-registry-auth.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/private-registry-auth] + title: Authenticating to Private Registries --- diff --git a/site/content/kapp-controller/docs/v0.48.x/security-model.md b/site/content/kapp-controller/docs/v0.48.x/security-model.md index 0c168c4d7..5655a710a 100644 --- a/site/content/kapp-controller/docs/v0.48.x/security-model.md +++ b/site/content/kapp-controller/docs/v0.48.x/security-model.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/security-model] + title: Security Model --- diff --git a/site/content/kapp-controller/docs/v0.48.x/security.md b/site/content/kapp-controller/docs/v0.48.x/security.md index 4a7b0542c..8a06a0f80 100644 --- a/site/content/kapp-controller/docs/v0.48.x/security.md +++ b/site/content/kapp-controller/docs/v0.48.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/security] + title: Security --- diff --git a/site/content/kapp-controller/docs/v0.48.x/sops.md b/site/content/kapp-controller/docs/v0.48.x/sops.md index 275dca2b6..3cf650392 100644 --- a/site/content/kapp-controller/docs/v0.48.x/sops.md +++ b/site/content/kapp-controller/docs/v0.48.x/sops.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/sops] + title: Sops --- diff --git a/site/content/kapp-controller/docs/v0.48.x/startup.md b/site/content/kapp-controller/docs/v0.48.x/startup.md index a6e0492e9..08d73b54c 100644 --- a/site/content/kapp-controller/docs/v0.48.x/startup.md +++ b/site/content/kapp-controller/docs/v0.48.x/startup.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/startup] + Title: Kapp Controller Startup --- diff --git a/site/content/kapp-controller/docs/v0.48.x/walkthrough.md b/site/content/kapp-controller/docs/v0.48.x/walkthrough.md index bf189fd68..89ed9091f 100644 --- a/site/content/kapp-controller/docs/v0.48.x/walkthrough.md +++ b/site/content/kapp-controller/docs/v0.48.x/walkthrough.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp-controller/docs/latest/walkthrough] + title: Install an Application --- diff --git a/site/content/kapp-controller/docs/v0.49.x/_index.md b/site/content/kapp-controller/docs/v0.49.x/_index.md new file mode 100644 index 000000000..098c9f3d8 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/_index.md @@ -0,0 +1,38 @@ +--- +aliases: [/kapp-controller/docs/latest/] +title: "About kapp-controller" +toc: "false" +cascade: + version: v0.49.x + toc: "true" + type: docs + layout: docs +--- + +kapp-controller provides declarative APIs to customize, install, and update your Kubernetes applications and packages. It is a part of the Carvel toolkit and follows core Carvel design principles. Get started with the [tutorial](packaging-tutorial.md)! + +The kapp-controller CLI `kctrl` ("k-control") helps users to observe and interact custom resources surfaced by kapp-controller effectively. It also allows package consumers get up and running with Carvel packages faster. + +#### Choice for authors; consistency for consumers +Kubernetes configuration takes many forms -- plain YAML configurations, Helm charts, ytt templates, jsonnet templates, etc. +Software running on Kubernetes lives in many different places: a Git repository, an archive over HTTP, a Helm repository, etc. + +kapp-controller provides software authors flexibility to choose their own configuration tools, while providing software consumers with consistent declarative APIs to customize, install, and update software on Kubernetes from various sources. + +#### Lightweight and composable +kapp-controller breaks down the installation of applications and packages into three easy to understand steps: +- Fetch: get configuration and OCI images from various sources including a Git repository, a local ConfigMap, a Helm chart, an OCI registry, etc. +- Template: take user provided values to customize software using ytt templates, helm templates, and more +- Deploy: create/update resources on the cluster + +#### GitOps and Continuous Delivery +With its layered approach, kapp-controller can be used as: +- Continuous delivery for Kubernetes applications using [App CR](app-spec.md) +- Kubernetes Package Management using [Package CR and supplementary CRs](packaging.md) +- Managing applications and packages using GitOps + +#### Share software and build distributions +Use kapp-controller's Package Management features along with Carvel's imgpkg bundles to distribute Package Repositories that can be added to cluster to provide a catalog of software for users to install. Package Repositries can be automatically updated ensuring users always have access to latest versions of software. Package Repositories and Packages can also be relocated and run in air-gapped environments. + +#### Reliable and ready for production! +kapp-controller has been hardened and is in use on production Kubernetes clusters. Learn more through [case studies](/blog/casestudy-modernizing-the-us-army) on our blog. diff --git a/site/content/kapp-controller/docs/v0.49.x/air-gapped-workflow.md b/site/content/kapp-controller/docs/v0.49.x/air-gapped-workflow.md new file mode 100644 index 000000000..8e993fe3c --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/air-gapped-workflow.md @@ -0,0 +1,92 @@ +--- +aliases: [/kapp-controller/docs/latest/air-gapped-workflow] +title: Install Packages in an air-gapped (offline) environment +--- + +The documentation below covers topics from the [imgpkg air-gapped workflow docs](/imgpkg/docs/latest/air-gapped-workflow) +more concisely in order to focus on applying these workflows to kapp-controller package repositories. + +## Scenario + +You have a [PackageRepository](packaging#packagerepository-cr) in an [imgpkg bundle format](/imgpkg/docs/latest/resources/#bundle) +in an external OCI registry that you would like to move into an OCI registry in an air-gapped environment. Once relocated, you would +like to deploy the bundle as part of a PackageRepository to a Kubernetes cluster. + +## Prerequisites + +In order to go through this process of moving an imgpkg bundle to an air-gapped environment, you will need to have [imgpkg](/imgpkg) +installed. More information on installing Carvel tools, including `imgpkg`, can be found [here](/#whole-suite). + +## Copy PackageRepository bundle to new location + +Most of the steps documented for the [imgpkg air-gapped workflow docs](/imgpkg/docs/latest/air-gapped-workflow#step-1-finding-bundle-in-source-registry) +still apply in the case of working with kapp-controller package repositories. A summary of these docs is that you will need to copy your package repository +bundle with `imgpkg` via one of the following options: + +- **Option 1:** From a common location connected to both registries. This option is more efficient because only changed image layers will be transferred between registries. +- **Option 2:** With intermediate tarball. This option works best when registries have no common network access. + +More detailed documents for [Option 1](/imgpkg/docs/latest/air-gapped-workflow/#option-1-from-a-location-connected-to-both-registries) and +[Option 2](/imgpkg/docs/latest/air-gapped-workflow/#option-2-with-intermediate-tarball) can be found at the attached links. + +A summary of steps for relocating a package repository bundle to an air-gapped environment are documented for both options below: + +For **Option 1**: + +1. Navigate to a location that can access both registries. If there is no such location, you have to use **Option 2** steps. +1. [Authenticate](/imgpkg/docs/latest/auth.md) with both source and destination registries. +1. Copy PackageRepository bundle to the new location by running: + + ``` + imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-repo final-registry.corp.com/apps/simple-app-bundle + ``` + +For **Option 2**: + +1. Navigate to a location that can access the source registry. +1. [Authenticate](/imgpkg/docs/latest/auth.md) with the source registry. +1. Compress PackageRepository bundle into a tarball file by running: + + ``` + imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-tar /tmp/my-image.tar + ``` + + **Note:** Make sure the tar file is in a location that has access to the destination registry. + +1. [Authenticate](/imgpkg/docs/latest/auth.md) with the destination registry. + +1. Copy the tarball file to the new location by running: + + ``` + imgpkg copy --tar /tmp/my-image.tar --to-repo final-registry.corp.com/apps/simple-app-bundle + ``` + +## Use Relocated Bundle or Image with PackageRepository + +Once you have relocated the package repository bundle into the destination OCI registry in your air-gapped environment, you can +now reference the relocated bundle in a PackageRepository definition: + +```yaml +--- +apiVersion: install.package.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + name: simple-package-repository +spec: + fetch: + imgpkgBundle: + image: final-registry.corp.com/apps/simple-app-bundle +``` + +In the event your PackageRepository needs authentication to pull the bundle, you can read more about kapp-controller's +[private authentication workflows using secretgen-controller](private-registry-auth.md) or [without secretgen-controller](private-registry-auth.md#packagerepository-authentication-without-secretgen-controller). + +After applying the PackageRepository definition above to your Kubernetes cluster, you will be able to check that the PackageRepository and +its associated Packages were successfully deployed by checking the PackageRepository status: + +```bash +$ kubectl get packagerepository/simple-package-repository +``` + +You will see a message of `Reconcile Succeeded` in the `DESCRIPTION` column of the output from `kubectl` if the PackageRepository was deloyed +successfully. You can also run `kubectl get packages` to see that all Packages were introduced successfully. diff --git a/site/content/kapp-controller/docs/v0.49.x/app-examples.md b/site/content/kapp-controller/docs/v0.49.x/app-examples.md new file mode 100644 index 000000000..256f92f66 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/app-examples.md @@ -0,0 +1,108 @@ +--- +aliases: [/kapp-controller/docs/latest/app-examples] +title: Example Usage +--- + +Below are some example App CRs showing common ways our users have used App CRs. Full App CR spec can be found [here](app-spec.md). + +## Gitops with an app +In this example a user wants to keep their app up to date with changes to the source Git repo + +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: simple-app +spec: + serviceAccountName: default + fetch: + - git: + url: https://github.com/k14s/k8s-simple-app-example + ref: origin/develop + subPath: config-step-2-template + + template: + - ytt: {} + + deploy: + - kapp: {} +``` + +## Gitops with a Helm chart +In this example a user wants to keep their cluster up to date with the latest version of a Helm chart fetched from a Git repo +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: nginx-helm +spec: + fetch: + - git: + url: https://github.com/bitnami/charts + ref: origin/master + subPath: bitnami/nginx + + template: + - helmTemplate: + valuesFrom: + - secretRef: + name: nginx-values + + deploy: + - kapp: {} +``` + +## Install a Helm chart +In this example a user wants to keep their cluster up to date with the latest version of a Helm chart +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: concourse-helm +spec: + fetch: + - helmChart: + name: stable/concourse + + template: + - helmTemplate: + valuesFrom: + - secretRef: + name: concourse-values + + deploy: + - kapp: {} +``` + +## Customize a Helm chart by adding an overlay +In this example a user wants to use `helm template`, but then modify the resulting YAML by adding their own add their own `ytt overlay` +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: concourse-helm +spec: + fetch: + - git: + url: https://github.com/bitnami/charts + ref: origin/master + subPath: bitnami/nginx + + template: + - helmTemplate: {} + - ytt: + ignoreUnknownComments: true + inline: + paths: + remove-lb.yml: | + #@ load("@ytt:overlay", "overlay") + #@overlay/match by=overlay.subset({"kind":"Service","metadata":{"name":"nginx"}}) + --- + spec: + type: ClusterIP + #@overlay/remove + externalTrafficPolicy: + + deploy: + - kapp: {} +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/app-overview.md b/site/content/kapp-controller/docs/v0.49.x/app-overview.md new file mode 100644 index 000000000..f02dc191b --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/app-overview.md @@ -0,0 +1,73 @@ +--- +aliases: [/kapp-controller/docs/latest/app-overview] +title: App CR High Level Overview +--- + +## Overview +kapp-controller provides a declarative way to install, manage, and upgrade applications on a Kubernetes cluster using the App CRD. Get started by installing the [latest release of kapp-controller](install.md). + +## App +An App is a set of Kubernetes resources. These resources could span any number of namespaces or could be cluster-wide (e.g. CRDs). An App is represented in kapp-controller using a App CR. + +The App CR comprises of three main sections: +- spec.fetch -- declare source for fetching configuration and OCI images +- spec.template -- declare templating tool and values +- spec.deploy -- declare deployment tool and any deploy specific configuration + +Full App CR spec can be found [here](app-spec.md). + +### spec.fetch + +App CR supports multiple source for fetching configuration and OCI images to give developers flexibility. + +- `inline`: specify one or more files within resource +- `imgpkgBundle`: download [imgpkg bundle](/imgpkg/docs/latest/resources/#bundle) from registry (available in v0.17.0+) +- `image`: download Docker image from registry +- `http`: download file at URL +- `git`: clone Git repository +- `helmChart`: fetch Helm chart from Helm repository + +For each fetch source, App CR supports specifying Secret resources that will be used for authenticating with the source. kapp-controller does not check for `type` value of Secret resource. + +#### `image` and `imgpkgBundle` authentication + +Allowed secret keys: + +- `username` and `password` +- `token`: Alternative to username/password authentication + +Also supports [dockerconfigjson secret type](https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets) (v0.19.0+) + + +#### `git` authentication + +Allowed secret keys: + +- `ssh-privatekey`: PEM-encoded key that will be provided to SSH +- `ssh-knownhosts`: Optional, set of known hosts allowed to connect (if not specified, all hosts are allowed) +- `username` and `password`: Alternative to private key authentication + +#### `http` and `helmChart` authentication + +Allowed secret keys: + +- `username` and `password` + + +### spec.template + +App CR supports multiple templating, overlaying, and data transformation tools to give developers flexibility. + +- `helmTemplate`: uses `helm template` command to render chart +- `ytt`: uses [ytt](/ytt) to render templates +- `kbld`: uses [kbld](/kbld) to resolve image URLs to include digests +- `kustomize`: (not implemented yet) uses kustomize to render configuration +- `jsonnnet`: (not implemented yet) renders jsonnet files +- `sops`: uses [sops](https://github.com/mozilla/sops) to decrypt secrets. [More details](sops.md). Available in v0.11.0+. + +--- +### spec.deploy + +App CR uses Carvel's `kapp` CLI to deploy. + +- `kapp`: uses [kapp](/kapp) to deploy resources diff --git a/site/content/kapp-controller/docs/v0.49.x/app-spec.md b/site/content/kapp-controller/docs/v0.49.x/app-spec.md new file mode 100644 index 000000000..52bd69c9d --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/app-spec.md @@ -0,0 +1,434 @@ +--- +aliases: [/kapp-controller/docs/latest/app-spec] +title: App CR spec +--- + +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App + +metadata: + name: simple-app + # namespace is going to be used as a default namespace during kapp deploy + namespace: ns + +spec: + # pauses _future_ reconcilation; does _not_ affect + # currently running reconciliation (optional; default=false) + paused: true + + # cancels current and future reconciliations (optional; default=false) + canceled: true + + # Deletion requests for the App will result in the App CR being + # deleted, but its associated resources will not be deleted + # (optional; default=false; v0.18.0+) + noopDelete: true + + # specifies that app should be deployed authenticated via + # given service account, found in this namespace (optional; v0.6.0+) + serviceAccountName: sa-name + + # specifies the length of time to wait, in time + unit + # format, before reconciling. Always >= 30s. If value below + # 30s is specified, 30s will be used. (optional; v0.9.0+; default=30s) + syncPeriod: 1m + + # Specifies the default namespace to install the App resources, by default this is + # same as the App's namespace (optional; v0.48.0+) + defaultNamespace: "" + + # specifies that app should be deployed to destination cluster; + # by default, cluster is same as where this resource resides (optional; v0.5.0+) + cluster: + # specifies namespace in destination cluster (optional) + namespace: ns2 + # specifies secret containing kubeconfig (required) + kubeconfigSecretRef: + # specifies secret name within app's namespace (required) + name: cluster1 + # specifies key that contains kubeconfig (optional) + key: value + + # Fetch must have one or more directives + fetch: + # pull content from within this resource; or other resources in the cluster + - inline: + # specifies mapping of paths to their content; + # not recommended for sensitive values as CR is not encrypted (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps; + # data values are recommended to be placed in secrets (optional) + pathsFrom: + - secretRef: + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # pulls content from Docker/OCI registry + - image: + # Docker image url; unqualified, tagged, or + # digest references supported (required) + url: host.com/username/image:v0.1.0 + # secret with auth details (optional) + secretRef: + name: secret-name + # grab only portion of image (optional) + subPath: inside-dir/dir2 + # specifies a strategy to choose a tag (optional; v0.24.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (required) + constraints: ">1.0.0 <3.0.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # pulls imgpkg bundle from Docker/OCI registry (v0.17.0+) + - imgpkgBundle: + # Docker image url; unqualified, tagged, or + # digest references supported (required) + image: host.com/username/image:v0.1.0 + # secret with auth details (optional) + secretRef: + name: secret-name + # specifies a strategy to choose a tag (optional; v0.24.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see https://carvel.dev/vendir/docs/latest/versions/ for details) (required) + constraints: ">1.0.0 <3.0.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # uses http library to fetch file + - http: + # http and https url are supported; + # plain file, tgz and tar types are supported (required) + url: https://host.com/archive.tgz + # checksum to verify after download (optional) + sha256: 0a12cdef83... + # secret to provide auth details (optional) + secretRef: + name: secret-name + # grab only portion of download (optional) + subPath: inside-dir/dir2 + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # uses git to clone repository + - git: + # http or ssh urls are supported (required) + url: https://github.com/k14s/k8s-simple-app-example + # branch, tag, commit; origin is the name of the remote (required) + ref: origin/develop + # secret with auth details. allowed keys: ssh-privatekey, ssh-knownhosts, username, password (optional) + # (if ssh-knownhosts is not specified, git will not perform strict host checking) + secretRef: + name: secret-name + # grab only portion of repository (optional) + subPath: config-step-2-template + # skip lfs download (optional) + lfsSkipSmudge: true + # specifies a strategy to resolve to an explicit ref (optional; v0.24.0+) + refSelection: + semver: + # list of semver constraints (see https://carvel.dev/vendir/docs/latest/versions/ for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # uses helm fetch to fetch specified chart + - helmChart: + name: stable/nginx + # (optional) + version: "0.1.0" + # (optional) + repository: + # repository url; + # scheme of oci:// will fetch experimental helm oci chart (v0.19.0+) + # (required) + url: https://... + # (optional) + secretRef: + name: secret-name + # Relative path to place the fetched artifacts + path: dir (optional; v0.33.1+) + + # Template must have one or more directives + template: + # use ytt to template configuration + - ytt: + # ignores comments that ytt doesn't recognize + # (optional; default=false) + ignoreUnknownComments: true + # forces strict mode https://github.com/k14s/ytt/blob/develop/docs/strict.md + # (optional; default=false) + strict: true + # specify additional files, including data values (optional) + inline: + # specifies content inline within resource; + # not recommended for sensitive values as CR is not encrypted (optional) + paths: + # mapping of paths to their content + dir/file.ext: | + file-content + file-content + # specified content via secrets and config maps; + # data values are recommended to be placed in secrets (optional) + pathsFrom: + - secretRef: + # Reference to a Secret. The keys will be used as data value file names, and the values as the content of the corresponding data values file (typically a multiline yaml) + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + # Reference to a ConfigMap. The keys will be used as data value file names, and the values as the content of the corresponding data values file (typically a multiline yaml) + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + # lists paths to provide to ytt explicitly (optional) + paths: + # - must be quoted when included with paths + - "-" + - dir/common + - dir/nested/app + # control metadata about input files passed to ytt (optional; v0.18.0+) + # see https://carvel.dev/ytt/docs/latest/file-marks/ for more details + fileMarks: + - file-content:type=yaml-plain + - dir/common/bom**/*:type=text-plain + - dir/nested/app/file.txt:exclude=true + - dir/common/generated.go.txt:path=gen.go.txt + # provide values via ytt's --data-values-file (optional; v0.19.0-alpha.9) + valuesFrom: + - secretRef: + name: secret-name + - configMapRef: + name: cfgmap-name + - path: values/shared.yml + # downwardAPI allows passing info about App CR as values into templates (v0.39.0+) + - downwardAPI: + items: + # name specifies the key used when the downwardAPI values are rendered. + # nested keys are supported by using a '.'. for e.g. `name: parent.child`. + # keys requiring a '.' can escape using '\\.'. for e.g. `name: key\\.with\\.dots` + - name: namespace + # fieldPath accepts relaxed jsonpath to select metadata fields from the AppCR (name, namespace, uid, labels, annotations) + fieldPath: metadata.namespace + - name: specificAnnotation + fieldPath: metadata.annotations['specificAnnotation'] + - name: anotherAnnotationWithDots + # keys requiring `\\.`` should use "" for the filedPath value + fieldPath: "metadata.annotations['another\\.annotation\\.with\\.dots']" + # query for the version of the cluster + - name: kubeVersion + kubernetesVersion: {} + # query for all group versions (a list of the API groups and versions in the form "group/version") supported on this cluster + - name: apiGroupVersions + kubernetesAPIs: {} + # query for the version of kapp-controller reconciling this App + - name: kappCtrlVersion + kappControllerVersion: {} + + + # use kbld to resolve image references to use digests + - kbld: + # lists paths to use explicitly (optional; v0.13.0+) + # - must be quoted when included with paths + paths: + - .imgpkg/images.yml + - "-" + + # use helm template command to render helm chart + - helmTemplate: + # path to chart (optional; v0.13.0+) + path: some-chart/ + # set name explicitly, default is App CR's name (optional; v0.13.0+) + name: custom-name + # set namespace explicitly, default is App CR's namespace (optional; v0.13.0+) + namespace: custom-ns + # one or more secrets, config maps, paths, downwardAPI that provide values (optional) + valuesFrom: + - secretRef: + name: secret-name + - configMapRef: + name: cfgmap-name + - path: values/shared.yml + # downwardAPI allows passing info about App CR as values into templates (v0.39.0+) + - downwardAPI: + items: + # name specifies the key used when the downwardAPI values are rendered. + # nested keys are supported by using a '.'. for e.g. `name: parent.child`. + # keys requiring a '.' can escape using '\\.'. for e.g. `name: key\\.with\\.dots` + - name: namespace + # fieldPath accepts relaxed jsonpath to select metadata fields from the AppCR (name, namespace, uid, labels, annotations) + fieldPath: metadata.namespace + - name: specificAnnotation + fieldPath: metadata.annotations['specificAnnotation'] + - name: anotherAnnotationWithDots + # keys requiring `\\.`` should use "" for the filedPath value + fieldPath: "metadata.annotations['another\\.annotation\\.with\\.dots']" + # query for the version of the cluster + - name: kubeVersion + kubernetesVersion: {} + # query for all group versions (a list of the API groups and versions in the form "group/version") supported on this cluster + - name: apiGroupVersions + kubernetesAPIs: {} + # query for the version of kapp-controller reconciling this App + - name: kappCtrlVersion + kappControllerVersion: {} + + # use cue to template configuration + - cue: + inputExpression: "data:" + valuesFrom: + - secretRef: + name: secret-values + # downwardAPI allows passing info about App CR as values into templates (v0.39.0+) + - downwardAPI: + items: + # name specifies the key used when the downwardAPI values are rendered. + # nested keys are supported by using a '.'. for e.g. `name: parent.child`. + # keys requiring a '.' can escape using '\\.'. for e.g. `name: key\\.with\\.dots` + - name: namespace + # fieldPath accepts relaxed jsonpath to select metadata fields from the AppCR (name, namespace, uid, labels, annotations) + fieldPath: metadata.namespace + - name: specificAnnotation + fieldPath: metadata.annotations['specificAnnotation'] + - name: anotherAnnotationWithDots + # keys requiring `\\.`` should use "" for the filedPath value + fieldPath: "metadata.annotations['another\\.annotation\\.with\\.dots']" + # query for the version of the cluster + - name: kubeVersion + kubernetesVersion: {} + # query for all group versions (a list of the API groups and versions in the form "group/version") supported on this cluster + - name: apiGroupVersions + kubernetesAPIs: {} + # query for the version of kapp-controller reconciling this App + - name: kappCtrlVersion + kappControllerVersion: {} + + # use sops to decrypt *.sops.yml files (optional; v0.11.0+) + - sops: + # use PGP to decrypt files (pgp or age is required) + pgp: + # secret with private armored PGP private keys (required) + privateKeysSecretRef: + # (required) + name: pgp-secrets + # use age to decrypt files (v0.28.0+) (pgp or age is required) + age: + # secret with private armored PGP private keys (required) + privateKeysSecretRef: + # (required) + name: age-secrets + # lists paths to decrypt explicitly (optional; v0.13.0+) + paths: + - all-secrets/ + - prod-secrets/prod.sops.yml + + # Deploy must have one directive + deploy: + # use kapp to deploy resources + - kapp: + # override namespace for all resources (optional) + intoNs: another-ns1 + # provide custom namespace override mapping (optional) + mapNs: ["ns1=another-ns1"] + # pass through options to kapp deploy (optional) + rawOptions: ["--apply-concurrency=10"] + # configuration for inspect command (optional) + # as of kapp-controller v0.31.0, inspect is disabled by default + # add rawOptions or use an empty inspect config like `inspect: {}` to enable it + inspect: + # pass through options to kapp inspect (optional) + rawOptions: ["--json=true"] + # configuration for delete command (optional) + delete: + # pass through options to kapp delete (optional) + rawOptions: ["--apply-ignored=true"] + +# status is populated by the controller +status: + # populated based on metadata.generation when controller + # observes a change to the resource; if this value is + # out of data, other status fields do not reflect latest state + observedGeneration: 1 + + conditions: + # "Reconciling" indicates that fetch/template/deploy is happening; + # it does not mean that any resource has changed + - type: Reconciling + status: "True" + # "ReconcileFailed" indicates that one of the stages failed + - type: ReconcileFailed + status: "True" + # "ReconcileSucceeded" indicates that all stages succeeded + - type: ReconcileSucceeded + status: "True" + + fetch: + exitCode: 0 + error: "..." + stderr: "..." + startedAt: "2019-11-07T16:37:23Z" + updatedAt: "2019-11-07T16:37:23Z" + + template: + exitCode: 0 + error: "..." + stderr: "..." + updatedAt: "2019-11-07T16:37:23Z" + + deploy: + exitCode: 0 + error: "..." + stderr: "..." + finished: true + startedAt: "2019-11-07T16:37:23Z" + stdout: |- + Changes + Namespace Name Kind Conds. Age Op Wait to Rs Ri + Op: 0 create, 0 delete, 0 update, 0 noop, 0 exists + Wait to: 0 reconcile, 0 delete, 0 noop + Succeeded + updatedAt: "2019-11-07T16:37:23Z" + + inspect: + exitCode: 0 + error: "..." + stderr: "..." + stdout: |- + Resources in app 'simple-app-ctrl' + Namespace Name Kind Owner Conds. Rs Ri Age + default simple-app Deployment kapp 2/2 t ok - 7d + default L simple-app-6b6b4fcd97 ReplicaSet cluster - ok - 7d + default L.. simple-app-6b6b4fcd97-kwclv Pod cluster 4/4 t ok - 7d + default simple-app Service kapp - ok - 7d + default L simple-app Endpoints cluster - ok - 7d + Rs: Reconcile state + Ri: Reconcile information + 5 resources + Succeeded + updatedAt: "2019-11-07T16:37:23Z" +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/authoring-command.md b/site/content/kapp-controller/docs/v0.49.x/authoring-command.md new file mode 100644 index 000000000..3af8661ba --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/authoring-command.md @@ -0,0 +1,69 @@ +--- +aliases: [/kapp-controller/docs/latest/authoring-command] +title: Authoring Commands Reference +--- + +## Package + +`kctrl` authoring commands help users generate resources that interact with `kapp-controllers` packaging layer. + +### Initialising the package +The `package init` command takes user inputs and creates a boilerplate for package creation. It should be run before using the `package release` or `dev` command. +```bash +$ kctrl package init +``` +Supported flags: +- `--chdir` _string_, Location of the working directory +- `--tty`, _boolean_, Force TTY-like output + +Note: We suggest to run `pkg init` in an interactive flow. + +### Releasing the Package +The `package release` command is used to generate Package and PackageMetadata resources. +```bash +$ kctrl package release -v 1.0.0 --repo-output packages +``` +Supported flags: +- `-v`, `--version` _string_, Version to be released +- `--repo-output` _string_, Output location for artifacts in repository bundle format +- `--copy-to` _string_, Output location for artifacts (default "carvel-artifacts") +- `--chdir` _string_, Location of the working directory +- `--tty`, _boolean_, Force TTY-like output +- `--openapi-schema`, _boolean_, Generates openapi schema for ytt and helm templated files and adds it to generated package +- `--tag` _string_, Tag pushed with imgpkg bundle (default "build-") + +## Package Repository +### Releasing a Package Repository +The `package repository release` command publishes a PackageRepository using the output of `--repo-output` flag from the `package release` command. +```bash +$ kctrl package repository release -v 1.0.0 +``` +Supported flags: +- `-v`, `--version` _string_, Version to be released +- `--copy-to` _string_, Output location for artifacts (default "carvel-artifacts") +- `--chdir` _string_, Location of the working directory +- `--tty`, _boolean_, Force TTY-like output + +## Dev +`kctrl dev` command help in testing the package locally using `kapp-controller`'s APIs. +```bash +$ kctrl dev +``` +Supported flags: +- `--delete` Delete deployed app +- `-f`, `--file strings` Set App CR, Package CR, PackageInstall CR file (required) +- `-b`, `--kbld-build` Allow kbld build +- `-l`, `--local` Use local fetch source +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--tty`, _boolean_, Force TTY-like output + +## Global Flags +- `--debug` _boolean_, Include debug output +- `--color` _boolean_, Set color output (default true) +- `--column` _string_, Filter to show only given columns +- `--json` _boolean_, Output as JSON +- `--kube-api-burst`, _int_, Set Kubernetes API client burst limit (default 1000) +- `--kube-api-qps` _float32_, Set Kubernetes API client QPS limit (default 1000) +- `--kubeconfig` _string_, Path to the kubeconfig file ($KCTRL_KUBECONFIG), +- `--kubeconfig-context`_string_, Kubeconfig context override ($KCTRL_KUBECONFIG_CONTEXT) +- `--kubeconfig-yaml` _string_, Kubeconfig contents as YAML ($KCTRL_KUBECONFIG_YAML) diff --git a/site/content/kapp-controller/docs/v0.49.x/controller-config.md b/site/content/kapp-controller/docs/v0.49.x/controller-config.md new file mode 100644 index 000000000..e504bfb17 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/controller-config.md @@ -0,0 +1,118 @@ +--- +aliases: [/kapp-controller/docs/latest/controller-config] +title: Configuring the Controller +--- + +kapp-controller exposes the ability to configure the controller via a +Secret (available in v0.22.0+) or ConfigMap (available in v0.14.0+), +which kapp controller will look for and apply as part of its [startup processes](startup.md). + +The controller configuration was originally only available in a ConfigMap +format, but as of v0.22.0 it is recommended to use a Secret since there +may be sensitive information stored in the config (e.g. proxy information including passwords). + +In this configuration the user can provide the following: +- Trusted Custom CA Certificates +- Proxy configuration +- List of domains that imgpkg should interact with and should skip TLS verification + +## Controller Configuration Spec + +```yaml +apiVersion: v1 +kind: Secret +metadata: + # Name must be `kapp-controller-config` for kapp controller to pick it up + name: kapp-controller-config + + # Namespace must match the namespace kapp-controller is deployed to + namespace: kapp-controller + +stringData: + # A cert chain of trusted ca certs. These will be added to the system-wide + # cert pool of trusted ca's (optional) + caCerts: | + -----BEGIN CERTIFICATE----- + MIIEXTCCAsWgAwIBAgIQDqAvoGhrmyB/EvhjT/efWzANBgkqhkiG9w0BAQsFADA4 + MQwwCgYDVQQGEwNVU0ExFjAUBgNVBAoTDUNsb3VkIEZvdW5kcnkxEDAOBgNVBAMT + B2Jvc2gtY2EwHhcNMjAxMjIzMTY1OTAxWhcNMjExMjIzMTY1OTAxWjA4MQwwCgYD + VQQGEwNVU0ExFjAUBgNVBAoTDUNsb3VkIEZvdW5kcnkxEDAOBgNVBAMTB2Jvc2gt + Y2EwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCsMTj5yHLez8jzONu1 + tv+u0dqzt8UdWCtUtHCDkIiNJIcB3PkGG7x/LvZ0bMydWeFcBq0g15tfG6N6vHnF + 4p2E9nSe0XjEEnxEkmtdpoFVPZdHTBgc6H5LOMshPH1ARWpuvBnDb87oVinIZBaf + 7BjhUQcRoGtsomk/R9Ke9FB4rMZUfuY/7CC8lDyP5Y02VeTAUimK6/WfDh3VPB3e + vQfXKJY0Ba5s43fIdudV+fcuKDut01oKmiBL6IHLRSrZKta5mg4fgimst6nJ4xvU + SWqYWS4yMxf6pOrTHPjbKUqXqbK4Reh+oQoE12WJZ3NvXr1GoDzt1xzTNzUpUVws + nQm5Fo9H07mkjKeu8gOrOBQ2FqaK+eZ5FFNV7kToVQj2KVTEbLLcTrF454jhsoSd + EOlqVUjtfxGz0dGEuy+IgMvSSjtky7eI08jdBWMiOThQvR3n0Q6TXF/wBwCEfgDa + 4eVeziaUGPXUsefR2+2ZCQ6Z31SmtUGECciCKmKtZTekKCUCAwEAAaNjMGEwDgYD + VR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFDwRpmIKYZvr + lKqROus2Ae6gSKkDMB8GA1UdIwQYMBaAFDwRpmIKYZvrlKqROus2Ae6gSKkDMA0G + CSqGSIb3DQEBCwUAA4IBgQA/LX15Qb7v/og06XB27TPl9StGBiewrb0WdHEz9H16 + eN926TwxWKUr6QcbGg6UbNfLUfMC3VicCDMTQCSNhBTUXm+4pKcJsTyM9/Sk/e4U + 5+l3FTgxXs+3mEoYJy16QlkU1XDr1q6Myo9Kc38d1yUW9OPxBV4Ur3+12uk5ElSC + jZu7l+ox2FLds1TmYBhRR/2Jdbm5aoamh4FVpkmDgGedjERREymvnOIMkhWyUfWE + L8Sxa2d8427cBieiEP4foLgjWKr2+diCDrBymU/pz/ZMRRpvUc2uFV005/vmDedK + xQACQ8ZWBYWzNCV4C0Y5AS1PETxbocZ09Yw6K1XyVveEp8aQ/ROMkAUOObhMD45W + GZNwewGU/V7kclDgMwq6R1VXr5R7NtK9V96vi6ZaujoJKvF1PFpZ/IHWcfFkpVoy + Fu8L5PIkg4weBW+87kp+CCseEXPUplpqQCAnmVJdvilK6vgKc7T+vzbET8LNw7NX + mHOVA3CR2w+yUhN4uiCI1aY= + -----END CERTIFICATE----- + + # The url/ip of a proxy for kapp controller to use when making network + # requests (optional) + httpProxy: proxy-svc.proxy-server.svc.cluster.local:80 + + # The url/ip of a tls capable proxy for kapp controller to use when + # making network requests (optional) + httpsProxy: "" + + # A comma delimited list of domain names which kapp controller should + # bypass the proxy for when making requests (optional) + noProxy: "github.com,docker.io" + + # A comma delimited list of domain names for which kapp controller, when + # fetching images or imgpkgBundles, will skip TLS verification. (optional) + dangerousSkipTLSVerify: "private-registry.com,insecure-registry.com" + + # JSON encoded array of kapp deploy rawOptions that are applied to all App CRs. + # App CR specified rawOptions take precedence over what's specified here. + # Value is parsed via go's json.Unmarshal. + # (optional; v0.37.0+) + kappDeployRawOptions: "[\"--diff-changes=true\"]" + + # Time duration value used as a default for App CR's spec.syncPeriod + # if one is not specified explicitly. Minimum is 30s. + # Value is parsed via go's time.ParseDuration. + # (optional; v0.41.0+) + appDefaultSyncPeriod: "30s" + + # Time duration value to force a minimum for App CR's spec.syncPeriod. + # If this value is greater than explicitly specified syncPeriod, + # this value value will be used instead. Minimum is 30s. + # Value is parsed via go's time.ParseDuration. + # (optional; v0.41.0+) + appMinimumSyncPeriod: "30s" + + # Time duration value used as a default for App CR's spec.syncPeriod + # created via PackageInstall + # if one is not specified explicitly. Minimum is 30s. + # Value is parsed via go's time.ParseDuration. + # (optional; v0.47.0+) + packageInstallDefaultSyncPeriod: "10m" +``` + +## Config Shorthands + +kapp-controller v0.30.0+ supports a shorthand for easily adding the `KUBERNETES_SERVICE_HOST` +environment variable to kapp-controller's `noProxy` controller config property. This can help +when a Kubernetes cluster is configured with a proxy and the kapp-controller-config is created +with the http and https proxy URL. In this case, kapp-controller fails to communicate with the +Kubernetes API server. + +To make this configuration simpler, the `noProxy` property will interpret `KAPPCTRL_KUBERNETES_SERVICE_HOST` +as the value of `KUBERNETES_SERVICE_HOST` (typically 10.96.9.1) environment variable in the kapp-controller pod. + +```yaml +noProxy: "github.com,docker.io,KAPPCTRL_KUBERNETES_SERVICE_HOST" +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/debugging-crs.md b/site/content/kapp-controller/docs/v0.49.x/debugging-crs.md new file mode 100644 index 000000000..9823d7444 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/debugging-crs.md @@ -0,0 +1,126 @@ +--- +aliases: [/kapp-controller/docs/latest/debugging-crs] +title: Debugging CRs +--- + +Running into issues deploying any of the kapp-controller CRs? This page will help with commonly encountered issues. + +If you can't find what you are looking for here, please reach out to us on #carvel. We love hearing from users and are keen to help you resolve any issues! + +## Debugging kapp-controller CRs + +### Reconcile failed +Your first alert to a failure +will come from the tool(s) (e.g. kapp or kubectl) you are using to deploy +kapp-controller CRs. `kapp` will more immediately tell you if a resource you are +creating or updating fails, but you will need to verify with a `kubectl get` if +using `kubectl` to create/update. + +You can verify a failure occurred by running a `kubectl get` for the resource +you encountered the failure with. You can then see in the `DESCRIPTION` column +of the output of `kubectl get` if the reconciliation process for the resource +failed. An example of this is below: + +``` +NAMESPACE NAME PACKAGE NAME PACKAGE VERSION DESCRIPTION AGE +foo instl-pkg-test-fail pkg.fail.carvel.dev 1.0.0 Reconcile failed: Error (see .status.usefulErrorMessage for details) 12s +``` + +### status.usefulErrorMessage +Once you have confirmed an error occurred, you can review the status of the CR +for more information. + +Apps, PackageInstalls, and PackageRepsitories all feature a status property +named `usefulErrorMessage`. `usefulErrorMessage` which contains an error message +from kapp-controller or the stderr from the underlying tool used by +kapp-controller (i.e. vendir, imgpkg, kbld, ytt, kapp, or helm). + +`usefulErrorMessage` will be located at the bottom of the statuses if running a +`kubectl get` or `kubectl describe` to view more information about a failure. + +`usefulErrorMessage` can also be accessed more directly through `kubectl` like +in the following examples: + +``` +# App errors +$ kubectl get apps/simple-app -o=jsonpath={.status.usefulErrorMessage} -n namespace + +# PackageInstall errors +$ kubectl get packageinstall simple-app -o=jsonpath={.status.usefulErrorMessage} -n namespace + +# PackageRepository errors (cluster scoped so no namespace) +$ kubectl get packagerepository repo -o=jsonpath={.status.usefulErrorMessage} +``` + +### Errors from underlying tools (App CR and PackageInstall CR) + +Failures can arise from fetch, template, deploy, or delete steps for an App CR. +These failures correspond to issues with runtime information declared in the App +CR's spec. kapp-controller creates an App CR for every PackageInstall + +Errors are reported as stderr from associated tools used in kapp-controller +(i.e. vendir, imgpkg, kbld, ytt, kapp, and helm) or as direct messages from +kapp-controller (e.g. when an App uses a ServiceAccount that doesn't exist). + +When a failure occurs with an App CR, you can find further details in the App +CR's `DESCRIPTION` column by running `kubectl get apps/simple-app -n namespace`: + +``` +NAME DESCRIPTION SINCE-DEPLOY AGE +simple-app Delete failed: Preparing kapp: Getting service account: serviceaccounts "default-ns-sa" not found 3s 56m +``` + +In the case above, the error message shown is coming directly from +kapp-controller, so all the information for the failure should be presented in +the description column. This commonly occurs when references used by +kapp-controller (e.g. secrets, configmaps, serviceaccounts) are not found by +kapp-controller. + +In cases where the error message does not originate from kapp-controller (e.g. a +failed fetch event for a git repository), the stderr from the underlying tool +(i.e. vendir, imgpkg, kbld, ytt, kapp, and helm) is shown in the App's status. + +In the App status, there is a field called `usefulErrorMessage` that displays +the stderr for a failure during App reconciliation. + +This `usefulErrorMessage` field can be found by running `kubectl get +apps/simple-app -o=jsonpath={.status.usefulErrorMessage} -n namespace`. The +kubectl command will return the stderr output from the App status to help you +further understand the reason for the App failure. + +The `usefulErrorMessage` can be helpful in pointing out where errors occurred +from inputs in the App spec and also pinpoint the resource that caused a +deployment failure. However, Apps will not surface errors of resources they are +deploying to Kubernetes and further debugging of resources deployed by an App +may be needed. + +### Debugging PackageInstall CRs + +Failures for PackageInstalls can be viewed directly via the `usefulErrorMessage` +property of the PackageInstall's status. This `usefulErrorMessage` property +comes from an App CR that is created as a result of creating a PackageInstall. +More information on interpreting the error message from `usefulErrorMessage` can +be found under the [Errors from underlying tools](#Errors from underlying tools (App CR and PackageInstall CR)). The underlying App +CR will have the same name as the PackageInstall that you create. + +You can also inpect the Package CR referenced by the PackageInstall CR for issues. You can view the Package details by running the following command: + +``` +$ kubectl describe package/ +``` + +You can then view the `.template.spec` of the Package to see if there are any +issues with the inputs of the Package. These inputs are eventually used to +create the App for the PackageInstall and can lead to failures. + +### Debugging PackageRepository CRs + +Failures for PackageRepositories can be viewed directly via the +`usefulErrorMessage` property of the PackageRepository's status. More information [here](status.usefulErrorMessage) + +A common source of errors is being unable to fetch the PackageRepository +contents. Please check the `.spec.fetch` portion of the PackageRepository spec for issues related to this. + +Is the registry you are fetching from require authentication? If so, check out [authenticating to private registries](private-registry-auth.md) + +You can also fetch the PackageRepository `imgpkg` bundle or image separately and inspect format of Package resources. diff --git a/site/content/kapp-controller/docs/v0.49.x/debugging-kc.md b/site/content/kapp-controller/docs/v0.49.x/debugging-kc.md new file mode 100644 index 000000000..e6d3a4cf6 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/debugging-kc.md @@ -0,0 +1,13 @@ +--- +aliases: [/kapp-controller/docs/latest/debugging-kc] +title: Debugging kapp-controller +--- + +The following flags can be used to debug the kapp-controller deployment. Use of these flags are **strongly discouraged in a production setting**. + +## `--dangerous-enable-pprof=true` + +This flag enables [Go's pprof server](https://golang.org/pkg/net/http/pprof/) within kapp-controller process. It runs on `0.0.0.0:6060`. It allows to inspect running Go process in various ways, for example: + +- list goroutines: `http://x.x.x.x/debug/pprof/goroutine?debug=2` +- collect CPU samples: `go tool pprof x.x.x.x/debug/pprof/profile?seconds=60` (useful commands: top10, tree) diff --git a/site/content/kapp-controller/docs/v0.49.x/dev.md b/site/content/kapp-controller/docs/v0.49.x/dev.md new file mode 100644 index 000000000..7eed6c3cf --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/dev.md @@ -0,0 +1,24 @@ +--- +aliases: [/kapp-controller/docs/latest/dev] +title: Development & Deploy +--- + +Install ytt, kbld, kapp beforehand (https://carvel.dev). + +``` +./hack/build.sh # to build locally + +# add `-v image_repo=docker.io/username/kapp-controller` with your registry to ytt invocation inside +./hack/deploy.sh # to deploy + +export KAPPCTRL_E2E_NAMESPACE=kappctrl-test +./hack/test-all.sh +``` + +## Release + +``` +# Bump version in cmd/controller/main.go +# Commit +./hack/build-release.sh +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/faq.md b/site/content/kapp-controller/docs/v0.49.x/faq.md new file mode 100644 index 000000000..8fdb25351 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/faq.md @@ -0,0 +1,97 @@ +--- +aliases: [/kapp-controller/docs/latest/faq] +title: FAQ +--- + +## App CR + +This section covers questions for users directly using the [App](app-spec.md) +custom resource. + +### How can I control App CR reconciliation (pause, force, adjust frequency...)? + +You can set and unset spec.paused +([example](https://github.com/carvel-dev/kapp-controller/blob/d94984a77fa907ac5ecc681e9a842b9877766a6b/test/e2e/pause_test.go#L91)) +or fiddle with spec.syncPeriod ([example]( +https://github.com/carvel-dev/kapp-controller/blob/d94984a77fa907ac5ecc681e9a842b9877766a6b/test/e2e/app_secret_configmap_reconcile_test.go#L133)), which +defaults to 30 seconds. + +### How can I tell which version of kapp-controller is installed? + +kapp-controller sets the annotation `kapp-controller.carvel.dev/version` on the deployment to the version deployed, +so e.g. `kubectl describe deployment kapp-controller -n kapp-controller | grep version` will show the installed version. + +## Package Management CRs + +This section covers questions for users directly using the [Package Management CRs](packaging.md) +custom resource. + +### How does kapp-controller handle PackageInstall when a PackageRepository is removed from the cluster? + +If a PackageInstall has been installed successfully from a Package that is part +of a PackageRepository, and if that PacakgeRepository is ever deleted after the +successful install, the PackageInstall will eventually report the following +error: `Reconcile failed: Expected to find at least one version, but did not`. +This error occurs due to the regular syncing of a PackageInstall with its +Package. + +Even though the error above is reported, the Package will still be installed and +should work as expected. It can also still be uninstalled by deleting the +PackageInstall. The PackageRepository can be recreated and the PackageInstall +will sync and reconcile without any updates needed to resolve the error. + +### How can I generate the valuesSchema from my ytt schema? + +If you are using `ytt` as your Package's templating option and have [defined a schema](../../../../ytt/docs/latest/how-to-write-schema), you can use `ytt` to generate your `valuesSchema` (which is in OpenAPI v3 format) for you. + +This is the recommended workflow: + +1. Create an OpenAPI Document from a Data Values Schema file: + + ```bash + $ ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 >schema-openapi.yml + ``` + + which will produce... + + ```yaml + #! schema-openapi.yml + openapi: 3.0.0 + info: + version: 1.0.0 + title: Openapi schema generated from ytt schema + paths: {} + components: + schemas: + dataValues: + type: object + properties: + namespace: + type: string + default: fluent-bit + ``` + +2. Turn your Package CR into a `ytt` template, so that you can insert the schema definition in the right spot, automatically: + + `package-template.yml` + ```yaml + #@ load("@ytt:data", "data") + #@ load("@ytt:yaml", "yaml") + ... + kind: Package + spec: + valuesSchema: + openAPIv3: #@ yaml.decode(data.values.openapi)["components"]["schemas"]["dataValues"] + ... + ``` + + and render with the output from the ytt schema inspect: + + ```bash + $ ytt -f package-template.yml --data-value-file openapi=schema-openapi.yml > package.yml + ``` + +For more details, see: +- [ytt: Export Schema in OpenAPI Format](../../../ytt/docs/latest/how-to-export-schema.md). +- [ytt: Configuring Data Values via command line flags](../../../ytt/docs/latest/ytt-data-values.md#configuring-data-values-via-command-line-flags) +- [@ytt:yaml module](../../../ytt/docs/latest/lang-ref-ytt.md#yaml) diff --git a/site/content/kapp-controller/docs/v0.49.x/install.md b/site/content/kapp-controller/docs/v0.49.x/install.md new file mode 100644 index 000000000..955da7841 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/install.md @@ -0,0 +1,143 @@ +--- +aliases: [/kapp-controller/docs/latest/install] +title: Install +--- + +Grab the latest copy of YAML from the [Releases page](https://github.com/carvel-dev/kapp-controller/releases) and use your favorite deployment tool (such as [kapp](/kapp) or kubectl) to install it. + +Example: + +```bash +$ kapp deploy -a kc -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml +``` + +or + +```bash +$ kubectl apply -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml +``` + +## Specific Environments and Distributions +Some kubernetes distributions require specific setup. +Notes below capture the wisdom of our collective community - we +appreciate your corrections and contributions to help everyone install +kapp-controller everywhere. + +### Openshift + +1. Explicitly set resource packageinstalls/finalizers for kapp controller cluster role to access (else the kapp controller fails to create packageinstalls). + + ``` + kind: ClusterRole + metadata: + name: kapp-controller-cluster-role + rules: + - apiGroups: + - packaging.carvel.dev + resources: + ... + - packageinstalls/finalizers + ``` + +2. Bind the kapp-controller cluster role to a security context constraint allowing uids/gids that kapp deployment uses +(currently uid 1000; value given for `runAsUser` in the release.yaml for your +version of kapp-controller). + + **Note:** The security context constraint you provide should allow kapp-controller's uid + to run and should not have root privileges. + + ``` + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: kapp-controller-cluster-role + rules: + - apiGroups: + - security.openshift.io + resourceNames: + - my-nonroot-security-context-contstraint + resources: + - securitycontextconstraints + verbs: + - use + ``` + +3. Remove the environment variable `IMGPKG_ACTIVE_KEYCHAINS` [environment + variable](/imgpkg/docs/latest/auth/#via-iaas) from the deployment yaml of the sidecar container. + + +### Kubernetes versions >= 1.24 +All kapp-controller versions <= v0.36.1 will be unable to reconcile +PackageInstall and App CRs with the `LegacyServiceAccountTokenNoAutoGeneration` +feature gate, which is enabled by default in Kubernetes starting in v1.24. + +### Kubernetes versions < 1.20 +Starting in kapp-controller 0.31.0 we have upgraded our underlying kubernetes +libraries which will try to use APIs that don't exist on clusters v1.19 and +earlier. + +Those using k8s v1.19 and earlier will see a repeating error message such as the one below, because +our libraries are hardcoded to watch `v1beta1.PriorityLevelConfiguration` and that won't exist on your cluster. +``` +k8s.io/client-go@v0.22.4/tools/cache/reflector.go:167: Failed to watch *v1beta1.PriorityLevelConfiguration: failed to list *v1beta1.PriorityLevelConfiguration: the server could not find the requested resource (get prioritylevelconfigurations.flowcontrol.apiserver.k8s.io) +``` +While kapp-controller will still work, your logs may fill at a remarkable pace. + +To disable these APIs, set the deployment config variable +`enable_api_priority_and_fairness` to false. + +### Installing kapp-controller CLI: kctrl + +#### 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 +$ kctrl version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ kctrl 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 kctrl +$ kctrl 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/kapp-controller/releases), for example for 'kctrl-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/kctrl-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/kctrl-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/kctrl-darwin-amd64 /usr/local/bin/kctrl + +# Make binary executable +$ chmod +x /usr/local/bin/kctrl + +# Check its version +$ kctrl version +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/kctrl-faq.md b/site/content/kapp-controller/docs/v0.49.x/kctrl-faq.md new file mode 100644 index 000000000..cba8e80a6 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/kctrl-faq.md @@ -0,0 +1,122 @@ +--- +aliases: [/kapp-controller/docs/latest/kctrl-faq] +aliases: [/kapp-controller/docs/latest/kctrl-faq] +title: "`kctrl` FAQ" +--- + +### How can we add information to PackageMetadata generated by `kctrl package release`? +Any changes to the PackageMetadata reesource in the `package-resources.yml` file will be copied over to the released artifact. + +### How can I build images while releasing a package using `kctrl`? +`kctrl` builds and pushes images using `kbld` if a `kbld` config is specified in the config being bundled into the package. + +For example, +```yaml +# config/config-release.yml +apiVersion: kbld.k14s.io/v1alpha1 +kind: Config +sources: +- image: simple-app + path: . +destinations: +- image: simple-app + newImage: 100mik/simple-app +``` +Here, we are expressing that the image referred to as `simple-app` needs to be built from the root of the project (the path being `.`). +And pushed to OCI registry `100mik/simple-app`. + +This file needs to reside in the paths passed to `ytt` in the AppSpec described in the PackageBuild resource. And also be included +in the list of paths assigned to key `includePaths`. + +Along with `kbld` configuration, the container image name in the deployment should be same as the `sources.image` in the `kbld` configuration. e.g.: +``` +apiVersion: apps/v1 +kind: Deployment +metadata: + name: simple-app +spec: + selector: + matchLabels: + simple-app: "" + template: + metadata: + labels: + simple-app: "" + spec: + containers: + - name: simple-app + image: simple-app #! <-- should be same as `sources.image` in the kbld config + env: + - name: SIMPLE_MSG + value: stranger +``` + +### How can we add ytt overlays or additional configuration to upstream release artifacts? +Overlays can be created in a separate folder in the project directory. `kctrl` can be made aware of any additional folders by updating `package-build.yml` manually, +If the project directory looks something like this, +```bash +. +├── package-build.yml +├── package-resources.yml +├── upstream +│ └── cert-manager.yaml +├── overlays +│ └── overlay.yaml +│ └── values-schema.yaml +├── vendir.lock.yml +└── vendir.yml +``` +Where, the directory overlays containing `ytt` files is created by the user. The fields `includePaths` and the `template` section of the App `spec` needs to be updated in `package-build.yml` like this, +``` +apiVersion: kctrl.carvel.dev/v1alpha1 +kind: PackageBuild +metadata: +name: certmanager.carvel.dev +spec: +release: +- resource: {} +template: + spec: + app: + spec: + deploy: + - kapp: {} + template: + - ytt: + paths: + - upstream + - overlays # <= addition to package template + - kbld: {} + export: + - imgpkgBundle: + image: 100mik/certman-carvel-package + useKbldImagesLock: true + includePaths: + - upstream + - overlays # <= ensure additional files are included in imgpkg bundle +``` +This is to ensure that the package is aware of the additional files, while `includePaths` ensures that the folder is a part of the `imgpkg` bundle created by `kctrl`. + +The template section in `package-resources.yml` should be updated in a similar fashion to ensure that `kctrl dev` yields accurate results. + +`kctrl` generates the OpenAPI schema for a package if a values schema is provided. + +### How can we go about updating a package dependent on an upstream release? +This can be done by running `kctrl package init` again and using the new tag/version. Alternatively, the value can be updated in the `vendir.yml` file and the new changes can be fetched by running `vendir sync`. + +WARNING: This will overwrite any changes to the `/upstream` directory. It is recommended that any additional configuration or overlays should reside in a separate folder. + +### Can `kctrl` be used to publish packages in a CI pipeline? +Yes! `kctrl` remembers the answers to questions that have been answered. +The `--yes` flag can be used to run the `release` command while using previously supplied +values if `package-resources.yml` and `package-build.yml` are committed to a repository with the source code. + +### Can we provide our own `ImagesLock` resource instead of it being generated when we run the `pkg release` command? +Yes, the path containing the file will need to be added [here](/kapp-controller/docs/develop/kctrl-faq/#how-can-we-add-ytt-overlays-and-values-schema-for-upstream-release-artifacts), before updating `package-build.yml` and setting the key `useKbldImagesLock` in the `export` section to false. + +### Can I build images from source while using `kctrl dev`? +Yes, if the `--kbld-build` command is supplied to the `dev` command, it will build images if a `kbld` config (similar to the one seen [here](https://carvel.dev/kapp-controller/docs/latest/kctrl-faq/#how-can-i-build-images-while-releasing-a-package-using-kctrl)) defines it. + +NOTE: If your cluster points to the same `docker` daemon using used by `kbld` while building images. The images need not be pushed to a registry (only `sources` need to be defined). +This is useful in some development environments, for example, if you are using a `minikube` cluster, and your local enironment points to the +`docker` daemon inside the `minikube` cluster, this can be set up by doing something like (`eval $(minikube docker-env)`) diff --git a/site/content/kapp-controller/docs/v0.49.x/kctrl-package-authoring.md b/site/content/kapp-controller/docs/v0.49.x/kctrl-package-authoring.md new file mode 100644 index 000000000..366d8f011 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/kctrl-package-authoring.md @@ -0,0 +1,556 @@ +--- +aliases: [/kapp-controller/docs/latest/kctrl-package-authoring] +aliases: [/kapp-controller/docs/latest/kctrl-package-authoring] +title: Authoring packages with kctrl +--- + +Before we jump in, we will create a namespace which will act as our playground and point our `kubeconfig` towards it. +```bash +$ kubectl create ns kctrl-tutorial +$ kubectl config set-context --current --namespace=kctrl-tutorial +``` +This must be done as installation of packages in public namespaces is a bad practice and disallowed by `kctrl`. + +This set of tutorials cover how `kctrl` helps authors release their configuration packaged as Carvel packages and test them. +## Packaging upstream artifacts +This tutorial explores how `kctrl` (from v0.40.0 onwards) allows us to create Carvel packages using existing artifacts like manifests released as a part of a GitHub release or a Helm chart. +For this tutorial we will package a release of `cert-manager` as a Carvel package. + +This tutorial requires `kapp-controller` to be installed on the cluster. + +### Getting started + +To start off, let's create a directory which acts as our working directory. + +```bash +$ mkdir certman-package +$ cd certman-package +``` + +Next we run the `init` command to set the stage! + +```bash +$ kctrl package init +``` + +`kctrl` asks a few quick questions to gather what it needs to know. +We know that `cert-manager` lives on the GitHub repository [_cert-manager/cert-manager_](https://github.com/cert-manager/cert-manager) and that it's releases have a manifest `cert-manager.yaml` which let's users deploy cert-manager on cluster. Our goal would be to build a package around this artifact. + +If we want to package `cert-manager v1.9.0`, we interact with package init somewhat like this: + +![Package Init for Cert Manager](/images/kctrl/pkg-init-certman.png) + +In the first step, we can see that the artifact could have been a helm chart or another artifact residing in the repository itself. + +Once, `kctrl` knows where to find our config, it uses `vendir` to make a copy of the required artifacts in the upstream folder. +```bash +$ ls upstream +cert-manager.yaml +``` + +### Releasing packages + +Now that `kctrl` knows what it is dealing with, we can use the release command to make a publish Package and PackageMetadata resources. +```bash +$ kctrl package release --version 1.0.0 +``` + +We just provide a image registry that `kctrl` can push OCI images to. Ensure that your host is authorised to push to the registry. + +![Package Release for Cert Manager](/images/kctrl/pkg-release-certman.png) + +`kctrl` first tries to build any images that are necessary, however, in our case we do not have any images that need to be built as we are consuming a released artifact. It bundles the fetched upstream config into an `imgpkg` bundle that is consumed by the Package. + +It then creates the required artifacts in the `carvel-artifacts` directory. +```yaml +# carvel-artifacts/packages/certmanager.carvel.dev/package.yaml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + creationTimestamp: null + name: certmanager.carvel.dev.1.9.0 +spec: + refName: certmanager.carvel.dev + releasedAt: "2022-08-03T22:40:06Z" + template: + spec: + deploy: + - kapp: {} + fetch: + - imgpkgBundle: + image: index.docker.io/100mik/certman-carvel-package@sha256:93a4e6d0577a0c56b69f7d7b24621d98bd205f69846a683a4dc5bcdd53879da5 + template: + - ytt: + paths: + - upstream + - kbld: + paths: + - '-' + - .imgpkg/images.yml + valuesSchema: + openAPIv3: + default: null + nullable: true + version: 1.9.0 + +# carvel-artifacts/packages/certmanager.carvel.dev/metadata.yaml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + creationTimestamp: null + name: certmanager.carvel.dev +spec: + displayName: certmanager +``` +These artifacts can be used to create the necessary resources on the cluster. +```bash +$ kapp deploy -a cert-manager-package -f carvel-artifacts/packages/certmanager.carvel.dev +``` +Once we have created these resources using `kapp`, we should be able to find these packages on the cluster using `kctrl`. +```bash +$ kctrl package available list +Target cluster 'https://127.0.0.1:62733' (nodes: minikube) + +Available summarized packages in namespace 'default' + +Name Display name +certmanager.carvel.dev certmanager + +Succeeded +``` + +### Relevant FAQs +- [How can we add additional configuration to an upstream release artifact?](/kapp-controller/docs/latest/kctrl-faq/#how-can-we-add-ytt-overlays-or-additional-configuration-to-upstream-release-artifacts) +- [How can we go about updating packages dependent on an upstream release?](/kapp-controller/docs/latest/kctrl-faq/#how-can-we-go-about-updating-a-package-dependent-on-an-upstream-release) + +## Building packages from source +This tutorial is a walk-through of how `kctrl` can be used to build and package your project as a Carvel package. + +For this tutorial we will start off with a [simple web server](https://github.com/cppforlife/simple-app). +We will create resources to deploy the application on Kubernetes and then release a Carvel package for the same using `kctrl`. + +First, the playground can be set up by cloning the project we are working with. +```bash +$ git clone https://github.com/cppforlife/simple-app +$ cd simple-app +``` + +### Putting together some configuration + +We can add a `config` directory to store our Kubernetes config. +```bash +$ mkdir config +``` + +We will need a Deployment and a Service pointing to it to deploy this project. We can define these in `config/config.yml`. +The image defined by the `Dockerfile` must be built and pushed to an OCI registry (`100mik/simple-app` in this case). + +(See [here](/kapp-controller/docs/latest/kctrl-faq/#how-can-i-build-images-while-releasing-a-package-using-kctrl) to see how +we can have `kctrl` build images while releasing) +```yaml +# config/config.yml +--- +apiVersion: v1 +kind: Service +metadata: + name: simple-app +spec: + ports: + - port: 80 + targetPort: 8080 + selector: + simple-app: "" +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: simple-app +spec: + selector: + matchLabels: + simple-app: "" + template: + metadata: + labels: + simple-app: "" + spec: + containers: + - name: simple-app + image: 100mik/simple-app + env: + - name: SIMPLE_MSG + value: stranger +``` +Great! We now have our configuration in place. + +### Setting up `kctrl` +We can run the `init` command to initialise the process. +```bash +$ kctrl package init +``` + +This command asks a few questions regarding how we want to build our package. +In this case, we want to build a package `simple-app.carvel.dev` from the local directory. +The configuration for the same can be found in the `config` directory. The interaction looks something like this, + +![Package Init for Simple App](/images/kctrl/pkg-init-simple-app.png) + +This command generates `package-build.yml` and `package-reources.yml` files that tell `kctrl` how it should put the package together! + +### Releasing the package + +We can release the first version of our carvel package using the `release` command now! +```bash +$ kctrl package release --version 1.0.0 +``` +At this step we need to tell kctrl where we want to push our `imgpkg` bundle. +Which is essentially an OCI image that contains all necessary config. +The interaction looks something like this, + +![Package Release for Simple App](/images/kctrl/pkg-release-simple-app.png) + +This command creates the Package and PackageMetadata resources in directory `carvel-artifacts`. +```yaml +# carvel-artifacts/packages/simple-app.carvel.dev/package.yml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + name: simple-app.carvel.dev.1.0.0 +spec: + refName: simple-app.carvel.dev + releasedAt: "2022-08-08T20:46:18Z" + template: + spec: + deploy: + - kapp: {} + fetch: + - imgpkgBundle: + image: index.docker.io/100mik/simple-package@sha256:dbf26c20859b32c0e08711c3af28844cc3e54968c3fa39e1975912ccbbb52899 + template: + - ytt: + paths: + - config + - kbld: + paths: + - '-' + - .imgpkg/images.yml + valuesSchema: + openAPIv3: + default: null + nullable: true + version: 1.0.0 + +# carvel-artifacts/packages/simple-app.carvel.dev/metadata.yml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + name: simple-app.carvel.dev +spec: + displayName: simple-app +``` +We can add these packages to the cluster using `kapp`. +```bash +kapp deploy -a simple-app-package -f carvel-artifacts/packages/simple-app.carvel.dev +``` +(`kubectl apply` would yield the same result) + +We should now be able to see our package on the cluster +```bash +$ kctrl package available list +Target cluster 'https://127.0.0.1:62733' (nodes: minikube) + +Available summarized packages in namespace 'default' + +Name Display name +simple-app.carvel.dev simple-app + +Succeeded +``` + +We can install the package on the cluster to create the packaged resources. +```bash +$ kctrl package install -i simple-app -p simple-app.carvel.dev --version 1.0.0 +``` + +Congratulations! `simple-app`s first Carvel package has been created using `kctrl`. + +### Relevant FAQs +- [How can I build images while releasing a package with `kctrl`?](/kapp-controller/docs/latest/kctrl-faq/#how-can-i-build-images-while-releasing-a-package-using-kctrl) +- [How can we add information to PackageMetadata generated by `kctrl package release`?](/kapp-controller/docs/latest/kctrl-faq/#how-can-we-add-information-to-packagemetadata-generated-by-kctrl-packge-release) +- [Can kctrl be used to publish packages in a CI pipeline?](/kapp-controller/docs/latest/kctrl-faq/#can-kctrl-be-used-to-publish-packages-in-a-ci-pipeline) +- [Can we provide our own ImagesLock resource?](/kapp-controller/docs/latest/kctrl-faq/#can-we-provide-our-own-imageslock-resource-instead-of-it-being-generated-when-we-run-the-pkg-release-command) + + +## Creating a package repository +`kctrl` can be used to release packages grouped together as a PackageRepository. +In this tutorial, let's bundle the two packages created in the previous tutorial into a PackageRepository. + +Let us create a folder for our repository, in the same directory where the other two projects exist. +```bash +$ mkdir demo-repo +$ tree -L 1 +. +├── certman-package +├── demo-repo +└── simple-app +``` + +The `--repo-output` flag can be used while releasing a package to create artifacts in the prescribed [PackageRepository bundle](/kapp-controller/docs/latest/packaging-artifact-formats/#package-repository-bundle) format at a specified location. +Let us make releases for both these packages while creating a repo bundle in the `demo-repo` folder. +```bash +# Releasing package for cert-manager +$ cd certmanager-package +$ kctrl package release --version 1.0.0 --repo-output ../demo-repo + +# Releasing package for simple-app +$ cd ../simple-app +$ kctrl package release --version 1.0.0 --repo-output ../demo-repo +``` + +Let's verify that the artifacts created in the `demo-repo` folder are in the desired bundle format. +```bash +$ cd ../demo-repo +$ tree +└── packages + ├── certmanager.carvel.dev + │   ├── 1.0.0.yml + │   └── metadata.yml + └── simple-app.carvel.dev + ├── 1.0.0.yml + └── metadata.yml +``` +`kctrl` can now be used to create a repository bundle and publish it on an OCI registry. +```bash +$ kctrl package repo release -v 1.0.0 +``` +`kctrl` first asks us to name our repository. We will be calling ours `demo.carvel.dev`. +![Package Release Step 1](/images/kctrl/pkg-repo-release-1.png) + +We are then required to specify the OCI registry we want to push our repository bundle to. +This bundle will contain all config required by the PackageRepositopry to create the required Packages on the cluster. +![Package Release Step 2](/images/kctrl/pkg-repo-release-2.png) + +Once `kctrl` has the required details it builds an `imgpkg` bundle and publishes it on an OCI registry. +![Package Release Step 3](/images/kctrl/pkg-repo-release-3.png) + +Two files are created when a PackageRepository is released successfully. + +`pkgrepo-build.yml` stores some metadata generated using the user inputs during the first release. +This can be comitted to a `git` repository, if users want to do releases in their CI pipelines. + +`package-repository.yml` has a PackageRepository resource that can be applied to the cluster directly. + +Let's use `kctrl` to add the repository to the cluster. We can use the bundle location that we can see in the output. +This location is also stored in the `package-repository.yml` artifact. We can use the version of the repository as a +tag while adding the PackageRepository bundle if specified using the `-v` flag. +```bash +$ kctrl package repository add -r demo-repo --url index.docker.io/100mik/demo-repo:1.0.0 +``` +Once the repository is added successfully we should be able to see our packages on the cluster. +```bash +$ kctrl package available list +Target cluster 'https://127.0.0.1:49841' (nodes: minikube) + +Available summarized packages in namespace 'default' + +Name Display name +certmanager.carvel.dev certmanager +simple-app.carvel.dev simple-app + +Succeeded +``` +Great! We have now bundled and published two of our packages together as a PackageRepository. + +## Testing packages locally +`kctrl` enables users authoring Apps and Packages using `kapp-controller`'s APIs to test their resources effectively. +Let us test our `simple-app` package locally. + +This can be done by using the `dev` command, and it does not require `kapp-controller` to be installed +on the cluster. The fetch and template steps are done locally on the host running the command before +using `kapp` to deploy the resources on the cluster. + +Let us take a look at the `package-resources.yml` file generated by `kctrl` while initialising the package. +```yaml +#package-resources.yml + +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + creationTimestamp: null + name: simple-app.carvel.dev.0.0.0 +spec: + refName: simple-app.carvel.dev + releasedAt: null + template: + spec: + deploy: + - kapp: {} + fetch: + - git: {} + template: + - ytt: + paths: + - config + - kbld: {} + valuesSchema: + openAPIv3: null + version: 0.0.0 + +--- +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + creationTimestamp: null + name: simple-app.carvel.dev +spec: + displayName: simple-app + longDescription: simple-app.carvel.dev + shortDescription: simple-app.carvel.dev + +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + annotations: + kctrl.carvel.dev/local-fetch-0: . + creationTimestamp: null + name: simple-app +spec: + packageRef: + refName: simple-app.carvel.dev + versionSelection: + constraints: 0.0.0 + serviceAccountName: simple-app-sa +status: + conditions: null + friendlyDescription: "" + observedGeneration: 0 +``` +We need to ensure that the service account referred to in the file is created on the cluster. +Alternatively, it can be replaced by a service account that has already been created. + +To create `simple-app-sa` referred to in the config along with required RBAC resources run, +```bash +$ kapp deploy -a simple-app-rbac -f https://carvel.dev/files/simple-app-rbac.yml +``` + +We want to use the configuration on our host instead of fetching it, this is indicated by the `--local` flag. + +`kctrl` needs to be informed where it can find the folder `config` on the host. This is done by using the annotation +`kctrl.carvel.dev/local-fetch-0: .` on the PackageInstall resource. It tells `dev` that +the files `kapp-controller` would otherwise fetch, is available in the root of the project. + +Let's build and deploy from source. +```bash +$ kctrl dev -f package-resources.yml --local +Target cluster 'https://192.168.64.10:8443' (nodes: minikube) + +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + annotations: + kctrl.carvel.dev/local-fetch-0: . + creationTimestamp: null + name: simple-app + namespace: kctrl-tutorial +spec: + packageRef: + refName: simple-app.carvel.dev + versionSelection: + constraints: 0.0.0 + serviceAccountName: simple-app-sa +status: + conditions: null + friendlyDescription: "" + observedGeneration: 0 + +Reconciling in-memory app/simple-app (namespace: default) ... +==> Executing /usr/local/bin/vendir [vendir sync -f - --lock-file /dev/null] +==> Finished executing /usr/local/bin/vendir + +==> Executing /usr/local/bin/ytt [ytt -f /var/folders/8n/8x1y1v2s6bs1cm5nmdmc63th0000gn/T/kapp-controller-fetch-template-deploy2431122835/0/config] +==> Finished executing /usr/local/bin/ytt + +==> Executing /usr/local/bin/kbld [kbld -f -] +==> Finished executing /usr/local/bin/kbld + +==> Executing /usr/local/bin/kapp [kapp deploy -f - --app-changes-max-to-keep=5 --app simple-app-ctrl --kubeconfig=/dev/null --yes] + +1:56:42AM: Fetch started (14s ago) +1:56:42AM: Fetching (13s ago) + | apiVersion: vendir.k14s.io/v1alpha1 + | directories: + | - contents: + | - directory: {} + | path: . + | path: "0" + | kind: LockConfig + | +1:56:42AM: Fetch succeeded (13s ago) +1:56:54AM: Template succeeded (2s ago) +1:56:54AM: Deploy started (2s ago) +1:56:56AM: Deploying + | Target cluster 'https://192.168.64.10:8443' (nodes: minikube) + | Changes + | Namespace Name Kind Age Op Op st. Wait to Rs Ri + | kctrl-tutorial simple-app Deployment - create - reconcile - - + | ^ simple-app Service - create - reconcile - - + | Op: 2 create, 0 delete, 0 update, 0 noop, 0 exists + | Wait to: 2 reconcile, 0 delete, 0 noop + | 1:56:54AM: ---- applying 2 changes [0/2 done] ---- + | 1:56:54AM: create deployment/simple-app (apps/v1) namespace: default + | 1:56:54AM: create service/simple-app (v1) namespace: default + | 1:56:54AM: ---- waiting on 2 changes [0/2 done] ---- + | 1:56:54AM: ok: reconcile service/simple-app (v1) namespace: default + | 1:56:54AM: ongoing: reconcile deployment/simple-app (apps/v1) namespace: default + | 1:56:54AM: ^ Waiting for generation 2 to be observed + | 1:56:54AM: L ok: waiting on replicaset/simple-app-6b69449d66 (apps/v1) namespace: default + | 1:56:54AM: ---- waiting on 1 changes [1/2 done] ---- + | 1:56:55AM: ongoing: reconcile deployment/simple-app (apps/v1) namespace: default + | 1:56:55AM: ^ Waiting for 1 unavailable replicas + | 1:56:55AM: L ok: waiting on replicaset/simple-app-6b69449d66 (apps/v1) namespace: default + | 1:56:55AM: L ongoing: waiting on pod/simple-app-6b69449d66-4gv8m (v1) namespace: default + | 1:56:55AM: ^ Pending: ContainerCreating + | 1:56:57AM: ok: reconcile deployment/simple-app (apps/v1) namespace: default + | 1:56:57AM: ---- applying complete [2/2 done] ---- + | 1:56:57AM: ---- waiting complete [2/2 done] ---- + | Succeeded +1:56:57AM: Deploy succeeded +==> Finished executing /usr/local/bin/kapp + +Succeeded +``` +We can see the result of the steps `kapp-controller` would perform while creating resources when +the package is installed. + +`dev` has created a `kapp` app (`simple-app.app`) on the cluster. +The resources that are a part of the app can be inspected, +```bash +$ kapp inspect -a simple-app.app +Target cluster 'https://127.0.0.1:50423' (nodes: minikube) + +Resources in app 'simple-app.app' + +Namespace Name Kind Owner Rs Ri Age +kctrl-tutorial simple-app Deployment kapp ok - 8m +^ simple-app Endpoints cluster ok - 8m +^ simple-app Service kapp ok - 8m +^ simple-app-2v6s5 EndpointSlice cluster ok - 8m +^ simple-app-5b97676c94 ReplicaSet cluster ok - 8m +^ simple-app-5b97676c94-h8hgw Pod cluster ok - 8m + +Rs: Reconcile state +Ri: Reconcile information + +6 resources + +Succeeded +``` +We can delete the app created once we are satisfied with the results, +```bash +$ kapp delete -a simple-app.app --yes +``` +Thus, we can reproduce the state that a package installation would create reliably! + +### Relevant FAQs +- [Can I build images from source while using `kctrl dev`?](/kapp-controller/docs/develop/kctrl-faq/#can-i-build-images-from-source-while-using-kctrl-dev) diff --git a/site/content/kapp-controller/docs/v0.49.x/kctrl-package-tutorial.md b/site/content/kapp-controller/docs/v0.49.x/kctrl-package-tutorial.md new file mode 100644 index 000000000..436ab4190 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/kctrl-package-tutorial.md @@ -0,0 +1,458 @@ +--- +aliases: [/kapp-controller/docs/latest/kctrl-package-tutorial] +title: Consuming Packages using the CLI +--- + +## Adding a PackageRepository to the cluster +We will be using the [TCE repository](oss-packages.md#tanzu-community-edition) maintained by the contributors to TCE for this tutorial. + +Lets add the repository to our cluster using `kctrl` and a link to the `imgpkg` bundle. + +```bash +$ kctrl package repo add -r tce --url projects.registry.vmware.com/tce/main:0.10.0 +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Waiting for package repository to be added + +1:43:45PM: packagerepository/tce (packaging.carvel.dev/v1alpha1) namespace: default: Reconciling +1:43:51PM: packagerepository/tce (packaging.carvel.dev/v1alpha1) namespace: default: ReconcileSucceeded + +Succeeded +``` + +We can list available repositories to verify that the repo has been added. + +```bash +$ kctrl package repo list +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Repositories in namespace 'default' + +Name Source Status +tce (imgpkg) projects.registry.vmware.com/tce/main:0.10.0 Reconcile succeeded + +Succeeded +``` + +Lets take a quick look at the packages added as a part of this repository. + +```bash +$ kctrl package available list +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Available summarized packages in namespace 'default' + +Name Display name +cert-manager.community.tanzu.vmware.com cert-manager +contour.community.tanzu.vmware.com contour +external-dns.community.tanzu.vmware.com external-dns +fluent-bit.community.tanzu.vmware.com fluent-bit +gatekeeper.community.tanzu.vmware.com gatekeeper +grafana.community.tanzu.vmware.com grafana +harbor.community.tanzu.vmware.com harbor +knative-serving.community.tanzu.vmware.com knative-serving +local-path-storage.community.tanzu.vmware.com local-path-storage +multus-cni.community.tanzu.vmware.com multus-cni +prometheus.community.tanzu.vmware.com prometheus +velero.community.tanzu.vmware.com velero +whereabouts.community.tanzu.vmware.com whereabouts + +Succeeded +``` +We can get more details about a particular package. + +```bash +$ kctrl package available get -p cert-manager.community.tanzu.vmware.com +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Name cert-manager.community.tanzu.vmware.com +Display name cert-manager +Categories - certificate management +Short description Certificate management +Long description Provides certificate management provisioning within the cluster +Provider VMware +Maintainers - name: Nicholas Seemiller +Support description Go to https://cert-manager.io/ for documentation + +Version Released at +1.3.3 2021-08-06 18:01:21 +0530 IST +1.4.4 2021-08-23 22:17:51 +0530 IST +1.5.4 2021-08-23 22:52:51 +0530 IST +1.6.1 2021-10-29 17:30:00 +0530 IST + +Succeeded +``` + +## Installing a Package + +Lets install one of these packages. `kctrl` creates the associated resources required by the PackageInstall to create resources on the cluster. + +```bash +$ kctrl package install -i cert-man -p cert-manager.community.tanzu.vmware.com --version 1.6.1 + +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +3:05:42PM: Creating service account 'cert-man-default-sa' +3:05:42PM: Creating cluster admin role 'cert-man-default-cluster-role' +3:05:43PM: Creating cluster role binding 'cert-man-default-cluster-rolebinding' +3:05:43PM: Creating package install resource +3:05:43PM: Waiting for PackageInstall reconciliation for 'cert-man' +3:05:44PM: Fetch started (1s ago) +3:05:45PM: Fetching + | apiVersion: vendir.k14s.io/v1alpha1 + | directories: + | - contents: + | - imgpkgBundle: + | image: projects.registry.vmware.com/tce/cert-manager@sha256:ca4c551c1e9c5bc0e2b554f20651c9538c97a1159ccf9c9b640457e18cdec039 + | path: . + | path: "0" + | kind: LockConfig + | +3:05:45PM: Fetch succeeded +3:05:47PM: Template succeeded +3:05:47PM: Deploy started (1s ago) +3:05:49PM: Deploying + | Target cluster 'https://10.92.0.1:443' (nodes: gke-cluster-sm-default-pool-28d3ddcd-gjqs, 2+) + | Changes + | Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri + | (cluster) cert-manager Namespace - - create - reconcile - - + | ^ cert-manager-cainjector ClusterRole - - create - reconcile - - + | ^ cert-manager-cainjector ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-approve:cert-manager-io ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-approve:cert-manager-io ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-certificates ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-certificates ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-certificatesigningrequests ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-certificatesigningrequests ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-challenges ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-challenges ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-clusterissuers ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-clusterissuers ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-ingress-shim ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-ingress-shim ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-issuers ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-issuers ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-controller-orders ClusterRole - - create - reconcile - - + | ^ cert-manager-controller-orders ClusterRoleBinding - - create - reconcile - - + | ^ cert-manager-edit ClusterRole - - create - reconcile - - + | ^ cert-manager-view ClusterRole - - create - reconcile - - + | ^ cert-manager-webhook MutatingWebhookConfiguration - - create - reconcile - - + | ^ cert-manager-webhook ValidatingWebhookConfiguration - - create - reconcile - - + | ^ cert-manager-webhook:subjectaccessreviews ClusterRole - - create - reconcile - - + | ^ cert-manager-webhook:subjectaccessreviews ClusterRoleBinding - - create - reconcile - - + | ^ certificaterequests.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | ^ certificates.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | ^ challenges.acme.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | ^ clusterissuers.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | ^ issuers.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | ^ orders.acme.cert-manager.io CustomResourceDefinition - - create - reconcile - - + | cert-manager cert-manager Deployment - - create - reconcile - - + | ^ cert-manager Service - - create - reconcile - - + | ^ cert-manager ServiceAccount - - create - reconcile - - + | ^ cert-manager-cainjector Deployment - - create - reconcile - - + | ^ cert-manager-cainjector ServiceAccount - - create - reconcile - - + | ^ cert-manager-webhook Deployment - - create - reconcile - - + | ^ cert-manager-webhook Service - - create - reconcile - - + | ^ cert-manager-webhook ServiceAccount - - create - reconcile - - + | ^ cert-manager-webhook:dynamic-serving Role - - create - reconcile - - + | ^ cert-manager-webhook:dynamic-serving RoleBinding - - create - reconcile - - + | kube-system cert-manager-cainjector:leaderelection Role - - create - reconcile - - + | ^ cert-manager-cainjector:leaderelection RoleBinding - - create - reconcile - - + | ^ cert-manager:leaderelection Role - - create - reconcile - - + | ^ cert-manager:leaderelection RoleBinding - - create - reconcile - - + | Op: 45 create, 0 delete, 0 update, 0 noop, 0 exists + | Wait to: 45 reconcile, 0 delete, 0 noop + | 9:35:49AM: ---- applying 23 changes [0/45 done] ---- + | 9:35:49AM: create validatingwebhookconfiguration/cert-manager-webhook (admissionregistration.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-certificates (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-orders (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-ingress-shim (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-challenges (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-approve:cert-manager-io (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-edit (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-view (rbac.authorization.k8s.io/v1) cluster + | 9:35:49AM: create clusterrole/cert-manager-controller-certificatesigningrequests (rbac.authorization.k8s.io/v1) cluster + # .... + # . + # . + # . + # .... + | 9:35:59AM: ^ Waiting for 1 unavailable replicas + | 9:35:59AM: L ok: waiting on replicaset/cert-manager-cainjector-5588886b68 (apps/v1) namespace: cert-manager + | 9:35:59AM: L ongoing: waiting on pod/cert-manager-cainjector-5588886b68-26pwz (v1) namespace: cert-manager + | 9:35:59AM: ^ Pending: ContainerCreating + | 9:36:00AM: ongoing: reconcile deployment/cert-manager-webhook (apps/v1) namespace: cert-manager + | 9:36:00AM: ^ Waiting for 1 unavailable replicas + | 9:36:00AM: L ok: waiting on replicaset/cert-manager-webhook-57b5dfd498 (apps/v1) namespace: cert-manager + | 9:36:00AM: L ongoing: waiting on pod/cert-manager-webhook-57b5dfd498-pdx86 (v1) namespace: cert-manager + | 9:36:00AM: ^ Condition Ready is not True (False) + | 9:36:01AM: ok: reconcile deployment/cert-manager (apps/v1) namespace: cert-manager + | 9:36:01AM: ok: reconcile deployment/cert-manager-cainjector (apps/v1) namespace: cert-manager + | 9:36:01AM: ---- waiting on 1 changes [44/45 done] ---- + | 9:36:08AM: ok: reconcile deployment/cert-manager-webhook (apps/v1) namespace: cert-manager + | 9:36:08AM: ---- applying complete [45/45 done] ---- + | 9:36:08AM: ---- waiting complete [45/45 done] ---- + | Succeeded +3:06:09PM: App reconciled + +Succeeded +``` +(_deploy output truncated_) + +`kctrl` waits for the PackageInstall to reconcile successfully. + +Users can also pass a `values.yml` file defining values to be consumed by the package using the `--values-file` flag. Let's see what values are accepted by the Cert Manager Package and supply custom values to it. + +```bash +$ kctrl package available get -p cert-manager.community.tanzu.vmware.com/1.6.1 --values-schema +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Values schema for 'cert-manager.community.tanzu.vmware.com/1.6.1' + +Key Default Type Description +namespace cert-manager string The namespace in which to deploy cert-manager. + +Succeeded +``` +It is worth noting that both the package name and version have to be supplied to view the values a package accepts as these might change across versions. `kctrl` accepts this in the `package-name/package-version` format. + +Lets create a `values.yml` file that supplies a custom value for `namespace` to the installation. + +```yaml +cat > values.yml << EOF +--- +namespace: cert-man-install +EOF +``` +Let's update the installation to use these values. + +`kctrl` creates a secret with the values defined in the file, updates the package installation to consume it and then waits for it to reconcile to the new desired state. + +```bash +$ kctrl package installed update -i cert-man --values-file values.yml + +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +3:10:05PM: Getting package install for 'cert-man' +3:10:06PM: Creating secret 'cert-man-default-values' +3:10:06PM: Updating package install for 'cert-man' +3:10:06PM: Waiting for PackageInstall reconciliation for 'cert-man' +3:10:08PM: Fetching + | apiVersion: vendir.k14s.io/v1alpha1 + | directories: + | - contents: + | - imgpkgBundle: + | image: projects.registry.vmware.com/tce/cert-manager@sha256:ca4c551c1e9c5bc0e2b554f20651c9538c97a1159ccf9c9b640457e18cdec039 + | path: . + | path: "0" + | kind: LockConfig + | +3:10:08PM: Fetch succeeded +3:10:10PM: Template succeeded +3:10:10PM: Deploy started (1s ago) +3:10:12PM: Deploying + | Target cluster 'https://10.92.0.1:443' (nodes: gke-cluster-sm-default-pool-28d3ddcd-gjqs, 2+) + | Changes + | Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri + | (cluster) cert-man-install Namespace - - create - reconcile - - + | ^ cert-manager Namespace - 4m delete - delete ok - + | ^ cert-manager-cainjector ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-approve:cert-manager-io ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-certificates ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-certificatesigningrequests ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-challenges ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-clusterissuers ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-ingress-shim ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-issuers ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-controller-orders ClusterRoleBinding - 4m update - reconcile ok - + | ^ cert-manager-webhook MutatingWebhookConfiguration - 4m update - reconcile ok - + | ^ cert-manager-webhook ValidatingWebhookConfiguration - 4m update - reconcile ok - + | ^ cert-manager-webhook:subjectaccessreviews ClusterRoleBinding - 4m update - reconcile ok - + | ^ certificaterequests.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | ^ certificates.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | ^ challenges.acme.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | ^ clusterissuers.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | ^ issuers.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | ^ orders.acme.cert-manager.io CustomResourceDefinition 2/2 t 4m update - reconcile ok - + | cert-man-install cert-manager Deployment - - create - reconcile - - + | ^ cert-manager Service - - create - reconcile - - + | ^ cert-manager ServiceAccount - - create - reconcile - - + | ^ cert-manager-cainjector Deployment - - create - reconcile - - + | ^ cert-manager-cainjector ServiceAccount - - create - reconcile - - + | ^ cert-manager-webhook Deployment - - create - reconcile - - + | ^ cert-manager-webhook Service - - create - reconcile - - + | ^ cert-manager-webhook ServiceAccount - - create - reconcile - - + | ^ cert-manager-webhook:dynamic-serving Role - - create - reconcile - - + | ^ cert-manager-webhook:dynamic-serving RoleBinding - - create - reconcile - - + | cert-manager cert-manager Deployment 2/2 t 4m delete - delete ok - + | ^ cert-manager Service - 4m delete - delete ok - + | ^ cert-manager ServiceAccount - 4m delete - delete ok - + | ^ cert-manager-cainjector Deployment 2/2 t 4m delete - delete ok - + | ^ cert-manager-cainjector ServiceAccount - 4m delete - delete ok - + | ^ cert-manager-webhook Deployment 2/2 t 4m delete - delete ok - + | ^ cert-manager-webhook Service - 4m delete - delete ok - + | ^ cert-manager-webhook ServiceAccount - 4m delete - delete ok - + | ^ cert-manager-webhook:dynamic-serving Role - 4m delete - delete ok - + | ^ cert-manager-webhook:dynamic-serving RoleBinding - 4m delete - delete ok - + | kube-system cert-manager-cainjector:leaderelection RoleBinding - 4m update - reconcile ok - + | ^ cert-manager:leaderelection RoleBinding - 4m update - reconcile ok - + | Op: 11 create, 11 delete, 20 update, 0 noop, 0 exists + | Wait to: 31 reconcile, 11 delete, 0 noop + | 9:40:25AM: ---- applying 20 changes [0/42 done] ---- + | 9:40:25AM: delete serviceaccount/cert-manager (v1) namespace: cert-manager + | 9:40:25AM: delete deployment/cert-manager-cainjector (apps/v1) namespace: cert-manager + | 9:40:25AM: delete deployment/cert-manager-webhook (apps/v1) namespace: cert-manager + | 9:40:25AM: delete role/cert-manager-webhook:dynamic-serving (rbac.authorization.k8s.io/v1) namespace: cert-manager + | 9:40:25AM: delete rolebinding/cert-manager-webhook:dynamic-serving (rbac.authorization.k8s.io/v1) namespace: cert-manager + | 9:40:25AM: delete serviceaccount/cert-manager-cainjector (v1) namespace: cert-manager + | 9:40:25AM: delete deployment/cert-manager (apps/v1) namespace: cert-manager + | 9:40:25AM: delete serviceaccount/cert-manager-webhook (v1) namespace: cert-manager + | 9:40:25AM: delete service/cert-manager-webhook (v1) namespace: cert-manager + | 9:40:25AM: delete namespace/cert-manager (v1) cluster + | 9:40:25AM: delete service/cert-manager (v1) namespace: cert-manager + | 9:40:26AM: update customresourcedefinition/certificaterequests.cert-manager.io (apiextensions.k8s.io/v1) cluster + # .... + # . + # . + # . + # .... + | 9:40:37AM: ---- waiting on 1 changes [41/42 done] ---- + | 9:40:43AM: ok: reconcile deployment/cert-manager-webhook (apps/v1) namespace: cert-man-install + | 9:40:43AM: ---- applying complete [42/42 done] ---- + | 9:40:43AM: ---- waiting complete [42/42 done] ---- + | Succeeded +3:10:43PM: App reconciled + + +Succeeded +``` +(_deploy output truncated_) + +## Deleting an installation +`kctrl` can be used to delete an installation and associated resources created with it. `kctrl` waits for them to be deleted from the cluster. +```bash +$ kctrl package installed delete -i cert-man + +Delete package install 'cert-man' from namespace 'default' + +Continue? [yN]: y + +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +3:12:41PM: Deleting package install 'cert-man' from namespace 'default' +3:12:41PM: Waiting for deletion of package install 'cert-man' from namespace 'default' +3:12:42PM: Delete started (1s ago) +3:12:44PM: Deleting + | Target cluster 'https://10.92.0.1:443' (nodes: gke-cluster-sm-default-pool-28d3ddcd-gjqs, 2+) + | Changes + | Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri + | (cluster) cert-man-install Namespace - 2m delete - delete ok - + | ^ cert-manager-cainjector ClusterRole - 6m delete - delete ok - + | ^ cert-manager-cainjector ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-approve:cert-manager-io ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-approve:cert-manager-io ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-certificates ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-certificates ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-certificatesigningrequests ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-certificatesigningrequests ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-challenges ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-challenges ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-clusterissuers ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-clusterissuers ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-ingress-shim ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-ingress-shim ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-issuers ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-issuers ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-controller-orders ClusterRole - 6m delete - delete ok - + | ^ cert-manager-controller-orders ClusterRoleBinding - 6m delete - delete ok - + | ^ cert-manager-edit ClusterRole - 6m delete - delete ok - + | ^ cert-manager-view ClusterRole - 6m delete - delete ok - + | ^ cert-manager-webhook MutatingWebhookConfiguration - 6m delete - delete ok - + | ^ cert-manager-webhook ValidatingWebhookConfiguration - 6m delete - delete ok - + | ^ cert-manager-webhook:subjectaccessreviews ClusterRole - 6m delete - delete ok - + | ^ cert-manager-webhook:subjectaccessreviews ClusterRoleBinding - 6m delete - delete ok - + | ^ certificaterequests.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | ^ certificates.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | ^ challenges.acme.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | ^ clusterissuers.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | ^ issuers.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | ^ orders.acme.cert-manager.io CustomResourceDefinition 2/2 t 6m delete - delete ok - + | cert-man-install cert-manager Deployment 2/2 t 2m delete - delete ok - + | ^ cert-manager Endpoints - 2m - - delete ok - + | ^ cert-manager Service - 2m delete - delete ok - + | ^ cert-manager ServiceAccount - 2m delete - delete ok - + | ^ cert-manager-7b9d7974f ReplicaSet - 2m - - delete ok - + | ^ cert-manager-7b9d7974f-s47vm Pod 4/4 t 2m - - delete ok - + | ^ cert-manager-cainjector Deployment 2/2 t 2m delete - delete ok - + | ^ cert-manager-cainjector ServiceAccount - 2m delete - delete ok - + | ^ cert-manager-cainjector-6d9d6b7c5b ReplicaSet - 2m - - delete ok - + | ^ cert-manager-cainjector-6d9d6b7c5b-sgjlc Pod 4/4 t 2m - - delete ok - + | ^ cert-manager-kp9sj EndpointSlice - 2m - - delete ok - + | ^ cert-manager-webhook Deployment 2/2 t 2m delete - delete ok - + | ^ cert-manager-webhook Endpoints - 2m - - delete ok - + | ^ cert-manager-webhook Service - 2m delete - delete ok - + | ^ cert-manager-webhook ServiceAccount - 2m delete - delete ok - + | ^ cert-manager-webhook-56676b8df7 ReplicaSet - 2m - - delete ok - + | ^ cert-manager-webhook-56676b8df7-hl62t Pod 4/4 t 2m - - delete ok - + | ^ cert-manager-webhook-5r7jg EndpointSlice - 2m - - delete ok - + | ^ cert-manager-webhook:dynamic-serving Role - 2m delete - delete ok - + | ^ cert-manager-webhook:dynamic-serving RoleBinding - 2m delete - delete ok - + | kube-system cert-manager-cainjector:leaderelection Role - 6m delete - delete ok - + | ^ cert-manager-cainjector:leaderelection RoleBinding - 6m delete - delete ok - + | ^ cert-manager:leaderelection Role - 6m delete - delete ok - + | ^ cert-manager:leaderelection RoleBinding - 6m delete - delete ok - + | Op: 0 create, 45 delete, 0 update, 10 noop, 0 exists + | Wait to: 0 reconcile, 55 delete, 0 noop + | 9:42:47AM: ---- applying 16 changes [0/55 done] ---- + | 9:42:47AM: noop pod/cert-manager-7b9d7974f-s47vm (v1) namespace: cert-man-install + | 9:42:47AM: noop endpointslice/cert-manager-webhook-5r7jg (discovery.k8s.io/v1) namespace: cert-man-install + | 9:42:47AM: noop endpointslice/cert-manager-kp9sj (discovery.k8s.io/v1) namespace: cert-man-install + | 9:42:47AM: noop endpoints/cert-manager (v1) namespace: cert-man-install + | 9:42:47AM: noop replicaset/cert-manager-cainjector-6d9d6b7c5b (apps/v1) namespace: cert-man-install + | 9:42:47AM: noop replicaset/cert-manager-webhook-56676b8df7 (apps/v1) namespace: cert-man-install + | 9:42:47AM: noop replicaset/cert-manager-7b9d7974f (apps/v1) namespace: cert-man-install + | 9:42:47AM: delete customresourcedefinition/orders.acme.cert-manager.io (apiextensions.k8s.io/v1) cluster + | 9:42:47AM: noop endpoints/cert-manager-webhook (v1) namespace: cert-man-install + | 9:42:47AM: noop pod/cert-manager-cainjector-6d9d6b7c5b-sgjlc (v1) namespace: cert-man-install + | 9:42:47AM: delete customresourcedefinition/certificaterequests.cert-manager.io (apiextensions.k8s.io/v1) cluster + | 9:42:47AM: noop pod/cert-manager-webhook-56676b8df7-hl62t (v1) namespace: cert-man-install + | 9:42:47AM: delete customresourcedefinition/clusterissuers.cert-manager.io (apiextensions.k8s.io/v1) cluster + | 9:42:47AM: delete customresourcedefinition/issuers.cert-manager.io (apiextensions.k8s.io/v1) cluster + | 9:42:47AM: delete customresourcedefinition/certificates.cert-manager.io (apiextensions.k8s.io/v1) cluster + | 9:42:48AM: delete customresourcedefinition/challenges.acme.cert-manager.io (apiextensions.k8s.io/v1) cluster + # .... + # . + # . + # . + # .... +3:13:03PM: App 'cert-man' in namespace 'default' deleted +3:13:03PM: packageinstall/cert-man (packaging.carvel.dev/v1alpha1) namespace: default: DeletionSucceeded +3:13:03PM: Deleting 'Secret': cert-man-default-values +3:13:04PM: Deleting 'ServiceAccount': cert-man-default-sa +3:13:04PM: Deleting 'ClusterRole': cert-man-default-cluster-role +3:13:04PM: Deleting 'ClusterRoleBinding': cert-man-default-cluster-rolebinding +Succeeded +``` +(_delete output truncated_) + +## Deleting an added repository +`kctrl` deletes the PackageRepository and waits till it is deleted from the cluster. + +```bash +$ kctrl package repo delete -r tce +Target cluster 'https://127.0.0.1:56457' (nodes: minikube) + +Deleting package repository 'tce' in namespace 'default' + +Continue? [yN]: y + +Waiting for deletion to be completed... + +2:21:58PM: packagerepository/tce (packaging.carvel.dev/v1alpha1) namespace: default: Deleting +2:22:02PM: packagerepository/tce (packaging.carvel.dev/v1alpha1) namespace: default: DeletionSucceeded + +Succeeded +``` + +## Congratulations! +You can now get up and running with published repositories and manage packages faster using `kctrl`. diff --git a/site/content/kapp-controller/docs/v0.49.x/management-command.md b/site/content/kapp-controller/docs/v0.49.x/management-command.md new file mode 100644 index 000000000..823fae7f2 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/management-command.md @@ -0,0 +1,304 @@ +--- +aliases: [/kapp-controller/docs/latest/management-command] +title: Management Commands Reference +--- + +## Package +Package commands provides options to interact with package repositories, available packages and package installs. + +### Available packages +The `package available` group of commands can be used to get or list packages available in a namespace or all namespaces. + +#### Listing available packages +The `package available list` command can be used to get a list of packages available in one or all namespaces. +```bash +$ kctrl package available list +``` +A package can also be passed to get different available versions of the package. +```bash +$ kctrl package available list -p pkg.test.carvel.dev +``` +Supported flags: +- `-A`, `--all-namespaces` _string_, List available packages in all namespaces +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `-p`, `--package`, _string_, List all available versions of package +- `--summary`, _boolean_, Show summarized list of packages (default true) +- `--wide`, _boolean_, Show additional info + +#### Getting details of available packages +The `package available get` command can be used to get details of available packages or specific versions of a package. +```bash +$ kctrl package available get -p pkg.test.carvel.dev +# or... +$ kctrl package available get -p pkg.test.carvel.dev/1.0.0 +``` +The `values-schema` flag can be used to get the available values schema for a specific version of the package. +```bash +$ kctrl package available get -p pkg.test.carvel.dev/1.0.0 --values-schema +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `-p`, `--package`, _string_, List all available versions of package +- `--values-schema`, _string_, Values schema of the package (optional) + +### Installed Packages +The `package installed` group of commands can be used to view, create and update installed packages. + +#### Installing a package +The `package installed create` command can be used to create a new installation. The `package install` command is a sugared alternative for the same. +```bash +$ kctrl package installed create --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4 +# or... +$ kctrl package install --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4 +``` +A values file can also be passed while running this command. +```bash +$ kctrl package install --package-install cert-man --package cert-manager.community.tanzu.vmware.com --version 1.5.4 --values-file values.yml +``` +Supported flags: +- `-p`, `--package` _string_, name of available package consumed by the installation +- `--version` _string_, version of package that the package install should consume +- `--service-account-name` _string_, Name of an existing service account used to install underlying package contents, optional +- `--namespace` _string_, Specified namespace for package installation +- `--dangerous-allow-use-of-shared-namespace` _boolean_, Allow installation of packages in shared namespaces (`default`, `kube-public`) +- `--wait` _boolean_, Wait for reconciliation to complete (default `true`) +- `--wait-check-interval` _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout` _duration_, Maximum amount of time to wait in wait phase (default 30m0s) +- `--values` _boolean_, Add or keep values supplied to package install, optional (default `true`) +- `--values-file` _string_, The path to the configuration values file, optional +- `--ytt-overlay-file` _string_, Path to ytt overlay file (can also be a directory) +- `--ytt-overlays` _boolean_, Add or keep ytt overlays (default true) + +#### Updating an installed package +The `package installed update` command can be used to update an existing installation to a newer version or with a new values file. +To update to a newer version: +```bash +$ kctrl package installed update --package-install cert-man --version 1.6.1 +``` +To update to a newer values file: +```bash +$ kctrl package installed update --package-install cert-man --values-file updated-values.yml +``` +Supported flags: +- `--version` _string_, version of package that the package install should consume +- `--install`_boolean_, Install package if the installed package does not exist (default `false`) +- `--namespace` _string_, Specified namespace to find package installation to be updated in +- `--wait` _boolean_, Wait for reconciliation to complete (default `true`) +- `--wait-check-interval` _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout` _duration_, Maximum amount of time to wait in wait phase (default 30m0s) +- `--values` _boolean_, Add or keep values supplied to package install, optional (default `true`) +- `--values-file` _string_, The path to the configuration values file, optional +- `--ytt-overlay-file` _string_, Path to ytt overlay file (can also be a directory) +- `--ytt-overlays` _boolean_, Add or keep ytt overlays (default true) + +#### Listing package installs +The `package installed list` command can be used to list all installed packages. +```bash +$ kctrl package installed list +``` +Supported flags: +- `-n`, `--namespace` _string_, Specify namespace where `kctrl` should look for package installs +- `-A`, `--all-namespaces` _boolean_, List installed packages in all namespaces + +#### Getting details for installed package +The `package installed get` command can be used to fetch information for an installed package. +```bash +$ kctrl package installed get --package-install cert-man +``` +This can also be used to view the values being used with the package install. +```bash +$ kctrl package installed get --package-install cert-man --values +``` +Or to download the values file consumed by the installation. +```bash +$ kctrl package installed get --package-install cert-man --values-file-output output-values.yml +``` + +#### Pausing reconciliation for a package install +The `kctrl package installed pause` command can be used to pause reconciliation for a package installation. +```bash +$ kctrl package installed pause -i cert-man +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +#### Triggering reconciliation for package installation +The `kctrl package installed kick` command can be used to trigger reconciliation for an installed package. +```bash +$ kctrl package installed kick -i cert-man +``` +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--wait` _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval` _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout` _duration_, Maximum amount of time to wait in wait phase (default 5m0s) + +#### Observing status of app created by package installation +The `kctrl package installed status` command can be used to observe the status of the app created by the package installation with information from the last reconciliation. The command tails and streams app status updates till the app reconciles or fails if the command is run while the installation is reconciling. +```bash +$ kctrl package installed status -i cert-man +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +#### Deleting package installatiions +The `package installed delete` command can be used to delete package installations and resources created along with it by `kctrl`. +```bash +$ kctrl package installed delete -i cert-man +``` +Created resources other than the `PackageInstall` resource might include Secrets, Service Accounts, Cluster Roles and Cluster Role Bindings which are cleaned up if they were created while installing the package using the CLI. + +#### Shared flags +- `-i`, `--package-install` _string_, assigned name for a package installation + +#### Created resources +If a service account name is not specified using a flag while creating a package installation, `kctrl` creates a service account, cluster role and cluster role binding to be used by the package install. + +If values are specified using a values file, `kctrl` creates a secret using the values that can be consumed by the package installation. +(See [Installing a Package](packaging-tutorial.md#installing-a-package) for information on how `PackageInstall` CRs consume secrets) + +These resources are tracked by using the `packaging.carvel.dev/package-...` annotations and similar annotations are added to the resources themselves to assert ownership of the resources, so that they can be safely deleted while deleting the package installation. +(See [Security Model](security-model.md) for information on how `PackageInstall` CRs use service accounts) + +## Package Repositories +The `package repository` group of commands can be used to view, create and delete packages repositories. + +### Adding package repositories +The `package repository add` command can be used to add a package repository to a namespace. +```bash +$ kctrl package repository add -r test-repo --url index.docker.io/k8slt/kc-e2e-test-repo:latest +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--dangerous-allow-use-of-shared-namespace` _boolean_, Allow addition of package repositories in shared namespaces (`default`, `kube-public`) +- `-r`, `--repository`, _string_, Set package repository name (required) +- `--url`, _string_, OCI registry url for package repository bundle (required) +- `--wait`, _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval`, _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout`, _duration_, Maximum amount of time to wait in wait phase (default 5m0s) + +### Updating existing package repositories +The `package repository update` command can be used to update an existing repository. +```bash +$ kctrl package repository update -r test-repo --url index.docker.io/k8slt/kc-e2e-test-repo-2:latest +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `-r`, `--repository`, _string_, Set package repository name (required) +- `--url`, _string_, OCI registry url for package repository bundle (required) +- `--wait`, _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval`, _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout`, _duration_, Maximum amount of time to wait in wait phase (default 5m0s) + +### Listing package repositories +The `package repository list` command can be used to list existing repositories. +```bash +$ kctrl package repository list +``` +Supported flags: +- `-A`, `--all-namespaces` _string_, List available packages in all namespaces +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +### Getting details for package repositories +The `package repository get` command can be used to get details of an existing package repository. +```bash +$ kctrl package repository get -r test-repo +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `-r`, `--repository` _string_, Set package repository name (required) + +### Deleting package repositories +The `package repository delete` command can be used to delete a package repository. +```bash +$ kctrl package repository delete -r test-repo +``` +Supported flags: +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `-r`, `--repository` _string_, Set package repository name (required) +- `--wait`, _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval`, _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout`, _duration_, Maximum amount of time to wait in wait phase (default 5m0s) +## App +The app commands let users observe and interact with Apps conveniently. + +### Listing apps +The `kctrl app list` command can be used to list apps. +```bash +$ kctrl app list +``` +Supported flags: +- `-A`, `--all-namespaces` _boolean_, List apps in all namespaces +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +### Geting details for an app +The `kctrl app get` command can be used to get details for an app. +```bash +$ kctrl app get -a simple-app +``` +Supported flags: +- `-a`, `--app` _string_, Set app name (required) +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +### Observe status of an app +The `kctrl app status` command allows users to observe the status of the app with information from the last reconciliation. The command tails and streams app status updates till the app reconciles or fails if the command is run while the app is reconciling. +```bash +$ kctrl app status -a simple-app +``` +Supported flags: +- `-a`, `--app` _string_, Set app name (required) +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--ignore-not-exists` _boolean_, Keep following app if it does not exist + +### Pause reconciliation of an app +The `kctrl app pause` command allows pausing of periodic recopnciliation of an app. +```bash +$ kctrl app pause -a simple-app +``` +Supported flags: +- `-a`, `--app` _string_, Set app name (required) +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) + +### Trigger reconciliation of an app +The `kctrl app kick` command can be used to trigger reconciliation of a command and tail the app status till it reconciles if desired. It can also be used to restart periodic reconciliation for a paused app. +```bash +$ kctrl app kick -a simple-app +``` +Supported flags: +- `-a`, `--app` _string_, Set app name (required) +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--wait` _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval` _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout` _duration_, Maximum amount of time to wait in wait phase (default 5m0s) + +### Delete an app +The `kctrl app delete` command can be used to delete an app. +```bash +$ kctrl app delete -a simple-app +``` +Supported flags: +- `-a`, `--app` _string_, Set app name (required) +- `-n`, `--namespace` _string_, Specified namespace ($KCTRL_NAMESPACE or default from kubeconfig) +- `--noop` _boolean_, Ignore resources created by the app and delete the custom resource itself +- `--wait` _boolean_, Wait for reconciliation to complete (default true) +- `--wait-check-interval` _duration_, Amount of time to sleep between checks while waiting (default 1s) +- `--wait-timeout` _duration_, Maximum amount of time to wait in wait phase (default 5m0s) + +## Global Flags +- `--color` _boolean_, Set color output (default true) +- `--column` _string_, Filter to show only given columns +- `--debug` _boolean_, Include debug output +- `-h`, `--help` _boolean_, help for kctrl +- `--json` _boolean_, Output as JSON +- `--kube-api-burst`, _int_, Set Kubernetes API client burst limit (default 1000) +- `--kube-api-qps` _float32_, Set Kubernetes API client QPS limit (default 1000) +- `--kubeconfig` _string_, Path to the kubeconfig file ($KCTRL_KUBECONFIG), +- `--kubeconfig-context`_string_, Kubeconfig context override ($KCTRL_KUBECONFIG_CONTEXT) +- `--kubeconfig-yaml` _string_, Kubeconfig contents as YAML ($KCTRL_KUBECONFIG_YAML) +- `--tty` _boolean_, Force TTY-like output (default true) +- `-v`, `--version` _boolean_, version for kctrl +- `-y`, `--yes`, _boolean_, Assumes yes for any prompt + +## Environment variables + +Environment Variables: + - `FORCE_COLOR`: set to `1` to force colors to the printed. Useful to preserve colors when piping output such as in `kctrl app list --tty --all-namespaces |& less -R` diff --git a/site/content/kapp-controller/docs/v0.49.x/oss-packages.md b/site/content/kapp-controller/docs/v0.49.x/oss-packages.md new file mode 100644 index 000000000..1e323714f --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/oss-packages.md @@ -0,0 +1,24 @@ +--- +aliases: [/kapp-controller/docs/latest/oss-packages] +title: OSS Carvel Packages +--- + +This page provides a list of Carvel Packages and Package Repositories that are available to open source users. + +Do you have a Package or Package Repository you'd like to add to this list? Please make a PR with details to our [docs](https://github.com/carvel-dev/carvel/blob/develop/site/content/kapp-controller/docs/develop/oss-packages.md). + +## Tanzu Community Edition +Tanzu Community Edition provides several open source [Carvel Packages](https://tanzucommunityedition.io/packages/). These are actively contributed to and maintained by contributors to Tanzu Community Edition. A list of the Package CRs can be found [here](https://github.com/vmware-tanzu/community-edition/tree/main/addons/packages). You can add the Package Repository to your cluster by creating a PackageRepository CR. + +```yaml +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + name: tce-repo +spec: + fetch: + imgpkgBundle: + # Check out the latest version from Tanzu Community Edition docs + image: projects.registry.vmware.com/tce/main:0.9.1 +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/package-consumer-concepts.md b/site/content/kapp-controller/docs/v0.49.x/package-consumer-concepts.md new file mode 100644 index 000000000..f87fc1e12 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/package-consumer-concepts.md @@ -0,0 +1,171 @@ +--- +aliases: [/kapp-controller/docs/latest/package-consumer-concepts] +title: Concepts for Package Consumers +--- + +## Resource Lineage +All resources created by a PackageRepository (PKGR) are decorated with an annotation +indicating their parent: `packaging.carvel.dev/package-repository-ref: +/` + +## Namespacing + +### Overview + +In the packaging APIs, all the CRs are namespaced, which can create a lot of +duplication when wanting to share packages across the cluster. To account for +this, kapp-controller accepts a flag `-packaging-global-namespace`, which +configures kapp-controller to treat the provided namespace as a global namespace +for packaging resources. This means any Package and PackageMetadata CRs within +that namespace will be included in all other namespaces on the cluster, without +duplicating them. This does not apply to PackageRepositories or PackageInstalls. + +### Collisions + +When there is a conflict, the locally namespaced resources will take precedence +over the global ones. A conflict for Packages is defined as having the same +`spec.refName` and `spec.version`, while for PackageMetadatas it is defined as +having the same `metadata.name`. For example, if there is a globally available +PackageMetadata created from the following YAML: + +```yaml +--- +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + name: simple-app.corp.com + namespace: +spec: + categories: + - demo + displayName: Simple App + longDescription: Simple app consisting of a k8s deployment and service + shortDescription: Simple app for demoing +``` + +and then a new locally available PackageMetadata is created from this YAML, + +```yaml +--- +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + name: simple-app.corp.com + namespace: +spec: + categories: + - demo + displayName: Simple App Override + longDescription: My locally available version of the Simple App package + shortDescription: Simple App with some edits +``` + +a user listing the PackageMetadatas will see the second CR, and not the first. + +### Annotations + +For client discoverability, the namespace should also be present as an +annotation on the PackageRepository CRD under the +`packaging.carvel.dev/global-namespace`. Kapp controller's release +YAML comes preconfigured with this annotation. + +To exclude global packages from a namespace, add the +annotation `packaging.carvel.dev/exclude-global-packages` to +that namespace. + +## Using PackageInstall's Version Selection + +The following sections cover aspects of how to approach version selection when using PackageInstalls. + +### Constraints + +PackageInstalls offer a property called `constraints` under +`.spec.packageRef.versionSelection`. This `constraints` property can be +used to select a specific version of a Package CR to install or include a set of +conditions to pick a version. This `constraints` property is based on semver +ranges and more details on conditions that can be included with `constraints` +can be found [here](https://github.com/k14s/semver#ranges). + +To select a specific version of a Package CR to use with a PackageInstall, the +full version (i.e. `.spec.version` from a Package CR) can be included in the +`constraints` property, such as what is shown below: + +```yaml +packageRef: + refName: fluent-bit.vmware.com + versionSelection: + constraints: "1.5.3" +``` + +The example above will result in version 1.5.3 of the Package being installed. + +An example of using a condition to select a Package CR with `constraints` is shown below: + +```yaml +packageRef: + refName: fluent-bit.vmware.com + versionSelection: + constraints: ">1.5.3" +``` + +The above constraint will result in any version greater than `1.5.3` of the +Package being installed. It will also automatically update to the latest +versions of the Package as they become available on the cluster. + +### Prereleases + +When creating a PackageInstall, by default prereleases are not included by +kapp-controller when considering which versions of a Package CR to install. To +include prereleases when creating a PackageInstall, the following can be +added to the spec: + +```yaml +versionSelection: + constraints: "3.0.0-rc.1" + prereleases: {} +``` + +Specifying `prereleases: {}` will make kapp-controller consider all available +prereleases when seeing if a Package CR is available to be installed. + +To filter by releases containing certain substrings, there is an `identifiers` +property under `prereleases` that can be used to only include certain +prereleases that contain the identifier, such as what is shown below: + +```yaml +versionSelection: + constraints: "3.0.0" + prereleases: + identifiers: [rc] +``` + +Multiple identifiers can be specified to include multiple types of pre-releases +(e.g. `identifiers: [rc, beta]`). + +### Downgrading + +In v0.25.0+ of kapp-controller, PackageInstalls feature an annotation to allow +PackageInstalls to be downgraded to previous versions of a Package. By default, +kapp-controller does not allow downgrading to a previous version of a Package to +protect against certain scenarios (e.g. the latest version of a Package being removed +resulting in a unintended reconciliation where the PackageInstall picks up a lower +Package version that is now the latest version). + +If downgrading to a previous version is desired, adding the annotation +`packaging.carvel.dev/downgradable: ""` to a PackageInstall will allow for +explicit or automated ways of downgrading the PackageInstall to a lower version. + +```yaml +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: pkg-demo + annotations: + packaging.carvel.dev/downgradable: "" +spec: + packageRef: + refName: simple-app.corp.com + versionSelection: + constraints: >=1.0.0 +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/package-install-extensions.md b/site/content/kapp-controller/docs/v0.49.x/package-install-extensions.md new file mode 100644 index 000000000..56d7cf833 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/package-install-extensions.md @@ -0,0 +1,65 @@ +--- +aliases: [/kapp-controller/docs/latest/package-install-extensions] +title: Overlays with PackageInstall +--- + +PackageInstalls expose the ability to customize package installation using +annotations recognized by kapp-controller. + +## Adding Paths to YTT (overlays) + +Since it is impossible for package configuration and exposed data values to meet +every consumer's use case, we have added an annotation which enables +consumers to extend the package configuration with custom ytt paths. The most +likely use case for this is providing overlays to tweak configuration that is +not exposed via data values, but it can be used to provide any kind of ytt file. + +The extension annotation is called `ext.packaging.carvel.dev/ytt-paths-from-secret-name` +and can be suffixed with a `.X`, where X is some number, to allow for specifying +it multiple times. For example, + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: fluent-bit + namespace: my-ns + annotations: + ext.packaging.carvel.dev/ytt-paths-from-secret-name.0: my-overlay-secret +spec: + serviceAccountName: fluent-bit-sa + packageRef: + refName: fluent-bit.vmware.com + versionSelection: + constraints: ">v1.5.3" + prereleases: {} + values: + - secretRef: + name: fluent-bit-values + +``` + +will include the overlay stored in the secret `my-overlay-secret` during the +templating steps of the package. This will allow users to further customize a +package installation in advanced cases. + +Example secret resource with a ytt overlay that adds a label to all Namespaces added by this package: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-overlay-secret + namespace: my-ns +stringData: + add-ns-label.yml: | + #@ load("@ytt:overlay", "overlay") + #@overlay/match by=overlay.subset({"kind":"Namespace"}),expects="1+" + --- + metadata: + #@overlay/match missing_ok=True + labels: + #@overlay/match missing_ok=True + custom-lbl: custom-lbl-value +``` + diff --git a/site/content/kapp-controller/docs/v0.49.x/packaging-artifact-formats.md b/site/content/kapp-controller/docs/v0.49.x/packaging-artifact-formats.md new file mode 100644 index 000000000..f7bc5003b --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/packaging-artifact-formats.md @@ -0,0 +1,66 @@ +--- +aliases: [/kapp-controller/docs/latest/packaging-artifact-formats] +title: Artifact formats +--- + +## Package Contents Bundle + +A package bundle is an [imgpkg bundle](/imgpkg/docs/latest/resources/#bundle) that +holds package contents such as Kubernetes YAML configuration, ytt templates, +Helm templates, etc. + +Filesystem structure used for package bundle creation: + +```bash +my-pkg/ +└── .imgpkg/ + └── images.yml +└── config/ + └── deployment.yml + └── service.yml + └── ingress.yml +``` + +- `.imgpkg/` directory (required) is a standard directory for any imgpkg bundle + - `images.yml` file (required) contains container image refs used by configuration (typically generated with `kbld`) +- `config/` directory (optional) should contain arbitrary package contents such as Kubernetes YAML configuration, ytt templates, Helm templates, etc. + - Recommendations: + - Group Kubernetes configuration into a single directory (`config/` is our + recommendation for the name) so that it could be easily referenced in the + Package CR (e.g. using `ytt` template step against single directory) + +See [Creating a package](packaging-tutorial.md#creating-a-package) for example creation steps. + +## Package Repository Bundle + +A package repository bundle is an [imgpkg bundle](/imgpkg/docs/latest/resources/#bundle) that holds PackageMetadata and Package CRs. + +Filesystem structure used for package repository bundle creation: + +```bash +my-pkg-repo/ +└── .imgpkg/ + └── images.yml +└── packages/ + └── simple-app.corp.com + └── metadata.yml + └── 1.0.0.yml + └── 1.2.0.yml +``` + +- `.imgpkg/` directory (required) is a standard directory for any imgpkg bundle + - `images.yml` file (required) contains package bundle refs used by Package CRs (typically generated with `kbld`) +- `packages/` directory (required) should contain zero or more YAML files describing available packages + - Each file may contain one or more PackageMetadata or Package CRs (using standard YAML document separator) + - Files may be grouped in directories or kept flat + - File names do not have any special meaning + - Recommendations: + - Separate packages in to directories with the package name + - Keep each PackageMetadata CR in a `metadata.yml` file in the package's + directory. + - Keep each versioned package in a file with the version name inside the package's + directory + - Always have a PackageMetadata CR if you have Package CRs + +See [Creating a Package Repository](packaging-tutorial.md#creating-a-package-repository) for example creation steps. + diff --git a/site/content/kapp-controller/docs/v0.49.x/packaging-gitops.md b/site/content/kapp-controller/docs/v0.49.x/packaging-gitops.md new file mode 100644 index 000000000..538c3f97c --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/packaging-gitops.md @@ -0,0 +1,250 @@ +--- +aliases: [/kapp-controller/docs/latest/packaging-gitops] +title: Package Management with GitOps +--- + +As you begin working with the [package management APIs](packaging.md) for kapp-controller, you may +be wondering how to use kapp-controller's gitops features to manage kapp-controller packages. This +section will cover an example gitops workflow using kapp-controller's package management resources. + +### GitOps Scenario + +An example gitops scenario with kapp-controller could be that a user wants to install a subset of +[Packages](packaging.md#package) from a [PackageRepository](packaging.md#package-repository). The +user wants to define which PackageRepository and Packages to install by defining these resources in +a git repository. With this approach, a user can manage resources in a declarative fashion and track +the history of changes to a Kubernetes cluster. + +After making changes to the main branch of the git repository, the user expects that kapp-controller +will sync these resources to the Kubernetes cluster where kapp-controller is installed. The user also +expects kapp-controller to sync these resources based on updates (e.g. PackageRepository or Package version upgrades) +to the main branch of the git repository. + +### Package Management GitOps Example + +To start, a user should already have kapp-controller installed on a Kubernetes cluster and have +a git repository available. + +First, a user can start by defining an [App custom resource](app-overview.md) like below. **NOTE:** +A user will also need to create a serviceaccount with associated RBAC permissions for the App to use. + +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: pkg-gitops-example + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-rule.create-order: "upsert after upserting rbac" + kapp.k14s.io/change-rule.delete-order: "delete before deleting rbac" +spec: + serviceAccountName: pkg-gitops-app-sa + fetch: + - git: + url: https://github.com/user/my-pkg-gitops-repo + ref: origin/main + subPath: packaging + + template: + - ytt: {} + + deploy: + - kapp: {} +``` + +The App will be pointed at the git repository branch where kapp-controller resources +(e.g. PackageRepository and Packages) will be defined. Read more on setting the App +up with a private git repository [here](app-overview.md#git-authentication). + +By default, an App custom resource will sync the cluster with its fetch source every +30 seconds to prevent the cluster state from drifting from its source of truth, which +is a git repository in this case. + +**NOTE:** The App should be managed separately from any additional kapp-controller resources +stored in a git repository for a gitops workflow. One potential example could be storing the +App definition and associated RBAC in the same git repository it is fetching from and have a +CI/CD process redeploy only the App when a change is made to the App itself versus other resourcees +in the repository. For simplicity in the example above, the user is deploying the App with +`kubectl` or `kapp` manually. + +After creating the App, a user can define a PackageRepository like below: + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + name: tce-repository + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-group: "tce-repo" +spec: + fetch: + imgpkgBundle: + image: projects.registry.vmware.com/tce/main:0.10.0 +``` + +This PackageRepository will install the [Tanzu Community Edition](https://tanzucommunityedition.io/) +packages on the cluster where kapp-controller is installed. + +Next, a user can pick which Packages to install on the cluster by defining [PackageInstall](packaging.md#packageinstall) +resources. The Tanzu Community Edition repository offers several Packages that are documented +[here](https://tanzucommunityedition.io/docs/latest/package-management/). + +For our gitops example, let's say the user is installing [cert-manager](https://cert-manager.io/docs/) +and [contour](https://projectcontour.io/) on the cluster. To do this, a user could define the following +PackageInstall along with associated RBAC. **NOTE:** The example below gives cluster admin permissions +to the serviceaccount. Make sure to assess appropriate RBAC needed for your specific PackageInstalls. + +RBAC: + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: pkg-gitops-pkgi-sa + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-group: "packageinstall-setup" +--- +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: cluster-admin-cluster-role + annotations: + kapp.k14s.io/change-group: "packageinstall-setup" +rules: +- apiGroups: ["*"] + resources: ["*"] + verbs: ["*"] +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: cluster-admin-cluster-role-binding + annotations: + kapp.k14s.io/change-group: "packageinstall-setup" +subjects: +- kind: ServiceAccount + name: pkg-gitops-pkgi-sa + namespace: pkg-gitops +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin-cluster-role +``` + +PackageInstalls: + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: cert-manager + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-group: "cert-manager" + kapp.k14s.io/change-rule.create-order: "upsert after upserting packageinstall-setup" + kapp.k14s.io/change-rule.delete-order: "delete before deleting packageinstall-setup" +spec: + serviceAccountName: pkg-gitops-pkgi-sa + packageRef: + refName: cert-manager.community.tanzu.vmware.com + versionSelection: + constraints: 1.5.4 +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: contour + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-rule.create-order: "upsert after upserting cert-manager" + kapp.k14s.io/change-rule.delete-order: "delete before deleting packageinstall-setup" +spec: + serviceAccountName: pkg-gitops-pkgi-sa + packageRef: + refName: contour.community.tanzu.vmware.com + versionSelection: + constraints: 1.17.1 +``` + +The structure of the git repository might look like the example below. In this structure, +the App definition is stored under a folder called app. The App definition above uses a +property called `subPath` to tell kapp-controller to only fetch and sync resources found +under the packaging folder of this git repository. The packaging folder will contain the +PackageRepository, PackageInstalls, and associated RBAC. + +``` +. +├── app +│ ├── app.yml +│ ├── rbac.yml +└── packaging + ├── packageinstalls.yml + ├── rbac.yml + └── repo.yml +``` + +The user can then check in and commit the App, PackageRepository, RBAC, and PackageInstalls to +the main branch of the git repository and push up the resources. + +To deploy the PackageRepository, RBAC, and PackageInstalls, create the App by running the following +commands: + +```shell +# Use kubectl +kubectl apply -f app/ +# Use kapp +kapp deploy -a pkg-gitops -f app/ +``` + +Once committed, the App custom resource created will create the PackageRepository, RBAC, and PackageInstalls +on the cluster. + +The user can view the status of the deployment through the App as well by running the following: + +```shell +kubectl get apps/pkg-gitops-example -n pkg-gitops +``` + +When the App's status is `Reconcile succeeded`, cert-manager and contour should be installed on the +cluster. This can be verified by running the following command: + +```shell +kubectl get pkgi -n pkg-gitops +``` + +### Making an Update + +When it's time to make an update to Packages installed on your cluster, a user can simply +open a pull request to the main branch of the git repositoy, make necessary changes in the +pull request review, and then merge when ready to introduce the change to the cluster. + +To expand on the example above, a user may want to upgrade contour to a later version (e.g. 1.17.2). +To do this, check out the git repository, edit the version used for the PackageInstall like below, +and then commit the change to the main branch. + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: contour + namespace: pkg-gitops + annotations: + kapp.k14s.io/change-rule.create-order: "upsert after upserting cert-manager" + kapp.k14s.io/change-rule.delete-order: "delete before deleting packageinstall-setup" +spec: + serviceAccountName: pkg-gitops-pkgi-sa + packageRef: + refName: contour.community.tanzu.vmware.com + versionSelection: + constraints: 1.17.2 +``` + +Once committed, the App custom resource will eventually sync in the changes. The change can be +verified by running the following command and checking in the kubectl output that the contour +PackageInstall is now using version 1.17.2: + +```shell +kubectl get pkgi/contour -n pkg-gitops +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/packaging-tutorial.md b/site/content/kapp-controller/docs/v0.49.x/packaging-tutorial.md new file mode 100644 index 000000000..816423c65 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/packaging-tutorial.md @@ -0,0 +1,478 @@ +--- +aliases: [/kapp-controller/docs/latest/packaging-tutorial] +title: "Tutorial: Create and Install a Package" +--- + +## Getting Started +Note the below steps are from a former katacoda tutorial (RIP katacoda) so your environment may differ slightly. + +Available kubernetes playground options include [killercoda](https://killercoda.com/playgrounds), +or local installations such as [minikube](https://minikube.sigs.k8s.io/docs/) or [kind](https://kind.sigs.k8s.io/). + +## Installing kapp-controller dependencies + +We'll be using [Carvel](https://carvel.dev/) tools throughout this tutorial, so first we'll install +[ytt](https://carvel.dev/ytt/), [kbld](https://carvel.dev/kbld/), +[kapp](https://carvel.dev/kapp/), [imgpkg](https://carvel.dev/imgpkg/), and [vendir](https://carvel.dev/vendir/). + +Install the tools with the scripts below: + +```bash +wget https://raw.githubusercontent.com/carvel-dev/kapp-controller/83fffcfe99a65031b4170813acf94f8d5058b346/hack/dependencies.yml +wget https://raw.githubusercontent.com/carvel-dev/kapp-controller/83fffcfe99a65031b4170813acf94f8d5058b346/hack/install-deps.sh +chmod a+x ./install-deps.sh +./install-deps.sh +``` + + +## Optional: explore kapp + +Before we install kapp-controller with [kapp](https://carvel.dev/kapp/), you may be interested in seeing +a different example of how kapp works. + +You can skip this step if you want to get straight to kapp-controller. + +First pull down the yaml for this example: + +```bash +wget https://raw.githubusercontent.com/carvel-dev/kapp/5886f388900ce66e4318220025ca77d16bfaa488/examples/jobs/cron-job.yml +``` + +Then deploy a CronJob to the Kubernetes cluster in this environment: + +```bash +kapp deploy -a hellocron -f cron-job.yml -y +``` + +Now take a look at the Kubernetes resources being managed by kapp: + +```bash +kapp ls +``` + +```bash +kapp inspect -a hellocron --tree +``` + +We scheduled our CronJob to output a hello message every minute, so if you're +patient you'll see new messages appended to the logs: + +```bash +kapp logs -f -a hellocron +``` + +When you're done watching the logs you can use control-c (`^C`) to quit. + +Because this was an optional interlude, we can use kapp to uninstall the CronJob before proceeding: +```bash +kapp delete -a hellocron -y +``` +## I believe I was promised kapp-controller? + +Use kapp to install kapp-controller (reconciliation may take a moment, which you +could use to read about [kubernetes controller reconciliation loops](https://kubernetes.io/docs/concepts/architecture/controller/)): + +```bash +kapp deploy -a kc -f https://github.com/carvel-dev/kapp-controller/releases/download/v0.32.0/release.yml -y +``` + +Gaze upon the splendor! + +```bash +kubectl get all -n kapp-controller +``` + +The kapp deployment is managing a replicaset which owns a service and a pod. The +pod is running kapp-controller, which is a kubernetes controller +running its own reconciliation loop. + +kapp-controller introduces new Custom Resource (CR) types we'll use throughout this +tutorial, including PackageRepositories and PackageInstalls. + +```bash +kubectl api-resources --api-group packaging.carvel.dev +``` + +You can see other kapp-controller CRs in other groups: + +```bash +kubectl api-resources --api-group data.packaging.carvel.dev +``` + +```bash +kubectl api-resources --api-group kappctrl.k14s.io +``` +## Creating a Package: Templating our config + +We will be using [ytt](https://carvel.dev/ytt/) templates that describe a simple Kubernetes Deployment and Service. +These templates will install a simple greeter app with a templated hello message. + +Create a config.yml: + +```bash +cat > config.yml << EOF +#@ load("@ytt:data", "data") + +#@ def labels(): +simple-app: "" +#@ end + +--- +apiVersion: v1 +kind: Service +metadata: + namespace: default + name: simple-app +spec: + ports: + - port: #@ data.values.svc_port + targetPort: #@ data.values.app_port + selector: #@ labels() +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + namespace: default + name: simple-app +spec: + selector: + matchLabels: #@ labels() + template: + metadata: + labels: #@ labels() + spec: + containers: + - name: simple-app + image: docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 + env: + - name: HELLO_MSG + value: #@ data.values.hello_msg +EOF +``` + +and put our schema into values.yml: + +```bash +cat > values.yml <<- EOF +#@data/values-schema +--- +#@schema/desc "Port number for the service." +svc_port: 80 +#@schema/desc "Target port for the application." +app_port: 80 +#@schema/desc "Name used in hello message from app when app is pinged." +hello_msg: stranger +EOF +``` + +## Creating a Package: Structuring our contents +We'll create an [imgpkg bundle](https://carvel.dev/imgpkg/docs/latest/resources/#bundle) +that contains the package contents: the configuration (config.yml and values.yml from the previous step) and a reference to the greeter app image (docker.io/dkalinin/k8s-simple-app@sha256:...). + +The [package bundle format](https://carvel.dev/kapp-controller/docs/latest/packaging-artifact-formats/#package-contents-bundle) describes the purpose of each directory +used in this section of the tutorial as well as general recommendations. + +Let's create a directory with our configuration files: +```bash +mkdir -p package-contents/config/ +cp config.yml package-contents/config/config.yml +cp values.yml package-contents/config/values.yml +``` + +Once we have the configuration figured out, let’s use kbld to record which container images are used: +```bash +mkdir -p package-contents/.imgpkg +kbld -f package-contents/config/ --imgpkg-lock-output package-contents/.imgpkg/images.yml +``` + +For more on using kbld to populate the .imgpkg directory with an ImagesLock, and why it is useful, see the [imgpkg docs on the subject](https://carvel.dev/imgpkg/docs/latest/resources/#imageslock-configuration). + +Once these files have been added, our package contents bundle is ready to be pushed! + +For the purpose of this tutorial, we will run an unsecured local docker +registry. In the real world please be safe and use appropriate security +measures. + +```bash +docker run -d -p 5000:5000 --restart=always --name registry registry:2 +``` + +From the terminal we can access this registry as `localhost:5000` but within the +cluster we'll need the IP Address. To emphasize that you would +normally use a repo host such as dockerhub or harbor we will store the IP +address in a variable: + +```bash +export REPO_HOST="`ifconfig | grep -A1 docker | grep inet | cut -f10 -d' '`:5000" +``` + +Now we can publish our bundle to our registry: + +```bash +imgpkg push -b ${REPO_HOST}/packages/simple-app:1.0.0 -f package-contents/ +``` + + +You can verify that we pushed something called `packages/simple-app` by checking the Docker registry catalog: + +```bash +curl ${REPO_HOST}/v2/_catalog +``` + +## Creating the Custom Resources + +To finish creating a package, we need to create two CRs. The first CR is the PackageMetadata CR, which will contain high level information and descriptions about our package. + +When creating this CR, the api will validate that the PackageMetadata’s name is a fully qualified name: It must have at least three segments separated by `.` and cannot have a trailing `.`. + +We'll make a conformant `metadata.yml` file: + +```bash +cat > metadata.yml << EOF +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + # This will be the name of our package + name: simple-app.corp.com +spec: + displayName: "Simple App" + longDescription: "Simple app consisting of a k8s deployment and service" + shortDescription: "Simple app for demoing" + categories: + - demo +EOF +``` + +Now we need to create a Package CR. +This CR contains versioned instructions and metadata used to install packaged software that fits the description provided in the PackageMetadata CR we just saved in `metadata.yml`. + +In order to create the Package CR with our OpenAPI Schema, we will export from +our ytt schema: + +```bash +ytt -f package-contents/config/values.yml --data-values-schema-inspect -o openapi-v3 > schema-openapi.yml +``` + +That command creates an OpenAPI document, from which we really only need the +`components.schema` section for our Package CR. + + +```bash +cat > package-template.yml << EOF +#@ load("@ytt:data", "data") # for reading data values (generated via ytt's data-values-schema-inspect mode). +#@ load("@ytt:yaml", "yaml") # for dynamically decoding the output of ytt's data-values-schema-inspect +--- +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + name: #@ "simple-app.corp.com." + data.values.version +spec: + refName: simple-app.corp.com + version: #@ data.values.version + releaseNotes: | + Initial release of the simple app package + valuesSchema: + openAPIv3: #@ yaml.decode(data.values.openapi)["components"]["schemas"]["dataValues"] + template: + spec: + fetch: + - imgpkgBundle: + image: #@ "${REPO_HOST}/packages/simple-app:" + data.values.version + template: + - ytt: + paths: + - "config/" + - kbld: + paths: + - ".imgpkg/images.yml" + - "-" + deploy: + - kapp: {} +EOF +``` + +This Package contains some metadata fields specific to the version, such as releaseNotes and a valuesSchema. The valuesSchema shows what configurable properties exist for the version. This will help when users want to install this package and want to know what can be configured. + +The other main component of this CR is the template section. +This section informs kapp-controller of the actions required to install the packaged software, so take a look at the [app-spec](https://carvel.dev/kapp-controller/docs/latest/app-spec/) section to learn more about each of the template sections. For this example, we have chosen a basic setup that will fetch the imgpkg bundle we created in the previous section, run the templates stored inside through ytt, apply kbld transformations, and then deploy the resulting manifests with kapp. + +There will also be validations run on the Package CR, so ensure that spec.refName and spec.version are not empty and that metadata.name is `.`. +These validations are done to encourage a naming scheme that keeps package version names unique. +## Creating a Package Repository + +A [package repository](https://carvel.dev/kapp-controller/docs/latest/packaging/#package-repository) +is a collection of packages (more specifically a collection of Package and PackageMetadata CRs). +Our recommended way to make a package repository is via an [imgpkg bundle](https://carvel.dev/imgpkg/docs/latest/resources/#bundle). + +The [PackageRepository bundle format](https://carvel.dev/kapp-controller/docs/latest/packaging-artifact-formats/#package-repository-bundle) describes purpose of each directory and general recommendations. + +Lets start by creating the needed directories: + +```bash +mkdir -p my-pkg-repo/.imgpkg my-pkg-repo/packages/simple-app.corp.com +``` + +we can copy our CR YAMLs from the previous step in to the proper packages +subdirectory. Note that we are declaring the version and the openAPI schema file +to ytt. + +```bash +ytt -f package-template.yml --data-value-file openapi=schema-openapi.yml -v version="1.0.0" > my-pkg-repo/packages/simple-app.corp.com/1.0.0.yml +cp metadata.yml my-pkg-repo/packages/simple-app.corp.com +``` + +Next, let’s use kbld to record which package bundles are used: + +```bash +kbld -f my-pkg-repo/packages/ --imgpkg-lock-output my-pkg-repo/.imgpkg/images.yml +``` + +With the bundle metadata files present, we can push our bundle to whatever OCI +registry we plan to distribute it from, which for this tutorial will just be our +same REPO_HOST. + +```bash +imgpkg push -b ${REPO_HOST}/packages/my-pkg-repo:1.0.0 -f my-pkg-repo +``` + +The package repository is pushed! + +You can verify by checking the Docker registry catalog: + +```bash +curl ${REPO_HOST}/v2/_catalog +``` + +In the next steps we'll act as the package consumer, showing an example of adding and using a PackageRepository with kapp-controller. + +## Adding a PackageRepository + +kapp-controller needs to know which packages are available to install. +One way to let it know about available packages is by creating a package repository. +To do this, we need a PackageRepository CR: + +```bash +cat > repo.yml << EOF +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + name: simple-package-repository +spec: + fetch: + imgpkgBundle: + image: ${REPO_HOST}/packages/my-pkg-repo:1.0.0 +EOF +``` + +(See our +[demo video](https://www.youtube.com/watch?v=PmwkicgEKQE) and [website](https://carvel.dev/kapp-controller/docs/latest/private-registry-auth) for more typical usage with an external repository.) + +This PackageRepository CR will allow kapp-controller to install any of the +packages found within the `${REPO_HOST}/packages/my-pkg-repo:1.0.0` imgpkg bundle, which we +stored in our docker OCI registry previously. + +We can use kapp to apply it to the cluster: +```bash +kapp deploy -a repo -f repo.yml -y +``` + +Check for the success of reconciliation to see the repository become available: +```bash +watch kubectl get packagerepository +``` + +Once the simple-package-repository has a "**Reconcile succeeded**" description, +we're ready to continue! You can exit the watch by hitting control-c or +clicking: `^C` + +Once the deploy has finished, we are able to list the package metadatas to see, at a high level, which packages are now available within our namespace: +```bash +kubectl get packagemetadatas +``` + +If there are numerous available packages, each with many versions, this list can become a bit unwieldy, so we can also list the packages with a particular name using the --field-selector option on kubectl get. +```bash +kubectl get packages --field-selector spec.refName=simple-app.corp.com +``` + +From here, if we are interested, we can further inspect each version to discover +information such as release notes, installation steps, licenses, etc. For +example: +```bash +kubectl get package simple-app.corp.com.1.0.0 -o yaml +``` + + +## Installing a Package + +Once we have the packages available for installation (as seen via `kubectl get packages`), +we need to let kapp-controller know which package we want to install. +To do this, we will need to create a PackageInstall CR (and a secret to hold the values used by our package): + +```bash +cat > pkginstall.yml << EOF +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: pkg-demo +spec: + serviceAccountName: default-ns-sa + packageRef: + refName: simple-app.corp.com + versionSelection: + constraints: 1.0.0 + values: + - secretRef: + name: pkg-demo-values +--- +apiVersion: v1 +kind: Secret +metadata: + name: pkg-demo-values +stringData: + values.yml: | + --- + hello_msg: "to all my internet friends" +EOF +``` + + +This CR references the Package we created in the previous sections using the package’s `refName` and `version` fields (see yaml from step 7). +Do note, the `versionSelection` property has a constraints subproperty to give more control over which versions are chosen for installation. +More information on PackageInstall versioning can be found [here](https://carvel.dev/kapp-controller/docs/latest/packaging/#versioning-packageinstalls). + +This yaml snippet also contains a Kubernetes secret, which is referenced by the PackageInstall. This secret is used to provide customized values to the package installation’s templating steps. Consumers can discover more details on the configurable properties of a package by inspecting the Package CR’s valuesSchema. + +Finally, to install the above package, we will also need to create `default-ns-sa` service account (refer to [Security model](https://carvel.dev/kapp-controller/docs/latest/security-model/) +for explanation of how service accounts are used) that give kapp-controller privileges to create resources in the default namespace: +```bash +kapp deploy -a default-ns-rbac -f https://raw.githubusercontent.com/carvel-dev/kapp-controller/develop/examples/rbac/default-ns.yml -y +``` + +Apply the PackageInstall using kapp: +```bash +kapp deploy -a pkg-demo -f pkginstall.yml -y +``` + +After the deploy has finished, kapp-controller will have installed the package in the cluster. We can verify this by checking the pods to see that we have a workload pod running. The output should show a single running pod which is part of simple-app: +```bash +kubectl get pods +``` + +Once the pod is ready, you can use kubectl’s port forwarding to verify the customized hello message has been used in the workload: +```bash +kubectl port-forward service/simple-app 3000:80 & +``` + +Now if we make a request against our service, we can see that our `hello_msg` +values is being used: +```bash +curl localhost:3000 +``` +## Congratulations! + +Visit [carvel.dev](https://carvel.dev/) to learn more about Carvel tools. + +See the full docs for [Package Management with kapp-controller](https://carvel.dev/kapp-controller/docs/latest/packaging/) diff --git a/site/content/kapp-controller/docs/v0.49.x/packaging.md b/site/content/kapp-controller/docs/v0.49.x/packaging.md new file mode 100644 index 000000000..129f053b0 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/packaging.md @@ -0,0 +1,504 @@ +--- +aliases: [/kapp-controller/docs/latest/packaging] +title: Package Management +--- + + +## Overview + +kapp-controller provides a declarative way to install, manage, and upgrade packages on a Kubernetes cluster. It leverages the PackageRepository, PackageMetadata, Package, and PackageInstall CRDs to do so. Get started by installing the [latest release of kapp-controller](install.md). + +## Concepts & CustomResourceDefinitions + +### Package + +A package is a combination of configuration metadata and OCI images that informs the package manager what software it holds and how to install itself onto a Kubernetes cluster. For example, an nginx-ingress package would instruct the package manager where to download the nginx container image, how to configure the associated Deployment, and install it into a cluster. + +A Package is represented in kapp-controller using a Package CR. The Package CR is created for every new version of a package and it carries information about how to fetch, template, and deploy the package. A Package CR is a namespaced resource by default. [Learn more](package-consumer-concepts.md#namespacing) about how to share a Package CR across all namespaces within a cluster. + +```yaml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + # Must be of the form '.' (Note the period) + name: fluent-bit.carvel.dev.1.5.3 + # The namespace this package is available in + namespace: my-ns +spec: + # Package name; referenced by PackageInstall; + # - must be a valid DNS subdomain name (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + # - at least three segments separated by a '.', no trailing '.' + # - only use subdomain names under your direct or your organization's control + # to avoid any future naming conflicts with domain owners. + # Examples (assuming you own "corp.com" or its subdomains): + # - fluent-bit.packages.corp.com + # - frontend.corp.com + # - frontend.apps.corp.com + # - app1.team-x.corp.com + # (required; string) + refName: fluent-bit.carvel.dev + # Package version; referenced by PackageInstall; + # Must be valid semver as specified by https://semver.org/spec/v2.0.0.html + # Cannot be empty (required; string) + version: 1.5.3 + # Version release notes (optional; string) + releaseNotes: "Fixed some bugs" + # System requirements needed to install the package. + # Note: these requirements will not be verified by kapp-controller on + # installation. (optional; string) + capacityRequirementsDescription: "RAM: 10GB" + # Description of the licenses that apply to the package software + # (optional; Array of strings) + licenses: + - "Apache 2.0" + - "MIT" + # Timestamp of release (iso8601 formatted string; optional) + releasedAt: 2021-05-05T18:57:06Z + # IncludedSoftware can be used to show the software contents of a Package. + # This is especially useful if the underlying versions do not match the Package version + includedSoftware: + - displayName: fluent-bit + version: 1.5.3 + description: fluent bit + - displayName: fluent-webhook + version: 2.3.4 + description: a fluent webhook + # KappControllerVersionSelection specifies the versions of kapp-controller which can install this package. + # PackageInstall will fail if this constraint is not met. + kappControllerVersionSelection: + # Constraint to limit acceptable versions for this package. + constraints: ">0.40.0 <1.0.0" + # KubernetesVersionSelection specifies the versions of kubernetes which this package can be installed on. + # PackageInstall will fail if this constraint is not met. + kubernetesVersionSelection: + # Constraint to limit acceptable versions for this package. + constraints: ">0.20.5" + # valuesSchema can be used to show template values that + # can be configured by users when a Package is installed. + # These values should be specified in an OpenAPI schema format. (optional) + valuesSchema: + # openAPIv3 key can be used to declare template values in OpenAPIv3 + # format. Read more on using ytt to generate this schema: + # https://carvel.dev/kapp-controller/docs/latest/packaging-tutorial/#creating-the-custom-resources + openAPIv3: + title: fluent-bit.carvel.dev.1.5.3 values schema + examples: + - namespace: fluent-bit + properties: + namespace: + type: string + description: Namespace where fluent-bit will be installed. + default: fluent-bit + examples: + - fluent-bit + # App template used to create the underlying App CR. + # See 'App CR Spec' docs for more info + template: + spec: + fetch: + - imgpkgBundle: + image: registry.tkg.vmware.run/tkg-fluent-bit@sha256:... + template: + - ytt: + paths: + - config/ + - kbld: + paths: + # - must be quoted when included with paths + - .imgpkg/images.yml + - "-" + deploy: + - kapp: {} +``` + +### Package Metadata + +Package Metadata are attributes of a single package that do not change frequently and that are shared across multiple versions of a single package. It contains information similar to a project's README.md. + +It is represented in kapp-controller by a PackageMetadata CR. A PackageMetadata CR is a namespaced resource by default. [Learn more](package-consumer-concepts.md#namespacing) about how to share a PackageMetadata CR across all namespaces within a cluster. + +```yaml +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: PackageMetadata +metadata: + # Package name (spec.refName) used by associated Package CRs + name: fluent-bit.vmware.com + # The namespace this package metadata is available in + namespace: my-ns +spec: + # Human friendly name of the package (optional; string) + displayName: "Fluent Bit" + # Long description of the package (optional; string) + longDescription: "Fluent bit is an open source..." + # Short desription of the package (optional; string) + shortDescription: "Log processing and forwarding" + # Base64 encoded icon (optional; string) + iconSVGBase64: YXNmZGdlcmdlcg== + # Name of the entity distributing the package (optional; string) + providerName: VMware + # List of maintainer info for the package. + # Currently only supports the name key. (optional; array of maintainer info) + maintainers: + - name: "Person 1" + - name: "Person 2" + # Classifiers of the package (optional; Array of strings) + categories: + - "logging" + - "daemon-set" + # Description of the support available for the package (optional; string) + supportDescription: "..." +``` + +### Package Repository + +A package repository is a collection of packages and their metadata. Similar to a maven repository or a rpm repository, adding a package repository to a cluster gives users of that cluster the ability to install any of the packages from that repository. + +It is represented in kapp-controller by a PackageRepository CR. A PackageRepository CR is a namespaced resource by default. [Learn more](package-consumer-concepts.md#namespacing) about how to share a PackageRepository CR across all namespaces within a cluster. + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + # Any user-chosen name that describes package repository + name: basic.carvel.dev + # The namespace to make packages available to + namespace: my-ns +spec: + # pauses _future_ reconciliation; does _not_ affect + # currently running reconciliation (optional; default=false) + paused: true + # specifies the length of time to wait, in time + unit + # format, before reconciling.(optional; default=10m) + syncPeriod: 1m + # Must have only one directive. + fetch: + # pull content from within this resource; or other resources in the cluster + inline: # NOTE: inline fetch available since v 0.31.0 + # specifies mapping of paths to their content; + # not recommended for sensitive values as CR is not encrypted (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps; + # data values are recommended to be placed in secrets (optional) + pathsFrom: + - secretRef: + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + # pulls imgpkg bundle from Docker/OCI registry + imgpkgBundle: + # Docker image url; unqualified, tagged, or + # digest references supported (required) + image: host.com/username/image:v0.1.0 + # specifies a strategy to choose a tag (optional; v0.24.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see https://carvel.dev/vendir/docs/latest/versions/ for details) (required) + constraints: ">1.0.0 <3.0.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] + # pulls image containing packages from Docker/OCI registry + image: + # Image url; unqualified, tagged, or + # digest references supported (required) + url: host.com/username/image:v0.1.0 + # grab only portion of image (optional) + subPath: inside-dir/dir2 + # specifies a strategy to choose a tag (optional; v0.24.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see https://carvel.dev/vendir/docs/latest/versions/ for details) (required) + constraints: ">1.0.0 <3.0.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] + # uses http library to fetch file containing packages + http: + # http and https url are supported; + # plain file, tgz and tar types are supported (required) + url: https://host.com/archive.tgz + # checksum to verify after download (optional) + sha256: 0a12cdef83... + # grab only portion of download (optional) + subPath: inside-dir/dir2 + # uses git to clone repository containing package list + git: + # http or ssh urls are supported (required) + url: https://github.com/k14s/k8s-simple-app-example + # branch, tag, commit; origin is the name of the remote (required) + ref: origin/develop + # grab only portion of repository (optional) + subPath: config-step-2-template + # skip lfs download (optional) + lfsSkipSmudge: true + # specifies a strategy to resolve to an explicit ref (optional; v0.24.0+) + refSelection: + semver: + # list of semver constraints (see https://carvel.dev/vendir/docs/latest/versions/ for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.24.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.24.0+) + identifiers: [beta, rc] +``` + +### Package Install + +A Package Install is an actual installation of a package and its underlying resources on a Kubernetes cluster. It is represented in kapp-controller by a PackageInstall CR. A PackageInstall CR must reference a Package CR. + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: fluent-bit + # The namespace to install the package in to + namespace: my-ns +spec: + # pauses _future_ reconcilation; does _not_ affect + # currently running reconciliation (optional; default=false) + paused: true + # cancels current and future reconciliations (optional; default=false) + canceled: true + # Deletion requests for the PackageInstall/App will result in + # the PackageInstall/App CR being deleted, but its associated + # resources will not be deleted (optional; default=false) + noopDelete: true + # specifies the length of time to wait, in time + unit + # format, before reconciling.(optional; default=10m) + syncPeriod: 1m + # specifies service account that will be used to install underlying package contents + serviceAccountName: fluent-bit-sa + # Specifies the default namespace to install the Package resources, by default this is + # same as the PackageInstall namespace + defaultNamespace: "" + # specifies that Package should be deployed to destination cluster; + # by default, cluster is same as where this resource resides (optional) + # NOTE: if you provide a serviceAccountName then the cluster block will be ignored. + cluster: + # specifies namespace in destination cluster (optional) + namespace: ns2 + # specifies secret containing kubeconfig (required) + kubeconfigSecretRef: + # specifies secret name within app's namespace (required) + name: cluster1 + # specifies key that contains kubeconfig (optional - by default kubeconfig + # will be expected under a key named "value") + key: value + packageRef: + # Specifies the name of the package to install (required) + refName: fluent-bit.vmware.com + # Selects version of a package based on constraints provided (required) + versionSelection: + # Constraint to limit acceptable versions of a package; + # Latest version satisfying the constraint is chosen; + # Newly available, acceptable later versions are picked up and installed automatically. (optional) + constraints: ">v1.5.3" + # Include prereleases when selecting version. (optional) + prereleases: {} + # Values to be included in package's templating step + # (currently only included in the first templating step) (optional) + values: + - secretRef: + name: fluent-bit-values +# Populated by the controller +status: + packageRef: + # Kubernetes resource name of the package chosen against the constraints + name: fluent-bit.tkg.vmware.com.v1.5.3 + # Derived from the underlying App's Status + conditions: + - type: ValuesSchemaCheckFailed + - type: ReconcileSucceeded + - type: ReconcileFailed + - type: Reconciling +``` + +**Note:** Values will only be included in the first templating step of the package, +though we intend to improve this experience in later releases. + +### Package Build + +A PackageBuild resource is created by running `kctrl package init` to store information about how users would like to build and publish +their projects as Packages. This format is used to store configuration on the hosts filesystem, rather than on the cluster. + +```yaml +apiVersion: kctrl.carvel.dev/v1alpha1 +kind: PackageBuild +metadata: + # The name of the PackageBuild (is the same as the 'spec.refName' of the Package it generates) + name: samplepackage.corp.com +spec: + # Describes the steps to be followed while building and releasing the project + template: + spec: + # Specifies app template that will be used by the generated Package + # NOTE: The fetch section is not included as the generated Package always + # fetches from an 'imgpkg' bundle which is created and published when a package is released. + app: + spec: + # The deploy section is copied over to the generated Package and might be used + # to specify any additional 'rawOptions' + deploy: + - kapp: {} + # Specifies how the generated Package will template the fetched config + # The section should include paths to a `kbld` Config that describes + # how images should be built and where they should be pushed, if images should be built + # as a part of the release. + # 'kctrl' will build and push images if 'kbld's Config tells it to - before + # 'kctrl' generates the ImagesLock file bundled into the 'imgpkg' bundle created by a release. + template: + # Options specified here will be used in the 'ytt' section of generated Package + - ytt: + paths: + - config + # Required (even if it does not specify paths) as 'kctrl' uses this step to generate lock + # files and build images. + # Paths pointing to the lockfile and piping output from the 'ytt' stage are added by 'kctrl' + - kbld: {} + # Describes any resources a release would have to publish + export: + # Publishes an 'imgpkg' bundle + - imgpkgBundle: + # The OCI registry the bundle should be pushed to + image: 100mik/simple-package + # Specifies whether or not 'kctrl' should use the ImagesLock generated while building the project + # true, by default (when generated with 'kctrl package init') + # NOTE: The user MUST include a path to a custom ImagesLock file in 'includePaths' if they + # set this value to 'false' + useKbldImagesLock: true + # Paths to be included as a part of the published resource + includePaths: + - config + # Describes the end product of the release process + release: + # Creates and stores Package and PackageMetadata resources on the hosts file system + - resource: {} +``` + +## Advanced Use Cases + +### Requiring specific versions of Kubernetes + +Available as of v0.41.x + +As Kubernetes APIs evolve, features can be deprecated and breaking changes can be introduced. For the contents of a +package to be successfully installed, the target cluster will need to support those associated resource versions. + +kapp-controller provides a way to declare which versions of Kubernetes for which the package is compatible. + +This is done in the [Package](#package) resource: + +```yaml +spec: + kubernetesVersionSelection: + constraints: ">0.20.5" +``` +_(see [Package Consumer Concepts > Constraints](package-consumer-concepts.md#constraints) for syntax.)_ + +If a PackageInstall resource is created for that package and the version of target cluster falls outside the given constraint, +the installation will fail. + +> ⚠️ **Unenforced Constraints** \ +> kapp-controller installations prior to v0.41.x are unaware of this field in the Package CRD, ignore it, and therefore +> **cannot** honor these constraints. + +If that constraint should be ignored, this can be noted in the [PackageInstall](#package-install) resource: + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + annotations: + packaging.carvel.dev/ignore-kubernetes-version-selection: true +``` + +When the `ignore-kubernetes-version-selection` annotation is present on the PackageInstall, kapp-controller will +attempt to install that package, regardless of the version of the cluster. + +### Requiring specific versions of kapp-controller + +Available as of v0.41.x + +A package may rely a feature of either kapp-controller itself or one of the bundled tools (or one of the bundled tools +used to fetch, template, or deploy). In this case, for the package to be installed successfully, the attendant version +of kapp-controller must be deployed. + +The package can declare which versions of kapp-controller are known to be compatible. + +This is done in the [Package](#package) resource: + +```yaml +spec: + kappControllerVersionSelection: + constraints: ">0.40.0 <1.0.0" +``` +_(see [Package Consumer Concepts > Constraints](package-consumer-concepts.md#constraints) for syntax.)_ + +If a PackageInstall resource is created for that package and the version of kapp-controller on that cluster falls outside +the given constraint, the installation will fail. + +> ⚠️ **Unenforced Constraints** \ +> kapp-controller installations prior to v0.41.x are unaware of this field in the Package CRD, ignore it, and therefore +> **cannot** honor these constraints. + +If that constraint should be ignored, this can be noted in the [PackageInstall](#package-install) resource: + +```yaml +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + annotations: + packaging.carvel.dev/ignore-kapp-controller-version-selection: true +``` + +When the `ignore-kapp-controller-version-selection` annotation is present on the PackageInstall, kapp-controller will +attempt to install that package, regardless of the version of kapp-controller. + + +## Combinations and Special Cases + +### Overlapping Package Repositories + +Available as of v0.38.0 + +Multiple Package Repositories (PKGRs) are trivially supported, but it gets more complicated if +they include the same Package or PackageMetadata (Package[Metadata]). The rules are: + +- Any Package[Metadata] with completely identical name (and version, + for Packages), spec, annotations[1], and labels[1] that appears in multiple PKGRs + will be associated to the first PKGR that reconciles. Subsequent PKGRs will + reconcile without conflicts. +- If an identical Package[Metadata] is provided by multiple PKGRs, and the PKGR that owns it is + deleted, there may be a transient period (corresponding to the PKGR sync + period) when that package is unavailable, + until the other PKGR that provides it reconciles again. +- If a Package[Metadata] is provided by multiple PKGRs, and while the + name/refname match, the rest of the resource is _not_ + identical, then only the first PKGR to reconcile on the system will reconcile + successfully. Subseuent PKGRs will fail with a nominally helpful error message + indicating which Package[Metadata] failed to match and providing a top-level + key (e.g. "annotations failed to match" or "spec.template failed to match"). +- If a Package[Metadata] is provided by multiple PKGRs and despite having the + same name/refname/version it is known that one of the resources is an update + or later revision, the annotation key "packaging.carvel.dev/revision" can be + used to provide an ordering. + - Resources without the annotation are considered to have version -1 + - Resources with the revision annotation should have a value of the form "int" + or "int.int" or "int.int.int.int.int...." + - Revision 0 will be considered < revision 0.0 (longer revision is "greater + than" shorter revision of the same numbers) + - Revision 1.1.0 will be considered < revision 1.2.0 (semver sensibilities, + but we don't parse '+' or other extensions) + + +[1] comparisons of annotations and labels exclude those annotations and labels +that are added or used by kapp or kapp-controller. diff --git a/site/content/kapp-controller/docs/v0.49.x/private-registry-auth.md b/site/content/kapp-controller/docs/v0.49.x/private-registry-auth.md new file mode 100644 index 000000000..78ca30c7e --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/private-registry-auth.md @@ -0,0 +1,217 @@ +--- +aliases: [/kapp-controller/docs/latest/private-registry-auth] +title: Authenticating to Private Registries +--- + +## Scenario + +As a package consumer you may need to provide registry credentials if you are consuming package repository (and/or packages) from a registry that requires authenticated access. That may involve providing registry credentials to multiple parts of the system: + +- credentials for pulling package repository bundle (via PackageRepository CR) + - consumed by imgpkg running inside kapp-controller Pod +- credentials for pulling package contents bundle (via PackageInstall CR) + - consumed by imgpkg running inside kapp-controller Pod +- credentials for pulling container images used by the package + - credentials consumed by Kubelets + - e.g. needed by cert-manager controller Pod +- credentials for pulling container images used by packages operator + - credentials consumed by Kubelets + - e.g. needed by Kafka cluster Pods created for KafkaInstance CR + +Providing credentials manually to each one of these parts of the system can become a hassle. kapp-controller v0.24.0+ when installed together with [secretgen-controller](https://github.com/carvel-dev/secretgen-controller) v0.5.0+ allow package consumers and package authors to simplify such configuration. + +Note that if you are using an IaaS provided Kubernetes cluster already preauthenticated with an IaaS provided registry, then there is no need to provide credentials manually in the cluster. kapp-controller v0.25.0+ is able to automatically pick up provided credentials to satisfy first two bullet points above. Last two bullet points are already satisfied by the Kubernetes kubelet. + +## secretgen-controller's placeholder secrets and SecretExport CR + +For this specific use case, secretgen-controller allows package consumer to specify registry credentials in one namespace and allows to export that secret to the entire cluster (or subset of namespaces) via [SecretExport CR](https://github.com/carvel-dev/secretgen-controller/blob/develop/docs/secret-export.md#secretexport-and-secretrequest). Registry credentials could be consumed in different namespaces via "placeholder secrets". + +A placeholder secret is: +- plain Kubernetes Secret +- with `kubernetes.io/dockerconfigjson` type (more about this secret type [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials)) +- has `secretgen.carvel.dev/image-pull-secret` annotation + +secretgen-controller will populate placeholder Secrets with a combined registry credentials. For example: + +- within `reg-creds` Namespace + - Secret `dockerhub-reg` includes DockerHub credentials for `index.docker.io` domain + - SecretExport CR `dockerhub-reg` specifies that same-named secret will be exported to all namespaces + - Secret `corp-reg` includes registry credentials for `registry.corp.com` domain + - SecretExport CR `corp-reg` specifies that same-named secret will be exported to all namespaces +- within `cert-manager-install` Namespace + - Secret `reg-creds` has `secretgen.carvel.dev/image-pull-secret` annotation indicating to secretgen to continuously ensure that this secret is filled with combination of registry credentials that allow export to this namespace (in this case both `dockerhub-reg` and `corp-reg`) + +Known limitation: Currently Secrets with type `kubernetes.io/dockerconfigjson` do not allow specifying multiple credentials for the same domain, hence you cannot provide multiple credentials for the same registry. + +**Warning** Since SecretExport CR allows you to export registry credentials to other namespaces, they will become visible to users of such namespaces. We **strongly recommend** to ensure that registry credentials you are exporting only allow read-only access to the registry and are minimally scoped within the registry. + +## kapp-controller CRs and placeholder secrets + +As of kapp-controller v0.24.0+, PackageRepository and PackageInstall CRs automatically create placeholder secrets for `image` and `imgpkgBundle` fetch types, if no explicit `secretRef.name` is provided. (These placeholder secrets are named as `-fetch-`.) If secretgen-controller is present on the cluster, these secrets will be populated with combined registry credentials; otherwise, they will remain empty. + +## Package authoring and placeholder secrets + +We encourage all package authors to include placeholder secrets within your package configuration already preconfigured to be used by your Deployments, StatefulSets, DaemonSets, Pods, etc (and any other resources that consume image pull secrets). This removes a need for package consumers to worry about configuring packages in any special way if it's being consumed from a registry that requires authentication. Note that even if you are distributing package repository from a registry that support anonymous access, package consumers may still copy it (via imgpkg copy) into a private registry that does require authentication. + +Note: In future we could provide a feature to automatically inject placeholder secrets as part of package installation (e.g. via Pod webhook); however, that is a bit more intrusive, hence we are recommending explicit usage of placeholder secrets for now. + +Example of a placeholder secret package authors should add next other resources: + +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: reg-creds + annotations: + secretgen.carvel.dev/image-pull-secret: "" +type: kubernetes.io/dockerconfigjson +data: + .dockerconfigjson: e30K +``` + +Note: `e30K` is base64 encoded `{}`. Valid `.dockerconfigjson` value is required when creating a Secret. + +## Operator writing and placeholder secrets + +If you are an owner of an operator, similar to the above section, we encourage you to create a placeholder secret for Pods (or other resources that consume image pull secrets) that may be created by your operator in other namespaces. More general operator packaging docs will come soon. + +--- +## Bringing it all together + +- Ensure kapp-controller v0.24.0+ is installed + +- Install secretgen-controller v0.5.0+ + + ```bash + kapp deploy -a sg -f https://github.com/carvel-dev/secretgen-controller/releases/download/v0.5.0/release.yml + ``` + +- Create registry credential Secret and use SecretExport CR to make it available for all namespaces (Note: if you use `kubectl create secret docker-registry` and you want to auth with DockerHub, please specify `--docker-server=index.docker.io` explicitly instead of relying on default server value.) + + ```yaml + --- + apiVersion: v1 + kind: Secret + metadata: + name: reg-creds # could be any name + namespace: secrets-ns # could be any namespace + type: kubernetes.io/dockerconfigjson # needs to be this type + stringData: + .dockerconfigjson: | + { + "auths": { + "index.docker.io": { + "username": "user...", + "password": "password...", + "auth": "" + } + } + } + + --- + apiVersion: secretgen.carvel.dev/v1alpha1 + kind: SecretExport + metadata: + name: reg-creds # must match source secret name + namespace: secrets-ns # must match source secret namespace + spec: + toNamespaces: + - "*" # star means export is available for all namespaces + ``` + +- Use PackageRepository and PackageInstall CRs without specifying secrets explicitly + + ```yaml + --- + apiVersion: packaging.carvel.dev/v1alpha1 + kind: PackageRepository + metadata: + name: e2e-repo.test.carvel.dev + namespace: kapp-controller-packaging-global + spec: + fetch: + imgpkgBundle: + image: k14stest/private-repo@sha256:ddd93b... + --- + apiVersion: packaging.carvel.dev/v1alpha1 + kind: PackageInstall + metadata: + name: pkg-demo + spec: + serviceAccountName: default-ns-sa + packageRef: + refName: pkg.test.carvel.dev + versionSelection: + constraints: 1.0.0 + ``` + +Assuming registry credentials specified are correct and both package repository bundle and package contents bundle use the same registry + +--- +## Manual configuration (without secretgen-controller) + +### PackageRepository + +If the registry containing the PackageRepository imgpkg bundle or image is private and secretgen-controller is not installed on your cluster, a secretRef can be added to the fetch stage for PackageRepository CR. For example: + +```yaml +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageRepository +metadata: + name: simple-package-repository +spec: + fetch: + imgpkgBundle: + image: k8slt/corp-com-pkg-repo:1.0.0 + secretRef: + name: my-registry-creds +``` + +This secret will need to be located in the namespace where the PackageRepository +is created and be in the format described in the [fetch docs](app-overview.md/#specfetch). + +### PackageInstall + +As of kapp-controller v0.23.0, support for adding an annotation on the PackageInstall was added to allow users to set a secret on the PackageInstall's underlying App custom resource. Before creating a PackageInstall, users can look at the Package definition that they want to install and see what fetch stages a Package has defined like below: + +```yaml +--- +apiVersion: data.packaging.carvel.dev/v1alpha1 +kind: Package +metadata: + name: simple-app.corp.com.1.0.0 +spec: + refName: simple-app.corp.com + version: 1.0.0 + template: + spec: + fetch: + - imgpkgBundle: + image: registry.corp.com/packages/simple-app:1.0.0 + # ... +``` + +In the example above, the Package has a single fetch stage to retrieve an imgpkg bundle. To use a PackageInstall +to specify what secret to use for this fetch stage, an annotation is added to the PackageInstall as shown below: + +```yaml +--- +apiVersion: packaging.carvel.dev/v1alpha1 +kind: PackageInstall +metadata: + name: simple-app-with-secret + annotations: + ext.packaging.carvel.dev/fetch-0-secret-name: simple-app-secret +spec: + serviceAccountName: default-ns-sa + packageRef: + refName: simple-app.corp.com + versionSelection: + constraints: 1.0.0 +``` + +The annotation shown above `ext.packaging.carvel.dev/fetch-0-secret-name: simple-app-secret` has a format that allows users to specify the specific fetch stage by how it is defined in the Package definition. In this case, the PackageInstall being created will add a secretRef to the App's first fetch stage (i.e. `fetch-0-secret-name`) for the imgpkg bundle. If the Package definition had an additional fetch stage, the secret annotation could be added in the following format: `ext.packaging.carvel.dev/fetch-1-secret-name: simple-app-additional-secret`. + +To use this annotation with a PackageInstall, associated secrets will need to be located in the namespace where the PackageInstall is created and be in the format described in the [fetch docs](app-overview.md/#specfetch). diff --git a/site/content/kapp-controller/docs/v0.49.x/security-model.md b/site/content/kapp-controller/docs/v0.49.x/security-model.md new file mode 100644 index 000000000..0c168c4d7 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/security-model.md @@ -0,0 +1,67 @@ +--- +aliases: [/kapp-controller/docs/latest/security-model] +title: Security Model +--- + +## App CR privileges + +kapp-controller container runs with a service account (named +`kapp-controller-sa` inside `kapp-controller` namespace) that has access to all +service accounts and secrets in the cluster. This service account *is not* used +for deployment of app resources. + +Each App CR *must* specify either a + +- service account (via `spec.serviceAccountName`) +- or, Secret with kubeconfig contents for some cluster (via `spec.cluster.kubeconfigSecretRef.name`) + +forcing App CR owner to explicitly provide needed privileges for management of +app resources. This avoids a problem of privilege escalation commonly found in +other general resource controllers which rely on a shared service account (often +requiring cluster admin privileges) to deploy resources. + +Since App CR only allows to reference service account or kubeconfig Secret +within the same namespace where App CR is located, kapp-controller is well +suited for multi-tenant use where different users of App CRD have varied level +of access (e.g. some may have cluster level privileges, and other may only have +access to one or more namespace). + +Example: + +- User A has been granted access to namespace `a` (and no other namespace or + cluster level access). User A can create an App CR with a service account + located in namespace `a` to deploy resources into namespace `a`. It _is not_ + possible for user A to create an App CR that would install cluster-wide + resources or place resources into another namespace. (e.g. a user that just + deploys web application to their namespace) + +- User B has been granted access to namespace `b` and ability to manage + specifically named CRD (single scoped cluster-wide privilege). User B can + create an App CR with a service account located in namespace `b` that installs + app into namespace `b` and also manages single CRD lifecycle. (e.g. a user + that manages another controller for other users) + +## Minimum ServiceAccount Permissions + +For users managing App and PackageInstall CR privileges via a service account, +the verbs in the role below are needed for working with ConfigMaps. + +```yaml +kind: Role +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: app-ip-cr-role +rules: +- apiGroups: [""] + resources: ["configmaps"] + verbs: ["get", "list", "create", "update", "delete"] +``` + +These permissions are needed because of how `kapp` tracks information about apps +it manages, which is via storing information in a ConfigMap. So even if your App +or PackageInstall CR does not create ConfigMaps, the service account will +still need permissions for working with ConfigMaps. + +The ConfigMap permissions above are needed in addition to any other +resource/verb combinations needed to deploy all resources created by the App and +PackageInstall CRs. diff --git a/site/content/kapp-controller/docs/v0.49.x/security.md b/site/content/kapp-controller/docs/v0.49.x/security.md new file mode 100644 index 000000000..4a7b0542c --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/kapp-controller/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `kapp-controller`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/content/kapp-controller/docs/v0.49.x/sops.md b/site/content/kapp-controller/docs/v0.49.x/sops.md new file mode 100644 index 000000000..275dca2b6 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/sops.md @@ -0,0 +1,146 @@ +--- +aliases: [/kapp-controller/docs/latest/sops] +title: Sops +--- + +Available in v0.11.0+. + +Storing _encrypted_ secrets next to your configuration (within a Git repo or other artifacts) is one way to manage secret lifecycle. kapp-controller integrates with [Mozilla's SOPS](https://github.com/mozilla/sops) to decrypt secret material in fetched configuration. + +## Prepare your keys +Sops shipped with kapp-controller includes support for encryption via both [GPG](https://gnupg.org/) and [age](https://github.com/FiloSottile/age). +Note that the Sops project recommends Age. + +### using GPG + +```bash +$ gpg --gen-key +... + +$ gpg --list-secret-keys --keyid-format LONG +/root/.gnupg/secring.gpg +------------------------ +sec 4096R/B464DFD255C6B9F8 2020-10-03 +uid test test (test) +ssb 4096R/FEE37B8E2098EDFC 2020-10-03 +``` + +(Note: `B464DFD255C6B9F8` is the ID to be used later) + +### using Age +You may find [this screencast](https://asciinema.org/a/431605) helpful. +```bash +$ age-keygen -o key.txt +Public key: age12345... + +$ chmod 600 key.txt +``` +(Note: the public key `age12345...` will be used later) + +## Encrypt contents + +kapp-controller expects that encrypted files have `.sops.yml` extension (or `.sops.yaml`). + +You can start by creating an unencrypted yaml: +```bash +# Unencrypted file +$ cat secret.yml +apiVersion: v1 +kind: Secret +metadata: + name: my-sec +data: + password: my-password +``` + +Then encrypt file with your public key from the previous step, to be later decrypted by kapp-controller. + +### using GPG +```bash +$ sops --encrypt --pgp B464DFD255C6B9F8 secret.yml > secret.sops.yml + +# Delete unencrypted file +$ rm secret.yml +``` + +### using Age +```bash +$ SOPS_AGE_KEY_FILE=./key.txt sops --encrypt --age age12345... secret.yml > secret.sops.yml +``` + +## Import private key into Kubernetes +Make a secret that includes the private key and import it into your +cluster. It will be referenced by App CR. + +### using GPG +Extract PGP private key from your GPG installation: + +```bash +$ gpg --armor --export-secret-keys B464DFD255C6B9F8 > my.pk +``` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: pgp-key + namespace: default +stringData: + # value of this is contents of my.pk + my.pk: | + -----BEGIN PGP PRIVATE KEY BLOCK----- + Version: GnuPG v1 + ... +``` + +### using Age +Cat the contents of your local key.txt to the body of a stringData block also named +key.txt: +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: age-key +stringData: + key.txt: | + # created: + # public key: age12345... + AGE-SECRET-KEY-HUNTER2ORSOMETHINGWHENEVERYOUTYPEYOURPASSWORDIJUSTSEEHUNTER2 +``` + +## Decrypt in App CR + +Configure App CR to decrypt contents. Assuming, in this example, your git repo contains `secret.sops.yml`, it would be decrypted into `secret.yml` file. + +### using GPG +```yaml +apiVersion: kappctrl.k14s.io/v1alpha1 +kind: App +metadata: + name: config-with-sops + namespace: default +spec: + serviceAccountName: default-ns + fetch: + - git: + ... + template: + - sops: + pgp: + privateKeysSecretRef: + name: pgp-key + - ytt: {} + deploy: + - kapp: {} +``` + +### using Age +Nearly identical to the example above, but with a sops.age key: +```yaml +spec: + template: + - sops: + age: + privateKeysSecretRef: + name: age-key +``` diff --git a/site/content/kapp-controller/docs/v0.49.x/startup.md b/site/content/kapp-controller/docs/v0.49.x/startup.md new file mode 100644 index 000000000..a6e0492e9 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/startup.md @@ -0,0 +1,31 @@ +--- +aliases: [/kapp-controller/docs/latest/startup] +Title: Kapp Controller Startup +--- + +(v0.14.0+) + +The startup of kapp controller consists of two processes: +controllerinit and controller. + +## The controllerinit Process + +This is the main process for the kapp controller binary. Since the binary is +the entrypoint for the docker image, kapp controller will be PID 1 +and is therefore responsible for reaping any zombie processes, so the process +begins by starting a thread to reap any zombies that appear. More on PID 1 and +zombie processes can be found [here][1]. + +Next, the process will look for the [controller Secret or ConfigMap][2] and apply any system level +configuration specified within. + +Finally, the process will fork to the same binary with a new flag, `--internal-controller`, +starting a second process, which runs the actual kubernetes controller. + +## The controller Process + +This process is responsible for running the app reconciler, which handles the fetch, +template, and deploy aspects of kapp controller. + +[1]: https://blog.phusion.nl/2015/01/20/docker-and-the-pid-1-zombie-reaping-problem/ +[2]: controller-config.md diff --git a/site/content/kapp-controller/docs/v0.49.x/walkthrough.md b/site/content/kapp-controller/docs/v0.49.x/walkthrough.md new file mode 100644 index 000000000..bf189fd68 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.49.x/walkthrough.md @@ -0,0 +1,214 @@ +--- +aliases: [/kapp-controller/docs/latest/walkthrough] +title: Install an Application +--- + +This walkthrough demonstrates how to install an example application on Kubernetes with kapp-controller. The example application is an HTTP server. You will use `examples/simple-app-git` directory for the YAML configuration. + +You can use [kapp](/kapp) or another tool such as kubectl to deploy the following YAML examples: + +1. [Install](install.md) kapp-controller onto your cluster. + +1. Install [examples/default-ns-rbac.yml](https://github.com/carvel-dev/kapp-controller/blob/develop/examples/rbac/default-ns.yml). + + It creates `default-ns-sa` service account to change resources within the `default` namespace. The App CR in the next step uses the service account. + + ```bash-plain + $ kapp deploy -a default-ns-rbac -f https://raw.githubusercontent.com/carvel-dev/kapp-controller/develop/examples/rbac/default-ns.yml + ``` + +1. Install [examples/simple-app-git/1.yml](https://github.com/carvel-dev/kapp-controller/blob/develop/examples/simple-app-git/1.yml) App CR. + + It specifies how to fetch, template, and deploy the example application. + + ```bash-plain + $ kapp deploy -a simple-app -f https://raw.githubusercontent.com/k14s/kapp-controller/develop/examples/simple-app-git/1.yml + # or... kubectl apply -f https://raw.githubusercontent.com/k14s/kapp-controller/develop/examples/simple-app-git/1.yml + + Changes + + Namespace Name Kind Conds. Age Op Wait to Rs Ri + default simple-app App - - create reconcile - - + + Op: 1 create, 0 delete, 0 update, 0 noop, 0 exists + Wait to: 1 reconcile, 0 delete, 0 noop + + Continue? [yN]: y + + 5:20:27PM: ---- applying 1 changes [0/1 done] ---- + 5:20:27PM: create app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:20:27PM: ---- waiting on 1 changes [0/1 done] ---- + 5:20:27PM: ongoing: reconcile app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:20:33PM: ok: reconcile app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:20:33PM: ---- applying complete [1/1 done] ---- + 5:20:33PM: ---- waiting complete [1/1 done] ---- + + Succeeded + ``` + +1. Run `kubectl get app` to verify that the app is deployed. + +1. Verify the status of the App CR. + + **Note:** As of kapp-controller v0.31.0, inspect is deactivated by default. See [App CR spec](app-spec.md) for more details. + + ```bash-plain + $ kapp inspect -a simple-app --status + # or... kubectl get app simple-app -oyaml + + Resources in app 'simple-app' + + Namespace default + Name simple-app + Kind App + Status conditions: + - status: "True" + type: ReconcileSucceeded + deploy: + exitCode: 0 + finished: true + startedAt: "2019-12-02T22:20:28Z" + stdout: |- + Changes + Namespace Name Kind Conds. Age Op Wait to Rs Ri + default simple-app Deployment - - create reconcile - - + ^ simple-app Service - - create reconcile - - + Op: 2 create, 0 delete, 0 update, 0 noop, 0 exists + Wait to: 2 reconcile, 0 delete, 0 noop + 10:20:28PM: ---- applying 2 changes [0/2 done] ---- + 10:20:28PM: create service/simple-app (v1) namespace: default + 10:20:28PM: create deployment/simple-app (apps/v1) namespace: default + 10:20:29PM: ---- waiting on 2 changes [0/2 done] ---- + 10:20:29PM: ok: reconcile service/simple-app (v1) namespace: default + 10:20:29PM: ongoing: reconcile deployment/simple-app (apps/v1) namespace: default + 10:20:29PM: ^ Waiting for 1 unavailable replicas + 10:20:29PM: L ok: waiting on replicaset/simple-app-6fb57f844b (apps/v1) namespace: default + 10:20:29PM: L ongoing: waiting on pod/simple-app-6fb57f844b-jk7d8 (v1) namespace: default + 10:20:29PM: ^ Pending: ContainerCreating + 10:20:29PM: ---- waiting on 1 changes [1/2 done] ---- + 10:20:31PM: ok: reconcile deployment/simple-app (apps/v1) namespace: default + 10:20:31PM: ---- applying complete [2/2 done] ---- + 10:20:31PM: ---- waiting complete [2/2 done] ---- + Succeeded + updatedAt: "2019-12-02T22:20:31Z" + fetch: + exitCode: 0 + startedAt: "2019-12-02T22:20:27Z" + updatedAt: "2019-12-02T22:20:27Z" + inspect: + exitCode: 0 + stdout: |- + Resources in app 'simple-app-ctrl' + Namespace Name Kind Owner Conds. Rs Ri Age + default simple-app Deployment kapp 2/2 t ok - 4s + default L simple-app-6fb57f844b ReplicaSet cluster - ok - 4s + default L.. simple-app-6fb57f844b-jk7d8 Pod cluster 4/4 t ok - 4s + default simple-app Service kapp - ok - 4s + default L simple-app Endpoints cluster - ok - 4s + Rs: Reconcile state + Ri: Reconcile information + 5 resources + Succeeded + updatedAt: "2019-12-02T22:20:32Z" + observedGeneration: 2 + template: + exitCode: 0 + updatedAt: "2019-12-02T22:20:28Z" + + 1 resources + + Succeeded + ``` + + The output shows the overall status of the application, including the latest deploy output (`status.deploy.stdout`) and the latest inspect output (`status.inspect.stdout`). Based on the inspect output you can see that the app included a `Deployment` and a `Service`. + +1. Update `simple-app` App CR to reconfigure it. + + This example changes data values for ytt templates. + + ```bash-plain + $ kapp deploy -a simple-app -f https://raw.githubusercontent.com/k14s/kapp-controller/develop/examples/simple-app-git/2.yml -c + # or... kubectl apply -f https://raw.githubusercontent.com/k14s/kapp-controller/develop/examples/simple-app-git/2.yml + + --- update app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + ... + 23, 23 template: + 24 - - ytt: {} + 24 + - ytt: + 25 + inline: + 26 + pathsFrom: + 27 + - secretRef: + 28 + name: simple-app-values + 25, 29 status: + 26, 30 conditions: + --- create secret/simple-app-values (v1) namespace: default + 0 + apiVersion: v1 + 1 + kind: Secret + 2 + metadata: + 3 + labels: + 4 + kapp.k14s.io/app: "1575325198404867000" + 5 + kapp.k14s.io/association: v1.7a671029ad7db07aa797301eac59e9ad + 6 + name: simple-app-values + 7 + namespace: default + 8 + stringData: + 9 + values2.yml: | + 10 + #@data/values + 11 + --- + 12 + hello_msg: updated + 13 + + + Changes + + Namespace Name Kind Conds. Age Op Wait to Rs Ri + default simple-app App 1/1 t 2m update reconcile ok - + ^ simple-app-values Secret - - create reconcile - - + + Op: 1 create, 0 delete, 1 update, 0 noop, 0 exists + Wait to: 2 reconcile, 0 delete, 0 noop + + Continue? [yN]: y + + 5:23:13PM: ---- applying 2 changes [0/2 done] ---- + 5:23:13PM: update app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:23:13PM: create secret/simple-app-values (v1) namespace: default + 5:23:14PM: ---- waiting on 2 changes [0/2 done] ---- + 5:23:14PM: ongoing: reconcile app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:23:14PM: ok: reconcile secret/simple-app-values (v1) namespace: default + 5:23:14PM: ---- waiting on 1 changes [1/2 done] ---- + 5:23:17PM: ok: reconcile app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:23:17PM: ---- applying complete [2/2 done] ---- + 5:23:17PM: ---- waiting complete [2/2 done] ---- + + Succeeded + ``` + +1. Delete the `simple-app` App CR. + + ```bash-plain + $ kapp delete -a simple-app + # or... kubectl delete -f https://raw.githubusercontent.com/k14s/kapp-controller/develop/examples/simple-app-git/2.yml + + Changes + + Namespace Name Kind Conds. Age Op Wait to Rs Ri + default simple-app App 1/1 t 6m delete delete ok - + ^ simple-app-values Secret - 3m delete delete ok - + + Op: 0 create, 2 delete, 0 update, 0 noop, 0 exists + Wait to: 0 reconcile, 2 delete, 0 noop + + Continue? [yN]: y + + 5:26:25PM: ---- applying 2 changes [0/2 done] ---- + 5:26:25PM: delete secret/simple-app-values (v1) namespace: default + 5:26:25PM: delete app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:26:26PM: ---- waiting on 2 changes [0/2 done] ---- + 5:26:26PM: ok: delete secret/simple-app-values (v1) namespace: default + 5:26:26PM: ongoing: delete app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:26:26PM: ---- waiting on 1 changes [1/2 done] ---- + 5:26:30PM: ok: delete app/simple-app (kappctrl.k14s.io/v1alpha1) namespace: default + 5:26:30PM: ---- applying complete [2/2 done] ---- + 5:26:30PM: ---- waiting complete [2/2 done] ---- + + Succeeded + ``` diff --git a/site/content/vendir/docs/v0.35.x/_index.md b/site/content/vendir/docs/v0.35.x/_index.md index 04aed5c6b..b3ffbd167 100644 --- a/site/content/vendir/docs/v0.35.x/_index.md +++ b/site/content/vendir/docs/v0.35.x/_index.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/] + title: "About vendir" toc: "false" cascade: diff --git a/site/content/vendir/docs/v0.35.x/github-release.md b/site/content/vendir/docs/v0.35.x/github-release.md index 827addfe8..54204e7d2 100644 --- a/site/content/vendir/docs/v0.35.x/github-release.md +++ b/site/content/vendir/docs/v0.35.x/github-release.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/github-release] + title: Github Release --- diff --git a/site/content/vendir/docs/v0.35.x/install.md b/site/content/vendir/docs/v0.35.x/install.md index 0c0d5399f..9174c19df 100644 --- a/site/content/vendir/docs/v0.35.x/install.md +++ b/site/content/vendir/docs/v0.35.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/install] + title: Install --- diff --git a/site/content/vendir/docs/v0.35.x/security.md b/site/content/vendir/docs/v0.35.x/security.md index 0e42ae4c1..73663e269 100644 --- a/site/content/vendir/docs/v0.35.x/security.md +++ b/site/content/vendir/docs/v0.35.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/security] + title: Security --- diff --git a/site/content/vendir/docs/v0.35.x/sync.md b/site/content/vendir/docs/v0.35.x/sync.md index fbb5703ef..8dcedeb44 100644 --- a/site/content/vendir/docs/v0.35.x/sync.md +++ b/site/content/vendir/docs/v0.35.x/sync.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/sync] + title: Sync command --- diff --git a/site/content/vendir/docs/v0.35.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.35.x/vendir-lock-spec.md index 027838675..6276527b6 100644 --- a/site/content/vendir/docs/v0.35.x/vendir-lock-spec.md +++ b/site/content/vendir/docs/v0.35.x/vendir-lock-spec.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/vendir-lock-spec] + title: vendir.lock.yml spec --- diff --git a/site/content/vendir/docs/v0.35.x/vendir-spec.md b/site/content/vendir/docs/v0.35.x/vendir-spec.md index 519c346dd..3c5d7c064 100644 --- a/site/content/vendir/docs/v0.35.x/vendir-spec.md +++ b/site/content/vendir/docs/v0.35.x/vendir-spec.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/vendir-spec] + title: vendir.yml spec --- diff --git a/site/content/vendir/docs/v0.35.x/versions.md b/site/content/vendir/docs/v0.35.x/versions.md index 3a5791f62..be4df2288 100644 --- a/site/content/vendir/docs/v0.35.x/versions.md +++ b/site/content/vendir/docs/v0.35.x/versions.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/versions] + title: Versions --- diff --git a/site/content/vendir/docs/v0.36.x/_index.md b/site/content/vendir/docs/v0.36.x/_index.md new file mode 100644 index 000000000..bd9db762e --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/_index.md @@ -0,0 +1,25 @@ +--- + +title: "About vendir" +toc: "false" +cascade: + version: v0.36.x + toc: "true" + type: docs + layout: docs +--- + +vendir allows to declaratively state what should be in a directory. It was designed to easily manage libraries for [ytt](/ytt); however, it is a generic tool and does not care how files within managed directories are used. + +Supported sources for fetching: + +- git +- hg (Mercurial) +- http +- image (image from OCI registry) +- imgpkgBundle (bundle from OCI registry) +- githubRelease +- helmChart +- directory + +Examples could be found in [carvel-vendir's `examples/` directory](https://github.com/carvel-dev/vendir/tree/develop/examples). diff --git a/site/content/vendir/docs/v0.36.x/github-release.md b/site/content/vendir/docs/v0.36.x/github-release.md new file mode 100644 index 000000000..54204e7d2 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/github-release.md @@ -0,0 +1,17 @@ +--- + +title: Github Release +--- + +vendir supports downloading software stored as a Github release. See [`vendir.yml` spec](vendir-spec.md) for how to configure. + +## Github API Rate Limiting + +If your public IP address is shared by multiple machines (e.g. workstations in an office), you may run into [Github rate limiting errors](https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#rate-limiting). vendir as of v0.8.0 supports providing "Personal access token" to increase Github API rate limits. You can specify it via an environment variable: + +```bash +$ export VENDIR_GITHUB_API_TOKEN=ghp_8c0a3... +$ vendir sync +``` + +To obtain personal access token go to [Github.com: Settings / Developer Settings / Personal access tokens](https://github.com/settings/tokens). During token creation, you will be prompted for selection of scopes, and in most cases there is no need to select any scopes because this token only used to identify API usage. For organizations that enable SSO, you will need to "Enable SSO" for created token. diff --git a/site/content/vendir/docs/v0.36.x/install.md b/site/content/vendir/docs/v0.36.x/install.md new file mode 100644 index 000000000..9174c19df --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/install.md @@ -0,0 +1,58 @@ +--- + +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 +$ vendir version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ vendir 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 vendir +$ vendir 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/vendir/releases), for example for 'vendir-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/vendir-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/vendir-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/vendir-darwin-amd64 /usr/local/bin/vendir + +# Make binary executable +$ chmod +x /usr/local/bin/vendir + +# Check its version +$ vendir version +``` diff --git a/site/content/vendir/docs/v0.36.x/security.md b/site/content/vendir/docs/v0.36.x/security.md new file mode 100644 index 000000000..73663e269 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/security.md @@ -0,0 +1,8 @@ +--- + +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `vendir`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/content/vendir/docs/v0.36.x/sync.md b/site/content/vendir/docs/v0.36.x/sync.md new file mode 100644 index 000000000..8dcedeb44 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/sync.md @@ -0,0 +1,76 @@ +--- + +title: Sync command +--- + +## Overview + +`vendir sync` command looks for [`vendir.yml`](vendir-spec.md) file in current directory for its configuration. `vendir.yml` specifies source of files for each managed directory. + +``` +# Run to sync directory contents as specified by vendir.yml +$ vendir sync +``` + +See [`vendir.yml` spec](vendir-spec.md) for its schema. + +## Sync with local changes override + +As of v0.7.0 you can use `--directory` flag to override contents of particular directories by pointing them to local directories. When this flag is specified other directories will not be synced (hence lock config is not going to be updated). + +``` +$ vendir sync --directory vendor/local-dir=local-dir-dev +``` + +## Sync with locks + +`vendir sync` writes [`vendir.lock.yml`](vendir-lock-spec.md) (next to `vendir.yml`) that contains resolved references: + +- for `git`, resolved SHAs are recorded +- for `hg`, resolved SHAs are recorded +- for `http`, nothing is recorded +- for `image`, resolved URL as a digest reference +- for `githubRelease`, permanent links are recorded +- for `helmChart`, resolved version +- for `directory`, nothing is recorded +- for `manual`, nothing is recorded + +To use these resolved references on top of `vendir.yml`, use `vendir sync -l`. + +## Syncing from different directory + +As of v0.22.0, you can use `--chdir` flag with `vendir sync` command to change current working directory of vendir before any syncing occurs. All other paths provided to `vendir sync` should be relative to the changed directory. + +## Caching + +`vendir` allows the users to cache OCI Images in their disk so as not to rely on access to the registry all the time. +To activate this feature the users need to set the environment variable `VENDIR_CACHE_DIR`. This variable should point +to the path where they want to store the OCI Images. + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ vendir sync +``` + +**Note:** Not all images can be cached. Only images that are referenced by SHA can be cached. + +The user can also specify what is the maximum size of the content to be cached, by setting the environment variable +`VENDIR_MAX_CACHE_SIZE`. The default value, when the variable is not provided is `1Mi` (1 Megabyte). + +The following are some accepted values: +``` +1 = 1 Byte +1Ki = 1 Kilobyte +1Mi = 1 Megabyte +1Gi = 1 Gigabyte +``` + +Example of usage: + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ export VENDIR_MAX_CACHE_SIZE=1Ki +$ vendir sync +``` diff --git a/site/content/vendir/docs/v0.36.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.36.x/vendir-lock-spec.md new file mode 100644 index 000000000..6276527b6 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/vendir-lock-spec.md @@ -0,0 +1,69 @@ +--- + +title: vendir.lock.yml spec +--- + +Lock file is generated by `vendir sync` and is placed next to related `vendir.yml`. + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: LockConfig + +directories: +- path: config/_ytt_lib + contents: + - path: github.com/cloudfoundry/cf-k8s-networking + + # present if this is managed manually + manual: {} + + # present if git + git: + # resolved checked out commit SHA + sha: 2b009b61fa8afb330a4302c694ee61b11104c54c + # resolved checked out commit title + commitTitle: 'feat: add /metrics prometheus scrapable endpoint...' + # resolved to a set of tags pointing to sha (v0.11.0+) + tags: + - "4.0.0" + + # present if hg (v0.22.0+) + hg: + # resolved checked out change SHA + sha: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # resolved checked out change title + changeSetTitle: 'Prevent wrapping filenames to preserve whitespace' + + # present if github release + githubRelease: + # resolved release url + url: https://api.github.com/repos/pivotal/kpack/releases/22747441 + + # present if helm chart (v0.11.0+) + helmChart: + appVersion: "5.0.7" + version: "10.5.7" + + # present if http + http: {} + + # present if image (v0.11.0+) + image: + # fully resolve image URL with digest + url: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if imgpkgBundle (v0.16.0+) + imgpkgBundle: + # fully resolve image URL with digest + image: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if inline (v0.11.0+) + inline: {} + + # present if this was sourced from local directory + directory: {} +``` diff --git a/site/content/vendir/docs/v0.36.x/vendir-spec.md b/site/content/vendir/docs/v0.36.x/vendir-spec.md new file mode 100644 index 000000000..d4333b693 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/vendir-spec.md @@ -0,0 +1,266 @@ +--- + +title: vendir.yml spec +--- + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: Config + +# declaration of minimum required vendir binary version (optional) +minimumRequiredVersion: 0.8.0 + +# one or more directories to manage with vendir +directories: +- # path is relative to `vendir` CLI working directory + path: config/_ytt_lib + + # set the permissions for this directory (optional; v0.33.0+) + # by default directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 + + contents: + - # path lives relative to directory path # (required) + path: github.com/cloudfoundry/cf-k8s-networking + + # skip fetching if the config for this path has not changed since the last sync + # optional, `false` by default, available since v0.36.0 + # use `vendir sync --lazy=false` to forcefully sync when needed + lazy: true + + # uses git to clone Git repository (optional) + git: + # http or ssh urls are supported (required) + url: https://github.com/cloudfoundry/cf-k8s-networking + # branch, tag, commit; origin is the name of the remote (required) + # optional if refSelection is specified (available in v0.11.0+) + ref: origin/master + # depth of commits to fetch; 0 (default) means everything (optional; v0.29.0+) + depth: 1 + # specifies a strategy to resolve to an explicit ref (optional; v0.11.0+) + refSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # skip downloading lfs files (optional) + lfsSkipSmudge: false + # skip SSL/TLS verification (optional) + dangerousSkipTLSVerify: false + # skip initializing any git submodules (optional; v0.28.0+) + skipInitSubmodules: false + # verify gpg signatures on commits or tags (optional; v0.12.0+) + verification: + publicKeysSecretRef: + name: my-git-gpg-auth + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-git-auth + + # uses hg to clone Mercurial repository (optional; v0.22.0+) + hg: + # http or ssh urls are supported (required) + url: https://hg.sr.ht/~sircmpwn/hg.sr.ht + # branch, tag, commit (required) + ref: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-hg-auth + + # fetches asset over HTTP (optional) + http: + # asset URL (required) + url: + # verification checksum (optional) + sha256: "" + # specifies name of a secret with basic auth details; + # secret may include 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-http-auth + # skip unpacking tar, tgz, and zip files; by default files are unpacked (optional) + disableUnpack: false + + # fetches asset from an image registry (optional; v0.11.0+) + image: + # image URL; could be plain, tagged or digest reference (required) + url: gcr.io/repo/image:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match url + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches imgpkg bundle from an image registry (optional; v0.16.0+) + imgpkgBundle: + # could be plain, tagged or digest reference (required) + image: gcr.io/repo/bundle:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in image key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match image + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches assets from a github release (optional) + githubRelease: + # slug for repository (org/repo) (required) + slug: k14s/kapp-controller + # use release tag (optional) + # optional if tagSelection is specified (available in v0.22.0+) + tag: v0.1.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # use latest published version (optional) + latest: true + # use exact release URL (optional) + url: https://api.github.com/repos/k14s/kapp-controller/releases/21912613 + # only download specific assets (optional; v0.12.0+) + assetNames: ["release*.yml"] + # checksums for downloaded files (optional) + # (if release text body contains checksums, it's not necessary + # to manually specify them here) + checksums: + release.yml: 26bf09c42d72ae448af3d1ee9f6a933c87c4ec81d04d37b30e1b6a339f5983a7 + # disables checking auto-found checksums for downloaded files (optional) + # (checksums are extracted from release's text body + # based on following format ` `) + disableAutoChecksumValidation: true + # specifies which archive to unpack for contents (optional) + unpackArchive: + # (required) + path: release.tgz + # specifies name of a secret with github auth details; + # secret may include 'token' key (optional) + secretRef: + # (required) + name: my-gh-auth + # Used to create the URL of the asset to download the metadata + # from the Github Release. (optional) + http: + # The url parameter of http can interpolate the tag of the GitHub release using the {tag} token. + url: https://dl.k8s.io/release/{tag}/bin/linux/amd64/kubectl + + # fetch Helm chart contents (optional; v0.11.0+) + helmChart: + # chart name (required) + name: stable/redis + # use specific chart version (string; optional) + version: "1.2.1" + # specifies Helm repository to fetch from (optional) + repository: + # repository url; supports exprimental oci helm fetch via + # oci:// scheme (required) + url: https://... + # specifies name of a secret with helm repo auth details; + # secret may include 'username', 'password'; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # as of v0.22.0+, 0 or 1 auth credential is expected within dockerconfigjson secret + # if >1 auth creds found, error will be returned. (currently registry hostname + # is not used when found in provide auth credential.) + secretRef: + # (required) + name: my-helm-auth + # specify helm binary version to use; + # '3' means binary 'helm3' needs to be on the path (optional) + helmVersion: "3" + + # copy contents from local directory (optional) + directory: + # local file system path relative to vendir.yml + path: some-path + + # states that directory specified by above path + # is managed by hand; nothing to do for vendir (optional) + manual: {} + + # specify contents inline within this file (optional; v0.11.0+) + inline: + # specifies mapping of paths to their content (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps (optional) + pathsFrom: + - secretRef: + # (required) + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + # (required) + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + + # includes paths specify what should be included. by default + # all paths are included (optional) + includePaths: + - cfroutesync/crds/**/* + - install/ytt/networking/**/* + + # exclude paths are "placed" on top of include paths (optional) + excludePaths: [] + + # specifies paths to files that need to be includes for + # legal reasons such as LICENSE file. Defaults to few + # LICENSE, NOTICE and COPYRIGHT variations (optional) + legalPaths: [] + + # make subdirectory to be new root path within this asset (optional; v0.11.0+) + newRootPath: cfroutesync + + # set the permissions for this content directory (optional; v0.33.0+) + # by default content directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 +``` diff --git a/site/content/vendir/docs/v0.36.x/versions.md b/site/content/vendir/docs/v0.36.x/versions.md new file mode 100644 index 000000000..be4df2288 --- /dev/null +++ b/site/content/vendir/docs/v0.36.x/versions.md @@ -0,0 +1,112 @@ +--- + +title: Versions +--- + +Available in v0.12.0+. + +Vendir uses version selection in following places: + +- git source type for selection of `ref` based on Git tags +- image source type for selection of `tag` based on registry tags +- imgpkgBundle source type for selection of `tag` based on registry tags +- githubRelease source type for selection of `tag` based on tags + +--- +## VersionSelection type + +`VersionSelection` type may be used by other projects (such as kbld) for selection of versions in different contexts. All usage follows same spec: + +```yaml +# interpret versions according to semantic version spec. +# see semver section below for further details (required) +semver: + # list of semver constraints (optional) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional) + prereleases: + # select prerelease versions that include given identifiers (optional) + identifiers: [beta, rc] +``` + +--- +## Semver + +[github.com/k14s/semver/v4 package](https://github.com/k14s/semver) is used for parsing "semver" versions. +It's a fork of [k14s/semver](https://github.com/k14s/semver). + +For valid semver syntax refer to . (Commonly-used `v` prefix will be ignored during parsing) + +For constraints syntax refer to [k14s/semver's Ranges section](https://github.com/k14s/semver#ranges). + +By default prerelease versions are not included in selection. See examples for details. + +### Examples + +Any version greater than 0.4.0 _without_ prereleases. + +```yaml +semver: + constraints: ">0.4.0" +``` + +Any version greater than 0.4.0 _with_ all prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: {} +``` + +Any version greater than 0.4.0 _with_ only beta or rc prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: + identifiers: [beta, rc] +``` + +### sort-semver command + +`vendir tools sort-semver` command is included to showcase how vendir parses versions. + +- `--version` (`-v`) specifies one or more versions +- `--constraint` (`-c`) specifies zero or more constraints +- `--prerelease` specifies to include prereleases +- `--prerelease-identifier` specifies zero or more identifiers to match prereleases + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.1 v0.2.0 v0.3.0" +Versions + +Version +v0.0.1 +v0.1.0 +v0.2.0-pre.20 +v0.2.0+build.1 +v0.2.0 +v0.2.1 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` + +Note that by default prerelease versions are not included. Use configuration or flag to include them. + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.0 v0.3.0" -c ">=0.1.0" +Versions + +Version +v0.1.0 +v0.2.0+build.1 +v0.2.0 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` diff --git a/site/content/vendir/docs/v0.37.x/_index.md b/site/content/vendir/docs/v0.37.x/_index.md new file mode 100644 index 000000000..6eb006e24 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/_index.md @@ -0,0 +1,25 @@ +--- + +title: "About vendir" +toc: "false" +cascade: + version: v0.37.x + toc: "true" + type: docs + layout: docs +--- + +vendir allows to declaratively state what should be in a directory. It was designed to easily manage libraries for [ytt](/ytt); however, it is a generic tool and does not care how files within managed directories are used. + +Supported sources for fetching: + +- git +- hg (Mercurial) +- http +- image (image from OCI registry) +- imgpkgBundle (bundle from OCI registry) +- githubRelease +- helmChart +- directory + +Examples could be found in [carvel-vendir's `examples/` directory](https://github.com/carvel-dev/vendir/tree/develop/examples). diff --git a/site/content/vendir/docs/v0.37.x/github-release.md b/site/content/vendir/docs/v0.37.x/github-release.md new file mode 100644 index 000000000..54204e7d2 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/github-release.md @@ -0,0 +1,17 @@ +--- + +title: Github Release +--- + +vendir supports downloading software stored as a Github release. See [`vendir.yml` spec](vendir-spec.md) for how to configure. + +## Github API Rate Limiting + +If your public IP address is shared by multiple machines (e.g. workstations in an office), you may run into [Github rate limiting errors](https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#rate-limiting). vendir as of v0.8.0 supports providing "Personal access token" to increase Github API rate limits. You can specify it via an environment variable: + +```bash +$ export VENDIR_GITHUB_API_TOKEN=ghp_8c0a3... +$ vendir sync +``` + +To obtain personal access token go to [Github.com: Settings / Developer Settings / Personal access tokens](https://github.com/settings/tokens). During token creation, you will be prompted for selection of scopes, and in most cases there is no need to select any scopes because this token only used to identify API usage. For organizations that enable SSO, you will need to "Enable SSO" for created token. diff --git a/site/content/vendir/docs/v0.37.x/install.md b/site/content/vendir/docs/v0.37.x/install.md new file mode 100644 index 000000000..9174c19df --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/install.md @@ -0,0 +1,58 @@ +--- + +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 +$ vendir version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ vendir 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 vendir +$ vendir 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/vendir/releases), for example for 'vendir-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/vendir-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/vendir-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/vendir-darwin-amd64 /usr/local/bin/vendir + +# Make binary executable +$ chmod +x /usr/local/bin/vendir + +# Check its version +$ vendir version +``` diff --git a/site/content/vendir/docs/v0.37.x/security.md b/site/content/vendir/docs/v0.37.x/security.md new file mode 100644 index 000000000..73663e269 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/security.md @@ -0,0 +1,8 @@ +--- + +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `vendir`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/content/vendir/docs/v0.37.x/sync.md b/site/content/vendir/docs/v0.37.x/sync.md new file mode 100644 index 000000000..8dcedeb44 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/sync.md @@ -0,0 +1,76 @@ +--- + +title: Sync command +--- + +## Overview + +`vendir sync` command looks for [`vendir.yml`](vendir-spec.md) file in current directory for its configuration. `vendir.yml` specifies source of files for each managed directory. + +``` +# Run to sync directory contents as specified by vendir.yml +$ vendir sync +``` + +See [`vendir.yml` spec](vendir-spec.md) for its schema. + +## Sync with local changes override + +As of v0.7.0 you can use `--directory` flag to override contents of particular directories by pointing them to local directories. When this flag is specified other directories will not be synced (hence lock config is not going to be updated). + +``` +$ vendir sync --directory vendor/local-dir=local-dir-dev +``` + +## Sync with locks + +`vendir sync` writes [`vendir.lock.yml`](vendir-lock-spec.md) (next to `vendir.yml`) that contains resolved references: + +- for `git`, resolved SHAs are recorded +- for `hg`, resolved SHAs are recorded +- for `http`, nothing is recorded +- for `image`, resolved URL as a digest reference +- for `githubRelease`, permanent links are recorded +- for `helmChart`, resolved version +- for `directory`, nothing is recorded +- for `manual`, nothing is recorded + +To use these resolved references on top of `vendir.yml`, use `vendir sync -l`. + +## Syncing from different directory + +As of v0.22.0, you can use `--chdir` flag with `vendir sync` command to change current working directory of vendir before any syncing occurs. All other paths provided to `vendir sync` should be relative to the changed directory. + +## Caching + +`vendir` allows the users to cache OCI Images in their disk so as not to rely on access to the registry all the time. +To activate this feature the users need to set the environment variable `VENDIR_CACHE_DIR`. This variable should point +to the path where they want to store the OCI Images. + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ vendir sync +``` + +**Note:** Not all images can be cached. Only images that are referenced by SHA can be cached. + +The user can also specify what is the maximum size of the content to be cached, by setting the environment variable +`VENDIR_MAX_CACHE_SIZE`. The default value, when the variable is not provided is `1Mi` (1 Megabyte). + +The following are some accepted values: +``` +1 = 1 Byte +1Ki = 1 Kilobyte +1Mi = 1 Megabyte +1Gi = 1 Gigabyte +``` + +Example of usage: + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ export VENDIR_MAX_CACHE_SIZE=1Ki +$ vendir sync +``` diff --git a/site/content/vendir/docs/v0.37.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.37.x/vendir-lock-spec.md new file mode 100644 index 000000000..6276527b6 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/vendir-lock-spec.md @@ -0,0 +1,69 @@ +--- + +title: vendir.lock.yml spec +--- + +Lock file is generated by `vendir sync` and is placed next to related `vendir.yml`. + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: LockConfig + +directories: +- path: config/_ytt_lib + contents: + - path: github.com/cloudfoundry/cf-k8s-networking + + # present if this is managed manually + manual: {} + + # present if git + git: + # resolved checked out commit SHA + sha: 2b009b61fa8afb330a4302c694ee61b11104c54c + # resolved checked out commit title + commitTitle: 'feat: add /metrics prometheus scrapable endpoint...' + # resolved to a set of tags pointing to sha (v0.11.0+) + tags: + - "4.0.0" + + # present if hg (v0.22.0+) + hg: + # resolved checked out change SHA + sha: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # resolved checked out change title + changeSetTitle: 'Prevent wrapping filenames to preserve whitespace' + + # present if github release + githubRelease: + # resolved release url + url: https://api.github.com/repos/pivotal/kpack/releases/22747441 + + # present if helm chart (v0.11.0+) + helmChart: + appVersion: "5.0.7" + version: "10.5.7" + + # present if http + http: {} + + # present if image (v0.11.0+) + image: + # fully resolve image URL with digest + url: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if imgpkgBundle (v0.16.0+) + imgpkgBundle: + # fully resolve image URL with digest + image: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if inline (v0.11.0+) + inline: {} + + # present if this was sourced from local directory + directory: {} +``` diff --git a/site/content/vendir/docs/v0.37.x/vendir-spec.md b/site/content/vendir/docs/v0.37.x/vendir-spec.md new file mode 100644 index 000000000..d4333b693 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/vendir-spec.md @@ -0,0 +1,266 @@ +--- + +title: vendir.yml spec +--- + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: Config + +# declaration of minimum required vendir binary version (optional) +minimumRequiredVersion: 0.8.0 + +# one or more directories to manage with vendir +directories: +- # path is relative to `vendir` CLI working directory + path: config/_ytt_lib + + # set the permissions for this directory (optional; v0.33.0+) + # by default directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 + + contents: + - # path lives relative to directory path # (required) + path: github.com/cloudfoundry/cf-k8s-networking + + # skip fetching if the config for this path has not changed since the last sync + # optional, `false` by default, available since v0.36.0 + # use `vendir sync --lazy=false` to forcefully sync when needed + lazy: true + + # uses git to clone Git repository (optional) + git: + # http or ssh urls are supported (required) + url: https://github.com/cloudfoundry/cf-k8s-networking + # branch, tag, commit; origin is the name of the remote (required) + # optional if refSelection is specified (available in v0.11.0+) + ref: origin/master + # depth of commits to fetch; 0 (default) means everything (optional; v0.29.0+) + depth: 1 + # specifies a strategy to resolve to an explicit ref (optional; v0.11.0+) + refSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # skip downloading lfs files (optional) + lfsSkipSmudge: false + # skip SSL/TLS verification (optional) + dangerousSkipTLSVerify: false + # skip initializing any git submodules (optional; v0.28.0+) + skipInitSubmodules: false + # verify gpg signatures on commits or tags (optional; v0.12.0+) + verification: + publicKeysSecretRef: + name: my-git-gpg-auth + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-git-auth + + # uses hg to clone Mercurial repository (optional; v0.22.0+) + hg: + # http or ssh urls are supported (required) + url: https://hg.sr.ht/~sircmpwn/hg.sr.ht + # branch, tag, commit (required) + ref: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-hg-auth + + # fetches asset over HTTP (optional) + http: + # asset URL (required) + url: + # verification checksum (optional) + sha256: "" + # specifies name of a secret with basic auth details; + # secret may include 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-http-auth + # skip unpacking tar, tgz, and zip files; by default files are unpacked (optional) + disableUnpack: false + + # fetches asset from an image registry (optional; v0.11.0+) + image: + # image URL; could be plain, tagged or digest reference (required) + url: gcr.io/repo/image:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match url + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches imgpkg bundle from an image registry (optional; v0.16.0+) + imgpkgBundle: + # could be plain, tagged or digest reference (required) + image: gcr.io/repo/bundle:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in image key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match image + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches assets from a github release (optional) + githubRelease: + # slug for repository (org/repo) (required) + slug: k14s/kapp-controller + # use release tag (optional) + # optional if tagSelection is specified (available in v0.22.0+) + tag: v0.1.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # use latest published version (optional) + latest: true + # use exact release URL (optional) + url: https://api.github.com/repos/k14s/kapp-controller/releases/21912613 + # only download specific assets (optional; v0.12.0+) + assetNames: ["release*.yml"] + # checksums for downloaded files (optional) + # (if release text body contains checksums, it's not necessary + # to manually specify them here) + checksums: + release.yml: 26bf09c42d72ae448af3d1ee9f6a933c87c4ec81d04d37b30e1b6a339f5983a7 + # disables checking auto-found checksums for downloaded files (optional) + # (checksums are extracted from release's text body + # based on following format ` `) + disableAutoChecksumValidation: true + # specifies which archive to unpack for contents (optional) + unpackArchive: + # (required) + path: release.tgz + # specifies name of a secret with github auth details; + # secret may include 'token' key (optional) + secretRef: + # (required) + name: my-gh-auth + # Used to create the URL of the asset to download the metadata + # from the Github Release. (optional) + http: + # The url parameter of http can interpolate the tag of the GitHub release using the {tag} token. + url: https://dl.k8s.io/release/{tag}/bin/linux/amd64/kubectl + + # fetch Helm chart contents (optional; v0.11.0+) + helmChart: + # chart name (required) + name: stable/redis + # use specific chart version (string; optional) + version: "1.2.1" + # specifies Helm repository to fetch from (optional) + repository: + # repository url; supports exprimental oci helm fetch via + # oci:// scheme (required) + url: https://... + # specifies name of a secret with helm repo auth details; + # secret may include 'username', 'password'; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # as of v0.22.0+, 0 or 1 auth credential is expected within dockerconfigjson secret + # if >1 auth creds found, error will be returned. (currently registry hostname + # is not used when found in provide auth credential.) + secretRef: + # (required) + name: my-helm-auth + # specify helm binary version to use; + # '3' means binary 'helm3' needs to be on the path (optional) + helmVersion: "3" + + # copy contents from local directory (optional) + directory: + # local file system path relative to vendir.yml + path: some-path + + # states that directory specified by above path + # is managed by hand; nothing to do for vendir (optional) + manual: {} + + # specify contents inline within this file (optional; v0.11.0+) + inline: + # specifies mapping of paths to their content (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps (optional) + pathsFrom: + - secretRef: + # (required) + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + # (required) + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + + # includes paths specify what should be included. by default + # all paths are included (optional) + includePaths: + - cfroutesync/crds/**/* + - install/ytt/networking/**/* + + # exclude paths are "placed" on top of include paths (optional) + excludePaths: [] + + # specifies paths to files that need to be includes for + # legal reasons such as LICENSE file. Defaults to few + # LICENSE, NOTICE and COPYRIGHT variations (optional) + legalPaths: [] + + # make subdirectory to be new root path within this asset (optional; v0.11.0+) + newRootPath: cfroutesync + + # set the permissions for this content directory (optional; v0.33.0+) + # by default content directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 +``` diff --git a/site/content/vendir/docs/v0.37.x/versions.md b/site/content/vendir/docs/v0.37.x/versions.md new file mode 100644 index 000000000..be4df2288 --- /dev/null +++ b/site/content/vendir/docs/v0.37.x/versions.md @@ -0,0 +1,112 @@ +--- + +title: Versions +--- + +Available in v0.12.0+. + +Vendir uses version selection in following places: + +- git source type for selection of `ref` based on Git tags +- image source type for selection of `tag` based on registry tags +- imgpkgBundle source type for selection of `tag` based on registry tags +- githubRelease source type for selection of `tag` based on tags + +--- +## VersionSelection type + +`VersionSelection` type may be used by other projects (such as kbld) for selection of versions in different contexts. All usage follows same spec: + +```yaml +# interpret versions according to semantic version spec. +# see semver section below for further details (required) +semver: + # list of semver constraints (optional) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional) + prereleases: + # select prerelease versions that include given identifiers (optional) + identifiers: [beta, rc] +``` + +--- +## Semver + +[github.com/k14s/semver/v4 package](https://github.com/k14s/semver) is used for parsing "semver" versions. +It's a fork of [k14s/semver](https://github.com/k14s/semver). + +For valid semver syntax refer to . (Commonly-used `v` prefix will be ignored during parsing) + +For constraints syntax refer to [k14s/semver's Ranges section](https://github.com/k14s/semver#ranges). + +By default prerelease versions are not included in selection. See examples for details. + +### Examples + +Any version greater than 0.4.0 _without_ prereleases. + +```yaml +semver: + constraints: ">0.4.0" +``` + +Any version greater than 0.4.0 _with_ all prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: {} +``` + +Any version greater than 0.4.0 _with_ only beta or rc prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: + identifiers: [beta, rc] +``` + +### sort-semver command + +`vendir tools sort-semver` command is included to showcase how vendir parses versions. + +- `--version` (`-v`) specifies one or more versions +- `--constraint` (`-c`) specifies zero or more constraints +- `--prerelease` specifies to include prereleases +- `--prerelease-identifier` specifies zero or more identifiers to match prereleases + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.1 v0.2.0 v0.3.0" +Versions + +Version +v0.0.1 +v0.1.0 +v0.2.0-pre.20 +v0.2.0+build.1 +v0.2.0 +v0.2.1 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` + +Note that by default prerelease versions are not included. Use configuration or flag to include them. + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.0 v0.3.0" -c ">=0.1.0" +Versions + +Version +v0.1.0 +v0.2.0+build.1 +v0.2.0 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` diff --git a/site/content/vendir/docs/v0.38.x/_index.md b/site/content/vendir/docs/v0.38.x/_index.md new file mode 100644 index 000000000..ef50fe39d --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/_index.md @@ -0,0 +1,25 @@ +--- +aliases: [/vendir/docs/latest/] +title: "About vendir" +toc: "false" +cascade: + version: v0.38.x + toc: "true" + type: docs + layout: docs +--- + +vendir allows to declaratively state what should be in a directory. It was designed to easily manage libraries for [ytt](/ytt); however, it is a generic tool and does not care how files within managed directories are used. + +Supported sources for fetching: + +- git +- hg (Mercurial) +- http +- image (image from OCI registry) +- imgpkgBundle (bundle from OCI registry) +- githubRelease +- helmChart +- directory + +Examples could be found in [carvel-vendir's `examples/` directory](https://github.com/carvel-dev/vendir/tree/develop/examples). diff --git a/site/content/vendir/docs/v0.38.x/github-release.md b/site/content/vendir/docs/v0.38.x/github-release.md new file mode 100644 index 000000000..827addfe8 --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/github-release.md @@ -0,0 +1,17 @@ +--- +aliases: [/vendir/docs/latest/github-release] +title: Github Release +--- + +vendir supports downloading software stored as a Github release. See [`vendir.yml` spec](vendir-spec.md) for how to configure. + +## Github API Rate Limiting + +If your public IP address is shared by multiple machines (e.g. workstations in an office), you may run into [Github rate limiting errors](https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#rate-limiting). vendir as of v0.8.0 supports providing "Personal access token" to increase Github API rate limits. You can specify it via an environment variable: + +```bash +$ export VENDIR_GITHUB_API_TOKEN=ghp_8c0a3... +$ vendir sync +``` + +To obtain personal access token go to [Github.com: Settings / Developer Settings / Personal access tokens](https://github.com/settings/tokens). During token creation, you will be prompted for selection of scopes, and in most cases there is no need to select any scopes because this token only used to identify API usage. For organizations that enable SSO, you will need to "Enable SSO" for created token. diff --git a/site/content/vendir/docs/v0.38.x/install.md b/site/content/vendir/docs/v0.38.x/install.md new file mode 100644 index 000000000..0c0d5399f --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/install.md @@ -0,0 +1,58 @@ +--- +aliases: [/vendir/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 +$ vendir version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ vendir 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 vendir +$ vendir 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/vendir/releases), for example for 'vendir-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/vendir-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/vendir-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/vendir-darwin-amd64 /usr/local/bin/vendir + +# Make binary executable +$ chmod +x /usr/local/bin/vendir + +# Check its version +$ vendir version +``` diff --git a/site/content/vendir/docs/v0.38.x/security.md b/site/content/vendir/docs/v0.38.x/security.md new file mode 100644 index 000000000..0e42ae4c1 --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/vendir/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `vendir`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/content/vendir/docs/v0.38.x/sync.md b/site/content/vendir/docs/v0.38.x/sync.md new file mode 100644 index 000000000..fbb5703ef --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/sync.md @@ -0,0 +1,76 @@ +--- +aliases: [/vendir/docs/latest/sync] +title: Sync command +--- + +## Overview + +`vendir sync` command looks for [`vendir.yml`](vendir-spec.md) file in current directory for its configuration. `vendir.yml` specifies source of files for each managed directory. + +``` +# Run to sync directory contents as specified by vendir.yml +$ vendir sync +``` + +See [`vendir.yml` spec](vendir-spec.md) for its schema. + +## Sync with local changes override + +As of v0.7.0 you can use `--directory` flag to override contents of particular directories by pointing them to local directories. When this flag is specified other directories will not be synced (hence lock config is not going to be updated). + +``` +$ vendir sync --directory vendor/local-dir=local-dir-dev +``` + +## Sync with locks + +`vendir sync` writes [`vendir.lock.yml`](vendir-lock-spec.md) (next to `vendir.yml`) that contains resolved references: + +- for `git`, resolved SHAs are recorded +- for `hg`, resolved SHAs are recorded +- for `http`, nothing is recorded +- for `image`, resolved URL as a digest reference +- for `githubRelease`, permanent links are recorded +- for `helmChart`, resolved version +- for `directory`, nothing is recorded +- for `manual`, nothing is recorded + +To use these resolved references on top of `vendir.yml`, use `vendir sync -l`. + +## Syncing from different directory + +As of v0.22.0, you can use `--chdir` flag with `vendir sync` command to change current working directory of vendir before any syncing occurs. All other paths provided to `vendir sync` should be relative to the changed directory. + +## Caching + +`vendir` allows the users to cache OCI Images in their disk so as not to rely on access to the registry all the time. +To activate this feature the users need to set the environment variable `VENDIR_CACHE_DIR`. This variable should point +to the path where they want to store the OCI Images. + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ vendir sync +``` + +**Note:** Not all images can be cached. Only images that are referenced by SHA can be cached. + +The user can also specify what is the maximum size of the content to be cached, by setting the environment variable +`VENDIR_MAX_CACHE_SIZE`. The default value, when the variable is not provided is `1Mi` (1 Megabyte). + +The following are some accepted values: +``` +1 = 1 Byte +1Ki = 1 Kilobyte +1Mi = 1 Megabyte +1Gi = 1 Gigabyte +``` + +Example of usage: + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ export VENDIR_MAX_CACHE_SIZE=1Ki +$ vendir sync +``` diff --git a/site/content/vendir/docs/v0.38.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.38.x/vendir-lock-spec.md new file mode 100644 index 000000000..027838675 --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/vendir-lock-spec.md @@ -0,0 +1,69 @@ +--- +aliases: [/vendir/docs/latest/vendir-lock-spec] +title: vendir.lock.yml spec +--- + +Lock file is generated by `vendir sync` and is placed next to related `vendir.yml`. + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: LockConfig + +directories: +- path: config/_ytt_lib + contents: + - path: github.com/cloudfoundry/cf-k8s-networking + + # present if this is managed manually + manual: {} + + # present if git + git: + # resolved checked out commit SHA + sha: 2b009b61fa8afb330a4302c694ee61b11104c54c + # resolved checked out commit title + commitTitle: 'feat: add /metrics prometheus scrapable endpoint...' + # resolved to a set of tags pointing to sha (v0.11.0+) + tags: + - "4.0.0" + + # present if hg (v0.22.0+) + hg: + # resolved checked out change SHA + sha: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # resolved checked out change title + changeSetTitle: 'Prevent wrapping filenames to preserve whitespace' + + # present if github release + githubRelease: + # resolved release url + url: https://api.github.com/repos/pivotal/kpack/releases/22747441 + + # present if helm chart (v0.11.0+) + helmChart: + appVersion: "5.0.7" + version: "10.5.7" + + # present if http + http: {} + + # present if image (v0.11.0+) + image: + # fully resolve image URL with digest + url: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if imgpkgBundle (v0.16.0+) + imgpkgBundle: + # fully resolve image URL with digest + image: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if inline (v0.11.0+) + inline: {} + + # present if this was sourced from local directory + directory: {} +``` diff --git a/site/content/vendir/docs/v0.38.x/vendir-spec.md b/site/content/vendir/docs/v0.38.x/vendir-spec.md new file mode 100644 index 000000000..8fcc37807 --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/vendir-spec.md @@ -0,0 +1,266 @@ +--- +aliases: [/vendir/docs/latest/vendir-spec] +title: vendir.yml spec +--- + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: Config + +# declaration of minimum required vendir binary version (optional) +minimumRequiredVersion: 0.8.0 + +# one or more directories to manage with vendir +directories: +- # path is relative to `vendir` CLI working directory + path: config/_ytt_lib + + # set the permissions for this directory (optional; v0.33.0+) + # by default directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 + + contents: + - # path lives relative to directory path # (required) + path: github.com/cloudfoundry/cf-k8s-networking + + # skip fetching if the config for this path has not changed since the last sync + # optional, `false` by default, available since v0.36.0 + # use `vendir sync --lazy=false` to forcefully sync when needed + lazy: true + + # uses git to clone Git repository (optional) + git: + # http or ssh urls are supported (required) + url: https://github.com/cloudfoundry/cf-k8s-networking + # branch, tag, commit; origin is the name of the remote (required) + # optional if refSelection is specified (available in v0.11.0+) + ref: origin/master + # depth of commits to fetch; 0 (default) means everything (optional; v0.29.0+) + depth: 1 + # specifies a strategy to resolve to an explicit ref (optional; v0.11.0+) + refSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # skip downloading lfs files (optional) + lfsSkipSmudge: false + # skip SSL/TLS verification (optional) + dangerousSkipTLSVerify: false + # skip initializing any git submodules (optional; v0.28.0+) + skipInitSubmodules: false + # verify gpg signatures on commits or tags (optional; v0.12.0+) + verification: + publicKeysSecretRef: + name: my-git-gpg-auth + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-git-auth + + # uses hg to clone Mercurial repository (optional; v0.22.0+) + hg: + # http or ssh urls are supported (required) + url: https://hg.sr.ht/~sircmpwn/hg.sr.ht + # branch, tag, commit (required) + ref: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-hg-auth + + # fetches asset over HTTP (optional) + http: + # asset URL (required) + url: + # verification checksum (optional) + sha256: "" + # specifies name of a secret with basic auth details; + # secret may include 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-http-auth + # skip unpacking tar, tgz, and zip files; by default files are unpacked (optional) + disableUnpack: false + + # fetches asset from an image registry (optional; v0.11.0+) + image: + # image URL; could be plain, tagged or digest reference (required) + url: gcr.io/repo/image:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match url + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches imgpkg bundle from an image registry (optional; v0.16.0+) + imgpkgBundle: + # could be plain, tagged or digest reference (required) + image: gcr.io/repo/bundle:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in image key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match image + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerouSkipTLSVerify: false + + # fetches assets from a github release (optional) + githubRelease: + # slug for repository (org/repo) (required) + slug: k14s/kapp-controller + # use release tag (optional) + # optional if tagSelection is specified (available in v0.22.0+) + tag: v0.1.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # use latest published version (optional) + latest: true + # use exact release URL (optional) + url: https://api.github.com/repos/k14s/kapp-controller/releases/21912613 + # only download specific assets (optional; v0.12.0+) + assetNames: ["release*.yml"] + # checksums for downloaded files (optional) + # (if release text body contains checksums, it's not necessary + # to manually specify them here) + checksums: + release.yml: 26bf09c42d72ae448af3d1ee9f6a933c87c4ec81d04d37b30e1b6a339f5983a7 + # disables checking auto-found checksums for downloaded files (optional) + # (checksums are extracted from release's text body + # based on following format ` `) + disableAutoChecksumValidation: true + # specifies which archive to unpack for contents (optional) + unpackArchive: + # (required) + path: release.tgz + # specifies name of a secret with github auth details; + # secret may include 'token' key (optional) + secretRef: + # (required) + name: my-gh-auth + # Used to create the URL of the asset to download the metadata + # from the Github Release. (optional) + http: + # The url parameter of http can interpolate the tag of the GitHub release using the {tag} token. + url: https://dl.k8s.io/release/{tag}/bin/linux/amd64/kubectl + + # fetch Helm chart contents (optional; v0.11.0+) + helmChart: + # chart name (required) + name: stable/redis + # use specific chart version (string; optional) + version: "1.2.1" + # specifies Helm repository to fetch from (optional) + repository: + # repository url; supports exprimental oci helm fetch via + # oci:// scheme (required) + url: https://... + # specifies name of a secret with helm repo auth details; + # secret may include 'username', 'password'; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # as of v0.22.0+, 0 or 1 auth credential is expected within dockerconfigjson secret + # if >1 auth creds found, error will be returned. (currently registry hostname + # is not used when found in provide auth credential.) + secretRef: + # (required) + name: my-helm-auth + # specify helm binary version to use; + # '3' means binary 'helm3' needs to be on the path (optional) + helmVersion: "3" + + # copy contents from local directory (optional) + directory: + # local file system path relative to vendir.yml + path: some-path + + # states that directory specified by above path + # is managed by hand; nothing to do for vendir (optional) + manual: {} + + # specify contents inline within this file (optional; v0.11.0+) + inline: + # specifies mapping of paths to their content (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps (optional) + pathsFrom: + - secretRef: + # (required) + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + # (required) + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + + # includes paths specify what should be included. by default + # all paths are included (optional) + includePaths: + - cfroutesync/crds/**/* + - install/ytt/networking/**/* + + # exclude paths are "placed" on top of include paths (optional) + excludePaths: [] + + # specifies paths to files that need to be includes for + # legal reasons such as LICENSE file. Defaults to few + # LICENSE, NOTICE and COPYRIGHT variations (optional) + legalPaths: [] + + # make subdirectory to be new root path within this asset (optional; v0.11.0+) + newRootPath: cfroutesync + + # set the permissions for this content directory (optional; v0.33.0+) + # by default content directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 +``` diff --git a/site/content/vendir/docs/v0.38.x/versions.md b/site/content/vendir/docs/v0.38.x/versions.md new file mode 100644 index 000000000..3a5791f62 --- /dev/null +++ b/site/content/vendir/docs/v0.38.x/versions.md @@ -0,0 +1,112 @@ +--- +aliases: [/vendir/docs/latest/versions] +title: Versions +--- + +Available in v0.12.0+. + +Vendir uses version selection in following places: + +- git source type for selection of `ref` based on Git tags +- image source type for selection of `tag` based on registry tags +- imgpkgBundle source type for selection of `tag` based on registry tags +- githubRelease source type for selection of `tag` based on tags + +--- +## VersionSelection type + +`VersionSelection` type may be used by other projects (such as kbld) for selection of versions in different contexts. All usage follows same spec: + +```yaml +# interpret versions according to semantic version spec. +# see semver section below for further details (required) +semver: + # list of semver constraints (optional) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional) + prereleases: + # select prerelease versions that include given identifiers (optional) + identifiers: [beta, rc] +``` + +--- +## Semver + +[github.com/k14s/semver/v4 package](https://github.com/k14s/semver) is used for parsing "semver" versions. +It's a fork of [k14s/semver](https://github.com/k14s/semver). + +For valid semver syntax refer to . (Commonly-used `v` prefix will be ignored during parsing) + +For constraints syntax refer to [k14s/semver's Ranges section](https://github.com/k14s/semver#ranges). + +By default prerelease versions are not included in selection. See examples for details. + +### Examples + +Any version greater than 0.4.0 _without_ prereleases. + +```yaml +semver: + constraints: ">0.4.0" +``` + +Any version greater than 0.4.0 _with_ all prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: {} +``` + +Any version greater than 0.4.0 _with_ only beta or rc prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: + identifiers: [beta, rc] +``` + +### sort-semver command + +`vendir tools sort-semver` command is included to showcase how vendir parses versions. + +- `--version` (`-v`) specifies one or more versions +- `--constraint` (`-c`) specifies zero or more constraints +- `--prerelease` specifies to include prereleases +- `--prerelease-identifier` specifies zero or more identifiers to match prereleases + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.1 v0.2.0 v0.3.0" +Versions + +Version +v0.0.1 +v0.1.0 +v0.2.0-pre.20 +v0.2.0+build.1 +v0.2.0 +v0.2.1 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` + +Note that by default prerelease versions are not included. Use configuration or flag to include them. + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.0 v0.3.0" -c ">=0.1.0" +Versions + +Version +v0.1.0 +v0.2.0+build.1 +v0.2.0 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` diff --git a/site/data/imgpkg/docs/imgpkg-v0-39-x-toc.yml b/site/data/imgpkg/docs/imgpkg-v0-39-x-toc.yml new file mode 100644 index 000000000..a04ec6eeb --- /dev/null +++ b/site/data/imgpkg/docs/imgpkg-v0-39-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 d70dfd8fc..371c344b1 100644 --- a/site/data/imgpkg/docs/toc-mapping.yml +++ b/site/data/imgpkg/docs/toc-mapping.yml @@ -14,3 +14,4 @@ v0.35.x: imgpkg-v0-35-x-toc v0.36.x: imgpkg-v0-36-x-toc v0.37.x: imgpkg-v0-37-x-toc v0.38.x: imgpkg-v0-38-x-toc +v0.39.x: imgpkg-v0-39-x-toc diff --git a/site/data/kapp-controller/docs/kapp-controller-v0-49-x-toc.yml b/site/data/kapp-controller/docs/kapp-controller-v0-49-x-toc.yml new file mode 100644 index 000000000..63a63df06 --- /dev/null +++ b/site/data/kapp-controller/docs/kapp-controller-v0-49-x-toc.yml @@ -0,0 +1,75 @@ +toc: + - title: Introduction + subfolderitems: + - page: About kapp-controller + url: / + - page: Install + url: /install + - title: Continuous Delivery + subfolderitems: + - page: App CR Overview + url: /app-overview + - page: App CR Detailed Spec + url: /app-spec + - page: Install an application + url: /walkthrough + - page: Example Usage + url: /app-examples + - page: Integration with Mozilla's sops + url: /sops + - page: Security Model + url: /security-model + - title: Package Management + subfolderitems: + - page: Concepts & CRDs + url: /packaging + - page: "Tutorial: Create & Install a Package" + url: /packaging-tutorial + - page: "Consuming Packages using the CLI" + url: /kctrl-package-tutorial + - page: Authoring packages using the CLI + url: /kctrl-package-authoring + - page: OSS Carvel Packages + url: /oss-packages + - page: Artifact Formats + url: /packaging-artifact-formats + - page: Consumer Concepts + url: /package-consumer-concepts + - page: Overlays with PackageInstall + url: /package-install-extensions + - page: Air-gapped installations + url: /air-gapped-workflow + - page: Private registry authentication + url: /private-registry-auth + - page: Package Management with GitOps + url: /packaging-gitops + - title: Advanced Topics + subfolderitems: + - page: Debugging CRs + url: /debugging-crs + - page: Controller Configuration + url: /controller-config + - page: Controller Startup + url: /startup + - page: Debugging kapp-controller + url: /debugging-kc + - title: Kctrl (CLI) Commands Reference + subfolderitems: + - page: Management Commands + url: /management-command + - page: Authoring Commands + url: /authoring-command + - title: FAQ + subfolderitems: + - page: kapp-controller FAQ + url: /faq + - page: kctrl FAQ + url: /kctrl-faq + - 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 diff --git a/site/data/kapp-controller/docs/toc-mapping.yml b/site/data/kapp-controller/docs/toc-mapping.yml index a5ed43e0d..23996ce68 100644 --- a/site/data/kapp-controller/docs/toc-mapping.yml +++ b/site/data/kapp-controller/docs/toc-mapping.yml @@ -18,3 +18,4 @@ v0.45.0: kapp-controller-v0-45-0-toc v0.46.0: kapp-controller-v0-46-0-toc v0.47.x: kapp-controller-v0-47-x-toc v0.48.x: kapp-controller-v0-48-x-toc +v0.49.x: kapp-controller-v0-49-x-toc diff --git a/site/data/vendir/docs/toc-mapping.yml b/site/data/vendir/docs/toc-mapping.yml index 89f857b18..57ad57917 100644 --- a/site/data/vendir/docs/toc-mapping.yml +++ b/site/data/vendir/docs/toc-mapping.yml @@ -10,3 +10,6 @@ v0.32.0: vendir-v0-32-0-toc v0.33.x: vendir-v0-33-x-toc v0.34.x: vendir-v0-34-x-toc v0.35.x: vendir-v0-35-x-toc +v0.36.x: vendir-v0-36-x-toc +v0.37.x: vendir-v0-37-x-toc +v0.38.x: vendir-v0-38-x-toc diff --git a/site/data/vendir/docs/vendir-v0-36-x-toc.yml b/site/data/vendir/docs/vendir-v0-36-x-toc.yml new file mode 100644 index 000000000..428a67fb5 --- /dev/null +++ b/site/data/vendir/docs/vendir-v0-36-x-toc.yml @@ -0,0 +1,29 @@ +toc: + - title: Introduction + subfolderitems: + - page: About vendir + url: / + - page: Install + url: /install + - title: Reference + subfolderitems: + - page: Sync command + url: /sync + - page: vendir.yml Spec + url: /vendir-spec + - page: vendir.lock.yml Spec + url: /vendir-lock-spec + - page: Versions + url: /versions + - page: Github Release + url: /github-release + - title: FAQ + subfolderitems: + - 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 diff --git a/site/data/vendir/docs/vendir-v0-37-x-toc.yml b/site/data/vendir/docs/vendir-v0-37-x-toc.yml new file mode 100644 index 000000000..428a67fb5 --- /dev/null +++ b/site/data/vendir/docs/vendir-v0-37-x-toc.yml @@ -0,0 +1,29 @@ +toc: + - title: Introduction + subfolderitems: + - page: About vendir + url: / + - page: Install + url: /install + - title: Reference + subfolderitems: + - page: Sync command + url: /sync + - page: vendir.yml Spec + url: /vendir-spec + - page: vendir.lock.yml Spec + url: /vendir-lock-spec + - page: Versions + url: /versions + - page: Github Release + url: /github-release + - title: FAQ + subfolderitems: + - 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 diff --git a/site/data/vendir/docs/vendir-v0-38-x-toc.yml b/site/data/vendir/docs/vendir-v0-38-x-toc.yml new file mode 100644 index 000000000..428a67fb5 --- /dev/null +++ b/site/data/vendir/docs/vendir-v0-38-x-toc.yml @@ -0,0 +1,29 @@ +toc: + - title: Introduction + subfolderitems: + - page: About vendir + url: / + - page: Install + url: /install + - title: Reference + subfolderitems: + - page: Sync command + url: /sync + - page: vendir.yml Spec + url: /vendir-spec + - page: vendir.lock.yml Spec + url: /vendir-lock-spec + - page: Versions + url: /versions + - page: Github Release + url: /github-release + - title: FAQ + subfolderitems: + - 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