add stack-validation examples (pulumi#1112)

* add stack-validation examples

* Update readme with instructions on how to try it out

policy-packs/stackvalidation-python/.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+venv/

policy-packs/stackvalidation-python/PulumiPolicy.yaml

@@ -0,0 +1,6 @@
+runtime:
+ name: python
+ options:
+ virtualenv: venv
+version: 0.0.1
+description: A minimal Policy Pack for AWS using Python.

policy-packs/stackvalidation-python/README.md

@@ -0,0 +1,32 @@
+# Stack Validation Example - python
+This provides an example of a stack validation policy.
+See [Policy as Code Core Concepts](https://www.pulumi.com/docs/guides/crossguard/core-concepts/) for more information.
+
+In a nutshell, the key differences between stack validation policies and resource validation policies are:
+* Stack validation policies can check resource outputs that are unknown to Pulumi until the provider creates the resource.
+* Stack validation policies can run checks that cross the entire set of resources in the stack.
+
+The example in this folder checks two things:
+* S3 bucket region: Although a bit of a contrived example, the region is an output assigned by AWS and thus is not known before the resource is created and thus is not able to be tested in a resource validation policy.
+* S3 bucket count: Checks the number of S3 buckets created in the stack. This is to show that a stack validation policy has access to the entire stack and not just individual resources like resource valiation policies do.
+
+## Try It Out
+* `mkdir stack-validation && cd stack-validation`
+* `mkdir policy-pack && cd policy-pack`
+ * Copy the stack validation policy pack here.
+ * Set up python virtual environment.
+ * `python3 -m venv ./venv`
+ * `./venv/bin/python -m pip install --upgrade pip setuptools wheel`
+ * `./venv/bin/python -m pip install -r ./requirements.txt`
+* `mkdir ../test-project && cd ../test-project`
+* `pulumi new aws-python`
+ * Note that the Pulumi program and the policy do not need to be written in the same language. So, you can actually use `pulumi new aws-typescript` for the project and this policy will still work.
+* `pulumi config set aws:region us-east-1` 
+ * Or any region other than us-west-1, or change the policy accordingly.
+* Edit `__main__.py` and copy/paste the s3 bucket declaration so you are creating 2 buckets.
+* Run `pulumi up --policy-pack ../policy-pack` to preview and then provision the resources.
+ * Note that the preview portion of the `pulumi up` will NOT trigger the "region" check but will trigger the "count" check.
+ * Once you enter `yes` and the resources are actually provisioned, then you will see the "region" check is triggered. This is because the bucket `region` property being checked in the policy is not known until AWS responds with the resource outputs.
+* Clean Up
+ * `pulumi destroy -y` to clean up resources
+ * `pulumi stack rm dev` to completely remove the stack and project.

policy-packs/stackvalidation-python/__main__.py

@@ -0,0 +1,42 @@
+from pulumi_policy import (
+ EnforcementLevel,
+ PolicyPack,
+ ReportViolation,
+ StackValidationArgs,
+ StackValidationPolicy,
+)
+
+required_region = "us-west-1"
+max_num_buckets = 1
+
+def s3_region_check_validator(stack: StackValidationArgs, report_violation: ReportViolation):
+ for resource in stack.resources:
+ if resource.resource_type == "aws:s3/bucket:Bucket": 
+ if "region" in resource.props and resource.props["region"] != required_region:
+ report_violation(f"Bucket, {resource.name}, must be in region {required_region}")
+
+s3_region_check = StackValidationPolicy(
+ name="s3-region-check",
+ description= "Checks the region the bucket was deployed in.",
+ validate=s3_region_check_validator
+)
+
+def s3_count_check_validator(stack: StackValidationArgs, report_violation: ReportViolation):
+ buckets = list(filter((lambda resource: resource.resource_type == "aws:s3/bucket:Bucket"), stack.resources))
+ if len(buckets) > max_num_buckets:
+ report_violation(f"No more than {max_num_buckets} bucket(s) should be created.")
+
+s3_count_check = StackValidationPolicy(
+ name="s3-count-check",
+ description= "Checks the number of buckets created.",
+ validate=s3_count_check_validator
+)
+
+PolicyPack(
+ name="aws-python",
+ enforcement_level=EnforcementLevel.ADVISORY,
+ policies=[
+ s3_region_check,
+ s3_count_check
+ ],
+)

policy-packs/stackvalidation-python/requirements.txt

@@ -0,0 +1,2 @@
+pulumi-policy>=1.3.0,<2.0.0
+pulumi-aws>=4.0.0,<5.0.0

policy-packs/stackvalidation-ts/.gitignore

@@ -0,0 +1,2 @@
+/bin/
+/node_modules/

policy-packs/stackvalidation-ts/PulumiPolicy.yaml

@@ -0,0 +1,2 @@
+description: A minimal Policy Pack for AWS using TypeScript.
+runtime: nodejs

policy-packs/stackvalidation-ts/README.md

@@ -0,0 +1,29 @@
+# Stack Validation Example - Typescript
+This provides an example of a stack validation policy.
+See [Policy as Code Core Concepts](https://www.pulumi.com/docs/guides/crossguard/core-concepts/) for more information.
+
+In a nutshell, the key differences between stack validation policies and resource validation policies are:
+* Stack validation policies can check resource outputs that are unknown to Pulumi until the provider creates the resource.
+* Stack validation policies can run checks that cross the entire set of resources in the stack.
+
+The example in this folder checks two things:
+* S3 bucket region: Although a bit of a contrived example, the region is an output assigned by AWS and thus is not known before the resource is created and thus is not able to be tested in a resource validation policy.
+* S3 bucket count: Checks the number of S3 buckets created in the stack. This is to show that a stack validation policy has access to the entire stack and not just individual resources like resource valiation policies do.
+
+## Try It Out
+* `mkdir stack-validation && cd stack-validation`
+* `mkdir policy-pack && cd policy-pack`
+ * Copy the stack validation policy pack here.
+ * `npm i`
+* `mkdir ../test-project && cd ../test-project`
+* `pulumi new aws-typescript`
+ * Note that the Pulumi program and the policy do not need to be written in the same language. So, you can actually use `pulumi new aws-python` for the project and this policy will still work.
+* `pulumi config set aws:region us-east-1` 
+ * Or any region other than us-west-1, or change the policy accordingly.
+* Edit `index.ts` and copy/paste the s3 bucket declaration so you are creating 2 buckets.
+* Run `pulumi up --policy-pack ../policy-pack` to preview and then provision the resources.
+ * Note that the preview portion of the `pulumi up` will NOT trigger the "region" check but will trigger the "count" check.
+ * Once you enter `yes` and the resources are actually provisioned, then you will see the "region" check is triggered. This is because the bucket `region` property being checked in the policy is not known until AWS responds with the resource outputs.
+* Clean Up
+ * `pulumi destroy -y` to clean up resources
+ * `pulumi stack rm dev` to completely remove the stack and project.

policy-packs/stackvalidation-ts/index.ts

@@ -0,0 +1,40 @@
+import * as aws from "@pulumi/aws";
+import { PolicyPack, validateStackResourcesOfType } from "@pulumi/policy";
+
+const requiredRegion = "us-west-1"
+const maxNumBuckets = 1
+
+new PolicyPack("stackvalidation-ts", {
+ policies: [
+ {
+ name: "s3-region-check",
+ description: "Checks the region the bucket was deployed in.",
+ enforcementLevel: "advisory", // "mandatory"
+ validateStack: (stack, reportViolation) => {
+ // stack contains all the resources created by the stack. So, loop through them to find S3 buckets and check the region output.
+ for (const resource of stack.resources) {
+ if (resource.type == "aws:s3/bucket:Bucket") {
+ // Check if the region property has been set yet - which it won't on initial preview since AWS hasn't returned that output property yet.
+ // But if is set which will be the case once the stack is created and for subsequent previews, check it.
+ if (resource.props.hasOwnProperty("region") && resource.props.region != requiredRegion) {
+ reportViolation(`Bucket, ${resource.name}, must be in region ${requiredRegion}`)
+ }
+ }
+ }
+ }
+ },
+ {
+ name: "s3-count-check",
+ description: "Checks the number of S3 buckets created in the stack.",
+ enforcementLevel: "advisory", // "mandatory"
+ validateStack: (stack, reportViolation) => {
+ // Gather up all the buckets in the stack.
+ const buckets = stack.resources.filter((resource) => resource.isType(aws.s3.Bucket))
+ // Make sure there no more than the allowed number of buckets.
+ if (buckets.length > maxNumBuckets) {
+ reportViolation(`No more than ${maxNumBuckets} bucket(s) should be created.`)
+ }
+ }
+ }
+ ],
+});

policy-packs/stackvalidation-ts/package.json

@@ -0,0 +1,12 @@
+{
+ "name": "aws-typescript",
+ "version": "0.0.1",
+ "dependencies": {
+ "@pulumi/aws": "^4.0.0",
+ "@pulumi/pulumi": "^3.0.0",
+ "@pulumi/policy": "^1.3.0"
+ },
+ "devDependencies": {
+ "@types/node": "^10.0.0"
+ }
+}

policy-packs/stackvalidation-ts/tsconfig.json

@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "outDir": "bin",
+ "target": "es6",
+ "module": "commonjs",
+ "moduleResolution": "node",
+ "declaration": true,
+ "sourceMap": false,
+ "stripInternal": true,
+ "experimentalDecorators": true,
+ "pretty": true,
+ "noFallthroughCasesInSwitch": true,
+ "noImplicitAny": true,
+ "noImplicitReturns": true,
+ "forceConsistentCasingInFileNames": true,
+ "strictNullChecks": true,
+ },
+ "files": [
+ "index.ts"
+ ]
+}