Documentation

1. Introduction
2. Installing kapp-controller in your Cluster
   1. Quick overview of the kapp-controller CRs
3. Using Kubeapps for Managing Carvel Packages
   1. Configuring Kubeapps to Support Carvel Packages
   2. Installing a Package Repository
   3. Installing a Package
   4. Viewing the Installed Packages
4. Conclusions

Historically, Kubeapps was initially developed to solely manage Helm Charts on your Kubernetes clusters. However, it has evolved to support multiple packaging formats, such as Carvel Packages and Helm releases via Fluxv2 .

TIP: Find more information about the architectural evolution at this video and this technical documentation .

Carvel is often defined as a set of reliable, single-purpose, composable tools that aid in your application building, configuration, and deployment to Kubernetes. Particularly, two of these tools have paramount importance for Kubeapps: kapp and kapp-controller .

On the one hand, kapp is a CLI for deploying and viewing groups of Kubernetes resources as Applications . On the other hand, kapp-controller is a controller for managing the lifecycle of those applications, which also helps package software into distributable Packages and enables users to discover, configure, and install these packages on a Kubernetes cluster.

This guide walks you through the process of using Kubeapps for configuring and deploying Packages and managing Applications .

NOTE: This section can safely be skipped if you already have kapp-controller installed in your cluster.

In order to manage Carvel Packages, first of all, you need to install kapp-controller in your cluster. That is, applying a set of Kubernetes resources and CRDs.

According to the Carvel kapp-controller official documentation , you can install everything that kapp-controller requires just by running the following command:

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

After running this command, you should have everything you need to manage Carvel Packages in your cluster. Next section gives you an overview of the relevant Custom Resources included in kapp-controller.

At the time of writing this guide, kapp-controller installs the following Custom Resources Definitions:

• PackageRepository : is a collection of packages and their metadata. Similar to a maven repository or a rpm repository, adding a package repository to a cluster gives users of that cluster the ability to install any of the packages from that repository.

  • Package : is a combination of configuration metadata and OCI images that informs the package manager what software it holds and how to install itself onto a Kubernetes cluster.

  • PackageMetadata : are attributes of a single package that do not change frequently and that are shared across multiple versions of a single package. It contains information similar to a project’s README.md.

• PackageInstall is an actual installation of a package and its underlying resources on a Kubernetes cluster.

• App is a set of Kubernetes resources. These resources could span any number of namespaces or could be cluster-wide.

The following image depicts the relationship between the different kapp-controller CRs:

As with any other packaging format, the kapp-controller support is brought into Kubeapps by means of a plugin.

This kapp-controller plugin is currently being built by default in the Kubeapps release and it is just a matter of enabling it when installing Kubeapps.

TIP: Please refer to the getting started documentation for more information on how to install Kubeapps and pass custom configuration values.

In the values.yaml file, enable the packaging.carvel option:

packaging:
  carvel:
    enabled: true

If required, you can additionally pass the following configuration values to modify the defaults used by Kubeapps for the Carvel support. These are options passed to the kapp-controller plugin that handles the Carvel packaging support:

• defaultUpgradePolicy: represents the default upgrade policy for the packages. If other than none is selected, the kapp-controller automatically upgrades the packages to the latest matching semantic version. For instance, assuming we installed the version 1.2.3:
  • With major selected, the package will be upgraded to >=1.2.3, for example, 2.0.0, for
  • With minor selected, the package will be upgraded to >=1.2.3 <2.0.0, for example, 1.3.0,
  • With patch selected, the package will be upgraded to >=1.2.3 <1.3.0, for example, 1.2.4,
• defaultPrereleasesVersionSelection: denotes the default behavior for installing prerelease versions (such as 1.0.0-rc1). There are three possible values:
  • null: no prereleases will be installed.
  • []: any prerelease version will be installed (if the version defaultUpgradePolicy allows it).
  • ["rc", "foo"]: only prerelease versions with rc or foo as part of their names will be installed (if the version defaultUpgradePolicy allows it). For instance, 1.0.0-rc1 will be installed, but 1.0.0-bar will not.
• defaultAllowDowngrades: is a boolean value that determines whether the kapp-controller will allow downgrades of packages.
  • true: adds an annotation to every PackageInstall resource created by Kubeapps that will allow them to be downgraded to previous versions of a Package.
  • false: is the default value and disables a PackageInstall to be downgraded to previous versions.

An example of the configuration values that can be passed to the kapp-controller plugin is:

kubeappsapis:
  ...
  pluginConfig:
    kappController:
      packages:
        v1alpha1:
          defaultUpgradePolicy: none # [ "major", "minor", "patch", "none" ]
          defaultPrereleasesVersionSelection: null # [ "null", "[]", "['foo']" ]
          defaultAllowDowngrades: false # [ true, false ]

Kubeapps allows you to install Carvel Packages Repositories directly from the UI.

First, you need to find a Carvel Package Repository already published. If not, you can always create your own manually . This tutorial uses the Tanzu Community Edition package repository.

TIP: In this Carvel website you can find a list of Carvel Packages and Package Repositories that are available to open-source users.

• To start with the installation, expand the right menu and click on the Package Repositories option.

  

• Kubeapps navigates to the Package Repositories page displaying a list of installed repositories (both Global and Namespaced repositories).

  

  • Global repositories are available cluster-wide to deploy applications from those repositories to any namespace.

  • Namespace repositories are available only in specific namespaces (to be aligned with the Kubernetes RBAC model where an account can have roles in specific namespaces).

  A Kubeapps Package Repository can be installed by anyone with the required RBAC for that namespace.

• Click the Add Package Repository button that displays a pop-up (structured in collapsible sections) to configure the parameters for the new Package Repository.

  

  The image above shows the parameters to configure the Tanzu Community Edition Carvel package repository as a Global repository in Kubeapps.

