From ef2634b42549578a18023a7c50169863999604c2 Mon Sep 17 00:00:00 2001 From: rcmadhankumar Date: Mon, 22 Apr 2024 20:37:57 +0530 Subject: [PATCH] Update kapp docs to latest version Signed-off-by: rcmadhankumar --- site/config.yaml | 5 +- site/content/kapp/docs/v0.61.x/_index.md | 2 +- .../kapp/docs/v0.61.x/apply-ordering.md | 2 +- .../kapp/docs/v0.61.x/apply-waiting.md | 2 +- site/content/kapp/docs/v0.61.x/apply.md | 2 +- site/content/kapp/docs/v0.61.x/apps.md | 2 +- site/content/kapp/docs/v0.61.x/cheatsheet.md | 2 +- .../kapp/docs/v0.61.x/command-reference.md | 2 +- site/content/kapp/docs/v0.61.x/config.md | 2 +- .../kapp/docs/v0.61.x/configmap-migration.md | 2 +- .../kapp/docs/v0.61.x/dangerous-flags.md | 2 +- site/content/kapp/docs/v0.61.x/diff.md | 2 +- site/content/kapp/docs/v0.61.x/faq.md | 2 +- site/content/kapp/docs/v0.61.x/gitops.md | 2 +- .../docs/v0.61.x/hpa-deployment-rebase.md | 2 +- site/content/kapp/docs/v0.61.x/install.md | 2 +- .../v0.61.x/integrating-with-other-tools.md | 2 +- .../content/kapp/docs/v0.61.x/merge-method.md | 2 +- site/content/kapp/docs/v0.61.x/preflight.md | 2 +- site/content/kapp/docs/v0.61.x/rbac.md | 2 +- site/content/kapp/docs/v0.61.x/rebase-pvc.md | 2 +- site/content/kapp/docs/v0.61.x/security.md | 2 +- .../kapp/docs/v0.61.x/state-namespace.md | 2 +- site/content/kapp/docs/v0.62.x/_index.md | 44 ++ .../kapp/docs/v0.62.x/apply-ordering.md | 94 ++++ .../kapp/docs/v0.62.x/apply-waiting.md | 47 ++ site/content/kapp/docs/v0.62.x/apply.md | 137 ++++++ site/content/kapp/docs/v0.62.x/apps.md | 41 ++ site/content/kapp/docs/v0.62.x/cheatsheet.md | 141 ++++++ .../kapp/docs/v0.62.x/command-reference.md | 242 +++++++++++ site/content/kapp/docs/v0.62.x/config.md | 401 ++++++++++++++++++ .../kapp/docs/v0.62.x/configmap-migration.md | 125 ++++++ .../kapp/docs/v0.62.x/dangerous-flags.md | 38 ++ site/content/kapp/docs/v0.62.x/diff.md | 378 +++++++++++++++++ site/content/kapp/docs/v0.62.x/faq.md | 128 ++++++ site/content/kapp/docs/v0.62.x/gitops.md | 17 + .../docs/v0.62.x/hpa-deployment-rebase.md | 42 ++ site/content/kapp/docs/v0.62.x/install.md | 58 +++ .../v0.62.x/integrating-with-other-tools.md | 27 ++ .../content/kapp/docs/v0.62.x/merge-method.md | 27 ++ site/content/kapp/docs/v0.62.x/preflight.md | 25 ++ site/content/kapp/docs/v0.62.x/rbac.md | 70 +++ site/content/kapp/docs/v0.62.x/rebase-pvc.md | 102 +++++ site/content/kapp/docs/v0.62.x/security.md | 8 + .../kapp/docs/v0.62.x/state-namespace.md | 53 +++ site/data/kapp/docs/kapp-v0-62-x-toc.yml | 57 +++ site/data/kapp/docs/toc-mapping.yml | 1 + 47 files changed, 2328 insertions(+), 24 deletions(-) create mode 100644 site/content/kapp/docs/v0.62.x/_index.md create mode 100644 site/content/kapp/docs/v0.62.x/apply-ordering.md create mode 100644 site/content/kapp/docs/v0.62.x/apply-waiting.md create mode 100644 site/content/kapp/docs/v0.62.x/apply.md create mode 100644 site/content/kapp/docs/v0.62.x/apps.md create mode 100644 site/content/kapp/docs/v0.62.x/cheatsheet.md create mode 100644 site/content/kapp/docs/v0.62.x/command-reference.md create mode 100644 site/content/kapp/docs/v0.62.x/config.md create mode 100644 site/content/kapp/docs/v0.62.x/configmap-migration.md create mode 100644 site/content/kapp/docs/v0.62.x/dangerous-flags.md create mode 100644 site/content/kapp/docs/v0.62.x/diff.md create mode 100644 site/content/kapp/docs/v0.62.x/faq.md create mode 100644 site/content/kapp/docs/v0.62.x/gitops.md create mode 100644 site/content/kapp/docs/v0.62.x/hpa-deployment-rebase.md create mode 100644 site/content/kapp/docs/v0.62.x/install.md create mode 100644 site/content/kapp/docs/v0.62.x/integrating-with-other-tools.md create mode 100644 site/content/kapp/docs/v0.62.x/merge-method.md create mode 100644 site/content/kapp/docs/v0.62.x/preflight.md create mode 100644 site/content/kapp/docs/v0.62.x/rbac.md create mode 100644 site/content/kapp/docs/v0.62.x/rebase-pvc.md create mode 100644 site/content/kapp/docs/v0.62.x/security.md create mode 100644 site/content/kapp/docs/v0.62.x/state-namespace.md create mode 100644 site/data/kapp/docs/kapp-v0-62-x-toc.yml diff --git a/site/config.yaml b/site/config.yaml index 18d04e40b..057630e97 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -73,15 +73,16 @@ params: name: kapp short_name: kapp root_link: /kapp/ - latest_docs_link: /kapp/docs/v0.61.x/ + latest_docs_link: /kapp/docs/v0.62.x/ github_url: https://github.com/carvel-dev/kapp search: true search_index_name: carvel-kapp search_api_key: a38560864c2e9128ae57d5734df438ff versioning: true - version_latest: v0.61.x + version_latest: v0.62.x versions: - develop + - v0.62.x - v0.61.x - v0.60.x - v0.59.x diff --git a/site/content/kapp/docs/v0.61.x/_index.md b/site/content/kapp/docs/v0.61.x/_index.md index ca8ee1617..147a98e35 100644 --- a/site/content/kapp/docs/v0.61.x/_index.md +++ b/site/content/kapp/docs/v0.61.x/_index.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/] + title: "About kapp" toc: "false" cascade: diff --git a/site/content/kapp/docs/v0.61.x/apply-ordering.md b/site/content/kapp/docs/v0.61.x/apply-ordering.md index 6a60e1044..6f870b2ec 100644 --- a/site/content/kapp/docs/v0.61.x/apply-ordering.md +++ b/site/content/kapp/docs/v0.61.x/apply-ordering.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/apply-ordering] + title: Apply Ordering --- diff --git a/site/content/kapp/docs/v0.61.x/apply-waiting.md b/site/content/kapp/docs/v0.61.x/apply-waiting.md index 93ff9f7ab..77c767455 100644 --- a/site/content/kapp/docs/v0.61.x/apply-waiting.md +++ b/site/content/kapp/docs/v0.61.x/apply-waiting.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/apply-waiting] + title: Apply Waiting --- diff --git a/site/content/kapp/docs/v0.61.x/apply.md b/site/content/kapp/docs/v0.61.x/apply.md index 70f63a637..7cd36ddd4 100644 --- a/site/content/kapp/docs/v0.61.x/apply.md +++ b/site/content/kapp/docs/v0.61.x/apply.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/apply] + title: Apply stage --- diff --git a/site/content/kapp/docs/v0.61.x/apps.md b/site/content/kapp/docs/v0.61.x/apps.md index ebaf13fab..2abf48417 100644 --- a/site/content/kapp/docs/v0.61.x/apps.md +++ b/site/content/kapp/docs/v0.61.x/apps.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/apps] + title: Applications --- diff --git a/site/content/kapp/docs/v0.61.x/cheatsheet.md b/site/content/kapp/docs/v0.61.x/cheatsheet.md index 9ac162011..021b6aa5c 100644 --- a/site/content/kapp/docs/v0.61.x/cheatsheet.md +++ b/site/content/kapp/docs/v0.61.x/cheatsheet.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/cheatsheet] + title: Cheatsheet --- diff --git a/site/content/kapp/docs/v0.61.x/command-reference.md b/site/content/kapp/docs/v0.61.x/command-reference.md index 6b48d8122..dd5f2a6e0 100644 --- a/site/content/kapp/docs/v0.61.x/command-reference.md +++ b/site/content/kapp/docs/v0.61.x/command-reference.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/command-reference] + title: Command Reference --- diff --git a/site/content/kapp/docs/v0.61.x/config.md b/site/content/kapp/docs/v0.61.x/config.md index 2cb2f326e..c22a8b560 100644 --- a/site/content/kapp/docs/v0.61.x/config.md +++ b/site/content/kapp/docs/v0.61.x/config.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/config] + title: Configuration --- diff --git a/site/content/kapp/docs/v0.61.x/configmap-migration.md b/site/content/kapp/docs/v0.61.x/configmap-migration.md index 9d1d3a4f7..d31a49ff5 100644 --- a/site/content/kapp/docs/v0.61.x/configmap-migration.md +++ b/site/content/kapp/docs/v0.61.x/configmap-migration.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/configmap-migration] + title: Configmap Migration (experimental) --- diff --git a/site/content/kapp/docs/v0.61.x/dangerous-flags.md b/site/content/kapp/docs/v0.61.x/dangerous-flags.md index 14bccdb53..1aecb4909 100644 --- a/site/content/kapp/docs/v0.61.x/dangerous-flags.md +++ b/site/content/kapp/docs/v0.61.x/dangerous-flags.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/dangerous-flags] + title: Dangerous Flags --- diff --git a/site/content/kapp/docs/v0.61.x/diff.md b/site/content/kapp/docs/v0.61.x/diff.md index d0535d9ec..01eadfb70 100644 --- a/site/content/kapp/docs/v0.61.x/diff.md +++ b/site/content/kapp/docs/v0.61.x/diff.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/diff] + title: Diff stage --- ## Overview diff --git a/site/content/kapp/docs/v0.61.x/faq.md b/site/content/kapp/docs/v0.61.x/faq.md index 50318f573..2bbe6317c 100644 --- a/site/content/kapp/docs/v0.61.x/faq.md +++ b/site/content/kapp/docs/v0.61.x/faq.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/faq] + title: FAQ --- diff --git a/site/content/kapp/docs/v0.61.x/gitops.md b/site/content/kapp/docs/v0.61.x/gitops.md index 156a06c19..c7ce67312 100644 --- a/site/content/kapp/docs/v0.61.x/gitops.md +++ b/site/content/kapp/docs/v0.61.x/gitops.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/gitops] + title: GitOps --- diff --git a/site/content/kapp/docs/v0.61.x/hpa-deployment-rebase.md b/site/content/kapp/docs/v0.61.x/hpa-deployment-rebase.md index 722c9bc68..ce4ce0d2e 100644 --- a/site/content/kapp/docs/v0.61.x/hpa-deployment-rebase.md +++ b/site/content/kapp/docs/v0.61.x/hpa-deployment-rebase.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/hpa-deployment-rebase] + title: HPA and Deployment rebase --- ## HPA and Deployment rebase diff --git a/site/content/kapp/docs/v0.61.x/install.md b/site/content/kapp/docs/v0.61.x/install.md index c4d30dbad..da1c6ea4d 100644 --- a/site/content/kapp/docs/v0.61.x/install.md +++ b/site/content/kapp/docs/v0.61.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/install] + title: Install --- diff --git a/site/content/kapp/docs/v0.61.x/integrating-with-other-tools.md b/site/content/kapp/docs/v0.61.x/integrating-with-other-tools.md index aa84510bf..0bdc967b8 100644 --- a/site/content/kapp/docs/v0.61.x/integrating-with-other-tools.md +++ b/site/content/kapp/docs/v0.61.x/integrating-with-other-tools.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/integrating-with-other-tools] + title: Integrating with Other Tools --- diff --git a/site/content/kapp/docs/v0.61.x/merge-method.md b/site/content/kapp/docs/v0.61.x/merge-method.md index ae06ce516..f555150fe 100644 --- a/site/content/kapp/docs/v0.61.x/merge-method.md +++ b/site/content/kapp/docs/v0.61.x/merge-method.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/merge-method] + title: "Resource Merge Method" --- diff --git a/site/content/kapp/docs/v0.61.x/preflight.md b/site/content/kapp/docs/v0.61.x/preflight.md index 230619c1e..b995900cb 100644 --- a/site/content/kapp/docs/v0.61.x/preflight.md +++ b/site/content/kapp/docs/v0.61.x/preflight.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/preflight] + title: Preflight Checks --- diff --git a/site/content/kapp/docs/v0.61.x/rbac.md b/site/content/kapp/docs/v0.61.x/rbac.md index 7eb89bd96..33b568951 100644 --- a/site/content/kapp/docs/v0.61.x/rbac.md +++ b/site/content/kapp/docs/v0.61.x/rbac.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/rbac] + title: Permissions --- diff --git a/site/content/kapp/docs/v0.61.x/rebase-pvc.md b/site/content/kapp/docs/v0.61.x/rebase-pvc.md index 0e9087088..519370c1c 100644 --- a/site/content/kapp/docs/v0.61.x/rebase-pvc.md +++ b/site/content/kapp/docs/v0.61.x/rebase-pvc.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/rebase-pvc] + title: PersistentVolumeClaim rebase --- ## PersistentVolumeClaim rebase diff --git a/site/content/kapp/docs/v0.61.x/security.md b/site/content/kapp/docs/v0.61.x/security.md index 6b16ba957..30752f23a 100644 --- a/site/content/kapp/docs/v0.61.x/security.md +++ b/site/content/kapp/docs/v0.61.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/security] + title: Security --- diff --git a/site/content/kapp/docs/v0.61.x/state-namespace.md b/site/content/kapp/docs/v0.61.x/state-namespace.md index 82185f326..17548c4f1 100644 --- a/site/content/kapp/docs/v0.61.x/state-namespace.md +++ b/site/content/kapp/docs/v0.61.x/state-namespace.md @@ -1,5 +1,5 @@ --- -aliases: [/kapp/docs/latest/state-namespace] + title: Namespace for State Storage --- diff --git a/site/content/kapp/docs/v0.62.x/_index.md b/site/content/kapp/docs/v0.62.x/_index.md new file mode 100644 index 000000000..8f5d397b8 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/_index.md @@ -0,0 +1,44 @@ +--- +aliases: [/kapp/docs/latest/] +title: "About kapp" +toc: "false" +cascade: + version: v0.62.x + toc: "true" + type: docs + layout: docs +--- + +`kapp` (pronounced: `kap`) CLI encourages Kubernetes users to manage resources in bulk by working with "Kubernetes applications" (sets of resources with the same label). It focuses on resource diffing, labeling, deployment and deletion. Unlike tools like Helm, `kapp` considers YAML templating and management of packages outside of its scope, though it works great with tools that generate Kubernetes configuration. + +![Kapp Deploy](/images/kapp/kapp-deploy-screenshot.png) + +Features: + +- Works with standard Kubernetes YAMLs +- Focuses exclusively on deployment workflow, not packaging or templating + - but plays well with tools (such as [ytt](/ytt)) that produce Kubernetes configuration +- Converges application resources (creates, updates and/or deletes resources) in each deploy + - based on comparison between provided files and live objects in the cluster +- Separates calculation of changes ([diff stage](diff.md)) from application of changes ([apply stage](apply.md)) +- [Waits for resources](apply-waiting.md) to be "ready" +- Creates CRDs and Namespaces first and supports [custom change ordering](apply-ordering.md) +- Works [without admin privileges](rbac.md) and does not use custom CRDs + - making it possible to use kapp as a regular user in a single namespace +- Records application deployment history +- Opt-in resource version management + - for example, to trigger Deployment rollout when ConfigMap changes +- Optionally streams Pod logs during deploy +- Works with any group of labeled resources (`kapp -a label:tier=web inspect -t`) +- Works without server side components +- GitOps friendly (`kapp app-group deploy -g all-apps --directory .`) + +## Blog posts + +- [Deploying Kubernetes Applications with ytt, kbld, and kapp](/blog/deploying-apps-with-ytt-kbld-kapp) + +## Talks + +- [ytt and kapp @ TGI Kubernetes 079](https://www.youtube.com/watch?v=CSglwNTQiYg) with Joe Beda +- [Managing Applications in Production: Helm vs ytt & kapp @ Kubecon 2020](https://www.youtube.com/watch?v=WJw1MDFMVuk) +- [Introduction to Carvel @ Rawkode Live](https://www.youtube.com/watch?v=LBCmMTofNxw) diff --git a/site/content/kapp/docs/v0.62.x/apply-ordering.md b/site/content/kapp/docs/v0.62.x/apply-ordering.md new file mode 100644 index 000000000..6a60e1044 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/apply-ordering.md @@ -0,0 +1,94 @@ +--- +aliases: [/kapp/docs/latest/apply-ordering] +title: Apply Ordering +--- + +## Overview + +kapp includes builtin rules to make sure certain changes are applied in particular order: + +- Creates/updates + - CRDs are created/updated before custom resources + - Namespaces are created/updated before namespaced resources + - Pod related resources (ServiceAccount, ConfigMap, Secret, etc.) are created/updated before other resources (v0.25.0+) + - RBAC related resources (Role, RoleBinding, etc.) are created/updated before other resources (v0.25.0+) +- Deletions (below is order as of v0.29.0+) + - Custom resources are deleted first + - CRDs are deleted next + - Rest of resoures are deleted + +As of v0.25.0+, builtin rules are specified via [changeGroupBindings and changeRuleBindings](config.md#changegroupbindings) configurations. Custom rules can be added via same mechanism. + +Additionally kapp allows to customize order of changes via following resource annotations: + +- `kapp.k14s.io/change-group` annotation to group one or more resource changes into arbitrarily named group. Example: `apps.big.co/db-migrations`. You can specify multiple change groups by suffixing each annotation with a `.x` where `x` is unique identifier (e.g. `kapp.k14s.io/change-group.istio-sidecar-order`). +- `kapp.k14s.io/change-rule` annotation to control when resource change should be applied (created, updated, or deleted) relative to other changes. You can specify multiple change rules by suffixing each annotation with a `.x` where `x` is unique identifier (e.g. `kapp.k14s.io/change-rule.istio-sidecar-order`). + +`kapp.k14s.io/change-rule` annotation value format is as follows: `(upsert|delete) (after|before) (upserting|deleting) `. For example: + +- `kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/db-migrations"` +- `kapp.k14s.io/change-rule: "delete before upserting apps.big.co/service"` + +As of v0.41.0+, kapp provides change group placeholders, which can be used in change-group and change-rule annotation values and are later replaced by values from the resource manifest of the resource they are associated with. For example: + +- `kapp.k14s.io/change-group: apps.co/db-migrations-{name}` - Here `{name}` would later be replaced by the name of the resource. +- `kapp.k14s.io/change-rule: upsert after upserting apps.co/namespaces-{namespace}` - Here `{namespace}` would later be replaced by the namespace of the resource. + +kapp provides the following placeholders: + +- `{api-group}` - apiGroup +- `{kind}` - kind +- `{name}` - name +- `{namespace}` - namespace +- `{crd-kind}` - spec.names.kind (available for CRDs only) +- `{crd-group}` - spec.group (available for CRDs only) + +These placeholders can also be used in changeGroupBindings and changeRuleBindings. By default, they are used for CRDs, CRs, namespaces and namespaced resources. Due to this, CRs now wait for their respective CRDs only and namespaced resources now wait for their respective namespaces only. + +## Example + +Following example shows how to run `job/migrations`, start and wait for `deployment/app`, and finally `job/app-health-check`. + +```yaml +kind: ConfigMap +metadata: + name: app-config + annotations: {} +#... +--- +kind: Job +metadata: + name: migrations + annotations: + kapp.k14s.io/change-group: "apps.big.co/db-migrations" +#... +--- +kind: Service +metadata: + name: app + annotations: + kapp.k14s.io/change-group: "apps.big.co/deployment" +#... +--- +kind: Ingress +metadata: + name: app + annotations: + kapp.k14s.io/change-group: "apps.big.co/deployment" +#... +--- +kind: Deployment +metadata: + name: app + annotations: + kapp.k14s.io/change-group: "apps.big.co/deployment" + kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/db-migrations" +#... +--- +kind: Job +metadata: + name: app-health-check + annotations: + kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/deployment" +#... +``` diff --git a/site/content/kapp/docs/v0.62.x/apply-waiting.md b/site/content/kapp/docs/v0.62.x/apply-waiting.md new file mode 100644 index 000000000..93ff9f7ab --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/apply-waiting.md @@ -0,0 +1,47 @@ +--- +aliases: [/kapp/docs/latest/apply-waiting] +title: Apply Waiting +--- + +## Overview + +kapp includes builtin rules on how to wait for the following resource types: + +- any resource with `metadata.deletionTimestamp`: wait for resource to be fully removed +- any resource matching Config's waitRules: [see "Custom waiting behaviour" below](#custom-waiting-behaviour) +- [`apiextensions.k8s.io//CustomResourceDefinition`](https://github.com/carvel-dev/kapp/blob/develop/pkg/kapp/resourcesmisc/api_extensions_vx_crd.go): wait for Established and NamesAccepted conditions to be `True` (note that this is wait rule for CustomResourceDefinition resource itself, not CRs) +- `apps/v1/DaemonSet`: wait for `status.numberUnavailable` to be 0 +- `apps/v1/Deployment`: [see "apps/v1/Deployment resource" below](#apps-v1-deployment-resource) +- `apps/v1/ReplicaSet`: wait for `status.replicas == status.availableReplicas` +- `batch/v1/Job`: wait for `Complete` or `Failed` conditions to appear +- `batch//CronJob`: immediately considered done +- `/v1/Pod`: looks at `status.phase` +- `/v1/Service`: wait for `spec.clusterIP` and/or `status.loadBalancer.ingress` to become set +- `apps/v1/StatefulSet`: [see "apps/v1/StatefulSet resource" below](#appsv1statefulset-resource) + +If resource is not affected by the above rules, its waiting behaviour depends on aggregate of waiting states of its associated resources (associated resources are resources that share same `kapp.k14s.io/association` label value). + +## Controlling waiting via resource annotations + +- `kapp.k14s.io/disable-wait` annotation controls whether waiting will happen at all. Possible values: "". +- `kapp.k14s.io/disable-associated-resources-wait` annotation controls whether associated resources impact resource's waiting state. Possible values: "". + +## apps/v1/Deployment resource + +kapp by default waits for `apps/v1/Deployment` resource to have `status.unavailableReplicas` equal to zero. Additionally waiting behaviour can be controlled via following annotations: + +- `kapp.k14s.io/apps-v1-deployment-wait-minimum-replicas-available` annotation controls how many new available replicas are enough to consider waiting successful. Example values: `"10"`, `"5%"`. + +## apps/v1/StatefulSet resource + +Available in v0.32.0+. + +kapp will wait for any pods created from the updated template to be ready based on StatefulSet's status. This behaviour depends on the [update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) used. + +Note: kapp does not do anything special when `OnDelete` strategy is used. It will wait for StatefulSet to report it's reconciled (expecting some actor in the system to delete Pods per `OnDelete` requirements). + +## Custom waiting behaviour + +Available in v0.29.0+. + +kapp can be extended with custom waiting behaviour by specifying [wait rules as additional config](config.md#wait-rules). (If this functionality is not enough to wait for resources in your use case, please reach out on Slack to discuss further.) diff --git a/site/content/kapp/docs/v0.62.x/apply.md b/site/content/kapp/docs/v0.62.x/apply.md new file mode 100644 index 000000000..70f63a637 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/apply.md @@ -0,0 +1,137 @@ +--- +aliases: [/kapp/docs/latest/apply] +title: Apply stage +--- + +## Overview + +Once change set is calculated (see [Diff](diff.md) section for details), kapp asks for user confirmation (unless `--yes` flag is specified) to proceed with changes. + +Changes are applied in particular order as described in [Apply ordering](apply-ordering.md). + +All created resources are labeled with several labels: + +- `kapp.k14s.io/app` to track which application "owns" resource +- `kapp.k14s.io/identity` to identify preferred API version used when creating resource +- `kapp.k14s.io/association` to track (best effort) parent-child relationships between resources + +Every time application is deployed, new application change record is saved. They can be viewed via `kapp app-change ls -a app-name`. + +Related: [ownership label rules](config.md#ownershiplabelrules) and [label scoping rules](config.md#labelscopingrules). + +## Controlling apply via resource annotations + +### kapp.k14s.io/create-strategy + +`kapp.k14s.io/create-strategy` annotation controls create behaviour (rarely necessary) + +Possible values: "" (default), `fallback-on-update`, `fallback-on-update-or-noop`. + +In some cases creation of a resource may conflict with that resource being created in the cluster by other means (often automated). An example of that is creation of default ServiceAccount by kapp racing with Kubernetes service accounts controller doing the same thing. By specifying `fallback-on-update` value, kapp will catch resource creation conflicts and apply resource as an update. + +`fallback-on-update-or-noop` (Available in v0.47.0+) also allows to use `noop` operation if `kapp.k14.io/noop` is added through rebase rules, else it behaves the same way as `fallback-on-update`. + +### kapp.k14s.io/update-strategy + +`kapp.k14s.io/update-strategy` annotation controls update behaviour + +Possible values: "" (default), `fallback-on-replace`, `always-replace`, `skip`. + +In some cases entire resources or subset resource fields are immutable which forces kapp users to specify how to apply wanted update. + +- "" means to issue plain update call +- `fallback-on-replace` causes kapp to fallback to resource replacement if update call results in `Invalid` error. Note that if resource is replaced (= delete + create), it may be negatively affected (loss of persistent data, loss of availability, etc.). For example, if Deployment or DaemonSet is first deleted and then created then associated Pods will be recreated as well, but all at the same time (even if rolling update is enabled), which likely causes an availability gap. +- `always-replace` causes kapp to always delete and then create resource (See note above as well.) +- `skip` causes kapp to not apply update (it will show up in a diff next time). Available in v0.33.0+. + +### kapp.k14s.io/delete-strategy + +`kapp.k14s.io/delete-strategy` annotation controls deletion behaviour + +Possible values: "" (default), `orphan`. + +By default resource is deleted, however; choosing `orphan` value will make kapp forget about this resource. Note that if this resource is owned by a different resource that's being deleted, it might still get deleted. Orphaned resources are labeled with `kapp.k14s.io/orphaned` label. As of v0.31.0+, resource is also disassociated from owning app so that it can be owned by future apps. + +### kapp.k14s.io/owned-for-deletion + +`kapp.k14s.io/owned-for-deletion` annotation controls resource deletion during `kapp delete` command + +Possible values: "". + +By default non-kapp owned resources are not explicitly deleted by kapp, but expected to be deleted by the cluster (for example Endpoints resource for each Service). In some cases it's desired to annotate non-kapp owned resource so that it does get explicitly deleted, possibly because cluster does not plan to delete it (e.g. PVCs created by StatefulSet are not deleted by StatefulSet controller; [https://github.com/carvel-dev/kapp/issues/36](https://github.com/carvel-dev/kapp/issues/36)). + +### kapp.k14s.io/nonce + +`kapp.k14s.io/nonce` annotation allows to inject unique ID + +Possible values: "" (default). + +Annotation value will be replaced with a unique ID on each deploy. This allows to force resource update as value changes every time. + +### kapp.k14s.io/renew-duration + +Available in v0.54.0+ + +`kapp.k14s.io/renew-duration` annotation allows specifying an interval which facilitates kapp to update or recreate the resource during next `kapp deploy` if this duration has lapsed. + +Possible values: [ParseDuration](https://pkg.go.dev/time#ParseDuration). + +If `kapp deploy` is run after this interval has lapsed, `kapp` will force an update irrespective of no changes to the resource's configuration by injecting an annotation with the current timestamp (`kapp.k14s.io/last-renewed-time=`) to the resource. + +**Note**: For precise results use `versioned resources` or `always-replace` update strategy for `non-versioned resources`. + +This annotation is helpful in scenario when you want a resource (like `secret`) get updated/recreated automatically irrespective of no changes to the resource's configuration at predetermined intervals. + +### kapp.k14s.io/deploy-logs + +`kapp.k14s.io/deploy-logs` annotation indicates which Pods' log output to show during deploy + +Possible values: + +- "" (default; equivalent to `for-new`) +- `for-new` (only newly created Pods are tailed) +- `for-existing` (only existing Pods are tailed) +- `for-new-or-existing` (both newly created and existing Pods are tailed) + +Especially useful when added to Jobs. For example, see [examples/resource-ordering/sync-check.yml](https://github.com/carvel-dev/kapp/blob/develop/examples/resource-ordering/sync-check.yml) + +### kapp.k14s.io/deploy-logs-container-names + +`kapp.k14s.io/deploy-logs-container-names` annotation indicates which containers' log output to show during deploy + +Possible values: "" (default), `containerName1`, `containerName1,containerName2` + +### kapp.k14s.io/exists + +Available in v0.43.0+ + +`kapp.k14s.io/exists` verifies that the resource exists in Kubernetes. Kapp does not consider the resource a part of the app (not labeled). + +If the resource is not present, then kapp uses the `exists` operation and asserts that the resource exists in Kubernetes. + +If the resource already exists, kapp does not perform any operation on it (using the `noop` operation). + +Possible values: "". + +Especially useful in scenarios where an external agency such as a controller might be creating a resource that we want to wait for. + +### kapp.k14s.io/noop + +Available in v0.43.0+ + +`kapp.k14s.io/noop` ensures that kapp is aware of the resource. It will not be considered to be part of the app (not labeled). + +kapp always uses the `noop` operation for these resources. + +Possible values: "". + +--- +## Controlling apply via deploy flags + +- `--apply-ignored=bool` explicitly applies ignored changes; this is useful in cases when controllers lose track of some resources instead of for example deleting them +- `--apply-default-update-strategy=string` controls default strategy for all resources (see `kapp.k14s.io/update-strategy` annotation above) +- `--apply-exit-status=bool` (default `false`) controls exit status (`0`: unused, `1`: any error, `2`: no changes applied, `3`: at least one change applied) +- `--wait=bool` (default `true`) controls whether kapp will wait for resource to "stabilize". See [Apply waiting](apply-waiting.md) +- `--wait-ignored=bool` controls whether kapp will wait for ignored changes (regardless whether they were initiated by kapp or by controllers) +- `--logs=bool` (default `true`) controls whether to show logs as part of deploy output for Pods annotated with `kapp.k14s.io/deploy-logs: ""` +- `--logs-all=bool` (deafult `false`) controls whether to show all logs as part of deploy output for all Pods diff --git a/site/content/kapp/docs/v0.62.x/apps.md b/site/content/kapp/docs/v0.62.x/apps.md new file mode 100644 index 000000000..ebaf13fab --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/apps.md @@ -0,0 +1,41 @@ +--- +aliases: [/kapp/docs/latest/apps] +title: Applications +--- + +## Overview + +kapp considers a set of resources with the same label as an application. These resources could span any number of namespaces or could be cluster-wide (e.g. CRDs). + +kapp has two methods of finding resources: + +1. via unique-to-Namespace application name (via `-a my-name` flag), or +2. via user provided label (via `-a label:my-label=val` flag) + +First approach is most common as kapp generates a unique label for each tracked application and associates that with an application name. + +## List + +Applications can be listed via `ls` command: + +```bash +$ kapp ls +``` + +## Deploy + +To create or update an application use `deploy` command: + +```bash +$ kapp deploy -a my-name -f my-app-config/ +``` + +Deploy command consists of two stages: [resource "diff" stage](diff.md), and [resource "apply" stage](apply.md). + +## Delete + +To delete an application use `delete` command: + +```bash +$ kapp delete -a my-name +``` diff --git a/site/content/kapp/docs/v0.62.x/cheatsheet.md b/site/content/kapp/docs/v0.62.x/cheatsheet.md new file mode 100644 index 000000000..9ac162011 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/cheatsheet.md @@ -0,0 +1,141 @@ +--- +aliases: [/kapp/docs/latest/cheatsheet] +title: Cheatsheet +--- + + +## List + +List all app in the cluster (across all namespaces) + +```bash +kapp ls -A +``` + +Show only specific columns while listing apps + +```bash +kapp ls --column=namespace,name,label +``` + +## Deploy + +Deploy app named `app1` with configuration from `config/`: + +```bash +kapp deploy -a app1 -f config/ -c +``` + +Deploy app named `app1` with configuration piped in (see alternative that does not require `--yes` next): + +```bash +ytt -f config/ | kapp deploy -a app1 -f- -c -y +``` + +Deploy app named `app1` with configuration generated inline and with confirmation dialog: + +```bash +kapp deploy -a app1 -f <(ytt -f config/ ) +``` + +Show more diff context when reviewing changes during deploy: + +```bash +kapp deploy -a app1 -f config/ -c --diff-context=10 +``` + +Show diff and exit successfully (without applying any changes): + +```bash +kapp deploy -a app1 -f config/ --diff-run +``` + +Show logs from all app `Pods` throughout deploy: + +```bash +kapp deploy -a app1 -f config/ --logs-all +``` + +Rewrite all resources to specify `app1-ns` namespace: + +```bash +kapp deploy -a app1 -f config/ --into-ns app1-ns +``` + +## Inspect + +Show summary of all resources in app `app1`: + +```bash +kapp inspect -a app1 +``` + +Show summary organized as a tree of all resources in app `app1`: + +```bash +kapp inspect -a app1 --tree +``` + +Show status subresources for each resource in app `app1`: + +```bash +kapp inspect -a app1 --status +``` + +Show all resources in the cluster: + +```bash +kapp inspect -a 'label:' +``` + +Show all resources in particular namespace (note that it currently does namespace filtering client-side): + +```bash +kapp inspect -a 'label:' --filter-ns some-ns +``` + +Show all resources labeled `tier=web` in the cluster: + +```bash +kapp inspect -a 'label:tier=web' +``` + +Show all `Deployment` resources in the cluster **not** managed by kapp: + +```bash +kapp inspect -a 'label:!kapp.k14s.io/app' --filter-kind Deployment +``` + +## Delete + +Delete resources under particular label (in this example deleting resources associated with some app): + +```bash +kapp delete -a 'label:kapp.k14s.io/app=1578599579922603000' +``` + +## Environment variables + +Environment Variables: + - `FORCE_COLOR`: set to `1` to force colors to the printed. Useful to preserve colors when piping output such as in `kapp list --all-namespaces --tty |& less -R` + +## Misc + +See which labels are used in your cluster (add `--values` to see label values): + +```bash +kapp tools list-labels +``` + +Shows app labels that are still present in the cluster (could be combined with delete command below): + +```bash +kapp tools list-labels --values --tty=false | grep kapp.k14s.io/app +``` + +Delete all app changes older than 500h (v0.12.0+): + +```bash +kapp deploy -a label:kapp.k14s.io/is-app-change --filter-age 500h+ --dangerous-allow-empty-list-of-resources --apply-ignored +``` + diff --git a/site/content/kapp/docs/v0.62.x/command-reference.md b/site/content/kapp/docs/v0.62.x/command-reference.md new file mode 100644 index 000000000..6b48d8122 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/command-reference.md @@ -0,0 +1,242 @@ +--- +aliases: [/kapp/docs/latest/command-reference] +title: Command Reference +--- + +## App Commands +App commands provides options to deploy, delete, inspect and list apps. + +### deploy +The `kapp deploy` command can be used to deploy resources as a single app to your cluster. + +```bash +# Deploy app 'app1' based on config files in config/ +$ kapp deploy -a app1 -f config/ + +# Deploy app 'app1' while showing full text diff +$ kapp deploy -a app1 -f config/ --diff-changes + +# Deploy app 'app1' based on remote file +$ kapp deploy -a app1 \ + -f https://github.com/...download/v0.6.0/crds.yaml \ + -f https://github.com/...download/v0.6.0/release.yaml +``` + +##### Supported flags: +Common flags: +- `-a`, `--app` _string_, Set app name (or label selector) (format: name, label:key=val, !key) +- `-c`, `--diff-changes` _boolean_, Show changes +- `-f`, `--file`, _strings_, Set file (format: /tmp/foo, https://..., -) (can repeat) +- `-n`, `--namespace` _string_, Specified namespace ($KAPP_NAMESPACE or default from kubeconfig) + +Diff Flags: +- `--diff-against-last-applied`, _boolean_, Show changes against last applied copy when possible (default true) +- `-c`, `--diff-changes` _boolean_, Show changes +- `--diff-changes-yaml`, _boolean_, Print YAML to be applied +- `--diff-context`, _int_, Show number of lines around changed lines (default 2) +- `--diff-exit-status`, _boolean_, Return specific exit status based on number of changes +- `--diff-filter` _string_, Set changes filter (example: {"and":[{"ops":["update"]},{"existingResource":{"kinds":["Deployment"]}]}) +- `--diff-line-numbers`, _boolean_, Show line numbers (default true) +- `--diff-mask`, _boolean_, Apply masking rules (default true) +- `--diff-run`, _boolean_, Show diff and exit successfully without any further action +- `--diff-summary`, _boolean_, Show diff summary (default true) +- `--diff-ui-alpha`, _boolean_, Start UI server to inspect changes (alpha feature) + +Apply flags: +- `--apply-check-interval`, _duration_, Amount of time to sleep between applies (default 1s) +- `--apply-concurrency`, _int_, Maximum number of concurrent apply operations (default 5) +- `--apply-default-update-strategy`, _string_, Change default update strategy +- `--apply-exit-status`, _boolean_, Return specific exit status based on number of changes +- `--apply-ignored`, _boolean_, Set to apply ignored changes +- `--apply-timeout`, _duration_, Maximum amount of time to wait in apply phase (default 15m0s) +- `--dangerous-allow-empty-list-of-resources`, _boolean_, Allow to apply empty set of resources (same as running kapp delete) +- `--dangerous-override-ownership-of-existing-resources`, _boolean_, Steal existing resources from another app + +Wait flags: +- `--wait`, _boolean_, Set to wait for changes to be applied (default true) +- `--wait-check-interval`, _duration_, Amount of time to sleep between checks while waiting (default 3s) +- `--wait-concurrency`, _int_, Maximum number of concurrent wait operations (default 5) +- `--wait-ignored`, _boolean_, Set to wait for ignored changes to be applied +- `--wait-resource-timeout`, _duration_, Maximum amount of time to wait for a resource in wait phase (0s means no timeout) +- `--wait-timeout`, _duration_, Maximum amount of time to wait in wait phase (default 15m0s) + +Resource Filter Flags: +- `--filter`, _string_, Set filter (example: {"and":[{"not":{"resource":{"kinds":["foo%"]}}},{"resource":{"kinds":["!foo"]}}]}) +- `--filter-age`, _string_, Set age filter (example: 5m-, 500h+, 10m-) +- `--filter-kind`, _strings_, Set kinds filter (example: Pod) (can repeat) +- `--filter-kind-name`, _strings_, Set kind-name filter (example: Pod/controller) (can repeat) +- `--filter-kind-ns`, _strings_, Set kind-namespace filter (example: Pod/, Pod/knative-serving) (can repeat) +- `--filter-kind-ns-name`, _strings_, Set kind-namespace-name filter (example: Deployment/knative-serving/controller) (can repeat) +- `--filter-labels`, _strings_, Set label filter (example: x=y) +- `--filter-name`, _strings_, Set name filter (example: controller) (can repeat) +- `--filter-ns`, _strings_. Set namespace filter (example: knative-serving) (can repeat) + +Resource Validation Flags: +- `--allow-all-ns`, _boolean_, Set to allow all namespaces for resources (does not apply to the app itself) +- `--allow-check`, _boolean_, Enable client-side allowing +- `--allow-cluster`, _boolean_, Set to allow cluster level for resources (does not apply to the app itself) +- `--allow-ns`, _strings_, Set allowed namespace for resources (does not apply to the app itself) + +Resource Mangling Flags: +- `--into-ns`, _string_, Place resources into namespace +- `--map-ns`, _strings_, Map resources from one namespace into another (could be specified multiple times) + +Logs Flags: +- `--logs`, _boolean_, Show logs from Pods annotated as 'kapp.k14s.io/deploy-logs' (default true) +- `--logs-all`, _boolean_, Show logs from all Pods + +Available/Other Flags: +- `--app-changes-max-to-keep`, _int_, Maximum number of app changes to keep (default 200) +- `--app-metadata-file-output`, _string_, Set filename to write app metadata +- `--dangerous-disable-gk-scoping`, _boolean_, Disable scoping of resource searching to used GroupKinds +- `--dangerous-ignore-failing-api-services`, _boolean_, Allow to ignore failing APIServices +- `--dangerous-scope-to-fallback-allowed-namespaces`, _boolean_, Scope resource searching to fallback allowed namespaces +- `--default-label-scoping-rules`, _boolean_, Use default label scoping rules (default true) +- `--existing-non-labeled-resources-check`, _boolean_, Find and consider existing non-labeled resources in diff (default true) +- `--existing-non-labeled-resources-check-concurrency`, _int_, Concurrency to check for existing non-labeled resources (default 100) +- `--exit-early-on-apply-error`, _boolean_, Exit quickly on apply failure (default true) +- `--exit-early-on-wait-error`, _boolean_, Exit quickly on wait failure (default true) +- `-h`, `--help`, _boolean_, help for deploy +- `--labels`, _strings_, Set app label (format: key=val, key=) (can repeat) +- `-p`, `--patch`, _boolean_, Add or update existing resources only, never delete any +- `--prev-app`, _string_, Set previous app name +- `--sort`, _boolean_, Sort by namespace, name, etc. (default true) +- `--tty`, _boolean_, Force TTY-like output (default true) + +### inspect +The `kapp inspect` command can be used inspect the resources present in an app. + +```bash +# Inspect app 'app1' +$ kapp inspect -a app1 +``` + +Supported flags: +- `-a`, `--app`, _string_, Set app name (or label selector) (format: name, label:key=val, !key) +- `--dangerous-disable-gk-scoping`, _boolean_, Disable scoping of resource searching to used GroupKinds +- `--dangerous-ignore-failing-api-services`, _boolean_, Allow to ignore failing APIServices +- `--dangerous-scope-to-fallback-allowed-namespaces`, _boolean_, Scope resource searching to fallback allowed namespaces +- `--filter`, _string_, Set filter (example: {"and":[{"not":{"resource":{"kinds":["foo%"]}}},{"resource":{"kinds":["!foo"]}}]}) +- `--filter-age`, _string_, Set age filter (example: 5m-, 500h+, 10m-) +- `--filter-kind`, _strings_, Set kinds filter (example: Pod) (can repeat) +- `--filter-kind-name`, _strings_, Set kind-name filter (example: Pod/controller) (can repeat) +- `--filter-kind-ns`, _strings_, Set kind-namespace filter (example: Pod/, Pod/knative-serving) (can repeat) +- `--filter-kind-ns-name`, _strings_, Set kind-namespace-name filter (example: Deployment/knative-serving/controller) (can repeat) +- `--filter-labels`, _strings_, Set label filter (example: x=y) +- `--filter-name`, _strings_, Set name filter (example: controller) (can repeat) +- `--filter-ns`, _strings_, Set namespace filter (example: knative-serving) (can repeat) +- `-h`, `--help`, _boolean_, help for inspect +- `--managed-fields`, _boolean_ Keep the metadata.managedFields when printing objects +- `-n`, `--namespace`, _string_, Specified namespace ($KAPP_NAMESPACE or default from kubeconfig) +- `--raw`, _boolean_ Output raw YAML resource content +- `--status`, _boolean_ Output status content +- `-t`, `--tree`, _boolean_ Tree view +- `--tty`, _boolean_ Force TTY-like output + +### list +The `kapp list` command can be used to list resources present on the cluster. + +```bash +$ kapp list +``` + +Supported flags: +- `-A`, `--all-namespaces`, _boolean_, List apps in all namespaces +- `--filter-age`, _string_, Set age filter (example: 5m-, 500h+, 10m-) +- `--filter-labels`, _strings_, Set label filter (example: x=y) +- `-h`, `--help`, _boolean_, help for list +- `-n`, `--namespace`, _string_, Specified namespace ($KAPP_NAMESPACE or default from kubeconfig) +- `--tty`, _boolean_, Force TTY-like output + +### logs +The `kapp list` command can be used to print app's pod logs. + +```bash +# Follow all pod logs in app 'app1' +$ kapp logs -a app1 -f + +# Show logs from pods that start with 'web' +$ kapp logs -a app1 -f -m web% +``` + +Supported flags: +- `-a`, `--app`, _string_, Set app name (or label selector) (format: name, label:key=val, !key) +- `-c`, `--container-name`, _strings_, Set container name to filter logs (% acts as wildcard, e.g. 'app%') (can repeat) +- `--container-tag`, _boolean_, Include container tag (default true) +- `-f`, `--follow`, _boolean_, As new pods are added, new pod logs will be printed +- `-h`, `--help`, _boolean_, help for logs +- `--lines`, _int_, Limit to number of lines (use -1 to remove limit) (default 10) +- `-n`, `--namespace`, _string_, Specified namespace ($KAPP_NAMESPACE or default from kubeconfig) +- `-m`, `--pod-name`, _string_, Set pod name to filter logs (% acts as wildcard, e.g. 'app%') +- `--tty`, _boolean_, Force TTY-like output + +### delete +The `kapp delete` command can be used to delete an app from your cluster. + +```bash +$ kapp delete -a app1 +``` + +Supported flags: +- `-a`, `--app`, _string_, Set app name (or label selector) (format: name, label:key=val, !key) +- `--apply-check-interval`, _duration_, Amount of time to sleep between applies (default 1s) +- `--apply-concurrency`, _int_, Maximum number of concurrent apply operations (default 5) +- `--apply-default-update-strategy`, _string_, Change default update strategy +- `--apply-exit-status`, _boolean_, Return specific exit status based on number of changes +- `--apply-ignored`, _boolean_, Set to apply ignored changes +- `--apply-timeout`, _duration_, Maximum amount of time to wait in apply phase (default 15m0s) +- `--dangerous-disable-gk-scoping`, _boolean_, Disable scoping of resource searching to used GroupKinds +- `--dangerous-ignore-failing-api-services`, _boolean_, Allow to ignore failing APIServices +- `--dangerous-scope-to-fallback-allowed-namespaces`, _boolean_, Scope resource searching to fallback allowed namespaces +- `--diff-against-last-applied`, _boolean_, Show changes against last applied copy when possible (default true) +- `-c`, `--diff-changes`, _boolean_, Show changes +- `--diff-changes-yaml`, _boolean_, Print YAML to be applied +- `--diff-context`, _int_, Show number of lines around changed lines (default 2) +- `--diff-exit-status`, _boolean_, Return specific exit status based on number of changes +- `--diff-filter`, _string_, Set changes filter (example: {"and":[{"ops":["update"]},{"existingResource":{"kinds":["Deployment"]}]}) +- `--diff-line-numbers`, _boolean_, Show line numbers (default true) +- `--diff-mask`, _boolean_, Apply masking rules (default true) +- `--diff-run`, _boolean_, Show diff and exit successfully without any further action +- `--diff-summary`, _boolean_, Show diff summary (default true) +- `--diff-ui-alpha`, _boolean_, Start UI server to inspect changes (alpha feature) +- `--exit-early-on-apply-error`, _boolean_, Exit quickly on apply failure (default true) +- `--exit-early-on-wait-error`, _boolean_, Exit quickly on wait failure (default true) +- `--filter`, _string_, Set filter (example: {"and":[{"not":{"resource":{"kinds":["foo%"]}}},{"resource":{"kinds":["!foo"]}}]}) +- `--filter-age`, _string_, Set age filter (example: 5m-, 500h+, 10m-) +- `--filter-kind`, _strings_, Set kinds filter (example: Pod) (can repeat) +- `--filter-kind-name`, _strings_, Set kind-name filter (example: Pod/controller) (can repeat) +- `--filter-kind-ns`, _strings_, Set kind-namespace filter (example: Pod/, Pod/knative-serving) (can repeat) +- `--filter-kind-ns-name`, _strings_, Set kind-namespace-name filter (example: Deployment/knative-serving/controller) (can repeat) +- `--filter-labels`, _strings_, Set label filter (example: x=y) +- `--filter-name`, _strings_, Set name filter (example: controller) (can repeat) +- `--filter-ns`, _strings_, Set namespace filter (example: knative-serving) (can repeat) +- `-h`, `--help`, _boolean_, help for delete +- `-n`, `--namespace`, _string_, Specified namespace ($KAPP_NAMESPACE or default from kubeconfig) +- `--prev-app`, _string_, Set previous app name +- `--tty`, _boolean_, Force TTY-like output (default true) +- `--wait`, _boolean_, Set to wait for changes to be applied (default true) +- `--wait-check-interval`, _duration_, Amount of time to sleep between checks while waiting (default 3s) +- `--wait-concurrency`, _int_, Maximum number of concurrent wait operations (default 5) +- `--wait-ignored`, _boolean_, Set to wait for ignored changes to be applied (default true) +- `--wait-resource-timeout`, _duration_, Maximum amount of time to wait for a resource in wait phase (0s means no timeout) +- `--wait-timeout`, _duration_, Maximum amount of time to wait in wait phase (default 15m0s) + +## Global Flags +- `--color` _boolean_, Set color output (default true) +- `--column` _string_, Filter to show only given columns +- `--debug` _boolean_, Include debug output +- `-h`, `--help` _boolean_, help for kctrl +- `--json` _boolean_, Output as JSON +- `--kube-api-burst`, _int_, Set Kubernetes API client burst limit (default 1000) +- `--kube-api-qps` _float32_, Set Kubernetes API client QPS limit (default 1000) +- `--kubeconfig` _string_, Path to the kubeconfig file ($KCTRL_KUBECONFIG), +- `--kubeconfig-context`_string_, Kubeconfig context override ($KCTRL_KUBECONFIG_CONTEXT) +- `--kubeconfig-yaml` _string_, Kubeconfig contents as YAML ($KCTRL_KUBECONFIG_YAML) +- `--tty` _boolean_, Force TTY-like output (default true) +- `-v`, `--version` _boolean_, version for kctrl +- `-y`, `--yes`, _boolean_, Assumes yes for any prompt + +## Environment variables + +Environment Variables: + - `FORCE_COLOR`: set to `1` to force colors to the printed. Useful to preserve colors when piping output such as in `kctrl app list --tty --all-namespaces |& less -R` diff --git a/site/content/kapp/docs/v0.62.x/config.md b/site/content/kapp/docs/v0.62.x/config.md new file mode 100644 index 000000000..2cb2f326e --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/config.md @@ -0,0 +1,401 @@ +--- +aliases: [/kapp/docs/latest/config] +title: Configuration +--- + +## Overview + +kapp supports custom `Config` resource to specify its own configuration. It's expected to be included with your other Kubernetes configuration. Config resource is never applied to the cluster, though it follows general Kubernetes resource format. Multiple config resources are allowed. + +kapp comes with __built-in configuration__ (see it via `kapp deploy-config`) that includes rules for common resources. + +## Format + +```yaml +apiVersion: kapp.k14s.io/v1alpha1 +kind: Config + +minimumRequiredVersion: 0.23.0 + +rebaseRules: +- path: [spec, clusterIP] + type: copy + sources: [new, existing] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: Service} + +ownershipLabelRules: +- path: [metadata, labels] + resourceMatchers: + - allMatcher: {} + +labelScopingRules: +- path: [spec, selector] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: Service} + +templateRules: +- resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: ConfigMap} + affectedResources: + objectReferences: + - path: [spec, template, spec, containers, {allIndexes: true}, env, {allIndexes: true}, valueFrom, configMapKeyRef] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + - path: [spec, template, spec, containers, {allIndexes: true}, envFrom, {allIndexes: true}, configMapRef] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + +additionalLabels: + department: marketing + cost-center: mar201 + +diffAgainstLastAppliedFieldExclusionRules: +- path: [metadata, annotations, "deployment.kubernetes.io/revision"] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + +diffAgainstExistingFieldExclusionRules: + - path: [status] + resourceMatchers: + - allMatcher: {} + +diffMaskRules: +- path: [data] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: Secret} + +preflightRules: +- name: [preflight] + config: + [preflightSpecific]: [data] +``` + +### minimumRequiredVersion + +`minimumRequiredVersion` forces kapp to exit with a validation error if kapp's version is below minimum required version. Available in v0.23.0+. + +### rebaseRules + +`rebaseRules` specify origin of field values. + +kapp rebase rules explicitly define how to merge resources during an update. To read more about why rebase rules are necessary, see [Resource Merge Method](merge-method.md). +For examples of rebase rules in use, see [HPA and Deployment rebase](hpa-deployment-rebase.md) or [PersistentVolumeClaim rebase](rebase-pvc.md). + +- `rebaseRules` (array) list of rebase rules + - `path` (array of strings) specifies location within a resource to rebase. Mutually exclusive with `paths`. Example: `[spec, clusterIP]` + - `paths` (array of `path`) specifies multiple locations within a resource to rebase. This is a convenience for specifying multiple rebase rules with only different paths. Mutually exclusive with `path`. Available in v0.27.0+. + - `type` (string) specifies strategy to modify field values. Allowed values: `copy` or `remove`. `copy` will update the field value; `remove` will delete the field. + - `sources` (array of `new` or `existing`) specifies a preference order for the source of the referenced field value being rebased. `new` refers to an updated resource from user input, where `existing` refers to a resource already in the cluster. If the field value being rebased is not found in any of the sources provided, kapp will error. Only used with `type: copy`. \ + Examples: + - `[existing, new]` – If field value is present in the `existing` resource on cluster, use that value, otherwise use the value in the `new` user input. + - `[existing]` – Only look for field values in resources already on cluster, corresponding value you provide in new resource will be overwritten. + - `resourceMatchers` (array) specifies rules to find matching resources. See various resource matchers below. + - `ytt` specifies choice as [ytt](https://carvel.dev/ytt/) for rebase rule. Available in v0.38.0+. + - `overlayContractV1` allows to use ytt overlay to modify provided resource based on existing resource. + - `overlay.yml` overlay YAML file. + - Following fields are accessible via `data.values` inside ytt: + - `data.values.existing` resource from live cluster + - `data.values.new` resource from config (post-prep) + - `data.values._current` resource after previous rebase rules already applied + +Rebase rule to `copy` the `clusterIP` field value to `Service`/`v1` resources; if `clusterIp` is present in the `new` user input, use that value, otherwise use the value in `existing` resource on cluster: +```yaml +rebaseRules: +- path: [spec, clusterIP] + type: copy + sources: [new, existing] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: Service} +``` + +Rebase rule to `copy` the `clusterIP` and `healthCheckNodePort` field values from the `existing` resource on cluster, to `Service`/`v1` resources: +```yaml +rebaseRules: +- paths: + - [spec, clusterIP] + - [spec, healthCheckNodePort] + type: copy + sources: [existing] + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: Service} +``` + +See [ytt rebase rule](https://github.com/carvel-dev/kapp/blob/d3ee9a01b5f0d7d5632b6a157ea7d0338730d497/pkg/kapp/config/default.go#L123-L154) (included in default configuration) for retaining cluster added token secret in ServiceAccount's secrets array. + +### ownershipLabelRules + +`ownershipLabelRules` specify locations for inserting kapp generated labels. These labels allow kapp to track which resources belong to which application. For resources that describe creation of other resources (e.g. `Deployment` or `StatefulSet`), configuration may need to specify where to insert labels for child resources that will be created. `kapp.k14s.io/disable-default-ownership-label-rules: ""` (value must be empty) annotation can be be used to exclude an individual resource from default onwership label rules. + +### labelScopingRules + +`labelScopingRules` specify locations for inserting kapp generated labels that scope resources to resources within current application. `kapp.k14s.io/disable-default-label-scoping-rules: ""` (as of v0.33.0+, or use `kapp.k14s.io/disable-label-scoping: ""` in earlier versions) annotation can be used to exclude an individual resource from label scoping. + +### waitRules + +Available in v0.29.0+. + +`waitRules` specify how to wait for resources that kapp does not wait for by default. Each rule provides a way to specify which `status.conditions` indicate success or failure. Once any of the condition matchers successfully match against one of the resource's conditions, kapp will stop waiting for the matched resource and report any failures. (If this functionality is not enough to wait for resources in your use case, please reach out on Slack to discuss further.) + +```yaml +waitRules: +- supportsObservedGeneration: true + conditionMatchers: + - type: Failed + status: "True" + failure: true + - type: Deployed + status: "True" + success: true + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: corp.com/v1, kind: DatabaseInstance} +``` + +```yaml +waitRules: +- supportsObservedGeneration: true + conditionMatchers: + - type: Ready + status: "False" + failure: true + - type: Ready + status: "True" + success: true + supportsObservedGeneration: true # available at condition level from v0.47.0+ + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: corp.com/v1, kind: Application} +``` + +Available in v0.48.0+. + +ytt `waitRules` can be for Custom Resources that don't have `conditions` field in their `status`. This allows users to configure arbitrary rules. `is_done(resource)` method can be defined as part of a ytt waitRule to return the done state based on resource fields. + +```yaml +waitRules: + - ytt: + funcContractV1: + resource.star: | + def is_done(resource): + state = resource.status.currentState + if state == "Failed": + return {"done": True, "successful": False, "message": "Current state as Failed"} + elif state == "Running": + return {"done": True, "successful": True, "message": "Current state as Running"} + else: + return {"done": False, "successful": False, "message": "Not in Failed or Running state"} + end + end + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: , kind: } +``` + +Available in v0.50.0+ + +`unblockChanges` can be used for conditions to unblock any dependent resources. These conditions are treated as non success/failure conditions. It can also be used along with ytt waitRules. + +```yaml +waitRules: +- conditionMatchers: + - type: Progressing + status: "True" + unblockChanges: true + resourceMatchers: + - apiVersionKindMatcher: {apiVersion: corp.com/v1, kind: Application} +``` + +### templateRules + +`templateRules` specify how versioned resources affect other resources. In above example, versioned config maps are said to affect deployments. [Read more about versioned resources](diff.md#versioned-resources). + +### additionalLabels + +`additionalLabels` specify additional labels to apply to all resources for custom uses by the user (added based on `ownershipLabelRules`). + +### diffAgainstLastAppliedFieldExclusionRules + +`diffAgainstLastAppliedFieldExclusionRules` specify which fields should be removed before diff-ing against last applied resource. These rules are useful for fields are "owned" by the cluster/controllers, and are only later updated. For example `Deployment` resource has an annotation that gets set after a little bit of time after resource is created/updated (not during resource admission). It's typically not necessary to use this configuration. + +### diffAgainstExistingFieldExclusionRules + +`diffAgainstExistingFieldExclusionRules` specify which fields should be removed before diff-ing against a resource. These rules are useful for fields that are "owned" by the cluster/controllers, and are only updated later. For example a `Custom Resource Definition` resource has a `status` field that gets altered now and then, especially between a diff and the actual apply step. It's typically not necessary to use this configuration. + +### diffMaskRules + +`diffMaskRules` specify which field values should be masked in diff. By default `v1/Secret`'s `data` fields are masked. Currently only applied to `deploy` command. + +### preflightRules + +Available in v0.61.0+. + +`preflightRules` specify configuration for [preflight checks](preflight.md). Specifying the `name` of a preflight check enables it; additional configuration via the `config` field may be optionally provided. The contents of the `config` field are specific to each preflight check. + +The `--preflight` flag overrides the enabled setting in the configuration: +* If a preflight check is omitted from the `--preflight` flag, it is disabled regardless of its presence in the configuration file. +* If a preflight check is specified in the `--preflight` flag, it is enabled regardless of its absence in the configuration file. + +### changeGroupBindings + +Available in v0.25.0+. + +`changeGroupBindings` bind specified change group to resources matched by resource matchers. This is an alternative to using `kapp.k14s.io/change-group` annotation to add change group to resources. See `kapp deploy-config` for default bindings. + +### changeRuleBindings + +Available in v0.25.0+. + +`changeRuleBindings` bind specified change rules to resources matched by resource matchers. This is an alternative to using `kapp.k14s.io/change-rule` annotation to add change rules to resources. See `kapp deploy-config` for default bindings. + +--- +## Resource matchers + +Resource matchers (as used by `rebaseRules`, `ownershipLabelRules`, `labelScopingRules`, `templateRules`, `diffAgainstLastAppliedFieldExclusionRules`, `diffAgainstExistingFieldExclusionRules` and `diffMaskRules`): + +### allMatcher + +Matches all resources + +```yaml +allMatcher: {} +``` + +### anyMatcher + +Matches resources that match one of matchers + +```yaml +anyMatcher: + matchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + - apiVersionKindMatcher: {apiVersion: extensions/v1alpha1, kind: Deployment} +``` + +### notMatcher + +Matches any resource that does not match given matcher + +```yaml +notMatcher: + matcher: + apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} +``` + +### andMatcher + +Matches any resource that matches all given matchers + +```yaml +andMatcher: + matchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + - hasNamespaceMatcher: {} +``` + +### apiGroupKindMatcher + +```yaml +apiGroupKindMatcher: {apiGroup: apps, kind: Deployment} +``` + +### apiVersionKindMatcher + +```yaml +apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} +``` + +### kindNamespaceNameMatcher + +```yaml +kindNamespaceNameMatcher: {kind: Deployment, namespace: mysql, name: mysql} +``` + +### hasAnnotationMatcher + +Matches resources that have particular annotation + +```yaml +hasAnnotationMatcher: + keys: + - kapp.k14s.io/change-group +``` + +### hasNamespaceMatcher + +Matches any resource that has a non-empty namespace + +```yaml +hasNamespaceMatcher: {} +``` + +Matches any resource with namespace that equals to one of the specified names + +```yaml +hasNamespaceMatcher: + names: [app1, app2] +``` + +### customResourceMatcher + +Matches any resource that is not part of builtin k8s API groups (e.g. apps, batch, etc.). It's likely that over time some builtin k8s resources would not be matched. + +```yaml +customResourceMatcher: {} +``` + +### emptyFieldMatcher + +Available in v0.34.0+. + +Matches any resource that has empty specified field + +```yaml +emptyFieldMatcher: + path: [aggregationRule] +``` + +--- +## Paths + +Path specifies location within a resource (as used `rebaseRules` and `ownershipLabelRules`): + +``` +[spec, clusterIP] +``` + +``` +[spec, volumeClaimTemplates, {allIndexes: true}, metadata, labels] +``` + +``` +[spec, volumeClaimTemplates, {index: 0}, metadata, labels] +``` + +--- +## Config wrapped in ConfigMap + +Available of v0.34.0+. + +Config resource could be wrapped in a ConfigMap to support same deployment configuration by tools that do not understand kapp's `Config` resource directly. ConfigMap carrying kapp config must to be labeled with `kapp.k14s.io/config` and have `config.yml` data key. Such config maps will be applied to the cluster, unlike config given as `Config` resource. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-kapp-config + labels: + kapp.k14s.io/config: "" +data: + config.yml: | + apiVersion: kapp.k14s.io/v1alpha1 + kind: Config + rebaseRules: + - path: [rules] + type: copy + sources: [existing, new] + resourceMatchers: + - notMatcher: + matcher: + emptyFieldMatcher: + path: [aggregationRule] +``` + +NOTE: `kapp` is _only_ affected by a `Config` (whether wrapped in a `ConfigMap` or not) when supplied as a direct input (i.e. as a `-f` argument). Any `ConfigMap` containing a `Config` is already present in the target cluster has _no affect whatsoever_ on `kapp`'s behavior. diff --git a/site/content/kapp/docs/v0.62.x/configmap-migration.md b/site/content/kapp/docs/v0.62.x/configmap-migration.md new file mode 100644 index 000000000..9d1d3a4f7 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/configmap-migration.md @@ -0,0 +1,125 @@ +--- +aliases: [/kapp/docs/latest/configmap-migration] +title: Configmap Migration (experimental) +--- + +## Overview + +Kapp internally uses a configmap to store information about an application. + +This configmap name has defaulted to the app name supplied during a deploy. `kapp deploy -a `. + +Example: + +```bash +kapp deploy -a my-app -f app.yml --yes + +$ kapp ls +Namespace Name Namespaces Lcs Lca +default my-app default true 7s + +$ kubectl get configmaps + +NAME DATA AGE +my-app 1 1m +``` + +This is challenging when users also want to create a configmap named `my-app` for their application. It is not expected that `kapp` is already using this configmap name. + +## Enabling Configmap migration + +As of v0.47.0+, kapp now supports a new optional boolean environment variable `KAPP_FQ_CONFIGMAP_NAMES` which can be used to migrate **both new and existing configmaps** to the new naming convention: `.apps.k14s.io`. + +- `KAPP_FQ_CONFIGMAP_NAMES=true` opts into the new kapp behavior. +- `KAPP_FQ_CONFIGMAP_NAMES=false` maintains the current kapp behavior. + +*Important Note: The app name is not being changed, only the configmap name, all references to the app name can remain the same.* + +### Examples + +#### Deploy new App + +```bash +export KAPP_FQ_CONFIGMAP_NAMES=true + +kapp deploy -a my-app -f app.yml --yes + +$ kapp ls +Namespace Name Namespaces Lcs Lca +default my-app default true 7s + +$ kubectl get configmaps + +NAME DATA AGE +my-app.apps.k14s.io 1 1m +``` + +#### Deploy existing App + +```bash +$ kapp ls +Namespace Name Namespaces Lcs Lca +default my-app default true 7s + +export KAPP_FQ_CONFIGMAP_NAMES=true + +$ kapp deploy -a my-app -f app.yml --yes + +$ kubectl get configmaps + +NAME DATA AGE +my-app.apps.k14s.io 1 1m +``` + +#### Delete + +```bash +# With migration enabled +$ KAPP_FQ_CONFIGMAP_NAMES=true kapp delete -a my-app + +Changes + +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default simple-app Deployment 2/2 t 28m delete - delete ok - + +# With migration disabled +$ KAPP_FQ_CONFIGMAP_NAMES=false kapp delete -a my-app + +App 'my-app' (namespace: default) does not exist + +``` + +### Caveats + +1. Migrated apps will show up with the suffix with previous versions of kapp (0.46.0-): + +```bash +export KAPP_FQ_CONFIGMAP_NAMES=true + +kapp deploy -a my-app -f app.yml --yes + +$ kapp ls +Namespace Name Namespaces Lcs Lca +default my-app default true 7s + +# With old kapp versions +$ kapp ls +Namespace Name Namespaces Lcs Lca +default my-app.apps.k14s.io default true 7s +``` + +### Opting out after migration + +To return to the previous configmap naming convention, the following steps must be followed: + +1. `kubectl get configmap my-app.apps.k14s.io -o yaml > app.yml` + +2. Find the `metadata.name` field in `app.yml` and remove the suffix `.apps.k14s.io` + +3. Find the annotation named `kapp.k14s.io/is-configmap-migrated` in `metadata.annotations` and remove it + +4. `kubectl create -f app.yml` + +5. `kubectl delete configmap my-app.apps.k14s.io` + +*Important Note: Ensure the configmap with suffix `apps.k14s.io` is deleted after opting-out!* diff --git a/site/content/kapp/docs/v0.62.x/dangerous-flags.md b/site/content/kapp/docs/v0.62.x/dangerous-flags.md new file mode 100644 index 000000000..14bccdb53 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/dangerous-flags.md @@ -0,0 +1,38 @@ +--- +aliases: [/kapp/docs/latest/dangerous-flags] +title: Dangerous Flags +--- + +## Overview + +There are several flags in `kapp deploy/delete/etc.` commands that might be helpful in rare cases, but can cause problems if used improperly. These are their stories: + +## `--dangerous-allow-empty-list-of-resources` + +This flag allows `kapp deploy` to accept empty set of new resources. Given that kapp deploy converges set of resources, when empty set is provided, kapp will delete all existing resources. + +This commonly happens unintentionally. When configuration is piped into kapp (e.g. `ytt -f config/ | kapp deploy -f- ...`) and resource producing command fails (ytt in this example), kapp will not receive any resources by the time is closes. Since providing empty set of resources intentionally is pretty rare, this functionality is behind a flag. + +## `--dangerous-override-ownership-of-existing-resources` + +This flag allows `kapp deploy` to take ownership of resources that are already associated with another application (i.e. already has `kapp.k14s.io/app` label with a different value). + +Most commonly user may have _unintentionally_ included resource that is already deployed, hence by default we do not want to override that resource with a new copy. This may happen when multiple apps accidently specified same resource (i.e. same name under same namespace). In most cases this is not what user wants. + +This flag may be useful in cases when multiple applications (managed by kapp) need to be merged into one, or may be previously owning application have been deleted but its resources were kept. + +Note that by default if resource is given to kapp and it already exists in the cluster, and is not owned by another application, kapp will label it to belong to deploying app. + +## `--dangerous-ignore-failing-api-services` + +In some cases users may encounter that they have misbehaving `APIServices` within they cluster. Since `APIServices` affect how one finds existing resources within a cluster, by default kapp will show error similar to below and stop: + +``` +Error: ... unable to retrieve the complete list of server APIs: <...>: the server is currently unable to handle the request +``` + +In cases when APIService cannot be fixed, this flag can be used to let kapp know that it is okay to proceed even though it's not able to see resources under that `APIService`. Note when this flag is used, kapp will effectively think that resources under misbehaving `APIService` do not exist. + +## `--dangerous-disable-gk-scoping` + +In `kapp deploy` resource searching is scoped to the GroupKinds used in the app, to keep the number of api requests to the api server to a minimum. This flag can be used to disable the scoping and search across all GroupKinds. diff --git a/site/content/kapp/docs/v0.62.x/diff.md b/site/content/kapp/docs/v0.62.x/diff.md new file mode 100644 index 000000000..d0535d9ec --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/diff.md @@ -0,0 +1,378 @@ +--- +aliases: [/kapp/docs/latest/diff] +title: Diff stage +--- +## Overview + +kapp compares resources specified in files against resources that exist in Kubernetes API. Once change set is calculated, it provides an option to apply it (see [Apply](apply.md) section for further details). + +There are five different types of operations: `create`, `update`, `delete`, `noop` (shown as empty), `exists` (added in v0.43.0). Seen in `Op` column of diff summary table. Additionally there is `Op strategy` column (shorted as `Op st.`), added in v0.31.0+, that shows supplemental information how operation will be performed (for example [`fallback on replace`](apply.md#kappk14sioupdate-strategy) for `update` operation). + +There are three different types of waiting: `reconcile` (waits until resource has converged to its desired state; see [apply waiting](apply-waiting.md) for waiting semantics), `delete` (waits until resource is gone), `noop` (shown as empty). Seen in `Wait to` column of diff summary table. + +## Diff strategies + +There are two diff strategies used by kapp: + +1. kapp compares against last applied resource content (previously applied by kapp; stored in annotation `kapp.k14s.io/original`) **if** there were no outside changes done to the resource (i.e. done outside of kapp, for example, by another team member or controller); kapp tries to use this strategy as much as possible to produce more user-friendly diffs. + +2. kapp compares against live resource content **if** it detects there were outside changes to the resource (hence, sometimes you may see a diff that shows several deleted fields even though these fields are not specified in the original file) + +Strategy is selected for each resource individually. You can control which strategy is used for all resources via `--diff-against-last-applied=bool` flag. + +Related: [rebase rules](config.md/#rebaserules). + +## Versioned Resources + +In some cases it's useful to represent an update to a resource as an entirely new resource. Common example is a workflow to update ConfigMap referenced by a Deployment. Deployments do not restart their Pods when ConfigMap changes making it tricky for wide variety of applications for pick up ConfigMap changes. kapp provides a solution for such scenarios, by offering a way to create uniquely named resources based on an original resource. + +Anytime there is a change to a resource marked as a versioned resource, entirely new resource will be created instead of updating an existing resource. + +To make resource versioned, add `kapp.k14s.io/versioned` annotation with an empty value. Created resource follow `{resource-name}-ver-{n}` naming pattern by incrementing `n` any time there is a change. + +Example: +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: secret-sa-sample + annotations: + kapp.k14s.io/versioned: "" +``` +This will create versioned resource named `secret-sa-sample-ver-1` + +```bash +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default secret-sa-sample-ver-1 Secret - - create - reconcile - - + +Op: 1 create, 0 delete, 0 update, 0 noop, 0 exists +Wait to: 1 reconcile, 0 delete, 0 noop +``` + +Additionally kapp follows configuration rules (default ones, and ones that can be provided as part of application) to find and update object references (since new resource name is not something that configuration author knew about). + +{{< detail-tag "Example" >}} +Sample Config +```yaml +apiVersion: kapp.k14s.io/v1alpha1 +kind: Config +templateRules: + - resourceMatchers: + - apiVersionKindMatcher: {apiVersion: v1, kind: ConfigMap} + affectedResources: + objectReferences: + - resourceMatchers: + - apiVersionKindMatcher: {apiVersion: apps/v1, kind: Deployment} + path: [spec, template, spec, containers, {allIndexes: true}, env, {allIndexes: true}, valueFrom, configMapKeyRef] +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: special-config + annotations: + kapp.k14s.io/versioned: "" +data: + special.how: very-good +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx +spec: + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + env: + - name: SPECIAL_LEVEL_KEY + valueFrom: + configMapKeyRef: + name: special-config + key: special.how +``` +Here we have specified the configuration rules that will update the ConfigMap object reference in resources of Kind Deployment. Here `ConfigMap` special-config is marked as versioned so anytime there is an update it will create a new resource with name `special-config-ver-{n}` and update the same name in resource of kind `Deployment` under `configMapKeyRef`. This example is part of [default configuration rule](https://github.com/carvel-dev/kapp/blob/28b17b775558ef4c64ce27a5655b81c00c8a2f59/pkg/kapp/config/default.go#L299) that kapp follows. +{{< /detail-tag >}} + +As of v0.38.0+, `kapp.k14s.io/versioned-keep-original` annotation can be used in conjunction with `kapp.k14s.io/versioned` to have the original resource (resource without `-ver-{n}` suffix in name) along with versioned resource. + +Example: +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: secret-sa-sample + annotations: + kapp.k14s.io/versioned: "" + kapp.k14s.io/versioned-keep-original: "" +``` +This will create two resources one with original name `secret-sa-sample` and one with `-ver-{n}` suffix in name `secret-sa-sample-ver-1`. +```bash +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default secret-sa-sample Secret - - create - reconcile - - +^ secret-sa-sample-ver-1 Secret - - create - reconcile - - + +Op: 2 create, 0 delete, 0 update, 0 noop, 0 exists +Wait to: 2 reconcile, 0 delete, 0 noop +``` + +You can control number of kept resource versions via `kapp.k14s.io/num-versions=str(int)` annotation, e.g. `kapp.k14s.io/num-versions: "5"`. + +As of v0.41.0+, the `kapp.k14s.io/versioned-explicit-ref` can be used to explicitly refer to a versioned resource. This annotation allows a resource to be updated whenever a new version of the referred resource is created. + +Multiple annotations with the prefix `kapp.k14s.io/versioned-explicit-ref.`(Note the "." at the end) can be used to define multiple explicit references. + +Example: +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-1 + annotations: + kapp.k14s.io/versioned: "" +data: + foo: bar +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-2 + annotations: + kapp.k14s.io/versioned-explicit-ref: | + apiVersion: v1 + kind: ConfigMap + name: config-1 +data: + foo: bar +``` +Here, `config-2` explicitly refers `config-1` and is updated with the latest versioned name when `config-1` is versioned. +```bash +@@ create configmap/config-1-ver-2 (v1) namespace: default @@ + ... + 1, 1 data: + 2 - foo: bar + 2 + foo: alpha + 3, 3 kind: ConfigMap + 4, 4 metadata: +@@ update configmap/config-2 (v1) namespace: default @@ + ... + 8, 8 kind: ConfigMap + 9 - name: config-1-ver-1 + 9 + name: config-1-ver-2 + 10, 10 creationTimestamp: "2021-09-29T17:27:34Z" + 11, 11 labels: + +Changes + +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default config-1-ver-2 ConfigMap - - create - reconcile - - +^ config-2 ConfigMap - 14s update - reconcile ok - +``` + +Try deploying [redis-with-configmap example](https://github.com/carvel-dev/kapp/tree/develop/examples/gitops/redis-with-configmap) and changing `ConfigMap` in a next deploy. + +--- +## Controlling diff via resource annotations + +### kapp.k14s.io/disable-original + +kapp, by default, records the resource copy into its annotation `kapp.k14s.io/original` while applying the resource to the cluster. + +{{< detail-tag "Example" >}} +Sample Config +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-1 + namespace: default +data: + foo: bar +``` +After deploying the resource, kapp added the annotation `kapp.k14s.io/original` with the content of the resource that was given to kapp: + +```bash +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-1 + namespace: default + annotations: + kapp.k14s.io/original: '{ "apiVersion": "v1", "kind": "ConfigMap", ...snip... }' +data: + foo: bar +``` +{{< /detail-tag >}} + +`kapp.k14s.io/disable-original` annotation controls whether to record provided resource copy (rarely wanted) + +Possible values: "" (empty). In some cases it's not possible or wanted to record applied resource copy into its annotation `kapp.k14s.io/original`. One such case might be when resource is extremely lengthy (e.g. long ConfigMap or CustomResourceDefinition) and will exceed annotation value max length of 262144 bytes. + +{{< detail-tag "Example" >}} +Sample Config +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-1 + namespace: default + annotations: + kapp.k14s.io/disable-original: "" +data: + foo: bar +``` +After deploying the resource, kapp didn't add the annotation `kapp.k14s.io/original` this time: + +```bash +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-1 + namespace: default + annotations: + kapp.k14s.io/disable-original: "" +data: + foo: bar +``` +{{< /detail-tag >}} + +--- +## Controlling diff via deploy flags + +Diff summary shows quick information about what's being changed: +- `--diff-summary=bool` (default `true`) shows diff summary, listing how resources have changed + {{< detail-tag "Example" >}} +Sample config +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: sample +stringData: + foo: bar +``` +```bash +$ kapp deploy -a sample-secret -f config.yaml --diff-summary=true +Target cluster 'https://127.0.0.1:56540' (nodes: kind-control-plane) + +Changes + +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default sample Secret - - create - reconcile - - + +Op: 1 create, 0 delete, 0 update, 0 noop, 0 exists +Wait to: 1 reconcile, 0 delete, 0 noop + +Continue? [yN]: +``` + {{< /detail-tag >}} + +Diff changes (line-by-line diffs) are useful for looking at actual changes, when app is re-deployed: +- `--diff-changes=bool` (`-c`) (default `false`) shows line-by-line diffs +- `--diff-context=int` (default `2`) controls number of lines to show around changed lines +- `--diff-mask=bool` (default `true`) controls whether to mask sensitive fields + {{< detail-tag "Example" >}} +Sample config +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: sample +stringData: + foo: bar +``` +```bash +# deploy sample-secre app +$ kapp deploy -a sample-secret -f config.yaml + +#update config +... +stringData: + foo: bars +... + +# re-deploy sample-secret app with required diff-changes flag to see line by line changes +$ kapp deploy -a sample-secret -f config.yaml --diff-changes=true --diff-context=4 +Target cluster 'https://127.0.0.1:56540' (nodes: kind-control-plane) + +@@ update secret/sample (v1) namespace: default @@ + ... + 30, 30 resourceVersion: "244751" + 31, 31 uid: b2453c2a-8dc8-4ed1-9b59-791547f78ea8 + 32, 32 stringData: + 33 - foo: <-- value not shown (#1) + 33 + foo: <-- value not shown (#2) + 34, 34 + +Changes + +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default sample Secret - 7m update - reconcile ok - + +Op: 0 create, 0 delete, 1 update, 0 noop, 0 exists +Wait to: 1 reconcile, 0 delete, 0 noop + +Continue? [yN]: + +# --diff-mask=true by default, note the masked value for secret data + +# try out kapp deploy -a sample-secret -f config.yaml --diff-mask=false --diff-changes=true --diff-context=2 +``` + {{< /detail-tag >}} + +Controlling how diffing is done: + +- `--diff-against-last-applied=bool` (default `true`) forces kapp to use particular diffing strategy (see above). +- `--diff-run=bool` (default `false`) set the flag to true, to stop after showing diff information. +- `--diff-exit-status=bool` (default `false`) controls exit status for diff runs (`0`: unused, `1`: any error, `2`: no changes, `3`: pending changes) + {{< detail-tag "Example" >}} + Sample config +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: sample +stringData: + foo: bar +``` +```bash +# deploy secret-sample app +$ kapp deploy -a secret-sample -f config.yaml --diff-run=true --diff-exit-status=true +Target cluster 'https://127.0.0.1:56540' (nodes: kind-control-plane) + +Changes + +Namespace Name Kind Conds. Age Op Op st. Wait to Rs Ri +default sample Secret - - create - reconcile - - + +Op: 1 create, 0 delete, 0 update, 0 noop, 0 exists +Wait to: 1 reconcile, 0 delete, 0 noop + +kapp: Error: Exiting after diffing with pending changes (exit status 3) + +# note that kapp exits after diff and displays the exit status + +``` + {{< /detail-tag >}} + +Diff filter allows to filter changes based on operation (add/update/delete), newResource (configuration provided to kapp) and existingResource (resources in Kubernetes cluster) + +- `--diff-filter='{"and":[{"ops":["update"]},{"existingResource":{"kinds":["Deployment"]}]}'` will keep the resources which are getting updated and were of kind Deployment. diff --git a/site/content/kapp/docs/v0.62.x/faq.md b/site/content/kapp/docs/v0.62.x/faq.md new file mode 100644 index 000000000..50318f573 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/faq.md @@ -0,0 +1,128 @@ +--- +aliases: [/kapp/docs/latest/faq] +title: FAQ +--- + +## Migrating from `kubectl apply` to kapp + +Switching from `kubectl apply` to `kapp deploy` will allow kapp to adopt resources mentioned in a given config. +However, kapp will try to insert a few of its labels in bodies of some resources, like Deployments, which may fail due to those resources having immutable fields that kapp tries to update (spec.selector on Deployments). + +To prevent this failure, add the [`kapp.k14s.io/disable-default-label-scoping-rules: ""` annotation](config.md#labelscopingrules) as a [kapp configuration](config.md) to prevent kapp from touching the immutable fields when adopting a resource. + +Additional Resources: [GitHub Issue](https://github.com/carvel-dev/kapp/issues/204), [Slack Thread](https://kubernetes.slack.com/archives/CH8KCCKA5/p1606079730457700) + +## `Error: Asking for confirmation: EOF` + +This probably means you have piped configuration into kapp and did not specify `--yes` (`-y`) flag to continue. It's necessary because kapp can no longer ask for confirmation via stdin. Feel free to re-run the command with `--diff-changes` (`-c`) to make sure pending changes are correct. Instead of using a pipe you can also use an anonymous fifo keeping stdin free for the confirmation prompt, e.g. `kapp deploy -a app1 -f <(ytt -f config/)` + +--- +## Where to store app resources (i.e. in which namespace)? + +See [state namespace](state-namespace.md) doc page. + +--- +## `... Field is immutable` error + +> After changing the labels/selectors in one of my templates, I'm getting the `MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable (reason: Invalid)` errors on deployment resource. Is there a way to tell kapp to force the change? + +[via slack](https://kubernetes.slack.com/archives/CH8KCCKA5/p1565600090224400) + +Some fields on a resource are immutable. kapp provides a `kapp.k14s.io/update-strategy` annotation that controls how kapp will update resource. One of the strategies is `fallback-on-replace` which will have kapp recreate an object (delete, wait, then create) if initial update results in `Invalid` error. See [Controlling apply via resource annotations](apply.md#controlling-apply-via-resource-annotations) for details. + +--- +## `Job.batch is invalid: ... spec.selector: Required value` error + +`batch.Job` resource is augmented by the Job controller with unique labels upon its creation. When using kapp to subsequently update existing Job resource, API server will return `Invalid` error since given configuration does not include `spec.selector`, and `job-name` and `controller-uid` labels. kapp's [rebase rules](config.md#rebaserules) can be used to copy over necessary configuration from server side copy; however, since Job resource is mostly immutable, we recommend to use [`kapp.k14s.io/update-strategy` annotation](apply.md#kappk14sioupdate-strategy) set to `fallback-on-replace` to recreate Job resource with any updates. + +--- +## Updating Deployments when ConfigMap changes + +> Can kapp force update on ConfigMaps in Deployments/DaemonSets? Just noticed that it didn't do that and I somehow expected it to. + +[via slack](https://kubernetes.slack.com/archives/CH8KCCKA5/p1565624685226400) + +kapp has a feature called [versioned resources](diff.md#versioned-resources) that allows kapp to create uniquely named resources instead of updating resources with changes. Resources referencing versioned resources are forced to be updated with new names, and therefore are changed, thus solving a problem of how to propagate changes safely. + +--- +## Quick way to find common kapp command variations + +See [cheatsheet](cheatsheet.md). + +--- +## Limit number of ReplicaSets for Deployments + +> Everytime I do a new deploy w/ kapp I see a new replicaset, along with all of the previous ones. + +[via slack](https://kubernetes.slack.com/archives/CH8KCCKA5/p1565887856281400) + +`Deployment` resource has a field `.spec.revisionHistoryLimit` that controls how many previous `ReplicaSets` to keep. See [Deployment's clean up polciy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#clean-up-policy) for more details. + +--- +## Changes detected immediately after successful deploy + +Sometimes Kubernetes API server will convert submitted field values into their canonical form server-side. This will be detected by kapp as a change during a next deploy. To avoid such changes in future, you will have to change your provided field values to what API server considers as canonical. + +``` +... +186 - cpu: "2" +187 - memory: 1Gi + 170 + cpu: 2000m + 171 + memory: 1024Mi +... +``` + +Consider using [ytt](/ytt) and [its overlay feature](/ytt/docs/latest/lang-ref-ytt-overlay/) to change values if you do not control source configuration. + +--- +## Changes detected after resource is modified server-side + +There might be cases where other system actors (various controllers) may modify resource outside of kapp. Common example is Deployment's `spec.replicas` field is modified by Horizontal Pod Autoscaler controller. To let kapp know of such external behaviour use custom `rebaseRules` configuration (see [HPA and Deployment rebase](hpa-deployment-rebase.md) for details). + +--- +## Colors are not showing up in my CI build, in my terminal, etc. + +Try setting `FORCE_COLOR=1` environment variable to force enabling color output. Available in v0.23.0+. + +--- +## How can I version apps deployed by kapp? + +kapp itself does not provide any notion of versioning, since it's just a tool to reconcile config. We recommend to include a ConfigMap in your deployment with application metadata e.g. git commit, release notes, etc. + +--- +## `Resource ... is associated with a different label value` + +Resource ownership is tracked by app labels. kapp expects that each resource is owned by exactly one app. + +If you are receiving this error and are using correct app name, it might be that you are targeting wrong namespace where app is located. Use `--namespace` to set correct namespace. + +Additional resources: [State Namespace](state-namespace.md), [Slack Thread](https://kubernetes.slack.com/archives/CH8KCCKA5/p1589264289257000) + +--- +## Why does kapp hang when trying to delete a resource? + +By default, kapp won't delete resources it didn't create. You can see which resources are owned by kapp in output of `kapp inspect -a app-name` in its `Owner` column. You can force kapp to apply this ignored change using `--apply-ignored` [flag](apply.md#controlling-apply-via-deploy-flags). Alternatively if you are able to set [kapp.k14s.io/owned-for-deletion](apply.md#kappk14sioowned-for-deletion) annotation on resource that will be created, kapp will take that as a request to "own it" for deletion. This comes in handy for example with PVCs created by StatefulSet. + +--- +## How does kapp handle merging? + +kapp explicitly decided against _basic_ 3 way merge, instead allowing the user to specify how to resolve conflicts via rebase rules. + +Resources: [merge method](merge-method.md), [rebase rules](config.md#rebaserules) + +--- +## Can I force an update for a change that does not produce a diff? + +If kapp does not detect changes, it won't perform an update. To force changes every time you can set [`kapp.k14s.io/nonce`](apply.md#kappk14siononce) annotation. That way, every time you deploy the resource will appear to have changes. + +--- +## How can I remove decorative headings from kapp inspect output? + +Use `--tty=false` flag which will disable decorative output. Example: `kapp inspect --raw --tty=false`. + +Additional resources: [tty flag in kapp code](https://github.com/carvel-dev/kapp/blob/3f3e207d7198cdedd6985761ecb0d9616a84e305/pkg/kapp/cmd/ui_flags.go#L20) + +--- +## How can I get kapp to skip waiting on some resources? + +kapp allows to control waiting behavior per resource via [resource annotations](apply-waiting.md#controlling-waiting-via-resource-annotations). When used, the resource will be applied to the cluster, but will not wait to reconcile. diff --git a/site/content/kapp/docs/v0.62.x/gitops.md b/site/content/kapp/docs/v0.62.x/gitops.md new file mode 100644 index 000000000..156a06c19 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/gitops.md @@ -0,0 +1,17 @@ +--- +aliases: [/kapp/docs/latest/gitops] +title: GitOps +--- + +## Using kapp with GitOps workflow + +kapp provides a set of commands to make GitOps workflow very easy. Assuming that you have a CI environment or some other place where `kapp` can run based on a trigger (e.g. for every Git repo change) or continuously (e.g. every 5 mins), you can use following command: + +```bash +$ ls my-repo +. .. app1/ app2/ app3/ + +$ kapp app-group deploy -g my-env --directory my-repo +``` + +Above command will deploy an application for each subdirectory in `my-repo` directory (in this case `app1`, `app2` and `app3`). It will also remove old applications if subdirectories are deleted. diff --git a/site/content/kapp/docs/v0.62.x/hpa-deployment-rebase.md b/site/content/kapp/docs/v0.62.x/hpa-deployment-rebase.md new file mode 100644 index 000000000..722c9bc68 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/hpa-deployment-rebase.md @@ -0,0 +1,42 @@ +--- +aliases: [/kapp/docs/latest/hpa-deployment-rebase] +title: HPA and Deployment rebase +--- +## HPA and Deployment rebase + +Here is an example on how to use custom `rebaseRules` to "prefer" server chosen value for `spec.replicas` field for a particular Deployment. + +```yaml +apiVersion: kapp.k14s.io/v1alpha1 +kind: Config +rebaseRules: +- path: [spec, replicas] + type: copy + sources: [existing, new] + resourceMatchers: + - kindNamespaceNameMatcher: + kind: Deployment + namespace: my-ns + name: my-app +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: my-ns +... +--- +apiVersion: autoscaling/v1 +kind: HorizontalPodAutoscaler +metadata: + name: my-app + namespace: my-ns +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: my-app + minReplicas: 1 + maxReplicas: 10 + targetCPUUtilizationPercentage: 50 +``` diff --git a/site/content/kapp/docs/v0.62.x/install.md b/site/content/kapp/docs/v0.62.x/install.md new file mode 100644 index 000000000..c4d30dbad --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/install.md @@ -0,0 +1,58 @@ +--- +aliases: [/kapp/docs/latest/install] +title: Install +--- + +## Via script (macOS or Linux) + +(Note that `install.sh` script installs other Carvel tools as well.) + +Install binaries into specific directory: + +```bash +$ mkdir local-bin/ +$ curl -L https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR=local-bin bash + +$ export PATH=$PWD/local-bin/:$PATH +$ kapp version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ kapp version +``` + +## Via Homebrew (macOS or Linux) + +Based on [github.com/carvel-dev/homebrew](https://github.com/carvel-dev/homebrew). + +```bash +$ brew tap carvel-dev/carvel +$ brew install kapp +$ kapp version +``` + +## Specific version from a GitHub release + +To download, click on one of the assets in a [chosen GitHub release](https://github.com/carvel-dev/kapp/releases), for example for 'kapp-darwin-amd64'. + +```bash +# **Compare binary checksum** against what's specified in the release notes +# (if checksums do not match, binary was not successfully downloaded) +$ shasum -a 256 ~/Downloads/kapp-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/kapp-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/kapp-darwin-amd64 /usr/local/bin/kapp + +# Make binary executable +$ chmod +x /usr/local/bin/kapp + +# Check its version +$ kapp version +``` diff --git a/site/content/kapp/docs/v0.62.x/integrating-with-other-tools.md b/site/content/kapp/docs/v0.62.x/integrating-with-other-tools.md new file mode 100644 index 000000000..aa84510bf --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/integrating-with-other-tools.md @@ -0,0 +1,27 @@ +--- +aliases: [/kapp/docs/latest/integrating-with-other-tools] +title: Integrating with Other Tools +--- + +**Note:** This is a non-exhaustive list of integrations + +## ytt and kbld + +We recommend to use kapp with [ytt](/ytt) and [kbld](/kbld) to cover your configuration templating and image building needs. Typical workflow may look like this: + +```bash +ytt -f config/ | kbld -f - | kapp deploy -a app1 -f- -c -y +``` + +## Helm + +If you want to take advantage of both Helm templating and kapp deployment mechanisms, you can use `helm template` command to build configuration, and have kapp apply to the cluster: + +```bash +helm template ... | kapp deploy -a app1 -f- -c -y +``` + +## PV labeling controller + +If you want to have better visibility into which persistent volumes (PVs) are associated with persistent volume claims (PVCs), you can install [https://github.com/k14s/pv-labeling-controller](https://github.com/k14s/pv-labeling-controller) so that it copies several kapp applied labels to associated PVs. Once that's done you will see PVs in `kapp inspect` output. + diff --git a/site/content/kapp/docs/v0.62.x/merge-method.md b/site/content/kapp/docs/v0.62.x/merge-method.md new file mode 100644 index 000000000..ae06ce516 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/merge-method.md @@ -0,0 +1,27 @@ +--- +aliases: [/kapp/docs/latest/merge-method] +title: "Resource Merge Method" +--- + +## Why not basic 3 way merge? + +kapp explicitly decided to _not_ do basic 3 way merge, and instead allow the user to specify how to resolve "conflicts". Here is our thinking: + +- you as an operator have a set of files (input files given to kapp via -f) which describe desired configuration +- cluster has resources that need to be converged to whatever input files specify, with one exception: in some cases, cluster is the source of truth for certain information (but not most) and should keep that state on resources (common examples: some annotation on Deployment, clusterIP on Service, etc.) + +Given information above there are multiple ways to converge: + +- make assumptions about how to merge things (basic 3 way merge, what kubectl and helm does afaik) +- be explicit about how to merge things (kapp with rebase rules) +- or, just override + +Overriding is not really an option as it removes potentially important cluster changes (e.g. removes replicas value as scaled by HPA). + +Regarding explicit vs implicit: we decided to go with the explicit option. kapp allows users to add [rebase rules](config.md#rebaserules) to specify exactly which information to retain from existing resources. That gives control to the user to decide what's important to be kept based on cluster state and what's not. This method ensures that there are no _surprising_ changes left in the cluster (if basic 3 way merge was used, then user cannot confidently know how final resource will look like; ... imagine if you had a field `allowUnauthenticatedRequests: true` in some resource that someone flipped on in your cluster, and your configs never specified it; it would not be removed unless you decide to also specify this field in your configs). + +kapp comes with some common k8s rebase rules. you can see them via `kapp deploy-config`. + +tldr: kapp takes user provided config as the only source of truth, but also allows to explicitly specify that certain fields are cluster controlled. This method guarantees that clusters don't drift, which is better than what basic 3 way merge provides. + +Originally answered [here](https://github.com/carvel-dev/kapp/issues/58#issuecomment-559214883). diff --git a/site/content/kapp/docs/v0.62.x/preflight.md b/site/content/kapp/docs/v0.62.x/preflight.md new file mode 100644 index 000000000..230619c1e --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/preflight.md @@ -0,0 +1,25 @@ +--- +aliases: [/kapp/docs/latest/preflight] +title: Preflight Checks +--- + +## Overview + +Once the change set is calculated (see [Diff](diff.md) section for details), kapp will run any of the optional preflight checks that have been enabled. + +If all enabled preflight checks are successful, kapp will continue to apply the changes in the change set (see [Apply](apply.md) section for further details). + +Preflight checks are enabled using the new `--preflight` flag when running `kapp deploy...` or `kapp app-group deploy...`. The `--preflight` flag follows the pattern `--preflight=CheckName,OtherCheck,...` to enable the specified preflight checks. Preflight checks not specified are disabled. + +Currently available preflight checks are: +- `PermissionValidation` - *disabled by default* - Validates that a user has the permissions necessary to apply the changes in the change set. If a user does not have the appropriate permissions the preflight check will fail and no changes will be applied to the cluster. + +## PermissionValidation + +The `PermissionValidation` preflight check validates that a user has the permissions necessary to apply the changes in the change set to the cluster. If a user does not have the appropriate permissions to apply *all* of the changes, this check will fail and result in no changes being applied to the cluster. + +This preflight check is disabled by default but can be enabled with `--preflight=PermissionValidation` when running `kapp deploy...` or `kapp app-group deploy...`. + +The following permission checks are run when this check is enabled: +- For all resources, verification that a user has the permissions to perform the change operation (`create`, `update`, `delete`). +- For `ClusterRole`, `ClusterRoleBinding`, `Role`, and `RoleBinding` resources, verification that no privilege escalation occurs. This is done by checking each rule specified in the `(Cluster)Role` resource (or in the case of `(Cluster)RoleBinding` the referenced `(Cluster)Role`) and ensuring that a user has the same level of permissions. This check also accounts for users with the `escalate` and `bind` permissions that are allowed to perform privilege escalation. diff --git a/site/content/kapp/docs/v0.62.x/rbac.md b/site/content/kapp/docs/v0.62.x/rbac.md new file mode 100644 index 000000000..7eb89bd96 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/rbac.md @@ -0,0 +1,70 @@ +--- +aliases: [/kapp/docs/latest/rbac] +title: Permissions +--- + +## Running kapp under restricted permissions + +In a multi-tenant Kubernetes cluster, user's actions may be limited to one or more namespaces via `Role` and `RoleBinding` configuration. + +Following setup is currently expected by kapp (v0.10.0+): + +- [required] kapp requires list/get/create/update/delete for `v1/ConfigMap` in [state namespace](state-namespace.md) so that it can store record of application and deployment history. +- [optional] kapp requires one `ClusterRole` rule: listing of namespaces. This requirement is necessary for kapp to find all namespaces so that it can search in each namespace resources that belong to a particular app (via a label). As of v0.11.0+, kapp will fallback to only [state namespace](state-namespace.md) if it is forbidden to list all namespaces. +- otherwise, kapp does _not_ require permissions to resource types that are not used in deployed configuration. In other words, if you are not deploying `Job` resource then kapp does not need any permissions for `Job`. Note that some resources are "cluster" created (e.g. `Pods` are created by k8s deployment controller when `Deployment` resource is created) hence users may not see all app associated resources in `kapp inspect` command if they are restricted (this could be advantageous and disadvantegeous in different setups). + +Please reach out to us in #carvel channel in k8s slack (linked at the bottom of the page) if current kapp permissions model isn't compatible with your use cases. We are eager to learn about your setup and potentially improve kapp. + +Example of `Namespace` listing permission needed by kapp: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: kapp-restricted-cr +rules: +- apiGroups: [""] + resources: ["namespaces"] + verbs: ["list"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: kapp-restricted-cr-binding +subjects: +- kind: ServiceAccount + name: # ??? + namespace: # ??? (some tenant ns) +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: kapp-restricted-cr +``` + +Example of `ConfigMap` permissions needed by kapp: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: kapp-restricted-role + namespace: # ??? (some tenant ns) +rules: +- apiGroups: [""] + resources: ["configmaps"] + verbs: ["list", "get", "create", "update", "delete"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: kapp-restricted-role-binding + namespace: # ??? (some tenant ns) +subjects: +- kind: ServiceAccount + name: # ??? + namespace: # ??? (some tenant ns) +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: kapp-restricted-role +``` diff --git a/site/content/kapp/docs/v0.62.x/rebase-pvc.md b/site/content/kapp/docs/v0.62.x/rebase-pvc.md new file mode 100644 index 000000000..0e9087088 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/rebase-pvc.md @@ -0,0 +1,102 @@ +--- +aliases: [/kapp/docs/latest/rebase-pvc] +title: PersistentVolumeClaim rebase +--- +## PersistentVolumeClaim rebase + +Here is an example on how to use custom `rebaseRules` to "prefer" server chosen value for several annotations added by PVC controller (in other words, cluster owned fields), instead of removing them based on given configuration. + +Let's deploy via `kapp deploy -a test -f config.yml -c` with following configuration `config.yml`: + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: mysqlclaim +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +``` + +Without additional rebase rules following diff will be presented upon next deploy, stating that several annotations will be removed (since they were not present in the initial configuration): + +```bash +$ kapp deploy -a test -f config.yml -c + +Target cluster 'https://x.x.x.x' (nodes: gke-dk-jan-9-default-pool-a218b1c9-55sl, 3+) + +--- update persistentvolumeclaim/mysqlclaim (v1) namespace: default + ... + 2, 2 metadata: + 3 - annotations: + 4 - pv.kubernetes.io/bind-completed: "yes" + 5 - pv.kubernetes.io/bound-by-controller: "yes" + 6 - volume.beta.kubernetes.io/storage-provisioner: kubernetes.io/gce-pd + 7, 3 creationTimestamp: "2020-03-08T22:17:29Z" + 8, 4 finalizers: + ... + 24, 20 storageClassName: standard + 25 - volumeMode: Filesystem + 26, 21 volumeName: pvc-1be63b2b-20de-429c-863a-9e7eb062f5d3 + 27, 22 status: + +Changes + +Namespace Name Kind Conds. Age Op Wait to Rs Ri +default mysqlclaim PersistentVolumeClaim - 43s update reconcile ok - + +Op: 0 create, 0 delete, 1 update, 0 noop, 0 exists +Wait to: 1 reconcile, 0 delete, 0 noop + +Continue? [yN]: +``` + +To let kapp know that these annotations should be copied from the live resource copy, we can augment deploys with following configuration `kapp-config.yml`: + +```yaml +--- +apiVersion: kapp.k14s.io/v1alpha1 +kind: Config + +rebaseRules: +- path: [metadata, annotations, pv.kubernetes.io/bind-completed] + type: copy + sources: [new, existing] + resourceMatchers: &pvcs + - apiVersionKindMatcher: + apiVersion: v1 + kind: PersistentVolumeClaim + +- path: [metadata, annotations, pv.kubernetes.io/bound-by-controller] + type: copy + sources: [new, existing] + resourceMatchers: *pvcs + +- path: [metadata, annotations, volume.beta.kubernetes.io/storage-provisioner] + type: copy + sources: [new, existing] + resourceMatchers: *pvcs + +- path: [spec, volumeMode] + type: copy + sources: [new, existing] + resourceMatchers: *pvcs +``` + +```bash +$ kapp deploy -a test -f config.yml -f kapp-config.yml -c + +Target cluster 'https://x.x.x.x' (nodes: gke-dk-jan-9-default-pool-a218b1c9-55sl, 3+) + +Changes + +Namespace Name Kind Conds. Age Op Wait to Rs Ri + +Op: 0 create, 0 delete, 0 update, 0 noop, 0 exists +Wait to: 0 reconcile, 0 delete, 0 noop + +Succeeded +``` diff --git a/site/content/kapp/docs/v0.62.x/security.md b/site/content/kapp/docs/v0.62.x/security.md new file mode 100644 index 000000000..6b16ba957 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/kapp/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `kapp`, 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/docs/v0.62.x/state-namespace.md b/site/content/kapp/docs/v0.62.x/state-namespace.md new file mode 100644 index 000000000..82185f326 --- /dev/null +++ b/site/content/kapp/docs/v0.62.x/state-namespace.md @@ -0,0 +1,53 @@ +--- +aliases: [/kapp/docs/latest/state-namespace] +title: Namespace for State Storage +--- + +## Overview + +To show list of deployed applications (via `kapp ls`), kapp manages metadata `ConfigMap` for each saved application. Each metadata `ConfigMap` contains generated label used to label all application resources. Additionally kapp creates `ConfigMap` per each deploy to record deployment history (seen via `kapp app-change list -a app1`). + +`--app-namespace` flag allows to control which namespace is used for finding and storing metadata `ConfigMaps`. If namespace is not explicitly specified the app-wide namespace is used as specified by `-n` or `--namespace`); if `-n` is not specified your current namespace is selected from kube config (typically `~/.kube/config`). + +There are currently two approaches to deciding which namespace to use for storing metadata `ConfigMaps`: + +- for each application, keep metadata `ConfigMap` and app resources themselves in the same namespace. That namespace will have to be created before running `kapp deploy` since kapp will first want to create a `ConfigMap` representing application. + + ```bash + $ kubectl create ns app1 + $ kapp deploy -n app1 -f config.yml + $ kapp ls -n app1 + ``` + +- create a dedicated namespace to store metadata `ConfigMaps` representing apps, and have kapp create `Namespace` resources for applications from their config. With this approach namespace management (creation and deletion) is tied to a particular app configuration which makes it a bit easier to track `Namespaces` via configuration. + + ```bash + $ kubectl create ns apps + $ kapp deploy --app-namespace apps -f app1/config.yml + $ kapp deploy --app-namespace apps -f app2/config.yml + $ kapp ls -n apps + ``` + + for example, `app1/config.yml` may look like this: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: app1 + --- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: dep + namespace: app1 + ... + ``` + +Note: It's currently not possible to have kapp place app `ConfigMap` resource into `Namespace` that kapp creates for that application. + +## App Changes + +As mentioned above, app changes (stored as `ConfigMap`) are stored in state namespace. App changes do not store any information necessary for kapp to operate, but rather act as informational records. There is currently no cap on how many app changes are kept per app. + +To remove older app changes, use `kapp app-change gc -a app1` which by default will keep 200 most recent changes (as of v0.12.0). Alternatively use `--app-changes-max-to-keep` flag on the `deploy` command to control number of changes kept at the time of deploy. diff --git a/site/data/kapp/docs/kapp-v0-62-x-toc.yml b/site/data/kapp/docs/kapp-v0-62-x-toc.yml new file mode 100644 index 000000000..ec2f4d474 --- /dev/null +++ b/site/data/kapp/docs/kapp-v0-62-x-toc.yml @@ -0,0 +1,57 @@ +toc: + - title: Introduction + subfolderitems: + - page: About kapp + url: / + - page: Install + url: /install + - page: Applications + url: /apps + - title: Deploy command + subfolderitems: + - page: Diff stage + url: /diff + - page: Apply stage + url: /apply + - page: Apply Ordering + url: /apply-ordering + - page: Apply Waiting + url: /apply-waiting + - page: Preflight Checks + url: /preflight + - title: Reference + subfolderitems: + - page: Configuration + url: /config + - page: Permissions + url: /rbac + - page: Namespace for State Storage + url: /state-namespace + - page: Cheatsheet + url: /cheatsheet + - page: Dangerous Flags + url: /dangerous-flags + - page: Configmap Migration (experimental) + url: /configmap-migration + - page: Command Reference + url: /command-reference + - title: Integrations + subfolderitems: + - page: Integrating With Other Tools + url: /integrating-with-other-tools + - page: GitOps + url: /gitops + - title: FAQ + subfolderitems: + - page: FAQ + url: /faq + - page: Resource Merge Method + url: /merge-method + - page: Code of Conduct + shared_url: /code-of-conduct + - page: Contributing + shared_url: /contributing + - page: Carvel Development Guidelines + shared_url: /development_guidelines + - page: Security + shared_url: /security-policy diff --git a/site/data/kapp/docs/toc-mapping.yml b/site/data/kapp/docs/toc-mapping.yml index 8ef6cdb6c..7f6e7c0e4 100644 --- a/site/data/kapp/docs/toc-mapping.yml +++ b/site/data/kapp/docs/toc-mapping.yml @@ -17,3 +17,4 @@ v0.58.x: kapp-v0-58-x-toc v0.59.x: kapp-v0-59-x-toc v0.60.x: kapp-v0-60-x-toc v0.61.x: kapp-v0-61-x-toc +v0.62.x: kapp-v0-62-x-toc