From 40a0fcb4f95fa43cf3f7310a709d7adc6655ea72 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Tue, 14 Mar 2023 13:45:04 -0400 Subject: [PATCH 1/4] regen docs --- docs/data-sources/object.md | 4 --- docs/index.md | 58 ++++++++++++++++++++++++++++++++----- 2 files changed, 51 insertions(+), 11 deletions(-) diff --git a/docs/data-sources/object.md b/docs/data-sources/object.md index 5b9081a5..7c6fbb84 100644 --- a/docs/data-sources/object.md +++ b/docs/data-sources/object.md @@ -7,10 +7,6 @@ description: |- # Data Source `restapi_object` - - - - ## Schema ### Required diff --git a/docs/index.md b/docs/index.md index 5c9b4c78..e0eb8ee4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,55 @@ --- -page_title: "restapi Provider" -subcategory: "" +page_title: "OpenZiti restapi Provider" +subcategory: "Utility" description: |- - + Ultra-thin REST wrapper for the OpenZiti Management API forked from Mastercard/restapi + --- -# restapi Provider +# OpenZiti Managment 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 + +```go +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 @@ -19,8 +59,14 @@ description: |- ### Optional +- **cacerts_string** (String, Optional) OpenZiti Controller's CA bundle as PEM +- **cacerts_file** (String, Optional) file path to OpenZiti Controller's CA bundle as PEM +- **ziti_username** (String, Optional) When set, will use this username for OpenZiti password auth to the API. +- **ziti_password** (String, Optional) When set, will use this password for OpenZiti password auth to the API. - **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. +- **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. - **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. @@ -29,10 +75,7 @@ description: |- - **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. @@ -40,6 +83,7 @@ description: |- - **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. +- **password** (String, Optional) When set, will use this password 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. From 6a53343a7d1e5b5390558baa9ac23abdd382dc56 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Tue, 14 Mar 2023 13:47:50 -0400 Subject: [PATCH 2/4] recompose after gen --- docs/data-sources/object.md | 34 +++++++----- docs/index.md | 74 ++++++++++++------------- docs/resources/object.md | 54 +++++++++--------- examples/provider_with_ziti_password.tf | 26 +++++++++ 4 files changed, 111 insertions(+), 77 deletions(-) create mode 100644 examples/provider_with_ziti_password.tf diff --git a/docs/data-sources/object.md b/docs/data-sources/object.md index 7c6fbb84..43ce76dd 100644 --- a/docs/data-sources/object.md +++ b/docs/data-sources/object.md @@ -1,33 +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 ### 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. diff --git a/docs/index.md b/docs/index.md index e0eb8ee4..3b3eac65 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,11 @@ --- -page_title: "OpenZiti restapi Provider" +page_title: restapi Provider subcategory: "Utility" description: |- Ultra-thin REST wrapper for the OpenZiti Management API forked from Mastercard/restapi - --- -# OpenZiti Managment restapi Provider +# restapi Provider ## A Note about Terraform Provider Configuration @@ -14,7 +13,7 @@ You'll probably need to get the provider configuration from remote state provide ## Example Usage -```go +```terraform terraform { cloud {} required_providers { @@ -51,52 +50,53 @@ You must provide at least one of (`ziti_username` and `ziti_password`) or ((`cer 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 ### 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 -- **cacerts_string** (String, Optional) OpenZiti Controller's CA bundle as PEM -- **cacerts_file** (String, Optional) file path to OpenZiti Controller's CA bundle as PEM -- **ziti_username** (String, Optional) When set, will use this username for OpenZiti password auth to the API. -- **ziti_password** (String, Optional) When set, will use this password for OpenZiti password auth to the API. -- **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. -- **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. -- **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. -- **oauth_client_credentials** (Block List, Max: 1) Configuration for oauth client credential flow (see [below for nested schema](#nestedblock--oauth_client_credentials)) -- **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. -- **password** (String, Optional) When set, will use this password 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. ### 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 diff --git a/docs/resources/object.md b/docs/resources/object.md index a4b6a9fb..420407ae 100644 --- a/docs/resources/object.md +++ b/docs/resources/object.md @@ -1,47 +1,49 @@ --- +# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "restapi_object Resource - terraform-provider-restapi" subcategory: "" description: |- --- -# Resource `restapi_object` +# restapi_object (Resource) + ## Schema ### Required -- **data** (String, Required) Valid JSON object that this provider will manage with the API server. -- **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. +- `data` (String) Valid JSON object that this provider will manage with the API server. +- `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. ### Optional -- **create_method** (String, Optional) Defaults to `create_method` set on the provider. Allows per-resource override of `create_method` (see `create_method` provider config documentation) -- **create_path** (String, Optional) Defaults to `path`. The API path that represents where to CREATE (POST) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object if the data contains the `id_attribute`. -- **debug** (Boolean, Optional) Whether to emit verbose debug output while working with the API object on the server. -- **destroy_data** (String, Optional) Valid JSON object to pass during to destroy requests. -- **destroy_method** (String, Optional) Defaults to `destroy_method` set on the provider. Allows per-resource override of `destroy_method` (see `destroy_method` provider config documentation) -- **destroy_path** (String, Optional) Defaults to `path/{id}`. The API path that represents where to DESTROY (DELETE) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. -- **force_new** (List of String, Optional) Any changes to these values will result in recreating the resource instead of updating. -- **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) -- **object_id** (String, Optional) Defaults to the id learned by the provider during normal operations and `id_attribute`. Allows you to set the id manually. This is used in conjunction with the `*_path` attributes. -- **query_string** (String, Optional) Query string to be included in the path -- **read_method** (String, Optional) Defaults to `read_method` set on the provider. Allows per-resource override of `read_method` (see `read_method` provider config documentation) -- **read_path** (String, Optional) Defaults to `path/{id}`. The API path that represents where to READ (GET) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. -- **read_search** (Map of String, Optional) Custom search for `read_path`. This map will take `search_key`, `search_value`, `results_key` and `query_string` (see datasource config documentation) -- **update_data** (String, Optional) Valid JSON object to pass during to update requests. -- **update_method** (String, Optional) Defaults to `update_method` set on the provider. Allows per-resource override of `update_method` (see `update_method` provider config documentation) -- **update_path** (String, Optional) Defaults to `path/{id}`. The API path that represents where to UPDATE (PUT) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. - -### 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. -- **create_response** (String, Read-only) The raw body of the HTTP response returned when creating the object. +- `create_method` (String) Defaults to `create_method` set on the provider. Allows per-resource override of `create_method` (see `create_method` provider config documentation) +- `create_path` (String) Defaults to `path`. The API path that represents where to CREATE (POST) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object if the data contains the `id_attribute`. +- `debug` (Boolean) Whether to emit verbose debug output while working with the API object on the server. +- `destroy_data` (String) Valid JSON object to pass during to destroy requests. +- `destroy_method` (String) Defaults to `destroy_method` set on the provider. Allows per-resource override of `destroy_method` (see `destroy_method` provider config documentation) +- `destroy_path` (String) Defaults to `path/{id}`. The API path that represents where to DESTROY (DELETE) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. +- `force_new` (List of String) Any changes to these values will result in recreating the resource instead of updating. +- `id_attribute` (String) Defaults to `id_attribute` set on the provider. Allows per-resource override of `id_attribute` (see `id_attribute` provider config documentation) +- `object_id` (String) Defaults to the id learned by the provider during normal operations and `id_attribute`. Allows you to set the id manually. This is used in conjunction with the `*_path` attributes. +- `query_string` (String) Query string to be included in the path +- `read_method` (String) Defaults to `read_method` set on the provider. Allows per-resource override of `read_method` (see `read_method` provider config documentation) +- `read_path` (String) Defaults to `path/{id}`. The API path that represents where to READ (GET) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. +- `read_search` (Map of String) Custom search for `read_path`. This map will take `search_key`, `search_value`, `results_key` and `query_string` (see datasource config documentation) +- `update_data` (String) Valid JSON object to pass during to update requests. +- `update_method` (String) Defaults to `update_method` set on the provider. Allows per-resource override of `update_method` (see `update_method` provider config documentation) +- `update_path` (String) Defaults to `path/{id}`. The API path that represents where to UPDATE (PUT) objects of this type on the API server. The string `{id}` will be replaced with the terraform ID of the object. + +### Read-Only + +- `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. +- `create_response` (String) The raw body of the HTTP response returned when creating the object. +- `id` (String) The ID of this resource. diff --git a/examples/provider_with_ziti_password.tf b/examples/provider_with_ziti_password.tf new file mode 100644 index 00000000..231d7fcb --- /dev/null +++ b/examples/provider_with_ziti_password.tf @@ -0,0 +1,26 @@ +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"] +} \ No newline at end of file From f5aca3987ad67c6ee7ec28e3ab303588a7145205 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Tue, 14 Mar 2023 13:56:27 -0400 Subject: [PATCH 3/4] add template --- templates/index.md.tmpl | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 templates/index.md.tmpl diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl new file mode 100644 index 00000000..9b3e07ae --- /dev/null +++ b/templates/index.md.tmpl @@ -0,0 +1,26 @@ +--- +page_title: {{ .ProviderShortName }} Provider +subcategory: "Utility" +description: |- + Ultra-thin REST wrapper for the OpenZiti Management API forked from Mastercard/restapi +--- + +# {{ .ProviderShortName }} 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 + +{{ tffile "examples/provider_with_ziti_password.tf" }} + +## 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. + +{{ .SchemaMarkdown | trimspace }} From 78d3b97900200fd9b56863ea7c8211644e6dcb5d Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Tue, 14 Mar 2023 13:58:44 -0400 Subject: [PATCH 4/4] finish regen --- docs/index.md | 4 +++- templates/index.md.tmpl | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3b3eac65..b2af4ced 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,10 +44,12 @@ provider restapi { ## 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 `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. diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 9b3e07ae..f8cee8a9 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -17,10 +17,12 @@ You'll probably need to get the provider configuration from remote state provide ## 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 `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. {{ .SchemaMarkdown | trimspace }}