WIP

content/docs/iac/using-pulumi/crossguard/_index.md

@@ -20,7 +20,7 @@ aliases:
 
 CrossGuard is Pulumi's Policy as Code offering. CrossGuard empowers you to set guardrails to enforce compliance for resources so developers within an organization can provision their own infrastructure while sticking to best practices and security compliance. Using Policy as Code, you can write flexible business or security policies.
 
-Using CrossGuard, organization administrators can apply these rules to particular stacks within their organization. When policies are executed as part of your Pulumi deployments, any violation will gate or block that update from proceeding. Policy remediations also allow you to automatically fix violations.
+Using CrossGuard, organization administrators can apply these rules to particular stacks and account within their organization. When policies are executed as part of your Pulumi deployments, any violation will gate or block that update from proceeding. Policy remediations also allow you to automatically fix violations.
 
 Learn more about [Policy as Code core concepts](/docs/using-pulumi/crossguard/core-concepts/).
 
@@ -48,7 +48,7 @@ With Pulumi Compliance Ready Policies, you get a comprehensive set of predefined
 
 ## Pulumi CrossGuard policies for AWS (AWSGuard)
 
-In addition to being able to implement your own CrossGuard policies, or use the Compliance Ready policies, we've also created a set of policies that codifies best practices for AWS that you can adopt and use in a Policy Pack. AWSGuard is a configurable library that you can use to enforce best practices for your own Pulumi stacks or organization. [Learn more and get started with AWSGuard](/docs/using-pulumi/crossguard/awsguard/).
+In addition to being able to implement your own CrossGuard policies, or use the Compliance Ready policies, we've also created a set of policies that codifies best practices for AWS that you can adopt and use in a Policy Pack. AWSGuard is a configurable library that you can use to enforce best practices for your own Pulumi resources. [Learn more and get started with AWSGuard](/docs/using-pulumi/crossguard/awsguard/).
 
 ## Configuring Policy Packs
 

content/docs/iac/using-pulumi/crossguard/core-concepts.md

@@ -26,8 +26,9 @@ Policies can be written in TypeScript/JavaScript (Node.js) or Python and can be
 
 A *Policy* contains specific logic you would like to enforce. For example, you may want to prevent the creation of public, world-readable storage objects. (e.g. on AWS S3, Azure BlobStore, etc.) or prevent the creation of a virtual machine without the proper security groups in-place.
 
-Policies are written as validation functions that are evaluated against resources in your Pulumi stack. If the validation function calls {{< policy-reportviolation >}}, the associated resource will be considered in violation of the policy. {{< policy-reportviolation >}} can be called multiple times to report multiple violations.
+Policies are written as validation functions that are evaluated against resources in your Pulumi stack or account. If the validation function calls {{< policy-reportviolation >}}, the associated resource will be considered in violation of the policy. {{< policy-reportviolation >}} can be called multiple times to report multiple violations.
 
+TODO: following lines are specific to IaC -- may want to split into a separate section
 Policies may also define *remediations* to automatically fix violations rather than report them. A remediation is written as a function that transforms a resource's state so that it complies with the policy. The resource will be configured using the transformed state.
 
 Policies are executed during `pulumi preview` and `pulumi up`, ensuring that cloud resource definitions comply with the policy immediately before they are created or updated. During preview, every resource is checked for policy violations, which are batched up into a final report. Policy violations may show up as warnings, or errors which halt the deployment.
@@ -78,18 +79,19 @@ There are no restrictions on which policies you combine within a pack, and you s
 
 There are two broad types of policies:
 
-1. *Resource Policies*: These validate a particular resource in a stack before the resource is created or updated, looking at the resource's _input_ properties.
+1. *Resource Policies*: These validate a particular resource in a stack or account before the resource is created or updated, looking at the resource's _input_ properties.
 2. *Stack Policies*: These validate validates all resources in the stack after they've been created/updated, but before the Pulumi preview/update has completed, looking at each resource's _output_ properties.
 
 This table summarizes the primary differences between the two types:
 
