Deploying HQ

This page describes installing Lenses HQ in Kubernetes via Helm.

Lenses HQ is prerequisite for installation of Lenses Agent

Latest images:

Latest HQ image available here from Docker Hub.

Latest Lenses CLI as tarball or as a container.

Prerequisites

Kubernetes 1.23+
Helm 3.8.0+
Available local Postgres database instance:
- If you need to install Postgres on Kubernetes you can use one of the many publicly available Helm charts such as Bitnami's.
- Or you can use one of the cloud provider's Postgres services such as one of these: AWS, Azure, or GCP.
- See Lenses docs here for information on configuring Postgres to work with HQ .
- username (and password) that has access to HQ database;
External Secrets Operator is the only supported secrets operator.

Configure HQ

To configure Lenses HQ properly we have to understand the parameter groups that the Chart offers.

Under the lensesHq parameter there are some key parameter groups that are used to set up HQ:

storage
- definition of connection towards database (Postgres is the only storage option)
auth
- Password based authentication configuration
- SAML / SSO configuration
- definition of administrators or first users to access the HQ
http
- defines port under which HQ will be available for end users
- defines values of special headers and cookies
- types of connection such as TLS and non-TLS definitions
agents
- defines connection between HQ and the Agent such as port where HQ will be listening for agent connections.
- types of connection such as TLS and non-TLS definitions
license
monitoring
- controls the metrics settings where Prometheus alike metrics will be exposed
loggers
- definition of logging level for HQ

Moving forward, in the same order you can start configuring your Helm chart.

Configure storage (Postgres)

Postgres is the only available storage option.

Prerequisite:

Running Postgres instance;
Created database for HQ;
Username (and password) which has access to the created database;

In order to successfully run HQ, storage within values.yaml has to be defined first.

Definition of storage object is as follows:

lensesHq:
  storage:
    postgres:
      enabled: true
      host: ""
      port: 
      username: ""
      database: ""
      schema: ""
      tls: 
      params: {}
      passwordSecret:
        type: ""

Alongside Postgres password, which can be referenced / created through Helm chart, there are few more options which can help while setting up HQ.

Username reference types

There are two ways how username can be defined:

The most straightforward way, if the username is not being changed, is by just defining it within the username parameter such as

values.yaml

lensesHq:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.postgres.svc.cluster.local
      port: 5432
      username: lenses

In case Postgres username is being rotated or frequently changed it can be referenced from pre-created secret

values.yaml

lensesHq:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.postgres.svc.cluster.local
      port: 5432
      username: lenses
      useSecretForUsername:
        enabled: true
        existingSecret:
          name: my-secret
          key: username

Password reference types

Postgres password can be handled in three ways using:

External Secret via ExternalSecretOperator;
Pre-created secret;
Creating secret on the spot through values.yaml;

To use this option, the External Secret Operator (ESO) has to be installed and available for usage in K8s cluster your are deploying HQ.

When specifying passwordSecret.type: "externalSecret", the chart will:

create an ExternalSecret in the namespace where HQ is deployed;
a secret is mounted for HQ to use.

values.yaml

lensesHq:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.playground.svc.cluster.local
      port: 5432
      username: lenses
      database: lenseshq
      passwordSecret:
        type: "externalSecret"
        # Secret name where database password will be read from
        name: hq-password
        # Key name under secret where database password is stored
        key: password
        externalSecret:
          additionalSpecs: {}
          secretStoreRef:
            type: SecretStore # or ClusterSecretStore
            name: secretstore-secrets

Make sure that secret you are going to use is already created in namespace where HQ will be installed.

values.yaml

 lensesHq:
   storage:  
     postgres:
       enabled: true
       host: postgres-postgresql.playground.svc.cluster.local
       port: 5432
       username: lenses
       database: lenseshq
       passwordSecret:
         type: "precreated"
         # Secret name where database password will be read from
         name: hq-password
         # Key from secret's data where database password is being stored
         key: postgres-password

This option is NOT for PRODUCTION usage but rather just for demo / testing.

The chart will create a secret with defined values below and the same secret will be read by HQ in order to connect to Postgres.

values.yaml

 lensesHq:
   storage:
     postgres:
       enabled: true
       host: [POSTGRES_HOSTNAME]
       port: 5432
       username: lenses
       database: lenseshq
       passwordSecret:
         type: "createNew"
         # name of a secret that will be created
         name: [K8s_SECRET_NAME]
         # Database password
         password: [DATABASE_USER_PASSWORD]

