Troubleshooting

1. How can I resolve 'Token not authorized' errors in ChkkAgent pods?

Answer: These errors typically indicate that your token is either invalid or missing. If you are using a secret-based approach, verify that the secret contains a valid token. If you are installing via Helm, ensure that the Helm chart is upgraded using a valid token.

1

Export a valid Access Token

Login to Chkk Dashboard and export a valid Access Token.

2

Upgrade the Helm chart with your valid token

helm upgrade chkk-operator chkk/chkk-operator --namespace chkk-system --set secret.chkkAccessToken=<ACCESS-TOKEN>

Sample Output

3

Confirming the agent-manager pod status

Use the command below to ensure the pod is running:

kubectl get pods -n chkk-system

Sample Output

If these steps do not solve your issue, please reach out on your private Slack or MS Team Channel or email support@chkk.io.

2. How do I use an existing Service Account with the Chkk Kubernetes Connector?

3. How can I use an existing secret with the Chkk Kubernetes Connector?

4. How do I ignore specific Risks using my Infrastructure as Code (IaC)?

Answer: You can ignore Risks by adding the chkk.io/ignore annotation to your Kubernetes resources in your IaC.

1

Ignoring all Risks

Use a wildcard (*) in the annotation:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    chkk.io/ignore: "*"
    deployment.kubernetes.io/revision: "1"
    meta.helm.sh/release-name: traefik-1
    meta.helm.sh/release-namespace: traefik-ns

2

Ignoring specific Risks

Specify the ARSig IDs you wish to ignore:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    chkk.io/ignore: CHKK-K8S-1002,CHKK-K8S-602
    deployment.kubernetes.io/revision: "1"
    meta.helm.sh/release-name: traefik-1
    meta.helm.sh/release-namespace: traefik-ns

5. How do I set Cluster Name and Environment using the ChkkAgent CRD?

Answer: You can define your Cluster Name and Cluster Environment within the ChkkAgent CRD itself.

For example:

kubectl apply -f - <<EOF
apiVersion: k8s.chkk.io/v1beta1
kind: ChkkAgent
metadata:
   name: chkk-agent
   namespace: chkk-system
spec:
  global:
    clusterName: <CLUSTER_NAME>
    clusterEnvironment: <CLUSTER_ENVIRONMENT>
EOF

You can also adjust these settings in the Chkk Dashboard under Risk Ledger > Clusters by clicking Edit on your cluster card or within the cluster’s Properties tab.

Note: If you set the Cluster Name/Environment through IaC, you cannot edit them from the Dashboard.

6. How do I specify Cluster Name and Environment with the Terraform module?

Answer: In your Terraform configuration, set the cluster_name and cluster_environment variables when using the Chkk K8s Connector Terraform Module.

Requirements

A compatible version of the Chkk K8s Connector Terraform Module

Example Terraform configuration:

hcl
module "chkk_k8s_connector" {
  source     = "git::https://github.com/chkk-io/terraform-chkk-k8s-connector.git?ref=<CHKK_TERRAFORM_K8S_CONNECTOR_VERSION>"

  create_namespace = true
  namespace        = "chkk-system"

  operator_config = {
    secret = {
      chkkAccessToken : <ACCESS-TOKEN>
    }
  }

  cluster_name        = <CLUSTER_NAME>
  cluster_environment = <CLUSTER_ENVIRONMENT>
}

Alternatively, you can edit the Cluster Name and Environment in the Chkk Dashboard.

Note: If the Cluster Name/Environment are defined via IaC, they cannot be edited from the Dashboard.

7. How do I manually clear the finalizer from the ChkkAgent custom resource?

Answer: When a Kubernetes custom resource is deleted, any configured finalizers must be cleared before the object is fully removed. If a finalizer is misconfigured or cannot complete its cleanup, the resource remains stuck in the terminating state. To force-remove the finalizer and allow the deletion to complete, run the following command:

kubectl patch chkkagent/chkk-agent -n chkk-system -p '{"metadata":{"finalizers":null}}' --type=merge

This command manually clears the finalizer from the metadata, allowing the resource to be removed successfully.

8. How do I fix 'failed to determine if *v1.ConfigMap is namespaced: Forbidden' errors in ChkkAgent pods?

