Deploying an Agent

This page describes installing Lenses Agent in Kubernetes via Helm.

Prerequisites

Kubernetes 1.23+
Helm 3.8.0+
Running Postgres instance
External secret operator (in case of ExternalSecret usage)

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

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

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

Provisioning

For more information on provisioning see here.

To automatically provision the connections to Kafka, HQ and other systems set the .Values.lenses.provision.connections to be the YAML definition of your connections.

The chart will render the full YAML specified under this setting as the provisioning.yaml file.

Alternatively you can use a second YAML file, which contains only the connections pass them at the command line when installing:

Understanding the Chart

The chart uses:

Secrets to store Postgres credentials and authentication credentials
Secrets to store connection credentials such as Kafka SASL_SCRAM password or password for SSL JKS stores.
Secrets to hold the base64 encoded values of the JKS stores
Secrets to store AGENT KEY for connection to Lenses HQ
ConfigMap for Lenses configuration overrides
Cluster roles and role bindings (optional).

Secrets and config maps are mounted as files under the mount /mnt:

settings - holds the lenses.conf
provision-secrets - holds the secrets for connections in the provisioning.yaml file
provision-secrets/files - holds any file needed for a connection, e.g. JKS files.

If you are curious about Provisioning API specs which can help you understand connection configs, you can find the same under page Provisioning API reference.

Connection to Lenses HQ

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

Creating Environment and obtaining AGENT KEY in HQ as described here, if you already have not done so.
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:

ExternalSecret via External Secret Operator (ESO)
Pre-created secret
Inline string

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

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

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

values.yaml

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

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

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

lensesHq:
    provision:
      enabled: true
      version: "2"
      path: /mnt/provision-secrets
      connections:
        grpcServer:
          - 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

Cluster RBAC

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:

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

Postgres

To use Postgres as the backing store for the Agent set the details in the lenses.storage.postgres object.

storage:
    postgres:
      enabled: false
      host:
      port: 
      username:
      password:
      database:
      schema:

External Secrets

The chart relies on secrets for sensitive information such as Passwords. Secrets can rotate and are commonly stored in an external store such as Azure KeyVault, Hashicorp Vault or AWS Secrets Manager.

For Postgres, add additional ENV variables via the lenses.additionalEnv object to point to your secret and set the username and password to external in the Postgres section.

      # - name: LENSES_STORAGE_POSTGRES_PASSWORD
      #   valueFrom:
      #     secretKeyRef:
      #       name: [SECRET_RESOURCE_NAME]
      #       key: [SECRET_RESOURCE_KEY]

Services

Enable a service resource in the values.yaml:

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

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:

if no requests or limits are defined, LENSES_HEAP_OPTS will be set as -Xms1G -Xmx3G
If requests and limits are defined above defined values, LENSES_HEAP_OPTS will be set by formula -Xms[-Xmx / 2] -Xmx[limits.memory - 2]
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

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

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

Example Values files

You can also find examples in the Helm chart repo.

PreviousDeploying HQ NextDocker

Last updated 4 days ago