Advanced Postgres settings

Sometimes to form the correct connection URI special parameters are needed. You can set the extra settings using params.

Example:

values.yaml

lensesHq:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.postgres.svc.cluster.local
      port: 5432
      username: lenses
      params:
        sslmode: require

Configure AUTH endpoint

SAML / SSO is available only with Enterprise license.

The second pre-requirement to successfully run HQ is setting initial authentication.

You can choose between:

password-based authentication, which requires users to provide a username and password;
and SAML/SSO (Single Sign-On) authentication, which allows users to authenticate through an external identity provider for a seamless and secure login experience.

Assertion Consumer Service endpoint is following

/api/v2/auth/saml/callback?client_name=SAML2Client

The definition of auth object is as follows:

values.yaml

lensesHq:
  auth:
    users:
      - username: admin
        # bcrypt("correcthorsebatterystaple").
        password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG
    administrators:
      - admin
      - [email protected]
      - [email protected]
    saml:
      enabled: true
      baseURL: ""
      entityID: ""
      # -- Example: <?xml version="1.0" ... (big blob of xml) </md:EntityDescriptor>
      metadata:
        referenceFromSecret: false
        secretName: ""
        secretKeyName: ""
        stringData: |
          <?xml version="1.0" encoding="UTF-8" standalone="no"?>
          </md:EntityDescriptor>
  
      userCreationMode: "sso"
      usersGroupMembershipManagementMode: "sso"
      uiRootURL: "/"
      groupAttributeKey: "groups"
      authnRequestSignature:
        enabled: false

First to cover is the users property. Users Property: The users property is defined as an array, where each entry includes a username and a password. Passwords must be hashed using bcrypt before being placed within the password property, for security purposes, ensuring that they are stored correctly and securely.

values.yaml

lensesHq:
  auth:
    users:
      - username: admin
        # bcrypt("correcthorsebatterystaple").
        password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG

values.yaml

lensesHq:
  auth:
    users:
      - username: $(ADMIN_USER)
        password: $(ADMIN_USER_PWD)
  additionalEnv:
    - name: ADMIN_USER
      valueFrom:
        secretKeyRef:
          name: multi-credentials-secret
          key: user1-username
    - name: ADMIN_USER_PWD
      valueFrom:
        secretKeyRef:
          name: multi-credentials-secret
          key: user1-password

Second, to cover will be administrators. It serves as the definition of user emails have the highest level of permissions upon authentication to HQ.

Third attribute is saml.metadata field, needed for setting SAML / SSO authentication. In this step, you will need metadata.xml file which can be set in two ways:

Referencing metadata.xml file through pre-created secret;
Placing metadata.xml contents inline as a string.

lensesHq:
  auth:
    address: ":8080"
    accessControlAllowOrigin:
      - 
    administrators:
      - [email protected]
      - [email protected]
    saml:
      baseURL: ""
      entityID: ""
      metadata:
        referenceFromSecret: true
        secretName: hq-tls-mock-saml-metadata
        secretKeyName: metadata.xml
      userCreationMode: "sso"
      usersGroupMembershipManagementMode: "manual"

lensesHq:
  auth:
    address: ":8080"
    accessControlAllowOrigin:
      - 
    administrators:
      - [email protected]
      - [email protected]
    saml:
      baseURL: ""
      entityID: ""
      metadata:
        referenceFromSecret: false
        stringData: |
          <?xml version="1.0" encoding="UTF-8" standalone="no"?>
          ...
          ...
          </md:EntityDescriptor>
      userCreationMode: "sso"
      usersGroupMembershipManagementMode: "sso"

In case SAML IdP requires certificate verification, same can be enabled and provided in the following way:

values.yaml

lensesHq:
  auth:
    saml:
      authnRequestSignature:
        enabled: true
        authnRequestSigningCert:
          referenceFromSecret: true
          secretName: hq-agent-test-authority
          secretKeyName: hq-tls-test.crt.pem
        authnRequestSigningKey:
          secret:
            name: saml-test
            key: privatekey.key

values.yaml

lensesHq:
  auth:
    saml:
      authnRequestSignature:
        enabled: true
        authnRequestSigningCert:
          stringData: |
            -----BEGIN CERTIFICATE-----
            ....
            -----END CERTIFICATE-----
        authnRequestSigningKey:
          secret:
            name: saml-test
            key: privatekey.key

