Kubernetes¶

Lenses can be deployed on Kubernetes by leveraging its prebuilt docker image.

Helm, a package manager for Kubernetes, is the recommended way to install Lenses. Helm can be download from here and relies on kubectl. Helm and kubectl are not part of the Lenses package and must be installed separately.

For a current list of our existing Helm Charts please visit our repo and are available on our GitHub repo.

Helm Chart¶

The Helm chart will optionally configure:

RBAC: Kubernetes role-based access controls. The chart will install the required cluster roles and cluster role bindings.
Services: The chart will create a service to abstract access to the Lenses backend.
Ingress: Lenses exposes a user interface and the endpoints behind. To allow access from outside Kubernetes, the chart can optionally create an ingress. The ingress is expected to be path based on an Ingress Controller such as Traefik.
Secrets: Sensitive data such as usernames, passwords, and TLS information should be distributed to pods by Kubernetes secrets. The chart will create secrets for the pod to mount. Secrets are used for the JKS stores to avoid base64 encoding twice the binaries via a config map.
ConfigMaps: A config map is used to hold krb5.conf data for SASL.
Deployment: The chart will deploy Lenses as a Deployment resource, mounting secrets in /mnt/secrets. The pods will be annotated with Prometheus annotations to allow automatic collection of the JMX metrics Lenses exposes.
Labels: All resources deployed by the chart are labeled with lenses.io./app: <release name> and lenses.io/app.type: lenses-<type>
Annotations: The Lenses deployment resource has the Prometheus annotations attached. Metrics are exposed on port 9102 at /metrics

Installing via Helm¶

Add the Landoop Helm chart repo:

# Add repos other connector charts
helm repo add Landoop https://landoop.github.io/kafka-helm-charts/

Use helm to install Lenses via the command line:

helm install lenses --name lenses --namespace lenses

Example to override the defaults i.e. enabled ingress and SSL:

helm install lenses --name lenses --namespace lenses --set ingress.enabled=true

Values Configuration¶

Field	Description	Type	Default	Required
image.repository	The sql runner image	landoop/lenses
image.tag	The sql runner image tag	2.1
replicaCount	Number of pods/instances to deploy	int	1	yes
monitoring.enabled	Flag to add Prometheus annotations to the pod for metric scraping	boolean	true	no
monitoring.pipeline	A label to attach to the pods for include in JMX	string		yes
monitoring.port	The port the Prometheus JMX exporter is exposing metrics on	int	9102	no
monitoring.path	The path which the metrics are served on	string	/metrics	no
resources.limit.memory	The kubernetes resource memory limit allowed for the pod	string	5Gi	no
resources.request.memory	The kubernetes resource memory request allowed for the pod	string	4Gi	no
rbacEnable	Create cluster roles and bindings if the kubernetes cluster has RBAC enabled	boolean	true
restPort	The port for Lenses	int	3030
serviceAccount	The Kubernetes service account Lenses will use to deploy resources. It must be patched with the image pull secret for the Lenses SQL runners	string	default	no
service.enabled	Create a service for Lenses	boolean	true	no
service.type	Kubernetes service type	string	ClusterIP	no
service.annotations	Annotations to add to the service	map		no
ingress.enabled	Create an ingress resource	boolean	true	no
ingress.path	The path based route for the ingress	string	/lenses	no
ingress.host	The host or ip of the external load balancer (Minikube ip)	string		yes
ingress.annotations	The annotations to add to the ingress resource	map	kubernetes.io/ingress.class: traefik, traefik.frontend.rule.type: PathPrefixStrip	no
ingress.tls.enabled	Enable TLS ingress	boolean	false	no
ingress.tls.crt	The TLS certificate data, base64 encoded	Base64 string		no
ingress.tls.key	The TLS key data base64 encoded	Base 64 string		no
lenses.jvm.heapOpts	JVM heap options for Lenses	string		no
lenses.jvm.performanceOpts	JVM performance tunning extra options for Lenses	string		no
lenses.jvm.logBackOpts	Logback options	string		no
lenses.kafka	List of Kafka brokers. See brokers	string		yes
lenses.zookeeper	List of Zookeepers. See zookeepers	string		yes
lenses.schemaRegistries	List of Schema Registries. See schema registries	string		yes
lenses.connectClusters	Array of Connect Clusters. See connect clusters	string		yes
lenses.grafanaUrl	The url to the grafana host	string		no
lenses.slack.enabled	Enable slack integration	boolean	false	no
lenses.slack.iconUrl	The url to the icon to use for slack	string		no
lenses.slack.webhookUrl	Slack webhookUrl	string		no
lenses.slack.username	The username to use for slack	string		no
lenses.slack.channel	The slack channel to send alerts to	string		no
lenses.topics.suffix	A suffix to add to Lenses system topics	string		no
lenses.sql	See processor options	string		no
lenses.security.mode	The security mode, NONE, BASIC, LDAP or KERBEROS	string	NONE	yes
lenses.security.groups	List of groups. See security groups if basic or ldap security enabled	string		no
lenses.security.users	List of users. See security users if basic mode is enabled	string		no
lenses.security.serviceAccounts	List of service accounts. See security users if basic mode is enabled	string		no
lenses.security.ldap.url		string		no
lenses.security.ldap.base		string		no
lenses.security.ldap.password	LDAP password for the user	string		no
lenses.security.ldap.user	LDAP user	string		no
lenses.security.ldap.plugin.class	FQDN class for the ldap plugin to use	string		no
lenses.security.ldap.plugin.memberOfKey		string		no
lenses.security.ldap.plugin.groupExtractRegex		string		no
lenses.security.ldap.plugin.personNameKey		string		no
lenses.security.kerberos.service.principal	The kerberos principal	string		no
lenses.security.kerberos.keyTabData	The kerberos keytab data	string		no
lenses.security.kerberos.debug	Enable kerberos debug	boolean		no
lenses.security.kerberos.mappings	Kerberos group mappings, see kerberos mappings	object		no
lenses.license	The Lenses license data	string		no
lenses.licenseUrl	Url to fetch the license from	string		no
lenses.configOverrides	Extra configs. Allows for any extra configurations For example lenses.interval.summary=1000	list of dictonaries		no

