From 7cbbcf30ed04f88e5cd2ab8db7e87580abeec90b Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 17:14:56 -0500 Subject: [PATCH 1/9] creates policy as code assemblies and modules --- .../platform/assembly-controller-pac.adoc | 37 ++++++++++++++ .../proc-configure-pac-enforcement.adoc | 49 +++++++++++++++++++ .../platform/proc-configure-pac-settings.adoc | 49 +++++++++++++++++++ .../modules/platform/proc-enable-pac.adoc | 49 +++++++++++++++++++ .../platform/ref-pac-inputs-outputs.adoc | 35 +++++++++++++ 5 files changed, 219 insertions(+) create mode 100644 downstream/assemblies/platform/assembly-controller-pac.adoc create mode 100644 downstream/modules/platform/proc-configure-pac-enforcement.adoc create mode 100644 downstream/modules/platform/proc-configure-pac-settings.adoc create mode 100644 downstream/modules/platform/proc-enable-pac.adoc create mode 100644 downstream/modules/platform/ref-pac-inputs-outputs.adoc diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc new file mode 100644 index 000000000..cead5a467 --- /dev/null +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -0,0 +1,37 @@ +:_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. + +include::platform/proc-enable-pac.adoc[leveloffset=+1] + +include::platform/proc-configure-pac-settings.adoc[leveloffset=+1] + +include::platform/proc-configure-pac-enforcement.adoc[leveloffset=+1] + +include::platform/ref-pac-input-output.adoc[leveloffset=+1] + diff --git a/downstream/modules/platform/proc-configure-pac-enforcement.adoc b/downstream/modules/platform/proc-configure-pac-enforcement.adoc new file mode 100644 index 000000000..6f24abe60 --- /dev/null +++ b/downstream/modules/platform/proc-configure-pac-enforcement.adoc @@ -0,0 +1,49 @@ +:_newdoc-version: 2.18.4 +:_template-generated: 2025-05-08 +:_mod-docs-content-type: PROCEDURE + +[id="configure-enforcement-points_{context}"] += configure enforcement points + +Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. + +.Prerequisites +* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. +* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. +* Do not use imperative statements in the Prerequisites section. + +.Procedure +. Make each step an instruction. +. Include one imperative sentence for each step, for example: +.. Do this thing and then select *Next*. +.. Do this other thing, and this other thing, and then select *Next*. +. Use an unnumbered bullet (*) if the procedure includes only one step. ++ +NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. + +.Verification +Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. + +* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. +* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. +* Make each step an instruction. +* Use an unnumbered bullet (*) if the verification includes only one step. + +.Troubleshooting +Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. + +* Make each step an instruction. +* Use an unnumbered bullet (*) if the troubleshooting includes only one step. + +.Next steps +* Delete this section if it does not apply to your module. +* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. +* Use an unnumbered bullet (*) if the list includes only one step. + +NOTE: Do not use *Next steps* to provide a second list of instructions. + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] +* xref:some-module_{context}[] + diff --git a/downstream/modules/platform/proc-configure-pac-settings.adoc b/downstream/modules/platform/proc-configure-pac-settings.adoc new file mode 100644 index 000000000..138c62361 --- /dev/null +++ b/downstream/modules/platform/proc-configure-pac-settings.adoc @@ -0,0 +1,49 @@ +:_newdoc-version: 2.18.4 +:_template-generated: 2025-05-08 +:_mod-docs-content-type: PROCEDURE + +[id="configure-pac-settings_{context}"] += configure pac settings + +Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. + +.Prerequisites +* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. +* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. +* Do not use imperative statements in the Prerequisites section. + +.Procedure +. Make each step an instruction. +. Include one imperative sentence for each step, for example: +.. Do this thing and then select *Next*. +.. Do this other thing, and this other thing, and then select *Next*. +. Use an unnumbered bullet (*) if the procedure includes only one step. ++ +NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. + +.Verification +Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. + +* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. +* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. +* Make each step an instruction. +* Use an unnumbered bullet (*) if the verification includes only one step. + +.Troubleshooting +Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. + +* Make each step an instruction. +* Use an unnumbered bullet (*) if the troubleshooting includes only one step. + +.Next steps +* Delete this section if it does not apply to your module. +* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. +* Use an unnumbered bullet (*) if the list includes only one step. + +NOTE: Do not use *Next steps* to provide a second list of instructions. + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] +* xref:some-module_{context}[] + diff --git a/downstream/modules/platform/proc-enable-pac.adoc b/downstream/modules/platform/proc-enable-pac.adoc new file mode 100644 index 000000000..b43f7345e --- /dev/null +++ b/downstream/modules/platform/proc-enable-pac.adoc @@ -0,0 +1,49 @@ +:_newdoc-version: 2.18.4 +:_template-generated: 2025-05-08 +:_mod-docs-content-type: PROCEDURE + +[id="enable-pac_{context}"] += enable PaC + +Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. + +.Prerequisites +* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. +* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. +* Do not use imperative statements in the Prerequisites section. + +.Procedure +. Make each step an instruction. +. Include one imperative sentence for each step, for example: +.. Do this thing and then select *Next*. +.. Do this other thing, and this other thing, and then select *Next*. +. Use an unnumbered bullet (*) if the procedure includes only one step. ++ +NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. + +.Verification +Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. + +* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. +* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. +* Make each step an instruction. +* Use an unnumbered bullet (*) if the verification includes only one step. + +.Troubleshooting +Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. + +* Make each step an instruction. +* Use an unnumbered bullet (*) if the troubleshooting includes only one step. + +.Next steps +* Delete this section if it does not apply to your module. +* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. +* Use an unnumbered bullet (*) if the list includes only one step. + +NOTE: Do not use *Next steps* to provide a second list of instructions. + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] +* xref:some-module_{context}[] + diff --git a/downstream/modules/platform/ref-pac-inputs-outputs.adoc b/downstream/modules/platform/ref-pac-inputs-outputs.adoc new file mode 100644 index 000000000..4a41c7721 --- /dev/null +++ b/downstream/modules/platform/ref-pac-inputs-outputs.adoc @@ -0,0 +1,35 @@ +:_newdoc-version: 2.18.4 +:_template-generated: 2025-05-08 +:_mod-docs-content-type: REFERENCE + +[id="pac-inputs-outputs_{context}"] += pac-inputs-outputs + +Write a short introductory paragraph that provides an overview of the module. + +A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. + +AsciiDoc markup to consider for reference data: + +.Unordered list +* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. +For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. + +.Labeled list +Term 1:: Definition +Term 2:: Definition + +.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 +|==== + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] +* xref:some-module_{context}[] + From a63eec39a65b25a22de748194cb9800be589eed9 Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 17:33:34 -0500 Subject: [PATCH 2/9] updates master.adoc with new assembly --- downstream/assemblies/platform/assembly-controller-pac.adoc | 2 +- downstream/titles/controller/controller-admin-guide/master.adoc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc index cead5a467..4edc702df 100644 --- a/downstream/assemblies/platform/assembly-controller-pac.adoc +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -33,5 +33,5 @@ include::platform/proc-configure-pac-settings.adoc[leveloffset=+1] include::platform/proc-configure-pac-enforcement.adoc[leveloffset=+1] -include::platform/ref-pac-input-output.adoc[leveloffset=+1] +include::platform/ref-pac-inputs-outputs.adoc[leveloffset=+1] diff --git a/downstream/titles/controller/controller-admin-guide/master.adoc b/downstream/titles/controller/controller-admin-guide/master.adoc index c77c1a71a..d5f3036c7 100644 --- 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] From e4f5287e127bf2441f6138e677403db165177c88 Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 18:02:15 -0500 Subject: [PATCH 3/9] populates enable pac module --- .../platform/assembly-controller-pac.adoc | 5 ++ .../modules/platform/proc-enable-pac.adoc | 75 +++++++++++-------- 2 files changed, 48 insertions(+), 32 deletions(-) diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc index 4edc702df..f468ffd87 100644 --- a/downstream/assemblies/platform/assembly-controller-pac.adoc +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -27,6 +27,11 @@ Before you can implement policy enforcement in your Ansible instance, you must h * 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] diff --git a/downstream/modules/platform/proc-enable-pac.adoc b/downstream/modules/platform/proc-enable-pac.adoc index b43f7345e..98ade33d1 100644 --- a/downstream/modules/platform/proc-enable-pac.adoc +++ b/downstream/modules/platform/proc-enable-pac.adoc @@ -3,47 +3,58 @@ :_mod-docs-content-type: PROCEDURE [id="enable-pac_{context}"] -= enable PaC += Enabling policy enforcement -Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. +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. -.Prerequisites -* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. -* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. -* Do not use imperative statements in the Prerequisites section. +== {OCPShort} Installation -.Procedure -. Make each step an instruction. -. Include one imperative sentence for each step, for example: -.. Do this thing and then select *Next*. -.. Do this other thing, and this other thing, and then select *Next*. -. Use an unnumbered bullet (*) if the procedure includes only one step. -+ -NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. +For {OCPShort} installations, you must modify the {PlatformNameShort} custom resource. Add the following to the spec section: -.Verification -Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. +[source,yaml] +---- +spec: + feature_flags: + FEATURE_POLICY_AS_CODE_ENABLED: True +---- -* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. -* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. -* Make each step an instruction. -* Use an unnumbered bullet (*) if the verification includes only one step. +After applying the changes, wait for the operator to complete the update process. The operator will automatically handle the necessary service restarts and configuration updates. -.Troubleshooting -Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. +== RPM Installation -* Make each step an instruction. -* Use an unnumbered bullet (*) if the troubleshooting includes only one step. +For RPM-based installations, modify the inventory file used by the installer to add the following variable: -.Next steps -* Delete this section if it does not apply to your module. -* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. -* Use an unnumbered bullet (*) if the list includes only one step. +[source,yaml] +---- +feature_flags: + FEATURE_POLICY_AS_CODE_ENABLED: True +---- -NOTE: Do not use *Next steps* to provide a second list of instructions. +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:///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://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] - +* link:https://access.redhat.com/articles/7109282[How to set feature flags for {PlatformName}] \ No newline at end of file From 45f0469ba538dcb7b13a6ac95150c96051908c12 Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 19:40:18 -0500 Subject: [PATCH 4/9] populates configure pac settings module --- .../platform/proc-configure-pac-settings.adoc | 62 +++++++------------ 1 file changed, 21 insertions(+), 41 deletions(-) diff --git a/downstream/modules/platform/proc-configure-pac-settings.adoc b/downstream/modules/platform/proc-configure-pac-settings.adoc index 138c62361..9fd5c4043 100644 --- a/downstream/modules/platform/proc-configure-pac-settings.adoc +++ b/downstream/modules/platform/proc-configure-pac-settings.adoc @@ -3,47 +3,27 @@ :_mod-docs-content-type: PROCEDURE [id="configure-pac-settings_{context}"] -= configure pac settings += Configuring policy enforcement settings -Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. - -.Prerequisites -* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. -* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. -* Do not use imperative statements in the Prerequisites section. +You can specify how your {PlatformNameShort} instance interacts with OPA by modifying your global settings. .Procedure -. Make each step an instruction. -. Include one imperative sentence for each step, for example: -.. Do this thing and then select *Next*. -.. Do this other thing, and this other thing, and then select *Next*. -. Use an unnumbered bullet (*) if the procedure includes only one step. -+ -NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. - -.Verification -Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. - -* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. -* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. -* Make each step an instruction. -* Use an unnumbered bullet (*) if the verification includes only one step. - -.Troubleshooting -Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. - -* Make each step an instruction. -* Use an unnumbered bullet (*) if the troubleshooting includes only one step. - -.Next steps -* Delete this section if it does not apply to your module. -* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. -* Use an unnumbered bullet (*) if the list includes only one step. - -NOTE: Do not use *Next steps* to provide a second list of instructions. - -[role="_additional-resources"] -.Additional resources -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] - +. 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]. \ No newline at end of file From 1e24f1f4140cdc98ed80936f5d313ea21cedf99b Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 21:07:45 -0500 Subject: [PATCH 5/9] populates enforcement points module --- .../proc-configure-pac-enforcement.adoc | 108 +++++++++++------- 1 file changed, 69 insertions(+), 39 deletions(-) diff --git a/downstream/modules/platform/proc-configure-pac-enforcement.adoc b/downstream/modules/platform/proc-configure-pac-enforcement.adoc index 6f24abe60..62db8120d 100644 --- a/downstream/modules/platform/proc-configure-pac-enforcement.adoc +++ b/downstream/modules/platform/proc-configure-pac-enforcement.adoc @@ -3,47 +3,77 @@ :_mod-docs-content-type: PROCEDURE [id="configure-enforcement-points_{context}"] -= configure enforcement points += Configuring enforcement points -Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. +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. -.Prerequisites -* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. -* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. -* Do not use imperative statements in the Prerequisites section. +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. + +== 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. + + +== Associating a policy with an organization + +To associate a policy with an organization, take the following steps. .Procedure -. Make each step an instruction. -. Include one imperative sentence for each step, for example: -.. Do this thing and then select *Next*. -.. Do this other thing, and this other thing, and then select *Next*. -. Use an unnumbered bullet (*) if the procedure includes only one step. -+ -NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. - -.Verification -Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. - -* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. -* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. -* Make each step an instruction. -* Use an unnumbered bullet (*) if the verification includes only one step. - -.Troubleshooting -Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. - -* Make each step an instruction. -* Use an unnumbered bullet (*) if the troubleshooting includes only one step. - -.Next steps -* Delete this section if it does not apply to your module. -* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. -* Use an unnumbered bullet (*) if the list includes only one step. - -NOTE: Do not use *Next steps* to provide a second list of instructions. - -[role="_additional-resources"] -.Additional resources -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] + +. 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. + +== 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. + +== 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. From 0a86603ea7f9662357839121308ee532dfab6bab Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 21:24:13 -0500 Subject: [PATCH 6/9] creates new concept module about policy structure --- .../platform/assembly-controller-pac.adoc | 2 + .../platform/con-pac-policies-rules.adoc | 28 ++++++++++ .../proc-configure-pac-enforcement.adoc | 25 --------- .../platform/ref-pac-inputs-outputs.adoc | 55 ++++++++++++------- 4 files changed, 65 insertions(+), 45 deletions(-) create mode 100644 downstream/modules/platform/con-pac-policies-rules.adoc diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc index f468ffd87..211567606 100644 --- a/downstream/assemblies/platform/assembly-controller-pac.adoc +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -36,6 +36,8 @@ 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/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 new file mode 100644 index 000000000..0d01ea3c4 --- /dev/null +++ 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 index 62db8120d..46e0c52dd 100644 --- a/downstream/modules/platform/proc-configure-pac-enforcement.adoc +++ b/downstream/modules/platform/proc-configure-pac-enforcement.adoc @@ -13,31 +13,6 @@ You can associate a policy with a job template, an inventory, or an organization * *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. -== 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. - - == Associating a policy with an organization To associate a policy with an organization, take the following steps. diff --git a/downstream/modules/platform/ref-pac-inputs-outputs.adoc b/downstream/modules/platform/ref-pac-inputs-outputs.adoc index 4a41c7721..8885fce9f 100644 --- a/downstream/modules/platform/ref-pac-inputs-outputs.adoc +++ b/downstream/modules/platform/ref-pac-inputs-outputs.adoc @@ -3,22 +3,40 @@ :_mod-docs-content-type: REFERENCE [id="pac-inputs-outputs_{context}"] -= pac-inputs-outputs - -Write a short introductory paragraph that provides an overview of the module. - -A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. - -AsciiDoc markup to consider for reference data: - -.Unordered list -* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -* Use a consistent system for file names, IDs, and titles. -For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. - -.Labeled list -Term 1:: Definition -Term 2:: Definition += Policy enforcement inputs and outputs + +== Input data +Use the following inputs to craft policies for use in policy enforcement. + +[cols="1,1,1",options="header"] +|=== +Input|Type|Description +id|Integer|The job’s unique identifier +name|String|Job template name +created|Datetime (ISO 8601)|Timestamp indicating when the job was created +created by|object|Information about the user who created the job. id (integer): Unique identifier for the user,Username (String): Creator username,Is_superuser (Boolean): indicates if the user is a superuser +credentials|List of objects|Credentials associated with job execution. id (integer): the credential’s unique identifier,name (String): credential name,description (String): credential description,organization (Integer or Null): Organization identifier associated with the credential,credential_type (Integer): credential type identifier,managed (Boolean): indicates if the credential is managed internally,"kind (String): Credential type ( ssh , cloud , kubernetes , etc)",cloud (Boolean): Indicates if the credential is for cloud services,kubernetes (Boolean): Indicates if the credential is for Kubernetes services +execution_environment|Object|Details about the execution environment used for the job. id (Integer): the execution environment’s unique identifier,name (String): execution environment name,image (String): Container image used for execution,pull (String): Pull policy for the execution environment +extra_vars|JSON|Extra variables provided for job execution. +forks|Integer|The number of parallel processes used for job execution +hosts_count|Integer|The number of hosts targeted by the job +instance_group|Object|"Information about the instance group handling the job, including:. ",id (Integer): the instance group’s unique identifier,name (String): the instance group name,Capacity (Integer): the available capacity in the group,jobs_running (Integer): the number of currently-running jobs,jobs_total (Integer): Total jobs handled by the group,max_concurrent_jobs (Integer): maximum concurrent jobs allowed,max_forks (Integer): Maximum forks allowed +inventory|Object|"Inventory details used in the job execution, including:.",id (Integer): The inventory’s unique identifier,name (String): The inventory name,description (String): Description of the inventory,kind (String): the inventory type,total_hosts (Integer): the total number of hosts in the inventory,total_groups (Integer): the total number of groups in the inventory,has_inventory_sources (Boolean) Indicates if the inventory has external sources,total_inventory_sources (Integer): the number of external inventory sources,has_active_failures (Boolean): Indicates if there are active failures in the inventory,hosts_with_active_failures (Integer): the number of hosts with active failures,inventory_sources (Array): external inventory sources associated with the inventory +job_template|Object|"Information about the job template, including:",id (Integer): the job template’s unique identifier,name (String): the job template name,"job_type (String): type of job (for example, run )" +job_type|Choice (String)|Type of job execution. Allowed values are:,run ,check ,scan +job_type_name|String|Human-readable name for the job type +labels|List of objects|"Labels associated with the job, including: ",id (Integer): the label’s unique identifier,name (String): the label name,organization (Object): the organization associated with the label,id (Integer): the organization’s unique identifier,name (String): the organization name +launch_type|Choice (String)|How the job was launched. Allowed values include: ,manual : Manual,relaunch : Relaunch,callback : Callback,scheduled : Scheduled,dependency : Dependency,workflow : Workflow,webhook : webhook,sync : Sync,scm : SCM update +limit|String|The limit applied to the job execution +launched_by|Object|"Information about the user who launched the job, including: ",id (Integer): the user’s unique identifier,name (String): the user’s name,"type : (String): the user type (for example, user , system , etc)",url : (String): the user’s API URL +organization|Object|"Information about the organization associated with the job, including: ",id (Integer): the organization’s unique identifier,name (String): the organization name +playbook|String|The playbook used in the job execution +project|Object|"Details about the project associated with the job, including: ",id (Integer): the project’s unique identifier,name (String): the project name,status (Choice-String): the project status,successful : Successful,failed : Failed,error : Error,"scm_type (String): Source control type ( git , svn , etc)",scm_url (String): the source control repository URL,scm_branch (String): the branch used in the repository,scm_refspec (String): RefSpec for the repository,scm_clean (Boolean): Whether the SCM is cleaned before updates,scm_track_submodules (Boolean): whether submodules are tracked,scm_delete_on_update (Boolean): whether SCM deletes files on update +scm_branch|String|The specific branch to use for SCM +scm_revision|String|SCM revision used for the job +workflow_job|Object|Workflow job details, if the job is part of a workflow +workflow_job_template|Object|Workflow job template details +|=== .Table [options="header"] @@ -28,8 +46,5 @@ Term 2:: Definition |Row 2, column 1|Row 2, column 2|Row 2, column 3 |==== -[role="_additional-resources"] -.Additional resources -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] + From d10d8dde6169fe0be72b5ca32d55e9dffe04d4fc Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Thu, 8 May 2025 21:25:50 -0500 Subject: [PATCH 7/9] commenting out table for now --- downstream/assemblies/platform/assembly-controller-pac.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc index 211567606..21bc9d5ce 100644 --- a/downstream/assemblies/platform/assembly-controller-pac.adoc +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -40,5 +40,5 @@ include::platform/con-pac-policies-rules.adoc[leveloffset=+1] include::platform/proc-configure-pac-enforcement.adoc[leveloffset=+1] -include::platform/ref-pac-inputs-outputs.adoc[leveloffset=+1] +// include::platform/ref-pac-inputs-outputs.adoc[leveloffset=+1] From aae35d7efea9eb43b7b6bedbf03393a616a2a7cc Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Fri, 9 May 2025 11:23:12 -0500 Subject: [PATCH 8/9] adds and populates three new proc mods --- .../platform/assembly-controller-pac.adoc | 6 +++ .../platform/con-pac-policies-rules.adoc | 4 +- .../proc-configure-pac-enforcement.adoc | 46 ++----------------- .../platform/proc-configure-pac-settings.adoc | 2 +- .../proc-pac-add-policy-to-inventory.adoc | 17 +++++++ .../platform/proc-pac-add-policy-to-org.adoc | 18 ++++++++ .../proc-pac-add-policy-to-template.adoc | 17 +++++++ 7 files changed, 64 insertions(+), 46 deletions(-) create mode 100644 downstream/modules/platform/proc-pac-add-policy-to-inventory.adoc create mode 100644 downstream/modules/platform/proc-pac-add-policy-to-org.adoc create mode 100644 downstream/modules/platform/proc-pac-add-policy-to-template.adoc diff --git a/downstream/assemblies/platform/assembly-controller-pac.adoc b/downstream/assemblies/platform/assembly-controller-pac.adoc index 21bc9d5ce..a13705dfe 100644 --- a/downstream/assemblies/platform/assembly-controller-pac.adoc +++ b/downstream/assemblies/platform/assembly-controller-pac.adoc @@ -40,5 +40,11 @@ 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 index 0d01ea3c4..85078a1c9 100644 --- a/downstream/modules/platform/con-pac-policies-rules.adoc +++ b/downstream/modules/platform/con-pac-policies-rules.adoc @@ -22,7 +22,7 @@ allowed := { 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. +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 index 46e0c52dd..eda626ab4 100644 --- a/downstream/modules/platform/proc-configure-pac-enforcement.adoc +++ b/downstream/modules/platform/proc-configure-pac-enforcement.adoc @@ -9,46 +9,6 @@ After you have set up your {PlatformNameShort} instance to communicate with the 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. - -== 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. - -== 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. - -== 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. - +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. \ No newline at end of file diff --git a/downstream/modules/platform/proc-configure-pac-settings.adoc b/downstream/modules/platform/proc-configure-pac-settings.adoc index 9fd5c4043..88788470a 100644 --- a/downstream/modules/platform/proc-configure-pac-settings.adoc +++ b/downstream/modules/platform/proc-configure-pac-settings.adoc @@ -16,7 +16,7 @@ You can specify how your {PlatformNameShort} instance interacts with OPA by modi .. *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 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. diff --git a/downstream/modules/platform/proc-pac-add-policy-to-inventory.adoc b/downstream/modules/platform/proc-pac-add-policy-to-inventory.adoc new file mode 100644 index 000000000..9372764ee --- /dev/null +++ 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. \ No newline at end of file diff --git a/downstream/modules/platform/proc-pac-add-policy-to-org.adoc b/downstream/modules/platform/proc-pac-add-policy-to-org.adoc new file mode 100644 index 000000000..a738ad759 --- /dev/null +++ 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 new file mode 100644 index 000000000..0adcdbe9e --- /dev/null +++ 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. \ No newline at end of file From a871fff16e48c5f2f72dc44c229dceda9a4e6d5e Mon Sep 17 00:00:00 2001 From: Hala Herbly Date: Fri, 9 May 2025 11:34:16 -0500 Subject: [PATCH 9/9] implements peer review feedback --- .../platform/proc-configure-pac-settings.adoc | 30 +++++++++++-------- .../modules/platform/proc-enable-pac.adoc | 10 +++---- .../platform/ref-pac-inputs-outputs.adoc | 30 +------------------ 3 files changed, 24 insertions(+), 46 deletions(-) diff --git a/downstream/modules/platform/proc-configure-pac-settings.adoc b/downstream/modules/platform/proc-configure-pac-settings.adoc index 88788470a..c1943d603 100644 --- a/downstream/modules/platform/proc-configure-pac-settings.adoc +++ b/downstream/modules/platform/proc-configure-pac-settings.adoc @@ -11,19 +11,25 @@ You can specify how your {PlatformNameShort} instance interacts with OPA by modi . 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. ++ +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. ++ +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. ++ +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]. \ No newline at end of file diff --git a/downstream/modules/platform/proc-enable-pac.adoc b/downstream/modules/platform/proc-enable-pac.adoc index 98ade33d1..006bb4394 100644 --- a/downstream/modules/platform/proc-enable-pac.adoc +++ b/downstream/modules/platform/proc-enable-pac.adoc @@ -8,7 +8,7 @@ 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 +.{OCPShort} Installation For {OCPShort} installations, you must modify the {PlatformNameShort} custom resource. Add the following to the spec section: @@ -19,9 +19,9 @@ spec: FEATURE_POLICY_AS_CODE_ENABLED: True ---- -After applying the changes, wait for the operator to complete the update process. The operator will automatically handle the necessary service restarts and configuration updates. +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 +.RPM Installation For RPM-based installations, modify the inventory file used by the installer to add the following variable: @@ -33,7 +33,7 @@ feature_flags: 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 +.Containerized Installation For containerized installations, modify the inventory file used by the installer to add: @@ -45,7 +45,7 @@ feature_flags: After modifying the inventory file, rerun the installer to apply the changes. -== Verifying feature flag status +.Verifying feature flag status To verify that the feature flag is enabled, you can check the feature flags state endpoint: diff --git a/downstream/modules/platform/ref-pac-inputs-outputs.adoc b/downstream/modules/platform/ref-pac-inputs-outputs.adoc index 8885fce9f..25776b9cd 100644 --- a/downstream/modules/platform/ref-pac-inputs-outputs.adoc +++ b/downstream/modules/platform/ref-pac-inputs-outputs.adoc @@ -5,38 +5,10 @@ [id="pac-inputs-outputs_{context}"] = Policy enforcement inputs and outputs -== Input data Use the following inputs to craft policies for use in policy enforcement. +.Input data [cols="1,1,1",options="header"] -|=== -Input|Type|Description -id|Integer|The job’s unique identifier -name|String|Job template name -created|Datetime (ISO 8601)|Timestamp indicating when the job was created -created by|object|Information about the user who created the job. id (integer): Unique identifier for the user,Username (String): Creator username,Is_superuser (Boolean): indicates if the user is a superuser -credentials|List of objects|Credentials associated with job execution. id (integer): the credential’s unique identifier,name (String): credential name,description (String): credential description,organization (Integer or Null): Organization identifier associated with the credential,credential_type (Integer): credential type identifier,managed (Boolean): indicates if the credential is managed internally,"kind (String): Credential type ( ssh , cloud , kubernetes , etc)",cloud (Boolean): Indicates if the credential is for cloud services,kubernetes (Boolean): Indicates if the credential is for Kubernetes services -execution_environment|Object|Details about the execution environment used for the job. id (Integer): the execution environment’s unique identifier,name (String): execution environment name,image (String): Container image used for execution,pull (String): Pull policy for the execution environment -extra_vars|JSON|Extra variables provided for job execution. -forks|Integer|The number of parallel processes used for job execution -hosts_count|Integer|The number of hosts targeted by the job -instance_group|Object|"Information about the instance group handling the job, including:. ",id (Integer): the instance group’s unique identifier,name (String): the instance group name,Capacity (Integer): the available capacity in the group,jobs_running (Integer): the number of currently-running jobs,jobs_total (Integer): Total jobs handled by the group,max_concurrent_jobs (Integer): maximum concurrent jobs allowed,max_forks (Integer): Maximum forks allowed -inventory|Object|"Inventory details used in the job execution, including:.",id (Integer): The inventory’s unique identifier,name (String): The inventory name,description (String): Description of the inventory,kind (String): the inventory type,total_hosts (Integer): the total number of hosts in the inventory,total_groups (Integer): the total number of groups in the inventory,has_inventory_sources (Boolean) Indicates if the inventory has external sources,total_inventory_sources (Integer): the number of external inventory sources,has_active_failures (Boolean): Indicates if there are active failures in the inventory,hosts_with_active_failures (Integer): the number of hosts with active failures,inventory_sources (Array): external inventory sources associated with the inventory -job_template|Object|"Information about the job template, including:",id (Integer): the job template’s unique identifier,name (String): the job template name,"job_type (String): type of job (for example, run )" -job_type|Choice (String)|Type of job execution. Allowed values are:,run ,check ,scan -job_type_name|String|Human-readable name for the job type -labels|List of objects|"Labels associated with the job, including: ",id (Integer): the label’s unique identifier,name (String): the label name,organization (Object): the organization associated with the label,id (Integer): the organization’s unique identifier,name (String): the organization name -launch_type|Choice (String)|How the job was launched. Allowed values include: ,manual : Manual,relaunch : Relaunch,callback : Callback,scheduled : Scheduled,dependency : Dependency,workflow : Workflow,webhook : webhook,sync : Sync,scm : SCM update -limit|String|The limit applied to the job execution -launched_by|Object|"Information about the user who launched the job, including: ",id (Integer): the user’s unique identifier,name (String): the user’s name,"type : (String): the user type (for example, user , system , etc)",url : (String): the user’s API URL -organization|Object|"Information about the organization associated with the job, including: ",id (Integer): the organization’s unique identifier,name (String): the organization name -playbook|String|The playbook used in the job execution -project|Object|"Details about the project associated with the job, including: ",id (Integer): the project’s unique identifier,name (String): the project name,status (Choice-String): the project status,successful : Successful,failed : Failed,error : Error,"scm_type (String): Source control type ( git , svn , etc)",scm_url (String): the source control repository URL,scm_branch (String): the branch used in the repository,scm_refspec (String): RefSpec for the repository,scm_clean (Boolean): Whether the SCM is cleaned before updates,scm_track_submodules (Boolean): whether submodules are tracked,scm_delete_on_update (Boolean): whether SCM deletes files on update -scm_branch|String|The specific branch to use for SCM -scm_revision|String|SCM revision used for the job -workflow_job|Object|Workflow job details, if the job is part of a workflow -workflow_job_template|Object|Workflow job template details -|=== .Table [options="header"]