docs: generate provider documentation

Related: 
- argoproj-labs#126
- hashicorp/terraform-plugin-docs#66 (Nested Schema for `info` for `argocd_cluster`)

GNUmakefile

@@ -62,6 +62,9 @@ lint:
 	@echo "==> Checking source code against linters..."
 	@GOGC=30 golangci-lint run ./$(PKG_NAME)
 
+generate:
+	go generate ./...
+
 test-compile:
 	@if [ "$(TEST)" = "./..." ]; then \
 		echo "ERROR: Set TEST to a specific package. For example,"; \

README.md

@@ -2,6 +2,17 @@
 
 [![Tests](https://github.com/oboukili/terraform-provider-argocd/actions/workflows/tests.yml/badge.svg)](https://github.com/oboukili/terraform-provider-argocd/actions/workflows/tests.yml)
 
+The [ArgoCD
+Provider](https://registry.terraform.io/providers/oboukili/argocd/latest/docs)
+provides lifecycle management of
+[ArgoCD](https://argo-cd.readthedocs.io/en/stable/) resources.
+
+**NB**: The provider is not concerned with the installation/configuration of
+ArgoCD itself. To make use of the provider, you will need to have an existing
+ArgoCD deployment and, the ArgoCD API server must be
+[accessible](https://argo-cd.readthedocs.io/en/stable/getting_started/#3-access-the-argo-cd-api-server)
+from where you are running Terraform.
+
 ---
 
 ## Compatibility promise
@@ -369,6 +380,16 @@ docker pull redis:6.2.4-alpine
 docker pull alpine:3
 ```
 
+### Generating documentation
+
+This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/)
+to generate documentation and store it in the `docs/` directory.
+Once a release is cut, the Terraform Registry will download the documentation from `docs/`
+and associate it with the release version. Read more about how this works on the
+[official page](https://www.terraform.io/registry/providers/docs).
+
+Use `make generate` to ensure the documentation is regenerated with any changes.
+
 #### Troubleshooting during local development
 
 * **"too many open files":** Running all acceptance tests in parallel (the default) may open a lot of files and sockets, therefore ensure your local workstation [open files/sockets limits are tuned accordingly](https://k6.io/docs/misc/fine-tuning-os).
@@ -380,4 +401,4 @@ docker pull alpine:3
 * Thanks to [JetBrains](https://www.jetbrains.com/?from=terraform-provider-argocd) for providing a GoLand open source license to support the development of this provider.
 * Thanks to [Keplr](https://www.welcometothejungle.com/fr/companies/keplr) for allowing me to contribute to this side-project of mine during paid work hours.
 
-![](sponsors/jetbrains.svg?display=inline-block) ![](sponsors/keplr.png?display=inline-block)
+![](sponsors/jetbrains.svg?display=inline-block) ![](sponsors/keplr.png?display=inline-block)

argocd/provider.go

@@ -40,11 +40,13 @@ func Provider() *schema.Provider {
 				Type:        schema.TypeString,
 				Required:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_SERVER", nil),
+				Description: "ArgoCD server address with port. Can be set through the `ARGOCD_SERVER` environment variable.",
 			},
 			"auth_token": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_AUTH_TOKEN", nil),
+				Description: "ArgoCD authentication token, takes precedence over `username`/`password`. Can be set through the `ARGOCD_AUTH_TOKEN` environment variable.",
 				ConflictsWith: []string{
 					"username",
 					"password",
@@ -56,6 +58,7 @@ func Provider() *schema.Provider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_AUTH_USERNAME", nil),
+				Description: "Authentication username. Can be set through the `ARGOCD_AUTH_USERNAME` environment variable.",
 				ConflictsWith: []string{
 					"auth_token",
 					"use_local_config",
@@ -71,6 +74,7 @@ func Provider() *schema.Provider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_AUTH_PASSWORD", nil),
+				Description: "Authentication password. Can be set through the `ARGOCD_AUTH_PASSWORD` environment variable.",
 				ConflictsWith: []string{
 					"auth_token",
 					"use_local_config",
@@ -83,38 +87,50 @@ func Provider() *schema.Provider {
 				},
 			},
 			"cert_file": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "Additional root CA certificates file to add to the client TLS connection pool.",
 			},
 			"client_cert_file": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "Client certificate.",
 			},
 			"client_cert_key": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "Client certificate key.",
 			},
 			"plain_text": {
-				Type:     schema.TypeBool,
-				Optional: true,
-				Default:  false,
+				Type:        schema.TypeBool,
+				Optional:    true,
+				Default:     false,
+				Description: "Whether to initiate an unencrypted connection to ArgoCD server.",
 			},
 			"context": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_CONTEXT", nil),
+				Description: "Kubernetes context to load from an existing `.kube/config` file. Can be set through `ARGOCD_CONTEXT` environment variable.",
 			},
 			"user_agent": {
 				Type:     schema.TypeString,
 				Optional: true,
 			},
 			"grpc_web": {
-				Type:     schema.TypeBool,
-				Optional: true,
+				Type:        schema.TypeBool,
+				Optional:    true,
+				Description: "Whether to use gRPC web proxy client. Useful if Argo CD server is behind proxy which does not support HTTP2.",
+			},
+			"grpc_web_root_path": {
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "Use the gRPC web proxy client and set the web root, e.g. `argo-cd`. Useful if the Argo CD server is behind a proxy at a non-root path.",
 			},
 			"use_local_config": {
-				Type:     schema.TypeBool,
-				Optional: true,
+				Type:        schema.TypeBool,
+				Optional:    true,
+				Description: "Use the authentication settings found in the local config file. Useful when you have previously logged in using SSO. Conflicts with `auth_token`, `username` and `password`.",
 				ConflictsWith: []string{
 					"username",
 					"password",
@@ -125,16 +141,13 @@ func Provider() *schema.Provider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_CONFIG_PATH", nil),
+				Description: "Override the default config path of `$HOME/.config/argocd/config`. Only relevant when `use_local_config`. Can be set through the `ARGOCD_CONFIG_PATH` environment variable.",
 				ConflictsWith: []string{
 					"username",
 					"password",
 					"auth_token",
 				},
 			},
-			"grpc_web_root_path": {
-				Type:     schema.TypeString,
-				Optional: true,
-			},
 			"port_forward": {
 				Type:     schema.TypeBool,
 				Optional: true,
@@ -144,14 +157,16 @@ func Provider() *schema.Provider {
 				Optional: true,
 			},
 			"headers": {
-				Type:     schema.TypeSet,
-				Optional: true,
-				Elem:     &schema.Schema{Type: schema.TypeString},
+				Type:        schema.TypeSet,
+				Optional:    true,
+				Description: "Additional headers to add to each request to the ArgoCD server.",
+				Elem:        &schema.Schema{Type: schema.TypeString},
 			},
 			"insecure": {
 				Type:        schema.TypeBool,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARGOCD_INSECURE", false),
+				Description: "Whether to skip TLS server certificate. Can be set through the `ARGOCD_INSECURE` environment variable.",
 			},
 			"kubernetes": {
 				Type:        schema.TypeList,
@@ -341,61 +356,62 @@ func kubernetesResource() *schema.Resource {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_HOST", ""),
-				Description: "The hostname (in form of URI) of Kubernetes master.",
+				Description: "The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`.",
 			},
 			"username": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_USER", ""),
-				Description: "The username to use for HTTP basic authentication when accessing the Kubernetes master endpoint.",
+				Description: "The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`.",
 			},
 			"password": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_PASSWORD", ""),
-				Description: "The password to use for HTTP basic authentication when accessing the Kubernetes master endpoint.",
+				Description: "The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`.",
 			},
 			"insecure": {
 				Type:        schema.TypeBool,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_INSECURE", false),
-				Description: "Whether server should be accessed without verifying the TLS certificate.",
+				Description: "Whether server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`.",
 			},
 			"client_certificate": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_CLIENT_CERT_DATA", ""),
-				Description: "PEM-encoded client certificate for TLS authentication.",
+				Description: "PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`.",
 			},
 			"client_key": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_CLIENT_KEY_DATA", ""),
-				Description: "PEM-encoded client certificate key for TLS authentication.",
+				Description: "PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`.",
 			},
 			"cluster_ca_certificate": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_CLUSTER_CA_CERT_DATA", ""),