Bootstrap servers

lenses.brokers contains the broker options. Multiple brokers are supported.

If you are deploying brokers inside Kubernetes they should be deployed as a statefulset like this. This allows the pods to have stable network identifiers. Each pods address should be added as an entry. The address takes the form of:

<statefulset-name>-<pod ordinal identifier>.<service name>.<namespace>.svc.cluster.local

For example, a statefulset of 3 replicas called broker with a headless service called broker, the addresses would be:
broker-0.broker.defaut.svc.cluster.local
broker-1.broker.defaut.svc.cluster.local
Note

New brokers added or removed on scaling will not be reflected. Currently, Lenses will require a config update. Future releases will address this.

If you only have one broker you can set the service name.

If your brokers are outside Kubernetes add host names.

Field Description Type Default Required

ssl.enabled SSL is enabled on the brokers false

ssl.truststoreFileData

The base64 encoded contents

of the truststore

base64 no

ssl.keystoreFileData

The base64 encoded contents

of the keystore

base64 no

ssl.truststorePassword The truststore password string no

ssl.keystorePassword The keystore password string no

sasl.enabled SASL is enabled on the brokers boolen false no

sasl.keyTabData

The base64 encoded contents

of the keytab file is sasl enabled with GSSAPI

base64 no

sasl.jaasFileData

The contents of the jaas.conf file

is sasl is enabled

string no

sasl.mechanism

The security.mechanism to use.

GSSAPI, SCRAM or PLAINTEXT

string GSSAPI no

sasl.krb5Conf

The contents of the krb5Conf file

if the sasl mechanism is GSSAPI
string no

bootstrapServers is a list of brokers, names and ports

Field Description Type Default Required

bootstrapServers.name Host name of the broker

bootstrapServers.port The PLAINTEXT default Kafka port int 9092 yes

bootstrapServers.sslPort The SSL Kafka port int 9093 yes

bootstrapServers.saslPort The SASL_SSL Kafka port int 9094 yes

bootstrapServers.saslPlainTextPort The SASL_PLAINTEXT Kafka port int 9095 yes

