resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update API docs

This commit is contained in:
Seth Vargo 2017-04-06 23:59:58 -04:00
parent 0a595cb1e9
commit 7c7c626a37
No known key found for this signature in database
GPG Key ID: C921994F9C27E0FF
7 changed files with 351 additions and 308 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
website/source/docs/enterprise/api/configuration-versions.html.md
View File

@ -1,84 +0,0 @@
---
layout: "enterprise"
page_title: "Configuration Versions API"
sidebar_current: "docs-enterprise-api-configurations"
description: |-
A configuration version represents versions of Terraform configuration.
---
# Configuration Versions API
A configuration version represents versions of Terraform configuration.
Each set of changes to Terraform HCL files or the scripts
used in the files should have an associated configuration version.
When creating versions via the API, the variables attribute can be sent
to include the necessary variables for the Terraform configuration.
### Configuration Version Attributes
<table class="apidocs">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td><code>variables</code></td>
<td>A key/value map of Terraform variables to be associated
with the configuration version.</td>
<td>No</td>
</tr>
<tr>
<td><code>metadata</code></td>
<td>A hash of key value metadata pairs.</td>
<td>No</td>
</tr>
</table>
### Actions
The following actions can be performed on this resource.
<dl>
<dt>Create</dt>
<dd>POST /api/v1/terraform/configurations/:username/:name/versions</dd>
<dt>Upload progress</dt>
<dd>GET /api/v1/terraform/configurations/:username/:name/versions/progress/:token</dd>
</dl>
### Examples
#### Creating a configuration version
Creates a configuration with the provided attributes.
$ cat version.json
{
"version": {
"metadata": {
"git_branch": "master",
"remote_type": "atlas",
"remote_slug": "hashicorp/atlas"
},
"variables": {
"ami_id": "ami-123456",
"target_region": "us-east-1",
"consul_count": "5",
"consul_ami": "ami-123456"
}
}
}
$ curl %{ATLAS_URL}/api/v1/terraform/configurations/%{DEFAULT_USERNAME}/test/versions \
-X POST \
-H "X-Atlas-Token: $ATLAS_TOKEN" \
-H "Content-Type: application/json" \
-d @version.json
#### Retrieving the progress of an upload for a configuration version
Returns upload progress for the version.
$ curl %{ATLAS_URL}/api/v1/terraform/configurations/%{DEFAULT_USERNAME}/test/versions/progress/63fc7e18-3911-4853-8b17-7fdc28f158f2 \
-H "X-Atlas-Token: $ATLAS_TOKEN"

203
website/source/docs/enterprise/api/configurations.html.md
View File

