Skip to content

Latest commit

 

History

History
122 lines (79 loc) · 6.61 KB

CONTRIBUTING.md

File metadata and controls

122 lines (79 loc) · 6.61 KB
Raw

Contributor Guide

Thank you for your interest in contributing to the Kubernetes provider. We welcome your contributions. Here, you'll find information to help you get started with provider development.

If you want to learn more about developing a Terraform provider, please refer to the Plugin Development documentation.

Configuring Environment

  1. Install Golang

    Install the version of Golang as indicated in the go.mod file.

  2. Fork this repo

    Fork the provider repository and clone it on your computer.

    Here is an example of how to clone this repository and switch to the directory:

    $ git clone https://github.com/<YOUR-USERNAME>/terraform-provider-kubernetes.git
$ cd terraform-provider-kubernetes

    From now on, we are going to assume that you have a copy of the repository on your computer and work within the terraform-provider-kubernetes directory.

  3. Prepare a Kubernetes Cluster

    While our preference is to use KinD for setting up a Kubernetes cluster for development and test purposes, feel free to opt for the solution that best suits your preferences. Please bear in mind that some acceptance tests might require specific cluster settings, which we maintain in the KinD configuration file.

    Here is an example of how to provision a Kubernetes cluster using the configuration file:

    $ kind create cluster --config=./.github/config/acceptance_tests_kind_config.yaml

    KinD comes with a default Node image version that depends on the KinD version and thus might not be always the one you want to use. The above command can be extended with the --image option to spin up a particular Kubernetes version:

    $ kind create cluster \
  --config=./.github/config/acceptance_tests_kind_config.yaml \
  --image kindest/node:v1.28.0@sha256:b7a4cad12c197af3ba43202d3efe03246b3f0793f162afb40a33c923952d5b31

    Refer to the KinD releases to get the right image.

    From now on, we are going to assume that the Kubernetes configuration is stored in the $HOME/.kube/config file, and the current context is set to a newly created KinD cluster.

    Once the Kubernetes cluster is up and running, we strongly advise you to run acceptance tests before making any changes to ensure they work with your setup. Please refer to the Testing section for more details.

Making Changes

Adding a New Resource

This quick guide covers best practices for adding a new Resource.

  1. Ensure all dependncies are installed.
  2. Add an SDK Client.
  3. Add Resource Schema and define attributes see Kubernetes Documentation. A best and recommended practice is reuse constants from the Kuberentes packages as a default value in an attribute or within a validation function.
  4. Scaffold an empty/new resource.
  5. Add Acceptance Tests(s) for the resource.
  6. Run Acceptance Tests(s) for this resource.
  7. Add Documentation for this resource by editing the .md.tmpl file to include the appropriate Data Fields and executing tfplugindocs generate command see Terraform PluginDocs then inspecting the corresponding .md file in the /docs to see all changes. The Data Fields that are currently apart of the templates are those for the Schema ({{ .SchemaMarkdown }}), Name ({{ .Name }}) and ({{ .Description }}).
  8. Execute make docs-lint and make tests-lint commands
  9. Create a Pull Request for your changes.

Adding a New Data Source

  1. Ensure all dependncies are installed.
  2. Add an SDK Client.
  3. Add Data Source Schema and define attributes see Kubernetes Documentation. A best and recommended practice is reuse constants from the Kuberentes packages as a default value in an attribute or within a validation function.
  4. Scaffold an empty/new resource.
  5. Add Acceptance Tests(s) for the data source.
  6. Run Acceptance Tests(s) for this data source.
  7. Add Documentation for this data source by editing the .md.tmpl file to include the appropriate Data Fields and executing tfplugindocs generate command see Terraform PluginDocs then inspecting the corresponding .md file in the /docs to see all changes. The Data Fields that are currently apart of the templates are those for the Schema ({{ .SchemaMarkdown }}), Name ({{ .Name }}) and ({{ .Description }}).
  8. Execute make docs-lint and make tests-lint commands
  9. Create a Pull Request for your changes.

Adding/Editing Documentation

All Documentation is edited in the .md.tmpl file. Please note that the tfplugindocs generate command should be executed to ensure it is updated and reflected in the .md files.

Testing

The Kubernetes provider includes two types of tests: unit tests and acceptance tests.

Before running any tests, make sure that the KUBE_CONFIG_PATH environment variable points to the Kubernetes configuration file:

$ export KUBE_CONFIG_PATH=$HOME/.kube/config

The following commands demonstrate how to run unit and acceptance tests respectively.

$ make test # unit tests
$ make testacc TESTARGS="-run ^TestAcc" # acceptance tests
  1. Run existing tests
  2. Write/Update tests
  3. Run tests with new changes

Updating changelog

A PR that is merged may or may not be added to the changelog. Not every change should be in the changelog since they don't affect users directly. Some instances of PRs that could be excluded are:

  • unit and acceptance tests fixes
  • minor documentation changes

However, PRs of the following categories should be added to the appropriate section:

  • FEATURES
  • ENHANCEMENTS
  • MAJOR BUG FIXES

Please refer to our ChangeLog Guide.

Creating & Submiting a PR

Please refer to this guide.