Install the KubeClarity backend

You can install the KubeClarity backend using Helm, or you can build and run it locally.

Prerequisites

KubeClarity requires these Kubernetes permissions:

Prerequisites for AWS

If you are installing KubeClarity on AWS, complete the following steps. These are needed because KubeClarity uses a persistent PostgreSQL database, and that requires a volume.

1. Make sure that your EKS cluster is 1.23 or higher.
2. Install the EBS CSI Driver EKS add-on. For details, see Amazon EKS add-ons.
3. Configure the EBS CSI Driver with IAMServiceRole and policies. For details, see Creating the Amazon EBS CSI driver IAM role.

Install using Helm

1. Add the Helm repository.

   helm repo add kubeclarity https://openclarity.github.io/kubeclarity
   

2. Save the default KubeClarity chart values.

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. (Optional) Check the configuration in the values.yaml file and update the required values if needed. You can skip this step to use the default configuration.

   • To enable and configure the supported SBOM generators and vulnerability scanners, check the analyzer and scanner configurations under the vulnerability-scanner section. You can skip this step to use the default configuration settings.

4. Deploy KubeClarity with Helm.

   • If you have customized the values.yaml file, run:

     helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity --namespace kubeclarity
     

   • To use the default configuration, run:

     helm install --create-namespace kubeclarity kubeclarity/kubeclarity --namespace kubeclarity
     

   • For an OpenShift Restricted SCC compatible installation, run:

     helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity --namespace kubeclarity --set global.openShiftRestricted=true \
     --set kubeclarity-postgresql.securityContext.enabled=false --set kubeclarity-postgresql.containerSecurityContext.enabled=false \
     --set kubeclarity-postgresql.volumePermissions.enabled=true --set kubeclarity-postgresql.volumePermissions.securityContext.runAsUser="auto" \
     --set kubeclarity-postgresql.shmVolume.chmod.enabled=false
     

5. Wait until all the pods are in ‘Running’ state. Check the output of the following command:

   kubectl get pods --namespace kubeclarity
   

   The output should be similar to:

   NAME                                                    READY   STATUS    RESTARTS   AGE
   kubeclarity-kubeclarity-7689c7fbb7-nlhh5                1/1     Running   0          82s
   kubeclarity-kubeclarity-grype-server-79b6fb4b88-5xtbh   1/1     Running   0          82s
   kubeclarity-kubeclarity-postgresql-0                    1/1     Running   0          82s
   kubeclarity-kubeclarity-sbom-db-6895d97d5d-55jnj        1/1     Running   0          82s
   

6. Port-forward to the KubeClarity UI.

   kubectl port-forward --namespace kubeclarity svc/kubeclarity-kubeclarity 9999:8080
   

7. (Optional) Install a sample application (sock shop) to run your scans on.

   1. Create a namespace for the application.

      kubectl create namespace sock-shop
      

   2. Install the application.

      kubectl apply -f https://raw.githubusercontent.com/microservices-demo/microservices-demo/master/deploy/kubernetes/complete-demo.yaml
      

   3. Check that the installation was successful.

      kubectl get pods --namespace sock-shop
      

      Expected output:

      NAME                            READY   STATUS    RESTARTS   AGE
      carts-5dc994cf5b-4rhfj          2/2     Running   0          44h
      carts-db-556cbbd5fb-64qls       2/2     Running   0          44h
      catalogue-b7b968c97-b9k8p       2/2     Running   0          44h
      catalogue-db-f7547dd6-smzk2     2/2     Running   0          44h
      front-end-848c97475d-b7sl8      2/2     Running   0          44h
      orders-7d47794476-9fjsx         2/2     Running   0          44h
      orders-db-bbfb8f8-7ndr6         2/2     Running   0          44h
      payment-77bd4bbdf6-hkzh7        2/2     Running   0          44h
      queue-master-6d4cf8c4ff-pzk68   2/2     Running   0          44h
      rabbitmq-9dd69888f-6lzfh        3/3     Running   0          44h
      session-db-7d9d77c495-zngsn     2/2     Running   0          44h
      shipping-67fff9d476-t87jw       2/2     Running   0          44h
      user-7b667cd8d-q8bg8            2/2     Running   0          44h
      user-db-5599d45948-vxpq6        2/2     Running   0          44h
      

8. Open the KubeClarity UI in your browser at http://localhost:9999/. The KubeClarity dashboard should appear. KubeClarity UI has no data to report vulnerabilities after a fresh install, so there is no data on the dashboard.

   

9. If you also want to try KubeClarity using its command-line tool, Install the CLI. Otherwise, you can run runtime scans using the dashboard.

Uninstall using Helm

Later if you have finished experimenting with KubeClarity, you can delete the backend by completing the following steps.

1. Helm uninstall

   helm uninstall kubeclarity --namespace kubeclarity
   

2. Clean the resources. By default, Helm doesn’t remove the PVCs and PVs for the StatefulSets. Run the following command to delete them all:

   kubectl delete pvc -l app.kubernetes.io/instance=kubeclarity --namespace kubeclarity
   

Build and run locally with demo data

1. Build the UI and the backend and start the backend locally, either using Docker, or without it:

   • Using docker:

     1. Build UI and backend (the image tag is set using VERSION):

        VERSION=test make docker-backend
        

     2. Run the backend using demo data:

        docker run -p 9999:8080 -e FAKE_RUNTIME_SCANNER=true -e FAKE_DATA=true -e ENABLE_DB_INFO_LOGS=true -e DATABASE_DRIVER=LOCAL ghcr.io/openclarity/kubeclarity:test run
        

   • Local build:

     1. Build UI and backend

        make ui && make backend
        

     2. Copy the built site:

        cp -r ./ui/build ./site
        

     3. Run the backend locally using demo data:

        FAKE_RUNTIME_SCANNER=true DATABASE_DRIVER=LOCAL FAKE_DATA=true ENABLE_DB_INFO_LOGS=true ./backend/bin/backend run
        

2. Open the KubeClarity UI in your browser: http://localhost:9999/

3. Install the CLI.