Document the default policy groups

[jkodroff]

https://www.pulumi.com/docs/insights/policy/policy-groups/ is missing docs on the default policy groups:

• There's a Default Preventative Policy Group that automatically includes all new stacks. They can be removed.
• There's a Default Audit Policy Group that automatically includes all new insights discovery accounts, which can be removed later.
• Advise caution when adding policy packs to the Default Preventative Policy Group: all clients running Pulumi commands must have the required runtime for the policy pack (all Pulumi-published policy packs require nodejs) <- We need to get the exact requirement here. This should probably be documented in the policy pack concepts page.

[jkodroff]

Adding a related gap: there's also nothing documented on managing the default policy groups programmatically. Below is what I verified empirically against a real org (all operations run and reverted), which should be most of what the docs need.

REST API — full support

A single endpoint covers everything. Being the org default imposes no restrictions.

PATCH https://api.pulumi.com/api/orgs/{org}/policygroups/{policyGroup}
Authorization: token $PULUMI_ACCESS_TOKEN
Content-Type: application/json

Returns 204 No Content with no response body — GET the same path to confirm the change.

Add / remove a stack

API=https://api.pulumi.com/api/orgs/{org}/policygroups/default-policy-group

# add
curl -X PATCH -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"addStack":{"name":"dev","routingProject":"my-project"}}' "$API"

# remove
curl -X PATCH -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"removeStack":{"name":"dev","routingProject":"my-project"}}' "$API"

name is the stack name, routingProject is the project name. Both required.

Add / remove a policy pack

# add
curl -X PATCH -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"addPolicyPack":{"name":"cis-aws","displayName":"cis-aws","version":3,"versionTag":"1.0.2"}}' "$API"

# remove — same payload shape, different field
  -d '{"removePolicyPack":{"name":"cis-aws","displayName":"cis-aws","version":3,"versionTag":"1.0.2"}}'

name, displayName, version (int), and versionTag (string) are all required — worth calling out explicitly in docs, since version and versionTag are distinct and both mandatory. Valid values come from GET /api/orgs/{org}/policypacks. addPolicyPack also optionally accepts config (map tying policies to their configuration) and environments (ESC environment references).

Other fields on the same PATCH

stacks, policyPacks, and insightsAccounts perform a full-list replace when non-nil (omit to leave untouched) — this is an easy footgun worth documenting alongside the additive add*/remove* fields. Also available: addInsightsAccount/removeInsightsAccount, newName, agentPoolId, and a PATCH .../{policyGroup}/batch variant taking an array of these bodies. Note that newName is rejected on the default groups — see the restrictions section below.

What the default groups do not allow

Verified against a real org. The useful generalization: the default groups are fixed in identity — name, mode, existence — and mutable only in membership. That single sentence is probably what the docs need most.

Operation	Default groups	Enforcement
Add / remove stack	✅ Yes	204
Add / remove policy pack	✅ Yes	204
Rename via newName	❌ No	400 Bad Request: cannot rename default Policy Group
Change mode	❌ No	no mode field exists in UpdatePolicyGroupRequest
Delete	❌ No	400, documented in the spec

Two of these are not currently discoverable from the OpenAPI spec, which is worth fixing alongside the docs page:

• DELETE documents its restriction well — the description states "The organization's default Policy Group cannot be deleted" and there's a dedicated 400 Cannot delete the default Policy Group response.
• PATCH does not. It describes newName as simply "rename the policy group" / "The new name to assign to the policy group", with only a generic 400 Bad Request response. The default-group exemption is real but discoverable only by hitting it.
• mode being creation-only isn't stated anywhere either; it's inferable only from its absence in the update schema. NewPolicyGroupRequest defaults it to preventative for stack groups and audit for account groups.

Practical consequence: since the preventative default can't be deleted, renamed, or switched to audit mode, emptying its policy pack list is the only way to neutralize it.

Pulumi Service Provider — stacks yes, policy packs no

Stacks are supported. pulumiservice:api:PolicyGroupStackAttachment (shipped in released v1.3.0) manages a single membership edge against any named group, including the defaults:

resources:
  attach:
    type: pulumiservice:api:PolicyGroupStackAttachment
    properties:
      orgName: my-org
      policyGroup: default-policy-group
      name: dev                    # stack name
      routingProject: my-project   # project name

pulumi up adds the stack, pulumi destroy removes it. ID format {orgName}/{policyGroup}/{name}/{routingProject}. It's intentionally diff-free — one edge per resource, all inputs replace-on-change — and creates are additive server-side, so parallel attachments to the same group don't clobber one another. There's a matching PolicyGroupInsightsAccountAttachment for the accounts-type default group.

Policy packs are not supported declaratively. There is no PolicyGroupPolicyPackAttachment resource. The only declarative route is importing the group itself:

pulumi import pulumiservice:api:PolicyGroup defgroup "{org}/default-policy-group"

That works, but is awkward for a default group, and the docs should probably warn against it:

• Import emits only name, orgName, and entityType: "" — it does not populate stacks or policyPacks, so the packs list has to be hand-written.
• policyPacks is full-list replace, so declaring it overwrites whatever is currently applied. (Omitting stacks does safely leave existing memberships alone.)
• The resource is create/delete-owned, so pulumi destroy calls DeletePolicyGroup on the org default. Import sets protect: true, which should stay.

Practical recommendation for the docs: use PolicyGroupStackAttachment for stack membership and the REST PATCH for policy packs. Mixing import-based ownership of a default group with attachment resources pointed at the same group means the two fight over the stacks/policyPacks lists.

Two caveats worth surfacing in the docs

1. This reinforces the caution already in the issue description: because the Default Preventative Policy Group is preventative and auto-includes every stack, a pack attached there begins blocking pulumi up on violating stacks immediately, with no soft-rollout path. Recommended pattern is to stage a new pack in an audit-mode group first, then promote. This matters more given the restrictions above — you can't soften the blast radius after the fact by flipping the default group to audit mode, since mode is creation-only.
2. If the CLI is pointed at a non-Pulumi-Cloud backend, the service provider derives its API URL from PULUMI_BACKEND_URL and fails with unsupported protocol scheme "file". Fix is pulumi config set pulumiservice:apiUrl https://api.pulumi.com. Not an issue on a normal pulumi login to Pulumi Cloud, but it bites when testing against local state.