docs and examples

rasschaert · Oct 14, 2024 · d93a563 · d93a563
1 parent d808cca
commit d93a563
Show file tree

Hide file tree

Showing 16 changed files with 362 additions and 132 deletions.
diff --git 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 generated by tfplugindocs -->
 ## Schema

diff --git 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 generated by tfplugindocs -->
+## 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
@@ -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 generated by tfplugindocs -->
 ## 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
@@ -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 generated by tfplugindocs -->
 ## 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
@@ -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 generated by tfplugindocs -->
 ## 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
+```