From d93a563bc4fc0300ef44ac4b01ac28f98a05fc5a Mon Sep 17 00:00:00 2001 From: Kenny Rasschaert Date: Mon, 14 Oct 2024 18:32:57 +0200 Subject: [PATCH] docs and examples --- docs/data-sources/cluster.md | 6 + docs/index.md | 155 +++--------------- docs/resources/cluster.md | 21 +++ docs/resources/cluster_settings.md | 58 +++++++ docs/resources/policy.md | 51 ++++++ docs/resources/route.md | 46 ++++++ .../pomeriumzero_cluster/data-source.tf | 3 + examples/provider/provider.tf | 18 ++ .../resources/pomeriumzero_cluster/import.sh | 2 + .../pomeriumzero_cluster/resource.tf | 9 + .../pomeriumzero_cluster_settings/import.sh | 2 + .../pomeriumzero_cluster_settings/resource.tf | 46 ++++++ .../resources/pomeriumzero_policy/import.sh | 2 + .../resources/pomeriumzero_policy/resource.tf | 39 +++++ .../resources/pomeriumzero_route/import.sh | 2 + .../resources/pomeriumzero_route/resource.tf | 34 ++++ 16 files changed, 362 insertions(+), 132 deletions(-) create mode 100644 examples/data-sources/pomeriumzero_cluster/data-source.tf create mode 100644 examples/provider/provider.tf create mode 100644 examples/resources/pomeriumzero_cluster/import.sh create mode 100644 examples/resources/pomeriumzero_cluster/resource.tf create mode 100644 examples/resources/pomeriumzero_cluster_settings/import.sh create mode 100644 examples/resources/pomeriumzero_cluster_settings/resource.tf create mode 100644 examples/resources/pomeriumzero_policy/import.sh create mode 100644 examples/resources/pomeriumzero_policy/resource.tf create mode 100644 examples/resources/pomeriumzero_route/import.sh create mode 100644 examples/resources/pomeriumzero_route/resource.tf diff --git a/docs/data-sources/cluster.md b/docs/data-sources/cluster.md index 93dcbc6..8d81975 100644 --- a/docs/data-sources/cluster.md +++ b/docs/data-sources/cluster.md @@ -10,7 +10,13 @@ description: |- Pomerium Zero Cluster data source +## Example Usage +```terraform +data "pomeriumzero_cluster" "default" { + name = "gifted-nightingale-1337" +} +``` ## Schema diff --git a/docs/index.md b/docs/index.md index 68d63f6..882d5d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,150 +1,41 @@ -# Terraform Provider for Pomerium Zero +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "pomeriumzero Provider" +subcategory: "" +description: |- + +--- -This Terraform provider allows you to manage resources in [Pomerium Zero](https://www.pomerium.com/zero), a cloud-native identity-aware access proxy. +# pomeriumzero Provider -## Usage -```hcl + +## Example Usage + +```terraform terraform { required_providers { pomeriumzero = { - source = "rasschaert/pomeriumzero" + source = "rasschaert/pomeriumzero" } } } provider "pomeriumzero" { - # Get an API token at https://console.pomerium.app/app/management/api-tokens - api_token = var.pomerium_zero_api_token -} - -``` - -## Data Sources - -### pomeriumzero_cluster - -Retrieves information about a Pomerium Zero cluster. - -This can be used to reference the cluster ID for managing the cluster configuration in a `pomeriumzero_cluster_settings` resource. - -It can also be used to reference the namespace ID for creating `pomeriumzero_route` and `pomeriumzero_policy` resources on this cluster. - -This may be useful if you're managing `pomeriumzero_route` or `pomeriumzero_policy` resources in a terraform state that does not contain a `pomeriumzero_cluster` resource. - -```hcl -data "pomeriumzero_cluster" "default" { - name = "gifted-nightingale-1337" -} - -``` - -## Resources - -### pomeriumzero_cluster - -You can use this resource to change the name of your Pomerium Zero cluster. - -This resource can be used to reference the cluster ID for managing the cluster configuration in a `pomeriumzero_cluster_settings` resource. - -It can also be used to reference the namespace ID for creating `pomeriumzero_route` and `pomeriumzero_policy` resources on this cluster. - -```hcl -resource "pomeriumzero_cluster" "default" { - name = "gifted-nightingale-1337" - domain = "gifted-nightingale-1337" -} - -``` - -### pomeriumzero_cluster_settings - -Manages the settings for a Pomerium Zero cluster. - -```hcl - -import { - id = data.pomeriumzero_cluster.default.id - to = pomeriumzero_cluster_settings.default -} - -resource "pomeriumzero_cluster_settings" "default" { - address = ":443" - authenticate_service_url = "https://authenticate.gifted-nightingale-1337.pomerium.app" - auto_apply_changesets = true - cookie_expire = "8h0m0s" - cookie_http_only = true - cookie_name = "_pomerium" - default_upstream_timeout = "30s" - dns_lookup_family = "V4_PREFERRED" - identity_provider = var.pomerium_zero_identity_provider - identity_provider_client_id = var.pomerium_zero_identity_provider_client_id - identity_provider_client_secret = var.pomerium_zero_identity_provider_client_secret - identity_provider_url = var.pomerium_zero_identity_provider_url - log_level = "info" - pass_identity_headers = false - proxy_log_level = "info" - skip_xff_append = false - timeout_idle = "5m0s" - timeout_read = "30s" - timeout_write = "0s" - tracing_sample_rate = 0.0001 -} - -``` - -### pomeriumzero_policy - -Manages policies in Pomerium Zero. - -If you want to apply a policy on one or more routes, you don't do it in the `pomeriumzero_policy` resource, but in the relevant `pomeriumzero_route` resources. - -```hcl -resource "pomeriumzero_policy" "allow_foobar_group_members" { - name = "Allow Foobar group members" - description = "Member of the Foobar group are allowed." - explanation = "You are not a member of the Foobar group." - remediation = "Please contact the IT team if you think this is an error." - enforced = false - namespace_id = data.pomeriumzero_cluster.default.namespace_id - ppl = jsonencode({ - allow = { - or = [ - { - "claim/groups" = "foobar" - } - ] - } - }) + api_token = var.pomerium_zero_api_token } -``` -### pomeriumzero_route - -Manages routes in Pomerium Zero. - -```hcl -resource "pomeriumzero_route" "foobar_tooling" { - name = "PoC devops" - from = "https://foobar-tool.example.com" - to = ["https://foobar-tool.examplecorp.lan/"] - prefix = "/home/" - prefix_rewrite = "/home/" - namespace_id = data.pomeriumzero_cluster.default.namespace_id - - allow_websockets = false - preserve_host_header = false - - policy_ids = [ - pomeriumzero_policy.allow_foobar_group_members.id - ] +# Get an API token at https://console.pomerium.app/app/management/api-tokens +variable "pomerium_zero_api_token" { + sensitive = true + description = "Pomerium Zero API token" + type = string } ``` -## Contributing - -Contributions are welcome! Please feel free to submit a Pull Request. + +## Schema -## License +### Required -This project is licensed under the [Mozilla Public License 2.0](LICENSE). +- `api_token` (String, Sensitive) The API token for authenticating with Pomerium Zero diff --git a/docs/resources/cluster.md b/docs/resources/cluster.md index 09d2025..c62c54e 100644 --- a/docs/resources/cluster.md +++ b/docs/resources/cluster.md @@ -10,7 +10,19 @@ description: |- Manages a Pomerium Zero Cluster. This resource allows you to create, update, and delete clusters in your Pomerium Zero organization. +## Example Usage +```terraform +import { + id = "default" + to = pomeriumzero_cluster.default +} + +resource "pomeriumzero_cluster" "default" { + name = "gifted-nightingale-1337" + domain = "gifted-nightingale-1337" +} +``` ## Schema @@ -28,3 +40,12 @@ Manages a Pomerium Zero Cluster. This resource allows you to create, update, and - `id` (String) The unique identifier of the cluster. This is automatically generated by Pomerium Zero. - `namespace_id` (String) The namespace ID of the cluster. This is automatically generated by Pomerium Zero and is used for creating routes and policies. - `updated_at` (String) The timestamp when the cluster was last updated. + +## Import + +Import is supported using the following syntax: + +```shell +# Cluster can be imported by specifying the name. +terraform import pomeriumzero_cluster.default gifted-nightingale-1337 +``` diff --git a/docs/resources/cluster_settings.md b/docs/resources/cluster_settings.md index 0aece53..7da5614 100644 --- a/docs/resources/cluster_settings.md +++ b/docs/resources/cluster_settings.md @@ -10,7 +10,56 @@ description: |- Manages settings for a Pomerium Zero Cluster. This resource allows you to configure various aspects of your cluster, including authentication, timeouts, and logging. +## Example Usage +```terraform +resource "pomeriumzero_cluster_settings" "default" { + address = ":443" + auto_apply_changesets = true + cookie_expire = "14h0m0s" + cookie_http_only = true + cookie_name = "_pomerium" + default_upstream_timeout = "30s" + dns_lookup_family = "V4_PREFERRED" + authenticate_service_url = "https://authenticate.${pomeriumzero_cluster.default.fqdn}" + identity_provider = var.pomerium_zero_identity_provider + identity_provider_client_id = var.pomerium_zero_identity_provider_client_id + identity_provider_client_secret = var.pomerium_zero_identity_provider_client_secret + identity_provider_url = var.pomerium_zero_identity_provider_url + log_level = "info" + pass_identity_headers = false + proxy_log_level = "info" + skip_xff_append = false + timeout_idle = "5m0s" + timeout_read = "30s" + timeout_write = "0s" + tracing_sample_rate = 0.0001 +} + +variable "pomerium_zero_identity_provider" { + sensitive = false + description = "Pomerium Zero Identity Provider" + type = string +} + +variable "pomerium_zero_identity_provider_url" { + sensitive = false + description = "Pomerium Zero Identity Provider URL" + type = string +} + +variable "pomerium_zero_identity_provider_client_id" { + sensitive = false + description = "Pomerium Zero Identity Provider Client ID" + type = string +} + +variable "pomerium_zero_identity_provider_client_secret" { + sensitive = true + description = "Pomerium Zero Identity Provider Client Secret" + type = string +} +``` ## Schema @@ -41,3 +90,12 @@ Manages settings for a Pomerium Zero Cluster. This resource allows you to config ### Read-Only - `id` (String) The unique identifier of the cluster settings. This corresponds to the cluster ID. + +## Import + +Import is supported using the following syntax: + +```shell +# Cluster settings can be imported by specifying the cluster id. You can get that using a command like terraform state show pomeriumzero_cluster.default +terraform import pomeriumzero_cluster_settings.default bZPhcRUBcFwVlLCEPsSHMTxEqLR +``` diff --git a/docs/resources/policy.md b/docs/resources/policy.md index adcf365..79b7e06 100644 --- a/docs/resources/policy.md +++ b/docs/resources/policy.md @@ -10,7 +10,49 @@ description: |- Manages a Pomerium Zero Policy. +## Example Usage +```terraform +resource "pomeriumzero_policy" "allow_any_authenticated_user" { + name = "Allow Any Authenticated User" + description = "Any authenticated user is allowed." + explanation = "You are not authenticated." + remediation = "" + enforced = false + namespace_id = pomeriumzero_cluster.default.namespace_id + ppl = jsonencode( + [ + { + allow = { + and = [ + { + authenticated_user = 1 + }, + ] + } + }, + ] + ) +} + +resource "pomeriumzero_policy" "allow_foobar_group_members" { + name = "Allow Foobar group members" + description = "Member of the Foobar group are allowed." + explanation = "You are not a member of the Foobar group." + remediation = "Please contact the IT team if you think this is an error." + enforced = false + namespace_id = data.pomeriumzero_cluster.default.namespace_id + ppl = jsonencode({ + allow = { + or = [ + { + "claim/groups" = "foobar" + } + ] + } + }) +} +``` ## Schema @@ -28,3 +70,12 @@ Manages a Pomerium Zero Policy. ### Read-Only - `id` (String) The unique identifier of the policy. + +## Import + +Import is supported using the following syntax: + +```shell +# Policies can be imported by specifying the policy ID. You can see the policy ID in the URL when viewing the policy in the Pomerium console. +terraform import pomeriumzero_policy.allow_any_authenticated_user bHeymGDZrHpQeRtyTsQTXJvkHkt +``` diff --git a/docs/resources/route.md b/docs/resources/route.md index cec75f4..0cb4788 100644 --- a/docs/resources/route.md +++ b/docs/resources/route.md @@ -10,7 +10,44 @@ description: |- Manages a route resource in Pomerium Zero. +## Example Usage +```terraform +resource "pomeriumzero_route" "verify" { + name = "Verify" + from = "https://verify.${pomeriumzero_cluster.default.fqdn}" + to = ["https://verify.pomerium.com"] + namespace_id = data.pomeriumzero_cluster.default.namespace_id + + allow_websockets = false + preserve_host_header = false + + policy_ids = [ + pomeriumzero_policy.allow_any_authenticated_user.id + ] + + pass_identity_headers = true +} + + +resource "pomeriumzero_route" "foobar_tooling" { + name = "Foobar Tooling" + # The external URL that the Pomerium Zero cluster should listen on + from = "https://foobar-tool.example.com" + # A system that is only reachable by the Pomerium Zero cluster via a private network + to = ["https://foobar-tool.examplecorp.lan/"] + # Only match requests that begin with /home/ + prefix = "/home/" + # Make sure to also include the prefix when forwarding the requests to the origin + prefix_rewrite = "/home/" + namespace_id = data.pomeriumzero_cluster.default.namespace_id + allow_websockets = false + preserve_host_header = false + policy_ids = [ + pomeriumzero_policy.allow_foobar_group_members.id + ] +} +``` ## Schema @@ -39,3 +76,12 @@ Manages a route resource in Pomerium Zero. ### Read-Only - `id` (String) The unique identifier of the route. + +## Import + +Import is supported using the following syntax: + +```shell +# Routes can be imported by specifying the route ID. You can see the route ID in the URL when viewing the policy in the Pomerium console. +terraform import pomeriumzero_route.verify bRMWzWNvrZruhmMgashHJegGeGL +``` diff --git a/examples/data-sources/pomeriumzero_cluster/data-source.tf b/examples/data-sources/pomeriumzero_cluster/data-source.tf new file mode 100644 index 0000000..d1f19b7 --- /dev/null +++ b/examples/data-sources/pomeriumzero_cluster/data-source.tf @@ -0,0 +1,3 @@ +data "pomeriumzero_cluster" "default" { + name = "gifted-nightingale-1337" +} diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf new file mode 100644 index 0000000..5ccc14f --- /dev/null +++ b/examples/provider/provider.tf @@ -0,0 +1,18 @@ +terraform { + required_providers { + pomeriumzero = { + source = "rasschaert/pomeriumzero" + } + } +} + +provider "pomeriumzero" { + api_token = var.pomerium_zero_api_token +} + +# Get an API token at https://console.pomerium.app/app/management/api-tokens +variable "pomerium_zero_api_token" { + sensitive = true + description = "Pomerium Zero API token" + type = string +} diff --git a/examples/resources/pomeriumzero_cluster/import.sh b/examples/resources/pomeriumzero_cluster/import.sh new file mode 100644 index 0000000..62c3349 --- /dev/null +++ b/examples/resources/pomeriumzero_cluster/import.sh @@ -0,0 +1,2 @@ +# Cluster can be imported by specifying the name. +terraform import pomeriumzero_cluster.default gifted-nightingale-1337 diff --git a/examples/resources/pomeriumzero_cluster/resource.tf b/examples/resources/pomeriumzero_cluster/resource.tf new file mode 100644 index 0000000..b3212f6 --- /dev/null +++ b/examples/resources/pomeriumzero_cluster/resource.tf @@ -0,0 +1,9 @@ +import { + id = "default" + to = pomeriumzero_cluster.default +} + +resource "pomeriumzero_cluster" "default" { + name = "gifted-nightingale-1337" + domain = "gifted-nightingale-1337" +} diff --git a/examples/resources/pomeriumzero_cluster_settings/import.sh b/examples/resources/pomeriumzero_cluster_settings/import.sh new file mode 100644 index 0000000..c7c017c --- /dev/null +++ b/examples/resources/pomeriumzero_cluster_settings/import.sh @@ -0,0 +1,2 @@ +# Cluster settings can be imported by specifying the cluster id. You can get that using a command like terraform state show pomeriumzero_cluster.default +terraform import pomeriumzero_cluster_settings.default bZPhcRUBcFwVlLCEPsSHMTxEqLR diff --git a/examples/resources/pomeriumzero_cluster_settings/resource.tf b/examples/resources/pomeriumzero_cluster_settings/resource.tf new file mode 100644 index 0000000..2e2a375 --- /dev/null +++ b/examples/resources/pomeriumzero_cluster_settings/resource.tf @@ -0,0 +1,46 @@ +resource "pomeriumzero_cluster_settings" "default" { + address = ":443" + auto_apply_changesets = true + cookie_expire = "14h0m0s" + cookie_http_only = true + cookie_name = "_pomerium" + default_upstream_timeout = "30s" + dns_lookup_family = "V4_PREFERRED" + authenticate_service_url = "https://authenticate.${pomeriumzero_cluster.default.fqdn}" + identity_provider = var.pomerium_zero_identity_provider + identity_provider_client_id = var.pomerium_zero_identity_provider_client_id + identity_provider_client_secret = var.pomerium_zero_identity_provider_client_secret + identity_provider_url = var.pomerium_zero_identity_provider_url + log_level = "info" + pass_identity_headers = false + proxy_log_level = "info" + skip_xff_append = false + timeout_idle = "5m0s" + timeout_read = "30s" + timeout_write = "0s" + tracing_sample_rate = 0.0001 +} + +variable "pomerium_zero_identity_provider" { + sensitive = false + description = "Pomerium Zero Identity Provider" + type = string +} + +variable "pomerium_zero_identity_provider_url" { + sensitive = false + description = "Pomerium Zero Identity Provider URL" + type = string +} + +variable "pomerium_zero_identity_provider_client_id" { + sensitive = false + description = "Pomerium Zero Identity Provider Client ID" + type = string +} + +variable "pomerium_zero_identity_provider_client_secret" { + sensitive = true + description = "Pomerium Zero Identity Provider Client Secret" + type = string +} diff --git a/examples/resources/pomeriumzero_policy/import.sh b/examples/resources/pomeriumzero_policy/import.sh new file mode 100644 index 0000000..309da54 --- /dev/null +++ b/examples/resources/pomeriumzero_policy/import.sh @@ -0,0 +1,2 @@ +# Policies can be imported by specifying the policy ID. You can see the policy ID in the URL when viewing the policy in the Pomerium console. +terraform import pomeriumzero_policy.allow_any_authenticated_user bHeymGDZrHpQeRtyTsQTXJvkHkt diff --git a/examples/resources/pomeriumzero_policy/resource.tf b/examples/resources/pomeriumzero_policy/resource.tf new file mode 100644 index 0000000..7ec5e07 --- /dev/null +++ b/examples/resources/pomeriumzero_policy/resource.tf @@ -0,0 +1,39 @@ +resource "pomeriumzero_policy" "allow_any_authenticated_user" { + name = "Allow Any Authenticated User" + description = "Any authenticated user is allowed." + explanation = "You are not authenticated." + remediation = "" + enforced = false + namespace_id = pomeriumzero_cluster.default.namespace_id + ppl = jsonencode( + [ + { + allow = { + and = [ + { + authenticated_user = 1 + }, + ] + } + }, + ] + ) +} + +resource "pomeriumzero_policy" "allow_foobar_group_members" { + name = "Allow Foobar group members" + description = "Member of the Foobar group are allowed." + explanation = "You are not a member of the Foobar group." + remediation = "Please contact the IT team if you think this is an error." + enforced = false + namespace_id = data.pomeriumzero_cluster.default.namespace_id + ppl = jsonencode({ + allow = { + or = [ + { + "claim/groups" = "foobar" + } + ] + } + }) +} diff --git a/examples/resources/pomeriumzero_route/import.sh b/examples/resources/pomeriumzero_route/import.sh new file mode 100644 index 0000000..18d3a53 --- /dev/null +++ b/examples/resources/pomeriumzero_route/import.sh @@ -0,0 +1,2 @@ +# Routes can be imported by specifying the route ID. You can see the route ID in the URL when viewing the policy in the Pomerium console. +terraform import pomeriumzero_route.verify bRMWzWNvrZruhmMgashHJegGeGL diff --git a/examples/resources/pomeriumzero_route/resource.tf b/examples/resources/pomeriumzero_route/resource.tf new file mode 100644 index 0000000..e50e9a4 --- /dev/null +++ b/examples/resources/pomeriumzero_route/resource.tf @@ -0,0 +1,34 @@ +resource "pomeriumzero_route" "verify" { + name = "Verify" + from = "https://verify.${pomeriumzero_cluster.default.fqdn}" + to = ["https://verify.pomerium.com"] + namespace_id = data.pomeriumzero_cluster.default.namespace_id + + allow_websockets = false + preserve_host_header = false + + policy_ids = [ + pomeriumzero_policy.allow_any_authenticated_user.id + ] + + pass_identity_headers = true +} + + +resource "pomeriumzero_route" "foobar_tooling" { + name = "Foobar Tooling" + # The external URL that the Pomerium Zero cluster should listen on + from = "https://foobar-tool.example.com" + # A system that is only reachable by the Pomerium Zero cluster via a private network + to = ["https://foobar-tool.examplecorp.lan/"] + # Only match requests that begin with /home/ + prefix = "/home/" + # Make sure to also include the prefix when forwarding the requests to the origin + prefix_rewrite = "/home/" + namespace_id = data.pomeriumzero_cluster.default.namespace_id + allow_websockets = false + preserve_host_header = false + policy_ids = [ + pomeriumzero_policy.allow_foobar_group_members.id + ] +}