Skip to content

Commit f8ab80c

Browse files
qrkourierqrkourier
authored
Merge pull request #4 from qrkourier/regen-docs
Regen docs
2 parents 63a86d5 + 78d3b97 commit f8ab80c

File tree

5 files changed

+176
-72
lines changed

5 files changed

+176
-72
lines changed

‎docs/data-sources/object.md

+16-14
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,39 @@
11
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
23
page_title: "restapi_object Data Source - terraform-provider-restapi"
34
subcategory: ""
45
description: |-
56
67
---
78

8-
# Data Source `restapi_object`
9+
# restapi_object (Data Source)
910

1011

1112

1213

1314

15+
<!-- schema generated by tfplugindocs -->
1416
## Schema
1517

1618
### Required
1719

18-
- **path** (String, Required) The API path on top of the base URL set in the provider that represents objects of this type on the API server.
19-
- **search_key** (String, Required) When reading search results from the API, this key is used to identify the specific record to read. This should be a unique record such as 'name'. Similar to results_key, the value may be in the format of 'field/field/field' to search for data deeper in the returned object.
20-
- **search_value** (String, Required) The value of 'search_key' will be compared to this value to determine if the correct object was found. Example: if 'search_key' is 'name' and 'search_value' is 'foo', the record in the array returned by the API with name=foo will be used.
20+
- `path` (String) The API path on top of the base URL set in the provider that represents objects of this type on the API server.
21+
- `search_key` (String) When reading search results from the API, this key is used to identify the specific record to read. This should be a unique record such as 'name'. Similar to results_key, the value may be in the format of 'field/field/field' to search for data deeper in the returned object.
22+
- `search_value` (String) The value of 'search_key' will be compared to this value to determine if the correct object was found. Example: if 'search_key' is 'name' and 'search_value' is 'foo', the record in the array returned by the API with name=foo will be used.
2123

2224
### Optional
2325

24-
- **debug** (Boolean, Optional) Whether to emit verbose debug output while working with the API object on the server.
25-
- **id** (String, Optional) The ID of this resource.
26-
- **id_attribute** (String, Optional) Defaults to `id_attribute` set on the provider. Allows per-resource override of `id_attribute` (see `id_attribute` provider config documentation)
27-
- **query_string** (String, Optional) An optional query string to send when performing the search.
28-
- **read_query_string** (String, Optional) Defaults to `query_string` set on data source. This key allows setting a different or empty query string for reading the object.
29-
- **results_key** (String, Optional) When issuing a GET to the path, this JSON key is used to locate the results array. The format is 'field/field/field'. Example: 'results/values'. If omitted, it is assumed the results coming back are already an array and are to be used exactly as-is.
30-
- **search_path** (String, Optional) The API path on top of the base URL set in the provider that represents the location to search for objects of this type on the API server. If not set, defaults to the value of path.
26+
- `debug` (Boolean) Whether to emit verbose debug output while working with the API object on the server.
27+
- `id_attribute` (String) Defaults to `id_attribute` set on the provider. Allows per-resource override of `id_attribute` (see `id_attribute` provider config documentation)
28+
- `query_string` (String) An optional query string to send when performing the search.
29+
- `read_query_string` (String) Defaults to `query_string` set on data source. This key allows setting a different or empty query string for reading the object.
30+
- `results_key` (String) When issuing a GET to the path, this JSON key is used to locate the results array. The format is 'field/field/field'. Example: 'results/values'. If omitted, it is assumed the results coming back are already an array and are to be used exactly as-is.
31+
- `search_path` (String) The API path on top of the base URL set in the provider that represents the location to search for objects of this type on the API server. If not set, defaults to the value of path.
3132

32-
### Read-only
33+
### Read-Only
3334

