Open

You will learn

How to migrate from ThreadFix on Docker Compose to ThreadFix on Kubernetes.

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.5, 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.5 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 the 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 applicable instructions on the External Database guide 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 helm args for all of the user 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 desired file name 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:

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 External Database setup to prepare the external database.

TLS Setup

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

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

Install ThreadFix with Helm

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

2. Install Helm >= 3.5 or greater 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 helm args for all of the user 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
      
      

Table of Contents