-|                                | Resource Policies                     | Stack Policies                                                                       |
-|--------------------------------|---------------------------------------|--------------------------------------------------------------------------------------|
-| What does it check?            | Individual resources                  | All resources in the stack                                                           |
-| When is the check performed?   | Before resources are created/modified | After all stack resources have been created/modified                                 |
-| Can it remediate?              | Yes                                   | No                                                                                   |
-| What information is available? | Resource _input_ properties           | Resource _output_ properties (Note: inputs are propagated to outputs during preview) |
-| What is the type name?         | `ResourceValidationPolicy`            | `StackValidationPolicy`                                                              |
+|                                | Resource Policies                     | Stack Policies                                                                        |
+|--------------------------------|---------------------------------------|---------------------------------------------------------------------------------------|
+| What does it check?            | Individual resources                  | All resources in the stack                                                            |
+| When is the check performed?   | Before resources are created/modified | After all stack resources have been created/modified                                  |
+| Can it remediate?              | Yes                                   | No                                                                                    |
+| What information is available? | Resource _input_ properties           | Resource _output_ properties (Note: inputs are propagated to outputs during preview)  |
+| What is the type name?         | `ResourceValidationPolicy`            | `StackValidationPolicy`                                                               |
+| Supported for Insights?        | Yes                                   | No - IaC-specific feature                                                             |
 
 ### Enforcement Levels
 
@@ -104,7 +106,13 @@ The enforcement level can be specified in multiple ways: on the definition of a
 
 ### Resource Policies
 
-Policies of `ResourceValidationPolicy` validate against a particular resource in a stack. These policies are run before a resource is registered and thus block an out-of-compliance resource from ever being created. Resource policies can validate compliance and report violations, remediate violations automatically, or do both.
+Policies of `ResourceValidationPolicy` validate against a particular resource in a stack or account. 
+
+TODO: IaC-specific
+These policies are run before a resource is registered and thus block an out-of-compliance resource from ever being created. Resource policies can validate compliance and report violations, remediate violations automatically, or do both.
+
+TODO: Insights-specific info:
+A policy violation indicates that the most recent version of a discovered resource failed a policy check. Policy violations for Insights resources are informational rather than preventative since the resource state is discovered, but not managed, by Pulumi.
 
 #### Resource Validation
 
