diff --git a/public/docs/i/1000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp b/public/docs/i/1000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp new file mode 100644 index 0000000000..dcf8196872 Binary files /dev/null and b/public/docs/i/1000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp differ diff --git a/public/docs/i/1000/platform-hub/policies/example-of-policy-with-two-conditions.webp b/public/docs/i/1000/platform-hub/policies/example-of-policy-with-two-conditions.webp new file mode 100644 index 0000000000..f41a6d0f64 Binary files /dev/null and b/public/docs/i/1000/platform-hub/policies/example-of-policy-with-two-conditions.webp differ diff --git a/public/docs/i/1000/platform-hub/policies/policy-violation-user-message.webp b/public/docs/i/1000/platform-hub/policies/policy-violation-user-message.webp new file mode 100644 index 0000000000..4bbfd15d52 Binary files /dev/null and b/public/docs/i/1000/platform-hub/policies/policy-violation-user-message.webp differ diff --git a/public/docs/i/2000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp b/public/docs/i/2000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp new file mode 100644 index 0000000000..f796d2bd95 Binary files /dev/null and b/public/docs/i/2000/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp differ diff --git a/public/docs/i/2000/platform-hub/policies/example-of-policy-with-two-conditions.webp b/public/docs/i/2000/platform-hub/policies/example-of-policy-with-two-conditions.webp new file mode 100644 index 0000000000..635d2a166d Binary files /dev/null and b/public/docs/i/2000/platform-hub/policies/example-of-policy-with-two-conditions.webp differ diff --git a/public/docs/i/2000/platform-hub/policies/policy-violation-user-message.webp b/public/docs/i/2000/platform-hub/policies/policy-violation-user-message.webp new file mode 100644 index 0000000000..c4118dbc21 Binary files /dev/null and b/public/docs/i/2000/platform-hub/policies/policy-violation-user-message.webp differ diff --git a/public/docs/i/600/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp b/public/docs/i/600/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp new file mode 100644 index 0000000000..11445bf381 Binary files /dev/null and b/public/docs/i/600/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.webp differ diff --git a/public/docs/i/600/platform-hub/policies/example-of-policy-with-two-conditions.webp b/public/docs/i/600/platform-hub/policies/example-of-policy-with-two-conditions.webp new file mode 100644 index 0000000000..9228b216cd Binary files /dev/null and b/public/docs/i/600/platform-hub/policies/example-of-policy-with-two-conditions.webp differ diff --git a/public/docs/i/600/platform-hub/policies/policy-violation-user-message.webp b/public/docs/i/600/platform-hub/policies/policy-violation-user-message.webp new file mode 100644 index 0000000000..90fb3d9c4a Binary files /dev/null and b/public/docs/i/600/platform-hub/policies/policy-violation-user-message.webp differ diff --git a/public/docs/i/x/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png b/public/docs/i/x/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png new file mode 100644 index 0000000000..6f6f5b0467 Binary files /dev/null and b/public/docs/i/x/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png differ diff --git a/public/docs/i/x/platform-hub/policies/example-of-policy-with-two-conditions.png b/public/docs/i/x/platform-hub/policies/example-of-policy-with-two-conditions.png new file mode 100644 index 0000000000..b21758ab6c Binary files /dev/null and b/public/docs/i/x/platform-hub/policies/example-of-policy-with-two-conditions.png differ diff --git a/public/docs/i/x/platform-hub/policies/policy-violation-user-message.png b/public/docs/i/x/platform-hub/policies/policy-violation-user-message.png new file mode 100644 index 0000000000..3476a5d790 Binary files /dev/null and b/public/docs/i/x/platform-hub/policies/policy-violation-user-message.png differ diff --git a/public/docs/img/platform-hub/platform-hub-policies-overview-page.png.json b/public/docs/img/platform-hub/platform-hub-policies-overview-page.png.json index 75f4729184..ab8bc66e99 100644 --- a/public/docs/img/platform-hub/platform-hub-policies-overview-page.png.json +++ b/public/docs/img/platform-hub/platform-hub-policies-overview-page.png.json @@ -1 +1 @@ -{"width":2391,"height":1936,"updated":"2025-09-15T06:34:44.683Z"} \ No newline at end of file +{"width":2391,"height":1936,"updated":"2025-09-19T07:36:25.728Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png b/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png new file mode 100644 index 0000000000..838099db4c Binary files /dev/null and b/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png differ diff --git a/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png.json b/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png.json new file mode 100644 index 0000000000..94d1756169 --- /dev/null +++ b/public/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png.json @@ -0,0 +1 @@ +{"width":2193,"height":1807,"updated":"2025-09-19T07:36:25.753Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png b/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png new file mode 100644 index 0000000000..4226d5748b Binary files /dev/null and b/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png differ diff --git a/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png.json b/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png.json new file mode 100644 index 0000000000..ddc2f1c612 --- /dev/null +++ b/public/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png.json @@ -0,0 +1 @@ +{"width":1676,"height":766,"updated":"2025-09-19T07:36:25.813Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/policies/policy-violation-user-message.png b/public/docs/img/platform-hub/policies/policy-violation-user-message.png new file mode 100644 index 0000000000..58c2a8333c Binary files /dev/null and b/public/docs/img/platform-hub/policies/policy-violation-user-message.png differ diff --git a/public/docs/img/platform-hub/policies/policy-violation-user-message.png.json b/public/docs/img/platform-hub/policies/policy-violation-user-message.png.json new file mode 100644 index 0000000000..b2b43060e7 --- /dev/null +++ b/public/docs/img/platform-hub/policies/policy-violation-user-message.png.json @@ -0,0 +1 @@ +{"width":1657,"height":779,"updated":"2025-09-19T07:36:25.849Z"} \ No newline at end of file diff --git a/src/pages/docs/platform-hub/policies/best-practices.md b/src/pages/docs/platform-hub/policies/best-practices.md new file mode 100644 index 0000000000..060c6246ac --- /dev/null +++ b/src/pages/docs/platform-hub/policies/best-practices.md @@ -0,0 +1,65 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-09-11 +modDate: 2025-09-11 +title: Policies best practices +subtitle: Best practices for creating policies within Platform Hub +icon: fa-solid fa-lock +navTitle: Best Practices +navSection: Policies +description: Best practices for creating policies within Platform Hub +navOrder: 115 +--- + +## Policies administration + +### Establish a naming standard + +Use a [ Prefix ] - [ Policy Name ] that is easy for everyone to understand the policy's purpose. The [ Prefix ] should reflect when the policy will run. + +For example: + +- Deployments - [ Policy Name ] for policies designed to run during deployments only. +- Runbook Runs - [ Policy Name ] for policies designed to run during runbooks runs only. +- Deployments and Runbook Runs - [ Policy Name ] for policies for designed to run for deployments or runbooks runs. + +### Turn on SIEM audit log streaming + +All policy evaluations are logged to the audit log. Ensure [audit log streaming](/docs/security/users-and-teams/auditing/audit-stream) is enabled to log those evaluations to Splunk, SumoLogic, or an OpenTelemetry collector. SIEM tools can provide alerting and visualizations that you can customize to your requirements. + +## Creating and Updating Policies + +### Start restrictive, then make generic + +Consider a policy that will block the execution of deployments and runbook runs. By default that policy applies to all deployments and runbook runs. + +When creating a new policy, be as restrictive as possible by limiting it to: + +- A specific hook - such a deployment or a runbook run (not both) +- A specific project + +That will a policy's "blast radius." Once you are confident the policy is working as intended, extend the policy to cover more projects or tenants. When acceptable, switch the policy to project groups or spaces. + +### Provide a verbose failure reason + +A policy violation will be the first experience for must users with policies within Octopus Deploy. For example, when a policy blocks a deployment or runbook run. Provide a verbose failure reason to help the user self-service the solution. + +:::figure +![An example of a verbose policy violation error message to help users self-service](/docs/img/platform-hub/policies/policy-violation-user-message.png) +::: + +### Check for both the existence of steps and if they’ve been skipped + +Policies can be written to check for the existence of specific steps within a deployment or runbook process. It's important to remember that in many cases those deployments and runbook processes have existed for years. Octopus Deploy has the capability to require a step and prevent it from being skipped. But it is unlikely that _all_ of those required steps in _all_ of your deployment and runbook processes have been configured to prevent them from being skipped. + +It is not enough for a policy to simply check for the existence of a specific step. The policy must also ensure users don't elect to skip the required step (for whatever reason). + +:::figure +![An example of a step that can be skipped before scheduling a deployment or runbook run](/docs/img/platform-hub/policies/a-step-that-can-be-skipped-violating-a-policy.png) +::: + +The resulting policy will have two conditions. + +:::figure +![An example of a policy that has both the existence and that isn't skipped](/docs/img/platform-hub/policies/example-of-policy-with-two-conditions.png) +:::