Docs: updates first batch of reference settings #980

ZPain8464 · 2023-09-12T19:52:04Z

Related to #912

This PR updates a small batch of reference settings. Pages with only one setting set the toc_max_heading_level to 2, so ### Examples sections are included in the Core tab but aren't visible on the sidebar ToC. Pages with multiple settings (like AutoCert) change the Examples to an h4; h4s aren't visible in the sidebar ToC be default.

I wanted to get an opinion on this approach before applying it everywhere.

netlify · 2023-09-12T19:52:10Z

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	`3174b0b`
🔍 Latest deploy log	https://app.netlify.com/sites/pomerium-docs/deploys/65776ae34938b2000890cbf1
😎 Deploy Preview	https://deploy-preview-980--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

ZPain8464 · 2023-09-22T14:00:56Z

@desimone to review this PR and determine what to do with these settings.

desimone

toc_max_heading_level 2 makes sense to me.

ZPain8464 · 2023-11-29T23:16:40Z

@kenjenkins this is a big commit, but do you mind giving these global settings changes a quick cursory review at some point this week?

I'll do the route settings in a separate commit.

kenjenkins · 2023-11-29T23:52:08Z

content/docs/reference/access-log-fields.mdx


+```yaml


Technically the environment variable examples aren't YAML, so it feels a little off to use yaml syntax highlighting for these.

I used bash for the environment variable examples on the downstream mTLS settings page, but the difference in the rendered output is pretty subtle (at least in light mode), so it probably doesn't matter too much either way.

Yeah I actually applied the bash syntax after seeing your example. I think the output pops more. I'll update all these to follow suit.

kenjenkins · 2023-11-29T23:55:43Z

content/docs/reference/authenticate-callback-path.mdx

@@ -65,12 +66,13 @@ See the [Kubernetes Deployment Reference](/docs/deploy/k8s/reference#authenticat
 ### Examples

 ```yaml
-# config file key
-authenticate_callback_path: "/custom/callback"
+authenticate_callback_path: '/custom/callback'


Did you mean to move these into the tabs above?

I may have misunderstood your suggestion. I didn't move these under the tab because there are Core and Kubernetes examples, but no Enterprise example. I kept examples underneath/outside the tabs if 2 or more tabs had examples. This setting has Core and K8s examples.

However, this K8s setting is for Core, so we could just include it under the K8s tab.

content/docs/reference/authenticate-service-url.mdx

kenjenkins · 2023-11-30T00:27:05Z

content/docs/reference/authorize-log-fields.mdx


+```yaml


and here as well?

So, this one is configurable in the Console. The original ask here (#912) was to move examples into the Core tab if the setting only has Core examples, right? Again, I may have misunderstood the suggestion.

Oh, I see. Yes, that was what I originally wrote in #912, but what do you think about moving all 'Examples' into their corresponding tabs? I think it would be good to keep the page structure consistent between reference pages.

That's a good point, I'll have to comb through these again but it should be quick.

ZPain8464 · 2023-12-05T18:13:51Z

@desimone and @kenjenkins changes are made in global and route settings. However, there are a number of settings that don't provide K8s examples, but link directly to the K8s reference. It's time consuming to untangle the inconsistencies, so I made a list in Notion and will add a ticket to update these settings, followed with a PR at a later time.

For now, this applies formatting changes consistently across the reference page examples.

kenjenkins · 2023-12-05T18:45:01Z

content/docs/reference/access-log-fields.mdx

+### Examples
+
+```yaml
+accessLogFields: '[{"authority"},{"duration"},{"path"}]'


@wasaga can you confirm if this example is correct?

@kenjenkins I had @wasaga review and incorporated his feedback into the commit below. I'm going to start working on updating K8s settings in a separate PR. I'll have @wasaga review the changes.

wasaga

https://github.com/pomerium/documentation/pull/980/files#diff-ca14d8afcddd18b3acbf56a8a81b492ceab27ab1d32903a6fa1c09fa6d28a703R68

this is incorrect, host rewrite is supported.

also, it need be consistent in indicating whether this is an Ingress annotation or a CRD.

If it's an ingress annotation it has to be full.

i.e. here it should say ingress.pomerium.io/allow_websockets and type string (cause annotations are strings)

