From 936c423166b7028ff7b2ffe7a33e95fbca144ec7 Mon Sep 17 00:00:00 2001 From: "Ariel Abuel (NCS)" Date: Tue, 18 Jan 2022 10:32:44 +0800 Subject: [PATCH] Updated README and data source documentation --- README.md | 230 +++++-------------- config/data_source_configuration_workbook.go | 12 +- docs/data-sources/ini.md | 3 +- docs/data-sources/restapi_get.md | 22 +- docs/index.md | 24 +- 5 files changed, 110 insertions(+), 181 deletions(-) diff --git a/README.md b/README.md index 6195ec5..6935445 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,85 @@ -# Terraform Configuration Workbook Provider +config Provider +================== -This is the repository for the Terraform Configuration Workbook Provider which you can use to parse a CSV file or an Excel file into a list of maps. +- Website: https://registry.terraform.io +- Documentation: https://registry.terraform.io/providers/alabuel/config/latest/docs -You can also provide a schema to set the key names of each map for your configurations. +Introduction +------------ -# Using the Provider +This is a Terraform provider for the following: +- Read Excel file as a data source +- Read INI configuration file as a data source +- Get response from API servers as a data source -## Configuring the Provider +Requirements +------------ -```hcl -terraform { - required_providers { - config = { - source = "alabuel/config" - version = "0.1.1" - } - } -} +* [Terraform 0.13 or above](https://www.terraform.io/downloads.html) +* [Go Language 1.16.4 or above](https://golang.org/dl) -provider "config" {} -``` -### Example - Using a CSV +Using the Provider +------------ -```hcl -data "config_workbook "csv" { - csv = <<-EOT - configuration_item,attr1,attr2,attr3 - vpc,my_vpc,1,"10.0.0.0/16" - EOT -} +See the [config documentation](https://registry.terraform.io/providers/alabuel/config/latest/docs) -# reading from a csv file -data "config_workbook" "csv_file" { - csv = file("filename.csv") -} -``` +See config data source examples [here](examples/README.md) -### Example - Using an Excel file +## Execution +These are the Terraform commands that can be used for the config plugin: +* `terraform init` - The init command is used to initialize a working directory containing Terraform configuration files. +* `terraform plan` - Plan command shows plan for resources like how many resources will be provisioned and how many will be destroyed. +* `terraform apply` - apply is responsible to execute actual calls to provision resources. +* `terraform refresh` - By using the refresh command you can check the status of the request. +* `terraform show` - show will set a console output for resource configuration and request status. +* `terraform destroy` - destroy command will destroy all the resources present in terraform configuration file. -```hcl -data "config_workbook" "excel" { - excel = "filename.xlsx" - worksheet = "Sheet1" -} -``` +Navigate to the location where `main.tf` and binary are placed and use the above commands as needed. -### Example - Using a CSV with a schema +Upgrading the provider +---------------------- -```hcl -data "config_workbook" "csv_using_yaml" { - csv = file("filename.csv") - schema = file("schema.yaml") -} +The config provider doesn't upgrade automatically once you've started using it. After a new release you can run -data "config_workbook" "csv_using_json" { - csv = file("filename.csv") - schema = file("schema.json") -} +```bash +terraform init -upgrade ``` -### Example - Using an Excel with a schema -```hcl -data "config_workbook" "excel_using_yaml" { - excel = "filename.xlsx" - worksheet = "Sheet1" - schema = file("schema.yaml") -} +to upgrade to the latest stable version of the config provider. See the [Terraform website](https://www.terraform.io/docs/configuration/providers.html#provider-versions) +for more information on provider upgrades, and how to set version constraints on your provider. -data "config_workbook" "excel_using_json" { - excel = "filename.xlsx" - worksheet = "Sheet1" - schema = file("schema.json") -} -``` - -### Schema format - Example 1 -```yaml -# you can set the attribute types -schema_config: - vpc: - attr1: - name: name - type: string - attr2: - name: create - type: bool - attr3: - name: cidr_block - type: string - -# this format assumes that all attributes are of "string" types -schema_config: - vpc: - attr1: name - attr2: create - attr3: cidr_block -``` +### A sample main.tf is as follows -### Schema format - Example 3 -```json -// you can set the attribute types -{ - "schema_config": { - "vpc": { - "attr1": { - "name": "name", - "type": "string" - }, - "attr2": { - "name": "create", - "type": "bool" - }, - "attr3": { - "name": "cidr_block", - "type": "string" - } - } - } -} - -// this format assumes that all attributes are of "string" types -{ - "schema_config": { - "vpc": { - "attr1": "name", - "attr2": "create", - "attr3": "cidr_block" +```hcl +terraform { + required_providers { + config = { + source = "alabuel/config" + version = "0.2.4" } } } -``` -## Valid attribute types -- string -- number/numeric -- bool/boolean -- map -- list - -## Attribute naming convention -1. Should have a column name of "`configuration_item`". This will identify the item you need to configure -2. Attributes starting with "`attr`" will be substituted with the correct attribute name using the provided schema. -3. You can preset the type of the attribute using prefixes. - - `s_` or `string_` - - `n_` or `num_` or `number_` or `numeric_` - - `b_` or `bool_` or `boolean` - - `m_` or `map_` - - `l_` or `list_` - - `t_` or `tag_` - Attributes without prefixes will be treated as string. Boolean values are (1,yes,true = True; 0,no,false = False) - -## Example 1 -|configuration_item|attr1|attr2|attr3| -|------------------|-----|-----|-----| -|vpc|my_vpc|1|"10.0.0.0/16"| - -## Example 2 -|configuration_item|name|b_create|cidr_block| -|------------------|-----|-----|-----| -|vpc|my_vpc|1|"10.0.0.0/16"| - -### Example 1 and 2 results: -```json -{ - "vpc": [ - { - "name": "my_vpc", - "create": true, - "cidr_block": "10.0.0.0/16" - } - ] +provider "config" {} + +# reading Excel worksheet +# ------------------------ +data "config_workbook" "excel" { + excel = "filename.xlsx" + worksheet = "Sheet1" } -``` -## Example 3 -|configuration_item|attr1|attr2|attr3|t_environment|t_alias|t_purpose| -|------------------|-----|-----|-----|-------------|-------|---------| -|vpc|my_vpc|1|"10.0.0.0/16"|dev|vpc1|"application vpc"| - -### Example 3 results will be: -```json -{ - "vpc": [ - { - "name": "my_vpc", - "create": true, - "cidr_block": "10.0.0.0/16", - "tags": { - "Environment": "dev", - "Alias": "vpc1", - "Purpose": "application vpc" - } - } - ] +# getting api response +# ----------------------- +data "config_restapi_get "apidata" { + uri = "http://localhost:3000/posts" +} + +# reading ini configuration file +# ------------------------------- +data "config_ini" "cfg" { + ini = file("configuration.ini") } ``` diff --git a/config/data_source_configuration_workbook.go b/config/data_source_configuration_workbook.go index 4321fcd..7deeca7 100644 --- a/config/data_source_configuration_workbook.go +++ b/config/data_source_configuration_workbook.go @@ -170,7 +170,7 @@ func dataSourceConfigurationItemRead(ctx context.Context, d *schema.ResourceData if params.excel_file != "" { csvstring, err := excelToCSV(params) if err != nil { - return diag.FromErr(fmt.Errorf(fmt.Sprintf("%v", csvstring))) + return diag.FromErr(err) } params.csv_string = csvstring // return diag.FromErr(fmt.Errorf(fmt.Sprintf("%v", csvstring))) @@ -256,17 +256,17 @@ func excelToCSV(args *ConfigurationWorkbook) (string, error) { // check if sheet is existing in the workbook sheetId := f.GetSheetIndex(args.sheet_name) - if sheetId == -1 { - return "", fmt.Errorf("sheet name not found") + if sheetId < 0 { + return "", fmt.Errorf("worksheet \"%s\" not found", args.sheet_name) } // Get all rows rows, err := f.GetRows(args.sheet_name) if err != nil { - return "", fmt.Errorf(fmt.Sprintf("%v", rows)) + return "", err } - if len(rows) == 0 { - return "", fmt.Errorf("sheet does not have data") + if len(rows) <= 0 { + return "", fmt.Errorf("worksheet \"%s\" does not have data", args.sheet_name) } // get the number of columns diff --git a/docs/data-sources/ini.md b/docs/data-sources/ini.md index c55e6ff..3b9510d 100644 --- a/docs/data-sources/ini.md +++ b/docs/data-sources/ini.md @@ -2,7 +2,8 @@ # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "config_ini Data Source - terraform-provider-config" subcategory: "" -description: This data source will parse the INI file and output a JSON string format. +description: |- + This data source will parse the INI file and output a JSON string format. --- diff --git a/docs/data-sources/restapi_get.md b/docs/data-sources/restapi_get.md index af893fd..2e1470d 100644 --- a/docs/data-sources/restapi_get.md +++ b/docs/data-sources/restapi_get.md @@ -70,12 +70,32 @@ data "config_restapi_get "general" { } ``` +### Example - Using POST method +```terraform +data "config_restapi_get" "post" { + uri = "http://localhost:3000/posts" + header { + key = "Content-Type" + value = "application/json" + } + method = "POST" + payload = <<-EOT + { + "title":"test-post", + "author":"me" + } + EOT +} +``` + ## Properties - **uri** (String) - (Required) URI of the target api. - **user** (String) - (Optional) Username for basic authentication. - **password** (String) - (Optional) Password for basic authentication. +- **method** (String) - (Optional) Valid values are GET,POST +- **payload** (String) - (Optional) JSON string for the POST body - **param** (Block) - (Optional) URI parameters. - **header** (Block) - (Optional) Additional headers for the request. @@ -85,7 +105,7 @@ Nested `param` blocks have the following structure: - **key** (String) - (Required) The name of the field to query. - **value** (String) - (Required) The value to query. -### Param +### Header Nested `header` blocks have the following structure: - **key** (String) - (Required) The name of the header to add. diff --git a/docs/index.md b/docs/index.md index fc8a0c9..853b642 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,16 +8,38 @@ description: |- # config Provider +The config Provider gives Terraform the ability to work with Excel worksheets, INI configuration files, and API response data. + +Use the navigation on the left to read about the various data sources supported by the provider. + +## Example Usage + +The following example demonstrates a current basic usage of the provider. + ```hcl terraform { required_providers { config = { - version = "x.x.x" source = "alabuel/config" + version = "x.x.x" # supply the version } } } provider "config" {} + +data "config_workbook" "excel" { + excel = "filename.xlsx" + worksheet = "Sheet1" +} + +data "config_restapi_get "apidata" { + uri = "http://localhost:3000/posts" +} + +data "config_ini" "cfg" { + ini = file("configuration.ini") +} ``` +See the sidebar for usage information on all the data sources, which will have examples specific to their own use cases. \ No newline at end of file