Pulumi Blog: Opa

From Kubernetes Gatekeeper to Full-Stack Governance with OPA

Levi Blackstone — Thu, 19 Mar 2026 00:00:00 +0000

Pulumi’s OPA (Open Policy Agent) support is now stable. The v1.1.0 release of pulumi-policy-opa makes OPA/Rego a first-class policy language for Pulumi with full feature parity alongside the native TypeScript and Python policy SDKs. Write Rego policies that validate any resource Pulumi manages, across AWS, Azure, GCP, Kubernetes, and the rest of the provider ecosystem. If you already have Kubernetes Gatekeeper constraint templates, a new compatibility mode lets you drop those .rego files directly into a Pulumi policy pack and enforce them against your Kubernetes resources without modification.

What’s in the stable release

OPA/Rego is now fully supported as a policy language for Pulumi Insights, with the same capabilities as the TypeScript and Python SDKs:

Resource and stack-level policies: Validate individual resources with deny and warn rules, or evaluate your entire stack at once with stack_deny and stack_warn for cross-resource checks like relationship validation and resource count limits.
Enforcement levels: Control how violations are handled. mandatory blocks deployments, advisory surfaces warnings, and disabled turns rules off without removing them. Enforcement levels can be overridden per policy without modifying Rego source.
Policy configuration: Pass custom parameters to policies via configuration files, with optional JSON schema validation. Configuration values are accessible in Rego as data.config.<policy_name>.<key>.
OPA metadata annotations: Use standard OPA # METADATA comments to provide titles, descriptions, and messages for your policies. These populate the policy metadata displayed in Pulumi Cloud.
Preventative and audit evaluation: OPA policies work with both preventative enforcement during pulumi up and audit policy scans for continuous compliance monitoring.

You can choose whichever language best fits your team. Organizations already using OPA across their toolchain can standardize on Rego for Pulumi policies, while teams preferring TypeScript or Python can continue to use those. All three languages work side by side in the same policy groups.

Kubernetes Gatekeeper compatibility

The headline feature of this release is native support for Kubernetes Gatekeeper constraint template rules. If you’re running Gatekeeper as an admission controller in your clusters, you likely have a library of .rego policies that enforce security and operational standards at admission time. With v1.1.0, those same rules can now run as Pulumi policies, catching violations during pulumi preview before resources ever reach the cluster.

To enable Gatekeeper compatibility, set inputFormat: kubernetes-admission in your PulumiPolicy.yaml:

description: Kubernetes Gatekeeper Policy Pack
runtime: opa
inputFormat: kubernetes-admission

With this setting, Pulumi automatically wraps Kubernetes resources in the Gatekeeper AdmissionReview structure (input.review.object, input.review.kind, etc.), so your existing rules work without modification. Non-Kubernetes resources are silently skipped.

Here’s an example that reuses standard Gatekeeper-style rules, requiring an app label and prohibiting the latest image tag:

package gatekeeper

import rego.v1

# METADATA
# title: Require App Label
# description: All Kubernetes resources must have an "app" label.
violation contains {"msg": msg} if {
 not input.review.object.metadata.labels["app"]
 msg := sprintf("%s '%s' is missing required label: app",
 [input.review.kind.kind, input.review.name])
}

# METADATA
# title: Disallow Latest Tag
# description: Container images must not use the "latest" tag.
deny contains msg if {
 container := input.review.object.spec.template.spec.containers[_]
 endswith(container.image, ":latest")
 msg := sprintf("container '%s' uses the 'latest' tag -- pin to a specific version",
 [container.name])
}

These rules are identical to what you’d write for Gatekeeper. Both rule head formats are supported and can coexist: the violation[{"msg": msg}] map format and the deny[msg] string format. Per-policy configuration via input.parameters also works as expected. You can take a .rego file from your Gatekeeper constraint templates, drop it into a Pulumi policy pack, and publish it to Pulumi Cloud to enforce automatically across your stacks.

This shifts policy enforcement left. Instead of waiting for the Kubernetes API server to reject a resource at admission time, you catch the violation during pulumi preview, before anything is deployed.

Walkthrough: Reusing policies from the gatekeeper-library

The OPA Gatekeeper Library is a community-maintained collection of constraint templates covering common Kubernetes guardrails like pod security, image provenance, and resource limits. You can use these policies directly with Pulumi. Here’s an end-to-end example using the allowedrepos policy to restrict which container image registries your deployments can use.

Create a new Kubernetes OPA policy pack:
```
pulumi policy new kubernetes-opa
```

Copy the Rego source from gatekeeper-library into your policy pack as allowedrepos.rego. No modifications are needed:

package k8sallowedrepos

violation[{"msg": msg}] {
 container := input.review.object.spec.containers[_]
 not strings.any_prefix_match(container.image, input.parameters.repos)
 msg := sprintf("container <%v> has an invalid image repo <%v>, allowed repos are %v",
 [container.name, container.image, input.parameters.repos])
}

violation[{"msg": msg}] {
 container := input.review.object.spec.initContainers[_]
 not strings.any_prefix_match(container.image, input.parameters.repos)
 msg := sprintf("initContainer <%v> has an invalid image repo <%v>, allowed repos are %v",
 [container.name, container.image, input.parameters.repos])
}

violation[{"msg": msg}] {
 container := input.review.object.spec.ephemeralContainers[_]
 not strings.any_prefix_match(container.image, input.parameters.repos)
 msg := sprintf("ephemeralContainer <%v> has an invalid image repo <%v>, allowed repos are %v",
 [container.name, container.image, input.parameters.repos])
}

Verify that your PulumiPolicy.yaml has Gatekeeper compatibility enabled:

description: Kubernetes Gatekeeper Policy Pack
runtime: opa
inputFormat: kubernetes-admission

Configure the allowed registries. Create a policy-config.json file to pass the repos parameter:

{
 "k8sallowedrepos": {
 "repos": ["gcr.io/my-company/", "docker.io/library/"]
 }
}

Test the policy locally against a stack:
```
pulumi preview --policy-pack . --policy-pack-config policy-config.json
```
Any Kubernetes deployment using an image outside the allowed registries will produce a violation at preview time, before it reaches the cluster.
Publish the pack and add it to a policy group to enforce it across your organization:
```
pulumi policy publish
```

The same approach works for any policy in the gatekeeper-library: containerlimits, requiredlabels, disallowedtags, and others. Copy the Rego, configure parameters, and publish.

Part of the Pulumi Insights governance story

OPA policy support is part of the broader Pulumi Insights governance platform. Insights gives you visibility and compliance across your entire cloud footprint, and OPA policies plug directly into that:

Audit policy scans continuously evaluate OPA policies against your Pulumi stacks and discovered cloud resources, providing a compliance baseline without redeploying anything.
Self-hosted execution lets you run policy evaluations on your own infrastructure using customer-managed workflow runners, keeping credentials and data within your network.
Pre-built compliance packs for CIS, NIST, PCI DSS, and other frameworks are available alongside your custom OPA policies in the same policy groups.

Whether you’re enforcing policy at deployment time, scanning existing infrastructure for drift, or running continuous compliance checks, OPA policies are a native participant.

Frequently asked questions

Do I need to modify my existing Gatekeeper `.rego` files?

No. Set inputFormat: kubernetes-admission in your PulumiPolicy.yaml and your existing Gatekeeper constraint template rules work as-is. Pulumi handles the AdmissionReview wrapping automatically.

What happens with non-Kubernetes resources?

When using inputFormat: kubernetes-admission, non-Kubernetes resources are silently skipped during evaluation. Your Gatekeeper rules only run against Kubernetes resources.

Do I need OPA installed locally?

No. The pulumi-policy-opa analyzer plugin embeds the OPA evaluation engine and is installed automatically by the Pulumi CLI (v3.227.0+). The standalone OPA CLI is only needed if you want to run opa test against your policies independently.

When should I use OPA vs. TypeScript or Python for policies?

If your team already writes Rego for other tools like Gatekeeper, writing Pulumi policies in Rego keeps your policy language consistent. If your team is more comfortable with general-purpose languages or needs auto-remediation, use the TypeScript or Python SDKs.

Gatekeeper constraint templates can be reused directly via the kubernetes-admission input format, but other OPA integrations use different input structures, so those policies would need to be adapted to Pulumi’s resource model. All three languages work together in the same policy groups.

Get started

Templates are available for kubernetes-opa, aws-opa, azure-opa, and gcp-opa via pulumi policy new. For more details, see the policy authoring guide and the Policy as Code overview.

Get started with OPA policies

github.com/pulumi/pulumi-policy-opa

Authoring CrossGuard Policy with Open Policy Agent (OPA)

Luke Hoban — Fri, 14 Aug 2020 00:00:00 +0000

We’re excited to announce the addition of Open Policy Agent (OPA) Rego language support to Pulumi’s CrossGuard policy-as-code framework. This enables Pulumi CrossGuard policy to be authored in either JavaScript/TypeScript/Python or in the popular Rego language using OPA.