content/docs/reference/authenticate-service-url.mdx

content/docs/reference/authorize-log-fields.mdx

content/docs/reference/cookies.mdx

content/docs/reference/pass-identity-headers.mdx

content/docs/reference/routes/allow-any-authenticated-user.mdx

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

content/docs/reference/authenticate-callback-path.mdx

content/docs/reference/authenticate-service-url.mdx

content/docs/reference/certificates.mdx

content/docs/reference/global-timeouts.mdx

wasaga · 2023-12-11T18:58:32Z

content/docs/reference/routes/kubernetes-service-account-token.mdx

 | `kubernetes_service_account_token` | `string` | **optional** |
 | `kubernetes_service_account_token_file` | `bearer token` file path | **optional** |


those are not supported

wasaga · 2023-12-11T18:59:03Z

content/docs/reference/routes/kubernetes-service-account-token.mdx

 ### Examples

 ```yaml
-kubernetes_service_account_token: eyJ0eXAiOiJKV1QiLCJhbGciOiJ...
+ingress.pomerium.io/kubernetes_service_account_token: eyJ0eXAiOiJKV1QiLCJhbGciOiJ...

-kubernetes_service_account_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+ingress.pomerium.io/kubernetes_service_account_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
 ```
+


wasaga · 2023-12-11T19:05:12Z

content/docs/reference/routes/public-access.mdx

@@ -40,15 +47,15 @@ Enable **Public Access** in the **Policy Builder** in the Console:

 | **Name** | **Type** | **Default** | **Usage** |


for follow-up: the column names are inconsistent. sometimes its "name", sometimes its "annotation", somtimes its "YAML", etc.

route level options are almost all annotations.

Yeah I plan on updating these to be consistent as well. I'll do this in another PR; this one is pretty big already.

content/docs/reference/routes/timeouts.mdx

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

wasaga

some comments are not yet resolved.

Could you please collect links to those that were not resolved into separate ticket that would be addressed in the follow-up PR?

backport-actions-token · 2023-12-13T16:07:24Z

The backport to 0-24-0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-0-24-0 0-24-0
# Navigate to the new working tree
cd .worktrees/backport-0-24-0
# Create a new branch
git switch --create backport-980-to-0-24-0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick --mainline 1 3f9b754fc1081d88f004f429fe17574e198687f8
# Push it to GitHub
git push --set-upstream origin backport-980-to-0-24-0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-0-24-0

Then, create a pull request where the base branch is 0-24-0 and the compare/head branch is backport-980-to-0-24-0.

updates first batch of reference settings

53b9f62

ZPain8464 added docs backport 0-23-0 Backports this PR to branch 0-23-0 labels Sep 12, 2023

ZPain8464 requested review from desimone and kenjenkins September 12, 2023 19:52

ZPain8464 mentioned this pull request Sep 13, 2023

Request: move "Examples" into "Core" tab on reference pages with only "Core" examples #912

Closed

desimone approved these changes Nov 28, 2023

View reviewed changes

kenjenkins mentioned this pull request Nov 29, 2023

add a border around the tabs container #982

Merged

ZPain8464 marked this pull request as ready for review November 29, 2023 14:07

ZPain8464 requested a review from a team as a code owner November 29, 2023 14:07

ZPain8464 requested review from cmo-pomerium and removed request for a team November 29, 2023 14:07

ZPain8464 added 2 commits November 29, 2023 15:25

Merge branch 'main' into zpain/fix-reference-examples

9a05f1c

updates global settings examples

32f0fe8

ZPain8464 added 2 commits November 29, 2023 18:20

adds envar example to programmatic redirect domain whitelist

42bda3f

removes comments from config

b47fe24

kenjenkins reviewed Nov 30, 2023

View reviewed changes

ZPain8464 added 5 commits November 30, 2023 10:09

adds bash syntax to envar examples

61b2d15

updates global level examples

fcb90ff

updates pages up to idp_client_id_per_route

1b6578f

moves routes examples

2208c11

Merge branch 'main' into zpain/fix-reference-examples

0cb1a2f

ZPain8464 added backport 0-24-0 and removed backport 0-23-0 Backports this PR to branch 0-23-0 labels Dec 5, 2023