@ -1,69 +1,174 @@
---
layout: "enterprise"
page_title: "Terraform Configuration API"
page_title: "Configurations - API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api-configurations"
description: |-
A configuration represents settings associated with a resource that runs Terraform with versions of Terraform configuration..
A configuration represents settings associated with a resource that runs
Terraform with versions of Terraform configuration.
---
# Terraform Configuration API
# Configuration API
A configuration represents settings associated with a resource that
runs Terraform with versions of Terraform configuration.
A configuration version represents versions of Terraform configuration. Each set
of changes to Terraform HCL files or the scripts used in the files should have
an associated configuration version.
Configurations have many [configuration versions](/docs/enterprise/api/configuration-versions.html)
which represent versions of Terraform configuration templates and other associated
configuration.
When creating versions via the API, the variables attribute can be sent to
include the necessary variables for the Terraform configuration. A configuration
represents settings associated with a resource that runs Terraform with versions
of Terraform configuration. Configurations have many configuration versions
which represent versions of Terraform configuration templates and other
associated configuration. Most operations take place on the configuration
version, not the configuration.
### Configuration Attributes
## Get Latest Configuration Version
<table class="apidocs">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td><code>name</code></td>
<td>The name of the configuration, used to identify it. It
has a maximum length of 50 characters and must contain only
letters, numbers, dashes, underscores or periods.</td>
<td>Yes</td>
</tr>
<tr>
<td><code>username</code></td>
<td>The username to assign the configuration to. You must be a member of the
organization and have the ability to create the resource.</td>
<td>Yes</td>
</tr>
</table>
This endpoint gets the latest configuration version.
### Actions
| Method | Path |
| :----- | :------------- |
| `GET` | `/terraform/configurations/:username/:name/versions/latest` |
The following actions can be performed on this resource.
### Parameters
<dl>
<dt>Show</dt>
<dd>GET /api/v1/terraform/configurations/:username/:name/versions/latest</dd>
<dt>Create</dt>
<dd>POST /api/v1/terraform/configurations</dd>
</dl>
- `:username` `(string: <required>)` - Specifies the username or organization
name under which to get the latest configuration version. This username must
already exist in the system, and the user must have permission to create new
configuration versions under this namespace. This is specified as part of the
URL.
### Examples
- `:name` `(string: <required>)` - Specifies the name of the configuration for
which to get the latest configuration. This is specified as part of the URL.
#### Creating a configuration
### Sample Request
Creates a configuration with the provided attributes.
```text
$ curl \
--header "X-Atlas-Token: ..." \
https://atlas.hashicorp.com/api/v1/terraform/configurations/my-organization/my-configuration/versions/latest
```
$ curl %{ATLAS_URL}/api/v1/terraform/configurations \
-X POST \
-H "X-Atlas-Token: $ATLAS_TOKEN" \
-d configuration[name]='test' \
-d configuration[username]='%{DEFAULT_USERNAME}'
### Sample Response
#### Retrieving a configuration
```json
{
"version": {
"version": 6,
"metadata": {
"foo": "bar"
},
"tf_vars": [],
"variables": {}
}
}
```
Returns the JSON representation of the latest configuration.
- `version` `(int)` - the unique version instance number.
$ curl %{ATLAS_URL}/api/v1/terraform/configurations/%{DEFAULT_USERNAME}/test/versions/latest \
-H "X-Atlas-Token: $ATLAS_TOKEN"
- `metadata` `(map<string|string>)` - a map of arbitrary metadata for this
version.
## Create Configuration Version
This endpoint creates a new configuration version.
| Method | Path |
| :----- | :------------- |
| `POST` | `/terraform/configurations/:username/:name/versions` |
### Parameters
- `:username` `(string: <required>)` - Specifies the username or organization
name under which to create this configuration version. This username must
already exist in the system, and the user must have permission to create new
configuration versions under this namespace. This is specified as part of the
URL.
- `:name` `(string: <required>)` - Specifies the name of the configuration for
which to create a new version. This is specified as part of the URL.
- `metadata` `(map<string|string>)` - Specifies an arbitrary hash of key-value
metadata pairs. This is specified as the payload as JSON.
- `variables` `(map<string|string>)` - Specifies a hash of key-value pairs that
will be made available as variables to this version.
### Sample Payload
```json
{
"version": {
"metadata": {
"git_branch": "master",
"remote_type": "atlas",
"remote_slug": "hashicorp/atlas"
},
"variables": {
"ami_id": "ami-123456",
"target_region": "us-east-1",
"consul_count": "5",
"consul_ami": "ami-123456"
}
}
}
```
### Sample Request
```text
$ curl \
--request POST \
--header "X-Atlas-Token: ..." \
--header "Content-Type: application/json" \
--data @payload.json \
https://atlas.hashicorp.com/api/v1/terraform/configurations/my-organization/my-configuration/versions
```
### Sample Response
```json
{
"version": 6,
"upload_path": "https://binstore.hashicorp.com/ddbd7db6-f96c-4633-beb6-22fe2d74eeed",
"token": "ddbd7db6-f96c-4633-beb6-22fe2d74eeed"
}
```
- `version` `(int)` - the unique version instance number. This is
auto-incrementing.
- `upload_path` `(string)` - the path where the archive should be uploaded via a
`POST` request.
- `token` `(string)` - the token that should be used when uploading the archive
to the `upload_path`.
## Check Upload Progress
This endpoint retrieves the progress for an upload of a configuration version.
| Method | Path |
| :----- | :------------- |
| `GET` | `/terraform/configurations/:username/:name/versions/progress/:token` |
### Parameters
- `:username` `(string: <required>)` - Specifies the username or organization to
read progress. This is specified as part of the URL.
- `:name` `(string: <required>)` - Specifies the name of the configuration for
to read progress. This is specified as part of the URL.
- `:token` `(string: <required>)` - Specifies the token that was returned from
the create option. **This is not an Atlas Token!** This is specified as part
of the URL.
### Sample Request
```text
$ curl \
--header "X-Atlas-Token: ..." \
https://atlas.hashicorp.com/api/v1/terraform/configurations/my-organization/my-configuration/versions/progress/ddbd7db6-f96c-4633-beb6-22fe2d74eeed
```
### Sample Response

