From b6171c023a4edb1ae8aa38890e77af26335cbb4c Mon Sep 17 00:00:00 2001 From: Denis Mishin Date: Mon, 10 Feb 2025 16:51:46 -0500 Subject: [PATCH 1/3] add enterprise/terraform docs --- .../deploy/enterprise/configure-terraform.md | 104 ++++++++++++++++++ cspell.json | 1 + package.json | 4 +- src/theme/NotFound/Content/index.tsx | 34 ------ 4 files changed, 108 insertions(+), 35 deletions(-) create mode 100644 content/docs/deploy/enterprise/configure-terraform.md delete mode 100644 src/theme/NotFound/Content/index.tsx diff --git a/content/docs/deploy/enterprise/configure-terraform.md b/content/docs/deploy/enterprise/configure-terraform.md new file mode 100644 index 000000000..f93e64b8a --- /dev/null +++ b/content/docs/deploy/enterprise/configure-terraform.md @@ -0,0 +1,104 @@ +--- +title: Configure with Terraform +description: Learn how to manage your Pomerium Enterprise configuration using Terraform, including authentication setup, resource management, and deployment examples. +keywords: + [ + Pomerium Enterprise, + Terraform, + IaC, + infrastructure as code, + configuration management, + service accounts, + provider configuration, + ] +--- + +# Configure with Terraform + +Pomerium Enterprise can be configured and managed using Terraform through our official provider. This enables you to manage your Pomerium Enterprise resources as infrastructure as code, making it easier to version, review, and automate your configuration changes. + +## Provider Configuration + +To use the Pomerium Terraform provider, first configure it in your Terraform configuration: + +```hcl +terraform { + required_providers { + pomerium = { + source = "pomerium/pomerium" + version = "~> 0.0.7" + } + } +} + +provider "pomerium" { + api_url = "https://console-api.your-domain.com" + # Choose one of the authentication methods below +} +``` + +## Authentication Methods + +The provider supports two authentication methods: + +### 1. Service Account Token (Recommended) + +This method uses a [Pomerium Enterprise Service Account](/docs/capabilities/service-accounts) and provides fine-grained access control at the namespace level: + +```hcl +provider "pomerium" { + api_url = "https://console-api.your-domain.com" + service_account_token = var.pomerium_service_account_token +} +``` + +### 2. Bootstrap Service Account + +This method requires enabling bootstrap service accounts in your Enterprise Console: + +```hcl +provider "pomerium" { + api_url = "https://console-api.your-domain.com" + shared_secret_b64 = var.shared_secret_b64 +} +``` + +:::warning The Bootstrap Service Account method requires setting `BOOTSTRAP_SERVICE_ACCOUNT=true` in your Enterprise Console configuration. ::: + +## Example + +```hcl + resource "pomerium_namespace" "engineering" { + name = "engineering" + } + + resource "pomerium_policy" "engineering_policy" { + name = "engineering-policy" + namespace = pomerium_namespace.engineering.id + ppl = yamlencode({ + allow = { + and = [ + { + groups = { + has = "engineering" + } + } + ] + } + }) + } + + resource "pomerium_route" "internal_tools" { + name = "internal-tools" + namespace = pomerium_namespace.engineering.id + from = "https://tools.example.com" + to = ["https://internal-tools.local"] + } +``` + +## Next Steps + +- [Provider Documentation](https://registry.terraform.io/providers/pomerium/pomerium/latest/docs) +- [Example Configurations](https://github.com/pomerium/enterprise-terraform-provider/tree/main/examples) +- [Enterprise API Reference](/docs/internals/management-api-enterprise) +- [Service Accounts](/docs/capabilities/service-accounts) diff --git a/cspell.json b/cspell.json index eaba9aa71..5cf1c01b1 100644 --- a/cspell.json +++ b/cspell.json @@ -217,6 +217,7 @@ "tgroth", "unvalidated", "Whitelabeling", + "yamlencode", "yourcompany", "Zipkin" ], diff --git a/package.json b/package.json index c50968e9d..914d10909 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,9 @@ "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", "format": "prettier --write .", - "format-check": "prettier --check ." + "format-check": "prettier --check .", + "precommit": "npm run format-check && npm run cspell", + "cspell": "cspell \"**/*\"" }, "dependencies": { "@docusaurus/core": "^3.6.3", diff --git a/src/theme/NotFound/Content/index.tsx b/src/theme/NotFound/Content/index.tsx deleted file mode 100644 index dc5a92d7d..000000000 --- a/src/theme/NotFound/Content/index.tsx +++ /dev/null @@ -1,34 +0,0 @@ -import React, {JSX, useEffect} from 'react'; -import Content from '@theme-original/NotFound/Content'; -import type ContentType from '@theme/NotFound/Content'; -import type {WrapperProps} from '@docusaurus/types'; - -type Props = WrapperProps; - -export default function ContentWrapper(props: Props): JSX.Element { - - useEffect(() => { - if (typeof window !== 'undefined' && window?.gtag) { - //normal page_view event - gtag("event", "page_view", { - page_title: "404 Not Found", - page_path: window.location.pathname, - event_category: "Errors", - event_label: "404" - }); - - //custom event that might be easier to work with - window.gtag("event", "not_found", { - page_title: "Page Not Found", - page_path: window.location.pathname, - event_category: "Errors", - event_label: "404" - }); - } - }, []) - return ( - <> - - - ); -} From f7b867ba1e75606d3cc0328cdf413f52fadd63c1 Mon Sep 17 00:00:00 2001 From: Denis Mishin Date: Tue, 11 Feb 2025 10:27:13 -0500 Subject: [PATCH 2/3] fix formatting --- content/docs/deploy/enterprise/configure-terraform.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/docs/deploy/enterprise/configure-terraform.md b/content/docs/deploy/enterprise/configure-terraform.md index f93e64b8a..dd86deece 100644 --- a/content/docs/deploy/enterprise/configure-terraform.md +++ b/content/docs/deploy/enterprise/configure-terraform.md @@ -63,7 +63,11 @@ provider "pomerium" { } ``` -:::warning The Bootstrap Service Account method requires setting `BOOTSTRAP_SERVICE_ACCOUNT=true` in your Enterprise Console configuration. ::: +:::warning + +The Bootstrap Service Account method requires setting `BOOTSTRAP_SERVICE_ACCOUNT=true` in your Enterprise Console configuration. + +::: ## Example From f567c6811577adc8ebb87bd7883c0fedf97ad0ff Mon Sep 17 00:00:00 2001 From: Denis Mishin Date: Mon, 24 Feb 2025 15:54:52 -0500 Subject: [PATCH 3/3] update docs --- .../deploy/enterprise/configure-terraform.md | 33 ++++++++++++++++--- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/content/docs/deploy/enterprise/configure-terraform.md b/content/docs/deploy/enterprise/configure-terraform.md index dd86deece..15507efd8 100644 --- a/content/docs/deploy/enterprise/configure-terraform.md +++ b/content/docs/deploy/enterprise/configure-terraform.md @@ -15,7 +15,12 @@ keywords: # Configure with Terraform -Pomerium Enterprise can be configured and managed using Terraform through our official provider. This enables you to manage your Pomerium Enterprise resources as infrastructure as code, making it easier to version, review, and automate your configuration changes. +Pomerium Enterprise can be configured and managed using Terraform through the [official Pomerium provider](https://registry.terraform.io/providers/pomerium/pomerium/latest/docs). This enables you to manage your Pomerium Enterprise resources as infrastructure as code, making it easier to version, review, and automate your configuration changes. + +## Prerequisites + +- Pomerium Enterprise must be running first +- Console API must be accessible ## Provider Configuration @@ -39,9 +44,9 @@ provider "pomerium" { ## Authentication Methods -The provider supports two authentication methods: +The provider supports one of the two authentication methods: -### 1. Service Account Token (Recommended) +### 1. Service Account Token This method uses a [Pomerium Enterprise Service Account](/docs/capabilities/service-accounts) and provides fine-grained access control at the namespace level: @@ -52,9 +57,18 @@ provider "pomerium" { } ``` +The Pomerium API route should authorize the relative pomerium service account access: + +```yaml +- allow: + or: + - user: + is: 'bootstrap-014e587b-3f4b-4fcf-90a9-f6ecdf8154af.pomerium' +``` + ### 2. Bootstrap Service Account -This method requires enabling bootstrap service accounts in your Enterprise Console: +This method requires enabling bootstrap service accounts in your Enterprise Console. It may be used if you wish to configure Pomerium Enterprise part of the installation process, without accessing its UI to create a new service account. ```hcl provider "pomerium" { @@ -63,6 +77,15 @@ provider "pomerium" { } ``` +The Pomerium API route should have the following policy, with the special bootstrap service account user ID. + +```yaml +- allow: + or: + - user: + is: 'bootstrap-014e587b-3f4b-4fcf-90a9-f6ecdf8154af.pomerium' +``` + :::warning The Bootstrap Service Account method requires setting `BOOTSTRAP_SERVICE_ACCOUNT=true` in your Enterprise Console configuration. @@ -103,6 +126,6 @@ The Bootstrap Service Account method requires setting `BOOTSTRAP_SERVICE_ACCOUNT ## Next Steps - [Provider Documentation](https://registry.terraform.io/providers/pomerium/pomerium/latest/docs) -- [Example Configurations](https://github.com/pomerium/enterprise-terraform-provider/tree/main/examples) +- [Example Configurations](https://github.com/pomerium/enterprise-terraform-provider/tree/main/example) - [Enterprise API Reference](/docs/internals/management-api-enterprise) - [Service Accounts](/docs/capabilities/service-accounts)