forked from Mastercard/terraform-provider-restapi
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4 from qrkourier/regen-docs
Regen docs
- Loading branch information
Showing
5 changed files
with
176 additions
and
72 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,37 +1,39 @@ | ||
| --- | ||
| # generated by https://github.com/hashicorp/terraform-plugin-docs | ||
| page_title: "restapi_object Data Source - terraform-provider-restapi" | ||
| subcategory: "" | ||
| description: |- | ||
| --- | ||
|
|
||
| # Data Source `restapi_object` | ||
| # restapi_object (Data Source) | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| <!-- schema generated by tfplugindocs --> | ||
| ## Schema | ||
|
|
||
| ### Required | ||
|
|
||
| - **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. | ||
| - **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. | ||
| - **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. | ||
| - `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. | ||
| - `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. | ||
| - `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. | ||
|
|
||
| ### Optional | ||
|
|
||
| - **debug** (Boolean, Optional) Whether to emit verbose debug output while working with the API object on the server. | ||
| - **id** (String, Optional) The ID of this resource. | ||
| - **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) | ||
| - **query_string** (String, Optional) An optional query string to send when performing the search. | ||
| - **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. | ||
| - **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. | ||
| - **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. | ||
| - `debug` (Boolean) Whether to emit verbose debug output while working with the API object on the server. | ||
| - `id_attribute` (String) Defaults to `id_attribute` set on the provider. Allows per-resource override of `id_attribute` (see `id_attribute` provider config documentation) | ||
| - `query_string` (String) An optional query string to send when performing the search. | ||
| - `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. | ||
| - `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. | ||
| - `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. | ||
|
|
||
| ### Read-only | ||
| ### Read-Only | ||
|
|
||
| - **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). | ||
| - **api_response** (String, Read-only) The raw body of the HTTP response from the last read of the object. | ||
| - `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). | ||
| - `api_response` (String) The raw body of the HTTP response from the last read of the object. | ||
| - `id` (String) The ID of this resource. | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,104 @@ | ||
| --- | ||
| page_title: "restapi Provider" | ||
| subcategory: "" | ||
| page_title: restapi Provider | ||
| subcategory: "Utility" | ||
| description: |- | ||
| Ultra-thin REST wrapper for the OpenZiti Management API forked from Mastercard/restapi | ||
| --- | ||
|
|
||
| # restapi Provider | ||
|
|
||
| ## A Note about Terraform Provider Configuration | ||
|
|
||
| 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. | ||
|
|
||
| ## Example Usage | ||
|
|
||
| ```terraform | ||
| terraform { | ||
| cloud {} | ||
| required_providers { | ||
| restapi = { | ||
| source = "qrkourier/restapi" | ||
| version = "~> 1.23.0" | ||
| } | ||
| } | ||
| } | ||
| data "terraform_remote_state" "controller_state" { | ||
| backend = "remote" | ||
| config = { | ||
| organization = "acmeorg" | ||
| workspaces = { | ||
| name = "acmespace" | ||
| } | ||
| } | ||
| } | ||
| provider restapi { | ||
| uri = "https://${data.terraform_remote_state.controller_state.outputs.ziti_controller_mgmt_external_host}:443/edge/management/v1" | ||
| cacerts_string = (data.terraform_remote_state.controller_state.outputs.ctrl_plane_cas).data["ctrl-plane-cas.crt"] | ||
| ziti_username = (data.terraform_remote_state.controller_state.outputs.ziti_admin_password).data["admin-user"] | ||
| ziti_password = (data.terraform_remote_state.controller_state.outputs.ziti_admin_password).data["admin-password"] | ||
| } | ||
| ``` | ||
|
|
||
| ## OpenZiti Authentication | ||
|
|
||
| You must provide at least one of `cacerts_file` or `cacerts_string` with the OpenZiti Controller's CA bundle as PEM. | ||
|
|
||
| You must provide at least one of (`ziti_username` and `ziti_password`) or ((`cert_file` or `cert_string`) and (`key_file` or `key_string`)). | ||
|
|
||
| You must have an `updb` Authenticator to use password auth. | ||
|
|
||
| You must have a `cert` Authenticator and compatible Authentication Policy to use cert auth. | ||
|
|
||
| <!-- schema generated by tfplugindocs --> | ||
| ## Schema | ||
|
|
||
| ### Required | ||
|
|
||
| - **uri** (String, Required) URI of the REST API endpoint. This serves as the base of all requests. | ||
| - `uri` (String) URI of the REST API endpoint. This serves as the base of all requests. | ||
|
|
||
| ### Optional | ||
|
|
||
| - **cert_file** (String, Optional) When set with the key_file parameter, the provider will load a client certificate as a file for mTLS authentication. | ||
| - **cert_string** (String, Optional) When set with the key_string parameter, the provider will load a client certificate as a string for mTLS authentication. | ||
| - **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. | ||
| - **create_method** (String, Optional) Defaults to `POST`. The HTTP method used to CREATE objects of this type on the API server. | ||
| - **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. | ||
| - **debug** (Boolean, Optional) Enabling this will cause lots of debug information to be printed to STDOUT by the API client. | ||
| - **destroy_method** (String, Optional) Defaults to `DELETE`. The HTTP method used to DELETE objects of this type on the API server. | ||
| - **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. | ||
| - **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"}}` | ||
| - **insecure** (Boolean, Optional) When using https, this disables TLS verification of the host. | ||
| - **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. | ||
| - **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. | ||
| - **oauth_client_credentials** (Block List, Max: 1) Configuration for oauth client credential flow (see [below for nested schema](#nestedblock--oauth_client_credentials)) | ||
| - **password** (String, Optional) When set, will use this password for BASIC auth to the API. | ||
| - **rate_limit** (Number, Optional) Set this to limit the number of requests per second made to the API. | ||
| - **read_method** (String, Optional) Defaults to `GET`. The HTTP method used to READ objects of this type on the API server. | ||
| - **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. | ||
| - **timeout** (Number, Optional) When set, will cause requests taking longer than this time (in seconds) to be aborted. | ||
| - **update_method** (String, Optional) Defaults to `PUT`. The HTTP method used to UPDATE objects of this type on the API server. | ||
| - **use_cookies** (Boolean, Optional) Enable cookie jar to persist session. | ||
| - **username** (String, Optional) When set, will use this username for BASIC auth to the API. | ||
| - **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. | ||
| - **xssi_prefix** (String, Optional) Trim the xssi prefix from response string, if present, before parsing. | ||
| - `cacerts_file` (String) One or more CA certs to trust as a PEM bundle in a file. | ||
| - `cacerts_string` (String) One or more CA certs to trust as a PEM bundle in a string. | ||
| - `cert_file` (String) When set with the key_file parameter, the provider will load a client certificate as a file for mTLS authentication. | ||
| - `cert_string` (String) When set with the key_string parameter, the provider will load a client certificate as a string for mTLS authentication. | ||
| - `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. | ||
| - `create_method` (String) Defaults to `POST`. The HTTP method used to CREATE objects of this type on the API server. | ||
| - `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. | ||
| - `debug` (Boolean) Enabling this will cause lots of debug information to be printed to STDOUT by the API client. | ||
| - `destroy_method` (String) Defaults to `DELETE`. The HTTP method used to DELETE objects of this type on the API server. | ||
| - `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. | ||
| - `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"}}` | ||
| - `insecure` (Boolean) When using https, this disables TLS verification of the host. | ||
| - `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. | ||
| - `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. | ||
| - `oauth_client_credentials` (Block List, Max: 1) Configuration for oauth client credential flow (see [below for nested schema](#nestedblock--oauth_client_credentials)) | ||
| - `password` (String) When set, will use this password for BASIC auth to the API. | ||
| - `rate_limit` (Number) Set this to limit the number of requests per second made to the API. | ||
| - `read_method` (String) Defaults to `GET`. The HTTP method used to READ objects of this type on the API server. | ||
| - `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. | ||
| - `timeout` (Number) When set, will cause requests taking longer than this time (in seconds) to be aborted. | ||
| - `update_method` (String) Defaults to `PUT`. The HTTP method used to UPDATE objects of this type on the API server. | ||
| - `use_cookies` (Boolean) Enable cookie jar to persist session. | ||
| - `username` (String) When set, will use this username for BASIC auth to the API. | ||
| - `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. | ||
| - `xssi_prefix` (String) Trim the xssi prefix from response string, if present, before parsing. | ||
| - `ziti_password` (String) When set, will use this password for Ziti auth to the API. | ||
| - `ziti_username` (String) When set, will use this username for Ziti auth to the API. | ||
|
|
||
| <a id="nestedblock--oauth_client_credentials"></a> | ||
| ### Nested Schema for `oauth_client_credentials` | ||
|
|
||
| Required: | ||
|
|
||
| - **oauth_client_id** (String, Required) client id | ||
| - **oauth_client_secret** (String, Required) client secret | ||
| - **oauth_token_endpoint** (String, Required) oauth token endpoint | ||
| - `oauth_client_id` (String) client id | ||
| - `oauth_client_secret` (String) client secret | ||
| - `oauth_token_endpoint` (String) oauth token endpoint | ||
|
|
||
| Optional: | ||
|
|
||
| - **endpoint_params** (Map of List of String, Optional) Additional key/values to pass to the underlying Oauth client library (as EndpointParams) | ||
| - **oauth_scopes** (List of String, Optional) scopes | ||
| - `endpoint_params` (Map of List of String) Additional key/values to pass to the underlying Oauth client library (as EndpointParams) | ||
| - `oauth_scopes` (List of String) scopes |
Oops, something went wrong.