-				Description: "PEM-encoded root certificates bundle for TLS authentication.",
+				Description: "PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`.",
 			},
 			"config_paths": {
 				Type:        schema.TypeList,
 				Elem:        &schema.Schema{Type: schema.TypeString},
 				Optional:    true,
-				Description: "A list of paths to kube config files. Can be set with KUBE_CONFIG_PATHS environment variable.",
+				Description: "A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`.",
 			},
 			"config_path": {
 				Type:          schema.TypeString,
 				Optional:      true,
 				DefaultFunc:   schema.EnvDefaultFunc("KUBE_CONFIG_PATH", nil),
-				Description:   "Path to the kube config file. Can be set with KUBE_CONFIG_PATH.",
+				Description:   "Path to the kube config file. Can be sourced from `KUBE_CONFIG_PATH`.",
 				ConflictsWith: []string{"kubernetes.0.config_paths"},
 			},
 			"config_context": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_CTX", ""),
+				Description: "Context to choose from the config file. Can be sourced from `KUBE_CTX`.",
 			},
 			"config_context_auth_info": {
 				Type:        schema.TypeString,
@@ -413,35 +429,39 @@ func kubernetesResource() *schema.Resource {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("KUBE_TOKEN", ""),
-				Description: "Token to authenticate an service account",
+				Description: "Token to authenticate an service account. Can be sourced from `KUBE_TOKEN`.",
 			},
 			"exec": {
-				Type:     schema.TypeList,
-				Optional: true,
-				MaxItems: 1,
+				Type:        schema.TypeList,
+				Optional:    true,
+				MaxItems:    1,
+				Description: "Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"api_version": {
-							Type:     schema.TypeString,
-							Required: true,
+							Type:        schema.TypeString,
+							Required:    true,
+							Description: "API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`.",
 						},
 						"command": {
-							Type:     schema.TypeString,
-							Required: true,
+							Type:        schema.TypeString,
+							Required:    true,
+							Description: "Command to execute.",
 						},
 						"env": {
-							Type:     schema.TypeMap,
-							Optional: true,
-							Elem:     &schema.Schema{Type: schema.TypeString},
+							Type:        schema.TypeMap,
+							Optional:    true,
+							Description: "List of arguments to pass when executing the plugin.",
+							Elem:        &schema.Schema{Type: schema.TypeString},
 						},
 						"args": {
-							Type:     schema.TypeList,
-							Optional: true,
-							Elem:     &schema.Schema{Type: schema.TypeString},
+							Type:        schema.TypeList,
+							Optional:    true,
+							Description: "Map of environment variables to set when executing the plugin.",
+							Elem:        &schema.Schema{Type: schema.TypeString},
 						},
 					},
 				},
