Installer script

Most of the deployment of Drogue Cloud uses Helm in combination with kubectl for installing dependencies. However, we do require a few steps before and after the deployment. Installing dependencies on the cluster and setting URLs afterwards.

For this we have a magic installer script, that does everything for you. It is suited for an easy start on a local test cluster.

Pure Helm based installation

While we describe the installation of Drogue Cloud using our installer script, it is also possible to install it using just Helm charts. In fact, the installer uses an opinionated value set for the Helm charts, and you can simply create your own wrapper chart, tweaking the values as needed.

This is what we do for our public sandbox too. The installer script is just there to get you started quickly.

Download the installer package

The installer package is part of the GitHub release record: https://github.com/drogue-iot/drogue-cloud/releases/latest

There is one package for each type of Kubernetes cluster:

  • install-minikube – For using with Minikube

  • install-kind – For using with Kind

  • install-openshift – For using with OpenShift

Download the package, matching the cluster you plan to use.

Unpacking

Unzip the package and change into the folder extracted from the archive.

What to expect

The installer will create a new instance of Drogue Cloud on the cluster you are currently logged in to.

By default, this includes:

  • Installing Strimzi

  • Creating a Kafka cluster

  • Installing the Keycloak operator

  • Create a custom CA for the endpoints

If you want to install those dependencies manually, for example using OLM, you can opt-out of the installation (see below).

Additionally, it installs Knative and an example application and can install digital twin feature as well. Deployment of these components can be configured using installer arguments as explained below.

Running the installer

Run the installer script ./script/drgadm deploy, adding the options appropriate for your setup.

You can use the -c argument to define which cluster type you have.

Default cluster type

By default, the cluster type will be minikube for the script in the repository. For the installers, this default value will be changed to the installer type you downloaded. You can still override the default, using:

./script/drgadm deploy -c kind

Additional installer options

The deploy command of drgadm supports the following argument

-k or INSTALL_DEPS

Don’t install any dependency by default.

-s <key=value>

Set additional Helm values. May be repeated multiple times.

-m

Minimize: Reduces the default resource requests to allow deploying on more constrained environments.

-d or DOMAIN

Manually provide the application DNS domain.

-c or CLUSTER

Specify the cluster type (any of minikube, kind, openshift, kubernetes).

-p <profile>

Adds an additional Helm value file, named deploy/helm/profiles/<profile>.yaml.

-t <timeout>

Helm installation timeout (default: 15m)

-n <namespace> or DROGUE_NS

Changes the target Drogue IoT namespace.

-T

Install digital twin feature.

-e

Don’t install examples.

-M

Deploy metrics

Example: Install Drogue Cloud on kind cluster without dependencies.

./script/drgadm deploy -c kind -k

Skip the dependency installation

The -k argument will skip installing all dependencies. If you want to install of just some of the dependencies (like Strimzi or Keycloak) yourself, you can opt out of installing them by the script.

The installer has a few additional options which are controlled by using environment variables. You can set them by prefixing the call to the installation script, using env and the variable assignment:

env INSTALL_STRIMZI=false ./script/drgadm deploy
Variable Name Default value Description

INSTALL_STRIMZI

${INSTALL_DEPS}

Control the installation of Strimzi.

INSTALL_KEYCLOAK_OPERATOR

${INSTALL_DEPS}

Control the installation of the Keycloak operator.

Install additional examples

By default the example dashboard is installed by the script. You can turn it off by using -e argument. Additionally, digital twin feature can be installed by specifying -T argument. Knative will be installed only if either examples or digital twin feature are installed. To deploy minimal installation without any examples (and Knative) use:

./script/drgadm deploy -e

Change the target namespace

You can change the namespace where of the Drogue Cloud components get installed using the variable DROGUE_NS. The default is drogue-iot.

Currently, you can only change the namespace of the Drogue Cloud installation. The namespaces of Knative, Strimzi, are currently not configurable.

Provide custom TLS certificates

By default, the installer script will create a custom certificate authority. However, if you already have a key and certificate, you can instruct the installer to use these. There are two options to achieve this.

Manually create the TLS secrets

The installer will check if the secrets http-endpoint-tls, mqtt-endpoint-tls and coap-endpoint-tls exist. If they don’t it will create them using generated key and certificate material.

If you manually create these TLS secrets, using those names, before running the installer, it will not override these existing secrets. You can do that by running shell commands similar to these:

kubectl -n drogue-iot create secret tls http-endpoint-tls --key $PATH_TO_CERT/tls.key --cert $PATH_TO_CERT/tls.crt --dry-run=client -o json | kubectl -n drogue-iot apply -f -
kubectl -n drogue-iot create secret tls mqtt-endpoint-tls --key $PATH_TO_CERT/tls.key --cert $PATH_TO_CERT/tls.crt --dry-run=client -o json | kubectl -n drogue-iot apply -f -
kubectl -n drogue-iot create secret tls coap-endpoint-tls --key $PATH_TO_CERT/tls.key --cert $PATH_TO_CERT/tls.crt --dry-run=client -o json | kubectl -n drogue-iot apply -f -

Where $PATH_TO_CERT should point to the path location of your certificate.

Re-running the installer

Should something go wrong, it should be possible to just re-run the installer script. That should simply set the desired state again, and Kubernetes should reconcile accordingly. In most of the cases, this works just fine.

Status information

After the installer script has run, it will show some information on how you can connect to the system and give some example commands to try out.