The thingsHub's tenants are managed and configured using the Kubernetes package manager helm. Helm charts are provided at https://helm.smartmakers.de and are documented below. Each tenant is managed with a separate release and therefore with a separate helm configuration.
The base configuration of a tenant, as initially created in Creating a Tenant, should only be changed with extra care after the initial creation of the tenant. In particular, this includes the tenant's name and domain, as well as the configuration options affecting where and how data is persisted.
Example configuration file
The following is an example of a minimal configuration of a thingsHub tenant.
Example Configuration File
global: domain: thingshub.smartmakers.de name: example security: service_key: <randomly-generated service key> admin_password: <randomly generated password> password_policy_regex: <user defined regular expression> password_help_text: <user defined help text to show on user form> sql: host: hostname.domain:port database: example user: example password: <the example role's passsword on the sql server> tls: enabled: true cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: | ----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
Updating a tenant’s configuration
The thingsHub helm chart repository is added with the following command:
$ helm repo add smartmakers https://helm.smartmakers.de ... $ helm repo update ... $
helm repo update command needs to be repeated before every upgrade to a newer version. To update a tenant configuration, first modify the config file as required, then run the helm tool with the following options:
$ helm upgrade --namespace <tenant> -f <tenant>.yaml <tenant> th-tenant ... $
Helm chart configuration options
The thingsHub’s tenant chart is an umbrella chart which ties together multiple charts for the different services. Options which affect multiple sub-charts are put in the
global section. Some of these options (wherever it makes sense) can be overridden for the sub-chart. These options are marked with an asterisk (*) at the end.
The base domain name, e.g.
The name of the tenant, e.g.
This must be alphanumeric, lowercase, and should be kept short but never longer than 63 characters. Dashes are allowed, neither in the beginning nor at the end and also never two consecutive ones.
This is concatenated with the value of
The file name of the logo file. The filename suffix is used to identify the file type, e.g.
The contents of the logo file encoded in base64. On Linux, the command
Keep this small and prefer a scalable format (i.e.
The name of the registry from which to pull the container images. By default, this is
This is the path to the repository with the repository naming being the concatenation of the repository option and the
The name of the container image to pull. This is only meant to be overridden by each subchart.
The name of the tag to select for the images. The default tag is the version of the chart itself, i.e. docker image versions are tied to helm chart versions.
The name used for pulling the container images
The password used for pulling the container images
A policy, deciding when images should be pulled. Can be
Security (Authentication & Transport Layer Security)
A service key, shared by the services for mutual authentication.
The password of the
Contains a regular expression as a value and basically reflects the desired complexity/security of the user's passwords. In other words, when a new user is created or an existing user is updated via the REST API, the given password is checked against the defined regular expression. If such a check fails, "HTTP 400 Bad Request" error and a message "user's password doesn't match security policy" is returned by the service. The default security policy ensures that any newly created password would match a string of any symbols with length no less than 10.
Contains the string to display on the user creation form to help users understand what the requirement for the password policy is.
The IP subnets from which admin login to the thingsHub is allowed. This is a comma-separated list of CIDR address ranges, e.g.
Enabled Transport Layer Security. This requires
The PEM-encoded TLS certificate for the domain name in
The matching key for the certficate in
The name of the TLS certificate issuer when using CertManager.
The kind of TLS certificate issuer, either
The name of the Kubernetes secret which contains the PosrtgreSQL database’s credentials.
Hostname of the PostgreSQL server which hosts the tenants database. The default is
Port of the PostgreSQL server. The default is
The database which stores the data of the different tenant’s services. The default is
The role with which the services shall access the PostgreSQL database. The default is
The password for the role with which the services shall access the PostgreSQL database.
Use the PostgreSQL operator to create the database secret.
The database server on which the PostgreSQL operator shall create the database.
The hostname (with schema and port) of the InfluxDB server.
The user with which to login to the InfluxDB server.
The password for the above user.
The database in which thingsHub shall store its data.
Set this to true to manage the Visualizer users with the thingsHub (recommended).
Email Notifications & SMTP
Enable SMTP notifications
The SMTP server’s address (e.g. smtp.gmail.com:587)
The username for logging into the SMTP server
The password for authentication at the SMTP server
The SMTP host name (this is usually identical to the address, except that this doesn’t contain the port, while the address usually does)
The “From” line of the email
The node selector to force deployment of the tenant’s pods on specific nodes.
When overriding this option, the two maps for the base and overridden selectors will be merged.
The lowest level of logs which shall be generated. One of
The quality of service with which data shall be sent to the built-in MQTT broker.
Set this to a path on the Kubernetes host machine in which Grafana plugins are stored. Make sure that the contents of this path are identical on all nodes of the cluster, so that grafana behaves consistently.
For each version of grafana in use, introduce a separate subpath with the version number, e.g. if the path is
... set a logo for the index page
You require a logo in an image format supported by your browser. It is preferable to use a vector graphic (
svg) over a raster image format. The logo must be supplied as a base64-encoded helm configuration option and suffix in the filename should match the real image type. Set the logo as in the example below:
global: logos: light_name: company-logo.png light_content: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==
In order to convert the image to base64, you can use an online encoder such as: https://www.base64-image.de/ or search google for others. If you run a linux machine you can execute the following command
$ cat logo.png | base64 -w 0 iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg== $
... generate a secure, random password on the command line
You can generate a secure, random password from the command line using the command line tool openssl:
$ openssl rand -base64 30 pNABkkecqQTdTrck9IzhrPgulvNY4qELUgaC3JDA $
…change data retention policies
Retention policies cannot be set in the helm configuration, but need to be set directly in InfluxDB. For this, log into the InfluxDB with an admin user and execute the following commands:
ALTER RETENTION POLICY receptions_retention_policy ON <tenant-influxdb-name> DURATION 744h REPLICATION 1; ALTER RETENTION POLICY thub_device_data ON <tenant-influxdb-name> DURATION 744h REPLICATION 1; ALTER RETENTION POLICY logs_rp ON <tenant-influxdb-name> DURATION 744h REPLICATION 1; ALTER RETENTION POLICY things ON <tenant-influxdb-name> DURATION 744h REPLICATION 1;
… create the PostgreSQL database secret
There are three ways to create a secret for the PostgreSQL database access:
Use a pre-defined secret
This is the default behavior. You create a secret of type
kubernetes.io/basic-auth with the fields
password. Next you set the helm configuration option
global.sql.secret_ref.name to the name of that secret. Now install the helm chart and all services will pick up the secret and connect to the SQL database.
This can also be used in combination with a tool such as terraform to create the secret.
Create a secret with the helm chart itself
Set the configuration options
global.sql.password. The helm chart will generate a secret automatically if it detects that the password option is set. The secret will be placed at
global.sql.secret_ref.name. Note that with this option the secret is in the
values.yaml file. As this file is usually checked into a version control system, this approach is depreciated.
Create a secret using the PostgreSQL operator
Do not set the any of the options from the above approach. Instead set the option
true and the option
global.sql.operator.server_ref to the name of the PostgreSQL server resource on which the database shall be created. The operator will create the database on the PostgreSQL server and then create the secret at
global.sql.secret_ref.name for the tenant to use.
Password policy regex examples
The following examples for regular password policy checking regular expression can be used as inspiration for defining your own regular expressions:
A password with at least 8 characters.
Minimum eight characters, at least one uppercase letter
Minimum eight characters, at least one uppercase letter, one lowercase letter and one number