Onboarding Kubernetes Clusters
You can onboard a Kubernetes Kubernetes, often abbreviated as “K8s”, orchestrates containerized applications to run on a cluster of hosts. cluster to CloudGuard. On the process completion, you can see clusters, nodes, pods, and other resources on the CloudGuard Assets page. Then you can run compliance assessments on them and use the data for more security functionality, such as Runtime Protection, Image Assurance, etc.
The cluster can be on an on-premises host or in a cloud environment with managed Kubernetes environments such as AKS on Azure Collection of integrated cloud services that developers and IT professionals use to build, deploy, and manage applications through a global network of data centers managed by Microsoft®., EKS
Amazon Elastic Kubernetes Service (Amazon EKS) is a managed Kubernetes service that makes it easy for you to run Kubernetes on AWS and on-premises. on AWS
Amazon® Web Services. Public cloud platform that offers global compute, storage, database, application and other cloud services., and GKE on GCP
Google® Cloud Platform - a suite of cloud computing services that runs on the same infrastructure that Google uses internally for its end-user products, such as Google Search, Gmail, Google Drive, and YouTube. Cloud.
As part of the onboarding process, CloudGuard agents are deployed on the cluster. The CloudGuard agents send encrypted information back to the CloudGuard server over the Internet.
For information on Kubernetes versions and container requirements, see Kubernetes Containers.
Onboarding a Cluster Manually
Follow the steps below to manually onboard a Kubernetes cluster to CloudGuard:

-
In the CloudGuard portal, open Assets > Environments.
-
For first-time onboarding, click Kubernetes. The first window of the wizard to onboard a Kubernetes cluster opens.
Or, from the top right, select Add New > Kubernetes / OpenShift / Tanzu.
-
Enter a name for the cluster. This is the name that appears in CloudGuard.
-
Follow the on-screen instructions to complete these steps:
-
Configure a Service Account by one of these methods:
-
Select an existing Service Account with its corresponding API Key.
-
Enter a Service Account manually.
-
Click Add Service Account to create a new account.
-
-
Enter a name for the Kubernetes namespace in which the agent is to be deployed or keep the default name - checkpoint.
-
Select what type of monitoring and security checks are necessary for your Kubernetes cluster by default. You can add each of these features later. Read more about each feature on a dedicated page:
-
Posture Management - for details, see Posture Management (mandatory feature)
-
Image Assurance - for details, see Image Assurance
-
Admission Control - for details, see Admission Control
-
Runtime Protection - for details, see Kubernetes Runtime Protection
-
Threat Intelligence - for details, see Intelligence
-
-
-
Click Next to continue to the next step.

-
Select the Organizational Units with which the onboarded cluster will be associated. If no Org Unit is selected, the root (top-level) unit is used.
-
Click Next.

-
Follow the onscreen instructions and apply Helm
A Kubernetes deployment tool for automating creation, packaging, configuration, and deployment of applications and services to Kubernetes clusters.. As an alternative, you can follow the Non-Helm instructions to deploy the agents. This generates a YAML file for deployment with
kubectl
commands. -
Click Next.