Example:
lenses:
  kafka:
    ssl:
      enabled: false
      trustStoreFileData:
      keyStoreFileData:
      trustStorePassword:
      keyStorePassword:
      keyPassword:
    sasl:
      enabled: false
      # keyTabData is the base64 enecoded contents kerberos keytab file is using kerberos mounted in /mnt/secrets
      keyTabData: |-

      # jaasFileData is the contents of the kafka jaas file mounted in /mnt/secrets
      jaasFileData: |-

      # mechanism is the sasl authentication mechanism GSSAPI, SCRAM or PLAIN
      mechanism: "GSSAPI"
      # krb5Conf is the Kerberos config data to be mounted into /etc
      krb5Conf: |-

    bootstrapServers:
      - name: kafka
        port: 9092
        sslPort: 9093
        saslSslPort: 9094
        saslPlainTextPort: 9095

Zookeepers

lenses.zookeepers is a list of zookeepers detailing the hostname, HTTP protocol, and ports. Multiple zookeepers are supported.

If you are deploying a quorum of zookeepers inside Kubernetes they should be deployed as a statefulset like this. This allows the pods to have stable network identifiers. Each pods address should be added as an entry. The address takes the form of:

<statefulset-name>-<pod ordinal identifier>.<service name>.<namespace>.svc.cluster.local

For example, a statefulset of 3 replicas called zookeeper with a headless service called zookeeper, the addresses would be:
zookeeper-0.zookeeper.defaut.svc.cluster.local
zookeeper-1.zookeeper.defaut.svc.cluster.local
Note

New zookeepers added or removed on scaling will not be reflected. Currently, Lenses will require a config update. Future releases will address this.

If you only have one zookeeper you can set the service name.

If your zookeepers are outside Kubernetes add host names.

Field Description Type Default Required

host The hostname of the zookeeper instance string zookeeper yes

port The port for the zookeeper instance int 8081 yes

jmxPort The JMX port for the zookeeper instance int 9102 yes

Example:
lenses:
  zookeepers:
    - host: zookeeper-1
      port: 2181
      jmxPort: 9102
    - host: zookeeper-2
      port: 2181
      jmxPort: 9102

Schema Registries

lenses.schemaRegistries.hosts is a list of schemaRegistries detailing the hostname, HTTP protocol and ports. Multiple schema registries are supported.

If you are deploying multiple schema registries for high availability inside Kubernetes they should be deployed as a statefulset. This allows the pods to have stable network identifiers. Each pods address should be added as an entry. The address takes the form of:

<statefulset-name>-<pod ordinal identifier>.<service name>.<namespace>.svc.cluster.local

For example, a statefulset of 2 replicas called schema-registry with a headless service called schema-registry, the addresses would be:
schema-registry-0.schema.defaut.svc.cluster.local
schema-registry-1.schema.defaut.svc.cluster.local
Note

New schema registries added or removed on scaling will not be reflected. Currently, Lenses will require a config update. Future releases will address this.

If you only have one schema registry you can set the service name.

If your schema registries are outside Kubernetes add host names.

Field Description Type Default Required

enabled Enable schema registry support boolean false

host The host name of the schema registry instance string schema-registry yes

protocol The HTTP protocol, http or https string http yes

port The port for the schema registry instance int 8081 yes

jmxPort The jmx port for the schema registry instance int 9102 yes

hosts.auth

The Worker authentication type

URL, NONE, SASL_INHEIRT

or USER_INFO

string NONE no

username

Username to authentication

with the workers

string no

password

Password to authentication

with the workers

string no

Example:

lenses:
  schemaRegistries:
    enabled: true
    hosts:
      - host: schema-registry-1
        protocol: http
        port: 8081
        jmxPort: 9102
        auth: USER_INFO
        username: myusername
        password: mypassword
      - host: schema-registry-2
        protocol: http
        port: 8081
        jmxPort: 9102

Connect clusters

The lenses.connectClusters is an array of Connect clusters detailing the cluster name, ports, backing topics and worker hosts. Multiple clusters can be configured.

If you are deploying a Connect cluster inside Kubernetes they should be deployed as a statefulset. This allows the pods to have stable network identifiers. Each pods address should be added as an entry. The address takes the form of:

<statefulset-name>-<pod ordinal identifier>.<service name>.<namespace>.svc.cluster.local

For example, a statefulset of 2 replicas called connect with a headless service called connect, the addresses would be:
connect-worker-0.connect.defaut.svc.cluster.local
connect-worker-1.connect.defaut.svc.cluster.local
Note

