Agent Install: Kubernetes

The recommended method to monitor Kubernetes environments is to deploy the Sysdig agent using the helm chart. Alternatively, you can install the agent container using DaemonSet. This section helps you install the agent in both the methods.

Installing the agent using helm or as a daemonSet will deploy agent containers on every node in your Kubernetes environment. Once the agent is installed, Sysdig Monitor automatically begins monitoring all of your hosts, apps, pods, and services and automatically connects to the Kubernetes API server to pull relevant metadata about the environment. If licensed, Sysdig Secure launches with default policies that you can view and configure to suit your needs. You can access the front-end web interfaces for Sysdig Monitor and Sysdig Secure immediately.

Sysdig supports monitoring numerous Kubernetes platforms, including the following:

Prerequisites

  • A supported distribution: See Agent Installation Requirements for details.

  • Kubernetes v1.9+: The agent installation on Kubernetes requires v1.9 or higher because the APIs used to fetch kubernetes metadata are only present in v1.9+.

  • Sysdig account and access key: Request a trial or full account at Sysdig.com and click the Activate Account button. The Getting Started Wizard provides an access key.

  • Port 6443 open for outbound traffic: The agent communicates with the collector on port 6443. If you are using a firewall, you must open port 6443 for outbound traffic for the agent.

  • Kernel headers installed: If a prebuilt kernel probe is not available for your kernel, the kernel headers must be installed in order to build the kernel probe.

  • kubectl installed: All of the installation methods utilize kubectl to install the agent in the cluster.

Kernel Headers

The Sysdig agent requires kernel header files to install successfully on a Kubernetes cluster. If the hosts in your environment match the pre-compiled kernel modules available from Sysdig, no special action is required.

In some cases, the nodes in your Kubernetes environment might use Unix versions that do not match the provided headers, and the agent might fail to install correctly. In those cases, you must install the kernel headers manually on each node.

To do so:

For Debian-style distributions, run the command:

apt-get -y install linux-headers-$(uname -r)

For RHEL-style distributions, run the command:

yum -y install kernel-devel-$(uname -r)

For more information on troubleshooting, see About Kernel Headers and the Kernel Module.

Kubernetes Environments

Some Kubernetes environments require special configuration options to deploy the agent. If you’re installing in one of the following environments, follow the guides specific to those environments to deploy the agent. Otherwise, continue with this topic.

Installation

Helm

Sysdig recommends using helm charts to install Sysdig agent in Kubernetes environments. For the latest chart and installation instructions, see sysdig-deploy.

Script

Sysdig also provides a script that you can use to install the agent as a DaemonSet.

Installation

  1. Download the script and make it executable.

     wget https://download.sysdig.com/stable/install-agent-kubernetes
     chmod +x install-agent-kubernetes
    
  2. Run the script to install the agent as a DaemonSet.

    ./install-agent-kubernetes -a <ACCESS_KEY> -c <COLLECTOR_URL> -cn <CLUSTER_NAME>
    

Options

Option

Description

-a

The agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.

-t

The list of tags to identify the host where the agent is installed. For example: role:webserver, location:europe, role:webserver.

-c

The collector URL for Sysdig Monitor or Sysdig Secure. This value is region-dependent in SaaS and is auto-completed on the Get Started page in the UI. It is a custom value in on-prem installations.

-cp

The collector port. The default is 6443.

-cn

If a value is provided, the cluster will be identified with the name provided

-s

Use a secure SSL/TLS connection to send metrics to the collector. This option is enabled by default.

-cc

Enable strong SSL certificate check. The default is true.

-ns

If a value is provided, the agent will be deployed to the specified namespace/project. The default is sysdig-agent.

-op

If provided, perform the agent installation using the OpenShift command line.

-ac

If a value is provided, the additional configuration will be appended to the agent configuration file.

-av

If a version is provided, use the specified agent version. The default is the latest version.

-r

If a value is provided, the daemonset, configmap, cluster role binding, service acccount and secret associated with the Sysdig Agent will be removed from the specified namespace.

-ae

The api_endpoint is the region-dependent domain for the Sysdig product, without the protocol. E.g. secure.sysdig.com, us2.app.sysdig.com, eu1.app.sysdig.com

-h

Print this usage and exit.

Sysdig Secure Only

-na

If provided, will install the Node Analyzer tools. It is an error to set both -ia and -na.

-ds

The docker socket for Image Analyzer.

-cs

The CRI socket for Image Analyzer.

-cv

The custom volume for Image Analyzer.

-h

Print this usage and exit.

-b

Required in AWS Bottlerocket nodes to determine whether the eBPF should be built. Alternatively, you can use `--bpf`.

Sysdig Secure Only (Legacy)

These values apply to the Node Image Analyzer (v1) in Sysdig Secure.

-am

The Analysis Manager endpoint for Sysdig Secure.

-ia

