Manage Kestra Governance Policies with the Terraform Provider

Terraform Resource: kestra_policy

Manages a Kestra governance Policy (EE) at the INSTANCE, TENANT or NAMESPACE scope. A policy bundles mutate and validate rules applied to flows and plugins; its YAML source is persisted by the API and round-tripped verbatim. STATIC policies are declared in the Kestra configuration and cannot be managed through the API.

Example usage

# A tenant-scope policy narrowed to a namespace subtree
resource "kestra_policy" "tenant" {
  scope     = "TENANT"
  policy_id = "deny-shell-commands"

  content = <<EOT
id: deny-shell-commands
displayName: Deny shell commands
description: Disallow the shell Commands plugin on the data teams
enforcement: ACTIVE
target:
  namespaces:
    - company.team
rules:
  - type: io.kestra.plugin.ee.rules.Deny
    on: PLUGIN
    action: BLOCK
    errorMessage: Shell commands are not allowed
    where:
      - field: type
        operator: EQUAL_TO
        value: io.kestra.plugin.scripts.shell.Commands
EOT
}

# A namespace-scope policy requiring an owner label on every flow
resource "kestra_policy" "namespace" {
  scope     = "NAMESPACE"
  policy_id = "require-owner-label"
  namespace = "company.team"

  content = <<EOT
id: require-owner-label
rules:
  - type: io.kestra.plugin.ee.rules.Require
    on: FLOW
    properties:
      - labels.owner
    errorMessage: Flows must carry an owner label
EOT
}

# An instance-scope policy (super-admin only), narrowed to some tenants
resource "kestra_policy" "instance" {
  scope     = "INSTANCE"
  policy_id = "inject-http-timeout"

  content = <<EOT
id: inject-http-timeout
target:
  tenants:
    - production
rules:
  - type: io.kestra.plugin.ee.rules.Add
    on: PLUGIN
    where:
      - field: type
        operator: EQUAL_TO
        value: io.kestra.plugin.core.http.Request
    values:
      options:
        readTimeout: PT30S
EOT
}

Schema

Required

• content (String) The policy YAML source: id, optional displayName, description, enforcement (defaults to ACTIVE) and target, and the non-empty rules list mixing mutate rules (io.kestra.plugin.ee.rules.Add, Delete) and validate rules (Deny, Require, Restrict). The scope, tenant and namespace are carried by the resource attributes, never by the content. Diffs are compared semantically, so a change that only reindents, reorders keys or edits comments produces no plan and the source persisted by the API keeps its previous formatting; change a value to push a reformatted source.
• policy_id (String) The policy id — a lowercase RFC 1123 label, unique per (scope, tenant, namespace). Must match the id of the YAML content.
• scope (String) The policy scope: INSTANCE (deployment-wide, super-admin only), TENANT or NAMESPACE.

Optional

• namespace (String) The namespace the policy is attached to. Required for the NAMESPACE scope, must not be set otherwise.
• tenant_id (String) The tenant id, for TENANT and NAMESPACE scopes. Defaults to the provider tenant when omitted; the value is captured at create time, so changing the provider tenant later does not retarget existing policies. Must not be set for the INSTANCE scope.

Import

Import is supported using the following syntax:

The terraform import command can be used, for example:

terraform import kestra_policy.instance INSTANCE/{{policy_id}}
terraform import kestra_policy.tenant TENANT/{{tenant_id}}/{{policy_id}}
terraform import kestra_policy.namespace NAMESPACE/{{tenant_id}}/{{namespace}}/{{policy_id}}