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 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:
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
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
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. |
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
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
).
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.
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.
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
Verify the upgrade
Sample output: