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.
What the chart expects you to bring
Section titled “What the chart expects you to bring”| You provide | Notes |
|---|---|
| Kubernetes 1.27 or later | Any 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 bucket | Evidence bytes go browser-to-bucket with presigned URLs, so the bucket must be reachable from users’ browsers |
| An OIDC provider | The only sign-in method the published frontend image supports. See Identity provider for the client settings the platform needs |
| A Kubernetes Secret | Holding the credentials below. The chart neither creates nor reads it, so use whatever secret tooling you already run |
| Your own SCF workbook | SCF 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.
Install
Section titled “Install”-
Create the credentials Secret in the release namespace and record its name in
secretName.Key When 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: trueDOWNLOAD_TOKEN_SECRETOptional. Signs evidence download links; falls back to API_KEYAWS_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
CreateContainerConfigErroruntil the Secret exists. -
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-credentialsdatabase:host: postgres.example.internalname: scfusername: scfsslMode: requireredis:host: redis.example.internalcacheDatabase: 0celeryDatabase: 1evidenceStorage:bucket: scf-evidenceregion: 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/scfclientId: scf-platform# The BACKEND's callback: register this exact URI at your provider.redirectUri: https://scf.example.com/api/auth/callbackingress:enabled: trueclassName: nginxhosts:- host: scf.example.compaths:- path: /pathType: Prefixtls:- secretName: scf-tlshosts: [scf.example.com]Images default to the chart’s
appVersion, which tracks the platform release. Setglobal.imageRegistryto pull through a mirror. -
Install.
Terminal window helm install scf ./helm-charts/charts/scf-controls-platform \--namespace scf --create-namespace \--values my-values.yamlDatabase migrations run as a
pre-install,pre-upgradehook before any workload rolls. A failed migration fails the release and leaves the previous pods running. -
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.
SCF catalogue
Section titled “SCF catalogue”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: falseconfig: singleTenant: true # the import refuses to run without itCopy your workbook onto the volume through the backend pod, then enable the importer and restart the backend once it finishes:
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-backendSet 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.
Branding and runtime settings
Section titled “Branding and runtime settings”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.comLeave 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.
Upgrades
Section titled “Upgrades”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.
GitOps
Section titled “GitOps”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.
Scaling and resilience
Section titled “Scaling and resilience”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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause |
|---|---|
helm install fails with ”… is required” | A mandatory value is unset. The message names it |
Pods in CreateContainerConfigError | The Secret named in secretName does not exist in the namespace, or lacks a required key |
| Evidence uploads fail while the API is healthy | evidenceStorage.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 upgrade | Either a real migration error, or migrations.acknowledge does not name the version being installed |
| Catalogue import pod fails immediately | The 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.
