Package @pulumi/policy

var policy = require("@pulumi/policy");

import * as policy from "@pulumi/policy";

APIs

• EnforcementLevel
• Policies
• Policy
• PolicyConfigJSONSchema
• PolicyConfigJSONSchemaDefinition
• PolicyConfigJSONSchemaType
• PolicyConfigJSONSchemaTypeName
• PolicyConfigSchema
• PolicyCustomTimeouts
• PolicyPack
• PolicyPackArgs
• PolicyPackConfig
• PolicyProviderResource
• PolicyResource
• PolicyResourceOptions
• ReportViolation
• ResourceValidation
• ResourceValidationArgs
• ResourceValidationPolicy
• StackValidation
• StackValidationArgs
• StackValidationPolicy
• validateResourceOfType
• validateStackResourcesOfType

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 configSchema

configSchema?: PolicyConfigSchema;

This policy’s configuration schema.

For example:

{
    configSchema: {
        properties: {
            expiration: {
                type: "integer",
                default: 14,
            },
            identifier: {
                type: "string",
            },
        },
    },

    validateResource: (args, reportViolation) => {
        const { expiration, identifier } = args.getConfig<{ expiration: number; identifier?: string; }>();

        // ...
    }),
}

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.

interface PolicyConfigJSONSchema

interface PolicyConfigJSONSchema

property additionalItems

additionalItems?: PolicyConfigJSONSchemaDefinition;

property additionalProperties

additionalProperties?: PolicyConfigJSONSchemaDefinition;

property const

const?: PolicyConfigJSONSchemaType;

property contains

contains?: PolicyConfigJSONSchema;

property default

default?: PolicyConfigJSONSchemaType;

property dependencies

dependencies?: undefined | {[key: string]: PolicyConfigJSONSchemaDefinition | string[]};

property description

description?: undefined | string;

property enum

enum?: PolicyConfigJSONSchemaType[];

property exclusiveMaximum

exclusiveMaximum?: undefined | number;

property exclusiveMinimum

exclusiveMinimum?: undefined | number;

property format

format?: undefined | string;

property items

items?: PolicyConfigJSONSchemaDefinition | PolicyConfigJSONSchemaDefinition[];

property maxItems

maxItems?: undefined | number;

property maxLength

maxLength?: undefined | number;

property maxProperties

maxProperties?: undefined | number;

property maximum

maximum?: undefined | number;

property minItems

minItems?: undefined | number;

property minLength

minLength?: undefined | number;

property minProperties

minProperties?: undefined | number;

property minimum

minimum?: undefined | number;

property multipleOf

multipleOf?: undefined | number;

property pattern

pattern?: undefined | string;

property patternProperties

patternProperties?: undefined | {[key: string]: PolicyConfigJSONSchemaDefinition};

property properties

properties?: undefined | {[key: string]: PolicyConfigJSONSchemaDefinition};

property propertyNames

propertyNames?: PolicyConfigJSONSchemaDefinition;

property required

required?: string[];

property type

type?: PolicyConfigJSONSchemaTypeName | PolicyConfigJSONSchemaTypeName[];

property uniqueItems

uniqueItems?: undefined | false | true;

type PolicyConfigJSONSchemaDefinition

type PolicyConfigJSONSchemaDefinition = PolicyConfigJSONSchema | boolean;

type PolicyConfigJSONSchemaType

type PolicyConfigJSONSchemaType = PolicyConfigJSONSchemaType[] | boolean | number | null | object | string;

type PolicyConfigJSONSchemaTypeName

type PolicyConfigJSONSchemaTypeName = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";

interface PolicyConfigSchema

interface PolicyConfigSchema

Represents the configuration schema for a policy.

property properties

properties: {[key: string]: PolicyConfigJSONSchema};

The policy’s configuration properties.

property required

required?: string[];

The configuration properties that are required.

interface PolicyCustomTimeouts

interface PolicyCustomTimeouts

Custom timeout options.

