HomeDocumentationAPI Reference
Log In
Documentation
Start typing to search…
  1. Installation
  2. Docker Image Install

Sandfly Install - Kubernetes

For customers who would prefer to install Sandfly in Kubernetes rather than the standard Docker Image install, Sandfly supports generating Kubernetes manifest files as an alternative installation option.

Kubernetes (k8s) is an open-source platform that automates the deployment, scaling, and management of containerized applications. It organizes the Sandfly application containers into logical units (pods) for easy management, discovery, and self-healing across clusters of virtual or physical machines.

Complete Prerequisites

Ensure that the installation prerequisites (Install Container Tool and Download Setup Archive) are completed before following the steps on this page.

Run the Generate Kubernetes (k8s) Script

The generate kubernetes script will create a set of YAML files that can then be used to start/stop the Sandfly services using the standard Kubernetes commands.

Go to the setup directory:

cd ~/sandfly-setup/setup

Run the generate kubernetes script. If you run it without any arguments, you will be prompted for the information required for the Sandfly setup. Alternatively, you can supply the information as arguments to the script.

./generate_k8s.sh
Usage:
  generate_k8s.sh [options]

Options:
  -pg-cpus <number>             Number of CPU cores available to PostgreSQL
  -pg-ram-gb <number>           Number of gigabytes of RAM available to PostgreSQL
  -storage-size-gb <number>     Size in gigabytes for the persistent volume available to PostgreSQL
  -admin-password <password>    Admin user initial password
  -hostname <hostname>          Hostname or IP Address used to access the server UI
  -tls-mode <mode>              TLS Certificate mode: self_signed | acme | user_managed | none
  -acme-email <email-address>   Email address for the ACME directory service account
  -acme-directory <URL>         Specific ACME directory service URL
  -namespace <string>           Specify the desired Kubernetes Namespace (defaults to 'sandfly')

Configure the PostgreSQL Settings

You will need to specify the settings for the PostgreSQL server, including the number of CPU cores available for use, the amount of RAM (in GB) available for use, and the amount of storage space (in GB) for the data volume:

Installing Sandfly server version 5.7.0.

Copyright (c) Sandfly Security Ltd.

Welcome to the Sandfly 5.7.0 server setup. This script will generate
Kubernetes manifest files for deploying Sandfly.

Sandfly Setup Helper
Copyright (c) Sandfly Security Ltd.
Sandfly version: 5.7.0

--> CPU cores available to PostgreSQL: 
--> RAM (GB) available to PostgreSQL: 
--> Storage size (GB) for PostgreSQL data volume:

Server Hostname

Enter the IP address or hostname of the system that is hosting the server and database.

If this host is not resolvable by DNS, enter the external interface IP address. Otherwise, enter the server's DNS resolvable, fully qualified domain name.

❗️

IMPORTANT: Do Not Use Localhost (127.0.0.1) as the Server Address

Do not enter localhost (127.0.0.1), or any other loopback interface, for the server address as the application will not work. It must be a valid, external interface such as an ethernet IP address or fully qualified domain name the system uses for connectivity.

Example:

****************************************************************************
*                             Server Hostname                              *
****************************************************************************

Please enter the fully qualified domain name (FQDN) or the IP address
of the Sandfly server. It is important that the address supplied is
reachable by your web browser and the scanning nodes.

If you choose to use a Let's Encrypt HTTPS certificate on the Sandfly
server, this is the address that the certificate request will use, so
it must match the internet-accessible FQDN of the server.

Do NOT use localhost (127.0.0.1) as the address; the address must be
one that is reachable from the scanning nodes and from users' web
browsers to access the Sandfly UI.

--> Enter server hostname (e.g. sandfly.example.com): myhost.mycompany.com

Alternatively, enter an externally reachable IP address if DNS is not available for this host:

 ...

--> Enter server hostname (e.g. sandfly.example.com): 198.51.100.100

TLS (HTTPS Certificate) Mode

This installation script will prompt you to select how to generate the TLS certificate for the Sandfly server. The default option is to automatically generate a self-signed certificate.

The second option is to use Let's Encrypt (or another ACME certificate service) to request a signed certificate. To use Let's Encrypt, the Sandfly server must be accessible from the internet on port 443, and the hostname from the previous step must be the internet-facing FQDN of the server.

The third mode is to provide your own TLS certificates that are mounted into the Docker container. Choose "user_managed" mode and then place your certificates in the setup_data/server_ssl_cert folder. See Installing a Custom SSL Certificate for more information.

The last option is to disable TLS on the server, but only use this option if an external load balancer or ingress controller terminates the TLS connection.

 ...

****************************************************************************
*                       TLS (HTTPS Certificate) Mode                       *
****************************************************************************

Select the TLS mode for the Sandfly server:

  1) self_signed    - Auto-generate a self-signed certificate
                      (default)
  2) acme           - Use Let's Encrypt to request a signed
                      certificate
  3) user_managed   - Provide your own certificate files
                      (mount into the container)
  4) none           - Disable TLS on the server (use when an
                      external load balancer or ingress
                      controller terminates TLS)

Choice [1]: 1

Option 2: ACME Certificate Service

If you choose option 2, acme (Let's Encrypt), some additional details are required.

❗️

IMPORTANT: Port 443 Must Be Visible from the Internet During Signing!

Make sure the server has a legitimate hostname that is reachable from the internet and resolves correctly. Port 443 will need to be open for the Let's Encrypt server to validate the host.

Ensure that the hostname is publicly resolvable and port 443 can be reached from the internet. The ACME service will not sign any certificates for servers that are not reachable on the internet.

 ...

Choice [1]: 2

Let's Encrypt requires an email address. By configuring Sandfly to
use Let's Encrypt to generate a server certificate and providing an
email address, you are indicating acceptance of the current Let's
Encrypt terms of service. For more information, see
https://letsencrypt.org/

--> Enter Let's Encrypt contact email:

Enter the Let's Encrypt contact email. We recommend entering a valid email in case there is a security alert regarding the certificates.

When starting the server, the scripts prioritize signed versions over unsigned ones.

If the process is successful, the browser will not display warnings about invalid certificates when connecting to the UI.

If an internal server is used to host Sandfly, this method may not be possible. The server certificate would then need to be signed in another way. If you choose to use a self-signed certificate, accept the warning in the browser and then skip this step.

Admin Password

You may set an initial password for the admin user account. Alternatively, to have Sandfly automatically generate the admin password, press <Enter> at the prompt.

 ...

****************************************************************************
*                              Admin Password                              *
****************************************************************************

Please set an initial password for the "admin" user account.

Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password: 
--> Confirm admin password:

If you generate a random password, record the new password, as it will not be displayed again. You must then enter the password to confirm and continue the setup.

 ...

****************************************************************************
*                              Admin Password                              *
****************************************************************************

Please set an initial password for the "admin" user account.

Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password:

**********************************************************************
*** MAKE NOTE OF YOUR NEW PASSWORD. IT WILL NOT BE DISPLAYED AGAIN ***
coveted-retrain-clapping-dastardly-flaring-uselessly-mulch
**********************************************************************

--> Enter generated password to confirm:

Setup Complete

When the install script finishes the following output will be displayed:

 ...

Kubernetes manifests generated:
  /home/sandfly/sandfly-setup/setup/setup_data/sandfly-namespace.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/sandfly-secrets.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/sandfly-config.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/sandfly-deploy.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/sandfly-loadbalancer.yaml

To deploy:
  kubectl apply -f /home/sandfly/sandfly-setup/setup/setup_data/sandfly-namespace.yaml
  kubectl apply -f /home/sandfly/sandfly-setup/setup/setup_data/sandfly-secrets.yaml
  kubectl apply -f /home/sandfly/sandfly-setup/setup/setup_data/sandfly-config.yaml
  kubectl apply -f /home/sandfly/sandfly-setup/setup/setup_data/sandfly-deploy.yaml

To expose the server externally (edit as needed for your environment):
  kubectl apply -f /home/sandfly/sandfly-setup/setup/setup_data/sandfly-loadbalancer.yaml


K8s yaml files generated in
  /home/sandfly/sandfly-setup/setup/setup_data

Deploy to Kubernetes

Four Kubernetes manifest files are generated that are required to deploy the Sandfly server:

  1. sandfly-namespace.yaml - Defines the Sandfly namespace.
  2. sandfly-secrets.yaml - Defines the various private keys and passwords for communication between the Sandfly server components (PostgreSQL, server, nodes).
  3. sandfly-config.yaml - Defines the various public keys and configuration options for the Sandfly server components (PostgreSQL, server, nodes).
  4. sandfly-deploy.yaml - Deploys the Sandfly component services (PostgreSQL, server, nodes).

The sandfly-loadbalancer.yaml file is optional and only required in specific instances where the Sandfly server ports need to be exposed for an external load balancer:

  1. sandfly-loadbalancer.yaml - Example configuration for an external load balancer, edit as needed for your environment.

Note that the Kubernetes manifest files should be applied in the order specified above, as each one may depend on values from the previous manifest.

Updated 4 days ago

What is Next