This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

    Steps for OpenShift

    Review the Prerequisites in Agent Install: Kubernetes | GKE | OpenShift | IBM and the Host Requirements for Agent Installation, then proceed with the installation.

    Kernel Headers

    The Sysdig agent requires kernel header files to install successfully on a host.

    This setup step is required for some environments and not others, as noted.

    If the hosts in your environment match the pre-compiled kernel modules available from Sysdig, no special action is required.

    In some cases, the host(s) in your environment may use Unix versions that do not match the provided headers, and the agent may fail to install correctly. In those cases, you must install the kernel headers manually.

    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)

    Background info: see also About Kernel Headers and the Kernel Module.

    Configure for OpenShift

    If you are using Red Hat OpenShift, these steps are required. They describe how to create a project, assign and label the node selector, create a privileged service account, and add it to a cluster role.

    Copy/Paste Sample Code Block

    In the example code, this document uses sysdig-agent for the PROJECT NAME (-n), the SERVICE ACCOUNT (-z), and the NODE SELECTOR.

    You can copy-paste the code as-is, or follow the steps below to customize your naming conventions.

    oc adm new-project sysdig-agent --node-selector='app=sysdig-agent'
    oc label node --all "app=sysdig-agent"
    oc project sysdig-agent
    oc create serviceaccount sysdig-agent
    oc adm policy add-scc-to-user privileged -n sysdig-agent -z sysdig-agent
    oc adm policy add-cluster-role-to-user cluster-reader -n sysdig-agent -z sysdig-agent

    Customize the Code

    You can use your own Project Name and Node Selector names if desired.

    Note that if you use a different Service Acccount name, you will need to edit the default service account in the Sysdig Installation Steps, below.

    1. Create a new OpenShift project for the Sysdig agent deployment and assign the node selector:

      oc adm new-project PROJECT-NAME --node-selector="app=APP-NAME"
    2. Label the node with the node selector:

      oc label node --all "app=APP-NAME"
    3. Change to the new OpenShift Project for the Sysdig agent deployment:

      oc project PROJECT-NAME
    4. Create a service account for the project:

      oc create serviceaccount SERVICE-ACCOUNT
    5. Add the service account to privileged Security Context Constraints:

      oc adm policy add-scc-to-user privileged -n PROJECT-NAME -z SERVICE-ACCOUNT
    6. Add the service account to the cluster-reader Cluster Role:

      oc adm policy add-cluster-role-to-user cluster-reader -n PROJECT-NAME -z SERVICE-ACCOUNT

    Sysdig Installation Steps

    To deploy agents using Kubernetes daemonsets, you download the configuration files, edit them as required, and deploy them.

    • sysdig-agent-daemonset-v2.yaml

    • sysdig-agent-clusterrole.yaml

    • sysdig-agent-configmap.yaml

    • sysdig-agent-service.yaml

    HELM CHART OPTIONKubernetes also offers a package manager, Helm, which uses charts to simplify this process.

    If you are using Helm charts in your K8s environment, we recommend using them to deploy Sysdig agents, as described here.

    Deploy the Agents

    1. Download the sample files:

      • sysdig-agent-daemonset-v2.yaml

      • sysdig-agent-clusterrole.yaml

      • sysdig-agent-configmap.yaml

      • sysdig-agent-service.yaml

    2. Create the sysdig-agent cluster role and assign it to the service account:

       oc apply -f sysdig-agent-clusterrole.yaml
       oc adm policy add-cluster-role-to-user sysdig-agent -n PROJECT-NAME -z SERVICE-ACCOUNT
    3. Create a secret key using the command:

      oc create secret generic sysdig-agent --from-literal=access-key=<your sysdig access key> -n sysdig-agent
    4. If you created a service account name other than sysdig-agent: Edit sysdig-agent-daemonset-v2.yamlto provide your custom value:``

      serviceAccount: sysdig-agent
    5. Edit sysdig-agent-configmap.yaml to add the collector address, port, and the SSL/TLS information:

      ssl: #true or false
      check_certificate: #true or false
    6. (All installs) Apply the sysdig-agent-configmap.yaml file using the command:

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

      oc 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. (All installs) Apply the daemonset-v2.yaml file:

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

    The agents will be deployed and you can see Getting Started with Sysdig Monitor to view some metrics in the Sysdig Monitor UI. You can make further edits to the configmap as described below.Getting Started with Sysdig Monitor

    Enable Kube State Metrics and Cluster Name

    These steps are optional but recommended.

    1. Edit sysdig-agent-configmap.yaml to uncomment the line: new_k8s: true

      This allows kube state metrics to be automatically detected, monitored, and displayed in Sysdig Monitor.

      For more information, see the Kube State Metrics entry in the Sysdig blog.

      As of agent 9.6.0, new_k8s is enabled by default.

    2. Edit sysdig-agent-configmap.yaml to uncomment the line: **k8s_cluster_name: **and add your cluster name.

      Setting cluster name here allows you to view, scope, and segment metrics in the Sysdig Monitor UI by the Kubernetes cluster.

      Note: Alternatively, if you assign a tag with “cluster” in the tag name, Sysdig Monitor will display that as the Kubernetes cluster name.

    3. Apply the configmap changes using the command:

      oc apply -f sysdig-agent-configmap.yaml -n sysdig-agent
    4. Proceed to verify the metrics in the Sysdig Monitor UI.

    There are two ways to update the agent configuration

    Option 1: Edit the files locally and apply the changes with oc apply -f:

    oc apply -f sysdig-agent-configmap.yaml -n sysdig-agent

    Option 2: Use oc edit to edit files on the fly:

    oc edit configmap sysdig-agent -n sysdig-agent

    Running agents will automatically pick the new configuration after Kubernetes pushes the changes across all the nodes in the cluster.

    Verify Metrics in Sysdig Monitor UI

    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

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

      Log in with your Sysdig user name and password.

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

    3. (Once you have enabled new_k8s:true): To verify that kube state metrics and cluster name are working correctly: Select the Explore tab and create a grouping by and

      As of agent 9.6.0, new_k8s is enabled by default.

    4. Select an individual container or pod to see details.

    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.

    Additional Options

    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

    The sysdig-agent-configmap.yaml file can be edited either locally or using the edit command in Kubernetes. refer to the section above for more information.

    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

    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
      name: sysdig-agent
      dragent.yaml: |
        ### Agent tags
        # tags: linux:ubuntu,dept:dev,local:nyc
        #### Sysdig Software related config ####
        # Sysdig collector address
        # Collector TCP port
        collector_port: 6443
        # Whether collector accepts ssl/TLS
        ssl: true
        # collector certificate validation
        ssl_verify_certificate: true
        # Sysdig Secure
          enabled: true
        # new_k8s: true
        # k8s_cluster_name: production