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) {
// ...
}
}),
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.