Skip to content

Latest commit

 

History

History
111 lines (78 loc) · 4.48 KB

README.md

File metadata and controls

111 lines (78 loc) · 4.48 KB
Terraform logo

Terraform Provider for CANCOM Cloud

The CANCOM Terraform Provider allows managing resources within CANCOM Managed Services Cloud.

Please note: We take Terraform's security and our users' trust very seriously. If you believe you have found a security issue in the Terraform CANCOM Provider, please responsibly disclose it by contacting us at [email protected].

Usage Example

# 1. Specify the version of the CANCOM Provider to use
terraform {
  required_providers {
    cancom = {
      source = "cancom/cancom"
      version = "0.0.1"
    }
  }
}

# 2. Configure the CANCOM Provider
# You can provide your API token via CANCOM_TOKEN environment variable, representing your CANCOM token.
# When using this method, you may omit the CANCOM provider block entirely.
provider "cancom" {
  token = "<token>"
}

# 3. Create a resource group
resource "cancom_dns_record" "test" {
  zone_name = "example.com"
  name      = "test.example.com"
  type      = "A"
  content   = "127.0.0.1"
}

Requirements

  • Terraform 0.14.x or higher
  • Go 1.21 (to build the provider plugin)

Building The Provider

Clone repository to: $GOPATH/src/github.com/cancom/terraform-provider-cancom

$ mkdir -p $GOPATH/src/github.com/cancom; cd $GOPATH/src/github.com/cancom
$ git clone [email protected]:cancom/terraform-provider-cancom

Enter the provider directory and build the provider

$ cd $GOPATH/src/github.com/cancom/terraform-provider-cancom
$ make build

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.21+ is required).

To compile the provider, run make build. This will build the provider and put the provider binary in a local bin directory.

$ make build
...

Alongside the newly built binary a file called developer_overrides.tfrc will be created. The make build target will communicate back details for setting the TF_CLI_CONFIG_FILE environment variable that will enable Terraform to use your locally built provider binary.

NOTE: If you have issues seeing any behaviours from code changes you've made to the provider, then it might be the terraform CLI is getting confused by which provider binary it should be using. Check inside the ./bin/ directory to see if there are multiple providers with different commit hashes (e.g. terraform-provider-cancom_v1.1.0-3-fgcd28ca1) and delete them first before running make build. This should help the Terraform CLI resolve to the correct binary.

Building The Documentation

The documentation is built from components (go templates) stored in the templates folder. Building the documentation copies the full markdown into the docs folder, ready for deployment to Hashicorp.

NOTE: you'll need the tfplugindocs tool for generating the Markdown to be deployed to Hashicorp. For more information on generating documentation, refer to https://www.terraform.io/docs/registry/providers/docs.html

  • To validate the /template directory structure:
make validate-docs
  • To build the /docs documentation Markdown files:
make generate-docs

Note: The description and the subcategory of resource are now automatically generated from the resource's Description field within the go file, similar to how the schema's arguments are generated. This allows you to define resources descriptions with My Subcategory --- The description of my resource and have the subcategory and description filled in correctly. It also works if you don't provide a subcategory, in that case, it will just populate the description.
The only caveat is that you can't use additional --- in your description.
Imports and examples are automatically filled in if they are placed and named correctly in examples/{type}/{resource_name}

Contributing

Refer to CONTRIBUTING.md