Deploying an Agent

This page describes installing Lenses Agent in Kubernetes via Helm.

Latest Agent image lensting/lenses-agent:6-preview

Prerequisites

• Kubernetes 1.23+

• Helm 3.8.0+

• Running Postgres instance

• External secret operator (in case of ExternalSecret usage)

Configure an Agent

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

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

1. Storage

2. HQ connection

3. Provision

4. Cluster RBACs

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

---

Configuring Agent chart

1

Configure storage (Postgres)

Postgres is the only available storage option.

Prerequisite:

• Running Postgres instance;

• Created database for an Agent;

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

lensesAgent:
  storage:
    postgres:
      enabled: true
      host: ""
      port: 
      username: ""
      database: ""
      schema: ""
      params: {}

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

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

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

Environment Variable

values.yaml

lensesAgent:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.postgres.svc.cluster.local
      port: 5432
      database: lensesagent
      username: external  # use "external" to manage it using secrets
  additionalEnv:
    - name: LENSES_STORAGE_POSTGRES_USERNAME
      valueFrom:
        secretKeyRef:
          name: [SECRET_RESOURCE_NAME]
          key: [SECRET_RESOURCE_KEY]

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;

Plain Value

values.yaml

lensesAgent:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.playground.svc.cluster.local
      port: 5432
      username: lenses
      database: lensesagent
      password: useOnlyForDemos         

Environment variable

values.yaml

lensesAgent:
  storage:
    postgres:
      enabled: true
      host: postgres-postgresql.postgres.svc.cluster.local
      port: 5432
      database: lensesagent
      username: lenses
      password: external   # use "external" to manage it using secrets
  additionalEnv:
    - name: LENSES_STORAGE_POSTGRES_PASSWORD
      valueFrom:
        secretKeyRef:
          name: [SECRET_RESOURCE_NAME]
          key: [SECRET_RESOURCE_KEY]

2

Configure HQ connection (agent key)

Connection to Lenses HQ is straight forward process which requires two steps:

1. Creating Environment and obtaining AGENT KEY in HQ as described here, if you already have not done so.

2. Storing that same key in Vault or as a K8s secret

The agent communicates with HQ via a secure custom binary protocol channel. To establish this channel and authenticate the Agent needs and AGENT KEY.

Once the AGENT KEY has been copied, store it inside of Vault or any other tool that has integration with Kubernetes secrets.

There are three available options how agent key can be used:

1. ExternalSecret via External Secret Operator (ESO)

2. Pre-created secret

3. Inline string

ExternalSecret

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

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

• create an ExternalSecret in the namespace where Agent is deployed;

• a secret is mounted for Agent to use.

values.yaml

lensesAgent:
  hq:
    agentKey:
      secret:
        type: "externalSecret"
        # Secret name where agentKey will be read from
        name: hq-password
        # Key name under secret where agentKey is stored
        key: key
        externalSecret:
          secretStoreRef:
            clusterSecretStore:
              name: [cluster_secretstore_name]

Pre-created secret

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

values.yaml

lensesAgent:
  hq:
    agentKey:
      secret:
        type: "precreated"
        # Secret name where agentKey will be read from
        name: hq-password
        # Key name under secret where agentKey is stored
        key: key

Inline String

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 Agent to connect to HQ.

values.yaml

lensesAgent:
  hq:
    agentKey:
      secret:
        type: "createNew"
        # Secret name where agentKey will be read from
        name: "lenses-agent-secret-1"
        # Value of agentKey generated by HQ
        value: "agent_key_*"

This secret will be fed into the provisioning.yaml. The HQ connection is specified at line 30, below, where reference ${LENSESHQ_AGENT_KEY} is being set:

values.yaml

lensesAgent:
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: [LENSES_HQ_FQDN_OR_IP]
            port:
              value: 10000
            agentKey:
              # This property shouldn't be changed as it is mounted automatically
              # based on secret choice for hq.agentKey above 
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false

In order to enable TLS for secure communication between HQ and the Agent please refer to the following part of the page.

3

Configure provisioning (Kafka / SchemaRegistry / Kafka Connect)

