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 for the version you’d like to install, 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.
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:
Enteraws
orgke
. 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
: Enterhostpath
, then define the nodes for the four main Sysdig components: ElasticSearch, Cassandra, MySQL, and Postgres.storageclassProvisionerSee Frequently Used Installer Configurations for details.
Quickstart Install
This install assumes the Kubernetes cluster has network access to pull images from quay.io.
Have your Sysdig Technical Account Manager download the installer binary that matches your OS from the the sysdigcloud-kubernetes releases page.
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.
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
orgke
in thestorageClassProvisioner
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 thevalues.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 tohostnetwork
.
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.
[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.]
Run the installer:
./installer deploy
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 astar
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
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
Follow the Docker Log In to quay.io steps, above.
Pull the image containing the self-extracting tar:
docker pull quay.io/sysdig/installer:5.1.2-2-uber
Extract the tarball:
docker create --name uber_image quay.io/sysdig/installer:5.1.2-2-uber docker cp uber_image:/sysdig_installer.tar.gz . docker rm uber_image
Copy the tarball to the installation machine.
On the Installation Machine:
Copy the current version values.yaml to your working directory. Below yaml is for version 5.1.4
wget https://github.com/draios/onprem-install-docs/blob/main/5.1/5.1.4/values.yaml
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
orgke
in thestorageClassProvisioner
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 thevalues.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.
Copy the tarball file to the directory where you have your
values.yaml
file.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 theairgapped_registry
.[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.]
Run the installer:
./installer deploy
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:
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.
Move the file from the jump box server to the airgapped environment (if needed)
Load the image file and push it to the airgapped image registry.
Restart the pod
sysdigcloud-feeds-db
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
To see all the configuration parameters available, as well as their definitions, values, and examples, see configuration_parameters.md on GitHub. Please note that this is for version 5.1.4 of the installer.
For advanced options, including static storage and patching, see Frequently Used Installer Configurations.
Example values.yaml files for version 5.1.4:
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.