Sysdig Documentation

Set Up (OpenShift)

Prerequisites

Overview

  • Access to a running OpenShift 3.11+ instance

  • Two items from your Sysdig purchase-confirmation email:

    • Your Sysdig license key

    • Your Sysdig quay.io pull secret

  • octools installed on your machine and communicating with the OpenShift cluster. (Note that your oc and OpenShift versions should match to avoid errors.)

DNS Preparation

If you want more information on OpenShift's DNS requirements; see the OpenShift documentation.

Option 1: DNS without Wildcard

You need to request two different DNS records from your DNS team: one for the Sysdig API/UI and another for the Sysdig collector. These records should point to your infrastructure nodes and are the two routes that will be exposed, i.e., sysdig.api.example.com and sysdig.collector.example.com .

Option 2: DNS with Wildcard

With wildcard DNS, you do not have to make an official request from the DNS team. Your implementation team can pick any two DNS names to use for the API/UI and Collector. These will be exposed to the infrastructure nodes once the configuration is completed. (i.e. sysdig.api.example.com and sysdig.collector.example.com .)

SSL Certificate Preparation

Step 5 Set Up SSL Connectivity to the Backend discusses how to implement SSL; decide ahead of time whether you will use SSL with wildcard or without.

SSL with Wildcard

With wildcard SSL, you use the same certificate for both the API and the collector.

SSL without Wildcard

You need two SSL certs, one for each DNS record.

Prepare the Environment

Step 1 Download and Unpack the Latest Release

  1. Download the latest release from https://github.com/draios/sysdigcloud-kubernetes/releases/latest

  2. Unpack the .tar ball.

    The source link has the format: https://github.com/draios/sysdigcloud-kubernetes/archive/<v1234>.tar.gz. To unpack it, run the following commands (replacing version number as appropriate):

    wget https://github.com/draios/sysdigcloud-kubernetes/archive/<v1234>.tar.gz
    tar zxf <v1234>.tar.gz
    cd sysdigcloud-kubernetes-<1234>
  3. Create a new project called sysdigcloud and copy the cloned folders into it:

    oc new-project sysdigcloud
  4. Apply the correct security contexts to the namespace. (This allows you to run privileged containers in the sysdigcloud namespace)

    oc adm policy add-scc-to-user anyuid -n sysdigcloud -z default
    oc adm policy add-scc-to-user privileged -n sysdigcloud -z default

Step 2 Configure Backend Components

The ConfigMap (config.yaml) is populated with information about usernames, passwords, SSL certs, and various application-specific settings.

The steps below give the minimum edits that should be performed in a test environment.

Warning

It is necessary to review and customize the entries in config.yaml before launching in a production environment.

See Making Configuration Changes, below, for the oc format to use for post-install edits, such as adding 3rd-party authenticators such as LDAP.

  1. Add your license key:

    In config.yaml, enter the key that was emailed to you in the following parameter:

    # Required: Sysdig Cloud license
      sysdigcloud.license: ""
  2. Change the super admin name and password, which are the super admin credentials for the entire system. See here for details.

    Find the settings in config.yaml here:

     sysdigcloud.default.user: test@sysdig.com
      # Required: Sysdig Cloud super admin user password
      # NOTE: Change upon first login
      sysdigcloud.default.user.password: test
  3. Edit the collector endpoint and API URL:Change the placeholder to point to the DNS names you have established for Sysdig.

    Note

    Remember that you must have defined one name for the collector and another for the API URL.

    Note: Change the collector port to 443.

    collector.endpoint: <COLLECTOR_DNS_NAME>
    collector.port: "443"
    api.url: https://<API_DNS_NAME>:443
  4. Recommended: edit the file to set the JVM options for Cassandra, Elasticsearch, and API, worker, and collector as well.

    (To use the AWS implicit key, edit the JVM options as described in AWS: Integrate AWS Account and CloudWatch Metrics (Optional).)

    For installations over 100 agents, it is recommended to allocate 8 GB of heap per JVM.

      cassandra.jvm.options: "-Xms8G -Xmx8G"
      elasticsearch.jvm.options: "-Xms8G -Xmx8G"
      sysdigcloud.jvm.api.options: "-Xms4G -Xmx8G"
      sysdigcloud.jvm.worker.options: "-Xms4G -Xmx8G"
      sysdigcloud.jvm.collector.options: "-Xms4G -Xmx8G"

    Note: If you do not wish to use SSL between the agent and the collector, use the following settings instead:

    cassandra.jvm.options: "-Xms8G -Xmx8G"
    elasticsearch.jvm.options: "-Xms8G -Xmx8G"
    sysdigcloud.jvm.api.options: "-Xms8G -Xmx8G -Ddraios.agents.installParams.sslEnabled=false"
    sysdigcloud.jvm.worker.options: "-Xms8G -Xmx8G -Ddraios.agents.installParams.sslEnabled=false"
    sysdigcloud.jvm.collector.options: "-Xms8G -Xmx8G -Ddraios.agents.installParams.sslEnabled=false"
  5. Deploy the configuration maps and secrets for all services by running the commands:

    For Sysdig Monitor:

    oc -n sysdigcloud apply -f sysdigcloud/config.yaml
  6. (For Sysdig Secure only) Edit and apply secrets for Anchore and the scanning component:Edit theyaml files:

    scanning-secrets.yaml

    stringData:
      scanning.mysql.password: change_me

    anchore-secrets yaml

    stringData:
      anchore.admin.password: change_me
      anchore.db.password: change_me

    Then apply the files:

    oc -n sysdigcloud apply -f sysdigcloud/scanning-secrets.yaml
    oc -n sysdigcloud apply -f sysdigcloud/anchore-secrets.yaml
  7. Edit the API DNS name in either api-ingress.yaml or api-ingress-with-secure.yaml (if using Secure).

    The files are located in sysdigcloud/

     spec:
       rules:
         - host: <API_DNS_NAME>
    ...
    
     tls:
         - hosts:
             - <API_DNS_NAME>
           secretName: sysdigcloud-ssl-secret
  8. Edit the collector DNS name in the file openshift-collector-router.yaml. Use the collector DNS name you created in the Prerequisites.

    The file is located in sysdigcloud/openshift/.

    spec:
      host: <COLLECTOR_DNS_NAME>