New workers added or removed on scaling will not be reflected. Currently, Lenses will require a config update. Future releases will address this.

If you only have one zookeeper you can set the service name.

If your connect workers are outside Kubernetes add host names.

Field Description Type Default Required

enabled Enabled Kafka Connect support boolean false yes

name The name/alais for the cluster string yes

port The workers rest port int 8083 yes

protocol The HTTP protocol, http or https string http yes

jmxPort The jmx port for the workers int 9102 yes

auth

The Worker authentication type

URL, NONE, SASL_INHEIRT

or USER_INFO

string NONE no

username

Username to authentication

with the workers

string no

password

Password to authentication

with the workers

string no

offsetsTopic

The offset backing topic

for the cluster

string connect-offsets yes

statusTopic

The statuses backing topic

for the cluster

string connect-statuses yes

configsTopic

The configs backing topic

for the cluster

string connect-configs yes

hosts List of connect worker host names string yes

Example:
connectClusters:
  enabled: true
  clusters:
    - name: datascience
      port: 8083
      jmxPort: 9102
      offsetsTopic: connect-offsets-datascience
      statusTopic: connect-statuses-datascience
      configTopic: connect-configs-datascience
      hosts:
        - worker-ds-1
        - worker-ds-1
        - worker-ds-1

    - name: dataengineering
      port: 8083
      jmxPort: 9102
      offsetsTopic: connect-offsets-dataengineering
      statusTopic: connect-statuses-dataengineering
      configTopic: connect-configs-dataengineering
      hosts:
        - worker-de-1
        - worker-de-1
        - worker-de-1
      auth: URL
      username: myusername
      password: mypassword

SQL Processor Options¶

lenses.sql contains the options for configuring SQL Processors deployed via Lenses.

Field	Description	Type	Default	Required
processorImage	The processor image to use for Lenses SQL runners	string	eu.gcr.io/k8-engine/lenses-sql-processor	no
processorImageTag	The processor image tag	string	2.1.0	no
mode	The SQL scaling mode, IN_PROCESS, CONNECT or KUBERNETES	string	IN_PROCESS	yes
heap	The heap space for the sql processors	string	1024M	no
memLimit	The Kubernetes memory resource limit for the sql processors	string	1152M	no
memRequest	The Kubernetes memory resource request for the sql processors	string	128M	no
truststoreFileData	The base64 encoded contents of the truststore	base64		no
keystoreFileData	The base64 encoded contents of the keystore	base64		no
truststorePassword	The truststore password	string		no
keystorePassword	The keystore password	string		no
enabled	SASL is enabled on the brokers	boolen	false	no
keyTabData	The base64 encoded contents of the keytab file is sasl enabled with GSSAPI	base64		no
jaasFileData	The contents of the jaas.conf file is sasl is enabled	string		no
sasl.mechanism	The `security.mechanism` to use. GSSAPI, SCRAM or PLAINTEXT	string	GSSAPI	no
sasl.krb5Conf	The contents of the krb5Conf file if the sasl mechanism is GSSAPI	string		no

Alert Managers

lenses.alertmanagers is a list of AlertManagers detailing the hostname, HTTP protocol, and ports. Multiple AlertManagers are supported.

If the AlertManagers are running inside Kubernetes add the service name to lenses.alertmanagers.host, otherwise just add the hostnames to lenses.alertmanagers.host.

Field	Description	Type	Default	Required
enabled	Enable alertmanager integration	boolean	false	no
sourceName	The source name for alerts The Helm release name and namespace are used as a suffix	string	Lenses-k8-<release-name>-<namespace>
consumersLagThreshold	The default consumer lag for alerting	int	50000
host	The host name of the alertmanagers instance	string	alertmanagers	yes
port	The port for the alertmanagers instance	int	8081	yes
protocol	The HTTP protocol, http or https	string	http	yes

Example:

alertManagers:
  enabled: false
  endpoints:
    - host: alertmanager
      protocol: http
      port: 9094

  sourceName: Lenses-k8
  consumersLagThreshold: 50000

Security Groups

The security group section contains a list of groups with the following attributes:

Field	Description	Type	Default	Required
lenses.security.groups.name	The name for a security group	string		yes
lenses.security.groups.roles	List of roles for the security group (read, write, admin, nodata)	string		yes

example:

lenses:
  security:
    groups:
      - name: adminGroup
        roles:
          - admin
          - write
          - read
      - name: writeGroup
        roles:
          - read
          - write
      - name: readGroup
        roles:
          - read

Security Users

The security users section contains a list of users with the following attributes:

Field	Description	Type	Required
lenses.security.users.username	User name	string	no
lenses.security.users.password	User password	string	no
lenses.security.users.displayName	Display name for the user	string	no
lenses.security.users.groups	Array of security group names	string	no
lenses.security.users.topic.whitelist	List of topic names to whitelist	string	no
lenses.security.users.topic.blacklist	List of topic names to blacklist	string	no

example:

lenses:
  security:
    users:
      - username: admin
        password: admin
        displayname: LensesAdmin
        groups:
          - adminGroup
        topic:
          blacklist:
            - andrew
          whitelist:
            - position_reports.*
      - username: write
        password: write
        displayname: Writer
        groups:
          - writeGroup
      - username: read
        password: read
        displayname: Reader
        groups:
          - readGroup

Security Service Accounts

The security service accounts section contains a list of service accounts with the following attributes:

Field	Description	Type	Required
lenses.security.serviceAccounts.username	Username for the service account	string	no
lenses.security.serviceAccounts.token	Token for the service account	string	no
lenses.security.serviceAccounts.groups	List of security groups the service acocunt belongs to	string	no

example:

lenses:
  serviceAccounts:
    - username: jenkins
    token: jenkins
    groups:
      - adminGroup

Kerberos Group Mappings

The Kerberos mapping group section contains a list of groups with the following attributes:

Field	Description	Type	Default	Required
lenses.security.kerberos.mappings.username	The name for a security group	string		yes
lenses.security.kerberos.mappings.groups	List of security groups the kerberos user is mapped to	string		yes

example:

lenses:
  security:
    kerberos:
      - name: admin@LANDOOP.COM
        groups:
          - adminGroup
          - writeGroup
          - readGroup
      - name: writer@LANDOOP.COM
        groups:
          - readGroup
          - writeGroup
      - name: reader@LANDOOP.COM
        groups:
          - readGroup

LoadBalancer Service¶

You can also set the service.serviceType to LoadBalancer and set a static address. To do this you must comment out the LoadBalancer section and set the values accordingly.

Secrets¶

Kafka Secrets

kafka.ssl and kafka.sasl values are placed in a Secret called <release-name>. Both the key/trust stores and the passwords are added. The items from this secret are then mounted in /mnt/secrets.

Take care with SASL enabled Kafka clusters to set the path correctly in the JAAS config data to /mnt/secrets for the keytab file. The kafka.sasl.keyTabData is mounted as a /mnt/secrets/keytab. If sasl is enabled -Djava.security.auth.login.config=/mnt/secrets/jaas.conf is added to the Lenses java opts.

Lenses secrets are labelled lenses.io/app.type: lenses-secret.

Lenses Secrets

Lenses secrets, lenses.license and lenses.security** values are placed in a secret named after the helm release.

ConfigMaps¶

The chart will create a configMap to hold the krb5.conf for Lenses and the SQL processors. This will be mounted in /etc.

Lenses configMaps are labelled lenses.io/app.type: lenses-configmap.

RBAC¶

If your Kubernetes cluster has RBAC enabled then Lenses service account Lenses requires the following access:

Resource	Verbs
namespaces	list, watch, get, create
pods	list, watch, get, update, create, patch, delete
deployments	list, watch, get, update, create, patch, delete
replicaSet	list, watch, get, update, create, patch, delete
events	list, watch, get

The Lenses Helm chart will create the required cluster roles and bindings.

Lenses cluster role bindings are labeled lenses.io/app.type: lenses-cluster-role-binding and the cluster role lenses.io/app.type: lenses-cluster-role.

Standard Manifest¶

A standard Kubernetes manifest can be found here.

Lenses requires the configuration to be split into two: the main one and the security-related settings - usually named as security.conf. The contents of a security.conf file can be mounted into the pods via:

kubectl create secret generic lenses-secrets --from-file=./LENSES_SECURITY_USERS --from-file=./license.json

The pod manifest will mount the contents of LENSES_SECURITY_USERS.

More Kubernetes integration¶

Lenses can deploy SQL processors on Kubernetes. Please see here.