@@ -220,6 +228,7 @@ elb_logging_enabled = ResourceValidationPolicy(
 
 #### Resource Remediation
 
+TODO: This section is IaC-specific
 A policy may define a remediation which is similarly given `args` with information about the resource. Instead of reporting violations, however, the remediation may alter and return resource properties. The Pulumi engine will use these new properties in place of the original ones passed to the remediation function.
 
 Here is an example resource policy remediation. Similar to resource validation, in TypeScript/JavaScript this example uses the `remediateResourceOfType` helper to filter and add strong typing:
@@ -273,6 +282,7 @@ Remediations are order dependent because multiple remediations may mutate the sa
 
 #### Defining Resource Validations and Remediations Together
 
+TODO: This section is IaC-specific
 It is possible to define a resource validation and remediation together. This allows a policy to function as both when the enforcement level is set to {{< policy-enforcementlevel-remediate >}} in addition to when it is not. It also serves as a sort of belts-and-suspenders "test" since, if the validation fails, it means the remediation failed to do its job.
 
 This can be done simply by specifying both a `validate` and a `remediate` on the policy definition. However, this can lead to code duplication. That is sometimes unavoidably, but it is also possible to remediate and validate with a single function:
@@ -389,6 +399,7 @@ In this example, the `password` property will be encrypted using the stack's sec
 
 ### Stack Policies
 
+TODO: this section is IaC-specific
 Policies of `StackValidationPolicy` are run against all the resources in a stack. These policies are run after all stack resources are registered and thus *do not* block an out-of-compliance resource from being created, but do fail the preview or update. To avoid creating out-of-compliance resources, we recommend always running a preview command before an update. This allows you to write policies where one resource depends on the state or existence of another resource.
 
 The below example requires that all dynamoDB tables have an App Autoscaling Policy associated with it.
@@ -455,14 +466,17 @@ The [Pulumi Policy Packs examples repository](https://github.com/pulumi/examples
 
 ## Policy Groups
 
-A *Policy Group* is a group of stacks with the same set of Policy Packs enforced. Policy Groups are only available from within the Pulumi Cloud when CrossGuard is enabled. A stack may belong to multiple Policy Groups. An example use of Policy Groups is to have a different group per environment. For example, you can have one for your stacks in production and a more permissive Policy Group for your other environments such as `staging` and `dev`.
+A *Policy Group* is a group of stacks and accounts with the same set of Policy Packs enforced. Policy Groups are only available from within the Pulumi Cloud when CrossGuard is enabled. A stack or account may belong to multiple Policy Groups. An example use of Policy Groups is to have a different group per environment. For example, you can have one for your stacks in production and a more permissive Policy Group for your other environments such as `staging` and `dev`.
 
-Organization admins can create new Policy Groups, add stacks to a Policy Group, or remove stacks from a group.
+Organization admins can create new Policy Groups, add stacks and accounts to a Policy Group, or remove stacks and accounts from a group.
 
 Each Policy Group has its own set of enforced Policy Packs. An organization administrator can add, remove, or update the version of the Policy Pack enforced on the Policy Group.
 
-In cases where a stack belongs to multiple Policy Groups and is therefore required to run multiple versions of the same Policy Pack, only the latest version of the Policy Pack gets enforced. For example, if `my-stack` belongs to two Policy Groups and you want to enforce `my-aws-policy-pack` versions 2 and 3, only version 3 will be enforced. You may view the Policy Groups a stack belongs to as well as the currently enforced Policy Packs for the stack by navigating to a stack’s `Settings` tab and then `Policies`.
+In cases where a stack or account belongs to multiple Policy Groups and is therefore required to run multiple versions of the same Policy Pack, only the latest version of the Policy Pack gets enforced. For example, if `my-stack` belongs to two Policy Groups and you want to enforce `my-aws-policy-pack` versions 2 and 3, only version 3 will be enforced. 
+
+You may view the Policy Groups a stack belongs to as well as the currently enforced Policy Packs for the stack by navigating to a stack’s `Settings` tab and then `Policies`.
+You may view the Policy Groups an account belongs to as well as the currently enforced Policy Packs for the account by navigating to a account's `Settings` tab and then `Policies`. TODO: not implemented yet
 
 ### Default Policy Group
 
-Every organization has a default Policy Group. When the default Policy Group is created, all stacks in your organization are automatically added to that Policy Group. Additionally, all stacks that are created after adding the default Policy Group are automatically added to it. Organization admins can remove stacks from the default Policy Group as desired.
+Every organization has a default Policy Group. When the default Policy Group is created, all stacks and accounts in your organization are automatically added to that Policy Group. Additionally, all stacks and accounts that are created after adding the default Policy Group are automatically added to it. Organization admins can remove stacks and accounts from the default Policy Group as desired.

content/docs/iac/using-pulumi/crossguard/faq.md

@@ -30,13 +30,14 @@ Policy Packs enforced by the Pulumi Cloud are always run by the Pulumi CLI.
 
 Therefore, if a Policy Pack is specified locally using `--policy-pack`, the Pulumi CLI will run the local Policy Pack as well as the Policy Packs enforced by the Pulumi Cloud. A violation by any of the Policy Packs would halt an update.
 
-## What happens if a stack belongs to multiple Policy Groups?
+## What happens if a stack or account belongs to multiple Policy Groups?
 
-If a stack belongs to multiple Policy Groups, the Pulumi Cloud will aggregate all required Policy Packs from those Policy Groups. Only one of version of each Policy Pack will be run per update.
+If a stack or account belongs to multiple Policy Groups, the Pulumi Cloud will aggregate all required Policy Packs from those Policy Groups. Only one of version of each Policy Pack will be run per update.
 
 This means that if a stack belongs to multiple Policy Groups that specify different versions of a Policy Pack, only the newest version of that pack will be run. For example, if a stack `my-stack` belongs to Policy Group `production-stacks` that requires Policy Pack `aws-policies` version 2 and Policy Group `platform-stacks` that requires Policy Pack `aws-policies` version 4, only version 4 of `aws-policies` would be run. In the case that a stack has the same version of a Policy Pack with different configuration enabled, the most recently modified Policy Pack and configuration will be enforced.
 
 Under a stack's "Settings" tab you can take a look at the Policy Packs that would be enforced on a `preview` or `update` as well as the Policy Groups that the stack belongs to.
+// TODO: update for accounts
 
 ![Stack Policy Settings](/images/docs/guides/crossguard/stack-policies.jpg)
 
@@ -48,9 +49,13 @@ During `pulumi refresh`, no resources are modified. This command updates the sta
 
 ## What happens if I add a Policy Pack that causes an existing resource to become out-of-compliance?
 
-The next preview or update of the stack with fail due to the policy violation. The stack will need to be fixed before it can be updated.
+For stacks:
 
-A stack with out-of-compliance resources can be destroyed.
+The next preview or update of the stack with fail due to the policy violation. The stack will need to be fixed before it can be updated. A stack with out-of-compliance resources can be destroyed.
+
+For accounts:
+
+A policy violation will be added to any account resources that are out of compliance. Policy violations for Insights resources are informational rather than preventative since the resource state is discovered, but not managed, by Pulumi.
 
 ## How do I version a Policy Pack?
 

content/docs/iac/using-pulumi/crossguard/get-started.md

@@ -25,7 +25,7 @@ Pulumi CrossGuard is a product that provides gated deployments via Policy as Cod
 
 Often organizations want to empower developers to manage their infrastructure yet are concerned about giving them full access. CrossGuard allows administrators to provide autonomy to their developers while ensuring compliance to defined organization policies.
 
-Using Policy as Code, users can express business or security rules as functions that are executed against resources in their stacks. Then using CrossGuard, organization administrators can apply these rules to particular stacks within their organization. When policies are executed as part of your Pulumi deployments, any violation will gate or block that update from proceeding.
+Using Policy as Code, users can express business or security rules as functions that are executed against resources in their stacks or accounts. Then using CrossGuard, organization administrators can apply these rules to particular stacks or accounts within their organization. When policies are executed as part of your Pulumi deployments, any violation will gate or block that update from proceeding.
 
 Policies can be written in TypeScript/JavaScript (Node.js) or Python and can be applied to Pulumi stacks written in any language. Learn more about [language support for policies](/docs/guides/crossguard#languages).
 
@@ -167,6 +167,8 @@ You can find more example Policy Packs in the [examples repo](https://github.com
 
 ### Running Locally {#running-locally}
 
+TODO: this only applies to IaC. Insights is cloud-only.
+
 Now let's take a look at how to run the Policy Pack locally against a Pulumi program.
 
 {{< chooser language "typescript,python" >}}
@@ -327,6 +329,8 @@ Once you’ve validated the behavior of your policies, an organization administr
 
     The CLI by default enables the Policy Pack to your default Policy Group. If you would like to add the Policy Pack to a different Policy Group, you can use the `--policy-group` flag.
 
+TODO: May want to add a section about Policy Groups or link to the info under core-concepts.md
+
 ## Next Steps
 
 Now that you have published your first Policy Pack, you now have all the tools needed to enforce compliance amongst your organization. For more example Policy Packs, you can check out the [examples repo](https://github.com/pulumi/examples/tree/master/policy-packs). You can also find more documentation in the [CrossGuard guide](/docs/using-pulumi/crossguard/).