Step 3 (Secure-Only): Edit mysql-deployment.yaml

If using Sysdig Secure :

Edit the MySQL deployment to uncomment the MYSQL_EXTRADB_* environment variables. This forces MySQL to create the necessary scanning database on startup.

File location: datastores/as_kubernetes_pods/manifests/mysql/mysql-deployment.yaml

 - name: MYSQL_EXTRADB_SCANNING_DBNAME
              valueFrom:
                configMapKeyRef:
                  name: sysdigcloud-config
                  key: scanning.mysql.dbname
            - name: MYSQL_EXTRADB_SCANNING_USER
              valueFrom:
                configMapKeyRef:
                  name: sysdigcloud-config
                  key: scanning.mysql.user
            - name: MYSQL_EXTRADB_SCANNING_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: sysdigcloud-scanning
                  key: scanning.mysql.password

Warning

The scanning service will not start unless MySQL creates the scanning database.

Step 4 Deploy Your Quay Pull Secret

A specific Quay pull secret is sent via email with your license key.

  1. Edit the file sysdigcloud/pull-secret.yaml and change the place holder <PULL_SECRET> with the provided pull secret.

    vi sysdigcloud/pull-secret.yaml
     
        ---
        apiVersion: v1
        kind: Secret
        metadata:
        name: sysdigcloud-pull-secret
        data:
        .dockerconfigjson: <PULL_SECRET>
        type: kubernetes.io/dockerconfigjson
  2. Deploy the pull secret object:

    oc -n sysdigcloud apply -f sysdigcloud/pull-secret.yaml

Step 5 Set Up SSL Connectivity to the Backend

SSL-secured communication is used between user browsers and the Sysdig API server(s), and between the Sysdig agent and the collectors.

To set this up, you must:

  • Use an existing wildcard SSL certificate and key, or

  • Use existing standard certs for API and collector, or

  • Create self-signed certificates and keys for API and collector

Warning

If you are not using wildcard SSL, you have to use two separate certificates, one for API URL and one for the collector.

To disable SSL between agent and collector:

To disable SSL between agent and collectors, you set a JVM option when configuring backend components.

To create self-signed certs:

Run these commands (edit to add your API_DNS_NAME and COLLECTOR_DNS_NAME):

openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -subj "/C=US/ST=CA/L=SanFrancisco/O=ICT/CN=<API_DNS_NAME>" -keyout server.key -out server.crt
openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -subj "/C=US/ST=CA/L=SanFrancisco/O=ICT/CN=<COLLECTOR_DNS_NAME>" -keyout collector.key -out collector.crt

To use an existing wildcard cert:

Obtain the respective server.crt and server.key files.

To create Kubernetes secrets for the certs:

With Wildcard

Uses the same certificate for both the API/UI and the collector.

Run these commands:

oc -n sysdigcloud create secret tls sysdigcloud-ssl-secret --cert=server.crt --key=server.key
oc -n sysdigcloud create secret tls sysdigcloud-ssl-secret-collector --cert=server.crt --key=server.key

Without Wildcard

Uses two different certificates, one for the API/UI, and one for the collector.

Run these commands:

oc -n sysdigcloud create secret tls sysdigcloud-ssl-secret --cert=server.crt --key=server.key
oc -n sysdigcloud create secret tls sysdigcloud-ssl-secret-collector --cert=collector.crt --key=collector.key

Step 6 (Optional): Use CA Certs for External SSL Connections

The Sysdig platform may sometimes open connections over SSL to certain external services, including:

  • LDAP over SSL

  • SAML over SSL

  • OpenID Connect over SSL

  • HTTPS Proxies

If the signing authorities for the certificates presented by these services are not well-known to the Sysdig Platform (e.g., if you maintain your own Certificate Authority), they are not trusted by default.

To allow the Sysdig platform to trust these certificates, use the command below to upload one or more PEM-format CA certificates. You must ensure you've uploaded all certificates in the CA approval chain to the root CA.

oc -n sysdigcloud create secret generic sysdigcloud-java-certs --from-file=certs1.crt --from-file=certs2.crt