Skip to content

Commit f4bade4

Browse files
devanshuVmware100mik
devanshuVmware
authored and
100mik
committed
Release docs for kapp v0.64.x
Signed-off-by: Devanshu <devanshu.d@broadcom.com>
1 parent 1b8e552 commit f4bade4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+2333
-24
lines changed

‎site/config.yaml

+3-2
Original file line numberDiff line numberDiff line change
@@ -76,15 +76,16 @@ params:
7676
name: kapp
7777
short_name: kapp
7878
root_link: /kapp/
79-
latest_docs_link: /kapp/docs/v0.63.x/
79+
latest_docs_link: /kapp/docs/v0.64.x/
8080
github_url: https://github.com/carvel-dev/kapp
8181
search: true
8282
search_index_name: carvel-kapp
8383
search_api_key: a38560864c2e9128ae57d5734df438ff
8484
versioning: true
85-
version_latest: v0.63.x
85+
version_latest: v0.64.x
8686
versions:
8787
- develop
88+
- v0.64.x
8889
- v0.63.x
8990
- v0.62.x
9091
- v0.61.x

‎site/content/kapp/docs/v0.63.x/_index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/]
2+
33
title: "About kapp"
44
toc: "false"
55
cascade:

‎site/content/kapp/docs/v0.63.x/apply-ordering.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/apply-ordering]
2+
33
title: Apply Ordering
44
---
55

‎site/content/kapp/docs/v0.63.x/apply-waiting.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/apply-waiting]
2+
33
title: Apply Waiting
44
---
55

‎site/content/kapp/docs/v0.63.x/apply.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/apply]
2+
33
title: Apply stage
44
---
55

‎site/content/kapp/docs/v0.63.x/apps.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/apps]
2+
33
title: Applications
44
---
55

‎site/content/kapp/docs/v0.63.x/cheatsheet.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/cheatsheet]
2+
33
title: Cheatsheet
44
---
55

‎site/content/kapp/docs/v0.63.x/command-reference.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/command-reference]
2+
33
title: Command Reference
44
---
55

‎site/content/kapp/docs/v0.63.x/config.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/config]
2+
33
title: Configuration
44
---
55

‎site/content/kapp/docs/v0.63.x/configmap-migration.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/configmap-migration]
2+
33
title: Configmap Migration (experimental)
44
---
55

‎site/content/kapp/docs/v0.63.x/dangerous-flags.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/dangerous-flags]
2+
33
title: Dangerous Flags
44
---
55

‎site/content/kapp/docs/v0.63.x/diff.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/diff]
2+
33
title: Diff stage
44
---
55
## Overview

‎site/content/kapp/docs/v0.63.x/faq.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/faq]
2+
33
title: FAQ
44
---
55

‎site/content/kapp/docs/v0.63.x/gitops.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/gitops]
2+
33
title: GitOps
44
---
55

‎site/content/kapp/docs/v0.63.x/hpa-deployment-rebase.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/hpa-deployment-rebase]
2+
33
title: HPA and Deployment rebase
44
---
55
## HPA and Deployment rebase

‎site/content/kapp/docs/v0.63.x/install.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/install]
2+
33
title: Install
44
---
55

‎site/content/kapp/docs/v0.63.x/integrating-with-other-tools.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/integrating-with-other-tools]
2+
33
title: Integrating with Other Tools
44
---
55

‎site/content/kapp/docs/v0.63.x/merge-method.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/merge-method]
2+
33
title: "Resource Merge Method"
44
---
55

‎site/content/kapp/docs/v0.63.x/preflight.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/preflight]
2+
33
title: Preflight Checks
44
---
55

‎site/content/kapp/docs/v0.63.x/rbac.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/rbac]
2+
33
title: Permissions
44
---
55

‎site/content/kapp/docs/v0.63.x/rebase-pvc.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/rebase-pvc]
2+
33
title: PersistentVolumeClaim rebase
44
---
55
## PersistentVolumeClaim rebase

