Documentation
About Kubeapps
Tutorials
- Get Started with Kubeapps
- Using an OIDC provider
- Managing Carvel packages
- Managing Flux packages
- Kubeapps on TKG
- Kubeapps on TCE
How-to guides
- Using the dashboard
- Access Control
- Basic Form Support
- Custon App View Support
- Custom Form Component Support
- Multi-cluster Support
- Offline installation
- Private Package Repository
- Syncing Package Repositories
- Using an OIDC provider with Pinniped
Background
Reference
About the project
Managing Carvel Packages with Kubeapps ¶
Table of Contents ¶
- Introduction
- Installing kapp-controller in your Cluster
- Using Kubeapps for Managing Carvel Packages
- Conclusions
Introduction ¶
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 .
Installing kapp-controller in your Cluster ¶
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.
Quick overview of the kapp-controller CRs ¶
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:
Using Kubeapps for Managing Carvel Packages ¶
Configuring Kubeapps to Support Carvel Packages ¶
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 thannone
is selected, the kapp-controller automatically upgrades the packages to the latest matching semantic version. For instance, assuming we installed the version1.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
,
- With
defaultPrereleasesVersionSelection
: denotes the default behavior for installing prerelease versions (such as1.0.0-rc1
). There are three possible values:null
: no prereleases will be installed.[]
: any prerelease version will be installed (if the versiondefaultUpgradePolicy
allows it).["rc", "foo"]
: only prerelease versions withrc
orfoo
as part of their names will be installed (if the versiondefaultUpgradePolicy
allows it). For instance,1.0.0-rc1
will be installed, but1.0.0-bar
will not.
defaultAllowDowngrades
: is a boolean value that determines whether thekapp-controller
will allow downgrades of packages.true
: adds an annotation to everyPackageInstall
resource created by Kubeapps that will allow them to be downgraded to previous versions of aPackage
.false
: is the default value and disables aPackageInstall
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 ]
Installing a Package Repository ¶
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 collapsable 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.Aditionally, 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
andPackageMetadata
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.
Creating a service account ¶
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: default
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 Package ¶
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 onServiceAccount
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 isstring
yields a default value offoo-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 Packages ¶
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
Conclusions ¶
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: