📙 You will learn

Prerequisites

Audience: IT Professional
Difficulty: Intermediate
Time needed: Approximately 30 minutes
Tools required: compose-to-k8s.sh (provided below), db-only.yaml (provided below), Helm > 3.2, kubectl

Migration with Automated Scripts

The following instructions assume there is an existing ThreadFix application running in Docker Compose and a functional
Kubernetes instance with kubectl access and Helm 3.2 or greater.

Create Migration Files

1. Download the following files (provided above):

   • compose-to-k8s.sh

   • db-only.yaml
     

2. Copy compose-to-k8s.sh to the existing ThreadFix application server.
   

3. Log into the existing ThreadFix application server.
   

4. Make migration script executable with: chmod +x compose-to-k8s.sh.
   

5. Create migration data with: ./compose-to-k8s.sh

   • By default this will use /opt/threadfix as the ThreadFix directory and will
     output data to the current directory. Run ./compose-to-k8s.sh --help to view
     all configurable items

   • The script will create the following files:

     • migrated_values.yaml

     • migrated_db.sql

     • appsec-data.zip

     • appsec-secrets.yaml (optional)

     • migrated_tls.yaml (optional)
       

6. Review the output from the script and make any necessary adjustments.
   

7. Validate all appropriate files have been created.
   

8. Copy the generated files and db-only.yaml to the server with Kubernetes access.

External Database

Reuse Existing Database

If reusing the existing external database:

• In migrated_values.yaml, validate appsec.db.urlOverride and auth.db.urlOverride are set and point to the correct database.

If the external database has separate credentials than the internal database:

1. Validate the appsec.db.existingSecret and auth.db.existingSecret fields exist in migrated_values.yaml and a corresponding appsec-secrets.yaml file has been created.
   

2. On the server with kubectl access, run kubectl apply -f appsec-secrets.yaml to create the Kubernetes Secret for the AppSec database.

New External Database

If using a new external database, first migrate all data from the existing database to the new database following the vendor's instructions, then:

1. In migrated_values.yaml, remove the appsec.db.urlOverride and auth.db.urlOverride items.
   

2. Follow steps 1 through 3 of the Configuring External Database guide for setting up the external database. Then proceed with the remainder of this guide.

Installing ThreadFix on Kubernetes with helm

1. Follow any necessary preparation tasks before continuing

2. Make any modifications to the migrated_values.yaml file if needed.

3. Setup TLS:

   • If reusing the existing TLS certificate, add the TLS certificate and keys with:

   kubectl apply -f migrated_tls.yaml

   • If using a new TLS certificate, add to Kubernetes with:

   kubectl create secret tls threadfix-cert --key <key_file> --cert <cert_file>

4. Setup an external database (Optional).

   • If appsec-secrets.yaml was created and an existing external database is being reused, apply with:

   kubectl apply -f appsec-secrets.yaml

   • If an new external database is being used, follow instructions on External Database Setup Instructions (Kubernetes) to add credentials for the external database
     

5. Add the ThreadFix Helm repository:

   1. Add the ThreadFix Helm repository by running:

      helm repo add denimgroup https://threadfix-downloads.s3-us-west-2.amazonaws.com/helm/

   2. Update the repositories by running:

      helm repo update

6. Make myValues dir if not present

   mkdir -p myValues

7. Generate a unique password for PostgreSQL

   PG_PASSWORD=$(openssl rand -base64 25)

8. Copy migrated_values.yaml in the to myValues dir

   cp migrated_values.yaml myValues/

9. Generate a your helm args for all of your values files

   HELM_INSTALL_ARGS=$(for values_file in myValues/*.yaml; do echo -n "-f $values_file "; done)

10. Start the application in database only mode with:

    helm install tf denimgroup/threadfix -f db-only.yaml $HELM_INSTALL_ARGS

11. Wait until the database has started to proceed. Check status with kubectl get po -w. Use Ctrl-C to exit the command.
    

12. Upload the exported database to the Kubernetes with:

    cat migrated_db.sql | kubectl exec -i $(kubectl get po -l app.kubernetes.io/name=db,app.kubernetes.io/part-of=threadfix -o jsonpath='{.items[0].metadata.name}') -- bash -c 'mysql -u$MYSQL_USER -p"$MYSQL_PASSWORD"'

13. Start the application with:

    helm upgrade $HELM_INSTALL_ARGS --no-hooks tf denimgroup/threadfix

14. Follow the on-screen instructions to access the application.

    • Use kubectl get po -w to watch the installation progress

Manual Migration

Export the Database

1. Change directory to the location of the ThreadFix install. ex. cd /opt/threadfix.
   

2. Stop ThreadFix with:

   docker-compose down

3. Start the database only with:

   docker-compose up -d db

4. Export the database (replacing <db_dump_file> with the file name you wish to create the database dump with):

   docker-compose exec -T db sh -c 'mysqldump --all-databases -u${MYSQL_USER} -p${MYSQL_PASSWORD} -h 127.0.0.1 2> /dev/null' > <db_dump_file>

5. Copy the dump file to the machine with kubectl access.

Create Helm Values

Create a Helm Values file from the existing ThreadFix .env file (default location /opt/threadfix/.env) where appropriate. The table below shows Compose variables with equivalent Helm values. If any value has not been changed from the default, it can safely be ignored.

Add Properties Files as YAML String

The following values need the contents of the listed file input as yaml strings.

Example

"threadfix.license": 2|
  -- listing properties --
  clientId=XXXXXXXX-YYYY-YYYY-YYYY-XXXXXXXXXXX
  version=ENTERPRISE
  organization=My Org
  targetDate=1000000000000
  numberApplications=1
  numberAssets=1
  apiKey=RS7gz88T7J/7EYd+dhVo2/xxg5bKvkJg+AXK5+gE
  eVBcBevX/sJDgsvWkryb+LZte7P0crzHW9G5ttWNTNX8d2KQ==

Other Values

The following values have no Helm equivalent and must be created as Kubernetes Secrets and linked to the ThreadFix installation.

• External AppSec database credentials:

  • APPSEC_DB_USER

  • APPSEC_DB_PASSWORD

• TLS certificates:

  • ssl_cert

  • ssl_key

External AppSec Database Credentials Setup

If using an internal Appsec database or sharing the same database credentials for Appsec and network, the AppSec database credentials values can be ignored. Otherwise, follow the Link external DB setup guide to setup the external database.

TLS Setup

On the Kubernetes instance, create a TLS Secret with the following command (replacing <> placeholders with actual values):

kubectl create secret tls tf-tls --key <path_to_tls_key> --cert <path_to_tls_cert>

Then add the following to the Helm values yaml file from above:

kong:
  env:
    SSL_CERT: /etc/secrets/tf-tls/tls.crt
    SSL_CERT_KEY: /etc/secrets/tf-tls/tls.key
  secretVolumes:
    - tf-tls

Install ThreadFix with Helm

1. Make any other modifications to the Helm values file if needed.
   

2. Install Helm >= 3.2 if not already installed. Perform one of the following:

   • Install from script with curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | sudo bash

   • Follow the instructions for Helm installation: https://helm.sh/docs/intro/install/
     

3. Add the ThreadFix Helm repository:

   1. Add the ThreadFix Helm repository by running:

      helm repo add denimgroup https://threadfix-downloads.s3-us-west-2.amazonaws.com/helm/

   2. Update the repositories by running:

      helm repo update

4. Create db-only.yaml file with the following contents:

   appsec:
     enabled: false
   auth:
     enabled: false
   crud:
     enabled: false
   db:
     enabled: true
   defect:
     enabled: false
   importer:
     enabled: false
   processor:
     enabled: false
   provider:
     enabled: false
   ui:
     enabled: false
   websocket:
     enabled: false
   kong:
     enabled: false
   kafka:
     enabled: false
   zk:
     enabled: false

5. Make myValues dir if not present

   mkdir -p myValues

6. Generate a unique password for PostgreSQL

   PG_PASSWORD=$(openssl rand -base64 25)

7. Create a myValues.yaml file

   echo "kong:
     postgresql:
       postgresqlPassword: $PG_PASSWORD
   " > myValues/postgresql.yaml

8. Copy any created helm values files the to myValues dir

9. Generate a your helm args for all of your values files

   HELM_INSTALL_ARGS=$(for values_file in myValues/*.yaml; do echo -n "-f $values_file "; done)

10. Start the application in database only mode with:

    helm install tf denimgroup/threadfix -f db-only.yaml $HELM_INSTALL_ARGS

11. Wait until the database has started to proceed. Check the status with kubectl get po -w. Use Ctrl-C to exit the command.
    

12. Upload the exported database to the Kubernetes with:

    cat <db_dump_file> | kubectl exec -i $(kubectl get po -l app.kubernetes.io/name=db,app.kubernetes.io/part-of=threadfix -o jsonpath='{.items[0].metadata.name}') -- bash -c 'mysql -u$MYSQL_USER -p"$MYSQL_PASSWORD"'

13. Start the application with (replacing <helm_values_file> with the values file created earlier):

    helm upgrade $HELM_INSTALL_ARGS --no-hooks tf denimgroup/threadfix

14. Follow the on screen instructions to access the application.

    • Use kubectl get po -w to watch the installation progress