W-23907611 docs: draft Policy Write documentation

modules/ROOT/pages/exp-governance-policy-library-apply.adoc

@@ -0,0 +1,154 @@
+= Apply and Manage Policies from the Policy Library
+:keywords: policy library, canonical policies, universal policies, governance policies, apply policy, edit policy, delete policy, policy catalog
+
+// DRAFT: Policy Write (MS2026-08-R2 / Dreamforce). Tracked in W-23907611.
+// This topic was previously a commented-out draft for the Policy Read GA. It has been
+// rewritten for the Policy Write scope. Sections contain TODO(W-23907611) markers where a
+// detail could not be grounded in code and must be confirmed with the PM before publishing.
+// Blockers to resolve before removing this DRAFT banner and publishing:
+//  1. Confirmed list of the universal policy templates and their per-gateway native mappings
+//     (APIM-owned; not enumerated in the Omni codebase).
+//  2. Which feature flags are ON for GA, per gateway
+//     (W_23173868_CANONICAL_POLICIES_ENABLED for Kong,
+//      W_23308031_NONKONG_POLICIES_VIA_APIM_ENABLED for Apigee/Azure).
+//  3. The enable/disable support matrix (which gateways expose the toggle at GA).
+//  4. Human-readable required permission/role names for policy write actions.
+//  5. Whether applying policies from the API Instance page is enabled at GA
+//     (listed as out of scope for MS2026-08-R2 in the program tracker).
+
+Use the Policy Library to apply a universal policy template to your API instances and to manage the resulting native policies. A universal template expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway.
+
+// TODO(W-23907611): AWS API Gateway is excluded from the policy write flow for this release
+// (deferred to a later release). Confirm the customer-facing framing of the AWS exclusion with the PM.
+
+== Before You Begin
+
+Before getting started, make sure you have:
+
+* An Anypoint Platform account.
+* Any of these permissions:
++
+--
+** API Governance: Governance Administrator
+** API Manager: Manage Policies
+--
++
+// TODO(W-23907611): Confirm the exact permission/role names required for apply, edit, delete,
+// and enable/disable. The code enforces per-action permissions (create, update, enable,
+// disable, delete) fetched per instance, but exposes only permission keys, not role labels.
+For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions].
+
+* API instances registered in the portfolio on a supported gateway.
+
+[NOTE]
+====
+Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request.
+====
+
+== Browse the Policy Library
+
+The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces.
+
+You can filter policies by category:
+
+* *Access & Security*
+* *Performance & Cost*
+* *Quality of Service*
+* *Data Privacy & Integrity*
+* *Compliance & Observability*
+
+// TODO(W-23907611): Confirm the shipping list of universal policy templates and the native
+// policy each maps to per gateway (for example, an API key template mapping to VerifyAPIKey
+// on Apigee and key-auth on Kong). This mapping is served at runtime by API Manager and is
+// not defined in the Omni codebase, so it must be confirmed with the PM / API Platform team
+// before it is documented as a table. Do not transcribe the mapping from the planning tracker.
+
+== Apply a Policy
+
+. Log in and go to *Governance* > *Governance Strategies* > *Policy Library*.
+. Select the policy you want to apply.
+. Configure the policy parameters. Required and optional fields vary by policy type.
+. Select the API instances where you want to apply the policy.
+. Review the summary, then apply the policy.
+
+// TODO(W-23907611): Confirm the exact wizard step labels and the primary action button label
+// against the shipped UI before publishing (the apply flow is driven by the governance policy
+// wizard). Applying policies directly from an API Instance page is listed as out of scope for
+// MS2026-08-R2 — confirm whether that entry point is available at GA before documenting it.
+
+When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway.
+
+Applying a policy is an asynchronous, tracked operation, not a fire-and-forget action. A message confirms that the operation is running and directs you to the *Activity log* tab to check its status. When you apply a policy to more than one instance, each instance reports its own result, so you can see which instances succeeded and which failed. To review the outcome, see <<track-policy-changes,Track Policy Changes>>.
+
+[NOTE]
+====
+While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs.
+====
+
+== Manage Applied Policies
+
+Manage the native policies on an instance from the *Policies* tab of the instance detail page. The available actions depend on the gateway and on your permissions. For where to find this tab, see xref:exp-services-view-details.adoc[].
+
+=== Edit a Policy
+
+For Apigee and Azure API Management native policies that originate from a universal template, select *Edit Configuration* to change the policy's settings.
+
+Editing uses a two-tier experience:
+
+* If the policy's configuration schema is available, the policy opens in an editable form.
+* If no schema is available, the policy opens in a read-only view of its current configuration.
+
+Your changes are saved back to the vendor gateway.
+
+[NOTE]
+====
+Editing Kong gateway-scope policies is not supported.
+====
+
+=== Delete a Policy
+
+To remove a native policy from an instance, select the remove action for the policy. A confirmation dialog appears before the policy is removed. Removing a policy detaches it from the instance, and traffic that the policy was filtering is no longer enforced. After you confirm, the policy no longer appears in the instance's policy list.
+
+// TODO(W-23907611): Confirm the exact remove action/menu label and confirmation button label
+// against the shipped UI before publishing.
+
+=== Enable or Disable a Policy
+
+On gateways that support it, you can enable or disable a policy without removing it. The state change is reflected in the policy list. On gateways that don't support enabling and disabling, the toggle is unavailable.
+
+// TODO(W-23907611): Confirm the enable/disable support matrix (which gateways expose the
+// toggle at GA) before publishing. Do not list specific gateways as supported or unsupported
+// until engineering confirms the shipping behavior.
+
+=== View Policies Outside Your Scope
+
+Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available.
+
+[#track-policy-changes]
+== Track Policy Changes
+
+Policy write actions run asynchronously and are tracked, so you can confirm whether a change landed on the gateway instead of assuming it did. Review recent policy operations for an instance on the *Activity log* tab of the instance detail page.
+
+The *Activity log* tab lists recent policy operations with these columns:
+
+* *Policy*: The policy the operation applied to.
+* *Action*: The operation performed — *Apply*, *Update*, *Toggle*, or *Remove*.
+* *Status*: The current state of the operation — *Running*, *Completed*, or *Failed*.
+
+The tab shows the most recent operations from the last 30 days. If no policy changes have been recorded for the instance in that window, the tab reports that no activity is available.
+
+Use the *Activity log* tab to confirm that an apply, edit, enable, disable, or delete completed, or to see which operations failed and need to be retried.
+
+// TODO(W-23907611): The Activity log tab is gated by a feature flag and, per the code,
+// currently appears only for external (non-MuleSoft) provider instances. Confirm the GA
+// availability (flag state and which provider instances show the tab) with engineering.
+// Also confirm the exact column headers and the empty-state wording against the shipped UI.
+// Note: the log records policy/action/status/time only — it does NOT record an actor
+// ("who"), so do not describe it as a full audit trail.
+
+== See Also
+
+* xref:exp-governance-create-strategy.adoc[]
+* xref:exp-governance-work-with-strategies.adoc[]
+* xref:exp-services-view-details.adoc[]
+* xref:exp-governance-govern-third-party-apis.adoc[]

modules/ROOT/pages/exp-instances-add.adoc

@@ -54,7 +54,15 @@ Field names, required metadata, and available gateway or runtime options depend
 
 After creating or updating an instance, you can continue managing the service through related areas of the experience.
 
-* Use the *Policies* tab to review or apply policies to the instance. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway.
+* Use the *Policies* tab to review or apply policies to the instance.
++
+--
+For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway.
+
+For an instance discovered on a third-party API gateway (Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites].
+
+If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway.
+--
 * Use the *Monitoring* tab to review metrics and runtime performance when monitoring is available.
 * Coordinate with platform owners if DNS, certificates, or upstream routing changes must happen outside the product.
 

modules/ROOT/pages/exp-overview.adoc

@@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int
 
 Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*.
 
-Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. Conformance reporting summarizes rule violations and severity so you can close gaps systematically.
+Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically.
 
 Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them.
 
@@ -38,7 +38,7 @@ Under *Portfolio*, open *Agents*, *MCP Servers*, *Model Proxies*, *APIs*, or *Ga
 In *Portfolio*, open a service detail page from *Agents*, *MCP Servers*, *Model Proxies*, or *APIs*, then open the *Instances* tab to create managed or unmanaged deployments that match your needs. Managed instances on Omni Gateway give stronger governance and monitoring when the new experience exposes them. *Gateways* don't include an *Instances* tab on their detail page. For instance workflows, see xref:exp-instances-add.adoc[].
 . Configure policies.
 +
-On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[].
+On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. For APIs discovered from third-party gateways, applying policies requires a scanner configured with write credentials for the provider; see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[].
 . Review compliance.
 +
 In *Portfolio*, open a service detail page from *Agents*, *APIs*, or *MCP Servers*, then open the *Conformance Report* tab to review scores, violations, and warnings and address the findings your governance team prioritizes. For gateways, use top-level *Governance* for the same compliance story at the scope the experience supports. For service-level tabs and conformance context, see xref:exp-services-view-details.adoc[].

modules/ROOT/pages/exp-providers-manage.adoc

@@ -100,6 +100,8 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor
 *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar.
 ====
 
+Of these providers, the API gateway providers Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites].
+
 The specific providers available depend on your organization's enabled products and enhanced experience configuration.
 
 == See Also

modules/ROOT/pages/exp-scanners-add-from-providers.adoc

@@ -38,6 +38,10 @@ Scheduled or on-demand scans pick up releases and configuration drift according
 +
 When a scanner is enabled, it can discover and read policies from API configurations. This allows the system to enforce policies on the discovered services. This is especially useful for API-based policies, such as web application firewall (WAF) policies.
 
+* Policy write
++
+For API gateway providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites].
+
 == Workflow Entry Points for Adding a Scanner
 
 The system exposes the same underlying connect-and-configure wizard from more than one place; the label depends on context:
@@ -82,6 +86,8 @@ If some environments show no policy binding, select *Check again* to retry the p
 
 Regardless of entry point, adding a scanner establishes trust and scope. You specify which provider platform to reach, how the system authenticates, and how you validate connectivity. You also name and schedule the scanner—or configure another trigger—so discovery runs on the cadence your team expects. Saving the configuration activates the scanner for the catalogs and features your administrator enabled.
 
+For API gateway providers that support policy write, supply credentials that include the provider's write scope during setup. Discovery credentials alone enable read-only access: the scanner discovers and reads policies, but the affected APIs appear as *Read-Only* and policy actions are unavailable until you add write credentials. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc[].
+
 == After the Scanner Runs
 
 When the scanner is active, it applies discovery results according to its settings and your organization's rules. You review outcomes on the *Providers* page and on scanner detail pages, and you manage discovered services from the relevant *Portfolio* catalogs.

modules/ROOT/pages/exp-scanners-manage.adoc

@@ -20,11 +20,15 @@ Re-enable scheduled scanning after a pause.
 * *Scanner Settings*
 +
 Change names, descriptions, credentials, provider scope, or scan-related settings your product exposes, then save, so future runs use the new definition.
++
+For API gateway providers that support policy write, adding write credentials to a read-only scanner enables policy write (apply, enable, disable, and delete) on the scanner's discovered APIs. Read and write credentials are configured separately. For provider-specific write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites].
 * *Delete Scanner*
 +
 Remove the scanner from *Providers* when the provider link is no longer authorized or useful. Consider the impact on discovered services in *Portfolio* and on dependent teams before you delete the scanner.
 +
 NOTE: When you delete an Akamai API Security scanner, the system attempts to remove the Akamai correlation policy from the scanner's environments. If the removal fails, the correlation policy may remain applied; check *Automated Policies* to verify. Discovered services remain in your portfolio regardless.
++
+NOTE: Deleting a write-enabled API gateway scanner doesn't remove policies that were previously applied to the provider's APIs through policy write. Those policies remain active on the gateway. Anypoint stops tracking them, and you lose the ability to manage them from Anypoint until you reconnect a scanner with write credentials.
 
 
 == See Also