Skip to content

Developer Guide

Jump to bottom
Iulia-Ioana Blindu edited this page Aug 1, 2022 · 6 revisions

This page is meant to provide a guideline for creating a new service within the IONOS Cloud Terraform Provider, a guideline in sync with decisions took inside the SDKs & Tooling Team regarding this product. :1st_place_medal: New proposals are always welcomed in order to improve our provider!

Step 1 - creating a new package (e.q. here)

If the new service is requiring another IONOS SDK beside sdk-go (e.q. sdk-go-dbaas-postgres), a new package should be created inside the services folder containing methods for the corresponding resources as follows:

  • client setup
  • all the CRUD operations
  • getters and setters of Schema Data
  • any other methods needed for performing actions using the new client

Step 2 - client initialization

Step 3 - creating the resource (e.q. here)

Note that not all API resources must have a terraform resource, since some of them may be just read-only. When a resource is created, a new file, named appropriately, should be added in the ionoscloud package. Steps for creating a resource:

  • the Resource Schema must be as complete as possible including the type, description and validations provided in the swagger
  • note that when a resource has a field that is optional and also has a default value, both optional and computed parameters should be set on true
  • a CustomizeDiff function should be added for the immutable fields
  • CreateContext, ReadContext, UpdateContext, DeleteContext and Importer methods must be added
  • the request time should be logged for each request
  • where needed wait for the request/state

Step 4 - creating the data source (e.q. here)

When a data source is created, a new file, named appropriately, should be added in the ionoscloud package. Data sources usually have as arguments id and name properties, but additional ones may be added according to the specific needs.

❗ the data source should correspond with the resource named similarly, meaning that if through a resource a single object is created, so should the data source behave. If a data source returning a list of objects is needed, the name of the data source must include plural (e.q. data_source_server.go vs data_source_servers.go)

Steps for creating a data source:

  • the Data Source Schema should include all the Resource fields along with any additional fields needed (e.q. read-only properties)
  • when it comes to the name argument, partial-match property should also exist in the Schema, being the property that specifies whether partial matching is allowed or not when using the name argument
  • usually partial matching can be done by using the filters provided by the SDK, but when they don't exist the functionality should be implemented in the provider
  • when it comes to the name argument the search must be case insensitive
  • appropriate logging messages should be added for knowing which filters were used

Step 5 - testing (e.q. here)

For testing, all test steps for a resource, including testing data sources and resources, should be in the same test, in order to reduce test duration as much as possible. Make sure all these use cases are covered:

  • resource is created with all available properties
  • all updatable properties are updated correctly
  • optional properties can be emptied (including lists)
  • data source using each of the available arguments is behaving correctly, together with combinations of them
  • expect error when data source is returning no result
  • expect error when data source is returning multiple results (where creating an additional resource doesn't take too much time - e.q. k8s)
  • add build tags for each test file, containing the service name, and update the README.md test guideline, along with the test workflow, to include the new test tags

Step 6 - writing the documentation (e.q. data source & resource)

  • all examples should work with just a copy paste (except when sensitive information is requried)
  • for resources, the following must be specified: type, whether it is required or not and description
  • for data sources all available arguments should be specified, along with how they work
  • for data sources description for all returned attributes but be specified
  • if more complex examples are needed, with specific use cases, they should be added under the examples folder, creating a folder for that use case along with a README.md that explains the use case (e.q. here)

Best practices

  • variables should be created instead of writing large peaces of code in one line
  • appropriate naming conventions should be used
  • don’t use lengthy functions. Ideally, a single function should carry out a single task
  • constants provided in the corresponding files here and here should be used or if needed, new ones should be created
  • corresponding methods for logApiRequestTime, httpNotFound, waitForRequest, waitForState should be used (WIP)

Releasing

  • Update documentation Check all the newly added resources, arguments and compartments are added in docs, along with all the updated in the CHANGELOG.md
  • Run all tests Make sure you run all tests either locally or by running the github actions for testing.
  • Update CHANGELOG.md
  • Merge to master
  • Release 
git tag vX.Y.Z
git push --tags
Clone this wiki locally