From 5691ff4c00666b5f183f79b82baf65f9b7e5bca1 Mon Sep 17 00:00:00 2001 From: Ryan Nixon Date: Sun, 16 Jul 2023 00:59:55 -0700 Subject: [PATCH] Introducing docs generation (#146) --- .github/PULL_REQUEST_TEMPLATE.md | 4 +- .github/dependabot.yml | 8 + .github/workflows/test.yml | 42 +++-- README.md | 6 + docs/index.md | 68 +++----- .../data-source.tf | 4 + .../data-source.tf | 4 + examples/provider/provider.tf | 7 + {example => integration}/Dockerfile | 0 integration/README.md | 21 +++ {example => integration}/credentials.tf | 0 .../credentials_azure_service_principal.tf | 0 .../credentials_secret_file.tf | 0 .../credentials_secret_text.tf | 0 {example => integration}/credentials_ssh.tf | 0 .../credentials_vault_approle.tf | 0 {example => integration}/docker-compose.yml | 0 {example => integration}/folder.tf | 0 {example => integration}/freestyle.xml | 0 {example => integration}/id_ed25519 | 0 {example => integration}/id_ed25519.pub | 0 {example => integration}/job.tf | 0 {example => integration}/pipeline.xml | 0 {example => integration}/providers.tf | 0 jenkins/provider.go | 8 +- jenkins/provider_framework.go | 8 +- makefile | 6 +- .../data-sources/credential_username.md.tmpl | 28 ++++ .../credential_vault_approle.md.tmpl | 32 ++++ templates/data-sources/folder.md.tmpl | 30 ++++ templates/data-sources/job.md.tmpl | 26 +++ templates/index.md.tmpl | 19 +++ ...credential_azure_service_principal.md.tmpl | 43 +++++ .../resources/credential_secret_file.md.tmpl | 30 ++++ .../resources/credential_secret_text.md.tmpl | 35 ++++ templates/resources/credential_ssh.md.tmpl | 33 ++++ .../resources/credential_username.md.tmpl | 31 ++++ .../credential_vault_approle.md.tmpl | 35 ++++ templates/resources/folder.md.tmpl | 71 ++++++++ templates/resources/job.md.tmpl | 76 +++++++++ tools/go.mod | 44 +++++ tools/go.sum | 152 ++++++++++++++++++ tools/tools.go | 18 +++ 43 files changed, 818 insertions(+), 71 deletions(-) create mode 100644 examples/data-sources/jenkins_credential_username/data-source.tf create mode 100644 examples/data-sources/jenkins_credential_vault_approle/data-source.tf create mode 100644 examples/provider/provider.tf rename {example => integration}/Dockerfile (100%) create mode 100644 integration/README.md rename {example => integration}/credentials.tf (100%) rename {example => integration}/credentials_azure_service_principal.tf (100%) rename {example => integration}/credentials_secret_file.tf (100%) rename {example => integration}/credentials_secret_text.tf (100%) rename {example => integration}/credentials_ssh.tf (100%) rename {example => integration}/credentials_vault_approle.tf (100%) rename {example => integration}/docker-compose.yml (100%) rename {example => integration}/folder.tf (100%) rename {example => integration}/freestyle.xml (100%) rename {example => integration}/id_ed25519 (100%) rename {example => integration}/id_ed25519.pub (100%) rename {example => integration}/job.tf (100%) rename {example => integration}/pipeline.xml (100%) rename {example => integration}/providers.tf (100%) create mode 100644 templates/data-sources/credential_username.md.tmpl create mode 100644 templates/data-sources/credential_vault_approle.md.tmpl create mode 100644 templates/data-sources/folder.md.tmpl create mode 100644 templates/data-sources/job.md.tmpl create mode 100644 templates/index.md.tmpl create mode 100644 templates/resources/credential_azure_service_principal.md.tmpl create mode 100644 templates/resources/credential_secret_file.md.tmpl create mode 100644 templates/resources/credential_secret_text.md.tmpl create mode 100644 templates/resources/credential_ssh.md.tmpl create mode 100644 templates/resources/credential_username.md.tmpl create mode 100644 templates/resources/credential_vault_approle.md.tmpl create mode 100644 templates/resources/folder.md.tmpl create mode 100644 templates/resources/job.md.tmpl create mode 100644 tools/go.mod create mode 100644 tools/go.sum create mode 100644 tools/tools.go diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index bfaff56..c9d7670 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,8 +8,8 @@ # Test Steps -- [ ] Have you updated the `docs/` folder to match your change? -- [ ] Have you exercised your change using the `examples/` docker compose setup? +- [ ] If you've changed documentation, have you run `make generate` to render the `docs/` folder? +- [ ] Have you exercised your change using the `integration/` docker compose setup? ```sh make testacc diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4c7c6de..b371647 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -15,3 +15,11 @@ updates: groups: combined: patterns: ["*"] + + - package-ecosystem: "gomod" + directory: "/tools" + schedule: + interval: "weekly" + groups: + tools: + patterns: ["*"] diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 3bfc9f6..ce2563e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -56,7 +56,7 @@ jobs: - name: Set up services env: - COMPOSE_FILE: ./example/docker-compose.yml + COMPOSE_FILE: ./integration/docker-compose.yml run: | docker-compose build docker-compose up -d --force-recreate jenkins @@ -75,7 +75,7 @@ jobs: name: acceptance-coverage path: coverage.txt - example: + integration: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 @@ -105,24 +105,46 @@ jobs: - name: Set up services env: - COMPOSE_FILE: ./example/docker-compose.yml + COMPOSE_FILE: ./integration/docker-compose.yml run: | docker-compose build docker-compose up -d --force-recreate jenkins while [ "$(docker inspect jenkins-provider-acc --format '{{ .State.Health.Status }}')" != "healthy" ]; do echo "Waiting for Jenkins to start..."; sleep 3; done - - name: Init example - working-directory: example/ + - name: Init integration + working-directory: integration/ run: terraform init - - name: Run example - working-directory: example/ + - name: Run integration + working-directory: integration/ run: terraform apply -no-color -auto-approve - name: Apply again - working-directory: example/ + working-directory: integration/ run: terraform apply -no-color -auto-approve - - name: Destroy example - working-directory: example/ + - name: Destroy integration + working-directory: integration/ run: terraform destroy -no-color -auto-approve + + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version-file: go.mod + cache: true + + - name: Generate Docs + run: make generate + + - name: Verify directory is clean + run: test -z "$(git status --porcelain)" + + - name: Error message + if: failure() + run: | + echo ':warning: Generated docs differs from committed docs. Did you forget to run `make generate`?' >> $GITHUB_STEP_SUMMARY diff --git a/README.md b/README.md index f09cf95..27816d4 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,12 @@ In order to run the full suite of Acceptance tests, run `make testacc`. These te $ make testacc ``` +When changing a data source or resource, you may need to update the documentation. This documentation is automatically rendered by https://github.com/hashicorp/terraform-plugin-docs. To trigger a render, execute: + +```sh +$ make generate +``` + ## Attribution This provider design was originally inspired from the work at [dihedron/terraform-provider-jenkins](https://github.com/dihedron/terraform-provider-jenkins). diff --git a/docs/index.md b/docs/index.md index 00b34e4..6dfeb64 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,21 +1,22 @@ +--- +page_title: "Provider: Jenkins" +description: |- + The Jenkins provider is used to interact with the Jenkins API. +--- + # Jenkins Provider The Jenkins provider is used to interact with the Jenkins API. The provider needs to be configured with the proper credentials before it can be used. ## Example Usage -```hcl +```terraform # Configure the Jenkins Provider provider "jenkins" { - server_url = "https://jenkins.url" # Or use JENKINS_URL env var - username = "username" # Or use JENKINS_USERNAME env var - password = "password" # Or use JENKINS_PASSWORD env var - ca_cert = "" # Or use JENKINS_CA_CERT env var -} - -# Create a Jenkins job -resource "jenkins_job" "example" { - # ... + server_url = "http://localhost:8080" # Or JENKINS_URL env var + username = "admin" # Or JENKINS_USERNAME env var + password = "admin" # Or JENKINS_PASSWORD env var + ca_cert = "" # Or JENKINS_CA_CERT env var } ``` @@ -23,45 +24,12 @@ resource "jenkins_job" "example" { Jenkins uses a user/password challenge for authentication. It requires a username & password for determining identity and permissions. This method also supports Jenkins' various authentication plugins, such as GitHub OAuth (through the use of Personal Access Tokens). -### Static credentials ### - -Static credentials can be provided by adding a `username` and `password` in-line in the Jenkins provider block: - -Usage: - -```hcl -provider "jenkins" { - server_url = "https://jenkins.url" - username = "username" - password = "password" -} -``` - -### Environment variables - -You can provide your credentials via the `JENKINS_USERNAME` and `JENKINS_PASSWORD`, environment variables. `JENKINS_URL` is also available which will assign the `server_url` property. - -```hcl -provider "jenkins" {} -``` - -Usage: - -```sh -$ export JENKINS_URL="https://jenkins.url" -$ export JENKINS_USERNAME="username" -$ export JENKINS_PASSWORD="password" -$ terraform plan -``` - -## Argument Reference - -In addition to [generic `provider` arguments](https://www.terraform.io/docs/configuration/providers.html) (e.g. `alias` and `version`), the following arguments are supported in the Jenkins `provider` block: - -* `server_url` - (Required) This is the Jenkins server URL. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location. - -* `username` - (Optional) This is Jenkins username for authentication. + +## Schema -* `password` - (Optional) This is the Jenkins password for authentication. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here. +### Optional -* `ca_cert` - (Optional) This is the path to the self-signed certificate that may be required in order to authenticate to your Jenkins instance. +- `ca_cert` (String) The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance. +- `password` (String) The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here. +- `server_url` (String) The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location. +- `username` (String) The username to authenticate to Jenkins. diff --git a/examples/data-sources/jenkins_credential_username/data-source.tf b/examples/data-sources/jenkins_credential_username/data-source.tf new file mode 100644 index 0000000..290ea8c --- /dev/null +++ b/examples/data-sources/jenkins_credential_username/data-source.tf @@ -0,0 +1,4 @@ +data "jenkins_credential_username" "example" { + name = "name" + folder = jenkins_folder.example.id +} diff --git a/examples/data-sources/jenkins_credential_vault_approle/data-source.tf b/examples/data-sources/jenkins_credential_vault_approle/data-source.tf new file mode 100644 index 0000000..1fbda72 --- /dev/null +++ b/examples/data-sources/jenkins_credential_vault_approle/data-source.tf @@ -0,0 +1,4 @@ +data "jenkins_credential_vault_approle" "example" { + name = "name" + folder = jenkins_folder.example.id +} diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf new file mode 100644 index 0000000..487fdbb --- /dev/null +++ b/examples/provider/provider.tf @@ -0,0 +1,7 @@ +# Configure the Jenkins Provider +provider "jenkins" { + server_url = "http://localhost:8080" # Or JENKINS_URL env var + username = "admin" # Or JENKINS_USERNAME env var + password = "admin" # Or JENKINS_PASSWORD env var + ca_cert = "" # Or JENKINS_CA_CERT env var +} diff --git a/example/Dockerfile b/integration/Dockerfile similarity index 100% rename from example/Dockerfile rename to integration/Dockerfile diff --git a/integration/README.md b/integration/README.md new file mode 100644 index 0000000..eab027d --- /dev/null +++ b/integration/README.md @@ -0,0 +1,21 @@ +# Integration + +This folder contains an example Dockerized instance of Jenkins for performing manual testing against. It can be used during development to validate against a real Jenkins installation. + +## Usage + +Start Jenkins with: + +```sh +docker-compose up --detach +``` + +And then open it in your web browser at http://localhost:8080. + +You can now run `terraform init`, `plan`, `apply`, etc. commands within this directory to test the provider against the Jenkins instance. If you are testing a version of the provider that you are developing locally, ensure that you've run the `make` command in the repository root and followed the provided instructions to configure your machine to use the built binary. + +When done with testing, clean up the instance with: + +```sh +docker-compose down --volumes +``` diff --git a/example/credentials.tf b/integration/credentials.tf similarity index 100% rename from example/credentials.tf rename to integration/credentials.tf diff --git a/example/credentials_azure_service_principal.tf b/integration/credentials_azure_service_principal.tf similarity index 100% rename from example/credentials_azure_service_principal.tf rename to integration/credentials_azure_service_principal.tf diff --git a/example/credentials_secret_file.tf b/integration/credentials_secret_file.tf similarity index 100% rename from example/credentials_secret_file.tf rename to integration/credentials_secret_file.tf diff --git a/example/credentials_secret_text.tf b/integration/credentials_secret_text.tf similarity index 100% rename from example/credentials_secret_text.tf rename to integration/credentials_secret_text.tf diff --git a/example/credentials_ssh.tf b/integration/credentials_ssh.tf similarity index 100% rename from example/credentials_ssh.tf rename to integration/credentials_ssh.tf diff --git a/example/credentials_vault_approle.tf b/integration/credentials_vault_approle.tf similarity index 100% rename from example/credentials_vault_approle.tf rename to integration/credentials_vault_approle.tf diff --git a/example/docker-compose.yml b/integration/docker-compose.yml similarity index 100% rename from example/docker-compose.yml rename to integration/docker-compose.yml diff --git a/example/folder.tf b/integration/folder.tf similarity index 100% rename from example/folder.tf rename to integration/folder.tf diff --git a/example/freestyle.xml b/integration/freestyle.xml similarity index 100% rename from example/freestyle.xml rename to integration/freestyle.xml diff --git a/example/id_ed25519 b/integration/id_ed25519 similarity index 100% rename from example/id_ed25519 rename to integration/id_ed25519 diff --git a/example/id_ed25519.pub b/integration/id_ed25519.pub similarity index 100% rename from example/id_ed25519.pub rename to integration/id_ed25519.pub diff --git a/example/job.tf b/integration/job.tf similarity index 100% rename from example/job.tf rename to integration/job.tf diff --git a/example/pipeline.xml b/integration/pipeline.xml similarity index 100% rename from example/pipeline.xml rename to integration/pipeline.xml diff --git a/example/providers.tf b/integration/providers.tf similarity index 100% rename from example/providers.tf rename to integration/providers.tf diff --git a/jenkins/provider.go b/jenkins/provider.go index 685f4ec..7581e59 100644 --- a/jenkins/provider.go +++ b/jenkins/provider.go @@ -17,22 +17,22 @@ func Provider() *schema.Provider { "server_url": { Type: schema.TypeString, Optional: true, - Description: "The URL of the Jenkins server to connect to.", + Description: "The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.", }, "ca_cert": { Type: schema.TypeString, Optional: true, - Description: "The path to the Jenkins self-signed certificate.", + Description: "The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance.", }, "username": { Type: schema.TypeString, Optional: true, // Needs to be optional to be able to run terraform validate without providing credentials - Description: "Username to authenticate to Jenkins.", + Description: "The username to authenticate to Jenkins.", }, "password": { Type: schema.TypeString, Optional: true, // Needs to be optional to be able to run terraform validate without providing credentials - Description: "Password to authenticate to Jenkins.", + Description: "The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.", }, }, diff --git a/jenkins/provider_framework.go b/jenkins/provider_framework.go index b5666a9..eec2367 100644 --- a/jenkins/provider_framework.go +++ b/jenkins/provider_framework.go @@ -32,19 +32,19 @@ func (p *JenkinsProvider) Schema(ctx context.Context, req provider.SchemaRequest Attributes: map[string]schema.Attribute{ "server_url": schema.StringAttribute{ Optional: true, - Description: "The URL of the Jenkins server to connect to.", + Description: "The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.", }, "ca_cert": schema.StringAttribute{ Optional: true, - Description: "The path to the Jenkins self-signed certificate.", + Description: "The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance.", }, "username": schema.StringAttribute{ Optional: true, // Needs to be optional to be able to run terraform validate without providing credentials - Description: "Username to authenticate to Jenkins.", + Description: "The username to authenticate to Jenkins.", }, "password": schema.StringAttribute{ Optional: true, // Needs to be optional to be able to run terraform validate without providing credentials - Description: "Password to authenticate to Jenkins.", + Description: "The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.", }, }, } diff --git a/makefile b/makefile index 0b9936b..0294669 100644 --- a/makefile +++ b/makefile @@ -1,5 +1,5 @@ BINARY=terraform-provider-jenkins -export COMPOSE_FILE=./example/docker-compose.yml +export COMPOSE_FILE=./integration/docker-compose.yml default: build @@ -17,6 +17,10 @@ build: @echo "" @echo "This should only be used during development. See https://www.terraform.io/docs/commands/cli-config.html#development-overrides-for-provider-developers for details." +# Formats TF files and generates documentation +generate: + cd tools; go generate ./... + # Executes all unit tests for the provider test: go test -cover ./... diff --git a/templates/data-sources/credential_username.md.tmpl b/templates/data-sources/credential_username.md.tmpl new file mode 100644 index 0000000..8b9dcbf --- /dev/null +++ b/templates/data-sources/credential_username.md.tmpl @@ -0,0 +1,28 @@ +# jenkins_credential_username Data Source + +Get the attributes of a username credential within Jenkins. + +## Example Usage + +```hcl +data "jenkins_credential_username" "example" { + name = "job-name" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the resource being read. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace containing this resource. + +## Attribute Reference + +In addition to all arguments above, the following attributes are exported: + +* `id` - The full canonical job path, E.G. `/job/job-name`. +* `description` - A human readable description of the credentials being stored. +* `scope` - The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". +* `username` - The username to be associated with the credentials. diff --git a/templates/data-sources/credential_vault_approle.md.tmpl b/templates/data-sources/credential_vault_approle.md.tmpl new file mode 100644 index 0000000..d0a7fec --- /dev/null +++ b/templates/data-sources/credential_vault_approle.md.tmpl @@ -0,0 +1,32 @@ +# jenkins_credential_vault_approle Data Source + +Get the attributes of a Vault AppRole credential within Jenkins. + +~> The Jenkins installation that uses this resource is expected to have the [Hashicorp Vault Plugin](https://plugins.jenkins.io/hashicorp-vault-plugin/) installed in their system. + +## Example Usage + +```hcl +data "jenkins_credential_vault_approle" "example" { + name = "job-name" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the resource being read. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace containing this resource. + +## Attribute Reference + +In addition to all arguments above, the following attributes are exported: + +* `id` - The full canonical job path, E.G. `/job/job-name`. +* `description` - A human readable description of the credentials being stored. +* `scope` - The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". +* `namespace` - The Vault namespace of the approle credential. +* `path` - The unique name of the approle auth backend. Defaults to `approle`. +* `role_id` - The role_id to be associated with the credentials. diff --git a/templates/data-sources/folder.md.tmpl b/templates/data-sources/folder.md.tmpl new file mode 100644 index 0000000..ad7940f --- /dev/null +++ b/templates/data-sources/folder.md.tmpl @@ -0,0 +1,30 @@ +# jenkins_folder Data Source + +Get the attributes of a folder within Jenkins. + +~> The Jenkins installation that uses this resource is expected to have the [Cloudbees Folders Plugin](https://plugins.jenkins.io/cloudbees-folder) installed in their system. + +## Example Usage + +```hcl +data "jenkins_folder" "example" { + name = "folder-name" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the folder being read. +* `folder` - (Optional) The folder namespace containing this folder. + + +## Attribute Reference + +In addition to all arguments above, the following attributes are exported: + +* `id` - The full canonical folder path, E.G. `/job/parent`. +* `description` - A block of text describing the folder's purpose. +* `display_name` - The name of the folder that is displayed in the UI. +* `template` - A Jenkins-compatible XML template to describe the folder. diff --git a/templates/data-sources/job.md.tmpl b/templates/data-sources/job.md.tmpl new file mode 100644 index 0000000..12ba37f --- /dev/null +++ b/templates/data-sources/job.md.tmpl @@ -0,0 +1,26 @@ +# jenkins_job Data Source + +Get the attributes of a job within Jenkins. + +## Example Usage + +```hcl +data "jenkins_job" "example" { + name = "job-name" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the job being read. +* `folder` - (Optional) The folder namespace containing this job. + + +## Attribute Reference + +In addition to all arguments above, the following attributes are exported: + +* `id` - The full canonical job path, E.G. `/job/job-name`. +* `template` - A Jenkins-compatible XML template to describe the job. diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl new file mode 100644 index 0000000..d570144 --- /dev/null +++ b/templates/index.md.tmpl @@ -0,0 +1,19 @@ +--- +page_title: "Provider: Jenkins" +description: |- + The Jenkins provider is used to interact with the Jenkins API. +--- + +# Jenkins Provider + +The Jenkins provider is used to interact with the Jenkins API. The provider needs to be configured with the proper credentials before it can be used. + +## Example Usage + +{{ tffile "examples/provider/provider.tf" }} + +## Authentication + +Jenkins uses a user/password challenge for authentication. It requires a username & password for determining identity and permissions. This method also supports Jenkins' various authentication plugins, such as GitHub OAuth (through the use of Personal Access Tokens). + +{{ .SchemaMarkdown | trimspace }} diff --git a/templates/resources/credential_azure_service_principal.md.tmpl b/templates/resources/credential_azure_service_principal.md.tmpl new file mode 100644 index 0000000..0c0a2c8 --- /dev/null +++ b/templates/resources/credential_azure_service_principal.md.tmpl @@ -0,0 +1,43 @@ +# resource_jenkins_credential_azure_service_principal Resource + +Manages an Azure Service Principal credential within Jenkins. This credential may then be referenced within jobs that are created. + +~> The "client_secret" property may leave plain-text secret id in your state file. If using the property to manage the secret id in Terraform, ensure that your state file is properly secured and encrypted at rest. + +~> The Jenkins installation that uses this resource is expected to have the [Azure Credentials Plugin](https://plugins.jenkins.io/azure-credentials/) installed in their system. + +## Example Usage + +```hcl +resource jenkins_credential_azure_service_principal foo { + name = "example-secret" + subscription_id = "01234567-89ab-cdef-0123-456789abcdef" + client_id = "abcdef01-2345-6789-0123-456789abcdef" + client_secret = "super-secret" + tenant = "01234567-89ab-cdef-abcd-456789abcdef" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. +* `subscription_id` - (Required) The Azure subscription id mapped to the Azure Service Principal. +* `client_id` - (Required) The client id (application id) of the Azure Service Principal. +* `client_secret` - (Optional) The client secret of the Azure Service Principal. Cannot be used with `certificate_id`. Has to be specified, if `certificate_id` is not specified. +* `certificate_id` - (Optional) The certificate reference of the Azure Service Principal, pointing to a Jenkins certificate credential. Cannot be used with `client_secret`. Has to be specified, if `client_secret` is not specified. +* `tenant` - (Required) The Azure Tenant ID of the Azure Service Principal. +* `azure_environment_name` - (Optional) The Azure Cloud enviroment name. Allowed values are "Azure", "Azure China", "Azure Germany", "Azure US Government". +* `service_management_url` - (Optional) Override the Azure management endpoint URL for the selected Azure environment. +* `authentication_endpoint` - (Optional) Override the Azure Active Directory endpoint for the selected Azure environment. +* `resource_manager_endpoint` - (Optional) Override the Azure resource manager endpoint URL for the selected Azure environment. +* `graph_endpoint` - (Optional) Override the Azure graph endpoint URL for the selected Azure environment. + +## Attribute Reference + +All arguments above are exported. diff --git a/templates/resources/credential_secret_file.md.tmpl b/templates/resources/credential_secret_file.md.tmpl new file mode 100644 index 0000000..fdf0099 --- /dev/null +++ b/templates/resources/credential_secret_file.md.tmpl @@ -0,0 +1,30 @@ +# jenkins_credential_secret_file Resource + +Manages a secret file credential within Jenkins. This secret file may then be referenced within jobs that are created. + +## Example Usage + +```hcl +resource "jenkins_credential_secret_file" "example" { + name = "example-secret-file" + filename = "secret-file.txt" + secretbytes = base64encode("My secret file very secret content.") +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. +* `filename` - (Required) The secret file filename on jenkins server side. +* `secretbytes` - (Required) The secret file, base64 encoded content. It can be sourced directly from local file with filebase64(path) TF function or given directly. + + +## Attribute Reference + +All arguments above are exported. diff --git a/templates/resources/credential_secret_text.md.tmpl b/templates/resources/credential_secret_text.md.tmpl new file mode 100644 index 0000000..4e04216 --- /dev/null +++ b/templates/resources/credential_secret_text.md.tmpl @@ -0,0 +1,35 @@ +# jenkins_credential_secret_text Resource + +Manages a secret text credential within Jenkins. This secret text may then be referenced within jobs that are created. + +## Example Usage + +```hcl +resource "jenkins_credential_secret_text" "example" { + name = "example-username" + secret = "super-secret" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. If not set will default to "Managed by Terraform". +* `secret` - (Required) The secret text to be associated with the credentials. + +## Attribute Reference + +All arguments above are exported. + +## Import + +Secret text credential may be imported by their canonical name, e.g. + +```sh +$ terraform import jenkins_credential_secret_text.example "[/]/" +``` diff --git a/templates/resources/credential_ssh.md.tmpl b/templates/resources/credential_ssh.md.tmpl new file mode 100644 index 0000000..e774c7c --- /dev/null +++ b/templates/resources/credential_ssh.md.tmpl @@ -0,0 +1,33 @@ +# jenkins_credential_ssh Resource + +Manages a SSH credential within Jenkins. This SSH credential may then be referenced within jobs that are created. + +~> The "passphrase" and "privatekey" properties may leave plain-text values in your state file. Ensure that your state file is properly secured and encrypted at rest. + +## Example Usage + +```hcl +resource "jenkins_credential_ssh" "example" { + name = "example-id" + username = "example-username" + privatekey = file("/some/path/id_rsa") + passphrase = "Super_Secret_Pass" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `username` - (Required) The username to be associated with the credentials. +* `privatekey` - (Required) Private SSH key, can be given as string or read from file with 'file()' terraform function. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. +* `passphrase` - (Optional) Passphrase for privatekey. This has to be skipped if private key was created without passphrase. + +## Attribute Reference + +All arguments above are exported. diff --git a/templates/resources/credential_username.md.tmpl b/templates/resources/credential_username.md.tmpl new file mode 100644 index 0000000..99664de --- /dev/null +++ b/templates/resources/credential_username.md.tmpl @@ -0,0 +1,31 @@ +# jenkins_credential_username Resource + +Manages a username credential within Jenkins. This username may then be referenced within jobs that are created. + +~> The "password" property may leave plain-text passwords in your state file. If using the property to manage the password in Terraform, ensure that your state file is properly secured and encrypted at rest. + +## Example Usage + +```hcl +resource "jenkins_credential_username" "example" { + name = "example-username" + username = "example" + password = "super-secret" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. +* `username` - (Required) The username to be associated with the credentials. +* `password` - (Optional) The password to be associated with the credentials. If empty then the password property will become unmanaged and expected to be set manually within Jenkins. If set then the password will be updated only upon changes -- if the password is set manually within Jenkins then it will not reconcile this drift until the next time the password property is changed. + +## Attribute Reference + +All arguments above are exported. diff --git a/templates/resources/credential_vault_approle.md.tmpl b/templates/resources/credential_vault_approle.md.tmpl new file mode 100644 index 0000000..49e3e08 --- /dev/null +++ b/templates/resources/credential_vault_approle.md.tmpl @@ -0,0 +1,35 @@ +# jenkins_credential_vault_approle Resource + +Manages a Vault AppRole credential within Jenkins. This credential may then be referenced within jobs that are created. + +~> The "secret_id" property may leave plain-text secret id in your state file. If using the property to manage the secret id in Terraform, ensure that your state file is properly secured and encrypted at rest. + +~> The Jenkins installation that uses this resource is expected to have the [Hashicorp Vault Plugin](https://plugins.jenkins.io/hashicorp-vault-plugin/) installed in their system. + +## Example Usage + +```hcl +resource "jenkins_credential_vault_approle" "example" { + name = "example-approle" + role_id = "example" + secret_id = "super-secret" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the credentials being created. This maps to the ID property within Jenkins, and cannot be changed once set. +* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store. +* `folder` - (Optional) The folder namespace to store the credentials in. If not set will default to global Jenkins credentials. +* `scope` - (Optional) The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM". If not set will default to "GLOBAL". +* `description` - (Optional) A human readable description of the credentials being stored. +* `namespace` - (Optional) The Vault namespace of the approle credential. +* `path` - (Optional) The unique name of the approle auth backend. Defaults to `approle`. +* `role_id` - (Required) The role_id to be associated with the credentials. +* `secret_id` - (Optional) The secret_id to be associated with the credentials. If empty then the secret_id property will become unmanaged and expected to be set manually within Jenkins. If set then the secret_id will be updated only upon changes -- if the secret_id is set manually within Jenkins then it will not reconcile this drift until the next time the secret_id property is changed. + +## Attribute Reference + +All arguments above are exported. diff --git a/templates/resources/folder.md.tmpl b/templates/resources/folder.md.tmpl new file mode 100644 index 0000000..89c528d --- /dev/null +++ b/templates/resources/folder.md.tmpl @@ -0,0 +1,71 @@ +# jenkins_folder Resource + +Manages a folder within Jenkins. + +~> The Jenkins installation that uses this resource is expected to have the [Cloudbees Folders Plugin](https://plugins.jenkins.io/cloudbees-folder) installed in their system. + +## Example Usage + +```hcl +resource "jenkins_folder" "example" { + name = "folder-name" + description = "A top-level folder" +} + +resource "jenkins_folder" "example_child" { + name = "child-name" + folder = jenkins_folder.example.id + description = "A nested subfolder" + + security { + permissions = [ + "com.cloudbees.plugins.credentials.CredentialsProvider.Create:anonymous", + "com.cloudbees.plugins.credentials.CredentialsProvider.Delete:authenticated", + "hudson.model.Item.Cancel:authenticated", + "hudson.model.Item.Discover:anonymous", + ] + } +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the folder being created. +* `display_name` - (Optional) The name of the folder to be displayed in the UI. +* `folder` - (Optional) The folder namespace to store the subfolder in. If creating in a nested folder structure you may separate folder names with `/`, such as `parent/child`. This name cannot be changed once the folder has been created, and all parent folders must be created in advance. +* `description` - (Optional) A block of text describing the folder's purpose. +* `security` - (Optional) An optional block defining a project-based authorization strategy, documented below. + +### security + +~> This block may need the [Matrix Authorization Strategy Plugin](https://plugins.jenkins.io/matrix-auth/) installed and enabled in the system's Global Security settings in order to function properly. + +* `inheritance_strategy` - The strategy for applying these permissions sets to existing inherited permissions. Defaults to "org.jenkinsci.plugins.matrixauth.inheritance.InheritParentStrategy". +* `permissions` - A list of strings containing Jenkins permissions assigments to users and groups for the folder. For example: + +```hcl + permissions = [ + "hudson.model.Item.Build:username", + "hudson.model.Item.Cancel:username", + "hudson.model.Item.Configure:username", + "hudson.model.Item.Create:username", + "hudson.model.Item.Delete:username", + ] +``` + +## Attribute Reference + +In addition to all arguments above, the following attributes are exported: + +* `id` - The full canonical folder path, E.G. `/job/parent`. +* `template` - A Jenkins-compatible XML template to describe the folder. You can retrieve an existing folder's XML by appending `/config.xml` to its URL and viewing the source in your browser. + +## Import + +Folders may be imported by their canonical name, e.g. + +```sh +$ terraform import jenkins_folder.example /job/folder-name +``` diff --git a/templates/resources/job.md.tmpl b/templates/resources/job.md.tmpl new file mode 100644 index 0000000..e6a0290 --- /dev/null +++ b/templates/resources/job.md.tmpl @@ -0,0 +1,76 @@ +# jenkins_job Resource + +Manages a job within Jenkins. + +## Example Usage + +```hcl +resource "jenkins_folder" "example" { + name = "folder-name" +} + +resource "jenkins_job" "example" { + name = "example" + folder = jenkins_folder.example.id + template = templatefile("${path.module}/job.xml", { + description = "An example job created from Terraform" + }) +} +``` + +And in `job.xml`: + +```xml + + + ${description} + false + + + + 2 + + + https://github.com/taiidani/terraform-provider-jenkins.git + github + + + + + */main + + + false + + + + Jenkinsfile + true + + + false + +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) The name of the job being created. +* `folder` - (Optional) The folder namespace to store the job in. If creating in a nested folder structure you may separate folder names with `/`, such as `parent/child`. This name cannot be changed once the folder has been created, and all parent folders must be created in advance. +* `parameters` - (Optional) A map of string values that are passed into the template for rendering. **Deprecated:** Please use Terraform's built-in [templatefile](https://www.terraform.io/docs/language/functions/templatefile.html) function instead of this property. +* `template` - (Required) A Jenkins-compatible XML template to describe the job. You can retrieve an existing jobs' XML by appending `/config.xml` to its URL and viewing the source in your browser. The `template` property is rendered using a Golang template that takes the other resource arguments as variables. Do not include the XML prolog in the definition. + +## Attribute Reference + +All arguments above are exported. + +## Import + +Jobs may be imported by their canonical name, e.g. + +```sh +$ terraform import jenkins_job.example /job/job-name +``` + +Please note that in some cases, the imported XML may not fully match the template you are specifying in your resource, therefore please run a `terraform plan`, and if there are any template XML changes, run `terraform apply` to ensure your Terraform state file is fully in sync. diff --git a/tools/go.mod b/tools/go.mod new file mode 100644 index 0000000..dd04a5a --- /dev/null +++ b/tools/go.mod @@ -0,0 +1,44 @@ +module tools + +go 1.19 + +require github.com/hashicorp/terraform-plugin-docs v0.16.0 + +require ( + github.com/Masterminds/goutils v1.1.1 // indirect + github.com/Masterminds/semver/v3 v3.1.1 // indirect + github.com/Masterminds/sprig/v3 v3.2.2 // indirect + github.com/ProtonMail/go-crypto v0.0.0-20230217124315-7d5c6f04bbb8 // indirect + github.com/apparentlymart/go-textseg/v13 v13.0.0 // indirect + github.com/armon/go-radix v1.0.0 // indirect + github.com/bgentry/speakeasy v0.1.0 // indirect + github.com/cloudflare/circl v1.3.3 // indirect + github.com/fatih/color v1.13.0 // indirect + github.com/google/uuid v1.3.0 // indirect + github.com/hashicorp/errwrap v1.1.0 // indirect + github.com/hashicorp/go-checkpoint v0.5.0 // indirect + github.com/hashicorp/go-cleanhttp v0.5.2 // indirect + github.com/hashicorp/go-multierror v1.1.1 // indirect + github.com/hashicorp/go-uuid v1.0.3 // indirect + github.com/hashicorp/go-version v1.6.0 // indirect + github.com/hashicorp/hc-install v0.5.2 // indirect + github.com/hashicorp/terraform-exec v0.18.1 // indirect + github.com/hashicorp/terraform-json v0.17.1 // indirect + github.com/huandu/xstrings v1.3.2 // indirect + github.com/imdario/mergo v0.3.13 // indirect + github.com/mattn/go-colorable v0.1.13 // indirect + github.com/mattn/go-isatty v0.0.16 // indirect + github.com/mitchellh/cli v1.1.5 // indirect + github.com/mitchellh/copystructure v1.2.0 // indirect + github.com/mitchellh/reflectwalk v1.0.2 // indirect + github.com/posener/complete v1.2.3 // indirect + github.com/russross/blackfriday v1.6.0 // indirect + github.com/shopspring/decimal v1.3.1 // indirect + github.com/spf13/cast v1.5.0 // indirect + github.com/zclconf/go-cty v1.13.2 // indirect + golang.org/x/crypto v0.8.0 // indirect + golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df // indirect + golang.org/x/mod v0.11.0 // indirect + golang.org/x/sys v0.7.0 // indirect + golang.org/x/text v0.11.0 // indirect +) diff --git a/tools/go.sum b/tools/go.sum new file mode 100644 index 0000000..748c5b5 --- /dev/null +++ b/tools/go.sum @@ -0,0 +1,152 @@ +github.com/Masterminds/goutils v1.1.1 h1:5nUrii3FMTL5diU80unEVvNevw1nH4+ZV4DSLVJLSYI= +github.com/Masterminds/goutils v1.1.1/go.mod h1:8cTjp+g8YejhMuvIA5y2vz3BpJxksy863GQaJW2MFNU= +github.com/Masterminds/semver/v3 v3.1.1 h1:hLg3sBzpNErnxhQtUy/mmLR2I9foDujNK030IGemrRc= +github.com/Masterminds/semver/v3 v3.1.1/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs= +github.com/Masterminds/sprig/v3 v3.2.1/go.mod h1:UoaO7Yp8KlPnJIYWTFkMaqPUYKTfGFPhxNuwnnxkKlk= +github.com/Masterminds/sprig/v3 v3.2.2 h1:17jRggJu518dr3QaafizSXOjKYp94wKfABxUmyxvxX8= +github.com/Masterminds/sprig/v3 v3.2.2/go.mod h1:UoaO7Yp8KlPnJIYWTFkMaqPUYKTfGFPhxNuwnnxkKlk= +github.com/Microsoft/go-winio v0.5.2 h1:a9IhgEQBCUEk6QCdml9CiJGhAws+YwffDHEMp1VMrpA= +github.com/ProtonMail/go-crypto v0.0.0-20230217124315-7d5c6f04bbb8 h1:wPbRQzjjwFc0ih8puEVAOFGELsn1zoIIYdxvML7mDxA= +github.com/ProtonMail/go-crypto v0.0.0-20230217124315-7d5c6f04bbb8/go.mod h1:I0gYDMZ6Z5GRU7l58bNFSkPTFN6Yl12dsUlAZ8xy98g= +github.com/acomagu/bufpipe v1.0.4 h1:e3H4WUzM3npvo5uv95QuJM3cQspFNtFBzvJ2oNjKIDQ= +github.com/apparentlymart/go-textseg/v13 v13.0.0 h1:Y+KvPE1NYz0xl601PVImeQfFyEy6iT90AvPUL1NNfNw= +github.com/apparentlymart/go-textseg/v13 v13.0.0/go.mod h1:ZK2fH7c4NqDTLtiYLvIkEghdlcqw7yxLeM89kiTRPUo= +github.com/armon/go-radix v0.0.0-20180808171621-7fddfc383310/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8= +github.com/armon/go-radix v1.0.0 h1:F4z6KzEeeQIMeLFa97iZU6vupzoecKdU5TX24SNppXI= +github.com/armon/go-radix v1.0.0/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8= +github.com/bgentry/speakeasy v0.1.0 h1:ByYyxL9InA1OWqxJqqp2A5pYHUrCiAL6K3J+LKSsQkY= +github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs= +github.com/bwesterb/go-ristretto v1.2.0/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0= +github.com/cloudflare/circl v1.1.0/go.mod h1:prBCrKB9DV4poKZY1l9zBXg2QJY7mvgRvtMxxK7fi4I= +github.com/cloudflare/circl v1.3.3 h1:fE/Qz0QdIGqeWfnwq0RE0R7MI51s0M2E4Ga9kq5AEMs= +github.com/cloudflare/circl v1.3.3/go.mod h1:5XYMA4rFBvNIrhs50XuiBJ15vF2pZn4nnUKZrLbUZFA= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc= +github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4= +github.com/fatih/color v1.13.0 h1:8LOYc1KYPPmyKMuN8QV2DNRWNbLo6LZ0iLs8+mlH53w= +github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYFFOfk= +github.com/frankban/quicktest v1.14.3 h1:FJKSZTDHjyhriyC81FLQ0LY93eSai0ZyR/ZIkd3ZUKE= +github.com/go-git/gcfg v1.5.0 h1:Q5ViNfGF8zFgyJWPqYwA7qGFoMTEiBmdlkcfRmpIMa4= +github.com/go-git/go-billy/v5 v5.4.1 h1:Uwp5tDRkPr+l/TnbHOQzp+tmJfLceOlbVucgpTz8ix4= +github.com/go-git/go-git/v5 v5.6.1 h1:q4ZRqQl4pR/ZJHc1L5CFjGA1a10u76aV1iC+nh+bHsk= +github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38= +github.com/google/uuid v1.1.1/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I= +github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4= +github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I= +github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4= +github.com/hashicorp/go-checkpoint v0.5.0 h1:MFYpPZCnQqQTE18jFwSII6eUQrD/oxMFp3mlgcqk5mU= +github.com/hashicorp/go-checkpoint v0.5.0/go.mod h1:7nfLNL10NsxqO4iWuW6tWW0HjZuDrwkBuEQsVcpCOgg= +github.com/hashicorp/go-cleanhttp v0.5.0/go.mod h1:JpRdi6/HCYpAwUzNwuwqhbovhLtngrth3wmdIIUrZ80= +github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ= +github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48= +github.com/hashicorp/go-multierror v1.0.0/go.mod h1:dHtQlpGsu+cZNNAkkCN/P3hoUDHhCYQXV3UM06sGGrk= +github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo= +github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM= +github.com/hashicorp/go-uuid v1.0.0/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro= +github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8= +github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro= +github.com/hashicorp/go-version v1.6.0 h1:feTTfFNnjP967rlCxM/I9g701jU+RN74YKx2mOkIeek= +github.com/hashicorp/go-version v1.6.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA= +github.com/hashicorp/hc-install v0.5.2 h1:SfwMFnEXVVirpwkDuSF5kymUOhrUxrTq3udEseZdOD0= +github.com/hashicorp/hc-install v0.5.2/go.mod h1:9QISwe6newMWIfEiXpzuu1k9HAGtQYgnSH8H9T8wmoI= +github.com/hashicorp/terraform-exec v0.18.1 h1:LAbfDvNQU1l0NOQlTuudjczVhHj061fNX5H8XZxHlH4= +github.com/hashicorp/terraform-exec v0.18.1/go.mod h1:58wg4IeuAJ6LVsLUeD2DWZZoc/bYi6dzhLHzxM41980= +github.com/hashicorp/terraform-json v0.17.1 h1:eMfvh/uWggKmY7Pmb3T85u86E2EQg6EQHgyRwf3RkyA= +github.com/hashicorp/terraform-json v0.17.1/go.mod h1:Huy6zt6euxaY9knPAFKjUITn8QxUFIe9VuSzb4zn/0o= +github.com/hashicorp/terraform-plugin-docs v0.16.0 h1:UmxFr3AScl6Wged84jndJIfFccGyBZn52KtMNsS12dI= +github.com/hashicorp/terraform-plugin-docs v0.16.0/go.mod h1:M3ZrlKBJAbPMtNOPwHicGi1c+hZUh7/g0ifT/z7TVfA= +github.com/huandu/xstrings v1.3.1/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE= +github.com/huandu/xstrings v1.3.2 h1:L18LIDzqlW6xN2rEkpdV8+oL/IXWJ1APd+vsdYy4Wdw= +github.com/huandu/xstrings v1.3.2/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE= +github.com/imdario/mergo v0.3.11/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA= +github.com/imdario/mergo v0.3.13 h1:lFzP57bqS/wsqKssCGmtLAb8A0wKjLGrve2q3PPVcBk= +github.com/imdario/mergo v0.3.13/go.mod h1:4lJ1jqUDcsbIECGy0RUJAXNIhg+6ocWgb1ALK2O4oXg= +github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOlocH6Fxy8MmwDt+yVQYULKfN0RoTN8A= +github.com/kevinburke/ssh_config v1.2.0 h1:x584FjTGwHzMwvHx18PXxbBVzfnxogHaAReU4gf13a4= +github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU= +github.com/mattn/go-colorable v0.1.9/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc= +github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= +github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= +github.com/mattn/go-isatty v0.0.3/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4= +github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU= +github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94= +github.com/mattn/go-isatty v0.0.16 h1:bq3VjFmv/sOjHtdEhmkEV4x1AJtvUvOJ2PFAZ5+peKQ= +github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= +github.com/mitchellh/cli v1.1.5 h1:OxRIeJXpAMztws/XHlN2vu6imG5Dpq+j61AzAX5fLng= +github.com/mitchellh/cli v1.1.5/go.mod h1:v8+iFts2sPIKUV1ltktPXMCC8fumSKFItNcD2cLtRR4= +github.com/mitchellh/copystructure v1.0.0/go.mod h1:SNtv71yrdKgLRyLFxmLdkAbkKEFWgYaq1OVrnRcwhnw= +github.com/mitchellh/copystructure v1.2.0 h1:vpKXTN4ewci03Vljg/q9QvCGUDttBOGBIa15WveJJGw= +github.com/mitchellh/copystructure v1.2.0/go.mod h1:qLl+cE2AmVv+CoeAwDPye/v+N2HKCj9FbZEVFJRxO9s= +github.com/mitchellh/reflectwalk v1.0.0/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw= +github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ= +github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw= +github.com/pjbgf/sha1cd v0.3.0 h1:4D5XXmUUBUl/xQ6IjCkEAbqXskkq/4O7LmGn0AqMDs4= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI= +github.com/posener/complete v1.2.3 h1:NP0eAhjcjImqslEwo/1hq7gpajME0fTLTezBKDqfXqo= +github.com/posener/complete v1.2.3/go.mod h1:WZIdtGGp+qx0sLrYKtIRAruyNpv6hFCicSgv7Sy7s/s= +github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k= +github.com/russross/blackfriday v1.6.0 h1:KqfZb0pUVN2lYqZUYRddxF4OR8ZMURnJIG5Y3VRLtww= +github.com/russross/blackfriday v1.6.0/go.mod h1:ti0ldHuxg49ri4ksnFxlkCfN+hvslNlmVHqNRXXJNAY= +github.com/sergi/go-diff v1.2.0 h1:XU+rvMAioB0UC3q1MFrIQy4Vo5/4VsRDQQXHsEya6xQ= +github.com/shopspring/decimal v1.2.0/go.mod h1:DKyhrW/HYNuLGql+MJL6WCR6knT2jwCFRcu2hWCYk4o= +github.com/shopspring/decimal v1.3.1 h1:2Usl1nmF/WZucqkFZhnfFYxxxu8LG21F6nPQBE5gKV8= +github.com/shopspring/decimal v1.3.1/go.mod h1:DKyhrW/HYNuLGql+MJL6WCR6knT2jwCFRcu2hWCYk4o= +github.com/skeema/knownhosts v1.1.0 h1:Wvr9V0MxhjRbl3f9nMnKnFfiWTJmtECJ9Njkea3ysW0= +github.com/spf13/cast v1.3.1/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkUJE= +github.com/spf13/cast v1.5.0 h1:rj3WzYc11XZaIZMPKmwP96zkFEnnAmV8s6XbB2aY32w= +github.com/spf13/cast v1.5.0/go.mod h1:SpXXQ5YoyJw6s3/6cMTQuxvgRl3PCJiyaX9p6b155UU= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs= +github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4= +github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA= +github.com/stretchr/testify v1.6.1 h1:hDPOHmpOpP40lSULcqw7IrRb/u7w6RpDC9399XyoNd0= +github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/xanzy/ssh-agent v0.3.3 h1:+/15pJfg/RsTxqYcX6fHqOXZwwMP+2VyYWJeWM2qQFM= +github.com/zclconf/go-cty v1.13.2 h1:4GvrUxe/QUDYuJKAav4EYqdM47/kZa672LwmXFmEKT0= +github.com/zclconf/go-cty v1.13.2/go.mod h1:YKQzy/7pZ7iq2jNFzy5go57xdxdWoLLpaEp4u238AE0= +golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= +golang.org/x/crypto v0.0.0-20200414173820-0848c9571904/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= +golang.org/x/crypto v0.0.0-20200820211705-5c72a883971a/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= +golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= +golang.org/x/crypto v0.8.0 h1:pd9TJtTueMTVQXzk8E2XESSMQDj/U7OUu0PqJqPXQjQ= +golang.org/x/crypto v0.8.0/go.mod h1:mRqEX+O9/h5TFCrQhkgjo2yKi0yYA+9ecGkdQoHrywE= +golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df h1:UA2aFVmmsIlefxMk29Dp2juaUSth8Pyn3Tq5Y5mJGME= +golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc= +golang.org/x/mod v0.11.0 h1:bUO06HqtnRcc/7l71XBe4WcqTZ+3AH1J59zWDDwLKgU= +golang.org/x/mod v0.11.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= +golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= +golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= +golang.org/x/net v0.9.0 h1:aWJ/m6xSmxWBx+V0XRHTlrYrPG56jKsLdTFmsSsCzOM= +golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= +golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU= +golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= +golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= +golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.11.0 h1:LAntKIrcmeSKERyiOh0XMV39LXS8IE9UL2yP7+f5ij4= +golang.org/x/text v0.11.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= +golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME= +gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.0 h1:hjy8E9ON/egN1tAYqKb61G10WtihqetD4sz2H+8nIeA= +gopkg.in/yaml.v3 v3.0.0/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/tools/tools.go b/tools/tools.go new file mode 100644 index 0000000..30fded6 --- /dev/null +++ b/tools/tools.go @@ -0,0 +1,18 @@ +// Copyright (c) HashiCorp, Inc. +// SPDX-License-Identifier: MPL-2.0 + +//go:build generate + +package tools + +import ( + // document generation + _ "github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs" +) + +// Format Terraform code for use in documentation. +// If you do not have Terraform installed, you can remove the formatting command, but it is suggested +// to ensure the documentation is formatted properly. +//go:generate terraform fmt -recursive ../examples/ +// Generate documentation. +//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-dir ..