ansible · dcdacosta · May 9, 2025 · May 8, 2025 · May 8, 2025 · May 8, 2025
diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc
@@ -0,0 +1,50 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-08
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context-of-controller-pac: {context}]
+
+ifndef::context[]
+[id="controller-pac"]
+endif::[]
+ifdef::context[]
+[id="controller-pac_{context}"]
+endif::[]
+= Implementing policy enforcement in your {PlatformNameShort} instance
+
+:context: controller-pac
+
+Policy enforcement at automation runtime is a feature that uses encoded rules to define, manage, and enforce policies that govern how your users interact with your {PlatformNameShort} instance. Policy enforcement automates policy management, improving security, compliance, and efficiency. 
+
+OPA, or link:https://www.openpolicyagent.org/docs/latest/[Open Policy Agent], is a policy engine that offloads policy decisions from your Ansible instance. When it is triggered, the policy enforcement feature connects to OPA to retrieve policies specified in your configuration, and applies policy rules to your automation content. If OPA detects a policy violation, it will stop the action and give your user information about the policy violation.
+
+== Prerequisites
+
+Before you can implement policy enforcement in your Ansible instance, you must have: 
+
+* An {PlatformNameShort} 2.5 deployment with the `FEATURE_POLICY_AS_CODE_ENABLED` feature flag set to `TRUE`.
+* Access to an OPA server that is reachable from your {PlatformNameShort} deployment.
+* Configured {PlatformNameShort} with settings required for authenticating to your OPA server.
+* Some familiarity with OPA and the Rego language, which is the language policies are written in.
+
+[NOTE]
+====
+OPA API V1 is the only version currently supported in {PlatformNameShort}.
+====
+
+include::platform/proc-enable-pac.adoc[leveloffset=+1]
+
+include::platform/proc-configure-pac-settings.adoc[leveloffset=+1]
+
+include::platform/con-pac-policies-rules.adoc[leveloffset=+1]
+
+include::platform/proc-configure-pac-enforcement.adoc[leveloffset=+1]
+
+include::platform/proc-pac-add-policy-to-org.adoc[leveloffset=+1]
+
+include::platform/proc-pac-add-policy-to-inventory.adoc[leveloffset=+1]
+
+include::platform/proc-pac-add-policy-to-template.adoc[leveloffset=+1]
+
+// include::platform/ref-pac-inputs-outputs.adoc[leveloffset=+1]
+
diff --git a/downstream/modules/platform/con-pac-policies-rules.adoc b/downstream/modules/platform/con-pac-policies-rules.adoc
@@ -0,0 +1,28 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-09
+:_mod-docs-content-type: CONCEPT
+
+[id="pac-policies-rules_{context}"]
+= Understanding OPA packages and rules
+
+An OPA policy is organized in packages, which are namespaced collections of rules. The basic structure of an OPA policy looks like this: 
+
+[source,rego]
+----
+package aap_policy_examples  # Package name
+
+import rego.v1  # Import required for Rego v1 syntax
+
+# Rules define the policy logic
+allowed := {
+    "allowed": true,
+    "violations": []
+}
+----
+
+The key components of the rule's structure are: 
+
+Package declaration:: This defines the namespace for your policy.
+Rules:: This defines the policy's logic and the decision that it returns.
+
+These components together comprise the OPA policy name, which is formatted as `[package]/[rule]`. You will enter the OPA policy name when you configure enforcement points. 
diff --git a/downstream/modules/platform/proc-configure-pac-enforcement.adoc b/downstream/modules/platform/proc-configure-pac-enforcement.adoc
@@ -0,0 +1,14 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-08
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-enforcement-points_{context}"]
+= Configuring enforcement points
+
+After you have set up your {PlatformNameShort} instance to communicate with the OPA server, you can set up enforcement points where you want the policy to be applied. 
+
+You can associate a policy with a job template, an inventory, or an organization. Enforcement then occurs in the following ways:
+
+Organization:: Jobs launched from a template owned by an organization will fail if the policy is violated. This configuration provides broad control over automation within organizational boundaries.
+Inventory:: Jobs using an inventory associated with a policy fail if the policy is violated. This configuration allows you to control access to specific infrastructure resources. 
+Job template:: Jobs launched from a template associated with a policy fail if the job violates the associated policy. This configuration provides granular control over specific automation tasks. 
diff --git a/downstream/modules/platform/proc-configure-pac-settings.adoc b/downstream/modules/platform/proc-configure-pac-settings.adoc
@@ -0,0 +1,35 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-08
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-pac-settings_{context}"]
+= Configuring policy enforcement settings
+
+You can specify how your {PlatformNameShort} instance interacts with OPA by modifying your global settings.
+
+.Procedure
+. From the navigation panel, select {MenuSetPolicy}.
+. Click *Edit policy settings*.
+. On the Policy Settings page, fill out the following fields: 
++
+OPA Server hostname:: Enter the name of the host that connects to the OPA service.
+OPA server port:: Enter the port that connects to the OPA service.
+Use SSL for OPA connection:: Toggle this switch to enable an SSL connection to the OPA service.
+OPA REST API version:: Enter the REST API version provided by OPA.
+OPA authentication type:: Select the OPA authentication type.
+OPA custom authentication header:: Enter a custom header to be appended to request headers for OPA authentication.
+OPA request timeout:: Enter the number of seconds until the connection times out.
+OPA request retry count:: Enter a figure for the number of times a request can attempt to connect to the OPA service before failing.
++
+. Depending on your authentication type, you may need to fill out the following fields.
+.. If you selected Token as your authentication type:
++
+OPA authentication token:: Enter the OPA authentication token.
++
+.. If you selected Certificate as your authentication type:
++
+OPA client certificate content:: Enter content of the CA certificate for mTLS authentication.
+OPA client key content:: Enter the client key for mTLS authentication.
+OPA CA certificate content:: Enter the content of the CA certificate for mTLS authentication.
++
+. Click btn:[Save policy settings].
diff --git a/downstream/modules/platform/proc-enable-pac.adoc b/downstream/modules/platform/proc-enable-pac.adoc
@@ -0,0 +1,60 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-08
+:_mod-docs-content-type: PROCEDURE
+
+[id="enable-pac_{context}"]
+= Enabling policy enforcement
+
+During installation, you must configure your {PlatformNameShort} instance to include the policy enforcement feature. You can do this by modifying the feature flag variables in your configuration file.
+Follow the instructions below relevant to your installation type.
+
+.{OCPShort} Installation
+
+For {OCPShort} installations, you must modify the {PlatformNameShort} custom resource. Add the following to the spec section: 
+
+[source,yaml]
+----
+spec: 
+  feature_flags: 
+    FEATURE_POLICY_AS_CODE_ENABLED: True 
+----
+
+After applying the changes, wait for the operator to complete the update process. The operator automatically handles the necessary service restarts and configuration updates.
+
+.RPM Installation
+
+For RPM-based installations, modify the inventory file used by the installer to add the following variable: 
+
+[source,yaml]
+----
+feature_flags: 
+  FEATURE_POLICY_AS_CODE_ENABLED: True 
+----
+
+See link:https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-at-runtime[Defining variables at runtime] for more on adding vars. After modifying the inventory file, rerun the installer to apply changes. 
+
+.Containerized Installation
+
+For containerized installations, modify the inventory file used by the installer to add: 
+
+[source,yaml]
+----
+feature_flags: 
+  FEATURE_POLICY_AS_CODE_ENABLED: True 
+----
+
+After modifying the inventory file, rerun the installer to apply the changes. 
+
+.Verifying feature flag status
+
+To verify that the feature flag is enabled, you can check the feature flags state endpoint:
+
+[source,yaml]
+----
+https://<your-aap-host>/api/controller/v2/feature_flags_state/
+----
+The endpoint will return a `JSON` response containing the current state of all feature flags, including `FEATURE_POLICY_AS_CODE_ENABLED`.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/articles/7109282[How to set feature flags for {PlatformName}]
diff --git a/downstream/modules/platform/proc-pac-add-policy-to-inventory.adoc b/downstream/modules/platform/proc-pac-add-policy-to-inventory.adoc
@@ -0,0 +1,17 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-09
+:_mod-docs-content-type: PROCEDURE
+
+[id="pac-add-policy-to-inventory_{context}"]
+== Associating a policy with an inventory
+
+To associate a policy with an inventory, take the following steps: 
+
+.Procedure
+
+. From the navigation panel, select {MenuInfrastructureInventories}.
+. On the Inventories screen:
+.. To edit an existing inventory, find the inventory you want to edit and click the pencil icon image:leftpencil.png[Edit,15,15] to go to the editing screen.
+.. To create a new inventory, click btn:[Create inventory].
+. In the field titled *Policy enforcement*, enter the query path associated with the policy you want to implement. Note that the query path must be formatted as `package/rule`.
+. Click btn:[Save inventory] if you are editing an existing inventory, or click btn:[Create inventory] if you are creating a new inventory.
diff --git a/downstream/modules/platform/proc-pac-add-policy-to-org.adoc b/downstream/modules/platform/proc-pac-add-policy-to-org.adoc
@@ -0,0 +1,18 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-09
+:_mod-docs-content-type: PROCEDURE
+
+[id="pac-add-policy-to-org_{context}"]
+== Associating a policy with an organization
+
+To associate a policy with an organization, take the following steps.
+
+.Procedure
+
+. From the navigation panel, select {MenuAMOrganizations}.
+. On the Organizations screen:
+.. To edit an existing organization, find the organization you want to edit and click the pencil icon image:leftpencil.png[Edit,15,15] to go to the editing screen.
+.. To create a new organization, click btn:[Create organization].
+. In the field labeled *Policy enforcement*, enter the query path associated with the policy you want to implement. Note that the query path must be formatted as `package/rule`.
+. Click btn:[Next] and then btn:[Finish] to save your settings.
+
diff --git a/downstream/modules/platform/proc-pac-add-policy-to-template.adoc b/downstream/modules/platform/proc-pac-add-policy-to-template.adoc
@@ -0,0 +1,17 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-09
+:_mod-docs-content-type: PROCEDURE
+
+[id="pac-add-policy-to-template_{context}"]
+== Associating a policy with a job template
+
+To associate a policy with a job template, take the following steps: 
+
+.Procedure
+
+. From the navigation panel, select {MenuAETemplates}.
+. On the Automation Templates screen:
+.. To edit an existing job template, find the job template you want to edit and click the pencil icon image:leftpencil.png[Edit,15,15] to go to the editing screen.
+.. To create a new job template, click btn:[Create template].
+. In the field titled *Policy enforcement*, enter the query path associated with the policy you want to implement. Note that the query path must be formatted as `package/rule`.
+. Click btn:[Save job template] if you are editing an existing job template, or click btn:[Create job template] if you are creating a new job template.
diff --git a/downstream/modules/platform/ref-pac-inputs-outputs.adoc b/downstream/modules/platform/ref-pac-inputs-outputs.adoc
@@ -0,0 +1,22 @@
+:_newdoc-version: 2.18.4
+:_template-generated: 2025-05-08
+:_mod-docs-content-type: REFERENCE
+
+[id="pac-inputs-outputs_{context}"]
+= Policy enforcement inputs and outputs
+
+Use the following inputs to craft policies for use in policy enforcement.
+
+.Input data
+[cols="1,1,1",options="header"]
+
+.Table
+[options="header"]
+|====
+|Column 1|Column 2|Column 3
+|Row 1, column 1|Row 1, column 2|Row 1, column 3
+|Row 2, column 1|Row 2, column 2|Row 2, column 3
+|====
+
+
+
diff --git a/downstream/titles/controller/controller-admin-guide/master.adoc b/downstream/titles/controller/controller-admin-guide/master.adoc
@@ -27,6 +27,7 @@ include::platform/assembly-controller-management-jobs.adoc[leveloffset=+1]
 include::platform/assembly-inventory-file-importing.adoc[leveloffset=+1]
 //include::platform/assembly-multi-credential-assignment.adoc[leveloffset=+1]
 include::platform/assembly-ag-controller-clustering.adoc[leveloffset=+1]
+include::platform/assembly-controller-pac.adoc[leveloffset=+1]
 //Removed to user Guide
 //include::platform/assembly-controller-instances.adoc[leveloffset=+1]
 //include::platform/assembly-ag-instance-and-container-groups.adoc[leveloffset=+1]