Documentation forSecurity Event Manager

Configure the Kube API reader connection settings

To connect to the Kubernetes API, provide the connection and authentication properties to the reader. There are different approaches available, which are explained in this section.

The following matrix provides an overview of the methods that work for each corresponding agent/manager deployment.

Deployment vs connection method support

Connector configuration Auto configuration Local Proxy Service Account

SEM agent is managed by Kubernetes.

The agent is deployed as a pod, similar to being part of the Daemon Set

 Yes No Yes

SEM agent is not managed by Kubernetes.

The agent is installed with sudo on the kube control plane/node machine directly using the standard installer.

Requires one of the following methods:

  • Copying the proper kube configuration file to the following location:

    $HOME/.kube/config

  • Configuring the env variable.

$HOME is the home of a user running the agent process--in this case, /root.

Yes

Requires running kubectl proxy on the kube machine

 Yes

SEM agent is installed outside of the Kubernetes cluster/nodes.

The Kubernetes API is remotely accessible for this machine (similar to the remote kubectl proxy)

Requires one of the following methods:

  • Copying the proper kube configuration file to the following location:

    $HOME/.kube/config

  • Configuring the env variable.

$HOME is the home of a user running the agent process.

Yes

Requires running kubectl proxy on the local machine

 Yes
Manager outside of the Kubernetes cluster. The Kubernetes API is remotely accessible to the manager. No No Yes

Agent inside the cluster

You can implement this connection using one of the following methods:

Auto-configuration

Using the auto-configuration method, you are not required to specify any additional connection parameters because they can be auto-discovered.

Auto-configuration uses the settings from different sources on the machine in the following order of priority:

  1. System properties or environment variables (useful to override config).

  2. Kube config file.

    By default, this file is located on the FS at ~/.kube/config. Resources including certificates, urls, and so on are configured based on the file contents.

  3. Service account token and mounted CA certificate (located on the FS).

    The following rules apply:

    • If the agent is running from a Pod environment, additional settings are not required. Kubernetes will set all resources to their proper locations.

    • By default, the token file is expected at /var/run/secrets/kubernetes.io/serviceaccount/token

    • By default, the CA certificate is expected at /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

    • The host and port must be set as env variables unless the API is accessible through kubernetes.default.svc.

      Optionally, you can set KUBERNETES_MASTER as a whole master URL. See the table with all properties.

      • KUBERNETES_SERVICE_HOST (without https)

      • KUBERNETES_SERVICE_PORT (can be left unset and will default to 443)

Overridable auto-configuration properties

You can define or override the env/system properties on the machine hosting the SEM agent to enable auto-configuration or adjust its behavior.

Property / Env variable Description Default value
kubernetes.master /
KUBERNETES_MASTER 		Kubernetes master URL https://kubernetes.default.svc

kubernetes.api.version /

KUBERNETES_API_VERSION

API version v1
kubernetes.trust.certificates /

KUBERNETES_TRUST_CERTIFICATES 		Trust all certificates false
kubernetes.disable.hostname.verification /

KUBERNETES_DISABLE_HOSTNAME_VERIFICATION 		  false
kubernetes.certs.ca.file /

KUBERNETES_CERTS_CA_FILE 		   
kubernetes.certs.ca.data /

KUBERNETES_CERTS_CA_DATA 		   
kubernetes.certs.client.file /

KUBERNETES_CERTS_CLIENT_FILE 		   
kubernetes.certs.client.data /

KUBERNETES_CERTS_CLIENT_DATA 		   
kubernetes.certs.client.key.file /

KUBERNETES_CERTS_CLIENT_KEY_FILE 		   
kubernetes.certs.client.key.data /

KUBERNETES_CERTS_CLIENT_KEY_DATA 		   
kubernetes.certs.client.key.algo /

KUBERNETES_CERTS_CLIENT_KEY_ALGO 		Client key encryption algorithm RSA
kubernetes.certs.client.key.passphrase / KUBERNETES_CERTS_CLIENT_KEY_PASSPHRASE    
kubernetes.auth.serviceAccount.token / KUBERNETES_AUTH_SERVICEACCOUNT_TOKEN Name of the service account token file /var/run/secrets/kubernetes.io/

