docs(secure-policy): cross-reference managed_ruleset from custom/managed_policy#737
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Clarifies when to use each Sysdig Secure policy-related Terraform resource by adding cross-referenced notes that explain the differences between managed policies, managed rulesets, and custom policies (including relevant API fields).
Changes:
- Expanded
secure_managed_rulesetdocs with a detailed definition and guidance on related resources. - Added usage guidance notes to
secure_managed_policyandsecure_custom_policyto reduce confusion between resources. - Documented how
isDefaultandtemplateIdrelate to resource choice.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| website/docs/r/secure_managed_ruleset.md | Adds a detailed “what is a managed ruleset” note and directs users to the correct alternative resources. |
| website/docs/r/secure_managed_policy.md | Adds an explicit note limiting usage to Sysdig-shipped default policies and points to alternatives. |
| website/docs/r/secure_custom_policy.md | Adds an explicit note limiting usage to fully custom-authored policies and explains distinguishing API fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Creates a Sysdig Secure Managed Ruleset | ||
| Creates a Sysdig Secure Managed Ruleset. | ||
|
|
||
| -> **Note:** A "managed ruleset" is a customer-owned policy that inherits a Sysdig-managed rule list (`isDefault: false`, `templateId != 0` in the API). The ruleset is locked: you can disable individual rules via `disabled_rules`, but you cannot add new rules or modify rule definitions. To customise scope, notifications, actions, and which rules are enabled while keeping Sysdig's curated rule list, this is the right resource. If you want full control over the rule list (add, remove, edit), use [`sysdig_secure_custom_policy`](secure_custom_policy.md). For tweaking a Sysdig-shipped default policy in place, use [`sysdig_secure_managed_policy`](secure_managed_policy.md). |
| Creates a Sysdig Secure Managed Ruleset | ||
| Creates a Sysdig Secure Managed Ruleset. | ||
|
|
||
| -> **Note:** A "managed ruleset" is a customer-owned policy that inherits a Sysdig-managed rule list (`isDefault: false`, `templateId != 0` in the API). The ruleset is locked: you can disable individual rules via `disabled_rules`, but you cannot add new rules or modify rule definitions. To customise scope, notifications, actions, and which rules are enabled while keeping Sysdig's curated rule list, this is the right resource. If you want full control over the rule list (add, remove, edit), use [`sysdig_secure_custom_policy`](secure_custom_policy.md). For tweaking a Sysdig-shipped default policy in place, use [`sysdig_secure_managed_policy`](secure_managed_policy.md). |
|
|
||
| Creates a Sysdig Secure Custom Policy. | ||
|
|
||
| -> **Note:** Use `sysdig_secure_custom_policy` only for policies you author from scratch (where you own the rule list). For a customer-owned policy that inherits a Sysdig-managed ruleset (e.g. created via "Copy Policy" on a Sysdig-managed policy in the UI), use [`sysdig_secure_managed_ruleset`](secure_managed_ruleset.md) instead. For tweaking a Sysdig-shipped default policy in place, use [`sysdig_secure_managed_policy`](secure_managed_policy.md). The three resources are distinguished by the API's `isDefault` and `templateId` fields: `managed_policy` for `isDefault: true`, `custom_policy` for `templateId: 0`, and `managed_ruleset` for `templateId != 0` with `isDefault: false`. |
There was a problem hiding this comment.
Respectfully disagreeing on this one. The isDefault / templateId partition isn't an implementation detail that might shift - it's the same predicate the provider's own Go code uses as import guards (e.g. resource_sysdig_secure_custom_policy.go:263, resource_sysdig_secure_managed_ruleset.go:228, and similar in the malware/drift/ml policy resources). If the backend semantics ever changed, the provider would break first and the docs would be updated as part of that change. Softening to "currently distinguished by..." would hedge accuracy without making the guidance more correct, and would leave readers genuinely uncertain about whether to trust the resource choice. Leaving as-is.
Picked up the other two comments though - converted the managed_ruleset note to bullets and changed "customise" -> "customize".
…ged_policy Adds note callouts to secure_custom_policy.md and secure_managed_policy.md pointing users at secure_managed_ruleset.md for customer-owned policies that inherit a Sysdig-managed ruleset (isDefault: false, templateId != 0). Also expands the secure_managed_ruleset.md intro to explain when to use it. The three policy resources are partitioned by the API's isDefault and templateId fields, but until now the docs did not make that taxonomy visible from the two most-discovered resources, leading users to assume the customer-owned + template-inheriting case was unsupported. Refs sysdiglabs#736
e4d885e to
8c944cc
Compare
Summary
secure_custom_policy.mdandsecure_managed_policy.mdpointing users atsecure_managed_ruleset.mdfor the customer-owned + template-inheriting casesecure_managed_ruleset.mdintro to make it clear when this resource is the right choiceMotivation
#736 reported that there was no way to manage a policy created by copying a Sysdig-managed policy in the UI (
isDefault: false,templateId != 0). In factsysdig_secure_managed_rulesethandles this case fully (Create, Read, Update, Delete, and Import), but nothing in thecustom_policyormanaged_policydocs surfaces it, so users searching the obvious resource names hit dead ends.Reproduced and verified against provider v3.8.1 on a real tenant:
templateId != 0?sysdig_secure_custom_policysysdig_secure_managed_policysysdig_secure_managed_rulesetTest plan
-> **Note:**convention used elsewhere in these filesRefs #736