DOCSEARCHbyAlgolia
Submit Docs

kapp Documentation

repository·develop·Indexed 22 days ago

https://github.com/carvel-dev/kapp

kapp is a Kubernetes deployment tool that manages sets of resources, labeled as 'applications', by diffing provided YAML files against live cluster state and converging them. It focuses strictly on deployment and resource management rather than templating or packaging. Key features include resource ordering, the use of RebaseRules to handle cluster-managed annotations (such as Calico Pod IP annotations), and the ability to trigger Pod recreations via versioned ConfigMaps.

Tokens
20K
Snippets
77
Records
102
Agent score
76%

What's inside kapp

  1. Understand the kapp source code structure

    develop

    The kapp repository is organized into several key packages that separate CLI logic, resource management, and Kubernetes interaction:

    • CLI Entrypoints: cmd/kapp is the main entry point. Commands are defined in pkg/kapp/cmd, with kapp.go acting as the root command and pkg/kapp/cmd/app containing top-level commands like deploy and delete.
    • App Abstractions: pkg/kapp/app defines how applications are tracked:
      • LabeledApp: Represents an app based on a user-provided label.
      • RecordedApp: Represents an app backed by a ConfigMap (uses LabeledApp internally).
    • Resource Management: pkg/kapp/resources handles parsing, fetching, and modifying Kubernetes resources via the Resource interface and ResourceImpl.
    • Diffing Logic: pkg/kapp/diff and pkg/kapp/diffgraph manage resource differences and deployment/deletion ordering. Note: These packages are Kubernetes-agnostic.
    • Cluster Application: pkg/kapp/clusterapply is the single package responsible for modifying the Kubernetes cluster. It uses ClusterChange objects to apply diffs and includes logic for resource convergence, retries, and deletions.
    • Resource Utilities: pkg/kapp/resourcesmisc provides objects for waiting on specific resource types (e.g., Pods, Services, Deployments).
    • Logging: pkg/kapp/logs provides log streaming functionality for the kapp logs command.

  2. What is kapp and how does it work?

    develop

    Core Concept: Kubernetes Applications

    kapp encourages managing resources in bulk by working with "Kubernetes applications"—defined as sets of resources sharing the same label.

    Key Characteristics

    • Deployment Focus: Unlike Helm, kapp does not handle YAML templating or package management. It is designed to work with tools (like ytt) that generate Kubernetes configuration, focusing instead on the deployment workflow.
    • Convergence: In each deploy operation, kapp compares provided files against live objects in the cluster to create, update, or delete resources to reach the desired state.
    • Two-Stage Workflow: It separates the calculation of changes (the diff stage) from the application of changes (the apply stage).
    • Low Privilege Requirements: kapp does not use custom CRDs and can work without admin privileges, allowing regular users to manage resources within a single namespace.
    • GitOps Friendly: It supports deploying application groups from a directory, making it suitable for GitOps workflows.

  3. How kapp manages application state and changes

    develop

    kapp follows specific design principles regarding how it interacts with Kubernetes and how it manages application lifecycles:

    • Separation of Concerns: The diffing stage is strictly separated from the apply stage. Diffing should only require initial resource fetching and does not require ongoing cluster access.
    • Cluster Modification Isolation: All modifications to the Kubernetes cluster are isolated within the pkg/kapp/clusterapply package to ensure reliability.
    • Deployment vs. Deletion: Deleting an application is treated as a deployment with no resources, followed by the deletion of state records. Both deploy and delete operations follow the same code path using a ClusterChangeSet.
    • State Management: To ensure all cluster changes are visible in the UI, kapp uses ClusterChanges. Application state and changes are managed via ConfigMaps (used by RecordedApp).

  4. Implement a lightweight StatefulSet alternative using kapp and ytt

    develop

    You can replicate common StatefulSet (STS) behaviors—such as ordered rollouts, stable network identities, and persistent storage—using a combination of ytt templates and kapp features. This approach allows for direct management of all resources, providing more flexibility than a standard STS.

    Key Capabilities

    • Stable Identity & Storage: Creates multiple Pods (e.g., redis-0, redis-1) paired with dedicated PersistentVolumeClaims (e.g., redis-0, redis-1).
    • Ordered Rollouts: Use kapp change rules to control the rollout sequence (e.g., updating Pod 0, then Pod 1, then Pod 2).
    • Config-driven Pod Restarts: By using the kapp.k14s.io/versioned annotation on a ConfigMap, kapp can trigger Pod recreations whenever the configuration changes.
    • Per-Pod DNS: Each Pod can be targeted via DNS by creating a dedicated Service for each individual Pod (e.g., a Service named redis-0 for Pod redis-0).

    Important Limitation

    Because this pattern uses a one-off kapp deploy invocation, if a Pod is deleted from the cluster, it will not be automatically recreated. To ensure high availability and automatic recovery, you should run kapp deploy continuously, ideally using kapp-controller.

    kapp deploy -a redis -f <(ytt -f examples/sts-alternative)

  5. Handle Calico Pod IP annotations using rebaseRules

    develop

    When deploying Pods directly on a cluster using Calico, Calico automatically adds IP annotations (e.g., cni.projectcalico.org/podIP) to the Pod. By default, kapp attempts to merge resources by removing these cluster-managed annotations, which causes the deployment to fail because Pod specifications are largely immutable.

    To resolve this, use a rebaseRule to instruct kapp to copy existing annotations from the cluster during the merge process. This ensures that the annotations managed by Calico are preserved rather than being treated as deletions.

    # Example rebase-rule.yml content