Configure HTTP endpoint

The third pre-requirement to successfully run HQ is the http definition. As previously mentioned, this parameter defines everything around the HTTP endpoint of the HQ itself and how users will interact with it.

Definition of HTTP object is as follows:

lensesHq:
  http:
    address: ":8080"
    accessControlAllowOrigin:
      - 
    accessControlAllowCredentials: false
    secureSessionCookies: true
    tls:
      enabled: true
      cert:
      privateKey:
        secret:
          name: 
          key:

Second part of HTTP definition would be enabling TLS and TLS definition itself. As previously defined for lensesHq.agents.tls same way of configuring TLS can be used for lensesHq.http.tls definition as well.

Configure agent's connection endpoint

After correctly configuring the authentication strategy and connection endpoint, the agent handling is the last most important box to tick.

The Agent's object is defined as follows:

lensesHq:
  agents:
    # which port to listen on for agent requests
    address: ":10000" 
    tls:
      enabled: false
      verboseLogs: false
      cert:
      privateKey:

Enabling TLS

By default TLS for the communication between Agent and HQ is disabled. In case the requirement is to enable it, fthe ollowing has to be set:

lensesHq.agents.tls - certificates to manage the connection between HQ and the Agents
lensesHq.http.tls- certificates to manage connection with HQ's API

Unlike private keys which can be referenced and obtained only through a secret, Certificates can be referenced directly in values.yaml file as a string or as a secret.

values.yaml

lensesHq:
  agents:
    address: ":10000"
    tls:
      enabled: true
      cert:
        referenceFromSecret: true
        secretName: hq-agent-test-authority
        secretKeyName: hq-tls-test.crt.pem
      privateKey:
        secret:
          name: hq-agent-test-authority
          key: hq-tls-test.key.pem

values.yaml

lensesHq:
  agents:
    address: ":10000"
    tls:
      enabled: true
      cert:
        stringData: |
          -----BEGIN CERTIFICATE-----
          ...
          ...
          -----END CERTIFICATE-----
      privateKey:
        secret:
          name: hq-agent-test-authority
          key: hq-tls-test.key.pem

Configure license

In demo purposes and testing the product you can use our community license

license_key_2SFZ0BesCNu6NFv0-EOSIvY22ChSzNWXa5nSds2l4z3y7aBgRPKCVnaeMlS57hHNVboR2kKaQ8Mtv1LFt0MPBBACGhDT5If8PmTraUM5xXLz4MYv

License can be read in multiple ways:

from a pre-created secret
directly as a string defined in values.yaml file

values.yaml

lensesHq:
  license:
    referenceFromSecret: true
    secretName: hq-license
    secretKeyName: key
    acceptEULA: true

Configure metrics endpoint

Metrics are optionally available in a Prometheus format and by default served on port 9090.

The port can be changed in the following way:

values.yaml

lensesHq:
  metrics:
    prometheusAddress: ":9090"

(Optional) Configure Ingress & Services

Whilst the chart supports setting TLS on Lenses HQ itself we recommend placing it on the Ingress resource

Ingress and service resources are optionally supported.

The http ingress is intended only for HTTP/S traffic, while the agents ingress is designed specifically for TCP protocol. Ensure appropriate ingress configuration for your use case.

Enable an Ingress resource in the values.yaml:

values.yaml

ingress:
  http:
    enabled: true
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
    host: example.com
    ingressClassName: ""
    tls:
      enabled: false
      # The TLS secret must contain keys named tls.crt and tls.key that contain the certificate and private key to use for TLS.
      secretName: ""


  agent:
    enabled: true
    agentIngressConfig:
      apiVersion: traefik.containo.us/v1alpha1
      kind: IngressRouteTCP
      metadata:
        name: agents
      spec:
        entryPoints:
          - agents
        routes:
          - match: HostSNI(`example.com`)  # HostSNI to match TLS for TCP
            services:
              - name: lenses-hq            # Replace with your service name
                port: 10000                # Agent default TCP port  
        tls: {}

Enable a service resource in the values.yaml:

values.yaml

# Lenses HQ service
service:
  enabled: true
  type: ClusterIP
  annotations: {}
  externalTrafficPolicy:
  loadBalancerIP: 130.211.x.x
  loadBalancerSourceRanges:
    - 0.0.0.0/0