-				Description: "",
 			},
 		},
 	}

argocd/resource_argocd_application.go

@@ -18,6 +18,7 @@ import (
 
 func resourceArgoCDApplication() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Manages [applications](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#applications) within ArgoCD.",
 		CreateContext: resourceArgoCDApplicationCreate,
 		ReadContext:   resourceArgoCDApplicationRead,
 		UpdateContext: resourceArgoCDApplicationUpdate,
@@ -30,7 +31,7 @@ func resourceArgoCDApplication() *schema.Resource {
 			"spec":     applicationSpecSchemaV4(),
 			"wait": {
 				Type:        schema.TypeBool,
-				Description: "Upon application creation or update, wait for application health/sync status to be healthy/Synced, upon application deletion, wait for application to be removed, when set to true.",
+				Description: "Upon application creation or update, wait for application health/sync status to be healthy/Synced, upon application deletion, wait for application to be removed, when set to true. Wait timeouts are controlled by Terraform Create, Update and Delete resource timeouts (all default to 5 minutes).",
 				Optional:    true,
 				Default:     false,
 			},

argocd/resource_argocd_cluster.go

@@ -12,6 +12,7 @@ import (
 
 func resourceArgoCDCluster() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Manages [clusters](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#clusters) within ArgoCD.",
 		CreateContext: resourceArgoCDClusterCreate,
 		ReadContext:   resourceArgoCDClusterRead,
 		UpdateContext: resourceArgoCDClusterUpdate,

argocd/resource_argocd_project.go

@@ -15,6 +15,7 @@ import (
 
 func resourceArgoCDProject() *schema.Resource {
 	return &schema.Resource{
+		Description:   "Manages [projects](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/) within ArgoCD.",
 		CreateContext: resourceArgoCDProjectCreate,
 		ReadContext:   resourceArgoCDProjectRead,
 		UpdateContext: resourceArgoCDProjectUpdate,