Provisioning offers various connection starting with:

• Kafka ecosystem components such as:

  • Kafka

  • Schema Registry

  • Kafka Connect

  • Zookeeper

• Alerts & Audits

• AWS

values.yaml

lensesAgent:
  provision:
    path: /mnt/provision-secrets
    connections:
      # Kafka Connection
      kafka:
        - name: Kafka
          version: 1
          tags: [my-tag]
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://your.kafka.broker.0:9092
                - PLAINTEXT://your.kafka.broker.1:9092
            protocol: 
              value: PLAINTEXT
            # all metrics properties are optional
            metricsPort: 
              value: 9581
            metricsType: 
              value: JMX
            metricsSsl: 
              value: falseSSL
      # Confluent Schema Registry Connection
      confluentSchemaRegistry:
        - name: schema-registry
          tags: ["tag1"]
          version: 1      
          configuration:
            schemaRegistryUrls:
              value:
                - http://my-sr.host1:8081
                - http://my-sr.host2:8081
            ## all metrics properties are optional
            metricsPort: 
              value: 9581
            metricsType: 
              value: JMX
            metricsSsl: 
              value: false
      # Kafka Connect connection
      connect:
        - name: my-connect-cluster-name
          version: 1    
          tags: ["tag1"]
          configuration:
            workers:
              value:
                - http://my-kc.worker1:8083
                - http://my-kc.worker2:8083
            metricsPort: 
              value: 9585
            metricsType: 
              value: JMX

More about provisioning and more advanced configuration options for each of these components can be found on the following link.

4

Cluster RBACs

The Helm chart creates Cluster roles and bindings, that are used by SQL Processors, if the deployment mode is set to KUBERNETES. They are used so that Lenses can deploy and monitor SQL Processor deployments in namespaces.

To disable the creation of Kubernetes RBAC set: rbacEnabled: false

If you want to limit the permissions the Agent has against your Kubernetes cluster, you can use Role/RoleBinging resources instead. Follow this link in order to enable it.

If you are not using SQL Processors and want to limit permissions given to Agent's ServiceAccount, there are two options you can choose from:

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

2. rbacEnable: true and namespaceScope: true - will enable creation of Role and RoleBinding which is more restrictive;

---

(Optional) Enable TLS connection with HQ

In this case, TLS has to be enabled on HQ. In case you haven't still enabled it, you can find details here to do it.

Enabling TLS in communication between HQ is being done in provisioning part of values.yaml.

In order to successfully enable TLS for the Agent you would need to:

• additionalVolume & additionalVolumeMounts - with which you will mount truststore with CA certificate that HQ is using and which Agent will need to successfully pass the handshake.

• additionalEnv - which will be used to securely read password to unlock truststore.

• Enable ssl in provision.

values.yaml

# Additional Volume with CA that HQ uses
additionalVolumes:
  - name: hq-truststore
    secret:
      secretName: hq-agent-test-authority
additionalVolumeMounts:
  - name: hq-truststore
    mountPath: "/mnt/provision-secrets/hq"

lensesAgent:
 # Additional Env to read truststore password from secret
 additionalEnv:
    - name: LENSES_HQ_AGENT_TRUSTSTORE_PWD
      valueFrom:
        secretKeyRef:
          name: hq-agent-test-authority
          key: truststore.jks.password
 provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: [HQ_URL]
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
            sslEnabled:
              value: false
            sslTruststore:
              file: "/mnt/provision-secrets/gq/truststore.jks"
            sslTruststorePassword:
              value: ${LENSES_HQ_AGENT_TRUSTSTORE_PWD}

---

(Optional) Services

Enable a service resource in the values.yaml:

# Lenses service
service:
  enabled: true
  annotations: {}

---

(Optional) Controlling resources

To control the resources used by the Agent:

# Resource management
resources:
  requests:
    cpu: 1
    memory: 4Gi
  limits:
    cpu: 2
    memory: 5Gi

In case LENSES_HEAP_OPTS is not set explicitly it will be set implicitly.

Examples:

1. if no requests or limits are defined, LENSES_HEAP_OPTS will be set as -Xms1G -Xmx3G