(Optional) Configure Service Accounts

Lenses HQ, by default, uses the default Kubernetes service account but you can choose to use a specific one.

If the user defines the following:

values.yaml

# serviceAccount is the Service account to be used by Lenses to deploy apps
serviceAccount:
  create: true
  annotations: {}
  name: lenses-hq

The chart will create a new service account in the defined namespace for HQ to use.

(Optional) Enable RBAC

There are two options you can choose between:

rbacEnable: true - will enable the creation of ClusterRole and ClusterRoleBinding for the service account mentioned in the snippet above\
rbacEnable: true and namespaceScope: true - will enable the creation of Role and RoleBinding which is more restrictive.

Configure logging

There are different logging modes and levels that can be adjusted.

values.yaml

lensesHq:
  logger:
    # Allowed values are: text | json
    mode: "text"

    # Allowed values are: info | debug
    level: "info"

Add chart repository

First, add the Helm Chart repository using the Helm command line:

helm repo add lensesio https://helm.repo.lenses.io/
helm repo update

GitHub - lensesio/lenses-helm-charts at release/6.0GitHub

Installing HQ

Be aware that for the time being and for alpha purposes usage of --versionis mandatory when deploying Helm chart through Helm repository.

terminal

helm install lenses-hq lensesio/lenses-hq \
   --values values.yaml \
   --create-namespace --namespace lenses-hq \
   --version 6.0.8

Example Values files

Be aware that example of values.yaml shows only how all parameters should look at the end. Please fill them with correct values otherwise Helm installation might not be successful.

Example of values.yaml

More about default values for Lenses HQ Helm Chart can be found in values.yaml. An example is below:

values.yaml

resources:
  requests:
  #   cpu: 1
    memory: 4Gi
  limits:
  #   cpu: 2
    memory: 8Gi

image:
  repository: lensesio/lenses:latest

rbacEnable: true
namespaceScope: true

ingress:
  http:
    enabled: true
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
    host: example.com

lensesHq:
  agents:
    address: ":10000"
    tls:
      enabled: true. # optional
      cert:
        referenceFromSecret: true
        secretName: hq-agent-test-authority
        secretKeyName: hq-tls-test.crt.pem
      privateKey:
        secret:
          name: hq-agent-test-authority
          key: hq-tls-test.key.pem
  auth:
    users:
      - username: admin
        # bcrypt("correcthorsebatterystaple").
        password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG
    administrators:
      - admin
      - [email protected]
      - [email protected]
    saml:
      enabled: true    # optional
      baseURL: ""
      entityID: ""
      # -- Example: <?xml version="1.0" ... (big blob of xml) </md:EntityDescriptor>
      metadata:
        referenceFromSecret: false
        secretName: ""
        secretKeyName: ""
        stringData: |
          <?xml version="1.0" encoding="UTF-8" standalone="no"?>
          </md:EntityDescriptor>
  
      userCreationMode: "sso"
      usersGroupMembershipManagementMode: "sso"
      uiRootURL: "/"
      groupAttributeKey: "groups"
  http:
    address: ":8080"
    accessControlAllowOrigin:
      - 
    accessControlAllowCredentials: false
    secureSessionCookies: true
    tls:
      enabled: true    # optional
      cert:
      privateKey:
        secret:
          name: 
          key:
  # Find more details in https://docs.lenses.io/current/installation/kubernetes/helm/#helm-storage
  ## Postgres template example: "postgres://[username]:[pwd]@[host]:[port]/[database]?sslmode=require"
  storage:
    postgres:
      enabled: true
      host: [POSTGRES_HOST_URL]
      port: 5432
      username: [POSTGRES_USERNAME]
      database: [POSTGRES_USER_PWD]
      passwordSecret:
        type: "precreated"
        name: initContainer-2-db-secret
        key: password

What's next?

After the successful configuration and installation of HQ, the next steps would be:

PreviousKubernetes - Helm NextDeploying an Agent

Last updated 1 month ago

Was this helpful?

Good afternoon

Prerequisites

Configure HQ

Configure storage (Postgres)

Configure AUTH endpoint

Configure HTTP endpoint

Configure agent's connection endpoint

Configure license

Configure metrics endpoint

(Optional) Configure Ingress & Services

(Optional) Configure Service Accounts

(Optional) Enable RBAC

Configure logging

Add chart repository

Installing HQ

Example Values files

What's next?