Install Console

Lightbend Console installs as a Helm chart with many configurable parameters. We provide a script that simplifies Console installation in development and production environments. The script verifies the environment before and after the install to help troubleshoot any issues. For cases where you cannot install Helm Tiller in your cluster, there is a section about doing an install without Tiller. It is also possible to install using Helm directly, that might be useful in cases where the install script can’t be used.

Prior to installing the Console, you should have already:

Windows support

The install script can be used on Windows 10 with OpenShift client. Running on local clusters like Minikube or Minishift is not supported.

To use the install script on Windows, make sure you have these programs available in your PATH: * Python 2.7 * OpenShift client * kubectl * Helm

Both PowerShell and Command Prompt shells can be used. Be aware that the example commands in the rest of this document need to be slightly altered by removing the leading ./ characters, so on Windows instead of:

./lbc.py install --version=1.1.0

Write this:

lbc.py install --version=1.1.0

Downloading the Lightbend Console script

Note

The script depends on Python 2.X being available in your system. The majority of Linux and macOS environments provide Python 2, so no additional actions need to be taken. If unsure, you can check which version of Python you have by running python --version in your terminal.

Download the script and make it executable.

curl -O https://raw.githubusercontent.com/lightbend/console-charts/master/enterprise-suite/scripts/lbc.py
chmod u+x lbc.py

The script checks your environment for platform dependencies and their versions, installs Lightbend Console into your cluster, can verify existing Console installations, and help with debugging problems by gathering logs and diagnostic data. The script uses Helm, allowing you to pass in chart values and offers other script configuration options.

For fine-grained control over the installation process, including when you aren’t running Tiller on your cluster, see Installing without Helm Tiller.

Performing the install

In some Kubernetes environments, you can simply run the install subcommand and specify the Console version:

./lbc.py install --version=1.1.0

We recommend always specifying a version when using install subcommand. If version argument is not provided, Helm will try to get the newest Lightbend Console version, including release candidates. Current version is 1.1.0.

It can take a few minutes for all components to initialize. Once that is done, you can verify that Lightbend Console is running:

./lbc.py verify

The following platforms require more specific install commands:

Setting chart values and Helm arguments

Any arguments you provide to lbc.py after -- are passed directly to Helm.

Chart values can be set in a YAML file and passed to Helm with the --values <values.yaml> parameter:

usePersistentVolumes: true
defaultStorageClass: gp2

It is also possible to pass ad-hoc values on the command line with --set setting=value, but it is strongly recommended to use a values.yaml file to preserve your settings for upgrades.

The following table describes the available chart values and lists their defaults.