apiVersion: kapp.dev/v1alpha1
kind: RebaseRule
metadata:
  name: preserve-calico-annotations
spec:
  rules:
    - apiVersion: v1
      kind: Pod
      action: copy-annotations

  6. Build and test kapp from source

    develop

    To build the kapp binary and run the full test suite, use the provided scripts in the hack directory. You will need a running Kubernetes cluster to execute the end-to-end tests.

    1. Build the project using ./hack/build.sh.
    2. Set the KAPP_E2E_NAMESPACE environment variable to define the namespace for testing.
    3. Create the test namespace in your cluster.
    4. Run the full test suite using ./hack/test-all.sh.
    ./hack/build.sh
export KAPP_E2E_NAMESPACE=kapp-test
kubectl create ns $KAPP_E2E_NAMESPACE
./hack/test-all.sh

  7. Generate Pinniped v0.32.0 configuration using ytt

    develop

    You can generate a combined configuration file for Pinniped v0.32.0 components (Concierge, Local User Authenticator, and Supervisor) by downloading and processing their respective installation YAML files using ytt.

    ytt \
  -f https://get.pinniped.dev/v0.32.0/install-pinniped-concierge.yaml \
  -f https://get.pinniped.dev/v0.32.0/install-local-user-authenticator.yaml \
  -f https://get.pinniped.dev/v0.32.0/install-pinniped-supervisor.yaml > config.yml

  8. Install the kapp CLI

    develop

    You can install kapp using one of the following methods:

    1. Prebuilt Binaries: Download them from the GitHub Releases page.
    2. Homebrew: Use the Carvel tap via Homebrew.

    kapp is a CLI tool designed to manage Kubernetes resources in bulk by treating sets of resources with the same label as a single "Kubernetes application."

  9. Use the kapp CLI to manage Kubernetes applications

    develop

    The kapp CLI is used to manage applications on a Kubernetes cluster. It provides a structured set of commands for deploying, inspecting, deleting, and managing various Kubernetes resources like applications, app groups, configmaps, appchanges, and service accounts.

    Core Command Groups

    • Application Management (app): Commands for managing individual applications.
      • kapp app list: List applications.
      • kapp app inspect: Inspect an application.
      • kapp app deploy: Deploy an application.
      • kapp app delete: Delete an application.
      • kapp app rename: Rename an application.
      • kapp app logs: View application logs.
      • kapp app label: Add labels to an application.
    • App Groups (appgroup): Manage groups of applications.
      • kapp appgroup deploy: Deploy an app group.
      • kapp appgroup delete: Delete an app group.
    • ConfigMaps (configmap):
      • kapp configmap list: List configmaps.
    • AppChanges (appchange):
      • kapp appchange list: List appchanges.
      • kapp appchange gc: Garbage collect appchanges.
    • ServiceAccounts (serviceaccount):
      • kapp serviceaccount list: List service accounts.
    • Tools (tools): Advanced inspection and diffing.
      • kapp tools inspect: Inspect resources.
      • kapp tools diff: Diff resources.
      • kapp tools list-labels: List labels.

  10. Inspect the resource tree view

    develop

    The InspectTreeView is a UI component used to display a hierarchical view of resources. It organizes resources into a table that visualizes their relationships (ownership and associations) through a tree-like structure.

    Table Columns

    The view provides the following information for each resource:

    • Namespace: The Kubernetes namespace.
    • Name: The resource name, prefixed with indentation (e.g., L ..) to indicate its depth in the resource tree.
    • Kind: The resource kind.
    • Version: The API version.
    • Owner: The owner of the resource.
    • Rs (Reconcile state): The current state of the resource reconciliation.
    • Ri (Reconcile info): Information regarding the reconciliation process.
    • Age: The age of the resource (time since creation).

    Resource Relationships

    The tree view identifies relationships using two primary methods:

    1. Label-based associations: Uses specific association labels to link resources.
    2. Owner Reference-based associations: Uses Kubernetes ownerReferences to trace the hierarchy via UIDs. These are represented in the table using a ref- prefix and a path of identifiers (e.g., ref-ns$api$kind$name/ns$api$kind$name).

  11. Configure Kubernetes service host/port via YAML templates

    develop

    When providing an explicit Kubernetes configuration via ConfigureYAMLResolver, the ConfigFactory supports environment variable substitution for in-cluster configurations.

    It looks for the ${KAPP_KUBERNETES_SERVICE_HOST_PORT} placeholder in your YAML and replaces it with the value from the KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT environment variables. This is useful for dynamically generating in-cluster kubeconfigs.