34-
- **api_data** (Map of String, Read-only) After data from the API server is read, this map will include k/v pairs usable in other terraform resources as readable objects. Currently the value is the golang fmt package's representation of the value (simple primitives are set as expected, but complex types like arrays and maps contain golang formatting).
35-
- **api_response** (String, Read-only) The raw body of the HTTP response from the last read of the object.
35+
- `api_data` (Map of String) After data from the API server is read, this map will include k/v pairs usable in other terraform resources as readable objects. Currently the value is the golang fmt package's representation of the value (simple primitives are set as expected, but complex types like arrays and maps contain golang formatting).
36+
- `api_response` (String) The raw body of the HTTP response from the last read of the object.
37+
- `id` (String) The ID of this resource.
3638

3739

‎docs/index.md

+78-32
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,104 @@
11
---
2-
page_title: "restapi Provider"
3-
subcategory: ""
2+
page_title: restapi Provider
3+
subcategory: "Utility"
44
description: |-
5-
5+
Ultra-thin REST wrapper for the OpenZiti Management API forked from Mastercard/restapi
66
---
77

88
# restapi Provider
99

10+
## A Note about Terraform Provider Configuration
1011

12+
You'll probably need to get the provider configuration from remote state provided by another plan. This is because provider configuration occurs in an early phase of plan and apply, and so it's not possible to reliably obtain the configuration values from the same plan.
1113

14+
## Example Usage
1215

16+
```terraform
17+
terraform {
18+
cloud {}
19+
required_providers {
20+
restapi = {
21+
source = "qrkourier/restapi"
22+
version = "~> 1.23.0"
23+
}
24+
}
25+
}
1326
27+
data "terraform_remote_state" "controller_state" {
28+
backend = "remote"
29+
config = {
30+
organization = "acmeorg"
31+
workspaces = {
32+
name = "acmespace"
33+
}
34+
}
35+
}
36+
37+
provider restapi {
38+
uri = "https://${data.terraform_remote_state.controller_state.outputs.ziti_controller_mgmt_external_host}:443/edge/management/v1"
39+
cacerts_string = (data.terraform_remote_state.controller_state.outputs.ctrl_plane_cas).data["ctrl-plane-cas.crt"]
40+
ziti_username = (data.terraform_remote_state.controller_state.outputs.ziti_admin_password).data["admin-user"]
41+
ziti_password = (data.terraform_remote_state.controller_state.outputs.ziti_admin_password).data["admin-password"]
42+
}
43+
```
44+
45+
## OpenZiti Authentication
46+
47+
You must provide at least one of `cacerts_file` or `cacerts_string` with the OpenZiti Controller's CA bundle as PEM.
48+
49+
You must provide at least one of (`ziti_username` and `ziti_password`) or ((`cert_file` or `cert_string`) and (`key_file` or `key_string`)).
50+
51+
You must have an `updb` Authenticator to use password auth.
52+
53+
You must have a `cert` Authenticator and compatible Authentication Policy to use cert auth.
54+
55+
<!-- schema generated by tfplugindocs -->
1456
## Schema
1557

1658
### Required
1759

18-
- **uri** (String, Required) URI of the REST API endpoint. This serves as the base of all requests.
60+
- `uri` (String) URI of the REST API endpoint. This serves as the base of all requests.
1961

2062
### Optional
2163

