Chkk Kubernetes Connector
An overview of Chkk Kubernetes Connector — what it is, why you need it, and how to install and configure it.
Overview
Key Components
The Chkk Kubernetes Connector is composed of two main components:
- Chkk Operator
- Chkk Agent
Working together, these components periodically (or on-demand) extract cluster metadata and ingest it into the Chkk SaaS platform. Once ingestion is complete, Chkk scans and analyzes your environment for potential risks or helpful insights (e.g., add-on, application service, and Kubernetes operator instances running in your cluster).
Chkk Operator
The Chkk Operator is a Kubernetes Operator that manages and configures the Chkk Kubernetes Connector. It deploys Chkk Agent through a single Custom Resource Definition (CRD) and simplifies configurations by:
- Providing a single source of truth (the CRD) for your Connector.
- Reporting deployment status, health, and errors in the CRD’s status.
- Limiting the risk of potential misconfigurations by enforcing higher-level settings.
Once deployed, the Operator:
- Validates your Chkk Connector configurations.
- Keeps the Connector aligned with your CRD-based configuration.
- Orchestrates creation and updates of the Connector resources.
- Reports the Connector’s status in the Operator’s CRD.
Chkk Agent
Chkk Agent is a Kubernetes Custom Resource managed by the Operator. It defines how and when to collect data from your cluster. Some key features include:
- Manages the Agent CronJob: Schedules periodic scans of your cluster to keep you informed of the latest known risks.
- Resource Filtering: Allows you to include or exclude specific namespaces or resource types.
Setup
Prerequisites
Before installing the Chkk Kubernetes Connector, ensure the following:
-
Allowlisted Access
- You must be allowlisted to access the Chkk SaaS. Contact us to get a dedicated Chkk Organization provisioned for you: chkk.io.
-
Network Firewall Rules
- If your cluster is in a restricted network, allow outbound connections to:
chkk.io
and its subdomainss3.amazonaws.com
and its subdomains
- If your cluster is in a restricted network, allow outbound connections to:
-
Proxy Settings
- If you use a proxy server, you will be required to configure the
HTTP_PROXY
,HTTPS_PROXY
, andNO_PROXY
environment variables at the time of installation.
- If you use a proxy server, you will be required to configure the
-
Image Hosting
- The Chkk Kubernetes Connector container images are hosted publicly on the Amazon ECR Public Registry. Ensure your cluster can pull images from this registry.
- Chkk supports custom registries. If you host all images in a private registry, detailed configuration instructions will be provided during installation.
Resource Requirements
Below are the baseline resource requests for each component of the Chkk Kubernetes Connector. Actual usage varies by cluster size and scan frequency.
Component | CPU | Memory |
---|---|---|
Chkk Operator | 100m | 256Mi |
Chkk Agent | 500m | 1024Mi |
Chkk Agent Manager | 50m | 128Mi |
Supported Kubernetes Distributions
The Chkk Kubernetes Connector is compatible with all Kubernetes providers that are compliant with the upstream API. For the list of supported Kubernetes providers and versions, refer to Support and Compatibility
Installation Modes
There are three deployment methods available for installing the Chkk Kubernetes Connector:
- Helm
- K8s YAML
- Terraform
System Requirements
Before installing the Chkk Kubernetes Connector, please ensure that your system meets the minimum requirements for the selected deployment method:
Helm
Helm
- Kubernetes >= v1.19 (tested on EKS, GKE, AKS)
- OS/Architecture: linux/amd64, linux/arm64
- kubectl: >= v1.19
- Helm: >= version 2
K8s YAML
K8s YAML
- Kubernetes >= v1.19 (tested on EKS, GKE, AKS)
- OS/Architecture: linux/amd64, linux/arm64
- kubectl: >= v1.19
Terraform
Terraform
- Kubernetes >= v1.19 (tested on EKS, GKE, AKS)
- OS/Architecture: linux/amd64, linux/arm64
Provider Requirements
Provider Requirements
- hashicorp/helm: >= version 2
- gavinbunney/kubectl: >= v1.19
Installation & Validation
- Log in to the Chkk Dashboard: chkk.io.
- In the left-hand sidebar, navigate to Risk Ledger → Clusters.
- Click Add Cluster in the top-right corner.
- Follow the step-by-step instructions and select your preferred deployment mode.
Configuration
Configuration Parameters
The table below lists the configurable parameters for installing the Chkk Operator.
Parameter | Description | Sample Default |
---|---|---|
image.repository | Image repository | public.ecr.aws/chkk/operator |
image.tag | Image tag | v0.0.14 |
image.pullPolicy | Image pull policy | Always |
replicaCount | Number of replicas | 1 |
revisionHistoryLimit | Revision history limit | 2 |
secret.create | Create a new secret | true |
secret.chkkAccessToken | Chkk access token | CHKK-ACCESS-TOKEN |
secret.ref.secretName | Name of an existing Secret with the Chkk access token (only used if secret.create=false ) | chkk-operator |
secret.ref.keyName | Key in the existing Secret’s data that contains the token (only used if secret.create=false ) | CHKK_ACCESS_TOKEN |
serviceAccount.create | Create a service account | true |
serviceAccount.name | Service account name | chkk-operator-sa |
podAnnotations | Annotations applied to the Chkk Operator Pod | { chkk.io/name: "chkk-operator" } |
disableAnalytics | Disable analytics data collection | false |
proxy.http_proxy | HTTP proxy | "" |
proxy.https_proxy | HTTPS proxy | "" |
proxy.no_proxy | No proxy | "" |
tolerations | Node tolerations | See values.yaml |
nodeSelector | Node labels for scheduling | {} |
affinity | Pod scheduling affinity | See values.yaml |
securityContext | Pod-Level Security Context | See values.yaml |
containerSecurityContext | Container-Level Security Context | See values.yaml |
Configuration Examples
Custom Secret
Custom Secret
If you prefer to manage the secret externally, set secret.create
to false and reference your secret in the values.yaml
file:
Custom RBAC
Custom RBAC
To customize the RBAC settings, modify the serviceAccount parameters in the values.yaml
file. You can specify whether to create a new service account and provide a custom name.
Custom Image
Custom Image
To use a custom image, update the image.repository
and image.tag
fields in the values.yaml
file. You can also set the image.pullPolicy
to control when the image is pulled.
Tolerations
Tolerations
To schedule the Chkk Operator on nodes with specific taints, configure the tolerations section in the values.yaml
file. You can specify the key, operator, value, and effect for each toleration.
Proxy Configuration
Proxy Configuration
When configuring the Chkk Connector to run behind a proxy, set the following fields in your values.yaml
to ensure proper connectivity and to disable telemetry reporting.
disableAnalytics: true
when defining proxy settings.This ensures the Chkk Operator and Agent operate correctly within your network environment.
Configuration Parameters
The table below lists the configurable parameters for installing the Chkk Operator.
Parameter | Description | Sample Default |
---|---|---|
image.repository | Image repository | public.ecr.aws/chkk/operator |
image.tag | Image tag | v0.0.14 |
image.pullPolicy | Image pull policy | Always |
replicaCount | Number of replicas | 1 |
revisionHistoryLimit | Revision history limit | 2 |
secret.create | Create a new secret | true |
secret.chkkAccessToken | Chkk access token | CHKK-ACCESS-TOKEN |
secret.ref.secretName | Name of an existing Secret with the Chkk access token (only used if secret.create=false ) | chkk-operator |
secret.ref.keyName | Key in the existing Secret’s data that contains the token (only used if secret.create=false ) | CHKK_ACCESS_TOKEN |
serviceAccount.create | Create a service account | true |
serviceAccount.name | Service account name | chkk-operator-sa |
podAnnotations | Annotations applied to the Chkk Operator Pod | { chkk.io/name: "chkk-operator" } |
disableAnalytics | Disable analytics data collection | false |
proxy.http_proxy | HTTP proxy | "" |
proxy.https_proxy | HTTPS proxy | "" |
proxy.no_proxy | No proxy | "" |
tolerations | Node tolerations | See values.yaml |
nodeSelector | Node labels for scheduling | {} |
affinity | Pod scheduling affinity | See values.yaml |
securityContext | Pod-Level Security Context | See values.yaml |
containerSecurityContext | Container-Level Security Context | See values.yaml |
Configuration Examples
Custom Secret
Custom Secret
If you prefer to manage the secret externally, set secret.create
to false and reference your secret in the values.yaml
file:
Custom RBAC
Custom RBAC
To customize the RBAC settings, modify the serviceAccount parameters in the values.yaml
file. You can specify whether to create a new service account and provide a custom name.
Custom Image
Custom Image
To use a custom image, update the image.repository
and image.tag
fields in the values.yaml
file. You can also set the image.pullPolicy
to control when the image is pulled.
Tolerations
Tolerations
To schedule the Chkk Operator on nodes with specific taints, configure the tolerations section in the values.yaml
file. You can specify the key, operator, value, and effect for each toleration.
Proxy Configuration
Proxy Configuration
When configuring the Chkk Connector to run behind a proxy, set the following fields in your values.yaml
to ensure proper connectivity and to disable telemetry reporting.
disableAnalytics: true
when defining proxy settings.This ensures the Chkk Operator and Agent operate correctly within your network environment.
The ChkkAgent
Custom Resource (CR) tells the Operator how the cluster scanning, and cluster context ingestion should function.
When you apply a ChkkAgent
resource, the Operator:
- Creates or updates a CronJob resource to run scans on a schedule.
- Handles resource filtering (which namespaces or resource types to include/exclude).
- Informs the Chkk Agent Manager about on-demand re-scan triggers from the Chkk Dashboard.
Specification Overview
Spec Fields
agentOverride
Field | Description |
---|---|
activeDeadlineSeconds | Time (in seconds) after which the job is terminated if it hasn’t finished. |
backoffLimit | Maximum number of retries for failed jobs before considering them permanently failed. |
completions | Number of pods that must successfully complete for the job to finish. |
completionMode | Method for tracking pod completions (NonIndexed or Indexed ). |
concurrencyPolicy | Defines concurrency handling for the job (Allow , Forbid , or Replace ). |
createRbac | Automatically create the necessary RBAC resources (Roles/ClusterRoles). |
failedJobsHistoryLimit | Number of failed job executions to keep for reference. |
image | Configuration for the Chkk Agent container image (repository, tag, etc.). |
managerImage | Configuration for the Chkk Agent Manager container image (repository, tag, etc.). |
name | Overrides the default name for the resource. Must be 1-65 characters if set. |
schedule | Cron expression defining how often the job runs. For example, 0 2 * * * would run daily at 02:00. |
serviceAccountName | ServiceAccount used by this job. Ignored if createRbac is true . If you’re manually managing RBAC, set this to reference your custom ServiceAccount. |
template | Pod template for the Chkk Agent, enabling detailed security, resource settings, etc. |
Advanced Configuration
Advanced Configuration
Field | Description |
---|---|
manualSelector | When true , allows you to manually control pod labels and pod selectors. Typically leave this false or unset so the system manages labels uniquely. |
parallelism | The maximum number of pods the job can run in parallel at one time. |
selector | A label query used to match pods to the job. Normally left unset so the system generates unique labels automatically. |
startingDeadlineSeconds | A deadline in seconds for starting the job if a scheduled run is missed. Missed runs are counted as failures. |
successfulJobsHistoryLimit | The number of successful job runs to retain. Older completions are cleaned up if you exceed this limit. |
suspend | When true , no pods are created and active pods are terminated. This effectively pauses the job. |
template | Defines the pod template for the Chkk Agent. You can customize security contexts, resource requests, environment variables, etc. |
timeZone | Time zone name for interpreting the schedule . Defaults to the kube-controller-manager’s time zone if unspecified. (Requires the CronJobTimeZone feature gate to be enabled in Kubernetes.) |
ttlSecondsAfterFinished | Time (in seconds) after the job finishes (Complete or Failed) before it’s eligible for garbage collection (auto-deletion). A value of 0 deletes the job immediately upon completion. |
global
Field | Description |
---|---|
clusterEnvironment | Environment name (e.g., production , development ). |
clusterName | Unique identifier for your cluster. |
credentials | API credentials for authenticating the agent with Chkk. |
endpoint | URL of the Chkk API. |
filter | Rules for including or excluding Kubernetes resources during scans. |
logLevel | Level of logging verbosity (e.g., trace , debug , info , warn , error , off ). |
podAnnotationsAsTags | Maps selected Kubernetes pod annotations to Chkk tags for better traceability. |
podLabelsAsTags | Maps selected Kubernetes pod labels to Chkk tags. |
tags | Custom tags to apply across clusters/resources (e.g., team:alpha ). |
updates | Controls agent auto-updates, specifying update frequency or behavior. |
Status Fields
Field | Description |
---|---|
agent | Indicates the current state of the associated CronJob (e.g., Active , Suspended ). |
conditions | List of conditions describing the ChkkAgent’s state (e.g., Ready , Reconciling ). |
lastScanTime | Timestamp of the most recent scan performed by the agent. |
latestUpdateState | Reflects the status of the last update applied to the ChkkAgent (e.g., Success , Failed ). |
Configuration Examples
Basic ChkkAgent Deployment
Basic ChkkAgent Deployment
The following example shows a basic deployment of the ChkkAgent
resource:
Custom Cluster Name and Cluster Environment on the Chkk Dashboard
Custom Cluster Name and Cluster Environment on the Chkk Dashboard
Setting the spec.global.clusterName
and spec.global.clusterEnvironment
fields in the ChkkAgent
resource allows you to customize the cluster name and environment displayed in the Chkk Dashboard:
Note: This can also be done manually through the Chkk Dashboard itself.
Custom Image
Custom Image
If you host the public.ecr.aws/chkk/chkk-agent
and public.ecr.aws/chkk/chkk-agent-manager
images in a private registry, or if you want to override the default versions of these images, you can do so by setting spec.agentOverride.image.name
and spec.agentOverride.managerImage.name
in the ChkkAgent
resource:
Custom Security Context
Custom Security Context
To customize the security context for the Chkk Agent, you can set the spec.agentOverride.template.securityContext
field and/or the spec.agentOverride.template.container.securityContext
field in the ChkkAgent
resource:
Custom Credentials via Secret
Custom Credentials via Secret
To use an existing Secret for the Chkk Agent’s credentials, set the spec.global.credentials.accessTokenSecret
field in the ChkkAgent
resource:
Custom RBAC Configuration
Custom RBAC Configuration
If you want to use a custom Service Account for the Chkk Agent, set the spec.agentOverride.serviceAccountName
field in the ChkkAgent
resource:
If you supply a custom ServiceAccount, ensure the associated ClusterRole has the following RBAC permissions:
Custom Resource Filtering
Custom Resource Filtering
To include or exclude specific namespaces or resource types during scans, set the spec.global.filter
field in the ChkkAgent
resource. By default, the following filter is applied:
Custom ChkkAgent CronJob Schedule
Custom ChkkAgent CronJob Schedule
To customize how frequently the Chkk Agent runs, set the spec.agentOverride.schedule
field in the ChkkAgent
custom resource. The schedule follows standard Kubernetes CronJob format.
If you prefer to manage your Kubernetes environment with Terraform, Chkk provides a Terraform module for deploying the Chkk Kubernetes Connector. This module automates creation of the Chkk Operator and Chkk Agent, handling secret management, RBAC, and other necessary resources.
Providers
The Terraform module relies on the following providers:
Name | Version |
---|---|
helm | >= 2.10.0 |
gavinbunney/kubectl | >= 1.7.0 |
Ensure these versions (or newer) are installed and configured in your Terraform environment.
Usage
Below are several usage examples showing how to configure secrets, override Service Accounts, or set the cluster name and environment. For all these examples, set source
to point to the appropriate Git repository and tag (e.g., ref=v0.1.6
).
Basic Token-Based Configuration
Basic Token-Based Configuration
This snippet deploys the Chkk Operator with a newly created Secret containing your Chkk access token. The Operator and Agent resources will be installed in the chkk-system
namespace.
Using an Existing Secret for Operator
Using an Existing Secret for Operator
If you already have a Secret named chkk-operator-secret
containing your Chkk access token, you can reference it directly instead of creating a new one.
Separate Secrets for Operator and Agent
Separate Secrets for Operator and Agent
You can also configure separate secrets for the Operator and the Agent. The Operator references chkk-operator-secret
, while the Agent references chkk-agent-secret
.
Custom Service Account for Operator
Custom Service Account for Operator
Use a custom Service Account name and let the module create it for you:
Custom Service Accounts (Operator + Agent)
Custom Service Accounts (Operator + Agent)
In this scenario, both Operator and Agent have their own existing Service Accounts (no new Service Accounts are created):
Custom Cluster Name and Cluster Environment on the Chkk Dashboard
Custom Cluster Name and Cluster Environment on the Chkk Dashboard
You can override the default cluster name and environment in the Chkk Dashboard by setting cluster_name
and cluster_environment
. In this example, a new secret is created for the Operator and Agent using <TOKEN>
.
Proxy Configuration
Proxy Configuration
When configuring the Chkk Connector to run behind a proxy using the Terraform module, define the following fields in your module configuration to ensure proper connectivity and to disable telemetry reporting.
disableAnalytics = true
when defining proxy settings.This ensures the Chkk Operator and Agent operate correctly within your network environment.
Custom Images
Custom Images
If you host the public.ecr.aws/chkk/chkk-agent
, public.ecr.aws/chkk/chkk-agent-manager
, or the public.ecr.aws/chkk/operator
images in a private registry, or if you want to override the default versions of these images, you can do so by updating the Terraform module with the following fields:
Custom ChkkAgent CronJob Schedule
Custom ChkkAgent CronJob Schedule
chkk_agent_config
section. The schedule follows standard Kubernetes CronJob format.Inputs
Below is a reference of the module’s input variables:
Name | Description | Type | Default | Required |
---|---|---|---|---|
release_name | The name of the Helm release. | string | chkk-operator | no |
namespace | The namespace where resources are deployed. | string | chkk-system | no |
chart_version | Version of the Helm chart to deploy. | string | n/a | no |
create_namespace | Whether to create the namespace if it doesn’t exist. | bool | true | no |
filter | Override the default filter for the ChkkAgent. | string | n/a | no |
cluster_name | Override the default cluster name for the ChkkAgent. | string | n/a | no |
cluster_environment | Override the default cluster environment for the ChkkAgent. | string | n/a | no |
chkk_operator_config | Values for configuring the Chkk Operator Helm chart. | map | {} | no |
chkk_operator_config.secret | Details on how to set up the Secret for the Chkk Operator (create new or reference existing). | map | {} | no |
chkk_operator_config.secret.create | Whether to create a new Secret resource or use an existing one. | bool | true | no |
chkk_operator_config.secret.chkkAccessToken | If create is true , this token is stored in the new Secret. | string | "" | no |
chkk_operator_config.secret.ref.secretName | If create is false , the name of an existing Secret containing the token. | string | "" | no |
chkk_operator_config.secret.ref.keyName | If create is false , the key name inside the existing Secret that stores the token. | string | "" | no |
chkk_operator_config.serviceAccount | Configure a dedicated Service Account for the Chkk Operator. | map | {} | no |
chkk_operator_config.serviceAccount.create | Whether to create a new Service Account or use an existing one. | bool | true | no |
chkk_operator_config.serviceAccount.name | Name of the Service Account (if create is true ) or the existing SA name. | string | chkk-operator-sa | no |
chkk_agent_config | Configuration overrides for the ChkkAgent. | map | {} | no |
chkk_agent_config.secret | Secret object used by the ChkkAgent. | string | "" | no |
chkk_agent_config.secret.accessToken | If the ChkkAgent is to create/use a new secret, specify the token here. | string | "" | no |
chkk_agent_config.secret.secretName | Name of the existing Secret that the ChkkAgent should use (if not creating a new one). | string | "" | no |
chkk_agent_config.secret.keyName | Key inside that Secret for the token. | string | "" | no |
chkk_agent_config.serviceAccount | Configure a dedicated Service Account for the ChkkAgent. | map | {} | no |
chkk_agent_config.serviceAccount.create | Whether to create or reuse an existing Service Account for the ChkkAgent. | bool | true | no |
chkk_agent_config.serviceAccount.serviceAccountName | If create = false , name of the existing Service Account the agent should use. | string | "" | no |
chkk_agent_config.agent_image | Agent Image object for ChkkAgent | map | {} | no |
chkk_agent_config.agent_image.name | Full image name for the agent image (repository:tag) | string | "" | no |
chkk_agent_config.manager_image | Manager Image object for ChkkAgent | map | {} | no |
chkk_agent_config.manager_image.name | Full image name for the manager image (repository:tag) | string | "" | no |
chkk_agent_config.schedule | Cron schedule for ChkkAgent CronJob execution. | string | "" | no |
Outputs
Currently, this module does not produce any outputs.
Upgrade
Get the current version of Helm chart installed in your K8s cluster
Sample output:
Update the Helm repository
Update the Helm repository to fetch latest chart
Upgrade the Kubernetes Connector
Replace <CHKK_ACCESS_TOKEN>
with your Chkk ingestion token, which you can copy from the Chkk Dashboard under Settings → Tokens.
Create a new Secret and ServiceAccount
Create a new Secret and ServiceAccount
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version.
Use the existing Secret with a new ServiceAccount
Use the existing Secret with a new ServiceAccount
Verify the Secret exists in your cluster
Sample output:
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version using the existing Secret.
Use the existing Secret and ServiceAccount
Use the existing Secret and ServiceAccount
Verify the ServiceAccount and Secret with the Chkk access token exists in your cluster
- Get the Secret:
Sample output:
- Get the ServiceAccount:
Sample output:
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version using the existing ServiceAccount and Secret.
Verify the upgrade
Sample output:
Get the current version of Helm chart installed in your K8s cluster
Sample output:
Update the Helm repository
Update the Helm repository to fetch latest chart
Upgrade the Kubernetes Connector
Replace <CHKK_ACCESS_TOKEN>
with your Chkk ingestion token, which you can copy from the Chkk Dashboard under Settings → Tokens.
Create a new Secret and ServiceAccount
Create a new Secret and ServiceAccount
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version.
Use the existing Secret with a new ServiceAccount
Use the existing Secret with a new ServiceAccount
Verify the Secret exists in your cluster
Sample output:
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version using the existing Secret.
Use the existing Secret and ServiceAccount
Use the existing Secret and ServiceAccount
Verify the ServiceAccount and Secret with the Chkk access token exists in your cluster
- Get the Secret:
Sample output:
- Get the ServiceAccount:
Sample output:
Run the following command to upgrade the Chkk Kubernetes Connector to the latest version using the existing ServiceAccount and Secret.
Verify the upgrade
Sample output:
Follow the given steps to Upgrade the Chkk Kubernetes Connector via Terraform
Update the Terraform IAC to use the latest version of the Chkk Kubernetes Connector
Create a new Secret and ServiceAccount
Create a new Secret and ServiceAccount
Use the existing Secret with a new ServiceAccount
Use the existing Secret with a new ServiceAccount
Use the existing Secret and ServiceAccount
Use the existing Secret and ServiceAccount
Verify the upgrade
Sample output: