Installation using Helm

Helm is a package manager for Kubernetes, and is the preferred way to install and deploy Ververica Platform. In Helm a package is called a Chart, and it contains all of the resource definitions necessary to run an application, tool, or service inside of a Kubernetes cluster. Charts are essentially just a collection of Templates and some input Values, which Helm refers to as Manifests that are then rendered into Kubernetes resources.

If you’re unfamiliar with Helm and would like to know more about Charts, we recommend checking out the Helm charts documentation

Before continuing, please read the documentation about the Ververica Platform Docker images and take any necessary action.

Prerequisites

You must have a working Kubernetes environment, an installation of the helm CLI tool, and a healthy “Tiller” pod—Helm’s server-side component—running on your cluster. Setting up Helm is not covered by this guide, so please refer to the Helm documentation for further information.

Attention

If your Kubernetes cluster is enabled with RBAC, you may get an “access denied” error when trying to use Helm. If this is the case, make sure you have created a service account and role binding according to the documentation.

Note

If you plan to use the Ververica Docker registry, or any other private registry requiring authentication, it’s important to keep this in mind when installing Application Manager. Currently in this scenario you must install Application Manager to a Namespace that has an imagePullSecret configured and bound to the default ServiceAccount for that Namespace. In addition to this you must also reference this imagePullSecret at install time so Helm will add it to the custom ServiceAccount that Application Manager uses by default.

To verify that your environment is prepared, the following commands should complete without error:

$ kubectl get pods
$ helm list

If you are working in a Kubernetes namespace that is not the default specified in your local Kubernetes configuration file, you can specify the namespace in the above command as follows:

$ kubectl --namespace my-namespace get pods

Similarly, if you set up Helm to use a non-default namespace for its Tiller pod, you can specify it in the above command as follows:

$ helm --tiller-namespace my-tiller-namespace list

Overriding chart values

Helm provides several options for setting and overriding the values in a chart. These consist of the following:

  • -f, --values valueFiles specify values in a YAML file or a URL (can specify multiple)
  • --set stringArray set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  • --set-file stringArray set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
  • --set-string stringArray set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)

For the Ververica Platform charts the two methods we’ll cover here are --set-file and --values. Specifically using --set-file we can specify a key/option to set and a file to obtain the contents/value from. This is the preferred method of specifying the license file for Application Manager, like so --set-file appmanager.license=path/to/license_file.

Notes about the Ververica Platform chart default values:

  • If no license file is referenced, Application Manager will operate in a limited trial mode, with its capabilities restricted.
  • By default, the chart uses the Docker registry hosted by Ververica. To specify your own registry, override the appropriate image/registry values for the respective chart component. (See Ververica Platform Docker Images)
  • By default, the chart will create and manage persistent volumes for the components that require them. For this to work, your Kubernetes installation must have a default StorageClass configured. You can use any existing PersistentVolumeClaims that you might have by using the respective *.persistentVolume.existingClaim: "" options for each of the components.
  • If your Kubernetes installation uses role-based access control (RBAC), you must specify either appmanager.rbac.create: true (default) or reference an existing ServiceAccount that you manage using the appmanager.rbac.serviceAccountName option.

Helm is fortunate to have an offline templating option, this is useful for debugging charts, and as a kind of dry-run/preview mode. Using the following command, you can render a Helm chart and see what it would create in your Kubernetes cluster (the target Helm chart can be either the .tar.gz archive you downloaded, or the resulting folder if you extracted it, both are valid):

$ helm template --debug daplatform

Similarly you can preview this with a custom values specified also:

$ helm template --debug daplatform --set-file appmanager.license=license_file
$ helm template --debug daplatform --values values.yaml

Passing the --debug flag to helm template exposes several important pieces of information:

  • USER-SUPPLIED VALUES: as the name suggests, these are any values provided by the user, using any of the methods outlined above. This is useful for seeing how Helm has interpreted your input if it’s not behaving as you expected.
  • COMPUTED VALUES: this is a combination of the user-supplied values, and the defaults, showing what will be used in the Helm charts ultimately. This is useful for seeing what other values are being set (defaults), and what you can change/override without having to resort to extracting the Helm release and inspecting the raw yaml files directly. Although this is a valid option when needed. This is a good source of information for creating your own values.yaml file.
  • MANIFEST: this is a default section not specific to the --debug output and shows the manifests/kubernetes resources in yaml format that Helm will create. This can help to contextualize the various values in the USER-SUPPLIED and COMPUTED values sections above.

Note

The output of helm template will contain the string RELEASE-NAME in many places. This is a special Helm variable, which will be replaced by Helm when you install the Chart. It is determined by the --name parameter, which we recommend setting to daplatform, or dynamically set by Helm if not specified.

Completing the installation using Helm

With the included Helm chart (named daplatform-1.3.4.tgz) and the values.yaml file generated in the previous step, complete the installation using helm install. To install into the Kubernetes namespace my-namespace and call the release daplatform, run:

$ helm install \
    --namespace my-namespace \
    --name daplatform \
    --set-file appmanager.license=path/to/the/license_file \
    daplatform-1.3.4.tgz