‎site/content/kapp/docs/v0.63.x/security.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/security]
2+
33
title: Security
44
---
55

‎site/content/kapp/docs/v0.63.x/state-namespace.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
aliases: [/kapp/docs/latest/state-namespace]
2+
33
title: Namespace for State Storage
44
---
55

‎site/content/kapp/docs/v0.64.x/_index.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
aliases: [/kapp/docs/latest/]
3+
title: "About kapp"
4+
toc: "false"
5+
cascade:
6+
version: v0.64.x
7+
toc: "true"
8+
type: docs
9+
layout: docs
10+
---
11+
12+
`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.
13+
14+
![Kapp Deploy](/images/kapp/kapp-deploy-screenshot.png)
15+
16+
Features:
17+
18+
- Works with standard Kubernetes YAMLs
19+
- Focuses exclusively on deployment workflow, not packaging or templating
20+
- but plays well with tools (such as [ytt](/ytt)) that produce Kubernetes configuration
21+
- Converges application resources (creates, updates and/or deletes resources) in each deploy
22+
- based on comparison between provided files and live objects in the cluster
23+
- Separates calculation of changes ([diff stage](diff.md)) from application of changes ([apply stage](apply.md))
24+
- [Waits for resources](apply-waiting.md) to be "ready"
25+
- Creates CRDs and Namespaces first and supports [custom change ordering](apply-ordering.md)
26+
- Works [without admin privileges](rbac.md) and does not use custom CRDs
27+
- making it possible to use kapp as a regular user in a single namespace
28+
- Records application deployment history
29+
- Opt-in resource version management
30+
- for example, to trigger Deployment rollout when ConfigMap changes
31+
- Optionally streams Pod logs during deploy
32+
- Works with any group of labeled resources (`kapp -a label:tier=web inspect -t`)
33+
- Works without server side components
34+
- GitOps friendly (`kapp app-group deploy -g all-apps --directory .`)
35+
36+
## Blog posts
37+
38+
- [Deploying Kubernetes Applications with ytt, kbld, and kapp](/blog/deploying-apps-with-ytt-kbld-kapp)
39+
40+
## Talks
41+
42+
- [ytt and kapp @ TGI Kubernetes 079](https://www.youtube.com/watch?v=CSglwNTQiYg) with Joe Beda
43+
- [Managing Applications in Production: Helm vs ytt & kapp @ Kubecon 2020](https://www.youtube.com/watch?v=WJw1MDFMVuk)
44+
- [Introduction to Carvel @ Rawkode Live](https://www.youtube.com/watch?v=LBCmMTofNxw)

‎site/content/kapp/docs/v0.64.x/apply-ordering.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
aliases: [/kapp/docs/latest/apply-ordering]
3+
title: Apply Ordering
4+
---
5+
6+
## Overview
7+
8+
kapp includes builtin rules to make sure certain changes are applied in particular order:
9+
10+
- Creates/updates
11+
- CRDs are created/updated before custom resources
12+
- Namespaces are created/updated before namespaced resources
13+
- Pod related resources (ServiceAccount, ConfigMap, Secret, etc.) are created/updated before other resources (v0.25.0+)
14+
- RBAC related resources (Role, RoleBinding, etc.) are created/updated before other resources (v0.25.0+)
15+
- Deletions (below is order as of v0.29.0+)
16+
- Custom resources are deleted first
17+
- CRDs are deleted next
18+
- Rest of resoures are deleted
19+
20+
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.
21+
22+
Additionally kapp allows to customize order of changes via following resource annotations:
23+
24+
- `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`).
25+
- `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`).
26+
27+
`kapp.k14s.io/change-rule` annotation value format is as follows: `(upsert|delete) (after|before) (upserting|deleting) <name>`. For example:
28+
29+
- `kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/db-migrations"`
30+
- `kapp.k14s.io/change-rule: "delete before upserting apps.big.co/service"`
31+
32+
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:
33+
34+
- `kapp.k14s.io/change-group: apps.co/db-migrations-{name}` - Here `{name}` would later be replaced by the name of the resource.
35+
- `kapp.k14s.io/change-rule: upsert after upserting apps.co/namespaces-{namespace}` - Here `{namespace}` would later be replaced by the namespace of the resource.
36+
37+
kapp provides the following placeholders:
38+
39+
- `{api-group}` - apiGroup
40+
- `{kind}` - kind
41+
- `{name}` - name
42+
- `{namespace}` - namespace
43+
- `{crd-kind}` - spec.names.kind (available for CRDs only)
44+
- `{crd-group}` - spec.group (available for CRDs only)
45+
46+
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.
47+
48+
## Example
49+
50+
Following example shows how to run `job/migrations`, start and wait for `deployment/app`, and finally `job/app-health-check`.
51+
52+
```yaml
53+
kind: ConfigMap
54+
metadata:
55+
name: app-config
56+
annotations: {}
57+
#...
58+
---
59+
kind: Job
60+
metadata:
61+
name: migrations
62+
annotations:
63+
kapp.k14s.io/change-group: "apps.big.co/db-migrations"
64+
#...
65+
---
66+
kind: Service
67+
metadata:
68+
name: app
69+
annotations:
70+
kapp.k14s.io/change-group: "apps.big.co/deployment"
71+
#...
72+
---
73+
kind: Ingress
74+
metadata:
75+
name: app
76+
annotations:
77+
kapp.k14s.io/change-group: "apps.big.co/deployment"
78+
#...
79+
---
80+
kind: Deployment
81+
metadata:
82+
name: app
83+
annotations:
84+
kapp.k14s.io/change-group: "apps.big.co/deployment"
85+
kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/db-migrations"
86+
#...
87+
---
88+
kind: Job
89+
metadata:
90+
name: app-health-check
91+
annotations:
92+
kapp.k14s.io/change-rule: "upsert after upserting apps.big.co/deployment"
93+
#...
94+
```

