Add documentation for upcoming Terraform Cloud secret engine (#10823)

* add side navigation for Terraform Cloud Secret Engine * terraform cloud engine docs * add api-docs for terraform cloud secret engine * fix some typos and improve wording, now with less management * fix capitalization * change text->shell-session * clarify rotating user roles returns an error
hashicorp · Feb 22, 2021 · 8c8d0a0 · 8c8d0a0
1 parent 54f3a58
commit 8c8d0a0
Show file tree

Hide file tree

Showing 4 changed files with 480 additions and 0 deletions.
diff --git a/website/content/api-docs/secret/terraform.mdx b/website/content/api-docs/secret/terraform.mdx
@@ -0,0 +1,311 @@
+---
+layout: api
+page_title: Terraform Cloud Secret Backend - HTTP API
+sidebar_title: Terraform Cloud
+description: This is the API documentation for the Vault Terraform Cloud secret backend.
+---
+
+# Terraform Cloud Secret Backend HTTP API
+
+This is the API documentation for the Vault Terraform Cloud secret backend. For general
+information about the usage and operation of the Terraform Cloud backend, please see the
+[Vault Terraform Cloud backend documentation](/docs/secrets/terraform).
+
+This documentation assumes the Terraform Cloud backend is mounted at the `/terraform` path
+in Vault. Since it is possible to mount secret backends at any location, please
+update your API calls accordingly.
+
+## Configure Access
+
+This endpoint configures the access information for Terraform Cloud. This access
+information is used so that Vault can communicate with Terraform Cloud and generate
+Terraform Cloud tokens.
+
+| Method | Path                   |
+| :----- | :--------------------- |
+| `POST` | `/terraform/config` |
+
+### Parameters
+
+- `address` `(string: "")` – Specifies the address of the Terraform Cloud
+  server, if using Terraform Enterprise, provided as `"protocol://host:port"`.
+  The default is `https://app.terraform.io` for Terraform Cloud.
+
+- `token` `(string: "")` – Specifies the Terraform Cloud authentication token to
+  use. This token must have the needed permissions to manage all Organization,
+  Team, and User tokens desired for this mount.
+
+
+### Sample Payload
+
+```json
+{
+  "address": "https://app.terraform.io",
+  "token": "glhf..."
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --request POST \
+    --header "X-Vault-Token: ..." \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/terraform/config
+```
+
+## Read Access Configuration
+
+This endpoint queries for information about the Terraform Cloud connection.
+
+| Method | Path                   |
+| :----- | :--------------------- |
+| `GET`  | `/terraform/config` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/terraform/config
+```
+
+### Sample Response
+
+```json
+  "data": {
+    "address": "https://app.terraform.io",
+    "base_path": "/api/v2/"
+  }
+```
+
+
+## Create/Update Role
+
+This endpoint creates or updates the Terraform Cloud role definition in Vault.
+If the role does not exist, it will be created. If the role already exists, it
+will receive updated attributes. 
+
+Terraform Cloud offers three distinct types of API tokens with varying level of
+access: Organizations, Teams, and Users. A Vault Role can manage a single type
+of API token at a time, determined by how it is configured: 
+
+- To manage an Organization API token, provide the organization
+name with the `organization` parameter
+- To manage a Team API token, provide the `team_id` parameter
+- To manage a User API token, provide a `user_id` parameter
+
+~> **Special Note:** both Organizations and Teams can only have a single active API
+token at any given time. Generating a new token for a team or organization will
+effectively revoke any existing tokens, regardless if those tokens were
+originally created by Vault. As such, requesting an Organization or Team token
+from Vault will return the same token indefinitely until that token is rotated
+with the `/rotate-role` endpoint.
+
+Please see the [Terraform Cloud API
+Token documentation for more
+information](https://www.terraform.io/docs/cloud/users-teams-organizations/api-tokens.html).
+
+
+| Method | Path                |
+| :----- | :------------------ |
+| `POST` | `/terraform/role/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name for the Vault role. This is
+  part of the request URL.
+
+- `organization` `(string: "")` – Organization name to manage the single API
+  token. Organizations can only have a single active API token at any given
+  time. Conflicts with `user_id`. 
+
+- `team_id` `(string: "")` – Team ID to manage the single API token. Teams can
+  only have a single active API token at any given time. Conflicts with
+  `user_id`.
+
+- `user_id` `(string: "")` – User ID to manage dynamic tokens. Conflicts with
+  `organization` and `team_id`.
+
+- `ttl` `(duration: "")` – Specifies the TTL for this role. This is provided
+  as a string duration with a time suffix like `"30s"` or `"1h"` or as seconds. If not
+  provided, the default Vault TTL is used. Only applies to User API tokens.
+
+- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. This is provided
+  as a string duration with a time suffix like `"30s"` or `"1h"` or as seconds. If not
+  provided, the default Vault Max TTL is used. Only applies to User API tokens.
+
+
+### Sample Payload
+
+To create a Vault role to manage a Terraform Cloud User tokens
+
+```json
+{
+  "user_id": "user-glhf1234",
+  "ttl":"1h",
+  "max_ttl":"24h",
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --request POST \
+    --header "X-Vault-Token: ..." \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/terraform/role/tfuser
+```
+
+## Read Role
+
+This endpoint queries for information about a Terraform Cloud role with the given name.
+If no role exists with that name, a 404 is returned.
+
+| Method | Path                |
+| :----- | :------------------ |
+| `GET`  | `/terraform/role/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the role to query. This
+  is part of the request URL.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/terraform/role/tfuser
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "max_ttl": 86400,
+    "name": "tfuser",
+    "ttl": 3600,
+    "user_id": "user-glhf1234"
+  },
+}
+```
+
+## List Roles
+
+This endpoint lists all existing roles in the backend.
+
+| Method | Path                    |
+| :----- | :---------------------- |
+| `LIST` | `/terraform/role`           |
+| `GET`  | `/terraform/role?list=true` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request LIST \
+    http://127.0.0.1:8200/v1/terraform/role
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "keys": ["tfuser"]
+  }
+}
+```
+
+## Delete Role
+
+This endpoint deletes a Terraform Cloud role with the given name. Even if the role does
+not exist, this endpoint will still return a successful response.
+
+| Method   | Path                |
+| :------- | :------------------ |
+| `DELETE` | `/terraform/role/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the role to delete. This
+  is part of the request URL.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --request DELETE \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/terraform/role/tfuser
+```
+
+## Rotate Role
+
+This endpoint rotates the credentials for a Terraform Cloud role that manages an
+Organization or Team. This endpoint is only valid for those roles; attempting to
+rotate a role that manages user tokens will result in an error.
+
+
+| Method   | Path                |
+| :------- | :------------------ |
+| `POST` | `/terraform/rotate-role/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the role to rotate. This
+  is part of the request URL.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --request POST \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/terraform/rotate-role/testing
+```
+
+## Generate Credential
+
+This endpoint returns a Terraform Cloud token based on the given role
+definition. For Organization and Team roles, the same API token is returned
+until the token is rotated with `rotate-role`. For User roles, a new token is
+generated with each request.
+
+| Method | Path                 |
+| :----- | :------------------- |
+| `GET`  | `/terraform/creds/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of an existing role against
+  which to create this Terraform Cloud token. This is part of the request URL.
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/terraform/creds/example
+```
+
+### Sample Response
+
+```json
+{
+  "request_id": "71629848-778d-f9ae-c396-0b02fae2adda",
+  "lease_id": "terraform/creds/tfuser/dWa2E5aiIX7jJfyMqPm1fSPr",
+  "lease_duration": 60,
+  "renewable": true,
+  "data": {
+    "token": "<example-token>",
+    "token_id": "at-example"
+  },
+  "warnings": null
+}
+```