96
website/source/docs/enterprise/api/environments.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Environments API"
page_title: "Environments - API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api-environments"
description: |-
Environments represent running infrastructure managed by Terraform.
@ -10,58 +10,60 @@ description: |-
Environments represent running infrastructure managed by Terraform.
Environments can also be connected to Consul clusters.
This documentation covers the environment interactions with Terraform.
Environments can also be connected to Consul clusters. This documentation covers
the environment interactions with Terraform.
### Environment Attributes
## Get Latest Configuration Version
<table class="apidocs">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td><code>variables</code></td>
<td>A key/value map of Terraform variables to be updated. Existing
variables will only be removed when their value is empty. Variables
of the same key will be overwritten.</td>
<td>Yes</td>
</tr>
</table>
<br>
<div class="alert-infos">
<div class="row alert-info">
Note: Only string variables can be updated via the API currently.
Creating or updating HCL variables is not yet supported.
</div>
</div>
This endpoint updates the Terraform variables for an environment. Due to the
sensitive nature of variables, they are not returned on success.
### Actions
| Method | Path |
| :----- | :------------- |
| `PUT` | `/environments/:username/:name/variables` |
The following actions can be performed on this resource.
### Parameters
<dl>
<dt>Update variables</dt>
<dd>PUT /api/v1/environments/:username/:name/variables</dd>
</dl>
- `:username` `(string: <required>)` - Specifies the username or organization
name under which to update variables. This username must already exist in the
system, and the user must have permission to create new configuration versions
under this namespace. This is specified as part of the URL.
### Examples
- `:name` `(string: <required>)` - Specifies the name of the environment for
which to update variables. This is specified as part of the URL.
#### Updating Terraform variables
- `variables` `(map<string|string>)` - Specifies a key-value map of Terraform
variables to be updated. Existing variables will only be removed when their
value is empty. Variables of the same key will be overwritten.
Updates the Terraform variables for an environment. Due to the sensitive nature
of variables, they will not returned on success.
-> Note: Only string variables can be updated via the API currently. Creating or updating HCL variables is not yet supported.
$ cat variables.json
{
"variables": {
"desired_capacity": "15",
"foo": "bar"
}
}
$ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/variables \
-X PUT \
-H 'Content-Type: application/json' \
-d @variables.json \
-H "X-Atlas-Token: $ATLAS_TOKEN"
### Sample Payload
```json
{
"variables": {
"desired_capacity": "15",
"foo": "bar"
}
}
```
### Sample Request
```text
$ curl \
--header "X-Atlas-Token: ..." \
--header "Content-Type: application/json" \
--request PUT \
--data @payload.json \
https://atlas.hashicorp.com/api/v1/environments/my-organization/my-environment/variables
```
### Sample Response
```text
```
(empty body)