• Additionally, there are two sections to provide authorization and advanced data to configure the Package Repository. Default values in these sections are enough to install the Tanzu Community Edition package repository.

  

• Finally, click the Install Repository button to launch the installation process, adding the new repository to Kubeapps.

  Under the hood, kapp-controller creates Package and PackageMetadata CRs for each of the packages in the repository in the global packaging namespace for kapp-controller, enabling those packages to be installed via Kubeapps in any namespace. If you select Namespace scope for the repository, the packages will only be available for install via Kubeapps in that namespace.

Since the Carvel system reconciles a PackageInstall in the background, we need to create a service account to use when creating PackageInstall via Carvel. This service account is created in the namespace where you intend to install the package (specifically, where the PackageInstall resource will be created).

cat > kubeapps-user-service-account.yaml << EOF
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: carvel-reconciler
  namespace: kubeapps-user-namespace
automountServiceAccountToken: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: carvel-reconciler
  namespace: kubeapps-user-namespace
subjects:
- kind: ServiceAccount
  name: carvel-reconciler
  namespace: kubeapps-user-namespace
roleRef:
  kind: ClusterRole
  name: admin
  apiGroup: rbac.authorization.k8s.io
EOF

kubectl apply -f kubeapps-user-service-account.yaml

Note that this service account will have admin access to the namespace only and so will be able to read/write most resources in the namespace, including adding other roles and rolebindings. If your package includes cluster-wide resources such as CRDs or ClusterRoles, you will need to update the above to use a ClusterRoleBinding with a different cluster role, such as cluster-admin. See Kubernetes user-facing roles for more info about the roles.

Installing a Carvel Package in Kubeapps is the same experience as installing any other package (such as a Helm Chart) in Kubeapps.

TIP: Please refer to the user documentation for more information on how to use Kubeapps as a user.

Assuming that a Package Repository, such as the Tanzu Community Edition, is already installed in the cluster, go to the Catalog tab and select the package you want to install.

The following image depicts the catalog page with a set of packages from the Tanzu Community Edition repository.

Next, select any package you want to install, for example, Harbor, as depicted below:

A big difference with respect to other packaging formats is that you must select a ServiceAccount to be used for installing the package. The reason why is that kapp-controller forces to explicitly provide needed privileges for management of app resources.

TIP: Find more information about the kapp-controller security model in their official documentation .

In Kubeapps, a dropdown allows you to select which ServiceAccount you want to use, such as the carvel-reconciler service account created above.

NOTE: As a consequence, the user logged in Kubeapps needs RBAC permissions to perform a list operation on ServiceAccount objects.

Furthermore, there is another difference: the values for installing the package are commented out by default. This is because there is no concept of default values in Carvel Packages.

In Kubeapps, maintainers team work around this decision by generating some default values based upon the OpenAPI Schema of the package.

TIP: For instance, a property foo-prop whose data type is string yields a default value of foo-prop: ""

TIP: you can uncomment a set of lines easily by selecting them and typing Ctrl + /.

Finally, after clicking the Install button, the required CRs is installed in the cluster (PackageInstall and the Secret holding the passed values). At this moment, kapp-controller performs the required actions to start creating the Kubernetes resources defined by the package. This process is known as reconciliation.

Viewing the installed Carvel Packages in Kubeapps is the same experience as viewing any other installed package (such as a Helm Chart) in Kubeapps.

TIP: Please refer to the user documentation for more information on how to use Kubeapps as a user.

Go to the Applications tab to see every Application installed in the cluster. Click on show apps in all namespaces to view the ones currently installed in every namespace of the cluster.

The following image shows an example of the Applications page with two Carvel Packages installed:

Since the reconciliation process can eventually fail for several reasons, this page shows the current status of each application. If it is deployed it means that the application is successfully running in the cluster.

Next, click on the application you want to view, for example, my-test to go to the details page, as depicted in the following image:

As in any other packaging format, this page displays those Kubernetes resources that have been created as a result of the Package installation. Besides, the current values are shown at the end of the page.

Next, you can click on the Delete button to uninstall the application or the Upgrade button to edit the values of the application or update it to another version.

NOTE: as opposed to Helm Charts managed by using Helm, Carvel Packages cannot be rolled back, hence there is no Rollback button.

Finally, note that every Carvel Package installed through Kubeapps can also be managed by the kapp CLI using the kapp inspect -a <APPLICATION_NAME> command (as well as every Carvel Package installed directly from the kapp CLI can also be managed by Kubeapps). For example:

kapp inspect -a my-test-ctrl

An example output of this command is:

Target cluster 'https://127.0.0.1:40903' (nodes: kubeapps-control-plane)

Resources in app 'my-test-ctrl'

Namespace  Name                         Kind           Owner    Conds.  Rs  Ri  Age
default    simple-app                   Deployment     kapp     2/2 t   ok  -   9m
^          simple-app                   Endpoints      cluster  -       ok  -   9m
^          simple-app                   Service        kapp     -       ok  -   9m
^          simple-app-77b6fd4c84        ReplicaSet     cluster  -       ok  -   9m
^          simple-app-77b6fd4c84-42lv9  Pod            cluster  4/4 t   ok  -   9m
^          simple-app-7r26k             EndpointSlice  cluster  -       ok  -   9m

Rs: Reconcile state
Ri: Reconcile information

6 resources

Succeeded

This guide covers how to manage Carvel Packages in Kubeapps, starting from how to configure Kubeapps itself , then how to add Carvel Packages Repositories , next how to browse and install Carvel Packages , and finally how to view the installed Carvel Packages .

Some additional resources and references include:

• Getting Started with kapp-controller
  • kapp-controller documentation
• Getting Started with kapp
  • kapp documentation