serviceaccount/token
kubernetes.auth.tryKubeConfig /

KUBERNETES_AUTH_TRYKUBECONFIG 		Configure client using Kubernetes config true
kubeconfig / KUBECONFIG Name of the Kubernetes config file to read ~/.kube/config
kubernetes.auth.tryServiceAccount /

KUBERNETES_AUTH_TRYSERVICEACCOUNT 		Configure client from the Service account true
kubernetes.tryNamespacePath /

KUBERNETES_TRYNAMESPACEPATH 		Configure client namespace from Kubernetes service account namespace path true
kubernetes.auth.token /

KUBERNETES_AUTH_TOKEN 		   
KUBERNETES_SERVICE_HOST Master URL host (used when configuring for SA) where the Kubernetes API is reachable kubernetes.default.svc
KUBERNETES_SERVICE_PORT Master URL port (used when configuring for SA) where Kubernetes API is reachable  

Override env variables for the Linux agent service

SEM runs the Linux agent as a systemd service. Exporting system properties through the current bash shell will not work. Instead, use the systemd service drop-in.

The solution is to use the standalone environment file that is loaded by means of EnvironmentFile. This approach is more secure and prevents the values from being shown by means of the systemctl show service. Additionally, this approach is cleaner if you need to define multiple variables.

mkdir -p /etc/swlem-agent
# create your environmental file in a proper location"
# put all of your variables on a separate line, like this:
# MY_SECRET=mypassword
nano /etc/swlem-agent/swlem-agent.conf
# create the drop-in dir
sudo mkdir -p /etc/systemd/system/swlem-agent.service.d
# create the drop-in with EnvironmentFile override
{ echo "[Service]";
echo "EnvironmentFile=/etc/swlem-agent/swlem-agent.conf";
} | tee /etc/systemd/system/swlem-agent.service.d/override.conf
# reload unit files
systemctl daemon-reload
# restart the agent service for new options to take effect
systemctl restart swlem-agent.service

Afterwards, you can modify the variables in the /etc/swlem-agent/swlem-agent.conf file and then restart the agent service for them to take effect.

Another solution is to pass properties directly by means of Environment if the standalone env file should be omitted: 

# create the drop-in dir
sudo mkdir -p /etc/systemd/system/swlem-agent.service.d
# create the drop-in with kube config location override
{ echo "[Service]";
echo "Environment=\"KUBECONFIG=/home/kube/.kube/config\"";
} | tee /etc/systemd/system/swlem-agent.service.d/override.conf
# reload unit files
systemctl daemon-reload
# restart the agent service for new options to take effect
systemctl restart swlem-agent.service

However, this approach is not as flexible as the first approach.

Local proxy (localhost only)

The kubectl proxy command creates a proxy server (or an application-level gateway) between localhost and the Kubernetes API server. The kubectl proxy offloads the mutual client-server authentication responsibility from the caller. Since the communication between the caller and the proxy occurs over the localhost, it is considered secure.

The proxy takes care of the client-server authentication using the information from the current context selected in the kube config file. This approach greatly simplifies API access.

The connector fields include the proxy port [Integer]—the HTTP port where the kubectl proxy is listening.

Agent or manager is outside of the cluster

The following methods require manual connection and authentication inputs to the reader by the user.

Service Account (SA) token authentication

The SA token is issued by Kubernetes and acts a client secret during authentication and authorization. The CA certificate is used to verify the server identity by the client.

See Service Accounts located on the Kubernetes website for more information.

The following table lists the connector fields.

Field Description Description
Master URL [String]

The API URL used for the connection

Can be received with the following command:

kubectl config view -o jsonpath='{"Cluster name\tServer\n"}{range .clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'

SA token [String] Service account bearer token

Can be received with command:

kubectl get secret/sem-sa-secret -o jsonpath='{.data.token}' | base64 --decode

where sem-sa-secret is the name of the secret
CA certificate [String] Base64 encoded contents of the server CA certificate in PEM format

Can be received with command:

kubectl get secret/sem-sa-secret -o jsonpath='{.data.ca\.crt}'

where sem-sa-secret is the name of the secret