1. Docs
  2. Insights & Governance
  3. Policies
  4. Policy Packs
  5. Policy Pack Project File

Policy Pack Project File Reference

    Every Pulumi policy pack has a project file, PulumiPolicy.yaml, that specifies metadata about the policy pack such as its runtime and version. This file is analogous to the Pulumi.yaml project file used by Pulumi IaC programs. The file must be named PulumiPolicy.yaml (case-sensitive) and placed in the root of your policy pack directory.

    When you create a new policy pack with pulumi policy new, the CLI generates this file automatically.

    Select your policy pack runtime to see the relevant attributes and examples:

    Attributes

    NameRequiredDescription
    runtimerequiredMust be nodejs. Can be a string or an object with name and options fields. See runtime options.
    versionoptionalThe version of the policy pack, following semantic versioning. Overrides the version in package.json when set.
    mainoptionalPath to the policy pack entry point, relative to PulumiPolicy.yaml. Defaults to the directory containing PulumiPolicy.yaml.
    descriptionoptionalA brief description of the policy pack.
    authoroptionalThe author of the policy pack.
    websiteoptionalA URL for the policy pack’s website or repository.
    licenseoptionalThe license for the policy pack (e.g., Apache-2.0, MIT).
    NameRequiredDescription
    runtimerequiredMust be python. Can be a string or an object with name and options fields. See runtime options.
    versionoptionalThe version of the policy pack, following semantic versioning. This is the primary way to set the version for Python packs.
    mainoptionalPath to the policy pack entry point, relative to PulumiPolicy.yaml. Defaults to the directory containing PulumiPolicy.yaml.
    descriptionoptionalA brief description of the policy pack.
    authoroptionalThe author of the policy pack.
    websiteoptionalA URL for the policy pack’s website or repository.
    licenseoptionalThe license for the policy pack (e.g., Apache-2.0, MIT).

    OPA (Open Policy Agent) policy packs let you write policies in Rego instead of TypeScript or Python. Install the analyzer plugin with pulumi plugin install analyzer policy-opa.

    NameRequiredDescription
    runtimerequiredMust be opa.
    versionoptionalThe version of the policy pack, following semantic versioning.
    descriptionoptionalA brief description of the policy pack.
    inputFormatoptionalControls how resource properties are structured before OPA evaluation. Set to kubernetes-admission to enable Kubernetes Admission Controller compatibility. When omitted, resources use the default Pulumi OPA input structure.

    runtime options

    The runtime attribute can be a simple string or an object with additional options.

    Simple form:

    runtime: nodejs

    Object form:

    runtime:
  name: nodejs

    The Node.js runtime does not have additional options specific to policy packs.

    The runtime attribute can be a simple string or an object with additional options.

    Simple form:

    runtime: python

    Object form with options:

    runtime:
  name: python
  options:
    virtualenv: venv

    The following option is available:

    NameDescription
    virtualenvPath to a Python virtual environment to use when running the policy pack. Defaults to venv for new projects created with pulumi policy new. Pulumi automatically creates the virtual environment and installs dependencies from requirements.txt into it.

    When virtualenv is set, Pulumi manages the virtual environment for you. If you prefer to manage it yourself (for example, with Pipenv), remove the virtualenv option and use the simple string form.

    For more details on Python dependency management in policy packs, see the Policies FAQ.

    The opa runtime is always specified as a simple string and has no additional options:

    runtime: opa

    inputFormat

    The inputFormat field is specific to OPA policy packs. The only supported value is kubernetes-admission, which wraps Kubernetes resources in the OPA Gatekeeper AdmissionReview structure before evaluation. This lets you reuse existing Gatekeeper constraint templates (.rego files) with Pulumi without modification.

    When inputFormat: kubernetes-admission is set:

    • Kubernetes resources are presented as input.review.object with input.review.kind, input.review.name, and input.review.namespace fields, matching the Gatekeeper schema.
    • Non-Kubernetes resources are silently skipped.
    • Per-rule policy configuration is injected as input.parameters for Gatekeeper Constraint compatibility.
    • Pulumi-specific metadata (URN, options, provider) is available via input._pulumi.
    • Both the Gatekeeper violation[{"msg": ...}] map format and the standard string-based rule format are supported.

    For more details, see the Pulumi OPA Policy Bridge documentation.

    Version handling

    The version is read from package.json by default. If a version field is set in PulumiPolicy.yaml, it takes precedence over package.json.

    Each version can only be published once. When you publish a new version, update the version number before running pulumi policy publish. See managing policy pack versions for details.

    The version is read from the version field in PulumiPolicy.yaml. There is no fallback file.

    Each version can only be published once. When you publish a new version, update the version number before running pulumi policy publish. See managing policy pack versions for details.

    The version is read from the version field in PulumiPolicy.yaml.

    Each version can only be published once. When you publish a new version, update the version number before running pulumi policy publish.

    Examples

    Minimal:

    runtime: nodejs

    Full-featured:

    runtime: nodejs
version: 1.2.0
main: src/
description: Acme Corp security and compliance policies
author: Platform Team
website: https://github.com/acme/policy-packs
license: Apache-2.0

    Minimal:

    runtime:
  name: python
  options:
    virtualenv: venv

    Full-featured:

    runtime:
  name: python
  options:
    virtualenv: venv
version: 1.2.0
main: src/
description: Acme Corp security and compliance policies
author: Platform Team
website: https://github.com/acme/policy-packs
license: Apache-2.0

    Minimal:

    runtime: opa
description: AWS security policies

    With version and Kubernetes Admission Controller compatibility:

    runtime: opa
version: 1.0.0
description: Kubernetes Gatekeeper policies
inputFormat: kubernetes-admission