property createSeconds

createSeconds: number;

The create resource timeout.

property deleteSeconds

deleteSeconds: number;

The delete resource timeout.

property updateSeconds

updateSeconds: number;

The update resource timeout.

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, initialConfig?: PolicyPackConfig)

interface PolicyPackArgs

interface PolicyPackArgs

The set of arguments for constructing a PolicyPack.

property enforcementLevel

enforcementLevel?: EnforcementLevel;

Indicates what to do on policy violation, e.g., block deployment but allow override with proper permissions. Default for all policies in the PolicyPack. Individual policies can override.

property policies

policies: Policies;

The policies associated with a PolicyPack.

type PolicyPackConfig

type PolicyPackConfig = {[policy: string]: PolicyConfig};

Represents configuration for the policy pack.

interface PolicyProviderResource

interface PolicyProviderResource

Information about the provider.

property name

name: string;

The name of the provider resource.

property props

props: Record<string, any>;

The properties of the provider resource.

property type

type: string;

The type of the provider resource.

property urn

urn: string;

The URN of the provider resource.

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 dependencies

dependencies: PolicyResource[];

The dependencies of the resource.

property name

name: string;

The name of the resource.

property opts

opts: PolicyResourceOptions;

The options of the resource.

property parent

parent?: PolicyResource;

An optional parent that this resource belongs to.

property propertyDependencies

propertyDependencies: Record<string, PolicyResource[]>;

The set of dependencies that affect each property.

property props

props: Record<string, any>;

The outputs of the resource.

property provider

provider?: PolicyProviderResource;

The provider of the resource.

property type

type: string;

The type of the resource.

property urn

urn: string;

The URN of the resource.

interface PolicyResourceOptions

interface PolicyResourceOptions

PolicyResourceOptions is the bag of settings that control a resource’s behavior.

property additionalSecretOutputs

additionalSecretOutputs: string[];

Outputs that should always be treated as secrets.

property aliases

aliases: string[];

Additional URNs that should be aliased to this resource.

property customTimeouts

customTimeouts: PolicyCustomTimeouts;

Custom timeouts for resource create, update, and delete operations.

property deleteBeforeReplace

deleteBeforeReplace?: undefined | false | true;

When set to true, indicates that this resource should be deleted before its replacement is created when replacement is necessary.

property ignoreChanges

ignoreChanges: string[];

Ignore changes to any of the specified properties.

property protect

protect: boolean;

When set to true, protect ensures this resource cannot be deleted.

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 getConfig

getConfig<T>(): T

Returns configuration for the policy.

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 opts

opts: PolicyResourceOptions;

The options of the resource.

property props

props: Record<string, any>;

The inputs of the resource.

property provider

provider?: PolicyProviderResource;

The provider 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 configSchema

configSchema?: PolicyConfigSchema;

This policy’s configuration schema.

For example:

{
    configSchema: {
        properties: {
            expiration: {
                type: "integer",
                default: 14,
            },
            identifier: {
                type: "string",
            },
        },
    },

    validateResource: (args, reportViolation) => {
        const { expiration, identifier } = args.getConfig<{ expiration: number; identifier?: string; }>();

        // ...
    }),
}

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 stack validation.

method getConfig

getConfig<T>(): T

Returns configuration for the policy.

property resources

resources: PolicyResource[];

The resources in the stack.

interface StackValidationPolicy

interface StackValidationPolicy extends Policy

StackValidationPolicy is a policy that validates a stack.

property configSchema

configSchema?: PolicyConfigSchema;

This policy’s configuration schema.

For example:

{
    configSchema: {
        properties: {
            expiration: {
                type: "integer",
                default: 14,
            },
            identifier: {
                type: "string",
            },
        },
    },

    validateResource: (args, reportViolation) => {
        const { expiration, identifier } = args.getConfig<{ expiration: number; identifier?: string; }>();

        // ...
    }),
}

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) {
        // ...
    }
}),