update docs (#37)

wasaga · web-flow · commit fec4af7a1b1c · 2025-02-11T18:33:34.000-05:00
updates provider reference documentation. Ref: https://linear.app/pomerium/issue/ENG-1755/docsterraform-add-provider-documentation
diff --git a/README.md b/README.md
@@ -1 +1,67 @@
-# enterprise-terraform-provider
+# Pomerium Terraform Provider
+
+[![Terraform](https://img.shields.io/badge/Terraform-v1.0+-blue.svg)](https://www.terraform.io)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+The Pomerium Terraform Provider enables management of Pomerium Enterprise resources through Terraform.
+
+## Quick Start
+
+Configure the provider in your Terraform configuration:
+
+```terraform
+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:
+  
+  # Option 1: Service Account Token
+  service_account_token = var.pomerium_service_account_token
+  
+  # Option 2: Bootstrap Service Account
+  # shared_secret_b64 = var.shared_secret_b64
+}
+```
+
+## Authentication
+
+Two authentication methods are supported:
+
+1. **Service Account Token** (Recommended)
+   - Uses a [Pomerium Enterprise Service Account](https://www.pomerium.com/docs/capabilities/service-accounts)
+   - Provides namespace-level access control
+   - Configure using `service_account_token`
+
+2. **Bootstrap Service Account**
+   - Requires `BOOTSTRAP_SERVICE_ACCOUNT=true` in Enterprise Console
+   - Configure using `shared_secret_b64`
+
+## Documentation
+
+- [Provider Documentation](https://registry.terraform.io/providers/pomerium/pomerium/latest/docs)
+- [Example Configurations](https://github.com/pomerium/enterprise-terraform-provider/tree/main/examples)
+- [Kubernetes Deployment Guide](https://github.com/pomerium/install/tree/main/enterprise/terraform/kubernetes)
+
+## Resources and Data Sources
+
+Common resources:
+- `pomerium_namespace`
+- `pomerium_policy`
+- `pomerium_route`
+- `pomerium_settings`
+- `pomerium_service_account`
+
+Data sources:
+- `pomerium_namespaces`
+- `pomerium_namespace`
+- `pomerium_route`
+
+For detailed examples, see our [examples directory](examples/) or the [provider documentation](https://registry.terraform.io/providers/pomerium/pomerium/latest/docs).
diff --git a/internal/provider/help/provider.md b/internal/provider/help/provider.md
@@ -0,0 +1,64 @@
+# Pomerium Provider
+
+The Pomerium provider enables management of Pomerium Enterprise resources through Terraform. It provides resources and data sources for managing policies, routes, namespaces, and other Pomerium Enterprise features.
+
+## Example Usage
+
+```terraform
+terraform {
+  required_providers {
+    pomerium = {
+      source  = "pomerium/pomerium"
+      version = "~> 0.0.7"
+    }
+  }
+}
+
+provider "pomerium" {
+  api_url      = "https://console-api.your-domain.com"
+  # Choose one authentication method:
+  service_account_token = var.pomerium_service_account_token
+  # shared_secret_b64   = var.shared_secret_b64
+}
+```
+
+## Authentication Methods
+
+The provider supports two authentication methods:
+
+### Service Account Token (Recommended)
+
+Uses a Pomerium Enterprise Service Account token for authentication. This method provides fine-grained access control at the namespace level.
+
+```terraform
+provider "pomerium" {
+  api_url               = "https://console-api.your-domain.com"
+  service_account_token = var.pomerium_service_account_token
+}
+```
+
+### Bootstrap Service Account
+
+Uses the Enterprise Console's shared secret for authentication. Requires `BOOTSTRAP_SERVICE_ACCOUNT=true` in the Enterprise Console configuration.
+
+```terraform
+provider "pomerium" {
+  api_url          = "https://console-api.your-domain.com"
+  shared_secret_b64 = var.shared_secret_b64
+}
+```
+
+## Schema
+
+### Required
+
+- `api_url` (String) - The URL of your Pomerium Enterprise Console API endpoint.
+
+### Optional
+
+- `service_account_token` (String, Sensitive) - A Pomerium Enterprise Service Account token. Mutually exclusive with `shared_secret_b64`.
+- `shared_secret_b64` (String, Sensitive) - The base64-encoded shared secret from your Pomerium Enterprise Console. Mutually exclusive with `service_account_token`.
+- `tls_insecure_skip_verify` (Boolean) - Skip TLS certificate verification. Should only be used in testing environments.
+
+~> **Note:** You must specify either `service_account_token` or `shared_secret_b64`, but not both.
+
diff --git a/internal/provider/provider.go b/internal/provider/provider.go
@@ -3,6 +3,7 @@ package provider
 import (
 	"context"
 	"crypto/tls"
+	_ "embed" // embed is used to embed the provider description
 	"net"
 	"net/url"
 
@@ -21,6 +22,9 @@ import (
 var (
 	_ provider.Provider              = &PomeriumProvider{}
 	_ provider.ProviderWithFunctions = &PomeriumProvider{}
+
+	//go:embed help/provider.md
+	providerDescription string
 )
 
 // PomeriumProvider defines the provider implementation.
@@ -46,6 +50,7 @@ func (p *PomeriumProvider) Metadata(_ context.Context, _ provider.MetadataReques
 
 func (p *PomeriumProvider) Schema(_ context.Context, _ provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: providerDescription,
 		Attributes: map[string]schema.Attribute{
 			"api_url": schema.StringAttribute{
 				MarkdownDescription: "Pomerium Enterprise API URL",
diff --git a/internal/provider/route.go b/internal/provider/route.go
@@ -57,12 +57,12 @@ func (r *RouteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 				Required:    true,
 			},
 			"from": schema.StringAttribute{
-				Description: "From URL.",
+				Description: "The external URL for a proxied request. Must contain a scheme and Hostname, must not contain a path.",
 				Required:    true,
 			},
 			"to": schema.SetAttribute{
 				ElementType: types.StringType,
-				Description: "To URLs.",
+				Description: "The destination(s) of a proxied request. Must contain a scheme and Hostname, with an optional weight.",
 				Required:    true,
 			},
 			"namespace_id": schema.StringAttribute{
@@ -80,75 +80,75 @@ func (r *RouteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 				Computed:    true,
 			},
 			"prefix": schema.StringAttribute{
-				Description: "Prefix.",
+				Description: "Matches incoming requests with a path that begins with the specified prefix.",
 				Optional:    true,
 			},
 			"path": schema.StringAttribute{
-				Description: "Path.",
+				Description: "Matches incoming requests with a path that is an exact match for the specified path.",
 				Optional:    true,
 			},
 			"regex": schema.StringAttribute{
-				Description: "Regex.",
+				Description: "Matches incoming requests with a path that matches the specified regular expression.",
 				Optional:    true,
 			},
 			"prefix_rewrite": schema.StringAttribute{
-				Description: "Prefix rewrite.",
+				Description: "While forwarding a request, Prefix Rewrite swaps the matched prefix (or path) with the specified value.",
 				Optional:    true,
 			},
 			"regex_rewrite_pattern": schema.StringAttribute{
-				Description: "Regex rewrite pattern.",
+				Description: "Rewrites the URL path according to the regex rewrite pattern.",
 				Optional:    true,
 			},
 			"regex_rewrite_substitution": schema.StringAttribute{
-				Description: "Regex rewrite substitution.",
+				Description: "Rewrites the URL path according to the regex rewrite substitution.",
 				Optional:    true,
 			},
 			"host_rewrite": schema.StringAttribute{
-				Description: "Host rewrite.",
+				Description: "Rewrites the Host header to a new literal value.",
 				Optional:    true,
 			},
 			"host_rewrite_header": schema.StringAttribute{
-				Description: "Host rewrite header.",
+				Description: "Rewrites the Host header to match an incoming header value.",
 				Optional:    true,
 			},
 			"host_path_regex_rewrite_pattern": schema.StringAttribute{
-				Description: "Host path regex rewrite pattern.",
+				Description: "Rewrites the Host header according to a regular expression matching the path.",
 				Optional:    true,
 			},
 			"host_path_regex_rewrite_substitution": schema.StringAttribute{
-				Description: "Host path regex rewrite substitution.",
+				Description: "Rewrites the Host header according to a regular expression matching the substitution.",
 				Optional:    true,
 			},
 			"regex_priority_order": schema.Int64Attribute{
 				Description: "Regex priority order.",
 				Optional:    true,
 			},
 			"timeout": schema.StringAttribute{
-				Description: "Timeout.",
+				Description: "Sets the per-route timeout value. Cannot exceed global timeout values. Defaults to 30 seconds.",
 				Optional:    true,
 				CustomType:  timetypes.GoDurationType{},
 				Computed:    true,
 			},
 			"idle_timeout": schema.StringAttribute{
-				Description: "Idle timeout.",
+				Description: "Sets the time to terminate the upstream connection if there are no active streams. Defaults to 5 minutes.",
 				Optional:    true,
 				CustomType:  timetypes.GoDurationType{},
 				Computed:    true,
 			},
 			"allow_websockets": schema.BoolAttribute{
-				Description: "Allow websockets.",
+				Description: "If applied, this setting enables Pomerium to proxy websocket connections.",
 				Optional:    true,
 			},
 			"allow_spdy": schema.BoolAttribute{
-				Description: "Allow SPDY.",
+				Description: "If applied, this setting enables Pomerium to proxy SPDY protocol upgrades.",
 				Optional:    true,
 			},
 			"tls_skip_verify": schema.BoolAttribute{
-				Description: "TLS skip verify.",
+				Description: "If applied, Pomerium accepts any certificate presented by the upstream server and any Hostname in that certificate. Use for testing only.",
 				Optional:    true,
 			},
 			"tls_upstream_server_name": schema.StringAttribute{
-				Description: "TLS upstream server name.",
+				Description: "This server name overrides the Hostname in the 'To:' field, and will be used to verify the certificate name.",
 				Optional:    true,
 			},
 			"tls_downstream_server_name": schema.StringAttribute{
@@ -161,25 +161,25 @@ func (r *RouteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 			},
 			"set_request_headers": schema.MapAttribute{
 				ElementType: types.StringType,
-				Description: "Set request headers.",
+				Description: "Sets static and dynamic values for given request headers. Available substitutions: ${pomerium.id_token}, ${pomerium.access_token}, ${pomerium.client_cert_fingerprint}.",
 				Optional:    true,
 			},
 			"remove_request_headers": schema.SetAttribute{
 				ElementType: types.StringType,
-				Description: "Remove request headers.",
+				Description: "Removes given request headers so they do not reach the upstream server.",
 				Optional:    true,
 			},
 			"set_response_headers": schema.MapAttribute{
 				ElementType: types.StringType,
-				Description: "Set response headers.",
+				Description: "Sets static HTTP Response Header values for a route. These headers take precedence over globally set response headers.",
 				Optional:    true,
 			},
 			"preserve_host_header": schema.BoolAttribute{
-				Description: "Preserve host header.",
+				Description: "Passes the host header from the incoming request to the proxied host, instead of the destination hostname.",
 				Optional:    true,
 			},
 			"pass_identity_headers": schema.BoolAttribute{
-				Description: "Pass identity headers.",
+				Description: "If applied, passes X-Pomerium-Jwt-Assertion header and JWT Claims Headers to the upstream application.",
 				Optional:    true,
 			},
 			"kubernetes_service_account_token": schema.StringAttribute{
@@ -195,7 +195,7 @@ func (r *RouteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 				Optional:    true,
 			},
 			"show_error_details": schema.BoolAttribute{
-				Description: "Show error details.",
+				Description: "If applied, shows error details, including policy explanation and remediation for 403 Forbidden responses.",
 				Optional:    true,
 				Computed:    true,
 			},
@@ -208,7 +208,7 @@ func (r *RouteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 				},
 			},
 			"rewrite_response_headers": schema.SetNestedAttribute{
-				Description: "Response header rewrite rules.",
+				Description: "Modifies response headers before they are returned to the client. 'Header' matches the HTTP header name; 'prefix' will be replaced with 'value'.",
 				Optional:    true,
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
diff --git a/internal/provider/settings_schema.go b/internal/provider/settings_schema.go