Value Key Default Description
exposeServices false Set to NodePort or LoadBalancer to generate services accessible from outside of cluster (eg. http://$(minikube ip):30080 when used with NodePort) for interacting with Lightbend Console.
esConsoleExposePort 30080 Port on which Console will be exposed when value exposeServices is used.
createClusterRoles true Set to true to create a ClusterRole for Prometheus and kube-state-metrics. Set to false to not create them, in case you would like to define your own.
usePersistentVolumes true Use Persistent Volumes by default. If false, Console will use emptyDir for all volumes. See Set up Storage for more information.
defaultStorageClass <none> Name of the StorageClass to use for persistent volumes. The default uses the cluster’s DefaultStorageClass.
prometheusVolumeSize 256Gi Size of the Prometheus volume. Used for storing prometheus data and custom monitors.
alertmanagerVolumeSize 32Gi Size of the Alertmanager volume. Used for saving silences.
esGrafanaVolumeSize 32Gi Size of the Grafana volume. Used for saving custom dashboards, plugins, and users.
prometheusDomain prometheus.io Domain for scrape annotations. For example, prometheus.io/scrape.
createAlertManager true Set to true to deploy an Alertmanager together with Console, set to false to use an existing Alertmanager.
alertManagers alertmanager:9093 Comma separated list of Alertmanager addresses. When installing with createAlertManager=false this is used to specify existing Alertmanagers to connect to.
alertManagerConfigMap default-alertmanager ConfigMap to use for Alertmanager configuration. Should contain a file alertmanager.yml.
esConsoleURL n/a External URL for access to the console. Currently used by Prometheus and Alertmanager in alerts.
defaultCPURequest 100m Default container resource request.
defaultMemoryRequest 50Mi Default container resource request.
prometheusMemoryRequest 250Mi Prometheus container memory request.
containerCPURequest n/a Container specific resource request. Replace container with one of esConsole, esMonitor, prometheus, or grafana.
containerMemoryRequest n/a Container specific resource request. Replace container with one of esConsole, esMonitor, prometheus, or grafana.

Install configuration

The install subcommand itself has several options which affect how it calls Helm. Pass the --help option to view them all:

./lbc.py install --help

Available arguments are:

Argument Description Default
--dry-run Just print the commands that the script would run instead of executing them. false
--skip-checks Skip checking for dependency tools, credentials validity, etc. false
--wait Wait for install or upgrade to finish before returning. false
--namespace Namespace into which to install Lightbend Console. lightbend
--force-install Set to true to delete the installed chart first. false
--delete-pvcs Override any warnings about possible data loss when uninstalling. USE WITH CAUTION. unset (false)
--set key1=val1,key2=val2 Set Helm chart values. Can be repeated. unset
--es-chart Chart name to install from the repository enterprise-suite
--export-yaml Export resource YAMLs to stdout instead of installing. Set to creds for credentials, console for everything else. unset
--helm-name Helm release name enterprise-suite
--local-chart Location of local chart (tarball). Overrides --repo. unset
--repo Helm chart repository to use https://repo.lightbend.com/helm-charts
--creds Credentials file in property format with username/password $HOME/.lightbend/commercial.credentials
--version Version of helm chart to install. The latest stable version is 1.1.0. unset

In addition to commandline arguments, the install subcommand supports the following environment variables:

Variable Description
LIGHTBEND_COMMERCIAL_USERNAME Credentials username. If specified in conjunction with LIGHTBEND_COMMERCIAL_PASSWORD the pair overrides --creds argument.
LIGHTBEND_COMMERCIAL_PASSWORD Credentials password. If specified in conjunction with LIGHTBEND_COMMERCIAL_USERNAME the pair overrides --creds argument.

Platform Details

This section provides install tips for specific platforms.

Minikube

Run the script and in addition to specifying the version, make sure to include the --set exposeServices=NodePort argument to enable external access.

./lbc.py install --version=1.1.0 --set exposeServices=NodePort

You should now be able to open the Console in your browser by running:

minikube service expose-es-console --namespace lightbend
Note

To just print the URL instead of opening it in a browser, add --url argument the above command.

Minishift and OpenShift

You should have cluster admin privileges to use the Console install script or have an administrator provide them for you.

To log in as admin:

oc login -u system:admin

To grant admin privileges to developer:

oc adm policy add-cluster-role-to-user cluster-admin developer

OpenShift 3.6

To install Lightbend Console on OpenShift version 3.6, we need to specify matching API versions.

Execute the following command to install Lighbend Console on OpenShift 3.6:

Create a values.yaml file:

rbacApiVersion: authorization.openshift.io/v1
deploymentApiVersion: apps/v1beta1
daemonSetApiVersion: extensions/v1beta1
apiGroupVersion: authorization.openshift.io/v1

Then install Console:

./lbc.py install --version=1.1.0 -- --values=values.yaml
Note

Container metrics graphs will be empty since these metrics are not available in OpenShift 3.6.

Upgrading the console version

The install subcommand will automatically upgrade the chart if it detects it is already installed.

Make sure to read the release notes in case any actions are required.

As Helm doesn’t remember the parameters you used for the initial install, you need to pass the same set of values you originally used.

Specify a new version and the values.yaml file you used for the initial install:

./lbc.py install --version=1.1.0 -- --values=values.yaml

If the upgrade fails, you can do a force install to purge the previous install:

./lbc.py install --version=1.1.0 --force-install -- --values=values.yaml

Installing without Helm Tiller

By default, lbc.py uses Helm client commands, some of which require the Helm Tiller server component to be installed. There are situations where this may not be appropriate. For example:

  • You do not or cannot run Tiller on your cluster.
  • You want to manage the Kubernetes resource yaml yourself.
  • You are attempting to install the product on a non-supported platform.

You can use the lbc.py script to generate the yaml and deploy directly.

Generating YAML From lbc.py

The lbc.py script can be used to export the resource yaml definitions that Helm would use. You can use these definitions to manage the installation of the Console into your Kubernetes infrastructure as you see fit. This still requires you to have Helm installed in your local environment, because it uses Helm to render chart templates into Kubernetes resources. Tiller, however, does not need to be installed in your cluster.

The --export-yaml commandline flag enables the yaml export.

First export the Lightbend commercial credentials as a Secret resource:

./lbc.py install --version=1.1.0 --export-yaml=creds | \
    kubectl --namespace=lightbend apply -f -

Then export all the resources that make up an install:

./lbc.py install --version=1.1.0 --export-yaml=console > console.yaml
kubectl --namespace=lightbend apply -f console.yaml
Note

Any exported credentials yaml will include your credentials. They are base64 encoded but not encrypted. They should be considered to be in plaintext so should be managed carefully. Do not commit them to a code repository for example.

Backwards compatibility and further customization

We provide backwards compatibility of the chart parameters based on the semantic version. For example, 1.x.x releases should not change existing parameter names.

While https://github.com/lightbend/console-charts is public, we provide no guarantee of maintaining its structure.

If you need further customization beyond what the Helm parameters provide, it is recommended to create a support ticket for Lightbend to add it. This gives you the greatest guarantee of compatibility across versions.

Verifying an install

The verify subcommand can be used to check if an existing Lightbend Console installation is running fine:

./lbc.py verify

Available arguments are:

Argument Description Default
--skip-checks Skip checks for dependency tools (kubectl). false
--namespace Namespace in which to look for Lightbend Console. lightbend

Uninstalling

To remove the Console from you cluster, you can use uninstall subcommand:

./lbc.py uninstall

In order to avoid losing your data, this will warn and stop if it detects that the the uninstall would risk the loss of Persistent Volumes containing your monitors and other data.

Available arguments are:

Argument Description Default
--dry-run Just print the commands that the script would run instead of executing them. false
--skip-checks Skip checks for dependency tools (helm, kubectl). false
--helm-name HELM_NAME Helm release name to uninstall enterprise-suite
--delete-pvcs Ignore warnings about PVs and proceed anyway. USE WITH CAUTION! unset (false)

Debug data for diagnostics

To help diagnosing any problems in Lightbend Console, there is debug-dump subcommand:

./lbc.py debug-dump

When no other arguments are given, it will look for an existing Lightbend Console installation, gather Kubernetes descriptions of the Console namespace as well as logs for all the containers running there. It will not gather any other data from outside of the Console namespace (lightbend by default). Everything is placed into a zip file in the working directory with a name like console-diagnostics-2018-11-12-11-32-15.zip.

Supported arguments are:

Argument Description Default
--skip-checks Skip checks for dependency tools (kubectl). false
--namespace Namespace in which to look for Lightbend Console. lightbend
--print Print gathered data to stdout instead of making a zip file. false

Installing without lbc.py

It is possible to install Lightbend Console into your cluster without using the lbc.py script. We advise that you use the install script if at all possible, but there may be reasons why you can’t. Manual installation consists of two steps - setting up credentials and then using Helm to install the Console chart. The instructions below assume that you have a Kubernetes cluster up and running with Helm installed.

Setting up credentials

Your Lightbend credentials are used to pull the Console Docker images that are only available to authenticated users. Credentials come in the form of username and password, usually kept in the ~/.lightbend/commercial.credentials file. When installing manually, you will have to create a credentials.yaml file, which has your username and password, and pass the location of the file as a parameter to Helm. The yaml file should look like the following:

imageCredentials:
    username: johndoe
    password: password123
Note

Be aware that this file contains your credentials in plain text. Do not commit it to your version control repository and consider where you are storing it.

Installing the Helm chart

After you have prepared your credentials, add the Lightbend Helm charts repository and update the list of known charts:

helm repo add es-repo https://repo.lightbend.com/helm-charts
helm repo update

When the repository is updated, install the Console as follows:

helm install es-repo/enterprise-suite --name enterprise-console --namespace lightbend --version 1.1.0 --values credentials.yaml

The previous command has quite a few parameters. Here they are explained in order:

  • install es-repos/enterprise-suite - Specifies the Lightbend Console Helm chart name, do not change this value.
  • --name enterprise-console - name of the Helm release (a local name given to the installed chart). Can be any name you like.
  • --namespace lightbend - Kubernetes namespace where the resources are installed. Can be an existing or new namespace.
  • --version $es.version$ - version of the Console.
  • --values credentials.yaml - a file where your Lightbend credentials are stored in yaml format.

For more information on how to use Helm and its install command, please refer to the official Helm docs.