22-
- **cert_file** (String, Optional) When set with the key_file parameter, the provider will load a client certificate as a file for mTLS authentication.
23-
- **cert_string** (String, Optional) When set with the key_string parameter, the provider will load a client certificate as a string for mTLS authentication.
24-
- **copy_keys** (List of String, Optional) When set, any PUT to the API for an object will copy these keys from the data the provider has gathered about the object. This is useful if internal API information must also be provided with updates, such as the revision of the object.
25-
- **create_method** (String, Optional) Defaults to `POST`. The HTTP method used to CREATE objects of this type on the API server.
26-
- **create_returns_object** (Boolean, Optional) Set this when the API returns the object created only on creation operations (POST). This is used by the provider to refresh internal data structures.
27-
- **debug** (Boolean, Optional) Enabling this will cause lots of debug information to be printed to STDOUT by the API client.
28-
- **destroy_method** (String, Optional) Defaults to `DELETE`. The HTTP method used to DELETE objects of this type on the API server.
29-
- **headers** (Map of String, Optional) A map of header names and values to set on all outbound requests. This is useful if you want to use a script via the 'external' provider or provide a pre-approved token or change Content-Type from `application/json`. If `username` and `password` are set and Authorization is one of the headers defined here, the BASIC auth credentials take precedence.
30-
- **id_attribute** (String, Optional) When set, this key will be used to operate on REST objects. For example, if the ID is set to 'name', changes to the API object will be to http://foo.com/bar/VALUE_OF_NAME. This value may also be a '/'-delimited path to the id attribute if it is multiple levels deep in the data (such as `attributes/id` in the case of an object `{ "attributes": { "id": 1234 }, "config": { "name": "foo", "something": "bar"}}`
31-
- **insecure** (Boolean, Optional) When using https, this disables TLS verification of the host.
32-
- **key_file** (String, Optional) When set with the cert_file parameter, the provider will load a client certificate as a file for mTLS authentication. Note that this mechanism simply delegates to golang's tls.LoadX509KeyPair which does not support passphrase protected private keys. The most robust security protections available to the key_file are simple file system permissions.
33-
- **key_string** (String, Optional) When set with the cert_string parameter, the provider will load a client certificate as a string for mTLS authentication. Note that this mechanism simply delegates to golang's tls.LoadX509KeyPair which does not support passphrase protected private keys. The most robust security protections available to the key_file are simple file system permissions.
34-
- **oauth_client_credentials** (Block List, Max: 1) Configuration for oauth client credential flow (see [below for nested schema](#nestedblock--oauth_client_credentials))
35-
- **password** (String, Optional) When set, will use this password for BASIC auth to the API.
36-
- **rate_limit** (Number, Optional) Set this to limit the number of requests per second made to the API.
37-
- **read_method** (String, Optional) Defaults to `GET`. The HTTP method used to READ objects of this type on the API server.
38-
- **test_path** (String, Optional) If set, the provider will issue a read_method request to this path after instantiation requiring a 200 OK response before proceeding. This is useful if your API provides a no-op endpoint that can signal if this provider is configured correctly. Response data will be ignored.
39-
- **timeout** (Number, Optional) When set, will cause requests taking longer than this time (in seconds) to be aborted.
40-
- **update_method** (String, Optional) Defaults to `PUT`. The HTTP method used to UPDATE objects of this type on the API server.
41-
- **use_cookies** (Boolean, Optional) Enable cookie jar to persist session.
42-
- **username** (String, Optional) When set, will use this username for BASIC auth to the API.
43-
- **write_returns_object** (Boolean, Optional) Set this when the API returns the object created on all write operations (POST, PUT). This is used by the provider to refresh internal data structures.
44-
- **xssi_prefix** (String, Optional) Trim the xssi prefix from response string, if present, before parsing.
64+
- `cacerts_file` (String) One or more CA certs to trust as a PEM bundle in a file.
65+
- `cacerts_string` (String) One or more CA certs to trust as a PEM bundle in a string.
66+
- `cert_file` (String) When set with the key_file parameter, the provider will load a client certificate as a file for mTLS authentication.
67+
- `cert_string` (String) When set with the key_string parameter, the provider will load a client certificate as a string for mTLS authentication.
68+
- `copy_keys` (List of String) When set, any PUT to the API for an object will copy these keys from the data the provider has gathered about the object. This is useful if internal API information must also be provided with updates, such as the revision of the object.
69+
- `create_method` (String) Defaults to `POST`. The HTTP method used to CREATE objects of this type on the API server.
70+
- `create_returns_object` (Boolean) Set this when the API returns the object created only on creation operations (POST). This is used by the provider to refresh internal data structures.
71+
- `debug` (Boolean) Enabling this will cause lots of debug information to be printed to STDOUT by the API client.
72+
- `destroy_method` (String) Defaults to `DELETE`. The HTTP method used to DELETE objects of this type on the API server.
73+
- `headers` (Map of String) A map of header names and values to set on all outbound requests. This is useful if you want to use a script via the 'external' provider or provide a pre-approved token or change Content-Type from `application/json`. If `username` and `password` are set and Authorization is one of the headers defined here, the BASIC auth credentials take precedence.
74+
- `id_attribute` (String) When set, this key will be used to operate on REST objects. For example, if the ID is set to 'name', changes to the API object will be to http://foo.com/bar/VALUE_OF_NAME. This value may also be a '/'-delimeted path to the id attribute if it is multple levels deep in the data (such as `attributes/id` in the case of an object `{ "attributes": { "id": 1234 }, "config": { "name": "foo", "something": "bar"}}`
75+
- `insecure` (Boolean) When using https, this disables TLS verification of the host.
76+
- `key_file` (String) When set with the cert_file parameter, the provider will load a client certificate as a file for mTLS authentication. Note that this mechanism simply delegates to golang's tls.LoadX509KeyPair which does not support passphrase protected private keys. The most robust security protections available to the key_file are simple file system permissions.
77+
- `key_string` (String) When set with the cert_string parameter, the provider will load a client certificate as a string for mTLS authentication. Note that this mechanism simply delegates to golang's tls.LoadX509KeyPair which does not support passphrase protected private keys. The most robust security protections available to the key_file are simple file system permissions.
78+
- `oauth_client_credentials` (Block List, Max: 1) Configuration for oauth client credential flow (see [below for nested schema](#nestedblock--oauth_client_credentials))
79+
- `password` (String) When set, will use this password for BASIC auth to the API.
80+
- `rate_limit` (Number) Set this to limit the number of requests per second made to the API.
81+
- `read_method` (String) Defaults to `GET`. The HTTP method used to READ objects of this type on the API server.
82+
- `test_path` (String) If set, the provider will issue a read_method request to this path after instantiation requiring a 200 OK response before proceeding. This is useful if your API provides a no-op endpoint that can signal if this provider is configured correctly. Response data will be ignored.
83+
- `timeout` (Number) When set, will cause requests taking longer than this time (in seconds) to be aborted.
84+
- `update_method` (String) Defaults to `PUT`. The HTTP method used to UPDATE objects of this type on the API server.
85+
- `use_cookies` (Boolean) Enable cookie jar to persist session.
86+
- `username` (String) When set, will use this username for BASIC auth to the API.
87+
- `write_returns_object` (Boolean) Set this when the API returns the object created on all write operations (POST, PUT). This is used by the provider to refresh internal data structures.
88+
- `xssi_prefix` (String) Trim the xssi prefix from response string, if present, before parsing.
89+
- `ziti_password` (String) When set, will use this password for Ziti auth to the API.
90+
- `ziti_username` (String) When set, will use this username for Ziti auth to the API.
4591

4692
<a id="nestedblock--oauth_client_credentials"></a>
4793
### Nested Schema for `oauth_client_credentials`
4894

4995
Required:
5096

51-
- **oauth_client_id** (String, Required) client id
52-
- **oauth_client_secret** (String, Required) client secret
53-
- **oauth_token_endpoint** (String, Required) oauth token endpoint
97+
- `oauth_client_id` (String) client id
98+
- `oauth_client_secret` (String) client secret
99+
- `oauth_token_endpoint` (String) oauth token endpoint
54100

55101
Optional:
56102

57-
- **endpoint_params** (Map of List of String, Optional) Additional key/values to pass to the underlying Oauth client library (as EndpointParams)
58-
- **oauth_scopes** (List of String, Optional) scopes
103+
- `endpoint_params` (Map of List of String) Additional key/values to pass to the underlying Oauth client library (as EndpointParams)
104+
- `oauth_scopes` (List of String) scopes

0 commit comments

Comments
 (0)