Skip to content

Kubernetes (Helm)

The platform ships a Helm chart at helm-charts/charts/scf-controls-platform for operators who already run Kubernetes. It deploys the four application workloads: the API backend, the Celery worker, Celery beat and the nginx frontend. Everything else is yours to provide.

This page is the operator journey. The chart README in the repository is the reference for every value the chart accepts, and values.yaml documents each one inline.

You provideNotes
Kubernetes 1.27 or laterAny conformant distribution. A ReadWriteMany storage class is needed only for the SCF catalogue volume
PostgreSQL 15+Reachable from the cluster. The chart never runs a database
Redis 7+Two logical databases: one for the cache, one for Celery
An S3 or S3-compatible bucketEvidence bytes go browser-to-bucket with presigned URLs, so the bucket must be reachable from users’ browsers
An OIDC providerThe only sign-in method the published frontend image supports. See Identity provider for the client settings the platform needs
A Kubernetes SecretHolding the credentials below. The chart neither creates nor reads it, so use whatever secret tooling you already run
Your own SCF workbookSCF content is licensed and not shipped; see SCF catalogue

The chart fails at install time with a named message for anything left unconfigured. It also refuses any image on the latest tag unless you set allowLatestTag: true.

  1. Create the credentials Secret in the release namespace and record its name in secretName.

    KeyWhen
    SCF_SECRET_KEYAlways. Encrypts integration credentials stored in the database; changing it later makes every stored secret unreadable
    API_KEYAlways. The master backend API key
    OIDC_CLIENT_SECRETAlways
    DB_PASSWORDUnless you pass a full DATABASE_URL (database.urlFromSecret: true)
    REDIS_URL, CELERY_BROKER_URL, CELERY_RESULT_BACKENDOnly with redis.urlFromSecret: true
    DOWNLOAD_TOKEN_SECRETOptional. Signs evidence download links; falls back to API_KEY
    AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYOptional. Omit both to use a pod identity instead
    ANTHROPIC_API_KEY, RESEND_API_KEY, HIBP_API_KEY, NVD_API_KEYOptional integrations, as on Compose

    Pods stay in CreateContainerConfigError until the Secret exists.

  2. Write a values file pointing the chart at your services. This is a complete minimal example; every host below is a placeholder.

    my-values.yaml
    secretName: scf-platform-credentials
    database:
    host: postgres.example.internal
    name: scf
    username: scf
    sslMode: require
    redis:
    host: redis.example.internal
    cacheDatabase: 0
    celeryDatabase: 1
    evidenceStorage:
    bucket: scf-evidence
    region: eu-west-2
    # For a non-AWS store set BOTH: endpoint is what the pods use,
    # publicEndpoint is what the browser uses.
    endpoint: ""
    publicEndpoint: ""
    oidc:
    issuer: https://idp.example.com/realms/scf
    clientId: scf-platform
    # The BACKEND's callback: register this exact URI at your provider.
    redirectUri: https://scf.example.com/api/auth/callback
    ingress:
    enabled: true
    className: nginx
    hosts:
    - host: scf.example.com
    paths:
    - path: /
    pathType: Prefix
    tls:
    - secretName: scf-tls
    hosts: [scf.example.com]

    Images default to the chart’s appVersion, which tracks the platform release. Set global.imageRegistry to pull through a mirror.

  3. Install.

    Terminal window
    helm install scf ./helm-charts/charts/scf-controls-platform \
    --namespace scf --create-namespace \
    --values my-values.yaml

    Database migrations run as a pre-install,pre-upgrade hook before any workload rolls. A failed migration fails the release and leaves the previous pods running.

  4. Load the SCF catalogue, then sign in through your identity provider. The sign-in button sends the browser to the backend’s /api/auth/login; the backend runs the code flow and returns the browser to the app. Inviting the rest of the team is covered in User management.

The backend reads the catalogue from a shared volume at /app/data/json, so the volume needs a ReadWriteMany storage class. The documented sequence installs the volume first and turns the importer on afterwards, because the importer would otherwise run before the workbook exists and fail the release.

catalogData:
enabled: true
importer:
enabled: false
config:
singleTenant: true # the import refuses to run without it

Copy your workbook onto the volume through the backend pod, then enable the importer and restart the backend once it finishes:

Terminal window
kubectl -n scf cp scf.xlsx \
"$(kubectl -n scf get pod -l app.kubernetes.io/component=backend \
-o jsonpath='{.items[0].metadata.name}')":/app/data/json/scf.xlsx
helm upgrade scf ./helm-charts/charts/scf-controls-platform \
--namespace scf --reuse-values \
--set catalogData.importer.enabled=true
kubectl -n scf rollout restart deploy/scf-scf-controls-platform-backend

Set catalogData.importer.enabled back to false once the catalogue is loaded, or it re-runs on every upgrade. The chart README describes a single-step alternative using a claim you create yourself (catalogData.existingClaim with the importer as a pre-install hook).

config.singleTenant is not a sign-in method. It grants the master API key admin rights for direct API calls and is what the catalogue import needs; the trust-boundary note on the Deployment page applies to that key here too.

The frontend reads a small set of values when its container starts, so changing any of them is a pod restart rather than an image rebuild:

branding:
appTitle: Acme GRC
logoUrl: /acme-logo.png
marketingUrl: https://acme.example.com

Leave a value unset for the platform default. logoUrl: "" hides the logo entirely, which is not the same as leaving it unset. The same mechanism is available on Compose through the SCF_* variables in Configuration.

Bump the image tag (or the chart version, which carries appVersion) and run helm upgrade. The migration hook runs first.

By default the migration refuses to touch an existing database until you acknowledge the target version in the same change:

migrations:
acknowledge: "0.42.0"

Fresh and already-migrated databases need no acknowledgement. "any" disables the check permanently, which is only reasonable when your pipeline takes a database backup first.

Rollback is forward-only: reverting the Helm release does not revert the schema. Restore the database from a backup taken before the upgrade. The Backup and restore page describes what a complete backup contains; on Kubernetes the database, the bucket and the Secret are all outside the release, so your existing backup tooling for each is what applies.

Point your GitOps controller at the repository path at a tagged revision. Under Argo CD the chart’s Helm hooks map to PreSync and PostSync automatically. Do not add argocd.argoproj.io/hook annotations of your own: defining any Argo hook makes Argo ignore every Helm hook in the release, including the migration.

Every workload accepts the usual knobs: replicaCount, resources, autoscaling (HPA), podDisruptionBudget, nodeSelector, tolerations, affinity and topologySpreadConstraints. Celery beat must stay at a single replica. The worker’s queues list defaults to all nine platform queues; split it across several worker deployments only if you have measured a need to.

SymptomCause
helm install fails with ”… is required”A mandatory value is unset. The message names it
Pods in CreateContainerConfigErrorThe Secret named in secretName does not exist in the namespace, or lacks a required key
Evidence uploads fail while the API is healthyevidenceStorage.publicEndpoint is missing or not reachable from browsers. Transfers go browser-to-bucket
Sign-in loops or “invalid issuer”oidc.issuer does not match the iss claim in tokens exactly. Set discoveryUrl only when the backend reaches the provider on a different address than browsers do
Migration hook fails on upgradeEither a real migration error, or migrations.acknowledge does not name the version being installed
Catalogue import pod fails immediatelyThe workbook is not on the volume yet, or config.singleTenant is false

For application-level issues the Troubleshooting page applies to both deployment paths; substitute kubectl logs for docker compose logs.