Indicate that max_token_ttl is required for OIDC auth methods (#360)

Co-authored-by: Rémi Lapeyre <[email protected]>
hashicorp · Oct 8, 2023 · e13f206 · e13f206
1 parent 7ce8556
commit e13f206
Show file tree

Hide file tree

Showing 12 changed files with 160 additions and 191 deletions.
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -39,10 +39,14 @@ jobs:
         go-version: 1.20.x
     - name: Checkout code
       uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v3.5.0
-    - name: Run OSS acceptance tests
+    - name: Install tfplugindocs
       run: |
         curl -LO https://github.com/hashicorp/terraform-plugin-docs/releases/download/v0.16.0/tfplugindocs_0.16.0_linux_amd64.zip
         sudo unzip tfplugindocs_0.16.0_linux_amd64.zip tfplugindocs -d /usr/local/bin
-        tfplugindocs generate --ignore-deprecated true
-    - name: Fail if repo has changes
-      uses: UnicornGlobal/has-changes-action@ea00e6f831a9e785271645729fa251907b314707 # v1.0.12
+        rm -f tfplugindocs_0.16.0_linux_amd64.zip
+    - name: Generate the documentation
+      run: tfplugindocs generate --ignore-deprecated true
+    - name: Fail if repository has changes
+      run: |
+        git status --short
+        [[ -z $(git status --porcelain) ]] || (echo "The docs/ folder is not up-to-date, please use 'tfplugindocs generate --ignore-deprecated true' to update it" && false)
diff --git a/consul/resource_consul_acl_auth_method.go b/consul/resource_consul_acl_auth_method.go
@@ -19,6 +19,8 @@ func resourceConsulACLAuthMethod() *schema.Resource {
 		Update: resourceConsulACLAuthMethodUpdate,
 		Delete: resourceConsulACLAuthMethodDelete,
 
+		Description: "Starting with Consul 1.5.0, the `consul_acl_auth_method` resource can be used to managed [Consul ACL auth methods](https://www.consul.io/docs/acl/auth-methods).",
+
 		Schema: map[string]*schema.Schema{
 			"name": {
 				Type:        schema.TypeString,
@@ -44,7 +46,7 @@ func resourceConsulACLAuthMethod() *schema.Resource {
 				Type:        schema.TypeString,
 				Optional:    true,
 				Default:     "0s",
-				Description: "The maximum life of any token created by this auth method.",
+				Description: "The maximum life of any token created by this auth method. **This attribute is required and must be set to a nonzero for the OIDC auth method.**",
 				DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool {
 					o, err := time.ParseDuration(old)
 					if err != nil {
@@ -74,7 +76,7 @@ func resourceConsulACLAuthMethod() *schema.Resource {
 				Type:        schema.TypeMap,
 				Optional:    true,
 				Description: "The raw configuration for this ACL auth method.",
-				Deprecated:  "The config attribute is deprecated, please use config_json instead.",
+				Deprecated:  "The config attribute is deprecated, please use `config_json` instead.",
 				Elem: &schema.Schema{
 					Type: schema.TypeString,
 				},
@@ -95,26 +97,30 @@ func resourceConsulACLAuthMethod() *schema.Resource {
 			},
 
 			"namespace_rule": {
-				Type:     schema.TypeList,
-				Optional: true,
+				Type:        schema.TypeList,
+				Description: "A set of rules that control which namespace tokens created via this auth method will be created within.",
+				Optional:    true,
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"selector": {
-							Type:     schema.TypeString,
-							Optional: true,
+							Type:        schema.TypeString,
+							Description: "Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation.",
+							Optional:    true,
 						},
 						"bind_namespace": {
-							Type:     schema.TypeString,
-							Required: true,
+							Type:        schema.TypeString,
+							Description: "If the namespace rule's `selector` matches then this is used to control the namespace where the token is created.",
+							Required:    true,
 						},
 					},
 				},
 			},
 
 			"namespace": {
-				Type:     schema.TypeString,
-				Optional: true,
-				ForceNew: true,
+				Type:        schema.TypeString,
+				Description: "The namespace in which to create the auth method.",
+				Optional:    true,
+				ForceNew:    true,
 			},
 
 			"partition": {

diff --git a/docs/data-sources/config_entry.md b/docs/data-sources/config_entry.md
@@ -29,5 +29,3 @@ description: |-
 
 - `config_json` (String) The configuration of the config entry.
 - `id` (String) The ID of this resource.
-
-
diff --git a/docs/data-sources/peering.md b/docs/data-sources/peering.md
@@ -39,5 +39,3 @@ data "consul_peering" "basic" {
 - `peer_server_addresses` (List of String)
 - `peer_server_name` (String)
 - `state` (String)
-
-
diff --git a/docs/data-sources/peerings.md b/docs/data-sources/peerings.md
@@ -43,5 +43,3 @@ Read-Only:
 - `peer_server_addresses` (List of String)
 - `peer_server_name` (String)
 - `state` (String)
-
-
diff --git a/docs/resources/acl_auth_method.md b/docs/resources/acl_auth_method.md
@@ -1,21 +1,19 @@
 ---
-layout: "consul"
-page_title: "Consul: consul_acl_auth_method"
-sidebar_current: "docs-consul-resource-acl-auth-method"
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "consul_acl_auth_method Resource - terraform-provider-consul"
 description: |-
-  Allows Terraform to create an ACL auth method
+  Starting with Consul 1.5.0, the consul_acl_auth_method resource can be used to managed Consul ACL auth methods https://www.consul.io/docs/acl/auth-methods.
 ---
 
-# consul_acl_auth_method
-
-Starting with Consul 1.5.0, the consul_acl_auth_method resource can be used to
-managed [Consul ACL auth methods](https://www.consul.io/docs/acl/auth-methods).
+# consul_acl_auth_method (Resource)
 
+Starting with Consul 1.5.0, the `consul_acl_auth_method` resource can be used to managed [Consul ACL auth methods](https://www.consul.io/docs/acl/auth-methods).
 
 ## Example Usage
 
 Define a `kubernetes` auth method:
-```hcl
+
+```terraform
 resource "consul_acl_auth_method" "minikube" {
   name        = "minikube"
   type        = "kubernetes"
@@ -29,70 +27,71 @@ resource "consul_acl_auth_method" "minikube" {
 }
 ```
 
+
 Define a `jwt` auth method:
-```hcl
-resource "consul_acl_auth_method" "minikube" {
-  name        = "auth_method"
-  type        = "jwt"
+
+```terraform
+resource "consul_acl_auth_method" "oidc" {
+  name          = "auth0"
+  type          = "oidc"
+  max_token_ttl = "5m"
 
   config_json = jsonencode({
-    JWKSURL          = "https://example.com/identity/oidc/.well-known/keys"
-    JWTSupportedAlgs = "RS256"
-    BoundIssuer      = "https://example.com"
-    ClaimMappings    = {
-      subject = "subject"
+    AllowedRedirectURIs = [
+      "http://localhost:8550/oidc/callback",
+      "http://localhost:8500/ui/oidc/callback"
+    ]
+    BoundAudiences = [
+      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
+    ]
+    ClaimMappings = {
+      "http://example.com/first_name" = "first_name"
+      "http://example.com/last_name"  = "last_name"
     }
+    ListClaimMappings = {
+      "http://consul.com/groups" = "groups"
+    }
+    OIDCClientID     = "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
+    OIDCClientSecret = "...(omitted)..."
+    OIDCDiscoveryURL = "https://my-corp-app-name.auth0.com/"
   })
 }
 ```
 
-## Argument Reference
-
-The following arguments are supported:
-
-* `name` - (Required) The name of the ACL auth method.
-* `type` - (Required) The type of the ACL auth method.
-* `display_name` - (Optional) An optional name to use instead of the name
-  attribute when displaying information about this auth method.
-* `max_token_ttl` - (Optional) The maximum life of any token created by this
-  auth method.
-* `token_locality` - (Optional) The kind of token that this auth method
-  produces. This can be either 'local' or 'global'.
-* `description` - (Optional) A free form human readable description of the auth method.
-* `config_json` - (Required) The raw configuration for this ACL auth method.
-* `config` - (Optional) The raw configuration for this ACL auth method. This
-  attribute is deprecated and will be removed in a future version. `config_json`
-  should be used instead.
-* `namespace` - (Optional, Enterprise Only) The namespace in which to create the auth method.
-* `partition` - (Optional, Enterprise Only) The partition the ACL auth method is associated with.
-* `namespace_rule` - (Optional, Enterprise Only) A set of rules that control
-  which namespace tokens created via this auth method will be created within.
-
-Each `namespace_rule` can have the following attributes:
-* `selector` - (Optional) Specifies the expression used to match this namespace
-  rule against valid identities returned from an auth method validation.
-  Defaults to `""`.
-* `bind_namespace` - (Required) If the namespace rule's `selector` matches then
-  this is used to control the namespace where the token is created.
-
-## Attributes Reference
-
-The following attributes are exported:
-
-* `id` - The ID of the the auth method.
-* `name` - The name of the ACL auth method.
-* `type` - The type of the ACL auth method.
-* `display_name` - An optional name to use instead of the name attribute when
-  displaying information about this auth method.
-* `max_token_ttl` - The maximum life of any token created by this auth method.
-* `token_locality` - The kind of token that this auth method produces. This can
-  be either 'local' or 'global'.
-* `description` - A free form human readable description of the auth method.
-* `config_json` - The raw configuration for this ACL auth method.
-* `config` - The raw configuration for this ACL auth method. This attribute is
-  deprecated and will be removed in a future version. If the configuration is
-  too complex to be represented as a map of strings it will be blank.
-  `config_json` should be used instead.
-* `namespace` - (Enterprise Only) The namespace in which to create the auth method.
-* `namespace_rule` - (Enterprise Only) A set of rules that control which
-  namespace tokens created via this auth method will be created within.
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of the ACL auth method.
+- `type` (String) The type of the ACL auth method.
+
+### Optional
+
+- `config` (Map of String, Deprecated) The raw configuration for this ACL auth method.
+- `config_json` (String) The raw configuration for this ACL auth method.
+- `description` (String) A free form human readable description of the auth method.
+- `display_name` (String) An optional name to use instead of the name attribute when displaying information about this auth method.
+- `max_token_ttl` (String) The maximum life of any token created by this auth method. **This attribute is required and must be set to a nonzero for the OIDC auth method.**
+- `namespace` (String) The namespace in which to create the auth method.
+- `namespace_rule` (Block List) A set of rules that control which namespace tokens created via this auth method will be created within. (see [below for nested schema](#nestedblock--namespace_rule))
+- `partition` (String) The partition the ACL auth method is associated with.
+- `token_locality` (String) The kind of token that this auth method produces. This can be either 'local' or 'global'.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+
+<a id="nestedblock--namespace_rule"></a>
+### Nested Schema for `namespace_rule`
+
+Required:
+
+- `bind_namespace` (String) If the namespace rule's `selector` matches then this is used to control the namespace where the token is created.
+
+Optional:
+
+- `selector` (String) Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation.
+
+
diff --git a/docs/resources/peering.md b/docs/resources/peering.md
@@ -73,5 +73,3 @@ resource "consul_peering" "eu-us" {
 - `peer_server_addresses` (List of String)
 - `peer_server_name` (String)
 - `state` (String)
-
-
diff --git a/docs/resources/peering_token.md b/docs/resources/peering_token.md
@@ -43,5 +43,3 @@ resource "consul_peering_token" "token" {
 
 - `id` (String) The ID of this resource.
 - `peering_token` (String, Sensitive) The generated peering token
-
-
diff --git a/examples/resources/consul_acl_auth_method/jwt.tf b/examples/resources/consul_acl_auth_method/jwt.tf
@@ -0,0 +1,25 @@
+resource "consul_acl_auth_method" "oidc" {
+  name          = "auth0"
+  type          = "oidc"
+  max_token_ttl = "5m"
+
+  config_json = jsonencode({
+    AllowedRedirectURIs = [
+      "http://localhost:8550/oidc/callback",
+      "http://localhost:8500/ui/oidc/callback"
+    ]
+    BoundAudiences = [
+      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
+    ]
+    ClaimMappings = {
+      "http://example.com/first_name" = "first_name"
+      "http://example.com/last_name"  = "last_name"
+    }
+    ListClaimMappings = {
+      "http://consul.com/groups" = "groups"
+    }
+    OIDCClientID     = "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
+    OIDCClientSecret = "...(omitted)..."
+    OIDCDiscoveryURL = "https://my-corp-app-name.auth0.com/"
+  })
+}
diff --git a/examples/resources/consul_acl_auth_method/kubernetes.tf b/examples/resources/consul_acl_auth_method/kubernetes.tf
@@ -0,0 +1,11 @@
+resource "consul_acl_auth_method" "minikube" {
+  name        = "minikube"
+  type        = "kubernetes"
+  description = "dev minikube cluster"
+
+  config_json = jsonencode({
+    Host              = "https://192.0.2.42:8443"
+    CACert            = "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n"
+    ServiceAccountJWT = "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
+  })
+}