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

Return to the regular view of this page.

    Steps for Rancher


    General Requirements

    You can review Agent Install: Kubernetes | GKE | OpenShift | IBM and the Agent Installation Requirements for additional context, if desired.

    Kernel Headers

    The Sysdig agent requires a kernel module in order to be installed successfully on a host. On RancherOS distributions, the Unix version does not match the provided headers, and the agent might fail to install correctly. Therefore, you must install the kernel headers manually.

    For RancherOS distributions, the kernel headers are available in the form of a system service and therefore are enabled using the ros service command:

    $ sudo ros service enable kernel-headers-system-docker
    $ sudo ros service up -d kernel-headers-system-docker

    Some cloud hosting service providers supply pre-configured Linux instances with customized kernels. You may need to contact your provider’s support desk for instructions on obtaining appropriate header files, or for installing the distribution’s default kernel.

    Installation steps

    Deploy Using Helm Charts

    To deploy agent using Helm charts, run the following:

    1. Export the access token and the name of the OKE cluster:

      export SDC_ACCESS_TOKEN=xxxx # Get it from the UI (User > Settings > Sysdig Secure API Token).
      export # us-west by default. Please check the right region.
      export # us-east by default. Please check the right region.
      export CLUSTER_NAME=my-cluster # Rancher cluster name
    2. Create a namespace to use for the Sysdig agent:

       kubectl create ns sysdig-agent
    3. Set up the helm repo:

       helm repo add sysdig
       helm repo update
    4. Install the agent:

       helm install sysdig-agent --namespace sysdig-agent --set sysdig.accessKey=$SDC_ACCESS_TOKEN --set sysdig.settings.collector=$SDC_COLLECTOR_URL --set sysdig.settings.collector_port=6443 --set clusterName=$CLUSTER_NAME sysdig/sysdig --set nodeAnalyzer.apiEndpoint=$SDC_NODEANALYZER_URL

    For more information,charts.

    Deploy Using Daemonsets

    Install Agent

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

    • sysdig-agent-clusterrole.yaml

    • sysdig-agent-service.yaml

    • sysdig-agent-daemonset-v2.yaml

    • sysdig-agent-configmap.yaml

    HELM CHART OPTION Kubernetes 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 Agent

    • Download the sample files:

      • sysdig-agent-clusterrole.yaml

      • sysdig-agent-daemonset-v2.yaml

      • sysdig-agent-configmap.yaml

      • sysdig-agent-service.yaml

    • Create a namespace to use for the Sysdig agent.

      You can use whatever naming you prefer. In this document, we used 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
    • Create a secret key:

      kubectl create secret generic sysdig-agent --from-literal=access-key=<your sysdig access key> -n sysdig-agent
    • Create a cluster role and service account, and define the cluster role bindingthat grants the Sysdig agent rules in the cluster role, using the commands:

      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
    • 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
    • (All installs) Apply the sysdig-agent-configmap.yaml file:

      kubectl apply -f sysdig-agent-configmap.yaml -n sysdig-agent
    • (All installs) 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.

    • (All installs) Apply the daemonset-v2.yaml file :

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

    The agents will be deployed. 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.

    • 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.

    • 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.

    • Apply the configmap changes using the command:

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

    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:

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

    • Uncomment the following lines:

      • collector:

      • collector_port

    • Set the collector: value to

      See SaaS Regions and IP Ranges and identify the correct URL associated with your Sysdig collector and region.

    • Set the collector_port: value to 6443

    • 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

    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.

    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.

    • 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.

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

    • (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.

    • Select an individual container or pod to see details.