2. If requests and limits are defined above defined values, LENSES_HEAP_OPTS will be set by formula -Xms[-Xmx / 2] -Xmx[limits.memory - 2]

3. If .Values.lenses.jvm.heapOpts it will override everything

---

Enabling SQL processors in K8s mode

To enable SQL processor in KUBERENTES mode and control the defaults:

sql:
  # processorImage: eu.gcr.io/lenses-container-registry/lenses-sql-processor
  # processorImageTag: 2.3
  mode: IN_PROC
  heap: 1024M
  minHeap: 128M
  memLimit: 1152M
  memRequest: 128M
  livenessInitialDelay: 60 seconds

To control the namespace Lenses can deploy processors, use the sql.namespaces value.

SQL Processor Role Binding

To achieve you need to create a Role and a RoleBinding resource in the namespace you want the processors deployed to.

For example:

• Lenses namespace = lenses-ns

• Processor namespace = lenses-proc-ns

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: processor-role
  namespace: lenses-proc-ns
rules:
- apiGroups: [""]
  resources:
    - namespaces
    - persistentvolumes
    - persistentvolumeclaims
    - pods/log
  verbs:
    - list
    - watch
    - get
    - create
- apiGroups: ["", "extensions", "apps"]
  resources:
    - pods
    - replicasets
    - deployments
    - ingresses
    - secrets
    - statefulsets
    - services
  verbs:
    - list
    - watch
    - get
    - update
    - create
    - delete
    - patch
- apiGroups: [""]
  resources:
    - events
  verbs:
    - list
    - watch
    - get
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: processor-role-binding
  namespace: lenses-proc-ns
subjects:
- kind: ServiceAccount
  namespace: lenses-ns
  name: default
roleRef:
  kind: Role
  name: processor-role
  apiGroup: rbac.authorization.k8s.io

Finally you need to define in the Agent configuration which namespaces the Agent has access to. Amend values.yaml to contain the following:

values.yaml

lensesAgent:
  append:
    conf: |
      lenses.kubernetes.namespaces = {
        incluster = [
          "lenses-processors"
        ]
      }      

---

Prometheus metrics

Prometheus metrics are automatically exposed on port 9102 under /metrics.

lenses.conf

The main configurable options for lenses.conf are available in the values.yaml under the lenses object. These include:

• Authentication

• Database connections

• SQL processor configurations

To apply other static configurations use lenses.append.conf, for example:

values.yaml

lensesAgent:
  append:
    conf: |
      lenses.interval.user.session.refresh=40000

Install the Chart

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 the Agent

Installing using cloned repository:

helm install lenses-agent charts/lenses-agent \
   --values charts/lenses-agent/values.yaml \
   --create-namespace --create lenses-agent

Installing using Helm repository:

terminal

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

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

---

Example Values files

Example of values.yaml

values.yaml

lensesAgent:
  storage:
    postgres:
      enabled: true
      host: [postgres.url]
      port: 5432
      username: postgres 
      password: changeMe
      database: agent
  hq:
    agentKey:
      secret:
        type: "createNew"
        name: "agentKey"
        value: "agent_key_*"
  provision:
    path: /mnt/provision-secrets
    connections:
      lensesHq:
        - name: lenses-hq
          version: 1
          tags: ['hq']
          configuration:
            server:
              value: hq-tls-test-lenses-hq.hq-agent-test.svc.cluster.local
            port:
              value: 10000
            agentKey:
              value: ${LENSESHQ_AGENT_KEY}
      kafka:
        # There can only be one Kafka cluster at a time
        - name: kafka
          version: 1
          tags: ['staging', 'pseudo-data-only']
          configuration:
            kafkaBootstrapServers:
              value:
                - PLAINTEXT://kafka-1.svc.cluster.local:9092
                - PLAINTEXT://kafka-2.svc.cluster.local:9092
            protocol:
              value: PLAINTEXT
            # Metrics are strongly suggested for better Kafka cluster observability
            metricsType:
              value: JMX
            metricsPort:
              value: 9581

You can also find examples in the Helm chart repo.