-
Verify the deployment status. The status is dynamically updated as the agents come online.
-
Your Kubernetes cluster has been successfully created
-
It is waiting for the agent to start communication
-
You can skip the validation by clicking the Finish button
-
Wait for the deployment completion based on the Cluster and Agent Status or click Finish to skip the process.
CloudGuard informs you that:
After the agent is deployed, CloudGuard accesses the cluster through the agent to get information about the assets and synchronize with it. This takes several minutes based on the time needed to download the images to the cluster and the number of assets in the cluster.
The Onboarding Summary page is updated automatically with the change of the cluster status.
Cluster Status
Available options of the cluster status:
-
Pending - CloudGuard has not received communication from the agents.
-
Initializing - CloudGuard is receiving communication from some of the agents. The progress bar shows how many agents are up and ready.
Note - During this state, if the number of running pods does not change for 10 minutes, the indicator pauses and the status changes to TIME OUT. In this case, verify the agents status on the cluster to make sure they do not have issues. For example, agents can be stuck because of missing resources (memory or CPU). After you solve the issue, you can continue the validation or skip the validation process entirely.
-
Error - There are agents in the Error state. Click Finish to complete the process. You can go to the cluster page to see which agents have the Error state and browse their Kubernetes logs for issues.
When all the agents are running, the cluster status changes to SUCCESS, and the onboarding process finishes successfully.
Agent Status
On the cluster page, for each feature, you can see its agents status:
-
Pending - The agent has never communicated with CloudGuard.
Note - There is a limitation for DaemonSet agents. During the cluster status calculation, tolerations settings are not taken into account. Agents from excluded nodes are considered Pending which can cause a false error state for the cluster.
-
Initializing - Status of an agent that comes online and initiates communication with the CloudGuard portal. The agent has a small period of time to report a successful self-test. If the agent does not report it back in time, the status is changed to Error because of a timeout.
-
Warning - Status of an agent that successfully finished its initialization, while it is based on an old image. See Upgrading the Agent for how to fix this issue.
-
Error – Status of agents that failed their self-test, sent an error message, or suffered a loss of connectivity for a minimum of one hour.
-
Pending cleanup - Disabled features that still have an agent which sends data to appear with the Pending cleanup status.
Onboarding a Cluster with Automation
Follow these steps to automate the onboarding process from the command line:
-
Create or update these environmental variables: $API_KEY, $API_SECRET, $CLUSTER_NAME, where the API Key and Secret are generated on the CloudGuard portal (see V2 API).
-
Run this command to create a Kubernetes account on CloudGuard:
curl -s -X POST https://api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{\"name\" : \"$CLUSTER_NAME\"}" --user $API_KEY:$API_SECRET)
Note - This and other commands below use
api.us1.cgn.portal.checkpoint.com
as an API endpoint for Infinity Portal users in the US region. For the full list of the API server endpoints in your region, see Question: Which CloudGuard endpoints do I have to allow on my network?. -
Extract the Cluster ID from the response:
CLUSTER_ID=$(echo $CREATION_RESPONSE | jq -r '.id')
-
Enable the required features:
Copycurl -X POST https://api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/imageAssurance/enable --user $API_KEY:$API_SECRET
curl -X POST https://api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/admissionControl/enable --user $API_KEY:$API_SECRET
curl -X POST https://api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/runtimeProtection/enable --user $API_KEY:$API_SECRET -
Run these commands on each cluster:
Copyhelm install asset-mgmt cloudguard --repo https://raw.githubusercontent.com/CheckPointSW/charts/master/repository/ --set-string credentials.user=$API_KEY --set-string credentials.secret=$API_SECRET --set-string clusterID=$CLUSTER_ID --set addons.imageScan.enabled={true|false} --set addons.admissionControl.enabled={true|false} --set addons.runtimeProtection.enabled={true|false} --namespace $NAMESPACE
You can set the
*.enabled
flags tofalse
or omit it if it is not necessary to enable the corresponding features.
For Non-Helm automation, run this command in step 5:
kubectl run cloudguard-install --rm --image alpine/helm --tty --stdin --quiet --restart=Never --command – helm template asset-mgmt cloudguard --repo https://raw.githubusercontent.com/CheckPointSW/charts/master/repository/ --set credentials.user=$API_KEY --set credentials.secret=$API_SECRET --set clusterID=$CLUSTER_ID --set addons.imageScan.enabled={true|false} --set addons.admissionControl.enabled={true|false} --set addons.runtimeProtection.enabled={true|false} --namespace $NAMESPACE --set containerRuntime=containerd --kube-version <KUBERNETES-VERSION> > cloudguard-install.yaml
kubectl apply -f cloudguard-install.yaml
-
If your cluster uses a Docker
Docker (specifically, Docker Engine) is a software technology providing operating-system-level virtualization also known as containers. or CRI-O
A tool that lets you use OCI container runtimes with Kubernetes CRI. CRI-O is an implementation of the Container runtime interface (CRI) to enable using container runtimes that are compatible with the Open Container Initiative (OCI) runtime spec. runtime environment, change the
containerRuntime
flag to:--set containerRuntime=docker
or--set containerRuntime=cri-o
-
If your cluster platform is OpenShift 4+, Amazon EKS, or Tanzu, before output redirection, add:
--set platform=openshift
or --set platform=eks or--set platform=tanzu
-
With the
kube-version
flag, set the Kubernetes version of your cluster, for example, for version 1.25, set:--kube-version 1.25
Example

