Trivy Operator on Kubernetes

Continuous image vulnerability, configuration and RBAC reports as Kubernetes custom resources, with bounded scan concurrency and expiring scan jobs. Host infrastructure collection and broad secret access are disabled by default.

Maintained by imos64 as a deployment and operations package. Upstream software belongs to its respective maintainers; this repository does not imply authorship of the upstream product. Official project.

High-level architecture

flowchart LR
 API[Workload changes] --> Operator[Trivy Operator with leader election]
 Operator --> Jobs[Bounded scan Jobs]
 Registry[Image registry and vulnerability DB] --> Jobs
 Jobs --> Reports[Vulnerability and configuration report CRDs]
 Reports --> Metrics[Metrics and alert integration]

Loading

Delivery contract

Path	Purpose
charts/trivy-operator	Versioned Helm chart, base values and production overlay
k8s/base	Committed native Kubernetes rendering of base values
k8s/production	Committed rendering of the production overlay
terraform	Locked Helm provider deployment to an existing cluster
opentofu	Equivalent OpenTofu delivery with its own provider lock
scripts	Pinned tool installation, rendering and validation
docs	Configuration, architecture, operations and validation evidence

Readiness: production-oriented configuration and operational requirements are included. Static validation is not evidence of a successful production installation, availability SLA, disaster recovery or vendor certification. See validation evidence for exactly what was checked and what still requires your environment.

Upstream chart trivy-operator 0.36.0; application 0.34.0. The vendored archive and recorded checksum are part of this release.

Prerequisites and site configuration

Registry and vulnerability database egress is required. Explicitly choose targetNamespaces for tenant scope and add registry secret references only where needed. Production requests two operator replicas using the upstream leader-election mechanism. Scan containers need temporary storage and memory; tune concurrency before enabling cluster-wide scanning.

Use a supported Kubernetes cluster, adequate node capacity, a CNI that implements NetworkPolicy, and a CSI class appropriate to any persistent volumes. Node-local development volumes are not durable backups. Review all cluster-scoped RBAC, CRDs and node privileges before installation. Keep namespace lifecycle outside the component release; do not install the platform-baseline quota/policy chart into a node-security namespace without adapting it.

Install the pinned local validation toolchain when needed:

python3 scripts/install-tools.py
export PATH="$PWD/.tools:$PATH"
python3 -m pip install -r requirements-dev.txt
make render
make validate

Create a non-secret site-values.yaml in your deployment workspace, following configuration. Store real credentials in externally managed Kubernetes Secrets; values are retained in Helm release metadata and Terraform/OpenTofu state. Never pass private keys or passwords through committed values or command-line --set arguments.

export KUBE_CONTEXT=your-explicit-context
kubectl --context "$KUBE_CONTEXT" create namespace trivy-operator --dry-run=client -o yaml | kubectl --context "$KUBE_CONTEXT" apply -f -

Choose one deployment owner below. Do not run all four paths against the same resources.

Helm deployment

helm upgrade --install trivy-operator ./charts/trivy-operator \
  --kube-context "$KUBE_CONTEXT" --namespace trivy-operator \
  -f charts/trivy-operator/values-production.yaml -f /absolute/path/site-values.yaml \
  --atomic --wait --timeout 15m

Pinned dependencies are already vendored. Do not run helm dependency update blindly: it can replace locally reviewed upstream patches. On a dependency upgrade, download and verify upstream sources, reapply documented patches, update checksums, render both profiles and review the complete diff. Helm does not automatically upgrade CRDs stored under a dependency's crds/ directory; apply reviewed CRD updates first and wait for them to be Established.

Native Kubernetes deployment

The committed files are reviewable examples with default namespace and placeholder site settings. For an actual installation, render your site values locally, then use the phased native installer:

helm template trivy-operator ./charts/trivy-operator --namespace trivy-operator \
  --include-crds --skip-tests -f charts/trivy-operator/values-production.yaml \
  -f /absolute/path/site-values.yaml > /tmp/trivy-operator-site.yaml
python3 scripts/deploy-native.py --context "$KUBE_CONTEXT" --namespace trivy-operator --file /tmp/trivy-operator-site.yaml

The installer applies CRDs first and waits for registration, then applies the remaining objects server-side. It refuses populated Secret resources except documented non-credential upstream configuration. Review Kubernetes events and application readiness afterward; native apply is not an atomic Helm release. Never publish a locally rendered file that contains site credentials.

Terraform or OpenTofu deployment

Both directories use Helm provider 2.17.0 and an explicit kubeconfig context. They install into an existing namespace and do not provision cloud infrastructure.

terraform -chdir=terraform init
terraform -chdir=terraform plan \
  -var="kube_context=$KUBE_CONTEXT" \
  -var='values_files=["/absolute/path/site-values.yaml"]' -out=deployment.plan
terraform -chdir=terraform apply deployment.plan

For OpenTofu, use tofu -chdir=opentofu with the same arguments. Use separate encrypted remote state with locking and limited access. Review resource destruction carefully: uninstalling operators can strand custom resources, and deleting PVCs or their namespace can delete data. Plan files and state are ignored by Git.

Production acceptance

Create a disposable workload with a known vulnerable image, wait for its VulnerabilityReport and ConfigurationAuditReport, verify registry auth and metrics, and replace the elected operator leader to verify reconciliation resumes.

Record the selected cluster and software versions, storage and CNI implementations, node placement, observed resource usage, application-level responses, failover/restart results and restore evidence. Validate TLS at every externally exposed endpoint. Keep UIs private until authentication, authorization, DNS and certificates are configured. A replica count alone does not establish high availability.

Operations and recovery

Reports can be regenerated from workloads, but retain compliance evidence externally if required. Upgrade CRDs before controller upgrades, preserve report compatibility and monitor failing/expired scan jobs.

Architecture · Configuration · Operations runbook · Validation · Source provenance · Security policy

License and contributions

Repository-authored deployment code is Apache-2.0. Vendored upstream charts and software retain their original licenses; product licenses and commercial entitlements are not granted by this repository. Changes should include rendered manifest diffs and appropriate validation evidence. Report security issues privately using the repository security reporting facility.