Follow these instructions if you are deploying Software Risk Manager for the first time. Follow the Software Risk Manager migration instructions to move to the new Software Risk Manager deployment model.
Running guided-setup.ps1 is the recommended way to deploy Code Dx on Kubernetes (requires PowerShell Core 7). The script will help you specify the correct setup.ps1 script parameters for installing Code Dx on your Kubernetes cluster. Download the Code Dx Deployment Diagram for an overview of how Code Dx runs on Kubernetes.
Code Dx supports Kubernetes versions 1.19 through 1.29.
The Code Dx Kubernetes deployment has been tested on AKS, EKS, Minikube, Rancher K3s, Rancher RKE, and OpenShift 4. If you are using another Kubernetes provider, choose 'Other' from the Guided Setup's Kubernetes Environment screen.
You must run guided-setup.ps1 from a system with administrative access to your cluster. Copy the following prerequisite programs to directories that are included in your PATH environment variable:
- git
- PowerShell Core 7
- kubectl (a version that matches the major.minor version of your k8s cluster)
- openssl
- helm v3.1+ - Download the Helm release for your platform and extract helm (or helm.exe).
- keytool - The keytool application is bundled with the Java 11 JRE. If your Code Dx deployment requires specifying a path to a cacerts file, use the cacerts file from a Java 11 JRE install.
- kubeseal - Required when using GitOps and Bitnami's Sealed Secrets.
Note: Starting with the codedx-kubernetes release v2.12.0 (9/7/2022), the Code Dx Kubernetes deployment depends on and automatically downloads the guided-setup PowerShell Gallery module.
On Windows, make sure that you can run PowerShell Core scripts by switching your PowerShell Execution Policy to RemoteSigned (recommended) or Unrestricted. You must run the Set-ExecutionPolicy -ExecutionPolicy RemoteSigned command from an elevated/administrator Command Prompt.
Kubernetes removed support for the PodSecurityPolicy (PSP) resource with the v1.25 release.
Note: If your deployment does not use PSP resources, you can skip this section.
You should append the -skipPSPs parameter to your run-setup.ps1 script and rerun the script before upgrading your cluster to Kubernetes v1.25. If you skip that step, future helm deployments will fail because your helm manifest will include unavailable PSP resources. One way to recover from that situation is to delete the helm release Kubernetes secret resources in all Code Dx namespaces and rerun your run-setup.ps1 script.
You can ignore this section if you previously deployed Code Dx without the TLS Deployment Option.
Note: Your run-setup.ps1 file will include the
-skipTLSparameter if your Code Dx deployment does not use the TLS Deployment Option.
The latest version of the Code Dx deployment script supports Kubernetes v1.22. The TLS Deployment Option uses Kubernetes Certificate Signing Request (CSR) resources. Starting with Kubernetes v1.22, the kubernetes.io/legacy-unknown CSR signer is no longer available, so you may see this message when you rerun your run-setup.ps1 file:
Unable to continue because you previously enabled the TLS deployment option with the 'kubernetes.io/legacy-unknown' signer name. That signer requires the v1beta1 version of the Certificate Request Signer (CSR) resource, unavailable in this Kubernetes version. You must either disable the TLS deployment option by using the -skipTLS deployment script parameter or switch to an alternate Certificate Request Signer. For an example of enabling the TLS deployment option with cert-manager (https://cert-manager.io/docs/usage/kube-csr/), refer to https://github.com/codedx/codedx-kubernetes/blob/master/setup/core/docs/config/cert-manager-csr-upgrade.md.
Appending the -skipTLS parameter to your run-setup.ps1 file will disable the TLS Deployment Option, which uses TLS for connections between Code Dx components. Alternatively, you can configure a different CSR signer. You can find an example of using cert-manager as a CSR signer and how to update your run-setup.ps1 file here.
Below are the default CPU, memory, ephemeral storage, and volume requirements you'll see when running guided-setup.ps1. Your deployment may not include every pod type listed, but make sure your cluster has sufficient capacity for your specific resource requirements.
| Pod | CPU | Memory | Ephemeral Storage | Volume Size |
|---|---|---|---|---|
| Web | 2000m | 8192Mi | 2048Mi | 64Gi |
| DB (master) | 2000m | 8192Mi | - | 64Gi |
| DB (subordinate) | 1000m | 8192Mi | - | 64Gi |
| Tool Service | - | 500Mi | - | - |
| MinIO | 2000m | 500Mi | - | 64Gi |
| Workflow | - | 500Mi | - | - |
| Tools | 500m | 500Mi | - | - |
Note: You may have more than one Tool Service pod, and orchestrated analyses can run multiple tools concurrently.
With prerequisites installed, open a Command Prompt/Terminal window and clone this repository on your system by running the following command from the directory where you want to store the codedx-kubernetes files:
git clone https://github.com/codedx/codedx-kubernetes.git
The guided setup script checks whether your system meets the prerequisites before gathering configuration data with a series of steps to help you specify the setup.ps1 parameters necessary to deploy Code Dx in your Kubernetes environment.
Note: You will not have to visit every Guided Setup step because screens are presented based on your selected deployment options. For example, opting to use Code Dx with an external database will show steps that request database configuration details and include links to external database instance provisioning instructions.
To run the guided setup script after cloning the codedx-kubernetes repository, change directory to codedx-kubernetes, and use pwsh to run guided-setup.ps1:
cd codedx-kubernetes
pwsh ./guided-setup.ps1
Note: If running
pwsh ./guided-setup.ps1generates errors mentioning unexpected tokens, runpwsh ./guided-setup-check-prereqs.ps1to test whether your system meets the PowerShell Core v7 prerequisite.
Finish the guided setup by either running the generated setup command or saving your setup command to one or more files. Saving your setup command is recommended and something that's required if you want to configure authentication with LDAP or specify Code Dx property values in the Code Dx Properties File.
Note: You can find a description of each setup command parameter here.
If you are migrating from a Code Dx system created by the Code Dx Installer to a Code Dx Kubernetes deployment, follow the data migration steps to move your data to Kubernetes.
If you want the option of recovering from a failed upgrade by rolling back to a known good state, start a Code Dx backup and wait for it to finish before beginning an upgrade.
Note: When using Velero Storage Provider Plugins, volume snapshots may complete after your Velero backup reports a completed status, so wait for snapshots to finish before proceeding.
You can start a Velero backup using the schedule you created. If you have not yet configured your Code Dx backup, refer to the Code Dx Kubernetes Backup & Restore document for configuration details. For example, if the name of your Velero schedule is codedx-schedule, you can start a backup with this command:
velero backup create --from-schedule codedx-schedule
Note: Remember to wait for both the backup and the volume snapshots to complete (they may finish at different times).
The codedx-kubernetes repository gets updated with each new Code Dx release, so you can download the latest repository files and re-run the setup commands you previously saved. If your setup.ps1 command references specific Docker image names (e.g., -imageCodeDxTomcat codedx/codedx-tomcat:v5.0.8), update those parameters to install the Docker image versions associated with a specific Code Dx release.
Note: Refer to the changelog for a specific codedx-kubernetes release for any important notes regarding backward compatibility.
You can run the setup script commands multiple times. On subsequent runs with modified setup parameters, depending on what you changed, you may need to restart a system component like the Code Dx web application pod. For example, restarting the Code Dx web application pod is necessary when changing a codedx.props setting with a custom values.yaml file so that Code Dx can observe the new file contents.
You can recover from a failed upgrade by restoring the Code Dx backup you created before upgrading Code Dx. Run the following command to find the backup you want to restore:
velero backup get
Velero will skip restoring resources that already exist, so delete the resources you want to revert before starting a restore. You can delete the Code Dx namespace(s) to remove all namespaced resources, and you can delete cluster scoped Code Dx resources to remove Code Dx entirely. Since Code Dx depends on multiple PersistentVolume resources, you should always delete Code Dx PersistentVolume resources when restoring Code Dx to a previous known good state.
Refer to the Code Dx Kubernetes Backup & Restore document for details on how to restore Code Dx from a Velero backup.
If you encounter a problem with your Code Dx Kubernetes deployment, contact Code Dx Support by visiting https://codedx.com/support/. You can also check out the codedx-kubernetes Troubleshooting wiki page.
Follow the steps below to uninstall Code Dx from your cluster, replacing cdx-app and cdx-svc with your Code Dx Kubernetes namespaces.
- Delete the Code Dx Helm release: helm -n cdx-app delete codedx
- Delete the Code Dx Tool Orchestration release, if it exists: helm -n cdx-svc delete codedx-tool-orchestration
Note: You can bypass the workflow clean up process by adding the --no-hooks parameter: helm -n cdx-svc delete --no-hooks codedx-tool-orchestration
- Delete the Code Dx k8s namespace: kubectl delete ns cdx-app
- Delete the Code Dx Tool Orchestration k8s namespace, if it exists: kubectl delete ns cdx-svc
- Delete any remaining Persistent Volumes (PV) and any related PV data
- Delete the Argo Workflow CRDs
Below is a graph that shows every step of the guided setup script - you only have to visit the steps that apply to your Code Dx deployment.