82
website/source/docs/enterprise/api/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "API Documentation"
page_title: "API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api"
description: |-
Terraform Enterprise provides an API for a **subset of features**.
@ -8,20 +8,17 @@ description: |-
# Terraform Enterprise API Documentation
Terraform Enterprise provides an API for a **subset of features** available. For questions
or requests for new API features please email [support@hashicorp.com](mailto:support@hashicorp.com).
Terraform Enterprise provides an API for a **subset of features** available. For
questions or requests for new API features please email
[support@hashicorp.com](mailto:support@hashicorp.com).
## Available Endpoints Terraform Enterprise
- [Environments](/docs/enterprise/api/environments.html)
- [Runs](/docs/enterprise/api/runs.html)
- [States](/docs/enterprise/api/states.html)
The list of available endpoints are on the navigation.
## Authentication
All requests must be authenticated with an `X-Atlas-Token` HTTP header. This
token can be generated or revoked on the account tokens page.
Your token will have access to all resources your account has access to.
All requests must be authenticated with an `X-Atlas-Token` HTTP header. This
token can be generated or revoked on the account tokens page. Your token will
have access to all resources your account has access to.
For organization level resources, we recommend creating a separate user account
that can be added to the organization with the specific privilege level
@ -29,57 +26,34 @@ required.
## Response Codes
Standard HTTP response codes are returned. `404 Not Found`
codes are returned for all resources that a user does not have access to,
as well as for resources that don't exist. This is done to avoid a
potential attacker discovering the existence of a resource.
Standard HTTP response codes are returned. `404 Not Found` codes are returned
for all resources that a user does not have access to, as well as for resources
that don't exist. This is done to avoid a potential attacker discovering the
existence of a resource.
## Errors
Errors are returned in JSON format:
{
"errors": {
"name": [
"has already been taken"
]
}
}
```json
{
"errors": {
"name": [
"has already been taken"
]
}
}
```
## Versioning
The API currently resides under the `/v1` prefix. Future APIs
will increment this version leaving the `/v1` API intact, though
in the future certain features may be deprecated. In that case,
ample notice to migrate to the new API will be provided.
The API currently resides under the `/v1` prefix. Future APIs will increment
this version leaving the `/v1` API intact, though in the future certain features
may be deprecated. In that case, ample notice to migrate to the new API will be
provided.
## Content Type
The API accepts namespaced attributes in either
JSON or `application/x-www-form-urlencoded`. We recommend
using JSON, but for simplicity form style requests are supported.
Below is an equivalent example with both styles using `curl`.
### JSON Request Example
$ cat variables.json
{
"variables": {
"desired_capacity": "15",
"foo": "bar"
}
}
$ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/variables \
-X PUT \
-H 'Content-Type: application/json' \
-d @variables.json \
-H "X-Atlas-Token: $ATLAS_TOKEN"
### Form URL Encoded Example
$ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/variables \
-X PUT \
-d variables[foo]='bar' \
-d variables[desired_capacity]='15' \
-H "X-Atlas-Token: $ATLAS_TOKEN"
The API accepts namespaced attributes in either JSON or
`application/x-www-form-urlencoded`. We recommend using JSON, but for simplicity
form style requests are supported.

72
website/source/docs/enterprise/api/runs.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Runs API"
page_title: "Runs - API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api-runs"
description: |-
Runs in Terraform Enterprise represents a two step Terraform plan and a subsequent apply.
@ -8,44 +8,58 @@ description: |-
# Runs API
Runs in Terraform Enterprise represents a two step Terraform plan and a subsequent apply.
Runs in Terraform Enterprise represents a two step Terraform plan and a
subsequent apply.
Runs are queued under [environments](/docs/enterprise/api/environments.html)
and require a two-step confirmation workflow. However, environments
can be configured to auto-apply to avoid this.
### Run Attributes
## Queue Run
<table class="apidocs">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td><code>destroy</code></td>
<td>If set to <code>true</code>, this run will be a destroy plan.</td>
<td>No</td>
</tr>
</table>
Starts a new run (plan) in the environment. Requires a configuration version to
be present on the environment to succeed, but will otherwise 404.
### Actions
| Method | Path |
| :----- | :------------- |
| `POST` | `/environments/:username/:name/plan` |
The following actions can be performed on this resource.
### Parameters
<dl>
<dt>Queue a run</dt>
<dd>POST /api/v1/environments/:username/:name/plan</dd>
</dl>
- `:username` `(string: <required>)` - Specifies the username or organization
name under which to get the latest configuration version. This username must
already exist in the system, and the user must have permission to create new
configuration versions under this namespace. This is specified as part of the
URL.
### Examples
- `:name` `(string: <required>)` - Specifies the name of the configuration for
which to get the latest configuration. This is specified as part of the URL.
#### Queueing a new run
- `destroy` `(bool: false)` - Specifies if the plan should be a destroy plan.
Starts a new run (plan) in the environment. Requires a configuration
version to be present on the environment to succeed, but will otherwise 404.
### Sample Payload
$ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/plan \
-X POST \
-d "" \
-H "X-Atlas-Token: $ATLAS_TOKEN"
```json
{
"destroy": false
}
```
### Sample Request
```text
$ curl \
--request POST \
--header "X-Atlas-Token: ..." \
--header "Content-Type: application/json" \
--data @payload.json \
https://atlas.hashicorp.com/api/v1/environments/my-organization/my-environment/plan
```
### Sample Response
```json
{
"success": true
}
```