‎site/content/kapp/docs/v0.64.x/apply-waiting.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
aliases: [/kapp/docs/latest/apply-waiting]
3+
title: Apply Waiting
4+
---
5+
6+
## Overview
7+
8+
kapp includes builtin rules on how to wait for the following resource types:
9+
10+
- any resource with `metadata.deletionTimestamp`: wait for resource to be fully removed
11+
- any resource matching Config's waitRules: [see "Custom waiting behaviour" below](#custom-waiting-behaviour)
12+
- [`apiextensions.k8s.io/<any>/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)
13+
- `apps/v1/DaemonSet`: wait for `status.numberUnavailable` to be 0
14+
- `apps/v1/Deployment`: [see "apps/v1/Deployment resource" below](#apps-v1-deployment-resource)
15+
- `apps/v1/ReplicaSet`: wait for `status.replicas == status.availableReplicas`
16+
- `batch/v1/Job`: wait for `Complete` or `Failed` conditions to appear
17+
- `batch/<any>/CronJob`: immediately considered done
18+
- `/v1/Pod`: looks at `status.phase`
19+
- `/v1/Service`: wait for `spec.clusterIP` and/or `status.loadBalancer.ingress` to become set
20+
- `apps/v1/StatefulSet`: [see "apps/v1/StatefulSet resource" below](#appsv1statefulset-resource)
21+
22+
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).
23+
24+
## Controlling waiting via resource annotations
25+
26+
- `kapp.k14s.io/disable-wait` annotation controls whether waiting will happen at all. Possible values: "".
27+
- `kapp.k14s.io/disable-associated-resources-wait` annotation controls whether associated resources impact resource's waiting state. Possible values: "".
28+
29+
## apps/v1/Deployment resource
30+
31+
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:
32+
33+
- `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%"`.
34+
35+
## apps/v1/StatefulSet resource
36+
37+
Available in v0.32.0+.
38+
39+
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.
40+
41+
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).
42+
43+
## Custom waiting behaviour
44+
45+
Available in v0.29.0+.
46+
47+
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.)

0 commit comments

Comments
 (0)