Package @pulumi/policy

var policy = require("@pulumi/policy");
import * as policy from "@pulumi/policy";

APIs

APIs

type EnforcementLevel

type EnforcementLevel = "advisory" | "mandatory" | "disabled";

Indicates the impact of a policy violation.

type Policies

type Policies = ResourceValidationPolicy | StackValidationPolicy[];

An array of Policies.

interface Policy

interface Policy

A policy function that returns true if a resource definition violates some policy (e.g., “no public S3 buckets”), and a set of metadata useful for generating helpful messages when the policy is violated.

property description

description: string;

A brief description of the policy rule. e.g., “S3 buckets should have default encryption enabled.”

property enforcementLevel

enforcementLevel: EnforcementLevel;

Indicates what to do on policy violation, e.g., block deployment but allow override with proper permissions.

property name

name: string;

An ID for the policy. Must be unique within the current policy set.

class PolicyPack

class PolicyPack

A PolicyPack contains one or more policies to enforce.

For example:

import * as aws from "@pulumi/aws";
import { PolicyPack, validateResourceOfType } from "@pulumi/policy";

new PolicyPack("aws-typescript", {
    policies: [{
        name: "s3-no-public-read",
        description: "Prohibits setting the publicRead or publicReadWrite permission on AWS S3 buckets.",
        enforcementLevel: "mandatory",
        validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
            if (bucket.acl === "public-read" || bucket.acl === "public-read-write") {
                reportViolation("You cannot set public-read or public-read-write on an S3 bucket.");
            }
        }),
    }],
});

constructor

new PolicyPack(name: string, args: PolicyPackArgs)

interface PolicyPackArgs

interface PolicyPackArgs

The set of arguments for constructing a PolicyPack.

property policies

policies: Policies;

The policies associated with a PolicyPack.

interface PolicyResource

interface PolicyResource

PolicyResource represents a resource in the stack.

method asType

asType<TResource>(resourceClass: {
    constructor: ;
}): q.ResolvedResource<TResource> | undefined

Returns the resource if the type of this resource is the same as resourceClass, otherwise undefined.

For example:

const buckets = args.resources
    .map(r = r.asType(aws.s3.Bucket))
    .filter(b => b);
for (const bucket of buckets) {
    // ...
}

method isType

isType<TResource>(resourceClass: {
    constructor: ;
}): boolean

Returns true if the type of this resource is the same as resourceClass.

For example:

for (const resource of args.resources) {
    if (resource.isType(aws.s3.Bucket)) {
        // ...
    }
}

property name

name: string;

The name of the resource.

property props

props: Record<string, any>;

The outputs of the resource.

property type

type: string;

The type of the resource.

property urn

urn: string;

The URN of the resource.

type ReportViolation

type ReportViolation = (message: string, urn?: undefined | string) => void;

ReportViolation is the callback signature used to report policy violations.

type ResourceValidation

type ResourceValidation = (args: ResourceValidationArgs, reportViolation: ReportViolation) => Promise<void> | void;

ResourceValidation is the callback signature for a ResourceValidationPolicy. A resource validation is passed args with more information about the resource and a reportViolation callback that can be used to report a policy violation. reportViolation can be called multiple times to report multiple violations against the same resource. reportViolation must be passed a message about the violation. The reportViolation signature accepts an optional urn argument, which is ignored when validating resources (the urn of the resource being validated is always used).

interface ResourceValidationArgs

interface ResourceValidationArgs

ResourceValidationArgs is the argument bag passed to a resource validation.

method asType

asType<TResource,TArgs>(resourceClass: {
    constructor: ;
}): Unwrap<NonNullable<TArgs>> | undefined

Returns the resource args for resourceClass if the type of this resource is the same as resourceClass, otherwise undefined.

For example:

const bucketArgs = args.AsType(aws.s3.Bucket);
if (bucketArgs) {
    // ...
}

method isType

isType<TResource>(resourceClass: {
    constructor: ;
}): boolean

Returns true if the type of this resource is the same as resourceClass.

For example:

if (args.isType(aws.s3.Bucket)) {
    // ...
}

property name

name: string;

The name of the resource.

