- Documentation: https://terraform-provider.yandexcloud.net
Clone repository to: $GOPATH/src/github.com/yandex-cloud/terraform-provider-yandex
$ mkdir -p $GOPATH/src/github.com/yandex-cloud; cd $GOPATH/src/github.com/yandex-cloud
$ git clone git@github.com:yandex-cloud/terraform-provider-yandex
Enter the provider directory and build the provider
$ cd $GOPATH/src/github.com/yandex-cloud/terraform-provider-yandex
$ make build
If you're building the provider, follow the instructions to install it as a plugin. After placing it into your plugins directory, run terraform init
to initialize it. Documentation about the provider specific configuration options can be found on the provider's website.
An example of using an installed provider from local directory:
Write following config into ~/.terraformrc
provider_installation {
dev_overrides {
"yandex-cloud/yandex" = "/path/to/local/provider"
}
direct {}
}
If you wish to work on the provider, you'll first need Go installed on your machine (version 1.11+ is required). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin
to your $PATH
.
To compile the provider, run make build
. This will build the provider and put the provider binary in the $GOPATH/bin
directory.
$ make build
...
$ $GOPATH/bin/terraform-provider-yandex
...
In order to test the provider, you can simply run make test
.
$ make test
In order to run the full suite of Acceptance tests, run make testacc
.
Note: Acceptance tests create real resources, and often cost money to run.
$ make testacc
Our documentation generator follows a specific flow. Based on the documentation template and the description fields for resources/datasources and their schema fields in the Terraform provider, we generate the corresponding documentation.
For every resource and data source defined in the Yandex provider, a documentation template is automatically generated.
If your resource/datasource does not have a template, please run the following command:
make generate-docs-templates
If it is a new service, first update templates/categories.yaml
.
For reference, you can view a generated template for container_repository.
By default, these templates are generated automatically. However, if you want to enhance the documentation of your resource or data source, you can manually add or rewrite information in the template. To do this, you can use the available template fields and functions that the Terraform documentation generator will process.
You can enhance your resource documentation by adding more examples. For instance, here’s an example from the storage documentation template:
### Simple Private Bucket With Static Access Keys
{{tffile "examples/storage/resources/example_2.tf"}}
### Static Website Hosting
{{tffile "examples/storage/resources/example_3.tf"}}
### Using ACL Policy Grants
{{tffile "examples/storage/resources/example_4.tf"}}
### Using CORS
{{tffile "examples/storage/resources/example_5.tf"}}
If you add a new service, please update templates/categories.yaml
. The key in this file is the service path in the templates directory, and the value is the service name. This is used for grouping services on the documentation website. Then run the following command:
make generate-docs-templates
Here are some examples of how template variables resolve:
- {{.Name}} resolves to yandex_dns_zone.
- {{.Description}} resolves to Manages a DNS Zone..
- {{ .SchemaMarkdown }} resolves to the generated schema documentation, such as Schema ....
To ensure consistency and completeness in your documentation:
-
Example Usage: Uncomment the following block and add examples of resource/data source usage in the specified path:
{{- /* Uncomment this block as you add "examples/{serviceName}/resources/example_1.tf" ## Example Usage {{tffile "examples/{serviceName}/resources/example_1.tf" }} */ -}}
-
Import Syntax: Uncomment the following block and add examples of resource import in the specified path:
{{- /* Uncomment this block as you add "examples/{serviceName}/resources/import/import.sh" ## Import Import is supported using the following syntax: {{codefile "shell" "examples/{serviceName}/resources/import/import.sh" }} */ -}}
To build the documentation website locally, follow these steps:
-
First, install YFM:
make install-yfm
-
Once installed, you can build your local version of the documentation by running the following command:
make build-website
-
To publish updates to the documentation, set the following environment variables:
export FM_STORAGE_KEY_ID=**censored** export YFM_STORAGE_SECRET_KEY=**censored**
Then, run the following command:
make publish-website
To migrate your document template to automatically generate resource/data source schema documentation, follow these steps:
-
Add a Description: Add a description to your resource in the Terraform provider. Example: dns_zone.
-
Describe Schema Fields: Add a description to every schema field for the resource/data source. Example: dns_zone.zone.
-
Remove Manual Documentation:
- Remove the manual description of the resource/data source in the template. Example: datasource.
- Remove the
Argument Reference
block. Example: Argument Reference. - Remove the
Attributes Reference
block. Example: Attributes Reference.
-
Automate Schema Documentation: Place the
{{ .SchemaMarkdown }}
field in the template to automatically generate documentation based on field descriptions.
Ensure that the markdown used in your documentation is properly formatted for consistent display and readability. This includes checking for proper syntax, resolving template variables, and ensuring that links and examples are correctly referenced.