Answer: This error commonly indicates that a proxy server or firewall is blocking requests to the Kube API Server. Verify that your Kube API Server address is allowlisted or permitted within your network’s proxy/firewall configurations.

Example log snippet:

2024-06-26T18:19:47Z ERROR setup unable to start manager {"error": "failed to determine if *v1.ConfigMap is namespaced: failed to get restmapping: failed to get server groups: Get \"https://172.20.0.1:443/api\": Forbidden"}

9. How do I uninstall the Chkk Operator to remove a Cluster?

Answer:

1

Deactivate the Cluster in the Chkk Dashboard

In the Dashboard, deactivate the cluster you want to remove.

2

Remove Custom Resources

List all ChkkAgent resources:

kubectl get chkkagent --all-namespaces

Delete all ChkkAgent resources:

kubectl delete chkkagent --all --all-namespaces

3

Remove Chkk Operator (Helm-based)

Check installed charts:

helm ls -n chkk-system

Uninstall the chart:

helm uninstall chkk-operator -n chkk-system

Delete the namespace:

kubectl delete ns chkk-system

4

Remove Chkk Operator (K8s YAML-based)

List resources in chkk-system:

kubectl get all -n chkk-system

Delete Operator resources:

kubectl delete -f https://helm.chkk.io/chkk-operator/manifest.yaml

Delete the namespace:

kubectl delete ns chkk-system

5

Remove the ChkkAgent CRDs

Finally, remove the CRD:

kubectl delete crds chkkagents.k8s.chkk.io

10. Why is my cluster stuck in onboarding or showing no or single-digit operational risks in Risk Ledger?

11. Why is my Chkk Operator failing with 'x509: certificate signed by unknown authority' when connecting to *.chkk.io?

Answer: This error often occurs when a proxy in the network is intercepting HTTPS traffic. Specifically, if you use Squid Proxy with SSL Bump enabled, the proxy acts as a proxy-in-the-middle and presents its own certificate instead of the actual server certificate. Since this certificate is not signed by a known Certificate Authority (CA), Chkk system refuses the connection due to failed certificate validation.

1

Understand the root cause

Squid Proxy with SSL Bump intercepts encrypted traffic and re-signs it with an internal/self-signed CA. Chkk system does not trust this certificate by default, which causes the error:

tls: failed to verify certificate: x509: certificate signed by unknown authority

2

Skip SSL Bump for Chkk domains in Proxy

To allow Chkk Operator to establish a secure connection without interference, please configure Squid Proxy to skip the SSL Bump. This will allow Chkk Operator to use its own certificates.

If this does not resolve the issue, please contact your internal network/security team to confirm whether SSL Bump is still affecting .chkk.io traffic, and reach out to support@chkk.io for further assistance.

12. How do I override default container images during cluster onboarding?

Answer: Both the Chkk Operator and the ChkkAgent Custom Resource Definition (CRD) support overriding default container images.

Default Images:

Chkk Operator: public.ecr.aws/chkk/operator:<VERSION>
ChkkAgent:
- Agent Manager: public.ecr.aws/chkk/cluster-agent-manager:<VERSION>
- Agent: public.ecr.aws/chkk/cluster-agent:<VERSION>

1

1. Create the namespace

kubectl create ns chkk-system

2

2. Add the Chkk Helm repository

helm repo add chkk https://helm.chkk.io
helm repo update chkk

3

3. Install the Chkk Operator with a custom image

helm install chkk-operator chkk/chkk-operator \
  --namespace chkk-system \
  --set secret.create=true \
  --set secret.chkkAccessToken=<ACCESS-TOKEN> \
  --set image.repository=<REPOSITORY_URL> \
  --set image.tag=<TAG>

4

4. Create a ChkkAgent resource with custom images

kubectl apply -f - <<EOF
apiVersion: k8s.chkk.io/v1beta1
kind: ChkkAgent
metadata:
  name: chkk-agent
  namespace: chkk-system
spec:
  agentOverride:
    image:
      name: <AGENT_IMAGE_URL>
    managerImage:
      name: <AGENT_MANAGER_IMAGE_URL>
EOF

13. How do I activate a cluster that was previously deactivated?

Getting Started

Use Cases & Insights

Covered Add-ons

Product Details

Security & Trust

Resources