Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: updates first batch of reference settings #980

Merged
merged 33 commits into from
Dec 13, 2023
Merged

Docs: updates first batch of reference settings #980

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
53b9f62
updates first batch of reference settings
ZPain8464 Sep 12, 2023
9a05f1c
Merge branch 'main' into zpain/fix-reference-examples
ZPain8464 Nov 29, 2023
32f0fe8
updates global settings examples
ZPain8464 Nov 29, 2023
42bda3f
adds envar example to programmatic redirect domain whitelist
ZPain8464 Nov 29, 2023
b47fe24
removes comments from config
ZPain8464 Nov 29, 2023
61b2d15
adds bash syntax to envar examples
ZPain8464 Nov 30, 2023
fcb90ff
updates global level examples
ZPain8464 Dec 1, 2023
1b6578f
updates pages up to idp_client_id_per_route
ZPain8464 Dec 5, 2023
2208c11
moves routes examples
ZPain8464 Dec 5, 2023
0cb1a2f
Merge branch 'main' into zpain/fix-reference-examples
ZPain8464 Dec 5, 2023
0f42127
runs yarn format
ZPain8464 Dec 5, 2023
8103d36
corrects accessLogFields k8 example
ZPain8464 Dec 6, 2023
3c7b585
updates global set response headers examples
ZPain8464 Dec 6, 2023
8f7c984
updates global set response headers
ZPain8464 Dec 6, 2023
faef415
Update content/docs/reference/authenticate-service-url.mdx
ZPain8464 Dec 7, 2023
af617ca
Update content/docs/reference/authorize-log-fields.mdx
ZPain8464 Dec 7, 2023
2945d4c
Update content/docs/reference/cookies.mdx
ZPain8464 Dec 7, 2023
b069ff1
Update content/docs/reference/pass-identity-headers.mdx
ZPain8464 Dec 7, 2023
0caf87a
Update content/docs/reference/routes/allow-any-authenticated-user.mdx
ZPain8464 Dec 7, 2023
8846653
runs prettier and corrects k8s websockets example
ZPain8464 Dec 7, 2023
01adb59
fixes k8s examples
ZPain8464 Dec 7, 2023
4becaa0
updates k8s examples
ZPain8464 Dec 8, 2023
debaa74
runs prettier
ZPain8464 Dec 8, 2023
be423a3
Update content/docs/reference/authenticate-callback-path.mdx
ZPain8464 Dec 11, 2023
8d29650
Update content/docs/reference/authenticate-service-url.mdx
ZPain8464 Dec 11, 2023
b96a4ed
Update content/docs/reference/certificates.mdx
ZPain8464 Dec 11, 2023
4ac6cf2
Update content/docs/reference/global-timeouts.mdx
ZPain8464 Dec 11, 2023
023e29c
Update content/docs/reference/global-timeouts.mdx
ZPain8464 Dec 11, 2023
2a046ac
Update content/docs/reference/global-timeouts.mdx
ZPain8464 Dec 11, 2023
edcba6f
Update content/docs/reference/global-timeouts.mdx
ZPain8464 Dec 11, 2023
d4e5871
Update content/docs/reference/routes/timeouts.mdx
ZPain8464 Dec 11, 2023
3bb654a
Merge branch 'main' into zpain/fix-reference-examples
ZPain8464 Dec 11, 2023
3174b0b
runs prettier and updates examples
ZPain8464 Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions content/docs/reference/access-log-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,9 @@ access_log_fields:
- authority
- duration
- path
```

```yaml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

ACCESS_LOG_FIELDS=authority,duration,path
```

Expand All @@ -173,6 +175,8 @@ ACCESS_LOG_FIELDS=authority,duration,path
access_log_fields:
- headers.user-agent
- headers.content-type
```

```yaml
ACCESS_LOG_FIELDS=headers.user-agent,headers.content-type
```
21 changes: 11 additions & 10 deletions content/docs/reference/address.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ keywords:
- Address
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand All @@ -34,6 +35,16 @@ In all-in-one deployments, gRPC traffic will be served on loopback on port `:544
| :-- | :-- | :-- | :-- | :-- |
| `address` | `ADDRESS` | `string` | **required** | `:443` |

### Examples

```yaml
address: ':8443'
```

```yaml
ADDRESS=:8443
```

</TabItem>
<TabItem label="Enterprise" value="Enterprise">

Expand All @@ -46,13 +57,3 @@ In all-in-one deployments, gRPC traffic will be served on loopback on port `:544

</TabItem>
</Tabs>

### Examples

```yaml
# config file key
address: :8443

# environment variable
ADDRESS=:8443
```
24 changes: 14 additions & 10 deletions content/docs/reference/authenticate-callback-path.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ keywords:
- Authenticate Callback Path
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand Down Expand Up @@ -45,6 +46,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen
| :-- | :-- | :-- | :-- | :-- |
| `authenticate_callback_path` | `AUTHENTICATE_CALLBACK_PATH` | `string` | **optional** | `/oauth2/callback` |

### Examples

```yaml
authenticate_callback_path: "/custom/callback"
```

```yaml
AUTHENTICATE_CALLBACK_PATH=/custom/callback
```

</TabItem>
<TabItem label="Enterprise" value="Enterprise">

Expand All @@ -59,18 +70,11 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen

See the [Kubernetes Deployment Reference](/docs/deploy/k8s/reference#authenticate) for more information.

</TabItem>
</Tabs>

### Examples

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

# environment variable
AUTHENTICATE_CALLBACK_PATH=/custom/callback

# ingress
authenticate.callbackPath: /custom/callback
ZPain8464 marked this conversation as resolved.
Show resolved Hide resolved
```

</TabItem>
</Tabs>
21 changes: 11 additions & 10 deletions content/docs/reference/authenticate-internal-service-url.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ keywords:
- Authenticate Internal Service URL
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand Down Expand Up @@ -38,6 +39,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen
| :-- | :-- | :-- | :-- |
| `authenticate_internal_service_url` | `AUTHENTICATE_INTERNAL_SERVICE_URL` | `URL` | **required** (In [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) only) |

### Examples

```yaml
authenticate_internal_service_url: https://authenticate.internal
```

```yaml
AUTHENTICATE_INTERNAL_SERVICE_URL=https://authenticate.internal
```

</TabItem>
<TabItem label="Enterprise" value="Enterprise">

Expand All @@ -50,13 +61,3 @@ Kubernetes does not support `authenticate_internal_service_url`

</TabItem>
</Tabs>

### Examples

```yaml
# config file key
authenticate_internal_service_url: https://authenticate.internal

# environment variable
AUTHENTICATE_INTERNAL_SERVICE_URL=https://authenticate.internal
```
26 changes: 14 additions & 12 deletions content/docs/reference/authenticate-service-url.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ keywords:
- Authenticate Service URL
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand Down Expand Up @@ -38,6 +39,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen
| :-- | :-- | :-- | :-- |
| `authenticate_service_url` | `AUTHENTICATE_SERVICE_URL` | `URL` | **required** |

### Examples

```yaml
authenticate_service_url: https://authenticate.corp.example.com
```

```yaml
AUTHENTICATE_SERVICE_URL=https://authenticate.corp.example.com
```

</TabItem>
<TabItem value="Enterprise" label="Enterprise">

Expand All @@ -50,20 +61,11 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen
| :---------------- | :------- | :----------- |
| `AuthenticateUrl` | `URL` | **required** |
ZPain8464 marked this conversation as resolved.
Show resolved Hide resolved

See [Kubernetes `authenticate.url`](/docs/deploy/k8s/reference#authenticate) reference for more information.

</TabItem>
</Tabs>

### Examples

```yaml
ZPain8464 marked this conversation as resolved.
Show resolved Hide resolved
# config file key
authenticate_service_url: https://authenticate.corp.example.com

# environment variable
AUTHENTICATE_SERVICE_URL=https://authenticate.corp.example.com

# ingress
authenticate.url: https://authenticate.corp.example.com
ZPain8464 marked this conversation as resolved.
Show resolved Hide resolved
```

</TabItem>
</Tabs>
21 changes: 11 additions & 10 deletions content/docs/reference/authorize-internal-service-url.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ keywords:
- Authorize Internal Service URL
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand All @@ -28,6 +29,16 @@ If included, **Authorize Internal Service URL** will override Authorize Service
| :-- | :-- | :-- | :-- |
| `authorize_internal_service_url` | `AUTHORIZE_INTERNAL_SERVICE_URL` | `URL` | **required** (Inferred in all-in-one mode to be localhost) |

### Examples

```yaml
authorize_internal_service_url: https://pomerium-authorize-service.default.svc.cluster.local
```

```yaml
AUTHORIZE_INTERNAL_SERVICE_URL=https://localhost:5443
```

</TabItem>
<TabItem value="Enterprise" label="Enterprise">

Expand All @@ -40,13 +51,3 @@ Kubernetes does not support `authorize_internal_service_url`

</TabItem>
</Tabs>

### Examples

```yaml
# config file key
authorize_internal_service_url: https://pomerium-authorize-service.default.svc.cluster.local

# environment variable
AUTHORIZE_INTERNAL_SERVICE_URL=https://localhost:5443
```
8 changes: 8 additions & 0 deletions content/docs/reference/authorize-log-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,9 @@ authorize_log_fields:
- request-id
- path
- ip
```

```yaml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and here as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

AUTHORIZE_LOG_FIELDS:request-id,path,ip
```

Expand All @@ -285,13 +287,19 @@ AUTHORIZE_LOG_FIELDS:request-id,path,ip
# List all HTTP headers
authorize_log_fields:
- headers
```

```yaml
AUTHORIZE_LOG_FIELDS:headers
```

```yaml
# List custom HTTP headers
authorize_log_fields:
- headers.cookie
- headers.content-type
```

```yaml
AUTHORIZE_LOG_FIELDS:headers.cookie,headers.content-type
```
27 changes: 13 additions & 14 deletions content/docs/reference/authorize-service-url.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ keywords:
- Authorize Service URL
pagination_prev: null
pagination_next: null
toc_max_heading_level: 2
---

import Tabs from '@theme/Tabs';
Expand Down Expand Up @@ -39,6 +40,18 @@ If your load balancer does not support gRPC pass-through, you must set this valu
| `authorize_service_url` | `AUTHORIZE_SERVICE_URL` | `URL` | **required** (Inferred in all-in-one mode to be localhost) |
| `authorize_service_urls` | `AUTHORIZE_SERVICE_URLS` | `URL` | **required** (Inferred in all-in-one mode to be localhost) |

### Examples

```yaml
authorize_service_urls:
- https://localhost:5443
- https://authorize.corp.example.com
```

```yaml
AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local
```

</TabItem>
<TabItem value="Enterprise" label="Enterprise">

Expand All @@ -51,17 +64,3 @@ The `authorize_service_url` is not customizable in all-in-one mode with the CRD

</TabItem>
</Tabs>

### Examples

**Examples:**

```yaml
# config file key
authorize_service_urls:
- https://localhost:5443
- https://authorize.corp.example.com

# environment variable
AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local
```
Loading