Deploying HQ

This page describes installing Lenses HQ in Kubernetes via Helm.

Lenses HQ is prerequisite for installation of Lenses Agent

Latest images:

• HQ image: lensting/lenses-hq:6-preview

• HQ Cli image: lensting/lenses-cli:6-preview

Prerequisites

• Kubernetes 1.23+

• Helm 3.8.0+

• Running Postgres instance:

  • database for HQ;

  • username (and password) that has access to HQ database;

• Optional External secret operator (in case of ExternalSecret usage)

Configure HQ

In order to configure properly HQ, we have to understand parameter groups that the Chart offers.

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

1. storage

   • definition of connection towards database (Postgres is the only storage option)

2. auth

   • Password based authentication configuration

   • SAML / SSO configuration

   • definition of administrators or first users to access the HQ

3. 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

4. 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

5. license

6. monitoring

   • controls the metrics settings where Prometheus alike metrics will be exposed

7. loggers

   • definition of logging level for HQ

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

---

1

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 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:

Plain Value

The most straight forward way if username is not being changed by just defining it within username parameter such as

values.yaml

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

Reference from Secret

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:

1. External Secret via ExternalSecretOperator;

2. Pre-created secret;

3. Creating secret on the spot through values.yaml;

External Secrets

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:
          secretStoreRef:
            clusterSecretStore:
              name: enjoy2-secrets            

Pre-created 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

Create New Secret

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 correct connection URI special parameters are needed. In order to od the same you can set 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

2

Configure AUTH endpoint

SAML / SSO is available only with Enterprise license.

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.

Definition of auth object is as follows:

values.yaml

lensesHq:
  auth:
    users:
      - username: admin
        # bcrypt("correcthorsebatterystaple").
        password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG
    administrators:
      - admin
      - [e-mail]
      - [e-mail]
    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"

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

Inline Bcrypt hash

Reading from secret

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 definition of user emails which will have 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:

1. Referencing metadata.xml file through pre-created secret;

2. Placing metadata.xml contents inline as a string.

Reference from Secret

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

Inline String

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

3

Configure HTTP endpoint

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

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.

4

Configure agents connection endpoint

After correctly configuring authentication strategy and connection endpoint , 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 requirement is to enabled it, following has to be set:

• lensesHq.agents.tls - certificates to manage 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.

Reference Certificate from 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

Inline String

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

5

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

Reference Certificate from Secret

values.yaml

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

Inline string

values.yaml

lensesHq:
  licence:
    referenceFromSecret: false
    stringData: "license_key_*"

6

Configure metrics endpoint

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

Port can be changed in a 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

  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 default Kubernetes service account but user can choose to use specific one.

If user defines 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 new service account in the the defined namespace for HQ to use.

---

(Optional) Enable RBAC

There are two options user can choose between:

1. rbacEnable: true - will enable creation of ClusterRole and ClusterRoleBinding for service account mentioned in snippet above

2. rbacEnable: true and namespaceScope: true - will enable 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-preview https://lenses.jfrog.io/artifactory/api/helm/helm-charts-preview
helm repo update

GitHub - lensesio/lenses-helm-charts: Helm Charts for Lenses.ioGitHub

Installing HQ

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

terminal

helm install lenses-hq lensesio-preview/lenses-hq \
   --values values.yaml \
   --create-namespace --namespace lenses-hq \
   --version 6.0.0-alpha.17

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
      - [e-mail]
      - [e-mail]
    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

Whats' next?

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

1. Deploying and Agent

2. Configuring IAM roles / groups / policies