#!/bin/bash
# Create environmental variables for the API Key, API Secret, and Cluster name.
export API_KEY=372e5df3-db03-432d-bf46-cb4261efb317
export API_SECRET=on3cs1ambgv4tnbs6kiwb1ws
export CLUSTER_NAME=auto-cluster
export NAMESPACE=checkpoint
export IMAGE_SCAN_ENABLED=true
export ADMISSION_CONTROL_ENABLED=true
export RUNTIME_PROTECTION_ENABLED=true
# Onboard the cluster
export CREATION_RESPONSE=$(curl -s -X POST https:// api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/ --header 'Content-Type: application/json' --header 'Accept: application/json' \-d "{\"name\" : \"$CLUSTER_NAME\"}" --user $API_KEY:$API_SECRET)
export CLUSTER_ID=$(echo $CREATION_RESPONSE | jq -r '.id')
curl -X POST https:// api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/imageAssurance/enable --user $API_KEY:$API_SECRET
curl -X POST https:// api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/admissionControl/enable --user $API_KEY:$API_SECRET
curl -X POST https:// api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account/$CLUSTER_ID/runtimeProtection/enable --user $API_KEY:$API_SECRET
# If the designated namespace already exists, comment out the following line
kubectl create namespace $NAMESPACE
# Deploy the Asset Management agent on the cluster using Helm
export NAMESPACE=checkpoint
helm install asset-mgmt cloudguard --repo https://raw.githubusercontent.com/CheckPointSW/charts/master/repository/ --set-string credentials.user=$API_KEY --set-string credentials.secret=$API_SECRET --set-string clusterID=$CLUSTER_ID --set addons.imageScan.enabled=$IMAGE_SCAN_ENABLED --set addons.admissionControl.enabled=$ADMISSION_CONTROL_ENABLED --set addons.runtimeProtection.enabled=$RUNTIME_PROTECTION_ENABLED --namespace $NAMESPACE
# Check the status of the cluster
curl -s https:// api.us1.cgn.portal.checkpoint.com/v2/kubernetes/account//$CLUSTER_ID/AccountSummary --user $API_KEY:$API_SECRET
|
Note - This example shows |
Upgrading the Agent
Agreed assumptions:
-
The environmental variables $API_KEY, $API_SECRET, $CLUSTER_NAME, $NAMESPACE have the same values as during onboarding
-
Image Assurance and Admission Control are enabled
For agents installed with Helm 3, use the command below to upgrade all agents to the latest version:
helm upgrade asset-mgmt cloudguard --repo https://raw.githubusercontent.com/CheckPointSW/charts/master/repository/ --set-string credentials.user=$API_KEY --set-string credentials.secret=$API_SECRET --set-string clusterID=$CLUSTER_ID --set addons.imageScan.enabled={true|false} --set addons.admissionControl.enabled={true|false} --set addons.runtimeProtection.enabled={true|false} --namespace $NAMESPACE
Uninstalling the Agent
During the process of onboarding, CloudGuard generates the cloudguard-install.yaml file that you use to uninstall the agents.
With Helm:
|
With kubectl:
|
|
Note - To install agents again after you have uninstalled them, follow STEP 3 - Deploy the agent on the cluster and not the upgrade procedure. |