From ce248d03ef7a09c3f1536d2f8b1c29f134e74bd2 Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Wed, 15 May 2019 14:59:18 +0200 Subject: [PATCH 1/6] add instructions to develop the provider --- provider/CONTRIBUTE.md | 112 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index d8c87313..33b82c85 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -1,6 +1,7 @@ # Contribute to Terraform AzureRM provider This document describe how you can get ready to contribute to the [AzureRM Terraform provider](https://github.com/terraform-providers/terraform-provider-azurerm). +We also recommand that your read the [README](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/README.md) on the AzureRM Terraform Provider repository. ## Setup your system @@ -135,6 +136,117 @@ Once done, you can just press F5 and the debug will start! You can place breakpo *Note: the first time your start the debug, it can take a while, you need to be patient :-)* +## How to contribute to the Azure RM provider + +First you need to pick [an issue on the provider](https://github.com/terraform-providers/terraform-provider-azurerm/issues) by commenting the issue and saying that you're going to work on that, to make sure that HashiCorp people who maintain the repository and will review your contribution are aware that you are going to work on that. + +*Note: if there is no issue for the problem you are trying to solve, you can create one.* + +If you are a new contributor, there is a [good first issue](https://github.com/terraform-providers/terraform-provider-azurerm/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label that may help you to filter the issue and start with a simple one. + +For each piece of code that you write into the provider, you need to make sure that you have: + +- the implementation in both `data source` and `resource` definition +- acceptance test created or updated +- documentation created or updated +- example created or updated + +Data sources, resources and tests are defined in the [azurerm](https://github.com/terraform-providers/terraform-provider-azurerm/tree/master/azurerm) folder of the repository. + +Documentation for data sources is in the [website/docs/d](https://github.com/terraform-providers/terraform-provider-azurerm/tree/master/website/docs/d) folder and documentation for resources is in the [website/docs/r](https://github.com/terraform-providers/terraform-provider-azurerm/tree/master/website/docs/r) folder. + +Finally, examples are located in the [examples](https://github.com/terraform-providers/terraform-provider-azurerm/tree/master/examples) folder. + +AzureRM Terraform provider uses the [Azure SDK for Go](https://github.com/Azure/azure-sdk-for-go) to interact with Azure. It's important that you respect that rule. If you are trying to do something that is not available in the Azure SDK for Go, then you should open an issue on that repository first. + +We recommand that you start with fixing issues/patching an existing data source or resource to understand how it works in details before trying to implement a brand new one. + +Don't forget that you are working on your own fork of the repository and that you need to open a pull request to the main repository to bring your update to the HashiCorp team, for review. + +### Working with Azure SDK for Go + +All the imports for the Azure Go SDK services have to be done in the [config.go](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/config.go) file. It exposes a top level struct, `ArmClient` that exposes all the client that you may use in a data source or resource to interact with Azure. + +For example, if you need to work on implementing Azure Batch Account support to the provider: + +1. Add import for `"github.com/Azure/azure-sdk-for-go/services/batch/mgmt/2018-12-01/batch"` in the imports list +2. Add a field for the `batchAccountClient`: + +```go +batchAccountClient batch.AccountClient +``` + +3. Add a function that registers the Azure Batch client: + +```go +func (c *ArmClient) registerBatchClients(endpoint, subscriptionId string, auth autorest.Authorizer) { + batchAccount := batch.NewAccountClientWithBaseURI(endpoint, subscriptionId) + c.configureClient(&batchAccount.Client, auth) + c.batchAccountClient = batchAccount +} +``` + +4. Call the function that registers the Batch client: + +```go +client.registerBatchClients(endpoint, c.SubscriptionID, auth) +``` + +By doing the four steps above, you will make sure that when developping the data source or the resource, you can access the Azure SDK for Go clients that you need. + +### Developping a Data Source + +The file for a data source is named following the convention: data_source_*NAME_OF_THE_DATA_SOURCE*.go. + +A data source is composed of two relevant functions: + +- The function that creates a `schema.Resource` object that returns the schema (definition) of the data source,i.e. the property that compose the data source, and some rules about those properties (for example, if it is mandatory or not, computed etc.). This function is named by convention dataSourceArm*NAME_OF_THE_DATA_SOURCE*, for example `dataSourceArmBatchAccount` for a Batch Account. +- The function that retrieves the data from Azure using the Azure SDK for Go client and set all the values related to the data source. This function is named by convention dataSourceArm*NAME_OF_THE_DATA_SOURCE*Read, for example `dataSourceArmBatchAccountRead` for a Batch Account. + +This function takes a `schema.ResourceData` in parameter. You can get the name of the object to retrieve and any property that is defined by the user on that object: + +```go +resourceGroup := d.Get("resource_group_name").(string) +name := d.Get("name").(string) +``` + +You can get a reference on any Azure SDK for Go client registered in the `client.go` using: + +```go +client := meta.(*ArmClient).batchAccountClient +``` + +Finally, you can set values retrieve from Azure on the same object, using the `Set` function: + +```go +d.Set("account_endpoint", resp.AccountEndpoint) +``` + +You can check the whole definition of the Azure Batch Account data source [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/data_source_batch_account.go). + +### Developing a resource + +Developing a resource is really similar to developing a data source. Instead of having only a function to read the data from Azure, it also offers the possibility to write functions to create, update and delete the resource. Apart from that, concepts are the same: + +- The file is named using the convention: resource_arm_*NAME_OF_RESOURCE*.go +- One function to define the structure of the resource, named by convention resourceArm*NAME_OF_RESOURCE*, for example `resourceArmBatchAccount`. +- One function to create the resource, named by convention resourceArm*NAME_OF_RESOURCE*Create, for example `resourceArmBatchAccountCreate`. +- One function to read the resource, named by convention resourceArm*NAME_OF_RESOURCE*Read, for example `resourceArmBatchAccountRead`. +- One function to update the resource, named by convention resourceArm*NAME_OF_RESOURCE*Update, for example `resourceArmBatchAccountUpdate`. +- One function to delete the resource, named by convention resourceArm*NAME_OF_RESOURCE*Delete, for example `resourceArmBatchAccountDelete`. + +The [Azure Batch Account resource](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/resource_arm_batch_account.go) is a good and simple example to understand the flow. + +### Acceptance tests + +Acceptance tests are test that will run live on your Azure subscription to validate that your data source or resource is working well. Each data source should have its acceptance tests and each resource should have its acceptance test. + +Tests are definied in the `azurerm` directory, aside with data sources and resources. The file name is the same than the one for the data source or resource, with the `_test` suffix. + +You can find examples of tests for Azure Batch Account data source [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/data_source_batch_account_test.go) and Azure Batch Account resource [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/resource_arm_batch_account_test.go). + +Please refer to the above section to learn on to run the acceptance test on your laptop. + ## Other ### Slack From 99ae52231c5807bd0bc8a9e2b4a35ba1a650ca5c Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Wed, 15 May 2019 15:30:09 +0200 Subject: [PATCH 2/6] add link to official docs --- provider/CONTRIBUTE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index 33b82c85..c28cc973 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -138,6 +138,8 @@ Once done, you can just press F5 and the debug will start! You can place breakpo ## How to contribute to the Azure RM provider +*Note: we also invite you to read the official documentation about developing a provider [here](https://www.terraform.io/docs/plugins/basics.html#developing-a-plugin)* + First you need to pick [an issue on the provider](https://github.com/terraform-providers/terraform-provider-azurerm/issues) by commenting the issue and saying that you're going to work on that, to make sure that HashiCorp people who maintain the repository and will review your contribution are aware that you are going to work on that. *Note: if there is no issue for the problem you are trying to solve, you can create one.* @@ -245,7 +247,7 @@ Tests are definied in the `azurerm` directory, aside with data sources and resou You can find examples of tests for Azure Batch Account data source [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/data_source_batch_account_test.go) and Azure Batch Account resource [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/resource_arm_batch_account_test.go). -Please refer to the above section to learn on to run the acceptance test on your laptop. +Please refer to the above section to learn on to run the acceptance tests on your laptop. ## Other From 3b18e78dcd32fbc364fb0c913629a9d6e5308d5c Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Wed, 15 May 2019 16:08:10 +0200 Subject: [PATCH 3/6] update local built provider --- provider/CONTRIBUTE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index c28cc973..c1cdb793 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -66,9 +66,9 @@ More information [here](https://github.com/terraform-providers/terraform-provide Once you have built a new version of the AzureRM Terraform provider, you can use it locally. To use your local version, the first thing to do is a `terraform init`, as usual, to inialize your terraform working directory. -The init operation will download the AzureRM Provider for you. You can just remove it, and replace it with your local copy. +If your `terraform` binary is in the `$GOPATH/bin` folder on your machine, then the terraform init operation will use the locally built provider. -Do a `terraform init` again and you're done ! :-) +If not, the init operation will download the AzureRM Provider for you. You can just remove it, and replace it with your local copy. Do a `terraform init` again and you're done ! :-) ## Debug the AzureRM provider using Visual Studio Code and Delve From eaef681e00ef945add6fb03d5da4a40dac75d8c8 Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Fri, 17 May 2019 10:11:21 +0200 Subject: [PATCH 4/6] fix typo and few additions --- provider/CONTRIBUTE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index c1cdb793..62c8ead3 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -1,7 +1,7 @@ # Contribute to Terraform AzureRM provider This document describe how you can get ready to contribute to the [AzureRM Terraform provider](https://github.com/terraform-providers/terraform-provider-azurerm). -We also recommand that your read the [README](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/README.md) on the AzureRM Terraform Provider repository. +We also recommend that you read the [README](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/README.md) on the AzureRM Terraform Provider repository. ## Setup your system @@ -140,7 +140,8 @@ Once done, you can just press F5 and the debug will start! You can place breakpo *Note: we also invite you to read the official documentation about developing a provider [here](https://www.terraform.io/docs/plugins/basics.html#developing-a-plugin)* -First you need to pick [an issue on the provider](https://github.com/terraform-providers/terraform-provider-azurerm/issues) by commenting the issue and saying that you're going to work on that, to make sure that HashiCorp people who maintain the repository and will review your contribution are aware that you are going to work on that. +First you need to pick [an issue on the provider](https://github.com/terraform-providers/terraform-provider-azurerm/issues) by commenting the issue and saying that you're going to work on that, to make sure that the repo maintainers are aware that you are going to work on this issue. +We also strongly advise that you describe the work you are planning to do, like explaining your implementation, submitting the TF schema for new resources, to make sure the discussion start early as possible with the reviewers. *Note: if there is no issue for the problem you are trying to solve, you can create one.* From e8d6b4f92c6c3d376272ee53c242fd5351b0cea4 Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Tue, 21 May 2019 09:58:42 +0200 Subject: [PATCH 5/6] few changes after @JunyiYi review --- provider/CONTRIBUTE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index 62c8ead3..f0a2e913 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -152,7 +152,7 @@ For each piece of code that you write into the provider, you need to make sure t - the implementation in both `data source` and `resource` definition - acceptance test created or updated - documentation created or updated -- example created or updated +- example created or updated (optional) Data sources, resources and tests are defined in the [azurerm](https://github.com/terraform-providers/terraform-provider-azurerm/tree/master/azurerm) folder of the repository. @@ -197,13 +197,13 @@ client.registerBatchClients(endpoint, c.SubscriptionID, auth) By doing the four steps above, you will make sure that when developping the data source or the resource, you can access the Azure SDK for Go clients that you need. -### Developping a Data Source +### Developing a Data Source The file for a data source is named following the convention: data_source_*NAME_OF_THE_DATA_SOURCE*.go. A data source is composed of two relevant functions: -- The function that creates a `schema.Resource` object that returns the schema (definition) of the data source,i.e. the property that compose the data source, and some rules about those properties (for example, if it is mandatory or not, computed etc.). This function is named by convention dataSourceArm*NAME_OF_THE_DATA_SOURCE*, for example `dataSourceArmBatchAccount` for a Batch Account. +- The function that creates a `schema.Resource` object that returns the schema (definition) of the data source,i.e. the property that compose the data source, and some rules about those properties. You only need to provide required properties to locate that resource, and mark all other properties returned from the service as `Computed`. This function is named by convention dataSourceArm*NAME_OF_THE_DATA_SOURCE*, for example `dataSourceArmBatchAccount` for a Batch Account. - The function that retrieves the data from Azure using the Azure SDK for Go client and set all the values related to the data source. This function is named by convention dataSourceArm*NAME_OF_THE_DATA_SOURCE*Read, for example `dataSourceArmBatchAccountRead` for a Batch Account. This function takes a `schema.ResourceData` in parameter. You can get the name of the object to retrieve and any property that is defined by the user on that object: @@ -232,7 +232,7 @@ You can check the whole definition of the Azure Batch Account data source [here] Developing a resource is really similar to developing a data source. Instead of having only a function to read the data from Azure, it also offers the possibility to write functions to create, update and delete the resource. Apart from that, concepts are the same: - The file is named using the convention: resource_arm_*NAME_OF_RESOURCE*.go -- One function to define the structure of the resource, named by convention resourceArm*NAME_OF_RESOURCE*, for example `resourceArmBatchAccount`. +- One function to define the schema of the resource, named by convention resourceArm*NAME_OF_RESOURCE*, for example `resourceArmBatchAccount`. - One function to create the resource, named by convention resourceArm*NAME_OF_RESOURCE*Create, for example `resourceArmBatchAccountCreate`. - One function to read the resource, named by convention resourceArm*NAME_OF_RESOURCE*Read, for example `resourceArmBatchAccountRead`. - One function to update the resource, named by convention resourceArm*NAME_OF_RESOURCE*Update, for example `resourceArmBatchAccountUpdate`. From 8b65cc21c022fa06fa45f33f4f253d2dfb302068 Mon Sep 17 00:00:00 2001 From: Julien Corioland Date: Fri, 24 May 2019 09:27:35 +0200 Subject: [PATCH 6/6] add data source/resource registration in provider.go --- provider/CONTRIBUTE.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/provider/CONTRIBUTE.md b/provider/CONTRIBUTE.md index f0a2e913..7c9b95fe 100644 --- a/provider/CONTRIBUTE.md +++ b/provider/CONTRIBUTE.md @@ -149,7 +149,7 @@ If you are a new contributor, there is a [good first issue](https://github.com/t For each piece of code that you write into the provider, you need to make sure that you have: -- the implementation in both `data source` and `resource` definition +- the implementations of the `data source` and/or `resource` definition - acceptance test created or updated - documentation created or updated - example created or updated (optional) @@ -227,6 +227,13 @@ d.Set("account_endpoint", resp.AccountEndpoint) You can check the whole definition of the Azure Batch Account data source [here](https://github.com/terraform-providers/terraform-provider-azurerm/blob/master/azurerm/data_source_batch_account.go). +Once your data source is defined, you need to register it into data sources map in the `provider.go` file: + +```go +DataSourcesMap: map[string]*schema.Resource{ + "azurerm_api_management": dataSourceApiManagementService(), +``` + ### Developing a resource Developing a resource is really similar to developing a data source. Instead of having only a function to read the data from Azure, it also offers the possibility to write functions to create, update and delete the resource. Apart from that, concepts are the same: @@ -250,6 +257,13 @@ You can find examples of tests for Azure Batch Account data source [here](https: Please refer to the above section to learn on to run the acceptance tests on your laptop. +Once your resource is defined, you need to register it into the resources map in the `provider.go` file: + +```go +ResourcesMap: map[string]*schema.Resource{ + "azurerm_api_management": resourceArmApiManagementService(), +``` + ## Other ### Slack