mirror of
https://github.com/pomerium/pomerium.git
synced 2025-06-15 09:12:43 +02:00
Enterprise settings docs (#2397)
* init console-specific reference docs files * remove shortdoc for name * init Enterprise Reference doc
This commit is contained in:
Alex Fornuto
alexfornuto
parent
9054106359
commit
e0b90a0750
6 changed files with 273 additions and 1 deletions
|
|
@ -210,7 +210,7 @@ module.exports = {
|
|||
],
|
||||
},
|
||||
"prometheus",
|
||||
"concepts",
|
||||
"reference",
|
||||
],
|
||||
},
|
||||
],
|
||||
|
|
|
|||
109
docs/enterprise/console-settings.yaml
Normal file
109
docs/enterprise/console-settings.yaml
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
preamble: |
|
||||
---
|
||||
title: Reference
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Pomerium Enterprise Console Settings
|
||||
|
||||
The Pomerium Enterprise Console is initially configured using a configuration file ([YAML]/[JSON]/[TOML]) or environment variables. In general, environmental variable keys are identical to config file keys but are uppercase.
|
||||
|
||||
If you are coming from a Kubernetes or docker background this should feel familiar. If not, check out the following primers.
|
||||
|
||||
- [Store config in the environment](https://12factor.net/config)
|
||||
- [Kubernetes: Environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
|
||||
- [Kubernetes: Config Maps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/)
|
||||
- [Docker: Environment variables](https://docs.docker.com/compose/environment-variables/)
|
||||
|
||||
Using both [environmental variables] and config file keys is allowed and encouraged (for instance, secret keys are probably best set as environmental variables). However, if duplicate configuration keys are found, environment variables take precedence.
|
||||
|
||||
Additional configuration and the setting of routes and policies is performed through the web user interface (**UI**).
|
||||
|
||||
postamble: |
|
||||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: ../docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
[yaml]: https://en.wikipedia.org/wiki/YAML
|
||||
|
||||
settings:
|
||||
- name: "Configuration Settings"
|
||||
doc: |
|
||||
These configuration values are set in the `config.yaml` file for Pomerium Enterprise Console. Once the console is accessible, configuration is adjusted through the web UI.
|
||||
settings:
|
||||
- keys: ["name"]
|
||||
shortdoc: All Routes, Policies, Certificates and Namespaces require a Name. This is a human-readable value used in the Enterprise Console interface.
|
||||
- name: "User Impersonation"
|
||||
keys: ["user impersonation"]
|
||||
doc: |
|
||||
@travis fill me with delicious data!
|
||||
- name: "Reports"
|
||||
settings:
|
||||
- name: "Traffic"
|
||||
- name: "Runtime"
|
||||
- name: "Sessions"
|
||||
- name: "Events"
|
||||
- name: "Deployments"
|
||||
- name: "Manage"
|
||||
settings:
|
||||
- name: "Routes"
|
||||
- name: "Policies"
|
||||
keys: ["Policy"]
|
||||
doc: |
|
||||
A Policy 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.
|
||||
|
||||
::: tip
|
||||
This is a separate concept from [policies](../reference/#policy) in the non-enterprise model. In open-source Pomerium, the `policy` block defines both routes and access.
|
||||
:::
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
#### Web UI
|
||||
|
||||
From the **BUILDER** tab, users can add allow or deny blocks to a policy, containing and/or/not/nor logic to allow or deny sets of users and groups.
|
||||
|
||||
|
||||
|
||||
#### Pomerium Policy Language
|
||||
|
||||
From the **EDITOR** tab users can write policies in Pomerium Policy Language, a YAML-based notation.
|
||||
|
||||
|
||||
|
||||
#### Rego
|
||||
|
||||
For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego.
|
||||
- name: "Certificates"
|
||||
- name: "Configure"
|
||||
settings:
|
||||
- name: "Settings"
|
||||
settings:
|
||||
- name: "Global"
|
||||
- name: "Cookies"
|
||||
- name: "Timeouts"
|
||||
- name: "GRPC"
|
||||
- name: "Tracing"
|
||||
- name: "Authenticate"
|
||||
- name: "Authorize"
|
||||
- name: "Proxy"
|
||||
- name: "Service Accounts"
|
||||
doc: |
|
||||
<!-- Explain Service Accounts -->
|
||||
- name: "Namespaces"
|
||||
keys: ["namespace"]
|
||||
doc: |
|
||||
A Namespace is a collection of users, groups, routes, and policies that allows system administrators to organize, manage, and delegate permissions across their infrastructure.
|
||||
|
||||
- Policies can be optional or enforced on a Namespace, and they can be nested to create inheritance.
|
||||
- Users or groups can be granted permission to edit access to routes within a Namespace, allowing them self-serve access to the routes critical to their work.
|
||||
BIN
docs/enterprise/img/example-policy-editor.png
Normal file
BIN
docs/enterprise/img/example-policy-editor.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
BIN
docs/enterprise/img/example-policy-single-user.png
Normal file
BIN
docs/enterprise/img/example-policy-single-user.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
121
docs/enterprise/reference.md
Normal file
121
docs/enterprise/reference.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
title: Reference
|
||||
lang: en-US
|
||||
sidebarDepth: 2
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
# Pomerium Enterprise Console Settings
|
||||
|
||||
The Pomerium Enterprise Console is initially configured using a configuration file ([YAML]/[JSON]/[TOML]) or environment variables. In general, environmental variable keys are identical to config file keys but are uppercase.
|
||||
|
||||
If you are coming from a Kubernetes or docker background this should feel familiar. If not, check out the following primers.
|
||||
|
||||
- [Store config in the environment](https://12factor.net/config)
|
||||
- [Kubernetes: Environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
|
||||
- [Kubernetes: Config Maps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/)
|
||||
- [Docker: Environment variables](https://docs.docker.com/compose/environment-variables/)
|
||||
|
||||
Using both [environmental variables] and config file keys is allowed and encouraged (for instance, secret keys are probably best set as environmental variables). However, if duplicate configuration keys are found, environment variables take precedence.
|
||||
|
||||
Additional configuration and the setting of routes and policies is performed through the web user interface (**UI**).
|
||||
|
||||
|
||||
## Configuration Settings
|
||||
These configuration values are set in the `config.yaml` file for Pomerium Enterprise Console. Once the console is accessible, configuration is adjusted through the web UI.
|
||||
|
||||
|
||||
|
||||
### User Impersonation
|
||||
@travis fill me with delicious data!
|
||||
|
||||
|
||||
## Reports
|
||||
|
||||
### Traffic
|
||||
|
||||
### Runtime
|
||||
|
||||
### Sessions
|
||||
|
||||
### Events
|
||||
|
||||
### Deployments
|
||||
|
||||
## Manage
|
||||
|
||||
### Routes
|
||||
|
||||
### Policies
|
||||
A Policy 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.
|
||||
|
||||
::: tip
|
||||
This is a separate concept from [policies](../reference/#policy) in the non-enterprise model. In open-source Pomerium, the `policy` block defines both routes and access.
|
||||
:::
|
||||
|
||||
Policies can be constructed three ways:
|
||||
|
||||
#### Web UI
|
||||
|
||||
From the **BUILDER** tab, users can add allow or deny blocks to a policy, containing and/or/not/nor logic to allow or deny sets of users and groups.
|
||||
|
||||
|
||||
|
||||
#### Pomerium Policy Language
|
||||
|
||||
From the **EDITOR** tab users can write policies in Pomerium Policy Language, a YAML-based notation.
|
||||
|
||||
|
||||
|
||||
#### Rego
|
||||
|
||||
For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego.
|
||||
|
||||
|
||||
### Certificates
|
||||
|
||||
## Configure
|
||||
|
||||
### Settings
|
||||
|
||||
#### Global
|
||||
|
||||
#### Cookies
|
||||
|
||||
#### Timeouts
|
||||
|
||||
#### GRPC
|
||||
|
||||
#### Tracing
|
||||
|
||||
#### Authenticate
|
||||
|
||||
#### Authorize
|
||||
|
||||
#### Proxy
|
||||
|
||||
### Service Accounts
|
||||
<!-- Explain Service Accounts -->
|
||||
|
||||
|
||||
### Namespaces
|
||||
A Namespace is a collection of users, groups, routes, and policies that allows system administrators to organize, manage, and delegate permissions across their infrastructure.
|
||||
|
||||
- Policies can be optional or enforced on a Namespace, and they can be nested to create inheritance.
|
||||
- Users or groups can be granted permission to edit access to routes within a Namespace, allowing them self-serve access to the routes critical to their work.
|
||||
|
||||
|
||||
[base64 encoded]: https://en.wikipedia.org/wiki/Base64
|
||||
[elliptic curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters
|
||||
[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
|
||||
[identity provider]: ../docs/identity-providers/
|
||||
[json]: https://en.wikipedia.org/wiki/JSON
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
|
||||
[okta]: ../docs/identity-providers/okta.md
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[signed headers]: ../docs/topics/getting-users-identity.md
|
||||
[toml]: https://en.wikipedia.org/wiki/TOML
|
||||
[yaml]: https://en.wikipedia.org/wiki/YAML
|
||||
42
scripts/generate-console-settings-docs.py
Executable file
42
scripts/generate-console-settings-docs.py
Executable file
|
|
@ -0,0 +1,42 @@
|
|||
#!/usr/bin/env python3
|
||||
import os.path
|
||||
from typing import Any, IO
|
||||
import yaml
|
||||
|
||||
|
||||
def main():
|
||||
d = os.path.join(os.path.dirname(__file__),
|
||||
"..", "docs", "enterprise")
|
||||
d = os.path.normpath(d)
|
||||
print(f"generating {d}/reference.md")
|
||||
|
||||
f = open(os.path.join(d, "console-settings.yaml"))
|
||||
doc = yaml.full_load(f)
|
||||
f.close()
|
||||
|
||||
f = open(os.path.join(os.path.dirname(__file__),
|
||||
"..", "docs", "enterprise", "reference.md"), "w")
|
||||
f.write(f"{doc['preamble']}\n")
|
||||
write_setting(f, 1, doc)
|
||||
f.write(f"{doc['postamble']}")
|
||||
f.close()
|
||||
|
||||
|
||||
def write_setting(w, depth, setting):
|
||||
if 'name' in setting:
|
||||
w.write(f"{'#' * depth} {setting.get('name', '')}\n")
|
||||
|
||||
if 'attributes' in setting:
|
||||
w.write(f"{setting.get('attributes','')}\n")
|
||||
|
||||
if 'doc' in setting:
|
||||
w.write(f"{setting.get('doc', '')}\n")
|
||||
|
||||
w.write("\n")
|
||||
|
||||
for subsetting in setting.get('settings', []):
|
||||
write_setting(w, depth+1, subsetting)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Loading…
Add table
Add a link
Reference in a new issue