If provided, will install the Node Image Analyzer (v1). It is an error to set both -ia and -na. The v1 Node Image Analyzer will be deprecated and replaced by the NA tools.

Manifests

To deploy agents using Kubernetes manifests, you can download manifest files, edit them as required, and deploy them using kubectl.

  1. Download the sample files:

    • sysdig-agent-clusterrole.yaml

    • sysdig-agent-daemonset-v2.yaml

    • sysdig-agent-configmap.yaml

    • sysdig-agent-service.yaml

  2. Create a namespace for the Sysdig agent.

    Note: You can use whatever name you prefer. This example uses sysdig-agent for both the namespace and the service account. The default service account name was automatically defined in sysdig-agent-daemonset-v2.yaml, at the line: serviceAccount: sysdig-agent

    kubectl create ns sysdig-agent
    
  3. Create a secret key:

    kubectl create secret generic sysdig-agent --from-literal=access-key=<your sysdig access key> -n sysdig-agent
    
  4. Create a cluster role and service account, and define the cluster role binding that grants the Sysdig agent rules in the cluster role:

    kubectl apply -f sysdig-agent-clusterrole.yaml -n sysdig-agent
    kubectl create serviceaccount sysdig-agent -n sysdig-agent
    kubectl create clusterrolebinding sysdig-agent --clusterrole=sysdig-agent --serviceaccount=sysdig-agent:sysdig-agent
    
  5. Edit sysdig-agent-configmap.yaml to add the collector address , port , and the SSL/TLS information:

    collector:
    collector_port:
    ssl: #true or false
    check_certificate: #true or false
    
    • For SaaS, find the collector address for your region.

    • For On-prem, enter the collector endpoint defined in your environment.

    • check_certificate should be set to false if a self-signed certificate or private, and a CA-signed cert is used. See Set Up SSL Connectivity to the Backend for more information.

  6. Apply the sysdig-agent-configmap.yaml file:

    kubectl apply -f sysdig-agent-configmap.yaml -n sysdig-agent
    
  7. Apply the sysdig-agent-service.yaml file:

    kubectl apply -f sysdig-agent-service.yaml -n sysdig-agent
    

    This allows the agent to receive Kubernetes audit events from the Kubernetes API server. See Kubernetes Audit Logging for information on enabling Kubernetes audit logging.

  8. Apply the daemonset-v2.yaml file :

    kubectl apply -f sysdig-agent-daemonset-v2.yaml -n sysdig-agent
    

Additional Options

Verify Metrics in Sysdig Monitor

Log in to Sysdig Monitor to verify that the agent deployed and the metrics are detected and collected appropriately.

The steps below give one way to do the check.

  1. Access Sysdig Monitor:

    SaaS: See SaaS Regions and IP Ranges and identify the correct domain URL associated with your Sysdig application and region. For example, for US East, the URL is https://app.sysdigcloud.com.

    For other regions, the format is https://<region>.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com.

    Log in with your Sysdig user name and password.

  2. Select the Explore tab to see if metrics are displayed.

  3. Determine the Kube State Metrics you want to collect.

  4. To verify that kube state metrics and cluster name are working correctly, select the Explore tab and see if your cluster is listed.

Kubernetes metadata (pods, deployments etc.) appear a minute or two later than the nodes/containers themselves; if pod names do not appear immediately, wait and retry the Explore view.

If agents are disconnecting, there could be an issue with your MAC addresses. See Troubleshooting Agent Installation for tips.

Connect to the Sysdig Backend via Static IPs (SaaS only)

Sysdig provides a list of static IP addresses that can be whitelisted in a Sysdig environment, allowing users to establish a network connection to the Sysdig backend without opening complete network connectivity. This is done by setting the Collector IP to collector-static.sysdigcloud.com.

The sysdig-agent-configmap.yaml file can be edited either locally or using the edit command in Kubernetes.

To configure the collector IP in a Kubernetes SaaS instance:

  1. Open sysdig-agent-configmap.yaml in a text editor.

  2. Uncomment the following lines:

    • collector:

    • collector_port

  3. Set the collector: value to collector-static.sysdigcloud.com

  4. Set the collector_port: value to 6443

  5. Save the file.

The example file below shows how the sysdig-agent-configmap.yaml file should look after configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: sysdig-agent
data:
  dragent.yaml: |
    ### Agent tags
    # tags: linux:ubuntu,dept:dev,local:nyc

    #### Sysdig Software related config ####

    # Sysdig collector address
    collector: collector-static.sysdigcloud.com

    # Collector TCP port
    collector_port: 6443

    # Whether collector accepts ssl/TLS
    ssl: true

    # collector certificate validation
    ssl_verify_certificate: true

    # Sysdig Secure
    security:
      enabled: true

    #######################################
    # new_k8s: true
    # k8s_cluster_name: production


Last modified September 23, 2022