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:

STEP 1 - Configuration

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 menu, select Add > 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 Cloud Security Posture Management (CSPM) (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 for Kubernetes Containers
Click Next to continue to the next step.

STEP 4 - Onboarding Summary

Verify the deployment status. The status is dynamically updated as the agents come online.

CloudGuard informs you that:

Your Kubernetes cluster has been successfully created.
It is waiting for the agent to start communication.
You can skip the validation if you click the Finish button.

Wait for the deployment completion based on the Cluster and Agent Status or click Finish to skip the process.

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 resolve 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 the status of its agents:

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 considered. 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 to report a successful self-test. If the agent does not report it back on 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 resolve this issue.
Error – Status of agents that
- failed their self-test
- sent an error message
- suffered a loss of connectivity for a minimum of one hour
- have the version below the minimal version
Pending cleanup - Disabled features that still have an agent that sends data to appear with the Pending cleanup status.

Onboarding a Cluster with Automation

Automation with the CLI

For the onboarding automation, you need a CloudGuard service account with onboarding permissions, so the service account must have a role with the Manage Resources Permissions (or, at least, the Onboarding Permissions).

Follow these steps to automate the onboarding process from the command line:

With the above-mentioned service account, 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 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:

Copy

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

Inactive Kubernetes Clusters

CloudGuard deletes inactive environments when a year (365 days) passed since any of the environment's agents has communicated with CloudGuard. An agent is required to communicate with CloudGuard at least once in the past.

Note - Environments with agents that communicated with errors are not removed.

Installing the Agent

During the onboarding process, you install the CloudGuard agent on the cluster with Helm. For the agent installation, permissions of the preconfigured Kubernetes Agent role are sufficient (see Roles). The Helm command is shown on the third page of the onboarding wizard; see STEP 3 - Deploy the agent on the cluster.

Example:

Copy

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={true|false} --set addons.admissionControl.enabled={true|false} --set addons.runtimeProtection.enabled={true|false} --namespace $NAMESPACE

You can set the *.enabled flags to false or omit them if it is not necessary to enable the corresponding features.

If you do not have Helm installed in your environment, use the command below to generate a YAML file for the agent installation with kubectl.

Copy

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

Installation with a Values File

You can use a YAML file as an alternative or in addition to the --set command line parameters during the Helm chart installation. Use the --values <file> or -f <file> flags in the Helm installation command. This is helpful when you have many changes to the default installation parameters or when it is necessary to specify complex or nested values.

See the default file format in CloudGuard repo, as well as the description of the configurable values.

Example

This values file with clusterId and credentials (userId, secretKey) enables the imageScan and flowLogs features on the cluster and requests a custom configuration of compute resources for the daemon.

Copy

## Check Point CloudGuard  cluster ID
## Example: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
clusterID: clusterId

## CloudGuard datacenter: usea1 [default], euwe1, apso1 etc.
datacenter: usea1

## Check Point CloudGuard Credentials
## Example
## API Secret: "abcdefghijklmnopqrstvuwxyz"
## API ID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
credentials:
  secret: secretKey
  user: userId
  
addons:
  imageScan:
    enabled: true
  flowLogs:
    enabled: true
    daemon:
      resources:
        requests:
          cpu: 200m
          memory: 60Mi
        limits:
          cpu: 400m
          memory: 200Mi
  admissionControl:
    enabled: false
  runtimeProtection:
    enabled: false

Run this command:

helm install asset-mgmt cloudguard --repo https://raw.githubusercontent.com/CheckPointSW/charts/master/repository/ -f values.yaml --namespace $NAMESPACE

Heterogeneous Node Pools

When a cluster contains multiple node pools with different configurations, it is sometimes necessary to configure the CloudGuard agent differently for each node pool. For example, one node pool can have small nodes (for example, four CPUs per node), while another can have very big nodes (32 CPUs per node). In such a cluster, it is practical to adjust the configuration of the CloudGuard agent's DaemonSets DaemonSet ensures a copy of a Pod is running across a set of nodes in a cluster. Used to deploy system daemons such as log collectors and monitoring agents that typically must run on every Node. for each node pool. Below are some examples of when different DaemonSets configurations in different node pools are beneficial:

Different resource allocation (for example, allocate more CPU for runtime daemon on nodes with more CPUs)
Different container runtimes (for example, nodes running Docker against nodes running containerd)
Different architecture

The CloudGuard agent's Helm chart allows to set up multiple DaemonSet configurations for different node pools with the use of the daemonConfigurationOverrides property. It is available under each addons.<feature>.daemon section of the YAML file. This property is an array that specifies multiple override configurations in addition to the default configuration specified under the daemon section.

For each section of overrides, Helm creates a new DaemonSet in the cluster, with the specified configuration.

In addition:

The overrides inherit from the default daemon configuration (addons.<feature>.daemon object), and each value set on it applies likewise to the override configurations, unless explicitly changed.
The name of each configuration override must be unique (case-insensitive). Non-unique names like “configExample” and “ConfigEXAMPLE” overwrite one another.
Each configuration must have a nodeSelector field defined, otherwise, the command fails.
Make sure that the nodeSelector fields do not overlap, and a node fits only one configuration. The node that matches more than one configuration will have additional daemons.

Example

This values file enables the flowLogs feature and sets two different configurations for daemons based on the values of the nodeSizeKey custom label on the nodes.

Copy

addons:
  flowLogs:
    enabled: true
    daemonConfigurationOverrides:
      exampleConfigOneSmall:
        nodeSelector:
          nodeSizeKey: small
        resources:
          requests:
            cpu: 100m
            memory: 30Mi
          limits:
            cpu: 200m
            memory: 100Mi
      exampleConfigOneLarge:
        nodeSelector:
          nodeSizeKey: large
        resources:
          requests:
            cpu: 200m
            memory: 60Mi
          limits:
            cpu: 400m
            memory: 200Mi

Agent Version Life Cycle

Each CloudGuard agent has its recommended and/or minimal required version, which CloudGuard recommends use. New versions of the agents are released when they accumulate significant content, including new capabilities, fixed vulnerabilities, etc.

To verify the agent's version:

Select an environment and click to open its page.
In the Blades tab, expand the module's details. In the Version column, see the version number.
In the Status column, see the agent's status:
1. Warning / Agent is not up to date - The agent version is below recommended
2. Error / Agent version is not supported - The agent version is below minimal
  
  This status appears on the environment page and in the applicable API (agentSummary APIs).

When an agent accumulates significant content, CloudGuard recommends upgrading it - see Upgrading the Agent. The agent status changes from OK to Warning.

When an agent has many issues or sufficient time passes after the outdated agent status is moved to Warning, CloudGuard changes the minimal version. The agent status changes from Warning to Error.

Upgrading the Agent

Assumptions:

The environment variables $API_KEY, $API_SECRET, $CLUSTER_ID, $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 --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} --set datacenter=usea1 --namespace $NAMESPACE --create-namespace

Downgrading the Agent

If you want to use a previous version of the agent (not recommended), you can downgrade the agent with standard Helm procedures, specifying the desired Helm chart version. Use the helm rollback or helm upgrade commands.

Uninstalling the Agent

During the process of onboarding, CloudGuard generates the cloudguard-install.yaml file that you use to uninstall the agents.

With Helm:

helm uninstall asset-mgmt --namespace $NAMESPACE

With kubectl:

kubectl delete -f cloudguard-install.yaml --namespace $NAMESPACE

Note - To install agents again after you have uninstalled them, follow STEP 3 - Deploy the agent on the cluster and not the upgrade procedure.