property props

props: Record<string, any>;

The properties of the resource.

property type

type: string;

The type of the resource.

property urn

urn: string;

The URN of the resource.

interface ResourceValidationPolicy

interface ResourceValidationPolicy extends Policy

ResourceValidationPolicy is a policy that validates a resource definition.

For example:

import * as aws from "@pulumi/aws";
import { validateResourceOfType } from "@pulumi/policy";

const s3NoPublicReadPolicy: ResourceValidationPolicy = {
    name: "s3-no-public-read",
    description: "Prohibits setting the publicRead or publicReadWrite permission on AWS S3 buckets.",
    enforcementLevel: "mandatory",
    validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
        if (bucket.acl === "public-read" || bucket.acl === "public-read-write") {
            reportViolation("You cannot set public-read or public-read-write on an S3 bucket.");
        }
    }),
};

property description

description: string;

A brief description of the policy rule. e.g., “S3 buckets should have default encryption enabled.”

property enforcementLevel

enforcementLevel: EnforcementLevel;

Indicates what to do on policy violation, e.g., block deployment but allow override with proper permissions.

property name

name: string;

An ID for the policy. Must be unique within the current policy set.

property validateResource

validateResource: ResourceValidation | ResourceValidation[];

A callback function that validates if a resource definition violates a policy (e.g. “S3 buckets can’t be public”). A single callback function can be specified, or multiple functions, which are called in order.

type StackValidation

type StackValidation = (args: StackValidationArgs, reportViolation: ReportViolation) => Promise<void> | void;

StackValidation is the callback signature for a StackValidationPolicy. A stack validation is passed args with more information about the stack and a reportViolation callback that can be used to report a policy violation. reportViolation can be called multiple times to report multiple violations against the stack. reportViolation must be passed a message about the violation, and an optional urn to a resource in the stack that’s in violation of the policy. Not specifying a urn indicates the overall stack is in violation of the policy.

interface StackValidationArgs

interface StackValidationArgs

StackValidationArgs is the argument bag passed to a resource validation.

property resources

resources: PolicyResource[];

The resources in the stack.

interface StackValidationPolicy

interface StackValidationPolicy extends Policy

StackValidationPolicy is a policy that validates a stack.

property description

description: string;

A brief description of the policy rule. e.g., “S3 buckets should have default encryption enabled.”

property enforcementLevel

enforcementLevel: EnforcementLevel;

Indicates what to do on policy violation, e.g., block deployment but allow override with proper permissions.

property name

name: string;

An ID for the policy. Must be unique within the current policy set.

property validateStack

validateStack: StackValidation;

A callback function that validates if a stack violates a policy.

function validateResourceOfType

validateResourceOfType<TResource,TArgs>(resourceClass: {
    constructor: ;
}, validate: (props: Unwrap<NonNullable<TArgs>>, args: ResourceValidationArgs, reportViolation: ReportViolation) => Promise<void> | void): ResourceValidation

A helper function that returns a strongly-typed resource validation function, used to check only resources of the specified resource class.

For example:

validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
    for (const bucket of buckets) {
        // ...
    }
}),

function validateStackResourcesOfType

validateStackResourcesOfType<TResource>(resourceClass: {
    constructor: ;
}, validate: (resources: q.ResolvedResource<TResource>[], args: StackValidationArgs, reportViolation: ReportViolation) => Promise<void> | void): StackValidation

A helper function that returns a strongly-typed stack validation function, used to check only resources of the specified resource class.

For example:

validateStack: validateStackResourcesOfType(aws.s3.Bucket, (buckets, args, reportViolation) => {
    for (const bucket of buckets) {
        // ...
    }
}),

function validateTypedResource

DEPRECATED This is deprecated and will be removed in a future version. Use validateResourceOfType instead.
validateTypedResource<TResource,TArgs>(resourceClass: {
    constructor: ;
}, validate: (props: Unwrap<NonNullable<TArgs>>, args: ResourceValidationArgs, reportViolation: ReportViolation) => Promise<void> | void): ResourceValidation

A helper function that returns a strongly-typed resource validation function, used to check only resources of the specified resource class.