From 91d4d22156afed59274d9404638e37642f5927d1 Mon Sep 17 00:00:00 2001 From: alexfornuto Date: Mon, 26 Jul 2021 17:16:27 -0500 Subject: [PATCH] update script and apply --- docs/.vuepress/config.js | 14 +- docs/enterprise/console-settings.yaml | 6 +- docs/enterprise/reference.md | 160 ------------------ .../reference/configuration-settings.md | 17 ++ docs/enterprise/reference/configure.md | 40 +++++ docs/enterprise/reference/manage.md | 80 +++++++++ docs/enterprise/reference/reports.md | 21 +++ package.json | 4 +- scripts/generate-console-pages.js | 18 +- 9 files changed, 191 insertions(+), 169 deletions(-) delete mode 100644 docs/enterprise/reference.md create mode 100644 docs/enterprise/reference/configuration-settings.md create mode 100644 docs/enterprise/reference/configure.md create mode 100644 docs/enterprise/reference/manage.md create mode 100644 docs/enterprise/reference/reports.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index ae205cca1..85bfad018 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -210,7 +210,19 @@ module.exports = { ], }, "prometheus", - "reference", + { + title: "Reference", + type: "group", + collapsable: false, + path: "/enterprise/reference/configure", + sidebarDepth: 2, + children: [ + "/enterprise/reference/configuration-settings", + "/enterprise/reference/configure", + "/enterprise/reference/manage", + "/enterprise/reference/reports", + ] + } ], }, ], diff --git a/docs/enterprise/console-settings.yaml b/docs/enterprise/console-settings.yaml index 54a5f53f6..a0319bd09 100644 --- a/docs/enterprise/console-settings.yaml +++ b/docs/enterprise/console-settings.yaml @@ -80,7 +80,7 @@ settings: - name: "Policies" keys: ["Policy"] doc: | - A Policy defines what permissions a set of users or groups has. Policies are applied to [Namespaces](#namespaces) or [Routes](#routes) to associate the set of permissions with a service or set of service, completing the authentication model. + 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. @@ -92,13 +92,13 @@ settings: 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. - ![A policy being constructed in Pomerium Enterprise console allowing a single user access](./img/example-policy-single-user.png) + ![A policy being constructed in Pomerium Enterprise console allowing a single user access](../img/example-policy-single-user.png) #### Pomerium Policy Language From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation. - ![A policy as viewed from the editor tab](./img/example-policy-editor.png) + ![A policy as viewed from the editor tab](../img/example-policy-editor.png) #### Rego diff --git a/docs/enterprise/reference.md b/docs/enterprise/reference.md deleted file mode 100644 index 1582bd69a..000000000 --- a/docs/enterprise/reference.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -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, or as environment variables. 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 -A Route provides access to a service through Pomerium. - - -#### General -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 the Route resides in will also be applied. - - -##### Name - -##### From - -##### To - -##### Redirect - -##### Policies - -##### Pass Identity Headers - -##### Enable Google Cloud Serverless Authentication - -#### Matchers - -#### Rewrite - -#### Timeouts - -#### Headers - -#### Load Balancer - -### Policies -A Policy defines what permissions a set of users or groups has. Policies are applied to [Namespaces](#namespaces) or [Routes](#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. - -![A policy being constructed in Pomerium Enterprise console allowing a single user access](./img/example-policy-single-user.png) - -#### Pomerium Policy Language - -From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation. - -![A policy as viewed from the editor tab](./img/example-policy-editor.png) - -#### Rego - -For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego. - -::: tip -A policy can only support PPL or Rego. Once one is set, the other tab is disabled. -::: - -#### Overrides -- **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**: -- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution. - - -### Certificates - -## Configure - -### Settings - -#### Global - -#### Cookies - -#### Timeouts - -#### GRPC - -#### Tracing - -#### Authenticate - -#### Authorize - -#### Proxy - -### 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 diff --git a/docs/enterprise/reference/configuration-settings.md b/docs/enterprise/reference/configuration-settings.md new file mode 100644 index 000000000..87643c5f7 --- /dev/null +++ b/docs/enterprise/reference/configuration-settings.md @@ -0,0 +1,17 @@ +--- +title: Configuration Settings +lang: en-US +sidebarDepth: 2 +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +# Configuration Settings + +These configuration values are set in the `config.yaml` file for Pomerium Enterprise Console, or as environment variables. Once the console is accessible, configuration is adjusted through the web UI. + +## User Impersonation + +@travis fill me with delicious data! + diff --git a/docs/enterprise/reference/configure.md b/docs/enterprise/reference/configure.md new file mode 100644 index 000000000..235c40f57 --- /dev/null +++ b/docs/enterprise/reference/configure.md @@ -0,0 +1,40 @@ +--- +title: Configure +lang: en-US +sidebarDepth: 2 +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +# Configure + +## Settings + +### Global + +### Cookies + +### Timeouts + +### GRPC + +### Tracing + +### Authenticate + +### Authorize + +### Proxy + +## 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. + diff --git a/docs/enterprise/reference/manage.md b/docs/enterprise/reference/manage.md new file mode 100644 index 000000000..bcd34fb20 --- /dev/null +++ b/docs/enterprise/reference/manage.md @@ -0,0 +1,80 @@ +--- +title: Manage +lang: en-US +sidebarDepth: 2 +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +# Manage + +## Routes + +A Route provides access to a service through Pomerium. + +### General + +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 the Route resides in will also be applied. + +#### Name + +#### From + +#### To + +#### Redirect + +#### Policies + +#### Pass Identity Headers + +#### Enable Google Cloud Serverless Authentication + +### Matchers + +### Rewrite + +### Timeouts + +### Headers + +### Load Balancer + +## 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. + +![A policy being constructed in Pomerium Enterprise console allowing a single user access](../img/example-policy-single-user.png) + +#### Pomerium Policy Language + +From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation. + +![A policy as viewed from the editor tab](../img/example-policy-editor.png) + +#### Rego + +For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego. + +::: tip +A policy can only support PPL or Rego. Once one is set, the other tab is disabled. +::: + +#### Overrides +- **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**: +- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution. + +## Certificates + diff --git a/docs/enterprise/reference/reports.md b/docs/enterprise/reference/reports.md new file mode 100644 index 000000000..0ec6fda45 --- /dev/null +++ b/docs/enterprise/reference/reports.md @@ -0,0 +1,21 @@ +--- +title: Reports +lang: en-US +sidebarDepth: 2 +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +# Reports + +## Traffic + +## Runtime + +## Sessions + +## Events + +## Deployments + diff --git a/package.json b/package.json index 11ee74c54..368ef1bb6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "devDependencies": { "@vuepress/plugin-google-analytics": "1.8.2", + "js-yaml": "^4.1.0", "vuepress": "1.8.2", "vuepress-plugin-check-md": "0.0.2", "vuepress-plugin-element-tabs": "^0.2.8", @@ -9,7 +10,8 @@ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs", - "docs:check-md": "vuepress check-md" + "docs:check-md": "vuepress check-md", + "buildref": "node scripts/generate-console-pages.js" }, "dependencies": { "esm": "3.2.25" diff --git a/scripts/generate-console-pages.js b/scripts/generate-console-pages.js index 05d0fd597..37b97f971 100755 --- a/scripts/generate-console-pages.js +++ b/scripts/generate-console-pages.js @@ -6,14 +6,24 @@ const yaml = require('js-yaml'); // Functions const writePage = (setting) => { - console.log('Generating ', setting.name, ".md") + console.log('Generating ', setting.name, " page") + let frontmatter = `--- +title: ${setting.name} +lang: en-US +sidebarDepth: 2 +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +` let path = './docs/enterprise/reference/' + setting.name.replace(/\s/g, '-').toLowerCase() + ".md" console.log("path=", path) //For Debugging - let header = '# ' + setting.name + '\n' + let header = '# ' + setting.name + '\n' + '\n' let body = setting.doc ? setting.doc.toString() + '\n' : '' let moreBody = setting.settings ? setting.settings.map(subsection => writeSubsection(subsection, 2)).join('') : '' - let content = header + body + moreBody + let content = frontmatter + header + body + moreBody fs.writeFileSync(path, content) } @@ -22,7 +32,7 @@ const writeSubsection = (subsection, depth) => { if (!subsection.name) { return } - let header = '#'.repeat(depth) + ' ' + subsection.name + '\n' + let header = '#'.repeat(depth) + ' ' + subsection.name + '\n' + '\n' let subContent = subsection.doc ? subsection.doc.toString() + '\n' : '' subsection.attributes ? subContent = subContent + subsection.attributes.toString() : null subsection.settings ? subContent = subContent + subsection.settings.map(turtles => writeSubsection(turtles, depth + 1)).join('') : ''