runs yarn format

0f42127

kenjenkins approved these changes Dec 5, 2023

View reviewed changes

ZPain8464 added 2 commits December 6, 2023 15:15

updates global set response headers examples

3c7b585

updates global set response headers

8f7c984

wasaga requested changes Dec 7, 2023

View reviewed changes

ZPain8464 and others added 7 commits December 7, 2023 13:46

Update content/docs/reference/authenticate-service-url.mdx

faef415

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/authorize-log-fields.mdx

af617ca

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/cookies.mdx

2945d4c

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/pass-identity-headers.mdx

b069ff1

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/routes/allow-any-authenticated-user.mdx

0caf87a

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

runs prettier and corrects k8s websockets example

8846653

fixes k8s examples

01adb59

ZPain8464 requested a review from wasaga December 7, 2023 19:45

ZPain8464 added 2 commits December 8, 2023 13:28

updates k8s examples

4becaa0

runs prettier

debaa74

wasaga requested changes Dec 11, 2023

View reviewed changes

ZPain8464 and others added 10 commits December 11, 2023 14:33

Update content/docs/reference/authenticate-callback-path.mdx

be423a3

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/authenticate-service-url.mdx

8d29650

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/certificates.mdx

b96a4ed

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/global-timeouts.mdx

4ac6cf2

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/global-timeouts.mdx

023e29c

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/global-timeouts.mdx

2a046ac

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/global-timeouts.mdx

edcba6f

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Update content/docs/reference/routes/timeouts.mdx

d4e5871

Co-authored-by: Denis Mishin <dmishin@pomerium.com>

Merge branch 'main' into zpain/fix-reference-examples

3bb654a

runs prettier and updates examples

3174b0b

ZPain8464 requested a review from wasaga December 11, 2023 20:02

wasaga approved these changes Dec 13, 2023

View reviewed changes

ZPain8464 merged commit 3f9b754 into main Dec 13, 2023
4 checks passed

ZPain8464 deleted the zpain/fix-reference-examples branch December 13, 2023 16:07

ZPain8464 mentioned this pull request Dec 19, 2023

k8s: docs/reference/certificates #1094

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: updates first batch of reference settings #980

Docs: updates first batch of reference settings #980

ZPain8464 commented Sep 12, 2023

netlify bot commented Sep 12, 2023 •

edited

Loading

ZPain8464 commented Sep 22, 2023

desimone left a comment

ZPain8464 commented Nov 29, 2023

kenjenkins Nov 29, 2023

ZPain8464 Nov 30, 2023

kenjenkins Nov 29, 2023

ZPain8464 Nov 30, 2023 •

edited

Loading

kenjenkins Nov 30, 2023

ZPain8464 Nov 30, 2023

kenjenkins Nov 30, 2023

ZPain8464 Nov 30, 2023

ZPain8464 commented Dec 5, 2023

kenjenkins Dec 5, 2023

ZPain8464 Dec 6, 2023

wasaga left a comment

wasaga Dec 11, 2023

wasaga Dec 11, 2023

wasaga Dec 11, 2023

ZPain8464 Dec 11, 2023

wasaga left a comment

backport-actions-token bot commented Dec 13, 2023

		\| `kubernetes_service_account_token` \| `string` \| optional \|
		\| `kubernetes_service_account_token_file` \| `bearer token` file path \| optional \|

		@@ -40,15 +47,15 @@ Enable Public Access in the Policy Builder in the Console:

		\| Name \| Type \| Default \| Usage \|

Docs: updates first batch of reference settings #980

Docs: updates first batch of reference settings #980

Conversation

ZPain8464 commented Sep 12, 2023

netlify bot commented Sep 12, 2023 • edited Loading

✅ Deploy Preview for pomerium-docs ready!

ZPain8464 commented Sep 22, 2023

desimone left a comment

Choose a reason for hiding this comment

ZPain8464 commented Nov 29, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZPain8464 Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZPain8464 commented Dec 5, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wasaga left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wasaga left a comment

Choose a reason for hiding this comment

backport-actions-token bot commented Dec 13, 2023

netlify bot commented Sep 12, 2023 •

edited

Loading

ZPain8464 Nov 30, 2023 •

edited

Loading