How to Integrate Trivy with Kubernetes Using the Operator: 3 Deployment Methods

Deploy the Trivy Operator by installing the official Helm chart from the AquaSecurity repository, creating a continuous security scanning deployment in your cluster that automatically generates VulnerabilityReport and ConfigAuditReport custom resources for all workloads.

To integrate Trivy with Kubernetes using the operator, you deploy a long-running controller that watches cluster resources and triggers automated scans. While the core Trivy CLI resides in the aquasecurity/trivy repository, the operator itself is maintained as a separate project with installation manifests and documentation housed in the main repo. This approach moves security scanning from manual CLI executions to an automated, cluster-native workflow that persists results as Kubernetes objects.

What Is the Trivy Operator?

The Trivy Operator is a Kubernetes controller that runs as a Deployment inside your cluster, continuously monitoring workloads, node components, and configurations for vulnerabilities and misconfigurations. Unlike the CLI tool that performs on-demand scans, the operator acts as a persistent security agent that reacts to changes in your cluster state.

Architecture Overview

According to the aquasecurity/trivy source code, the solution consists of two distinct components:

• Trivy CLI: The core binary located in this repository that performs the actual scanning logic when invoked by the operator
• Trivy Operator: A separate controller project that manages scan jobs, aggregates results, and exposes them through Kubernetes APIs

The operator watches for changes to pods, deployments, and nodes, then creates temporary scan Jobs that use the Trivy CLI container image. As documented in docs/guide/target/kubernetes.md, this architecture decouples the scanning engine from the orchestration logic, allowing independent updates to the vulnerability database and the operator itself.

Custom Resources

Scan results are stored as Custom Resource Definitions (CRDs) that integrate natively with kubectl and Kubernetes APIs:

• VulnerabilityReport: Contains detailed CVE findings for container images
• ConfigAuditReport: Stores misconfiguration findings from infrastructure-as-code and runtime checks

These resources are defined in the operator's Helm chart and become queryable through standard Kubernetes tooling once the operator is installed.

Prerequisites

Before you integrate Trivy with Kubernetes using the operator, ensure you have:

• A Kubernetes cluster (1.19 or later)
• Helm 3.0+ installed locally
• Cluster-admin permissions to install CRDs and create the trivy-system namespace
• The AquaSecurity Helm repository added: helm repo add aquasecurity https://aquasecurity.github.io/helm-charts/

Deployment Methods

The docs/tutorials/kubernetes/gitops.md file in the aquasecurity/trivy repository provides three primary installation patterns depending on your infrastructure management approach.

Option 1: GitOps with Argo CD

For teams practicing GitOps, deploy the operator using an Argo CD Application manifest. This method stores the desired state in Git and enables automated synchronization.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: trivy-operator
  namespace: argocd
spec:
  project: default
  source:
    chart: trivy-operator
    repoURL: https://aquasecurity.github.io/helm-charts/
    targetRevision: 0.0.3
    helm:
      values: |
        trivy:
          ignoreUnfixed: true
  destination:
    server: https://kubernetes.default.svc
    namespace: trivy-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Apply this manifest with kubectl apply -f trivy-operator.yaml. Argo CD will reconcile the Helm chart and maintain the operator deployment.

Option 2: GitOps with Flux CD

If you use Flux CD, define a HelmRepository and HelmRelease to manage the operator lifecycle declaratively.

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: trivy-operator
  namespace: flux-system
spec:
  interval: 60m
  url: https://aquasecurity.github.io/helm-charts/
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: trivy-operator
  namespace: trivy-system
spec:
  chart:
    spec:
      chart: trivy-operator
      sourceRef:
        kind: HelmRepository
        name: trivy-operator
        namespace: flux-system
      version: 0.10.1
  interval: 60m
  values:
    trivy:
      ignoreUnfixed: true
  install:
    crds: CreateReplace
    createNamespace: true

Commit this to your Git repository and let Flux reconcile the resources. The createNamespace: true flag ensures the trivy-system namespace is created automatically.

Option 3: Manual Helm Installation

For traditional imperative deployments or CI/CD pipelines, install directly via Helm without GitOps tooling.

kubectl create ns trivy-system
helm repo add aquasecurity https://aquasecurity.github.io/helm-charts/
helm install trivy-operator aquasecurity/trivy-operator \
  --namespace trivy-system \
  --version 0.10.1 \
  --set trivy.ignoreUnfixed=true

This command pulls the trivy-operator chart from the AquaSecurity Helm repository and installs the controller with RBAC roles and CRDs defined in the chart templates.

Verifying the Installation

After deploying using any of the above methods, confirm the operator is functioning correctly:

# Check operator pod status

kubectl get pods -n trivy-system

# Verify CRDs are installed

kubectl get crd | grep trivy

# List generated vulnerability reports

kubectl get vulnerabilitiereports -A

If the installation succeeded, you will see the operator pod in a Running state and VulnerabilityReport resources appearing for existing workloads within a few minutes. The Helm chart referenced in helm/trivy/Chart.yaml provisions all necessary RBAC permissions automatically, so no additional role configuration is required for basic operation.

Summary

• Integrate Trivy with Kubernetes using the operator to enable continuous, automated security scanning as a cluster-native service rather than manual CLI executions.
• Choose between Argo CD, Flux CD, or manual Helm installation based on your GitOps maturity, with all methods using the same upstream chart from https://aquasecurity.github.io/helm-charts/.
• Scan results persist as VulnerabilityReport and ConfigAuditReport custom resources that integrate with existing Kubernetes tooling and CI/CD pipelines.
• The aquasecurity/trivy repository provides official documentation in docs/tutorials/kubernetes/gitops.md and docs/guide/target/kubernetes.md for customizing scan policies and target scopes.

Frequently Asked Questions

What is the difference between Trivy CLI and Trivy Operator?

The Trivy CLI is a standalone binary in the aquasecurity/trivy repository that performs on-demand scans when executed manually or in CI pipelines. The Trivy Operator is a separate Kubernetes controller that runs continuously inside your cluster, watching for resource changes and automatically creating scan jobs using the CLI container image. While the CLI is stateless and ephemeral, the operator maintains persistent security state through Kubernetes custom resources.

Where are scan results stored in Kubernetes?

Scan results are stored as Custom Resources in the cluster's etcd database. Specifically, the operator creates VulnerabilityReport resources for image findings and ConfigAuditReport resources for misconfigurations. These resources are namespace-scoped and can be queried using standard kubectl get commands, allowing security data to be consumed by dashboards, alerting systems, and policy engines without external databases.

Can I use the Trivy Operator without GitOps?

Yes, the Trivy Operator does not require GitOps tooling. You can install it manually using the Helm command shown in the manual installation section, or integrate the Helm chart into traditional CI/CD pipelines. The GitOps examples in docs/tutorials/kubernetes/gitops.md are optional patterns for teams already using Argo CD or Flux CD, but the operator functions identically regardless of deployment method.

How do I customize scan policies in the operator?

Customize scanning behavior by passing values to the Helm chart during installation or updates. Key configuration options include trivy.ignoreUnfixed to suppress unfixed vulnerabilities, trivy.severity to filter by severity levels, and trivy.skipFiles to exclude specific paths. These values map to environment variables in the operator deployment, which then passes flags to the underlying Trivy CLI containers when creating scan jobs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}