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

Return to the regular view of this page.

  • 1:

    Installer (Kubernetes | OpenShift)

    For v 3.6.0+, go to the GitHub repo. On-prem installation documentation is transitioning to GitHub.

    All on-premises installations and upgrades are now scheduled with and guided by Sysdig technical account managers and professional services division. See Oversight Services Now Offered for All Installs and Upgrades .

    For customers, the instructions in this section are for review purposes only.

    The Sysdig Installer tool is a binary containing a collection of scripts that help automate the on-premises deployment of the Sysdig platform (Sysdig Monitor and/or Sysdig Secure), for environments using Kubernetes or OpenShift. Use the Installer to install or upgrade your Sysdig platform. It is recommended as a replacement for the earlier Kubernetes manual installation and upgrade procedures.

    Installation Overview

    To install, you will download the installer binary and a values.yaml file, provide a few basic parameters, and launch the Installer. In a normal installation, the rest is automatically configured and deployed.

    You can perform a quick install if your environment has access to the internet, or a partial or full airgapped installation, as needed. Each is described below.

    See Frequently Used Installer Configurations to:

    • Customize or override settings

    • Use hostPath for static storage of Sysdig components

    • Use Kubernetes node labels and taints to run only Sysdig pods on selected nodes in a cluster

    Install vs Upgrade

    With Sysdig Platform 3.5.0, the installer has been simplified from previous versions. Upgrade differs from Install in that you run an installer diff to discover the differences between the old and new versions and then installer deploy for the new version.

    If you are installing the Sysdig Platform for the first time, ignore the For Upgrade Only step in the process.

    If you are upgrading, check the Upgrade notes before you begin.

    Prerequisites

    The installer must be run from a machine with kubectl/oc configured with access to the target cluster where the Sysdig platform will be installed. Note that this cluster may be different than where the Sysdig agent will be deployed.

    Requirements for Installation Machine with Internet Access

    • Network access to Kubernetes cluster

    • Network access to quay.io

    • A domain name you are in control of.

    Additional Requirements for Airgapped Environments

    • Edited values.yaml with airgap registry details updated

    • Network and authenticated access to the private registry

    Access Requirements

    • Sysdig license key (Monitor and/or Secure)

    • Quay pull secret

    Storage Requirements

    You may use dynamic or static storage on a variety of platforms to store the Sysdig platform components (stateful sets). Different configuration parameters and values are used during the install, depending on which scenario you have.

    Use Case 1: Default, undefined (AWS/GKE)

    If you will use dynamic storage on AWS or GKE and haven’t configured any storage class there yet, then the Quick Install streamlines the process for you.

    • storageclassProvisioner: Enter aws or gke. The installer will create the appropriate storage class and then use it for all the Sysdig platform stateful sets.

    • storageclassName: Leave empty.

    Use Case 2: Dynamic, predefined

    It is also possible that you are using dynamic storage but have already created storage classes there. This dynamic storage could be AWS, GKE, or any other functioning dynamic storage you use.  In this case, you would enter: 

    • storageclassProvisioner: Leave empty; anything put here would be ignored.

    • storageclassName: Provide the name of the pre-configured storage class you want to use. The installer will use this storage class for all the Sysdig platform stateful sets.

    Use Case 3: Static Storage

    In cases where dynamic storage is not available, you can use static storage for the Sysdig stateful sets. In this case, you would use:

    • storageclassProvisioner: Enter hostpath, then define the nodes for the four main Sysdig components: ElasticSearch, Cassandra, MySQL, and Postgres.storageclassProvisioner

    • See Frequently Used Installer Configurations for details.

    Quickstart Install

    This install assumes the Kubernetes cluster has network access to pull images from quay.io.

    1. Have your Sysdig Technical Account Manager download the installer binary that matches your OS from the  the sysdigcloud-kubernetes releases page.

    2. For Upgrades Only: Copy the current version of values.yaml to your working directory.]

      ./installer-image import -n sysdig --certs-directory certs -o values.yaml
      

      If you will be editing for an OpenShift installation and want to review a sample, see openshift-with-hostpath values.yaml. .

    3. Edit the following values:

      • size: Specifies the size of the cluster. Size defines CPU, Memory, Disk, and Replicas. Valid options are: small, medium and large

      • quaypullsecret: quay.io provided with your Sysdig purchase confirmation mail

      • storageClassProvisioner: Review Storage Requirements, above.

        If you have the default use case, enter aws or gke in the storageClassProvisioner field. Otherwise, refer to Use Case 2 or 3.

      • sysdig.license: Sysdig license key provided with your Sysdig purchase confirmation mail

      • sysdig.dnsname: The domain name the Sysdig APIs will be served on. Note that the master node may not be used as the DNS name when using hostNetwork mode.

      • sysdig.collector.dnsName: (OpenShift installs only) Domain name the Sysdig collector will be served on. When not configured it defaults to whatever is configured for sysdig.dnsName. Note that the master node may not be used as the DNS name when using hostNetwork mode.

      • deployment: (OpenShift installs only) Add deployment: openshift to the root of the values.yaml file.

      • sysdig.ingressNetworking: The networking construct used to expose the Sysdig API and collector.Options are:

        • hostnetwork: sets the hostnetworking in the ingress daemonset and opens host ports for api and collector. This does not create a Kubernetes service.

        • loadbalancer: creates a service of type loadbalancer and expects that your Kubernetes cluster can provision a load balancer with your cloud provider.

        • nodeport: creates a service of type nodeport.The node ports can be customized with:

          sysdig.ingressNetworkingInsecureApiNodePort

          sysdig.ingressNetworkingApiNodePort

          sysdig.ingressNetworkingCollectorNodePort

          When not configured, sysdig.ingressNetworking defaults to hostnetwork.

        If doing an airgapped install , you would also edit the following values:

      • airgapped_registry_name: The URL of the airgapped (internal) docker registry. This URL is used for installations where the Kubernetes cluster can not pull images directly from Quay

      • airgapped_repository_prefix: This defines custom repository prefix for airgapped_registry. Tags and pushes images as airgapped_registry_name/airgapped_repository_prefix/image_name:tag

      • airgapped_registry_password: The password for the configured airgapped_registry_username. Ignore this parameter if the registry does not require authentication.

      • airgapped_registry_username: The username for the configured airgapped_registry_name. Ignore this parameter if the registry does not require authentication.

    4. [For Upgrades Only:]

      [Generate and review the diff of changes the installer is about to introduce:

      ./installer diff
      

      This will generate the differences between the installed environment and the upgrade version. The changes will be displayed in your terminal.

      If you want to override a change, based on your environment’s custom settings, then contact Sysdig Support for assistance.]

    5. Run the installer:

      ./installer deploy
      
    6. See Output (below) to finish.

    Save the values.yaml file in a secure location; it will be used for future upgrades.

    There will also be a generated directory containing various Kubernetes configuration yaml files that were applied by the Installer against your cluster. It is not necessary to keep the generated directory, as the Installer can regenerate it consistently with the same values.yaml file.

    Airgapped Installation Options

    The installer can be used in airgapped environments, either with a multi-homed installation machine that has internet access, or in an environment with no internet access.

    Airgapped with Multi-Homed Installation Machine

    This assumes a private docker registry is used and the installation machine has network access to pull from quay.io and push images to the private registry.

    The Prerequisites and workflow are the same as in the Quickstart Install (above) with the following exceptions:

    • In step 2, add the airgap registry information

    • After step 3, make the installer push Sysdig images to the airgapped registry by running:

      ./installer airgap
      

      That will pull all the images into the images_archive directory as tar files and push them to the airgapped registry.

    • If you are upgrading, run the diff as directed in Step 4.

    • Run the installer:

      ./installer deploy
      

    Full Airgap Install

    This assumes a private docker registry is used and the installation machine does not have network access to pull from quay.io, but can push images to the private registry.

    In this situation, a machine with network access (called the “jump machine”) will pull an image containing a self-extracting tarball which can be copied to the installation machine.

    Access Requirements

    • Sysdig license key (Monitor and/or Secure) 

    • Quay pull secret

    • Anchore license file (if Sysdig Secure is licensed)

    Requirements for jump machine

    • Network access to quay.io

    • Docker

    • jq

    Requirements for installation machine

    • Network access to Kubernetes cluster

    • Docker

    • Network and authenticated access to the private registry

    • Edited values.yaml with airgap registry details updated

    • Host Disk Space Requirements:/tmp > 4 GB; directory from which the installer is run >8GB; and /var/lib/docker > 4GB.

      NOTE: The environment variable TMPDIR can be used to override the /tmp directory.

    Docker Log In to quay.io

    • Retrieve Quay username and password from Quay pull secret. For example:

      AUTH=$(echo <REPLACE_WITH_quaypullsecret> | base64 --decode | jq -r '.auths."quay.io".auth'| base64 --decode)
      QUAY_USERNAME=${AUTH%:*}
      QUAY_PASSWORD=${AUTH#*:}
      
    • Log in to quay.ioUse the username and password retrieved above.

      docker login -u "$QUAY_USERNAME" -p "$QUAY_PASSWORD" quay.io
      

    Workflow

    On the Jump Machine

    1. Follow the Docker Log In to quay.io steps, above.

    2. Pull the image containing the self-extracting tar:

      docker pull quay.io/sysdig/installer:-uber
      
    3. Extract the tarball:

      docker create --name uber_image quay.io/sysdig/installer:-uber
      docker cp uber_image:/sysdig_installer.tar.gz .
      docker rm uber_image
      
    4. Copy the tarball to the installation machine.

    On the Installation Machine:

    1. Copy the current version values.yaml to your working directory.

      wget https://raw.githubusercontent.com/draios/sysdigcloud-kubernetes/installer/installer/values.yaml
      
    2. Edit the following values:

      • size: Specifies the size of the cluster. Size defines CPU, Memory, Disk, and Replicas. Valid options are: small, medium and large

      • quaypullsecret: quay.io provided with your Sysdig purchase confirmation mail

      • storageClassProvisioner: Review Storage Requirements, above.

        If you have the default use case, enter aws or gke in the storageClassProvisioner field. Otherwise, refer to Use Case 2 or 3.

      • sysdig.license: Sysdig license key provided with your Sysdig purchase confirmation mail

      • sysdig.dnsname: The domain name the Sysdig APIs will be served on. Note that the master node may not be used as the DNS name when using hostNetwork mode.

      • sysdig.collector.dnsName: (OpenShift installs only) Domain name the Sysdig collector will be served on. When not configured it defaults to whatever is configured for sysdig.dnsName. Note that the master node may not be used as the DNS name when using hostNetwork mode.

      • deployment: (OpenShift installs only) Add deployment: openshift to the root of the values.yaml file.

      • sysdig.ingressNetworking: The networking construct used to expose the Sysdig API and collector.Options are:

        • hostnetwork: sets the hostnetworking in the ingress daemonset and opens host ports for api and collector. This does not create a Kubernetes service.

        • loadbalancer: creates a service of type loadbalancer and expects that your Kubernetes cluster can provision a load balancer with your cloud provider.

        • nodeport: creates a service of type nodeport.The node ports can be customized with:

          sysdig.ingressNetworkingInsecureApiNodePort

          sysdig.ingressNetworkingApiNodePort

          sysdig.ingressNetworkingCollectorNodePort

      • airgapped_registry_name: The URL of the airgapped (internal) docker registry. This URL is used for installations where the Kubernetes cluster can not pull images directly from Quay

      • airgapped_repository_prefix: This defines custom repository prefix for airgapped_registry. Tags and pushes images as airgapped_registry_name/airgapped_repository_prefix/image_name:tag

      • airgapped_registry_password: The password for the configured airgapped_registry_username. Ignore this parameter if the registry does not require authentication.

      • airgapped_registry_username: The username for the configured airgapped_registry_name. Ignore this parameter if the registry does not require authentication.

    3. Copy the tarball file to the directory where you have your values.yaml file.

    4. Run:

      installer airgap --tar-file sysdig_installer.tar.gz
      

      NOTE: This step will extract the images into the images_archive directory relative to where the installer was run and push the images to the airgapped_registry.

    5. [For Upgrades Only:]

      [Generate and review the diff of changes the installer is about to introduce:

      ./installer diff
      

      This will generate the differences between the installed environment and the upgrade version. The changes will be displayed in your terminal.

      If you want to override a change, based on your environment’s custom settings, then contact Sysdig Support for assistance.]

    6. Run the installer:

      ./installer deploy
      
    7. See Output (below) to finish.

    Save the values.yaml file in a secure location; it will be used for future upgrades.

    There will also be a generated directory containing various Kubernetes configuration yaml files that were applied by the Installer against your cluster. It is not necessary to keep the generated directory, as the Installer can regenerate it consistently with the same values.yaml file.

    Updating Vulnerability Feed in Airgapped Environments

    NOTE: Sysdig Secure users who install in an airgapped environment do not have internet access to the continuous checks of vulnerability databases that are used in image scanning. (See also: How Sysdig Image Scanning Works.)

    As of installer version 3.2.0-9, airgapped environments can also receive periodic vulnerability database updates.

    When you install with the “airgapped_” parameters enabled (see Full Airgap Install instructions), the installer will automatically push the latest vulnerability database to your environment. Follow the steps below to reinstall/refresh the vuln db, or use the script and chron job to schedule automated updates (daily, weekly, etc.).

    To automatically update the vulnerability database, you can:

    1. Download the image file quay.io/sysdig/vuln-feed-database-ubi:latest from the Sysdig registry to the jump box server and save it locally.

    2. Move the file from the jump box server to the airgapped environment (if needed)

    3. Load the image file and push it to the airgapped image registry.

    4. Restart the pod sysdigcloud-feeds-db

    5. Restart the pod feeds-api

    The following script (feeds_database_update.sh) performs the five steps:

    #!/bin/bash
    QUAY_USERNAME="<change_me>"
    QUAY_PASSWORD="<change_me>"
    
    # Download image
    docker login quay.io/sysdig -u ${QUAY_USERNAME} -p ${QUAY_PASSWORD}
    docker image pull quay.io/sysdig/vuln-feed-database-ubi:latest
    # Save image
    docker image save quay.io/sysdig/vuln-feed-database-ubi:latest -o vuln-feed-database-ubi.tar
    # Optionally move image
    mv vuln-feed-database-ubi.tar /var/shared-folder
    # Load image remotely
    ssh -t user@airgapped-host "docker image load -i /var/shared-folder/vuln-feed-database-ubi.tar"
    # Push image remotely
    ssh -t user@airgapped-host "docker tag vuln-feed-database-ubi:latest airgapped-registry/vuln-feed-database-ubi:latest"
    ssh -t user@airgapped-host "docker image push airgapped-registry/vuln-feed-database-ubi:latest"
    # Restart database pod
    ssh -t user@airgapped-host "kubectl -n sysdigcloud scale deploy sysdigcloud-feeds-db --replicas=0"
    ssh -t user@airgapped-host "kubectl -n sysdigcloud scale deploy sysdigcloud-feeds-db --replicas=1"
    # Restart feeds-api pod
    ssh -t user@airgapped-host "kubectl -n sysdigcloud scale deploy sysdigcloud-feeds-api --replicas=0"
    ssh -t user@airgapped-host "kubectl -n sysdigcloud scale deploy sysdigcloud-feeds-api --replicas=1"
    

    Schedule a chron job to run the script on a chosen schedule (e.g. every day):

    0 8 * * * feeds-database-update.sh >/dev/null 2>&1
    

    Output

    A successful installation should display output in the terminal such as:

    All Pods Ready.....Continuing
    Congratulations, your Sysdig installation was successful!
    You can now login to the UI at "https://awesome-domain.com:443" with:
    
    username: "configured-username@awesome-domain.com"
    password: "awesome-password"
    

    There will also be a generated directory containing various Kubernetes configuration yaml files which were applied by installer against your cluster. It is not necessary to keep the generated directory, as the installer can regenerate consistently with the same values.yaml file.

    Additional Installer Resources

    1 -

    Frequently Used Installer Configurations

    SMTP Configs for Email Notifications

    The available fields for SMTP configuration are documented in the configuration_parameters.md. Each includes SMTP in its name. For example:

    sysdig:
      ...
      smtpServer: smtp.sendgrid.net
      smtpServerPort: 587
      #User,Password can be empty if the server does not require authentication
      smtpUser: apikey
      smtpPassword: XY.abcdefghijk...
      smtpProtocolTLS: true
      smtpProtocolSSL: false
      #Optional Email Header
      smtpFromAddress: sysdig@mycompany.com
    

    To configure email settings to be used for a notification channel, copy the parameters and appropriate values into your values.yaml.

    Configure AWS Credentials Using the Installer

    The available fields for AWS credentials are documented in the configuration_parameters.md. They are:

    sysdig:
      accessKey: my_awesome_aws_access_key
      secretKey: my_super_secret_secret_key
    

    Use hostPath for Static Storage of Sysdig Components

    The Installer assumes the usage of a dynamic storage provider (AWS or GKE). In case these are not used in your environment, add the entries below to thevalues.yamlto configure static storage.

    Based on the size entered in the values.yaml file (small/medium/large), the Installer assumes a minimum number of replicas and nodes to be provided. You will enter the names of the nodes on which you will run the Cassandra, ElasticSearch, mySQL and Postgres components of Sysdig in the values.yaml, as in the parameters and example below.

    Parameters

    • storageClassProvisioner: hostPath.

    • sysdig.cassandra.hostPathNodes: The number of nodes configured here needs to be at minimum 1 when configured size is small, 3 when configured size is medium and 6 when configured size is large.

    • elasticsearch.hostPathNodes: The number of nodes configured here needs to be at minimum 1 when configured size is small, 3 when configured size is medium and 6 when configured size is large.

    • sysdig.mysql.hostPathNodes: When sysdig.mysqlHA is configured to true, this must be at least 3 nodes. When sysdig.mysqlHA is not configured, it should be at least 1 node.

    • sysdig.postgresql.hostPathNodes: This can be ignored if Sysdig Secure is not licensed or used in this environment. If Secure is used, then the parameter should be set to 1, regardless of the size setting

    Example

    storageClassProvisioner: hostPath
    elasticsearch:
      hostPathNodes:
        - my-cool-host1.com
        - my-cool-host2.com
        - my-cool-host3.com
        - my-cool-host4.com
        - my-cool-host5.com
        - my-cool-host6.com
    sysdig:
      cassandra:
        hostPathNodes:
          - my-cool-host1.com
          - my-cool-host2.com
          - my-cool-host3.com
          - my-cool-host4.com
          - my-cool-host5.com
          - my-cool-host6.com
      mysql:
        hostPathNodes:
          - my-cool-host1.com
      postgresql:
        hostPathNodes:
          - my-cool-host1.com
    

    Run Only Sysdig Pods on a Node Using Taints and Tolerations

    If you have a large shared Kubernetes cluster and want to dedicate a few nodes for just the Sysdig backend component installation, you can use the Kubernetes concept of taints and tolerations.

    The basic process is:

    1. Assign labels and taints to the relevant nodes.

    2. Review the sample node-labels-and-taints values.yaml in the Sysdig github repo.

    3. Copy that section to your own values.yaml file and edit with labels and taints you assigned.

    Example from the sample file:

    # To make the 'tolerations' code sample below functional, assign nodes the taint
    # dedicated=sysdig:NoSchedule. E.g:
    # kubectl taint my-awesome-node01 dedicated=sysdig:NoSchedule
      tolerations:
        - key: "dedicated"
          operator: "Equal"
          value: sysdig
          effect: "NoSchedule"
    # To make the Label code sample below functional, assign nodes the label
    # role=sysdig.
    # e.g: kubectl label nodes my-awesome-node01 role=sysdig
      nodeaffinityLabel:
        key: role
        value: sysdig
    

    Patching

    Patching can be used to customize or “tweak” the default behavior of the Installer to accommodate the unique requirements of a specific environment. Use patching to modify the parameters that are not exposed by thevalues.yaml. Refer to the configuration_parameters.md for more detail about various parameters.  

    The most common use case for patching is during upgrades. When generating the differences between an existing installation and the upgrade, you may see previously customized configurations that the upgrade would overwrite, but that you want to preserve.

    Patching Process

    If you have run  generate diff  and found a configuration that you need to tweak (e.g. the installer will delete something you want to keep, or you need to add something that isn’t there), then follow these general steps:

    • Create an overlays directory in the same location as the values.yaml.

      This directory, and the PATCH.yaml you create for it, must be kept. The installer will use it during future upgrades of Sysdig.

    • Create a .yaml file to be used for patching. You can name it whatever you want; we will call it PATCH.yaml for this example.

      Patch files must include, at a minimum:

      • apiVersion

      • kind

      • metadata.name

      of the object to be patched.

      Then you add the specific configuration required for your needs. See one example below.

      You will need this patch definition for every Kubernetes object you want to patch.

    • Run generate diff again and check that the outcome will be what you want.

    • When satisfied, complete the update by changing the scripts value to deploy and running the installer (see Installer Upgrade (2.5.0+).

    If you want to add another patch, you can either add a separate .yaml file or a new YAML document separated by ---

    The recommended practice is to use a single patch per Kubernetes object.

    Example

    Presume you have the following generated configuration:

    apiVersion: v1
    kind: Service
    metadata:
      annotations: {}
      labels:
        app: sysdigcloud
        role: api
      name: sysdigcloud-api
      namespace: sysdigcloud
    spec:
      clusterIP: None
      ports:
      - name: api
        port: 8080
        protocol: TCP
        targetPort: 8080
      selector:
        app: sysdigcloud
        role: api
      sessionAffinity: None
      type: ClusterIP
    

    To Add to the Generated Configuration

    Suppose you want to add an extra label my-awesome-label: my-awesome-value to the Service object. Then in the PATCH.yaml, you would put the following:

    apiVersion: v1
    kind: Service
    metadata:
      name: sysdigcloud-api
      labels:
        my-awesome-label: my-awesome-value
    

    Run the installer again, and the configuration would be as follows:

    apiVersion: v1
    kind: Service
    metadata:
      annotations: {}
      labels:
        app: sysdigcloud
        role: api
        my-awesome-label: my-awesome-value
      name: sysdigcloud-api
      namespace: sysdigcloud
    spec:
      clusterIP: None
      ports:
      - name: api
        port: 8080
        protocol: TCP
        targetPort: 8080
      selector:
        app: sysdigcloud
        role: api
      sessionAffinity: None
      type: ClusterIP
    

    To Remove from the Generated Configuration

    Supposed you wanted to remove all the labels. Then in the PATCH.yaml, you would put the following:

    apiVersion: v1
    kind: Service
    metadata:
      name: sysdigcloud-api
      labels:
    

    Run the installer again, and the configuration would be as follows:

    apiVersion: v1
    kind: Service
    metadata:
      annotations: {}
      name: sysdigcloud-api
      namespace: sysdigcloud
    spec:
      clusterIP: None
      ports:
      - name: api
        port: 8080
        protocol: TCP
        targetPort: 8080
      selector:
        app: sysdigcloud
        role: api
      sessionAffinity: None
      type: ClusterIP