79
website/source/docs/enterprise/api/states.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "State API"
page_title: "State - API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api-states"
description: |-
State represents the status of your infrastructure at the last time Terraform was run.
@ -8,45 +8,60 @@ description: |-
# State API
State represents the status of your infrastructure at the last time Terraform was run. States can be pushed to Terraform Enterprise from Terraform's CLI after an apply is done locally, or state is automatically stored if the apply is done in Terraform Enterprise.
State represents the status of your infrastructure at the last time Terraform
was run. States can be pushed to Terraform Enterprise from Terraform's CLI after
an apply is done locally, or state is automatically stored if the apply is done
in Terraform Enterprise.
### State Attributes
## List of States
<table class="apidocs">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td><code>username</code></td>
<td>If supplied, only return states belonging to the organization with this username.</td>
<td>No</td>
</tr>
</table>
This endpoint gets a list of states accessible to the user corresponding to the
provided token.
### Actions
| Method | Path |
| :----- | :------------- |
| `GET` | `/terraform/state` |
The following actions can be performed on this resource.
### Parameters
<dl>
<dt>Get a list of states accessible to a user</dt>
<dd>GET /api/v1/terraform/state</dd>
</dl>
- `?username` `(string: "")` - Specifies the organization/username to filter
states
### Examples
- `?page` `(int: 1)` - Specifies the pagination, which defaults to page 1.
#### Getting a list of Terraform states
### Sample Requests
$ curl %{ATLAS_URL}/api/v1/terraform/state \
-H "X-Atlas-Token: $ATLAS_TOKEN"
```text
$ curl \
--header "X-Atlas-Token: ..." \
https://atlas.hashicorp.com/api/v1/terraform/state
```
#### Getting a list of Terraform states for an organization
```text
$ curl \
--header "X-Atlas-Token: ..." \
https://atlas.hashicorp.com/api/v1/terraform/state?username=acme
```
$ curl %{ATLAS_URL}/api/v1/terraform/state?username=acme_inc \
-H "X-Atlas-Token: $ATLAS_TOKEN"
### Sample Response
#### Getting second page of list of Terraform states
$ curl %{ATLAS_URL}/api/v1/terraform/state?page=2 \
-H "X-Atlas-Token: $ATLAS_TOKEN"
```json
{
"states": [
{
"updated_at": "2017-02-03T19:52:37.693Z",
"environment": {
"username": "my-organization",
"name": "docs-demo-one"
}
},
{
"updated_at": "2017-04-06T15:48:49.677Z",
"environment": {
"username": "my-organization",
"name": "docs-demo-two"
}
}
]
}
```

43
website/source/docs/enterprise/api/users.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Users API"
page_title: "Users - API - Terraform Enterprise"
sidebar_current: "docs-enterprise-api-users"
description: |-
Users are both users and organizations in Terraform Enterprise. They are the parent resource of all resources.
@ -12,21 +12,38 @@ Users are both users and organizations in Terraform Enterprise. They are the
parent resource of all resources.
Currently, only the retrieval of users is available on the API. Additionally,
only Vagrant box resources will be listed. Boxes will
be returned based on permissions over the organization, or user.
only Vagrant box resources will be listed. Boxes will be returned based on
permissions over the organization, or user.
### Actions
## Read User
The following actions can be performed on this resource.
This endpoint retrieves information about a single user.
<dl>
<dt>Show</dt>
<dd>GET /api/v1/user/:username</dd>
</dl>
| Method | Path |
| :----- | :------------- |
| `GET` | `/user/:username` |
### Examples
### Parameters
#### Retrieve a user
- `:username` `(string: <required>)` - Specifies the username to search. This is
specified as part of the URL.
$ curl %{ATLAS_URL}/api/v1/user/%{DEFAULT_USERNAME} \
-H "X-Atlas-Token: $ATLAS_TOKEN"
### Sample Request
```text
$ curl \
--header "X-Atlas-Token: ..." \
https://atlas.hashicorp.com/api/v1/user/my-user
```
### Sample Response
```json
{
"username": "sally-seashell",
"avatar_url": "https://www.gravatar.com/avatar/...",
"profile_html": "Sally is...",
"profile_markdown": "Sally is...",
"boxes": []
}
```