Pulumi’s CrossGuard policy-as-code framework provides the ability to author, apply and enforce policy directly as part of your Pulumi deployments. With the new support for OPA Rego, CrossGuard supports a broad spectrum of policy authoring options, from expressive imperative languages to a popular industry-standard declarative policy language.

OPA-based rules for CrossGuard get all the core benefits of Pulumi’s policy-as-code framework - policies can be run on previews to get warnings about errors before you even deploy, policies can produce either advisory or mandatory recommendations allowing flexibility in flagging and enforcing policy violations, and policies can be applied and enforced across an entire organization through the Pulumi Service.

What is Pulumi CrossGuard?

Pulumi CrossGuard is a policy-as-code framework for enforcing policy across Pulumi infrastructure deployments on any cloud or in Kubernetes. CrossGuard can be used to enforce policy for compliance, security, best practices or cost control.

Pulumi’s web console offers tools to manage and enforce CrossGuard policy across your organization, ensuring that every infrastructure project is held to a high bar on policy compliance.

CrossGuard policy is enforced during previews, ensuring that policy violations are found during development, not just at deployment time. At deployment, policies are enforced on each resource immediately before changes to that resource are applied. As a result, any change that would violate policy is rejected before being applied to your target cloud or Kubernetes environments.

What is OPA?

Open Policy Agent (OPA) provides policy-based control for cloud native environments. OPA provides a single authoring language (Rego) and policy runtime, which can be used to enforce policy in a wide variety of environments including Kubernetes, Envoy, Terraform Kafka, SQL, Linux - and now Pulumi!

The Rego language is declarative, easy to use, and expressive - along with good integration in tools like Visual Studio Code.

Using OPA with Pulumi CrossGuard

To get started with OPA and CrossGuard, start by downloading and installing Pulumi, then get the OPA plugin with:

$ pulumi plugin install analyzer policy-opa v0.0.2
[analyzer plugin policy-opa-0.0.2] installing
Downloading plugin: 6.11 MiB / 6.11 MiB [===========================] 100.00% 0s
Moving plugin... done.

You are now ready to apply OPA-based policies to your Pulumi deployments. Create a folder for your policies named policy-kubernetes and place two files in it - PulumiPolicy.yaml and kubernetes.rego.

Your PulumiPolicy.yaml should look like this. Note that it specifies the runtime to use for the policy rules is opa.

description: A minimal Policy Pack for Kubernetes using OPA.
runtime: opa

Your kubernetes.rego should look like this.

package kubernetes

name = input.metadata.name

labels {
 input.metadata.labels["app.kubernetes.io/name"]
 input.metadata.labels["app.kubernetes.io/instance"]
 input.metadata.labels["app.kubernetes.io/version"]
 input.metadata.labels["app.kubernetes.io/component"]
 input.metadata.labels["app.kubernetes.io/part-of"]
 input.metadata.labels["app.kubernetes.io/managed-by"]
}

deny[msg] {
 input.kind = "Deployment"
 not labels
 msg = sprintf("%s must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels ", [name])
}

The rule above uses the standard OPA Rego language to express a rule that enforces that any Deployment resource in Kubernetes must have a set of defined labels applied to it. All OPA rules used in Pulumi will be applied to an input object, which is a JSON representation of the resource inputs for the Pulumi resource being validated. In particular, for a Kubernetes Deployment resource, this will have top level kind, apiVersion, metadata, and spec fields which can be used to query aspects of the resource for policy enforcement.

To test our rule, we can create a new Pulumi Kubernetes project and deploy it with the policy enforced.

First we create a new project kubeapp in a sibling folder:

$ cd .. && mkdir kubeapp && cd kubeapp
$ pulumi new kubernetes-typescript

This will create a project that deploys a single Kubernetes Deployment (but without our required labels!).

import * as k8s from "@pulumi/kubernetes";
import * as kx from "@pulumi/kubernetesx";

const appLabels = { app: "nginx" };
const deployment = new k8s.apps.v1.Deployment("nginx", {
 spec: {
 selector: { matchLabels: appLabels },
 replicas: 1,
 template: {
 metadata: { labels: appLabels },
 spec: { containers: [{ name: "nginx", image: "nginx" }] }
 }
 }
});
export const name = deployment.metadata.name;

We can deploy this to any Kubernetes cluster (configure your kubectl context locally to point at the desired cluster) with our policy applied with:

$ pulumi up --policy-pack ../policy-kubernetes
Previewing update (dev):
Type Name Plan Info
+ pulumi:pulumi:Stack simple-kubernetes-dev create 1 error
+ └─ kubernetes:apps:Deployment nginx create
Diagnostics:
pulumi:pulumi:Stack (simple-kubernetes-dev):
error: preview failed
Policy Violations:
[mandatory] kubernetes v0.0.1 deny (nginx: kubernetes:apps/v1:Deployment)
nginx-me0llhgr must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels

Note that the preview fails because the policy was violated, preventing me from deploying this resource to my cluster!

The policy defined above has a “mandatory” policy, defined in OPA with deny. We can also define “advisory” policies using warn rules. For example, if we changed our policy from deny to warn and rerun - we will see the preview succeed:

$ pulumi up --policy-pack ../policy-kubernetes
Previewing update (dev2):
Type Name Plan
+ pulumi:pulumi:Stack simple-kubernetes-dev2 create
+ └─ kubernetes:apps:Deployment nginx create
Policy Violations:
[advisory] kubernetes v0.0.1 warn (nginx: kubernetes:apps/v1:Deployment)
nginx-ylgvoqpk must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels

In the previous examples, we manually applied our policy to our deployment with the --policy-pack option. But we can also publish our policy pack to the Pulumi Service and configure it to be enforced across our organization. To do, go back to the policy folder and run pulumi policy publish.

$ cd ../policy-kubernetes
$ pulumi policy publish
Obtaining policy metadata from policy plugin
Compressing policy pack
Uploading policy pack to Pulumi service
Publishing "kubernetes" to "lukehoban"
Published as version 2
Permalink: https://app.pulumi.com/lukehoban/policypacks/kubernetes/2

You can now navigate into the Pulumi Service and configure the new policy to be part of the “default” policy pack (or create a new one), and applied to all stacks in your Organization (or select specify stacks to enforce the policy on).

We can now run our deployment without the --policy-pack argument and our policy will still be enforced on this deployment (and any others done by any other users in our organization)!

$ pulumi up
Previewing update (dev2):
Installing policy pack kubernetes 2...
Finished installing policy pack
Type Name Plan
+ pulumi:pulumi:Stack simple-kubernetes-dev2 create
+ └─ kubernetes:apps:Deployment nginx create
Policy Violations:
[advisory] kubernetes v0.0.1 warn (nginx: kubernetes:apps/v1:Deployment)
nginx-q4ilsuqq must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels
Do you want to perform this update? yes
Updating (dev2):
Type Name Status
+ pulumi:pulumi:Stack simple-kubernetes-dev2 created
+ └─ kubernetes:apps:Deployment nginx created
Policy Violations:
[advisory] kubernetes v0.0.1 warn (nginx: kubernetes:apps/v1:Deployment)
nginx-6ooayw4j must include Kubernetes recommended labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels
Outputs:
name: "nginx-6ooayw4j"
Permalink: https://app.pulumi.com/lukehoban/simple-kubernetes/dev2/updates/1

We can now navigate to the URL for our update and see that the policy was enforced. Note the badge showing that this deployment was protected by policy enforcement and the list of policy violations.

Using OPA Rego with Pulumi

OPA-based rules are easy to write for Pulumi. The input object represents each individual resource that will be deployed by Pulumi, and the rules are applied independently to each Pulumi resource when it is deployed. The schema for each resource is the same as the properties available when defining the resource. Critically, although we highlighted Kubernetes above, Pulumi’s resource model spans any cloud or Kubernetes, with providers for more than 50 Cloud and SaaS platforms available. And OPA-based rules can target any or all of these in a single deployment.

For example - the policy file above could be expanded to include:

# Enforce that AWS EC2 Instance public IP is not enabled
warn[msg] {
 input.associatePublicIpAddress
 msg := "Associating public IP addresses is discouraged"
}

# Enforce that Kubernetes Pod images must be published by `hooli.com`
deny[msg] {
 input.kind == "Pod"
 image := input.spec.containers[_].image
 not startswith(image, "hooli.com/")
 msg := sprintf("image '%v' comes from untrusted registry", [image])
}

With support in Visual Studio Code, authoring both your infrastructure and policy in a rich IDE using Pulumi is also possible.

Conclusion

OPA support in Pulumi CrossGuard enables authoring cloud infrastructure policy using a familiar and popular policy authoring language while leveraging Pulumi’s CrossGuard platform for policy enforcement from development to production. Along with existing support for TypeScript, JavaScript and Python - Pulumi CrossGuard offers a great breadth of authoring languages to meet the needs of any infrastructure team.

Check out the open source pulumi-policy-opa project to learn more about the OPA integration with CrossGuard. And get started with Pulumi for your modern cloud infrastructure and policy today.