DOCSEARCHbyAlgolia
Submit Docs

kapp-controller

repository·develop·Indexed 43 days ago

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

A Kubernetes-native continuous delivery and package management tool that uses Custom Resource Definitions (CRDs) to automate the deployment and lifecycle management of applications and software packages. It provides capabilities for Kubernetes package management via Package, PackageMetadata, PackageRepository, and PackageInstall resources, as well as declarative application management using the App CRD. The tool includes the kctrl CLI for interacting with resources and managing package releases.

Tokens
33.9K
Snippets
137
Records
177
Agent score
56%

What's inside kapp-controller

  1. Overview of kapp-controller

    develop

    kapp-controller provides a Kubernetes-native continuous delivery and package management experience using Custom Resource Definitions (CRDs). It allows you to manage software lifecycles directly within Kubernetes through declarative resources.

    Key capabilities include:

    • Kubernetes Package Management: Authoring and consuming software packages using Package, PackageMetadata, PackageRepository, and PackageInstall resources.
    • Continuous Delivery: Declarative installation, management, and upgrading of applications using the App CRD. It supports 'fetchable resources' that are continuously monitored to ensure the cluster state reflects the desired state.
    • GitOps: The continuous delivery mechanism is designed to work with Git repositories as a single source of truth for package management.

  3. Install the MongoDB Enterprise Kubernetes Operator

    develop

    You can install the MongoDB Enterprise Operator using Helm. By default, it installs Custom Resource Definitions (CRDs) and the operator in the default namespace. You can specify a custom namespace using the --namespace flag and optionally create it using --create-namespace.

    # Install in the default namespace
helm install enterprise-operator mongodb/enterprise-operator

# Install in a specific namespace (e.g., 'mongodb') and create it if it doesn't exist
helm install enterprise-operator mongodb/enterprise-operator --namespace mongodb [--create-namespace]

  4. Run unit and e2e tests

    develop

    Unit Testing

    Run the unit test suite using:

    ./hack/test.sh

    End-to-End (e2e) Testing

    To run e2e tests, deploy the test assets first, then execute the test suite. You can specify the namespace for the tests using KAPPCTRL_E2E_NAMESPACE.

    # 1. Deploy kapp-controller to cluster with test assets
./hack/deploy-test.sh

# 2. Set the test namespace
export KAPPCTRL_E2E_NAMESPACE=kappctrl-test

# 3. Run the e2e test suite
./hack/test-all.sh

    Note: The hack/test-e2e.sh script (called by test-all) pipes output to both stdout and tmp/e2eoutput.txt for easier parsing.

  6. Install a standalone package without a package repository

    develop

    You can install a package that does not belong to a managed package repository by including the Standalone Package Custom Resource (CR) directly in your configuration.

    While the source of the package differs, the PackageInstall resource remains identical to the process used when installing packages from a repository. This allows you to manage external or one-off packages using the same lifecycle and reconciliation logic as repository-based packages.

  7. Deploy with secretgen-controller for private auth

    develop

    To deploy kapp-controller alongside secretgen-controller (required for private registry authentication workflows), set the KAPPCTRL_E2E_SECRETGEN_CONTROLLER environment variable to true before deploying:

    export KAPPCTRL_E2E_SECRETGEN_CONTROLLER=true
./hack/deploy.sh

  8. Setup a local Kapp Controller in KIND

    develop

    To test Kapp Controller locally, you can set up a Kubernetes environment using KIND (Kubernetes in Docker) combined with a local Docker registry. This setup allows you to build, push, and deploy packages without needing an external container registry.

    Prerequisites

    • KIND: Install via brew install kind (macOS).
    • Docker: Installed and running.
    • jq: Install via brew install jq (macOS).

    Step 1: Initialize KIND with a Registry

    Run the provided setup script to create a KIND cluster that includes a local registry:

    ./scripts/kind-with-registry.sh

    Step 2: Install Kapp Controller

    Install the latest release of kapp-controller:

    kubectl apply -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml

    To grant administrative permissions to a service account (useful for local testing), apply the RBAC configuration:

    kubectl apply -f https://raw.githubusercontent.com/carvel-dev/kapp-controller/develop/examples/rbac/cluster-admin.yml

    Step 3: Configure Local Host for Registry Access

    To ensure tools like imgpkg use HTTP instead of HTTPS for the local registry, add the following entry to your /etc/hosts file:

    127.0.0.1 kind-registry.local

    Note: Remember to remove this entry after your testing session.

    # Install kapp-controller
kubectl apply -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml

# Install RBAC for admin SA
kubectl apply -f https://raw.githubusercontent.com/carvel-dev/kapp-controller/develop/examples/rbac/cluster-admin.yml

  10. Deploy kapp-controller to a non-Minikube environment

    develop

    To deploy to a standard Kubernetes cluster, you must first modify the development configuration:

    1. In the configuration files, set the push_images property to true.
    2. Set the image_repo property to your target image repository location.
    3. Run the deploy script:
    ./hack/deploy.sh

    Note: For faster iteration, you can use ./hack/dev-deploy.sh after an initial full deployment, but you may need to make direct changes to the overlay in config-dev-deploy/build.yml.

  11. Configure Service Accounts for App CRs

    develop

    When deploying App Custom Resources (CRs), you must provide a Service Account that has the necessary permissions to manage resources. The repository provides two common RBAC patterns for this purpose:

    1. Namespace-scoped permissions: Creates a service account (default-ns-sa) in the default namespace with permissions to modify any resource within that specific namespace. Use this for simple applications (e.g., simple-app-http.yml).
    2. Cluster-wide permissions: Creates a service account (cluster-admin-sa) in the default namespace with cluster-admin privileges, allowing it to modify any resource across the entire cluster. Use this for complex infrastructure deployments (e.g., istio-knative.yml).

    You can deploy these RBAC configurations using the kapp deploy command.

    $ kapp deploy -a default-ns-rbac -f https://raw.githubusercontent.com/carvel-dev/kapp-controller/develop/examples/rbac/default-ns.yml

  12. Release kapp-controller

    develop

    Releases are driven by Git tags.

    1. Tag the release: Use a version tag (e.g., v1.2.3).
      git tag "v1.2.3"
git push --tags
    2. Automated Workflow: Pushing the tag triggers a GitHub workflow that:
      • Builds and pushes the image to ghcr.io.
      • Generates release.yml.
      • Creates a GitHub release draft.
      • Uploads release.yml to the release.
    3. Publish: Once the draft is ready and release notes are reviewed, click Publish release in the GitHub UI.

    LTS Releases

    To ensure LTS releases are sorted correctly in GitHub's semver sorting, use post-dated annotated tags:

    GIT_COMMITTER_DATE="2022-02-25 2:00" git tag -a -m "v0.30.2" "v0.30.2"
    git tag "v1.2.3"
git push --tags