diff --git a/site/config.yaml b/site/config.yaml index 824376ce0..72d640392 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -72,16 +72,17 @@ params: name: kapp-controller short_name: kc root_link: /kapp-controller/ - latest_docs_link: /kapp-controller/docs/latest/ + latest_docs_link: /kapp-controller/docs/v0.31.0/ github_url: https://github.com/vmware-tanzu/carvel-kapp-controller search: true search_index_name: carvel search_api_key: 582b1408d7a3fe145c0f84f48ca03755 search_tag: kapp-controller - versioning: false - version_latest: latest + versioning: true + version_latest: v0.31.0 versions: - - latest + - develop + - v0.31.0 vendir: name: vendir short_name: vendir diff --git a/site/content/kapp-controller/docs/latest/_index.md b/site/content/kapp-controller/docs/develop/_index.md similarity index 97% rename from site/content/kapp-controller/docs/latest/_index.md rename to site/content/kapp-controller/docs/develop/_index.md index d7df95cb9..6a852213c 100644 --- a/site/content/kapp-controller/docs/latest/_index.md +++ b/site/content/kapp-controller/docs/develop/_index.md @@ -2,7 +2,7 @@ title: "About kapp-controller" toc: "false" cascade: - version: latest + version: develop toc: "true" type: docs layout: docs @@ -32,4 +32,4 @@ With its layered approach, kapp-controller can be used as: 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. \ No newline at end of file +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/latest/air-gapped-workflow.md b/site/content/kapp-controller/docs/develop/air-gapped-workflow.md similarity index 100% rename from site/content/kapp-controller/docs/latest/air-gapped-workflow.md rename to site/content/kapp-controller/docs/develop/air-gapped-workflow.md diff --git a/site/content/kapp-controller/docs/latest/app-examples.md b/site/content/kapp-controller/docs/develop/app-examples.md similarity index 100% rename from site/content/kapp-controller/docs/latest/app-examples.md rename to site/content/kapp-controller/docs/develop/app-examples.md diff --git a/site/content/kapp-controller/docs/latest/app-overview.md b/site/content/kapp-controller/docs/develop/app-overview.md similarity index 93% rename from site/content/kapp-controller/docs/latest/app-overview.md rename to site/content/kapp-controller/docs/develop/app-overview.md index f7a41860e..e634f6599 100644 --- a/site/content/kapp-controller/docs/latest/app-overview.md +++ b/site/content/kapp-controller/docs/develop/app-overview.md @@ -20,7 +20,7 @@ Full App CR spec can be found [here](app-spec.md). 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](https://carvel.dev/imgpkg/docs/latest/resources/#bundle) from registry (available in v0.17.0+) +- `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 @@ -69,4 +69,4 @@ App CR supports multiple templating, overlaying, and data transformation tools t App CR uses Carvel's `kapp` CLI to deploy. -- `kapp`: uses [kapp](/kapp) to deploy resources \ No newline at end of file +- `kapp`: uses [kapp](/kapp) to deploy resources diff --git a/site/content/kapp-controller/docs/latest/app-spec.md b/site/content/kapp-controller/docs/develop/app-spec.md similarity index 100% rename from site/content/kapp-controller/docs/latest/app-spec.md rename to site/content/kapp-controller/docs/develop/app-spec.md diff --git a/site/content/kapp-controller/docs/latest/controller-config.md b/site/content/kapp-controller/docs/develop/controller-config.md similarity index 100% rename from site/content/kapp-controller/docs/latest/controller-config.md rename to site/content/kapp-controller/docs/develop/controller-config.md diff --git a/site/content/kapp-controller/docs/latest/debugging-crs.md b/site/content/kapp-controller/docs/develop/debugging-crs.md similarity index 100% rename from site/content/kapp-controller/docs/latest/debugging-crs.md rename to site/content/kapp-controller/docs/develop/debugging-crs.md diff --git a/site/content/kapp-controller/docs/latest/debugging-kc.md b/site/content/kapp-controller/docs/develop/debugging-kc.md similarity index 100% rename from site/content/kapp-controller/docs/latest/debugging-kc.md rename to site/content/kapp-controller/docs/develop/debugging-kc.md diff --git a/site/content/kapp-controller/docs/latest/dev.md b/site/content/kapp-controller/docs/develop/dev.md similarity index 100% rename from site/content/kapp-controller/docs/latest/dev.md rename to site/content/kapp-controller/docs/develop/dev.md diff --git a/site/content/kapp-controller/docs/latest/faq.md b/site/content/kapp-controller/docs/develop/faq.md similarity index 99% rename from site/content/kapp-controller/docs/latest/faq.md rename to site/content/kapp-controller/docs/develop/faq.md index 416abce26..de7a52d26 100644 --- a/site/content/kapp-controller/docs/latest/faq.md +++ b/site/content/kapp-controller/docs/develop/faq.md @@ -93,4 +93,4 @@ This is the recommended workflow: 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) \ No newline at end of file +- [@ytt:yaml module](../../../ytt/docs/latest/lang-ref-ytt.md#yaml) diff --git a/site/content/kapp-controller/docs/latest/install.md b/site/content/kapp-controller/docs/develop/install.md similarity index 97% rename from site/content/kapp-controller/docs/latest/install.md rename to site/content/kapp-controller/docs/develop/install.md index 9236392dd..365c1b281 100644 --- a/site/content/kapp-controller/docs/latest/install.md +++ b/site/content/kapp-controller/docs/develop/install.md @@ -56,7 +56,7 @@ rules: - use ``` 3. Set the `IMGPKG_ENABLE_IAAS_AUTH` [environment - variable](https://carvel.dev/imgpkg/docs/latest/auth/#via-iaas) to false. + variable](/imgpkg/docs/latest/auth/#via-iaas) to false. ### Kubernetes versions < 1.20 diff --git a/site/content/kapp-controller/docs/latest/oss-packages.md b/site/content/kapp-controller/docs/develop/oss-packages.md similarity index 100% rename from site/content/kapp-controller/docs/latest/oss-packages.md rename to site/content/kapp-controller/docs/develop/oss-packages.md diff --git a/site/content/kapp-controller/docs/latest/package-consumer-concepts.md b/site/content/kapp-controller/docs/develop/package-consumer-concepts.md similarity index 100% rename from site/content/kapp-controller/docs/latest/package-consumer-concepts.md rename to site/content/kapp-controller/docs/develop/package-consumer-concepts.md diff --git a/site/content/kapp-controller/docs/latest/package-install-extensions.md b/site/content/kapp-controller/docs/develop/package-install-extensions.md similarity index 100% rename from site/content/kapp-controller/docs/latest/package-install-extensions.md rename to site/content/kapp-controller/docs/develop/package-install-extensions.md diff --git a/site/content/kapp-controller/docs/latest/packaging-artifact-formats.md b/site/content/kapp-controller/docs/develop/packaging-artifact-formats.md similarity index 100% rename from site/content/kapp-controller/docs/latest/packaging-artifact-formats.md rename to site/content/kapp-controller/docs/develop/packaging-artifact-formats.md diff --git a/site/content/kapp-controller/docs/latest/packaging-gitops.md b/site/content/kapp-controller/docs/develop/packaging-gitops.md similarity index 100% rename from site/content/kapp-controller/docs/latest/packaging-gitops.md rename to site/content/kapp-controller/docs/develop/packaging-gitops.md diff --git a/site/content/kapp-controller/docs/latest/packaging-tutorial.md b/site/content/kapp-controller/docs/develop/packaging-tutorial.md similarity index 91% rename from site/content/kapp-controller/docs/latest/packaging-tutorial.md rename to site/content/kapp-controller/docs/develop/packaging-tutorial.md index 6a9eb848e..03f640246 100644 --- a/site/content/kapp-controller/docs/latest/packaging-tutorial.md +++ b/site/content/kapp-controller/docs/develop/packaging-tutorial.md @@ -171,10 +171,10 @@ EOF ``` ## Creating a Package: Structuring our contents -We'll create an [imgpkg bundle](https://carvel.dev/imgpkg/docs/latest/resources/#bundle) +We'll create an [imgpkg bundle](/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 +The [package bundle format](packaging-artifact-formats.md#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: @@ -190,7 +190,7 @@ 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). +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](/imgpkg/docs/latest/resources/#imageslock-configuration). Once these files have been added, our package contents bundle is ready to be pushed! @@ -299,17 +299,17 @@ 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. +This section informs kapp-controller of the actions required to install the packaged software, so take a look at the [app-spec](app-spec.md) 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) +A [package repository](packaging.md#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). +Our recommended way to make a package repository is via an [imgpkg bundle](/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. +The [PackageRepository bundle format](packaging-artifact-formats.md#package-repository-bundle) describes purpose of each directory and general recommendations. Lets start by creating the needed directories: @@ -371,7 +371,7 @@ 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.) +[demo video](https://www.youtube.com/watch?v=PmwkicgEKQE) and [website](private-registry-auth.md) 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 @@ -446,11 +446,11 @@ 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). +More information on PackageInstall versioning can be found [here](packaging.md#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/) +Finally, to install the above package, we will also need to create `default-ns-sa` service account (refer to [Security model](security-model.md) 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/vmware-tanzu/carvel-kapp-controller/develop/examples/rbac/default-ns.yml -y @@ -480,4 +480,4 @@ curl localhost:3000 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/) +See the full docs for [Package Management with kapp-controller](packaging.md) diff --git a/site/content/kapp-controller/docs/latest/packaging.md b/site/content/kapp-controller/docs/develop/packaging.md similarity index 100% rename from site/content/kapp-controller/docs/latest/packaging.md rename to site/content/kapp-controller/docs/develop/packaging.md diff --git a/site/content/kapp-controller/docs/latest/private-registry-auth.md b/site/content/kapp-controller/docs/develop/private-registry-auth.md similarity index 100% rename from site/content/kapp-controller/docs/latest/private-registry-auth.md rename to site/content/kapp-controller/docs/develop/private-registry-auth.md diff --git a/site/content/kapp-controller/docs/latest/security-model.md b/site/content/kapp-controller/docs/develop/security-model.md similarity index 100% rename from site/content/kapp-controller/docs/latest/security-model.md rename to site/content/kapp-controller/docs/develop/security-model.md diff --git a/site/content/kapp-controller/docs/latest/security.md b/site/content/kapp-controller/docs/develop/security.md similarity index 100% rename from site/content/kapp-controller/docs/latest/security.md rename to site/content/kapp-controller/docs/develop/security.md diff --git a/site/content/kapp-controller/docs/latest/sops.md b/site/content/kapp-controller/docs/develop/sops.md similarity index 100% rename from site/content/kapp-controller/docs/latest/sops.md rename to site/content/kapp-controller/docs/develop/sops.md diff --git a/site/content/kapp-controller/docs/latest/startup.md b/site/content/kapp-controller/docs/develop/startup.md similarity index 100% rename from site/content/kapp-controller/docs/latest/startup.md rename to site/content/kapp-controller/docs/develop/startup.md diff --git a/site/content/kapp-controller/docs/latest/walkthrough.md b/site/content/kapp-controller/docs/develop/walkthrough.md similarity index 100% rename from site/content/kapp-controller/docs/latest/walkthrough.md rename to site/content/kapp-controller/docs/develop/walkthrough.md diff --git a/site/content/kapp-controller/docs/v0.31.0/_index.md b/site/content/kapp-controller/docs/v0.31.0/_index.md new file mode 100644 index 000000000..274036d6a --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/_index.md @@ -0,0 +1,35 @@ +--- +title: "About kapp-controller" +toc: "false" +cascade: + version: v0.31.0 + 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)! + +#### 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.31.0/air-gapped-workflow.md b/site/content/kapp-controller/docs/v0.31.0/air-gapped-workflow.md new file mode 100644 index 000000000..1cc476df7 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/air-gapped-workflow.md @@ -0,0 +1,74 @@ +--- +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 transfered 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`: +* Get to a location that can access both registries. If there is no such location, you will have to use `Option 2` steps. +* [Authenticate](/imgpkg/docs/latest/auth.md) with both source and destination registries +* Run `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`: +* Get to a location that can access the source registry +* [Authenticate](/imgpkg/docs/latest/auth.md) with the source registry +* Run `imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-tar /tmp/my-image.tar` +* Make sure the tar file is in a location that has access to the destination registry +* Authenticate with the destination registry +* Run `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.31.0/app-examples.md b/site/content/kapp-controller/docs/v0.31.0/app-examples.md new file mode 100644 index 000000000..6bd6e9ed9 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/app-examples.md @@ -0,0 +1,107 @@ +--- +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 +pec: + 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: {} +``` \ No newline at end of file diff --git a/site/content/kapp-controller/docs/v0.31.0/app-overview.md b/site/content/kapp-controller/docs/v0.31.0/app-overview.md new file mode 100644 index 000000000..e634f6599 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/app-overview.md @@ -0,0 +1,72 @@ +--- +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 rended 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.31.0/app-spec.md b/site/content/kapp-controller/docs/v0.31.0/app-spec.md new file mode 100644 index 000000000..252c64943 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/app-spec.md @@ -0,0 +1,332 @@ +--- +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 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 + + # 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] + + # 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] + + # 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 + + # 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] + + # 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 + + # 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: + 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 + # 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 + + # 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 that provide values (optional) + valuesFrom: + - secretRef: + name: secret-name + - configMapRef: + name: cfgmap-name + - path: values/shared.yml + + # use sops to decrypt *.sops.yml files (optional; v0.11.0+) + - sops: + # use PGP to decrypt files (required) + pgp: + # secret with private armored PGP private keys (required) + privateKeysSecretRef: + # (required) + name: pgp-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 popuated 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 + 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.31.0/controller-config.md b/site/content/kapp-controller/docs/v0.31.0/controller-config.md new file mode 100644 index 000000000..66ffe7e8f --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/controller-config.md @@ -0,0 +1,87 @@ +--- +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). + +## 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" +``` + +## 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.31.0/debugging-crs.md b/site/content/kapp-controller/docs/v0.31.0/debugging-crs.md new file mode 100644 index 000000000..d9499a7c5 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/debugging-crs.md @@ -0,0 +1,125 @@ +--- +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.31.0/debugging-kc.md b/site/content/kapp-controller/docs/v0.31.0/debugging-kc.md new file mode 100644 index 000000000..829f09a53 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/debugging-kc.md @@ -0,0 +1,12 @@ +--- +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.31.0/dev.md b/site/content/kapp-controller/docs/v0.31.0/dev.md new file mode 100644 index 000000000..51bba53dd --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/dev.md @@ -0,0 +1,23 @@ +--- +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.31.0/faq.md b/site/content/kapp-controller/docs/v0.31.0/faq.md new file mode 100644 index 000000000..de7a52d26 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/faq.md @@ -0,0 +1,96 @@ +--- +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/vmware-tanzu/carvel-kapp-controller/blob/d94984a77fa907ac5ecc681e9a842b9877766a6b/test/e2e/pause_test.go#L91)) +or fiddle with spec.syncPeriod ([example]( +https://github.com/vmware-tanzu/carvel-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.31.0/install.md b/site/content/kapp-controller/docs/v0.31.0/install.md new file mode 100644 index 000000000..365c1b281 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/install.md @@ -0,0 +1,75 @@ +--- +title: Install +--- + +Grab the latest copy of YAML from the [Releases page](https://github.com/vmware-tanzu/carvel-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/vmware-tanzu/carvel-kapp-controller/releases/latest/download/release.yml +``` + +or + +```bash +$ kubectl apply -f https://github.com/vmware-tanzu/carvel-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 that allows uids/gids that kapp deployment uses +(currently uid 1000; value given for `runAsUser` in the release.yaml for your +version of kapp-controller). +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. Set the `IMGPKG_ENABLE_IAAS_AUTH` [environment + variable](/imgpkg/docs/latest/auth/#via-iaas) to false. + + +### 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. diff --git a/site/content/kapp-controller/docs/v0.31.0/oss-packages.md b/site/content/kapp-controller/docs/v0.31.0/oss-packages.md new file mode 100644 index 000000000..84d9d2005 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/oss-packages.md @@ -0,0 +1,23 @@ +--- +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/vmware-tanzu/carvel/main/site/content/kapp-controller/docs/latest/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 +``` \ No newline at end of file diff --git a/site/content/kapp-controller/docs/v0.31.0/package-consumer-concepts.md b/site/content/kapp-controller/docs/v0.31.0/package-consumer-concepts.md new file mode 100644 index 000000000..fba8b957d --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/package-consumer-concepts.md @@ -0,0 +1,165 @@ +--- +title: Concepts for Package Consumers +--- + +## 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. + +(upcoming) If users would like to exclude the global packages from their namespace, the +annotation `packaging.carvel.dev/exclude-global-packages` can be added to +the 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/blang/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.31.0/package-install-extensions.md b/site/content/kapp-controller/docs/v0.31.0/package-install-extensions.md new file mode 100644 index 000000000..dfd8ce447 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/package-install-extensions.md @@ -0,0 +1,64 @@ +--- +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.31.0/packaging-artifact-formats.md b/site/content/kapp-controller/docs/v0.31.0/packaging-artifact-formats.md new file mode 100644 index 000000000..449321236 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/packaging-artifact-formats.md @@ -0,0 +1,65 @@ +--- +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.31.0/packaging-gitops.md b/site/content/kapp-controller/docs/v0.31.0/packaging-gitops.md new file mode 100644 index 000000000..6e24a5451 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/packaging-gitops.md @@ -0,0 +1,249 @@ +--- +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.31.0/packaging-tutorial.md b/site/content/kapp-controller/docs/v0.31.0/packaging-tutorial.md new file mode 100644 index 000000000..03f640246 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/packaging-tutorial.md @@ -0,0 +1,483 @@ +--- +title: "Tutorial: Create and Install a Package" +--- + +[//]: # (Generated from katacoda content using 'carvel/tutorials/copy-katacoda-to-static.sh') + +## Get Started With Katacoda +Make a katacoda account and take our interactive tutorial [here](https://katacoda.com/carvel/scenarios/kapp-controller-package-management) +## Or Follow Our Tutorial Below +You can spin up your favorite [playground](https://www.katacoda.com/courses/kubernetes/playground) and follow the steps below. +Note the below steps are from the linked katacoda tutorial so your environment may differ slightly. + +## 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 whole tool suite with the script below: + +(Note: we are temporarily overriding kapp-controller's version to jump to ytt +0.38.0, in order to include the recent OpenAPI Schema feature in this tutorial) +```bash +wget -O- https://raw.githubusercontent.com/vmware-tanzu/carvel-kapp-controller/fc5458fe2102d67e85116c26534a35e265b28125/hack/install-deps.sh | \ +sed 's/ytt_version=v0.35.1/ytt_version=v0.38.0/' | \ +sed 's/0aa78f7b5f5a0a4c39bddfed915172880344270809c26b9844e9d0cbf6437030/2ca800c561464e0b252e5ee5cacff6aa53831e65e2fb9a09cf388d764013c40d/' | \ +bash +``` + + +## 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. + +### Using kapp to install a cronjob + +First clone the GitHub repository for examples: + +```bash +git clone https://github.com/vmware-tanzu/carvel-kapp +``` + +Then deploy a CronJob to the Kubernetes cluster in this environment: + +```bash +kapp deploy -a hellocron -f carvel-kapp/examples/jobs/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/vmware-tanzu/carvel-kapp-controller/releases/download/v0.21.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](/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](packaging-artifact-formats.md#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](/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](app-spec.md) 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](packaging.md#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](/imgpkg/docs/latest/resources/#bundle). + +The [PackageRepository bundle format](packaging-artifact-formats.md#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](private-registry-auth.md) 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 katacoda 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](packaging.md#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](security-model.md) +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/vmware-tanzu/carvel-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](packaging.md) diff --git a/site/content/kapp-controller/docs/v0.31.0/packaging.md b/site/content/kapp-controller/docs/v0.31.0/packaging.md new file mode 100644 index 000000000..b3288f88c --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/packaging.md @@ -0,0 +1,295 @@ +--- +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: + # The name of the PackageMetadata associated with this version + # Must be a valid PackageMetadata name (see PackageMetadata CR for details) + # Cannot be empty + refName: fluent-bit.carvel.dev + # Package version; Referenced by PackageInstall; + # Must be valid semver (required) + # Cannot be empty + 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 + # 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: + # Must consist of at least three segments separated by a '.' + # Cannot have a trailing '.' + 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 maintner 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_ reconcilation; 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 that Package should be deployed to destination cluster; + # by default, cluster is same as where this resource resides (optional) + 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 + # specifies service account that will be used to install underlying package contents + serviceAccountName: fluent-bit-sa + packageRef: + # Specifies the name of the package to install (required) + refName: fluent-bit.vmware.com + # Selects version of a package based on constraints provided (optional) + # Either version or versionSelection is 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. diff --git a/site/content/kapp-controller/docs/v0.31.0/private-registry-auth.md b/site/content/kapp-controller/docs/v0.31.0/private-registry-auth.md new file mode 100644 index 000000000..95e6868ad --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/private-registry-auth.md @@ -0,0 +1,216 @@ +--- +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: + +1. credentials for pulling package repository bundle (via PackageRepository CR) + - consumed by imgpkg running inside kapp-controller Pod +1. credentials for pulling package contents bundle (via PackageInstall CR) + - consumed by imgpkg running inside kapp-controller Pod +1. credentials for pulling container images used by the package + - credentials consumed by Kubelets + - e.g. needed by cert-manager controller Pod +1. 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/vmware-tanzu/carvel-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/vmware-tanzu/carvel-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 `imgpkgBunle` 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/vmware-tanzu/carvel-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](config.md#image-authentication). + +### 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](config.md#image-authentication). diff --git a/site/content/kapp-controller/docs/v0.31.0/security-model.md b/site/content/kapp-controller/docs/v0.31.0/security-model.md new file mode 100644 index 000000000..ed8261367 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/security-model.md @@ -0,0 +1,66 @@ +--- +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.31.0/security.md b/site/content/kapp-controller/docs/v0.31.0/security.md new file mode 100644 index 000000000..1fff1a2c3 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/security.md @@ -0,0 +1,7 @@ +--- +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.31.0/sops.md b/site/content/kapp-controller/docs/v0.31.0/sops.md new file mode 100644 index 000000000..979a7aa7b --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/sops.md @@ -0,0 +1,145 @@ +--- +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.yml`). + +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.31.0/startup.md b/site/content/kapp-controller/docs/v0.31.0/startup.md new file mode 100644 index 000000000..7723d9f39 --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/startup.md @@ -0,0 +1,30 @@ +--- +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.31.0/walkthrough.md b/site/content/kapp-controller/docs/v0.31.0/walkthrough.md new file mode 100644 index 000000000..25172e9ca --- /dev/null +++ b/site/content/kapp-controller/docs/v0.31.0/walkthrough.md @@ -0,0 +1,204 @@ +--- +title: Install an Application +--- + +This walkthrough demonstrates how to install a simple example application, an HTTP server, on Kubernetes with kapp-controller. We will use `examples/simple-app-git` directory as our YAML configuration. + +You can use `kubectl` (or another tool) to deploy the YAML examples below. We've chosen [kapp](/kapp). + +- Start by [installing](install.md) kapp-controller onto your cluster + +- Install [examples/default-ns-rbac.yml](https://github.com/vmware-tanzu/carvel-kapp-controller/blob/develop/examples/rbac/default-ns.yml). It creates `default-ns-sa` service account that allows to change any + resource within the `default` namespace. This will be used by App CR below. + + ```bash-plain + $ kapp deploy -a default-ns-rbac -f https://raw.githubusercontent.com/vmware-tanzu/carvel-kapp-controller/develop/examples/rbac/default-ns.yml + ``` + +- Install [examples/simple-app-git/1.yml](https://github.com/vmware-tanzu/carvel-kapp-controller/blob/develop/examples/simple-app-git/1.yml) App CR. It specifies how to fetch, template, and deploy our 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 + 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 + ``` + +- Check out `kubectl get app` output to see that app is deployed. + +- Additionally, let's check status of our App CR. It shows the overall status of the application, including the latest deploy output (`status.deploy.stdout`) and latest inspect output (`status.inspect.stdout`). Based on the inspect output we can see that our app included a `Deployment` and a `Service`. (Note: As of kapp-controller v0.31.0, inspect is disabled 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 + 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 + ``` + +- Update simple-app App CR to reconfigure simple-app. In this example we are changing 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 + 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 + ``` + +- Delete 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 + 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/data/kapp-controller/docs/kapp-controller-latest-toc.yml b/site/data/kapp-controller/docs/kapp-controller-develop-toc.yml similarity index 100% rename from site/data/kapp-controller/docs/kapp-controller-latest-toc.yml rename to site/data/kapp-controller/docs/kapp-controller-develop-toc.yml diff --git a/site/data/kapp-controller/docs/kapp-controller-v0-31-0-toc.yml b/site/data/kapp-controller/docs/kapp-controller-v0-31-0-toc.yml new file mode 100644 index 000000000..9b071ae6f --- /dev/null +++ b/site/data/kapp-controller/docs/kapp-controller-v0-31-0-toc.yml @@ -0,0 +1,57 @@ +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: Intergration 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: 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: FAQ + subfolderitems: + - page: kapp-controller FAQ + url: /faq + - page: Security + url: /security diff --git a/site/data/kapp-controller/docs/toc-mapping.yml b/site/data/kapp-controller/docs/toc-mapping.yml index 9e3dff6e3..065541b93 100644 --- a/site/data/kapp-controller/docs/toc-mapping.yml +++ b/site/data/kapp-controller/docs/toc-mapping.yml @@ -2,4 +2,5 @@ # (TOC). You'll want to use this after any revamps to information architecture, to ensure # that the navigation for older versions still work. -latest: kapp-controller-latest-toc +develop: kapp-controller-develop-toc +v0.31.0: kapp-controller-v0-31-0-toc