.png?version=1&modificationDate=1571907064596&cacheVersion=1&api=v2)
| Note |
|---|
IMPORTANT UPDATE: Mend K8s Agent Docker Runtime was deprecated in Kubernetes v1.20 and is not planned to be supported in future versions. We currently support a feature used by a small subset of our customers to scan Kubernetes for vulnerabilities. This offering supports docker-engine runtime only. Therefore, it is irrelevant and cannot be used in any Kubernetes systems with version 1.20 or higher. Subsequently, Mend has decided to deprecate this feature starting August 1st, 2022. |
| Table of Contents |
|---|
Overview
Mend for Kubernetes is a designated deployment within your Kubernetes cluster used to identify security and compliance issues associated with your open-source libraries.
Downloading the Kubernetes Agent
Please contact your Mend Customer Success Manager for information on how to download the Kubernetes integration package.
Prerequisites
Docker registry
Docker client installed
A Linux installation machine or a Windows machine, with admin permissions, to build, tag, run, and push docker images
Kubernetes v1.10 to v1.18
Docker is the underlying runtime in the cluster
Helm is installed
Installing the Kubernetes Agent
Extract the integration package content to an empty directory ('WS_K8S_INSTALL_HOME'). The integration package contains the following directories:
Config
Docs
Helm-chart
ws-k8s: Docker files and artifacts to build Docker images locally
A build.sh and build.bat file can also be found within the integration package.
Update Installation Properties
Update the helm-chart/values.yaml file according to your configuration requirements.
See Properties List Table section.
Permissions
The controller requires some basic permissions in order to scan the cluster. These can be found within the Helm installation:
| Code Block |
|---|
rules:
- apiGroups: [""]
resources: ["secrets", "pods"]
verbs: ["get", "watch", "list"] |
Build Docker Images
Run the build.sh or build.bat script to build the following three Docker images required for the Mend solution:
pre-configure: Prepares the environment used by the other images (e.g. certificate file). It is required to build and run this image before building the other images.
pod-main: The main pod that will scan the cluster periodically. There will be only one deployment of this image.
pod-worker: A pod that scans an image. There will be many instances of this image.
Publish Docker Images to Registry
Tag and push the newly created Docker images to your registry:
NOTE: The registry name should match the value in the docker.registry parameter in the values.yaml file.
| Code Block |
|---|
docker tag {SHA256} {registry}/whitesource-worker:latest
docker tag 222333acd0ab myregistry.azurecr.io/whitesource-worker:19.1.1 |
| Code Block |
|---|
docker push {registry}/whitesource-worker:latest
docker push myregistry.azurecr.io/whitesource-worker:latest |
The pod-main and pod-worker images should be available in your registry.
Installing the Helm Chart
To install the initial helm chart, run the following command from the main folder:
| Code Block |
|---|
Windows
helm install whitesource-k8s .\helm-chart\ --wait
Linux
helm install whitesource-k8s ./helm-chart --wait |
Properties List Table
The following properties are stored in the Mend-runtime-configmap and should be set in the values.yaml file during the installation process.
...
Name
...
Description
...
Sample Value
...
Required
...
whitesource.url
...
URL for sending the request.
Use the 'Mend Server URL' which can be retrieved from your 'Profile' page on the 'Server URLs' panel.
...
https://saas.whitesourcesoftware.com/
...
Yes
...
whitesource.apiKey
...
Unique identifier of the organization. It can be retrieved from the admin page in your Mend account
...
1235cfnwqp8
...
Yes
...
whitesource.userKey
...
Unique identifier of user. It can be generated from the 'Profile' page in your Mend account.
NOTE: The user must be an Administrator.
...
vnp0vq4[bofhsa
...
Yes
...
Mend.productName
...
(Previously cluster.name) A product name. Appears in Mend portal with the scan results of the images retrieved from the cluster
NOTE: A 'k8s-' prefix will be added to the product name.
...
my-product-name
...
Yes
...
enforcement.enabled
...
If enabled then for each request for Create/Update of Pod/Deployment the following occurs: checks the Docker images of the request for vulnerabilities. Denies the request when any known vulnerability is found in at least one of the Docker images of the request.
Default is false.
...
false
...
Required when WebHook functionality is enabled.
...
rbac.enabled
...
True only if RBAC is enabled in cluster. Default is false.
...
true
...
Yes
...
docker.registry
...
The Docker registry where your images are saved
...
Yes
...
docker.mainPod
...
The name and version of your Mend main image. Default is 'Mend-main:<version Number>'. It is not recommended to change the value of this parameter.
...
whitesource-main:19.1.1
...
No (defaults to whitesource-main:latest)
...
docker.workerPod
...
The name and version of your Mend worker image. Default is 'Mend-worker:<version Number>'. It is not recommended to change the value of this parameter.
...
whitesource-worker:19.1.1
...
No (defaults to whitesource-worker:latest)
...
docker.pullSecret
...
The 'imagePullSecret' of the registry.
...
regcred
...
Required when the registry is private and requires 'imagePullSecret' to pull the images
...
resourcesFetcher.initialDelay
...
Delay before the resources' fetcher starts
...
1
...
Yes, default value is provided
...
resourcesFetcher.runTimer
...
A timer to run the resources fetcher each X minutes
...
60
...
Yes, default value is provided
...
workersSpawner.initialDelay
...
Delay before the works spawner starts (can use it to wait for the resources fetcher to run its first time)
...
3
...
Yes, default value is provided
...
workersSpawner.runTimer
...
A timer to run the workers spawner each X minutes
...
10
...
Yes, default value is provided
...
workersSpawner.maxCreation
...
(Previously workers.maxCreation) Max number of Mend-worker pods that can be created each time the workers-spawner runs (according to workersSpawner.runTimer).
NOTE: Higher number requires more resources (CPU/Memory/Storage) during the run.
...
3
...
Yes, default value is provided
...
workersSpawner.maxScanAttempts
...
Max number of scan attempts for each image.
May occur in case of a failed scan attempt by the Mend-worker pod.
For example, an invalid image name that can not be pulled by Docker.
...
2
...
Yes, default value is provided
...
cvesFetcher.initialDelay
...
Delay before the CVEs fetcher starts (can use it to wait for the resources fetcher and workers spawner to run its first time)
...
2
...
Yes, default value is provided
...
cvesFetcher.runTimer
...
A timer to run the CVEs fetcher each X minutes
...
60
...
Yes, default value is provided
...
tagsSync.initialDelay
...
A delay of 'X' minutes before the tags synchronization starts. May be used to specify an interval in order to allow all the related worker pods to finish scanning the images.
...
15
...
Yes, default value is provided
...
tagsSync.runTimer
...
A timer to run the tags synchronization every 'X' minutes
...
30
...
Yes, default value is provided
...
workersCleaner.initialDelay
...
The delay (in minutes) before the worker pods cleaner starts
...
60
...
Yes, default value is provided
...
workersCleaner.runTimer
...
The time (in minutes) between two sequential runs of the worker pods cleaner
...
15
...
Yes, default value is provided
...
workersCleaner.removeSucceeded
...
Delete completed worker pods with "Succeeded" status
...
false
...
No (defaults to false)
...
workersCleaner.removeFailed
...
Delete completed worker pods with "Failed" status
...
false
...
No (defaults to false)
...
debugLevel.mainPod
...
The debug level used in the main pod (image source from docker.mainPod).
NOTE: The main always starts in debug level to help identify JVM start issues if they occur, and then switches to desired log level
...
TRACE, DEBUG, INFO, WARN, ERROR
...
True, default value INFO
...
debugLevel.workerPod
...
The log level of the worker pod (image source from docker.workerPod), Unified-Agent scan (inside the worker container).
...
TRACE, DEBUG, INFO, WARN, ERROR
...
True, default value INFO
...
scanningRules
...
A list of rules, where each rule consists of three parts: ruleCompType, ruleCompName, ruleAction
...
demoPod
...
No
...
scanningRules.ruleCompType
...
The components types to which the rule should be applied (currently only one value supported).
The supported wildcard is '*'
...
Supported types list: [ pod ]
...
No
...
scanningRules.ruleCompName
...
The type of components names to which the rule should be applied for scan action.
The supported wildcard is '*'.
...
kube-proxy-*
all pods with name starting with "kube-proxy-"
...
No
...
scanningRules.ruleAction
...
Action applied by the rule
...
include, exclude
...
No
...
requests.cpu
...
If not defined, then Kubernetes will manage it. Default 512 m
...
512 m
...
No
...
requests.memory
...
If not defined, then Kubernetes will manage it. Default 1Gi.
...
1 Gi
...
No
...
limits.cpu
...
CPU limits for the main pod. If not set then Kubernetes will manage it
...
512 m
...
No
...
limits.memory
...
Memory limit for the main pod
...
1 Gi
...
No
| Info |
|---|
If a process requires 'X' minutes to finish, and you defined it to run every 'Y' minutes, then this process will run every 'Y' minutes from last execution. (fixed-delay rather than fix-rate) Example: 'workersSpawner.runTimer=3', but it takes this process 5 minutes to finish a single run. Therefore, this process will run every 8 minutes, and not every 3 minutes. |
During run-time, you can change the values by running the following command:
| Code Block |
|---|
kubectl --namespace=whitesource-namespace edit configmap whitesource-runtime-configmap
kubectl --namespace=whitesource-namespace edit configmap whitesource-global-configmap
kubectl --namespace=whitesource-namespace edit configmap whitesource-ua-configmap |
Scanning
Upon first integration, the Kubernetes agent will scan the entire cluster and detect any open-source libraries used in your cluster along with their vulnerabilities and licenses. This first scan is used as a baseline for future changes, after which the Kubernetes agent tracks changes in the cluster (for example, a new deployment or image modification) and alerts about new vulnerabilities in real-time..
Mend also scans the cluster on a periodic basis to identify vulnerabilities in resources that are already running in the cluster. The following are triggers for a scan:
Upon controller deployment, there is an initial scan to identify all vulnerable images
On each restart of the controller pods
On a periodic basis - Default is 60 minutes
Viewing Scan Results
Scan results can be viewed in the Mend UI in the Containers dashboard or in the relevant Mend Product page.
A Mend Project page will be created for each Docker image in the cluster.
Upgrading the Kubernetes Agent
First, preserve your helm installation values and database cache from the previous installation (if needed).
To preserve your helm installation values, save your values.yaml file and merge it with the newly created values.yaml file from the upgraded distribution.
To preserve the database cache for history, copy the cache from the main pod using the following command:
| Code Block |
|---|
kubectl cp whitesource-namespace/whitesource-main-54664468f-b6dwp:/K8s_info.db K8s_info.db |
...
To delete an installation, use helm delete with the installation name (Use --purge to remove any record of the installation - full uninstall).
The old Mend-main and Mend-worker Docker images must also be deleted from your Docker registry.
NOTE: You can use new Docker tags on the new Mend-main and Mend-worker Docker images instead of deleting the old images from your registry. If you use new Docker tags, make sure to update them in the values.yaml file (the docker.mainPod and docker.workerPod values).
Run the build.sh or build.bat script again to build the new Mend-main and Mend-worker Docker images.
Tag and push the new Mend-main and Mend-worker Docker images to your registry.
After deleting the installation and reinstalling, the Mend scanner will re-scan the whole cluster.
NOTE: Ensure the Mend.userKey property contains a user key with Mend admin privileges.
Support
To retrieve the database content, copy the cache DB file from the Mend-main pod to the required destination using the following command:
| Code Block |
|---|
kubectl cp whitesource-main-{unique-id}:wss_k8s_sqlite.db --namespace=whitesource-namespace {destination}
kubectl cp whitesource-main-59f766fa79-j456a7:wss_k8s_sqlite.db --namespace=whitesource-namespace/var/DB/File |
Uninstalling the Kubernetes Agent
To remove the installation, run the following commands:
...
This page is available at: https://docs.mend.io/bundle/integrations/page/getting_started_with_kubernetes.html