docs: Add UUID to docs yaml blocks (#3251)

Makefile

@@ -138,6 +138,13 @@ yarn:
 	@echo "==> $@"
 	cd ui ; yarn install --network-timeout 120000
 
+.PHONY: gen-docs
+gen-docs:
+	@echo "==> $@"
+	pip3 install ruamel.yaml
+	python3 ./scripts/generate-settings-docs.py
+	node scripts/generate-console-pages.js
+
 .PHONY: help
 help:
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

docs/enterprise/console-settings.yaml

@@ -1,22 +1,25 @@
 settings:
-  - name: "Reports"
+- name: Reports
   settings:
-      - name: "Traffic"
+  - name: Traffic
     doc: |
       View the traffic running through Pomerium. Filter by [Route][route-concept] name, or date range.
 
       ![The Traffic page in Pomerium Enterprise](./img/traffic-fullpage.png)
-      - name: "Runtime"
+    uuid: fbf40372-9895-4ca7-95d3-5e18f8f56413
+  - name: Runtime
     doc: |
       Monitor how many system resources Pomerium is consuming. Filter by date range, service, and instance.
 
       ![The Runtime Info page in Pomerium Enterprise](./img/runtime-fullpage.png)
-      - name: "Sessions"
+    uuid: 2edcf120-b62c-464b-a3a7-e5b14e3e6400
+  - name: Sessions
     doc: |
       View active Sessions. From here you can revoke sessions, filter by session or user information, or revoke one or multiple sessions. You can also export the data.
 
       ![The Sessions page in Pomerium Enterprise](./img/sessions-fullpage.png)
-      - name: "Events"
+    uuid: d11acb05-65cc-4c65-9f92-4b1f08b622ef
+  - name: Events
     doc: |
       The events page displays the log output of Envoy as it process changes from Pomerium and applies updates to the underlying services.
 
@@ -25,16 +28,19 @@ settings:
       The most common updates are to Pomerium Proxy services, which are updated every time a Route or Policy is created or updated.
 
       The value under **Resource ID** will usually match the resource ID of a [Policy][policy-reference], visible in the Policy under **Change History** or in the URL. A value of "Pomerium Restarted" refers to when services are reloaded, usually due to a system update.
-      - name: "Deployments"
+    uuid: 219f8dd6-38d4-4dc3-98a6-98cca314c49e
+  - name: Deployments
     doc: |
       From the **Deployment History** page administrators can review changes made to their Pomerium configuration.
 
       The default view shows all changes made through Pomerium Enterprise. Use the **COMPARE** button next to an entry to filter to only changes that affected that resource. Select two versions of that resource, then **DIFF** to see what changed:
 
       ![A screenshot showing the diff of a change to a route, adding a policy](./img/deployment-diff.png)
-  - name: "Manage"
+    uuid: c812c87e-ec06-4091-b1fe-e206e43103d5
+  uuid: e15ae275-fa57-40d3-b2f7-ce24799ccf79
+- name: Manage
   settings:
-      - name: "Routes"
+  - name: Routes
     doc: |
       A [Route](/enterprise/concepts.md#routes) defines how to access a service running behind Pomerium. This includes authentication (both for Pomerium and passed through to the service), rewrites, header management, load balancing, etc.
 
@@ -49,62 +55,93 @@ settings:
 
       The sections below cover the options available when creating or editing a route.
     settings:
-          - name: "General"
+    - name: General
       doc: |
         The **General** tab defines the route path, both from the internet and to the internal service, and the policies attached. Note that policies enforced on a [Namespace][namespace-reference] the route resides in will also be applied.
       settings:
-              - name: "Name"
+      - name: Name
         doc: This value is only visible in the Console UI.
-                more: '/enterprise/reference/manage.html#name'
-              - name: "From"
-              - name: "Metrics Name"
+        more: /enterprise/reference/manage.html#name
+        uuid: 3f59881a-24b4-41a0-b92f-1d36a69b76e8
+      - name: From
+        uuid: b9c54c4e-28ad-4a8b-aa65-3aa7f8b1f032
+      - name: Metrics Name
         doc: |
           Once a Route is created, the Metric Name field will populate. You can use this name to scrape the Prometheus service for metrics on this Route when making custom dashboards.
-              - name: "To"
-              - name: "Redirect"
-              - name: "Pass Identity Headers"
-              - name: "Policies"
-                doc: Add or remove Policies to be applied to the Route. Note that Policies enforced in the Route's Namespace will be applied automatically.
-                more: '/enterprise/reference/manage.html#policies-2'
-              - name: "Enable Google Cloud Serverless Authentication"
-          - name: "Matchers"
+        uuid: 7df15eef-3070-4353-822d-c2745386e0db
+      - name: To
+        uuid: 9c0201e0-b5fa-4027-a1e7-f115a3f70969
+      - name: Redirect
+        uuid: 72d885ce-8cd3-41a7-b7d0-0953ce49f8de
+      - name: Pass Identity Headers
+        uuid: 12e599f2-8bcc-4061-ba88-998c2671109c
+      - name: Policies
+        doc: Add or remove Policies to be applied to the Route. Note that Policies
+          enforced in the Route's Namespace will be applied automatically.
+        more: /enterprise/reference/manage.html#policies-2
+        uuid: c7340a01-2942-4ffe-bbf6-f97f0fec1e75
+      - name: Enable Google Cloud Serverless Authentication
+        uuid: 416405ec-74c3-47cb-899e-34bebaff26bf
+      uuid: fd86b6ea-fe73-4222-a675-5493c7dbd105
+    - name: Matchers
       settings:
       - name: Path
+        uuid: e5c805e5-4f7f-4fce-ba33-d3f1f47f5d35
       - name: Prefix
+        uuid: 3a2bc400-d1bc-4249-a813-9777cfca7779
       - name: Regex
-          - name: "Rewrite"
+        uuid: 13dbfeb0-a8a0-4c97-9bb9-52aa3f22c7cc
+      uuid: 0bbff866-b7b9-4fdf-b8e5-b6d4f2475855
+    - name: Rewrite
       settings:
-              - name: "Prefix Rewrite"
-              - name: "Regex Rewrite Pattern"
-                keys: ["regex_rewrite_pattern"]
+      - name: Prefix Rewrite
+        uuid: 3fb98409-89ae-47ae-b9ff-44f07f833492
+      - name: Regex Rewrite Pattern
+        keys: [regex_rewrite_pattern]
         doc: |
           The pattern to match before rewriting, ex: `^/service/([^/]+)(/.*)$`.
-              - name: "Regex Rewrite Substitution"
-                keys: ["regex_rewrite_substitution"]
+        uuid: 5cd03f7c-b474-45fd-aef0-c1ee15f2eaf2
+      - name: Regex Rewrite Substitution
+        keys: [regex_rewrite_substitution]
         doc: |
           The substitution for your regex pattern, ex: `\\2/instance/\\1`.
-          - name: "Timeouts"
+        uuid: 71cdc7a9-d72e-407c-99f0-36e3a5ef1f41
+      uuid: b9ee5ae3-e90d-40f1-8df3-91d26ebe85cd
+    - name: Timeouts
       settings:
-              - name: "Allow Websockets"
-                keys: ["allow_websockets"]
-              - name: "Allow SPDY"
-                keys: ["allow_spdy"]
-              - name: "Timeout"
-                keys: ["timeout"]
-              - name: "Idle Timeout"
-                keys: ["idle_timeout"]
-          - name: "Headers"
+      - name: Allow Websockets
+        keys: [allow_websockets]
+        uuid: f42c273d-7c3d-471c-a28e-75b8c9e771f3
+      - name: Allow SPDY
+        keys: [allow_spdy]
+        uuid: ca7bf8ec-e123-4171-b22b-00c24a6a0d96
+      - name: Timeout
+        keys: [timeout]
+        uuid: 2b38fd23-24b0-4830-b924-0de802402191
+      - name: Idle Timeout
+        keys: [idle_timeout]
+        uuid: 25d0d973-9add-4efb-abaa-d526a41b3c4e
+      uuid: d93421db-ae13-4978-8d22-91561cc9eb61
+    - name: Headers
       settings:
-              - name: "Host Headers"
-                keys: ["host_rewrite"]
-              - name: "Set Request Headers"
-              - name: "Remove Request Headers"
-              - name: "Rewrite Response Headers"
-          - name: "Load Balancer"
+      - name: Host Headers
+        keys: [host_rewrite]
+        uuid: 399e48ea-e6f3-4ab9-b007-714ed7428168
+      - name: Set Request Headers
+        uuid: 6acc6aa7-6cde-4849-b960-63103e3f00ee
+      - name: Remove Request Headers
+        uuid: c593bd77-b333-40c7-95bb-0ba41bf270e3
+      - name: Rewrite Response Headers
+        uuid: 1a9d6b6e-8d79-4ece-92c3-1d36d9c58af6
+      uuid: e8022486-c36d-4fad-970f-6412b7b156a2
+    - name: Load Balancer
       settings:
-              - name: "Load Balancing Policy"
-      - name: "Policies"
-        keys: ["Policy"]
+      - name: Load Balancing Policy
+        uuid: b4563876-813c-4eab-85e1-7c74efeb4412
+      uuid: ef865e68-a544-4482-b331-6acf5e723d3a
+    uuid: 99cab2ec-f8e6-4bcb-aa1d-2eba94948f49
+  - name: Policies
+    keys: [Policy]
     doc: |
       A [Policy](/enterprise/concepts.md#policies) defines what permissions a set of users or groups has. Policies are applied to Namespaces or Routes to associate the set of permissions with a service or set of service, completing the authentication model.
 
@@ -185,100 +222,137 @@ settings:
       - **Any Authenticated User**: This setting will allow access to a route with this policy attached to any user who can authenticate to your Identity Provider (**IdP**).
       - **CORS Preflight**: Allow unauthenticated HTTP OPTIONS requests as per the CORS spec.
       - **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
-      - name: "Certificates"
-      - name: "Devices"
+    uuid: 1710a312-0562-4a18-b5a6-bedfc54873f6
+  - name: Certificates
+    uuid: bff9a877-7c35-4b9d-80d8-ca3b2d16a2fc
+  - name: Devices
     doc: |
       Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
     settings:
-          - name: "Manage Devices"
+    - name: Manage Devices
       doc: |
         From this page, administrators can manage new and existing device enrollments.
         Device enrollment let's you create [policies](/docs/topics/ppl.md#device-matcher) that use [device identity](/docs/topics/device-identity.md).
         - Users can [self-enroll](/guides/enroll-device.md) devices, which must then be approved in the **Devices List** for policies requiring approved devices.
         - Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved. See our [Pre-Approved Device Enrollment](/guides/admin-enroll-device.md) guide for more information.
-            more: '/enterprise/reference/manage.html#manage-devices'
-          - name: "Devices List"
+      more: /enterprise/reference/manage.html#manage-devices
+      uuid: 742c64e4-9441-41b0-ac6e-677b6bfe6cbb
+    - name: Devices List
       doc: |
         Displays the currently enrolled devices for each user, along with their current approval status.
         Administrators can inspect, approve, or delete registered devices from this table.
 
         ![List of user devices](./img/console-devices.png)
-          - name: "New Enrollment"
+      uuid: dd10552e-c7f8-4cca-8c31-3ed01f31b478
+    - name: New Enrollment
       doc: |
         The **New Enrollment** button allows administrators to create a custom link for a specific user to use to register a new device, which will automatically be approved.
         This scheme is known as [Trust on First Use (TOFU)](https://en.wikipedia.org/wiki/Trust_on_first_use).
 
         ![Example device enrollment](./img/new-enrollment.png)
-            more: '/guides/admin-enroll-device.html'
+      more: /guides/admin-enroll-device.html
       settings:
-              - name: "Search Users"
-                doc: "New Enrollment URLs are only valid for the specified user."
-                more: '/guides/admin-enroll-device.html'
-              - name: "Redirect URL"
-                doc: "**Optional**: The URL the user will be taken to after device enrollment is successful."
-                more: '/guides/admin-enroll-device.html'
-              - name: "Enrollment Type"
-                doc: "Specify if the user can enroll any device identity, or restrict it to a [secure enclave](/docs/topics/device-identity.md#secure-enclaves)."
-                more: '/guides/admin-enroll-device.html'
-  - name: "Configure"
+      - name: Search Users
+        doc: New Enrollment URLs are only valid for the specified user.
+        more: /guides/admin-enroll-device.html
+        uuid: 4d636f56-21e2-4c72-9a65-0fc9ff76823e
+      - name: Redirect URL
+        doc: '**Optional**: The URL the user will be taken to after device enrollment
+          is successful.'
+        more: /guides/admin-enroll-device.html
+        uuid: 79e3b000-79cd-4522-9336-cefb28906930
+      - name: Enrollment Type
+        doc: Specify if the user can enroll any device identity, or restrict it to
+          a [secure enclave](/docs/topics/device-identity.md#secure-enclaves).
+        more: /guides/admin-enroll-device.html
+        uuid: 69b7c84d-84aa-4a38-b830-55dfed8ad2a1
+      uuid: 4bdd0102-a593-420b-8999-51a461657dc4
+    uuid: d1eb6b9e-ab93-4beb-ab91-d1de6aa76498
+  uuid: e0dbd749-1a83-4d28-8fb9-e067f2d6daa4
+- name: Configure
   doc: |
     The **Configure** section of the Pomerium Enterprise Console houses settings that affect the entirety of the Console environment, i.e. across all Namespaces. Adjust these settings with care.
   settings:
-      - name: "Settings"
+  - name: Settings
     doc: |
       The **Settings** section holds global settings that affect how the Pomerium Enterprise Console runs, logs, and communicates. Values set here are applied globally, except for settings documented to override global options.
     settings:
-          - name: "Global"
+    - name: Global
       settings:
-              - name: "Debug"
-              - name: "HTTP Redirect Address"
-              - name: "DNS Lookup Family"
-              - name: "Log Level"
-              - name: "Proxy Log Level"
-          - name: "Cookies"
+      - name: Debug
+        uuid: 6c058151-b21b-4b65-9abc-6ab884f946c0
+      - name: HTTP Redirect Address
+        uuid: 42459dde-ebb7-4e31-9cd1-1dbf01d7a440
+      - name: DNS Lookup Family
+        uuid: 206d37b5-9a6b-4043-8dae-68ca89640e2d
+      - name: Log Level
+        uuid: 1c13dfc6-6718-412a-8091-904f703c3014
+      - name: Proxy Log Level
+        uuid: c1f29676-7bf9-4feb-bb3b-246debd9c64b
+      uuid: 77e4a8cb-447e-4f79-b6b9-e752dcc53249
+    - name: Cookies
       settings:
-              - name: "HTTPS Only"
-                keys: ["cookie_secure"]
-              - name: "Javascript Security"
-              - name: "Expires"
-                keys: ["cookie_expire"]
-          - name: "Timeouts"
-            doc: "Timeouts set the global server timeouts. Timeouts can also be set for individual routes."
-          - name: "GRPC"
+      - name: HTTPS Only
+        keys: [cookie_secure]
+        uuid: 43d28fb7-69c3-4923-b095-b0f97ec88ed4
+      - name: Javascript Security
+        uuid: 9597b118-6fa1-4dd2-bf07-68b9f582f519
+      - name: Expires
+        keys: [cookie_expire]
+        uuid: e28156d0-5175-4cdc-8a39-dcb3735d1438
+      uuid: 378293b9-6068-4a97-9fa5-75a0fa155538
+    - name: Timeouts
+      doc: Timeouts set the global server timeouts. Timeouts can also be set for individual
+        routes.
+      uuid: 58a18216-744f-4ffc-aab5-aeabd74851f1
+    - name: GRPC
       settings:
-              - name: "GRPC Server Max Connection Age"
+      - name: GRPC Server Max Connection Age
         doc: |
           Set max connection age for GRPC servers. After this interval, servers ask clients to reconnect and perform any rediscovery for new/updated endpoints from DNS.
 
           See <https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters> (opens new window) for details
-              - name: "GRPC Server Max Connection Age Grace"
+        uuid: 02d307d3-415f-4c0c-8d64-5f2fb96198cc
+      - name: GRPC Server Max Connection Age Grace
         doc: |
           Additive period with grpc_server_max_connection_age, after which servers will force connections to close.
 
           See <https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters> (opens new window) for details
-          - name: "Tracing"
+        uuid: b49ffe89-5006-4f8e-841a-d6a12d00dbb3
+      uuid: f744ee07-7d41-4016-8621-3ead4e330a95
+    - name: Tracing
       doc: |
         Tracing tracks the progression of a single user request as it is handled by Pomerium.
 
         Each unit of work is called a Span in a trace. Spans include metadata about the work, including the time spent in the step (latency), status, time events, attributes, links. You can use tracing to debug errors and latency issues in your applications, including in downstream connections.
       settings:
-              - name: "Tracing Sample Rate"
+      - name: Tracing Sample Rate
         doc: |
           Percentage of requests to sample. Default is .01%.
 
           Unlike the decimal value notion used for the `tracing_sample_rate` [key](/reference/readme.md#shared-tracing-settings) in open-source Pomerium, this value is a percentage, e.g. a value of `1` equates to 1%
-          - name: "Authenticate"
-          - name: "Proxy"
+        uuid: a214565d-9b77-4994-9c07-531bd9610dd0
+      uuid: bd62365e-1e08-4c45-9b3f-0eccbb0f8d80
+    - name: Authenticate
+      uuid: 5ce0bdf1-c73b-4994-988c-74a3c1743514
+    - name: Proxy
       settings:
-              - name: "Certificate Authority"
-                keys: ["certificate_authority"]
-              - name: "Default Upstream Timeout"
-              - name: "JWT Claim Headers"
-              - name: "X-Forward-For HTTP Header"
-                keys: ["skip_xff_append"]
-              - name: "Response Headers"
-                keys: ["set_response_headers"]
-      - name: "Service Accounts"
+      - name: Certificate Authority
+        keys: [certificate_authority]
+        uuid: 8b2127cd-b876-4296-b724-80101825be10
+      - name: Default Upstream Timeout
+        uuid: 11689429-03f1-4a75-9432-8c070c468ad7
+      - name: JWT Claim Headers
+        uuid: 01b24ad4-96dc-4885-b837-96ec1a5e826e
+      - name: X-Forward-For HTTP Header
+        keys: [skip_xff_append]
+        uuid: b1427fa5-4ddb-468b-a6c6-527634b374f6
+      - name: Response Headers
+        keys: [set_response_headers]
+        uuid: fe27b075-e5f0-40fe-8561-748b7ff9dae3
+      uuid: 9334d44c-919c-45af-8405-6acf19be1085
+    uuid: b0e3a449-e743-4cc2-a820-d5d470b752ab
+  - name: Service Accounts
     doc: |
       [Service accounts](/enterprise/concepts.md#service-accounts) offer a protected and standardized method of authenticating machine-to-machine communication between services protected by Pomerium.
 
@@ -311,8 +385,9 @@ settings:
         ---
 
         ![An example policy for a service account](./img/create-policy-2.png)
-      - name: "Namespaces"
-        keys: ["namespace"]
+    uuid: f2a12f52-ea7a-4b44-8308-3500d653c122
+  - name: Namespaces
+    keys: [namespace]
     doc: |
       A [Namespace][namespace-concept] is a collection of users, groups, routes, and policies that allows system administrators to organize, manage, and delegate permissions across their infrastructure.
 
@@ -324,6 +399,8 @@ settings:
       When using an IdP without directory sync or when working with non-domain users, they will not show up in the look-ahead search. See [Non-Domain Users](/enterprise/concepts.md#non-domain-users) for more information.
       :::
 
+    uuid: 3ffcbb2a-4c02-4c3f-b11e-0eef5c30f1bd
+  uuid: b1688ca0-aea8-4296-bc67-8c397ef969a6
 postamble: |
   [route-concept]: /enterprise/concepts.md#routes
   [route-reference]: /enterprise/reference/manage.md#routes

docs/enterprise/reference/configure.md

@@ -151,7 +151,9 @@ Default Upstream Timeout is the default timeout applied to a proxied route when
 
 The JWT Claim Headers setting allows you to pass specific user session data to upstream applications as HTTP request headers. Note, unlike the header `x-pomerium-jwt-assertion` these values are not signed by the authorization service.
 
-Any claim in the pomerium session JWT can be placed into a corresponding header for upstream consumption. This claim information is sourced from your Identity Provider (IdP) and Pomerium's own session metadata. The header will have the following format:
+Additionally, this will add the claim to the `X-Pomerium-Jwt-Assertion` header provided by [`pass_identity_headers`](/reference/readme.md#pass-identity-headers), if not already present.
+
+Any claim in the pomerium session JWT can be placed into a corresponding header and the JWT payload for upstream consumption. This claim information is sourced from your Identity Provider (IdP) and Pomerium's own session metadata. The header will have the following format:
 
 `X-Pomerium-Claim-{Name}` where `{Name}` is the name of the claim requested. Underscores will be replaced with dashes; e.g. `X-Pomerium-Claim-Given-Name`.
 

scripts/generate-settings-docs.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 import os.path
+import uuid
 from typing import Any, IO
-import yaml
+from ruamel.yaml import YAML
+
+yaml = YAML()
 
 
 def main():
@@ -10,9 +13,16 @@ def main():
     d = os.path.normpath(d)
     print(f"generating {d}/readme.md")
 
-    f = open(os.path.join(d, "settings.yaml"))
-    doc = yaml.full_load(f)
-    f.close()
+    settings_path = f"{d}/settings.yaml"
+
+    enterprise_settings_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..',
+                                                             'docs', 'enterprise', 'console-settings.yaml'))
+
+    rewrite_settings_yaml(settings_path)
+    rewrite_settings_yaml(enterprise_settings_path)
+
+    with open(settings_path) as f:
+        doc = yaml.load(f)
 
     f = open(os.path.join(os.path.dirname(__file__),
                           "..", "docs", "reference", "readme.md"), "w")
@@ -22,6 +32,25 @@ def main():
     f.close()
 
 
+def rewrite_settings_yaml(path):
+    with open(path) as f:
+        doc = yaml.load(f)
+
+    add_uuid(doc['settings'])
+
+    with open(path, 'w') as f:
+        yaml.dump(doc, f)
+
+
+def add_uuid(settings):
+    for setting in settings:
+        if not 'uuid' in setting:
+            setting['uuid'] = str(uuid.uuid4())
+
+        if 'settings' in setting:
+            add_uuid(setting['settings'])
+
+
 def write_setting(w, depth, setting):
     if 'name' in setting:
         w.write(f"{'#' * depth} {setting.get('name', '')}\n")