Merge branch 'main' into update-contributing-docs

Author: ADubhlaoich

CONTRIBUTING_DOCS.md

@@ -136,12 +136,14 @@ Supported callouts:
 - `caution`
 - `warning`
 
-You can also create custom callouts using the `call-out` shortcode `{{< call-out "type" "header" "font-awesome icon >}}`. For example:
+You can also create custom callouts using the `call-out` shortcode `{{< call-out "type position" "header" "font-awesome icon >}}`. For example:
 
 ```md
-{{<call-out "important" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
+{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
 ```
 
+By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content.
+
 Here are some other shortcodes:
 
 - `fa`: Inserts a Font Awesome icon

content/agent/configuration/configure-nginx-agent-group.md

@@ -13,7 +13,7 @@ doctypes: ["task"]
 
 During installation, NGINX Agent detects the NGINX user (typically `nginx`) for the master and worker processes and adds this user to a group called `nginx-agent`.
 
-If you change the NGINX username after installing the NGINX Agent, you'll need to add the new username to the `nginx-agent` group so that the NGINX socket has the proper permissions.
+If you change the NGINX username after installing NGINX Agent, you'll need to add the new username to the `nginx-agent` group so that the NGINX socket has the proper permissions.
 
 A failure to update the `nginx-agent` group when the NGINX username changes may result in non-compliance errors for NGINX Plus.
 

content/ngf/how-to/data-plane-configuration.md

@@ -15,7 +15,7 @@ NGINX Gateway Fabric can dynamically update the global data plane configuration
 
 The data plane configuration is stored in the NginxProxy custom resource, which is a cluster-scoped resource that is attached to the `nginx` GatewayClass.
 
-By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-creating-the-configuration) the resource after NGINX Gateway Fabric is already installed.
+By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-create-the-configuration) the resource after NGINX Gateway Fabric is already installed.
 
 When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config`.
 

content/ngf/how-to/traffic-security/integrating-cert-manager.md

@@ -68,9 +68,10 @@ The first step is to deploy cert-manager onto the cluster.
     cert-manager jetstack/cert-manager \
     --namespace cert-manager \
     --create-namespace \
-    --version v1.12.0 \
-    --set installCRDs=true \
-    --set "extraArgs={--feature-gates=ExperimentalGatewayAPISupport=true}"
+    --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
+    --set config.kind="ControllerConfiguration" \
+    --set config.enableGatewayAPI=true \
+    --set crds.enabled=true
   ```
 
 ---

content/nginx-one/changelog.md

@@ -34,6 +34,19 @@ Stay up-to-date with what's new and improved in the F5 NGINX One Console.
 
 ## January 20, 2025
 
+### Manage certificates with Config Sync Groups
+
+With the NGINX One Console, you can now manage certificate deployment in Config Sync Groups. 
+
+You can:
+
+- Add a certificate to a Config Sync Group
+- Remove a deployed certificate from a Config Sync Group
+
+For more information, including warnings about risks, see our documentation on how you can:
+- [Add a file]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md" >}}) 
+- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}})
+
 ### Revert a configuration
 
 Using the NGINX One Console you can now:

content/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md

@@ -62,7 +62,7 @@ If you need to deactivate a data plane key before its expiration date, follow th
 
 ## Delete a data plane key
 
-Before you can delete a key, it must be expired or revoked. You can revoke a key either through the NGINX One console, as explained above, or by using the REST API. Once deleted, all information about the data plane key is permanently removed.
+Before you can delete a key, it must be expired or revoked. You can revoke a key either through the NGINX One Console, as explained above, or by using the REST API. Once deleted, all information about the data plane key is permanently removed.
 
 1. On the left menu, select **Data Plane Keys**.
 2. Find the key you want to revoke in the list of expired or revoked keys.

content/nginx-one/rbac/rbac-api.md

@@ -7,15 +7,15 @@ product: NGINX One
 docs: DOCS-000
 ---
 
-Beyond [Default roles]({{< relref "/nginx-one/rbac/roles.md" >}}), you may need to set up custom roles. For convenience, we include a list of API groups that you could use to specify permissions for custom roles.
-
-These are not NGINX One APIs.
+Beyond the [Default roles]({{< relref "/nginx-one/rbac/roles.md" >}}) for NGINX One Console access, you can create [custom roles](https://docs.cloud.f5.com/docs-v2/administration/how-tos/user-mgmt/roles#custom-roles) with more precisely defined access permissions.
+You can assign custom roles to users or service accounts. You can associate these roles with specific namespaces, to help facilitate the principle of least privilege across your tenant.
+For this use-case, we include a list of API groups that you can use to specify permissions for custom roles with more granular access controls to NGINX One Console APIs.
 
 ## F5 API groups for NGINX One
 
-The following table lists the **[F5 XC roles](https://docs.cloud.f5.com/docs-v2/administration/how-tos/user-mgmt/roles)** that you can use. These are narrowly scoped API Groups that align with all the features and functionality within the NGINX One Console. These groups can help you create custom roles tailored to your specific needs.
+The following table lists the available API groups that you can use to construct a Role. These are narrowly scoped API groups that align with all the features and functionality within the NGINX One Console. These groups can help you create custom roles tailored to your specific needs.
 
-{{< note >}}If you create custom roles using the more granular API Groups, users may not have access until you add the corresponding API Groups to their roles.{{< /note >}}
+{{< note >}}If you create custom roles using these API groups, users may not have access to all capabilities of the browser web portal.{{< /note >}}
 
 | API Group Name                          | Level of Access | Description                                                                                                                   |
 |-----------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|
@@ -27,7 +27,7 @@ The following table lists the **[F5 XC roles](https://docs.cloud.f5.com/docs-v2/
 | f5xc-nginx-one-custom-all-instances-manage          | Write           | View and delete all Instances.                                                                                                |
 | f5xc-nginx-one-custom-instance-manage               | Write           | View and edit Instance details.                                                                        |
 | f5xc-nginx-one-custom-instance-read                 | Read            | View Instance and configuration details.                                                                        |
-| f5xc-nginx-one-custom-certificate-manage            | Write           | View TSL/SSL certificate details. Create, update, and delete any managed certificates.                                    |
+| f5xc-nginx-one-custom-certificate-manage            | Write           | View TLS/SSL certificate details. Create, update, and delete any managed certificates.                                    |
 | f5xc-nginx-one-custom-certificate-read              | Read            | View TLS/SSL certificates.                                                                                    |
 | f5xc-nginx-one-custom-all-certificates-manage       | Write           | View all TLS/SSL certificates. Delete managed certificates.                                               |
 | f5xc-nginx-one-custom-data-plane-key-manage         | Write           | View, create, update, and delete any Data Plane Keys. Note: The actual Data Plane Key is shown _only_ when created. |

content/nginx-one/rbac/roles.md

@@ -13,13 +13,14 @@ We provide three default **[roles](https://docs.cloud.f5.com/docs-v2/administrat
 
 ### Admin
 
-The Admin role, identified as <code>f5xc-nginx-one-admin</code>, provides full read and write access to all endpoints and features within the NGINX One Console.
+The Admin role, identified as `f5xc-nginx-one-admin`, provides full read and write access to all endpoints and features within the NGINX One Console. 
+It also supports RBAC for related XC services, as described in [Role-based Access Control Concepts](https://flatrender.tora.reviews/docs-v2/administration/how-tos/user-mgmt/rbac).
 
 ### User
 
-Our standard User role, listed as <code>f5xc-nginx-one-user</code> in the role list, provides read and write access to all endpoints and features, save for those considered to be administrator level. An example of an administrator level feature would be **[Instance Settings](https://docs.nginx.com/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances/)** where unavailable instance clean up logic is set.
+Our standard User role, listed as `f5xc-nginx-one-user` in the role list, provides read and write access to all endpoints and features, save for those considered to be administrator level. An example of an administrator level feature would be **[Instance Settings](https://docs.nginx.com/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances/)** where unavailable instance clean up logic is set.
 
 ### Monitor
 
-Our read only or Monitor role, <code>f5xc-nginx-one-monitor</code>, grants read only access to all non-administrator features and endpoints within the NGINX One Console.
+Our read only or Monitor role, `f5xc-nginx-one-monitor`, grants read only access to all non-administrator features and endpoints within the NGINX One Console.
 

content/nginxaas-azure/changelog.md

@@ -13,6 +13,12 @@ To see a list of currently active issues, visit the [Known issues]({{< relref "/
 
 To review older entries, visit the [Changelog archive]({{< relref "/nginxaas-azure/changelog-archive" >}}) section.
 
+## March 13, 2025
+
+- {{% icon-resolved %}} **Percentage capacity metric**
+
+   We’re introducing the new percentage capacity metric, `nginxaas.capacity.percentage`, which provides a more accurate estimate of your deployment's load compared to the previous consumed NCUs metric. The new capacity metric expresses the capacity consumed as a percentage of the deployment's total capacity. Please modify any alerts and monitoring on deployment performance to use the new percentage capacity metric. The consumed NCUs metric is being deprecated and will be removed in the near future. Please see [Scaling guidance]({{< relref "/nginxaas-azure/quickstart/scaling.md">}}) for more details.
+
 ## March 5, 2025
 
 - {{% icon-info %}} **Retirement of Standard Plan**

content/nginxaas-azure/monitoring/metrics-catalog.md

@@ -37,13 +37,15 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio
 | --------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
 | ncu.provisioned       |                | count    | The number of successfully provisioned NCUs during the aggregation interval. During scaling events, this may lag behind `ncu.requested` as the system works to achieve the request. Available for Standard plan(s) only.                                                                                              | deployment      |
 | ncu.requested         |                | count    | The requested number of NCUs during the aggregation interval. Describes the goal state of the system. Available for Standard plans(s) only.                                                                                                                                                                            | deployment      |
-| ncu.consumed          |                | count    | The estimated number of NCUs used to handle the current traffic. This may burst above the `ncu.provisioned`. This can be used to guide scaling out or in to match your workload. See [Scaling Guidance]({{< relref "/nginxaas-azure/quickstart/scaling.md#iterative-approach" >}}) for details. Available for Standard plan(s) only. | deployment      |
+| nginxaas.capacity.percentage          |                | count    | The percentage of the deployment's total capacity being used. This can be used to guide scaling your workload. See [Scaling Guidance]({{< relref "/nginxaas-azure/quickstart/scaling.md#iterative-approach" >}}) for details. Available for Standard plan(s) only. | deployment      |
 | system.worker_connections | pid process_name | count | The number of nginx worker connections used on the dataplane. This metric is one of the factors which determines the deployment's consumed NCU value.  | deployment |
 | nginxaas.certificates | name status    | count    | The number of certificates added to the NGINXaaS deployment dimensioned by the name of the certificate and its status. Refer to [Certificate Health]({{< relref "/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md#monitor-certificates" >}}) to learn more about the status dimension.             | deployment      |
 | nginxaas.maxmind      | status         | count    | The status of any MaxMind license in use for downloading geoip2 databases. Refer to [License Health]({{< relref "/nginxaas-azure/quickstart/geoip2.md#monitoring" >}}) to learn more about the status dimension.                                                                                                                 | deployment      |
 
 {{</bootstrap-table>}}
 
+{{< warning >}}The `ncu.consumed` metric is now deprecated and is on the path to retirement. Please change any alerting on this metric to use the new Capacity Percentage metric.{{< /warning >}}
+
 ### NGINX connections statistics
 
 {{<bootstrap-table "table table-striped table-bordered">}}
@@ -225,6 +227,9 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio
 | system.interface.packets_sent| interface | count | System Interface Packets Sent. | deployment |
 | system.interface.total_bytes| interface | count | System Interface Total Bytes,  sum of bytes_sent and bytes_rcvd. | deployment |
 | system.interface.egress_throughput| interface | count | System Interface Egress Throughput, i.e. bytes sent per second| deployment |
+| system.listener_backlog.max| listen_addr, file_desc | count | The fullness (expressed as a fraction) of the fullest backlog queue. | deployment |
+| system.listener_backlog.length| listen_address, file_desc | count | The number of items in a specific backlog queue, labelled by listen address. | deployment |
+| system.listener_backlog.queue_limit| listen_address, file_desc | count | The capacity of a specific backlog queue, labelled by listen address. | deployment |
 
 {{</bootstrap-table>}}