Merge pull request #7 from equinix-labs/add_documentation

Add documentation

Author: displague

CONTRIBUTING.md

@@ -9,13 +9,8 @@ Contributors to this project must abide by the [Contributor Covenant Code of Con
 The project has the following folders and files:
 
 - /: root folder.
-- /docs: Examples for using this module.
 - /examples: Examples for using this module.
-- /files: Static files referenced but not executed by Terraform.
-- /helpers: Helper scripts NOT called by Terraform.
 - /modules: Inline local modules called by this module.
-- /scripts: Scripts for specific tasks on module.
-- /templates: Template files used to be execute by data sources.
 - /main.tf: Main file for this module, contains all the resources to operate the module.
 - /variables.tf: All the variables necessary for run the module.
 - /output.tf: The outputs generate from the module.
@@ -25,6 +20,20 @@ The project has the following folders and files:
 - /CODE_OF_CONDUCT.md: Code of Conduct file.
 - /CONTRIBUTING.md: This file.
 
+## Adding a new module
+
+To add a new module, fork this repo then add your module under [./modules](./modules/) folder. Please visit our [Terraform Module Development Standards guide](https://github.com/equinix-labs/equinix-labs/blob/main/terraform-module-standards.md) for more info on module development best practices.
+
 ## Issues and Change Requests
 
-Please submit change requests and / or features via [Issues](https://github.com/equinix-labs/equinix-labs/issues).
+Please submit change requests and / or features via [Issues](https://github.com/equinix-labs/terraform-equinix-labs/issues).
+
+## Submitting Pull Requests
+
+Before starting any work or sending us a pull request, please ensure that:
+
+- Your working branch is up-to-date with the latest source on the main branch.
+- Check issues and pull requests (open/merged) to make sure someone else hasn't already addressed that issue.
+- You open an issue to discuss your proposal.
+
+To learn how to send us a pull request, please see [Contributing to Projects](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) in the GitHub Docs.

README.md

@@ -1,5 +1,30 @@
 # Terraform Equinix Labs Project
 
+[![Experimental](https://img.shields.io/badge/Stability-Experimental-red.svg)](https://github.com/equinix-labs/standards#about-uniform-standards)
+[![run-pre-commit-hooks](https://github.com/equinix-labs/terraform-equinix-labs/actions/workflows/pre-commit.yaml/badge.svg)](https://github.com/equinix-labs/terraform-equinix-labs/actions/workflows/pre-commit.yaml)
+[![generate-terraform-docs](https://github.com/equinix-labs/terraform-equinix-labs/actions/workflows/documentation.yaml/badge.svg)](https://github.com/equinix-labs/terraform-equinix-labs/actions/workflows/documentation.yaml)
+
+This repository contains a collection of Terraform modules to help automate the deployment and management of either bare metal nodes or a kubernetes cluster environment running on [Equinix Metal](https://deploy.equinix.com/).
+
+## Usage
+
+This project is intended to be used as a Terraform module. It may also be forked, cloned, or downloaded and modified as needed as the base in your integrations and deployments.
+
+Prerequesites:
+
+* A valid Equinix Metal organization ID, API token, and/or project ID.
+* HashiCorp Terraform installed. Please see [tfenv](https://github.com/tfutils/tfenv) util.
+* Optional [metal-cli](https://github.com/equinix/metal-cli/#installation) installation.
+
+## Examples
+
+This project may be deployed into new project(s) or existing project(s). Check out sample deployments in the [examples](./examples/) directory described as follows:
+
+| Name | Description |
+|------|---------|
+| [eksa-setup](./examples/eksa-setup/) | Deploys a AWS EKS-A cluster into new projects provisioned for each user described in users.csv  |
+| [metal-setup](./examples/metal-setup/) | Deploys a cluster or bare nodes into new projects provisioned for each user described in users.csv  |
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -27,14 +52,14 @@ No resources.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
-| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 | <a name="input_eksa_config"></a> [eksa\_config](#input\_eksa\_config) | Module configuration for EKSA module | <pre>object({<br>    cluster_name        = string<br>    cp_device_count     = number<br>    worker_device_count = number<br>  })</pre> | <pre>{<br>  "cluster_name": "equinix-labs-cluster",<br>  "cp_device_count": 3,<br>  "worker_device_count": 3<br>}</pre> | no |
 | <a name="input_enable_eksa"></a> [enable\_eksa](#input\_enable\_eksa) | Enable EKSA module | `bool` | `false` | no |
 | <a name="input_enable_metal"></a> [enable\_metal](#input\_enable\_metal) | Enable Metal module | `bool` | `false` | no |
 | <a name="input_enable_workshop_setup"></a> [enable\_workshop\_setup](#input\_enable\_workshop\_setup) | Enable Workshop Setup module | `bool` | `false` | no |
+| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
 | <a name="input_metal_config"></a> [metal\_config](#input\_metal\_config) | Configuration for Metal module | <pre>object({<br>    device_count  = number<br>    os            = string<br>    billing_cycle = string<br>    cluster_name  = string<br>    device_type   = string<br>  })</pre> | <pre>{<br>  "billing_cycle": "hourly",<br>  "cluster_name": "metal-cluster",<br>  "device_count": 3,<br>  "device_type": "m3.small.x86",<br>  "os": "ubuntu_20_04"<br>}</pre> | no |
 | <a name="input_metal_metro"></a> [metal\_metro](#input\_metal\_metro) | Equinix Metal metro | `string` | `"sv"` | no |
+| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 | <a name="input_metal_project_id"></a> [metal\_project\_id](#input\_metal\_project\_id) | Project ID | `string` | `""` | no |
 | <a name="input_metal_tags"></a> [metal\_tags](#input\_metal\_tags) | String list of common tags for Equinix resources | `list(string)` | <pre>[<br>  "terraform",<br>  "equinix-labs"<br>]</pre> | no |
 
@@ -46,3 +71,10 @@ No resources.
 | <a name="output_deploy_metal_outputs"></a> [deploy\_metal\_outputs](#output\_deploy\_metal\_outputs) | Outputs of the Deploy Metal module |
 | <a name="output_project_setup_outputs"></a> [project\_setup\_outputs](#output\_project\_setup\_outputs) | Outputs of the Project Setup module |
 <!-- END_TF_DOCS -->
+## Contributing
+
+If you would like to contribute to this module, see [CONTRIBUTING](CONTRIBUTING.md) page for more info.
+
+## License
+
+Apache License, Version 2.0. See [LICENSE](LICENSE).

examples/eksa-setup/README.md

@@ -1,4 +1,6 @@
-# Terraform Equinix Labs Metal Setup Example
+# Terraform Equinix Labs EKSA Setup Example
+
+This is an example of how to utilize the root module to deploy the [invite-from-csv](https://github.com/equinix-labs/terraform-equinix-labs/tree/main/modules/invite-from-csv) module and the [eksa](https://github.com/equinix-labs/terraform-equinix-labs/tree/main/modules/eksa) module. In this example, each user identified in the `users.csv` file (see users.csv.example) will have a project provisioned and an invitation sent by email to join that project. Kubernetes will then be provisioned into each user's project with the configurations set within the [variables.tf](./variables.tf) file.
 
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
@@ -27,11 +29,11 @@ No resources.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
-| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 | <a name="input_eksa_config"></a> [eksa\_config](#input\_eksa\_config) | Module configuration for EKSA module | <pre>object({<br>    cluster_name        = string<br>    cp_device_count     = number<br>    worker_device_count = number<br>  })</pre> | <pre>{<br>  "cluster_name": "equinix-labs-cluster",<br>  "cp_device_count": 3,<br>  "worker_device_count": 3<br>}</pre> | no |
 | <a name="input_enable_eksa"></a> [enable\_eksa](#input\_enable\_eksa) | Enable EKSA module | `bool` | `true` | no |
 | <a name="input_enable_workshop_setup"></a> [enable\_workshop\_setup](#input\_enable\_workshop\_setup) | Enable Workshop Setup module | `bool` | `true` | no |
+| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
+| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 
 ## Outputs
 

examples/metal-setup/README.md

@@ -1,5 +1,7 @@
 # Terraform Equinix Labs Metal Setup Example
 
+This is an example of how to utilize the root module to deploy the [invite-from-csv](https://github.com/equinix-labs/terraform-equinix-labs/tree/main/modules/invite-from-csv) module and the [metal](https://github.com/equinix-labs/terraform-equinix-labs/tree/main/modules/metal) module. In this example, each user identified in the `users.csv` file (see users.csv.example) will have a project provisioned and an invitation sent by email to join that project. Kubernetes will then be provisioned into each user's project with the configurations set within the [variables.tf](./variables.tf) file.
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -27,11 +29,11 @@ No resources.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
-| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 | <a name="input_enable_metal"></a> [enable\_metal](#input\_enable\_metal) | Enable Metal module | `bool` | `true` | no |
 | <a name="input_enable_workshop_setup"></a> [enable\_workshop\_setup](#input\_enable\_workshop\_setup) | Enable Workshop Setup module | `bool` | `true` | no |
+| <a name="input_metal_auth_token"></a> [metal\_auth\_token](#input\_metal\_auth\_token) | Equinix Metal user api token. | `string` | n/a | yes |
 | <a name="input_metal_config"></a> [metal\_config](#input\_metal\_config) | Configuration for Metal Setup config | <pre>object({<br>    device_count  = number<br>    os            = string<br>    billing_cycle = string<br>    cluster_name  = string<br>    device_type   = string<br>  })</pre> | <pre>{<br>  "billing_cycle": "hourly",<br>  "cluster_name": "metal-cluster",<br>  "device_count": 3,<br>  "device_type": "m3.small.x86",<br>  "os": "ubuntu_20_04"<br>}</pre> | no |
+| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 
 ## Outputs
 

main.tf

@@ -3,14 +3,22 @@ terraform {
   required_version = ">= 1.3"
 }
 
+# ---------------------------------------------------------------------------------------------------------------------
+# Project Setup
+# ---------------------------------------------------------------------------------------------------------------------
+
 # Setup Project for deploying metal or EKSA
 module "project_setup" {
   count                 = var.enable_workshop_setup ? 1 : 0
   source                = "./modules/invite-from-csv"
   metal_organization_id = var.metal_organization_id
 }
 
-# Deploy the metal module if platform of choice is metal
+# ---------------------------------------------------------------------------------------------------------------------
+# Platforms
+# ---------------------------------------------------------------------------------------------------------------------
+
+# Deploy the metal module if platform of choice is Metal
 module "deploy_metal" {
   count  = var.enable_metal ? 1 : 0
   source = "./modules/metal"
@@ -19,7 +27,7 @@ module "deploy_metal" {
   module_config  = var.metal_config
 }
 
-# Deploy the eksa module if platform of choice is eksa
+# Deploy the eksa module if platform of choice is EKSA
 module "deploy_eksa" {
   count  = var.enable_eksa ? 1 : 0
   source = "./modules/eksa"

modules/README.md

@@ -1,5 +1,7 @@
 # Terraform Equinix Labs Collaborator Project Module
 
+This module creates a project with collaborator users, sends each user an inviation for each user to join their project, and assigns those users `limited_collaborator` role.
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -12,7 +14,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="provider_equinix"></a> [equinix](#provider\_equinix) | >= 1.10.0 |
+| <a name="provider_equinix"></a> [equinix](#provider\_equinix) | 1.14.1 |
 
 ## Modules
 
@@ -31,8 +33,8 @@ No modules.
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_collaborator"></a> [collaborator](#input\_collaborator) | Collaborator email to join the organization | `string` | n/a | yes |
-| <a name="input_module_context"></a> [module\_context](#input\_module\_context) | Input context for the module | <pre>object({<br>    organization_id = string<br>  })</pre> | n/a | yes |
 | <a name="input_module_config"></a> [module\_config](#input\_module\_config) | Module configuration for Collaborator module | `any` | <pre>{<br>  "send_invites": true<br>}</pre> | no |
+| <a name="input_module_context"></a> [module\_context](#input\_module\_context) | Input context for the module | <pre>object({<br>    organization_id = string<br>  })</pre> | n/a | yes |
 
 ## Outputs
 

modules/collaborator-project/README.md

@@ -1,5 +1,7 @@
 # Terraform Equinix Labs EKS-A Module
 
+This module utilizes the [metal-eks-anywhere](https://registry.terraform.io/modules/equinix-labs/metal-eks-anywhere/equinix/latest) module to deploy AWS EKS-A.
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -25,8 +27,8 @@ No resources.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_module_context"></a> [module\_context](#input\_module\_context) | Input context for the module | <pre>object({<br>    metal_api_token = string<br>    project_id      = string<br>    metro           = string<br>    tags            = list(string)<br>  })</pre> | n/a | yes |
 | <a name="input_module_config"></a> [module\_config](#input\_module\_config) | Module configuration for EKSA module | <pre>object({<br>    cluster_name        = string<br>    cp_device_count     = number<br>    worker_device_count = number<br>  })</pre> | <pre>{<br>  "cluster_name": "eksa-workshop-cluster",<br>  "cp_device_count": 1,<br>  "worker_device_count": 1<br>}</pre> | no |
+| <a name="input_module_context"></a> [module\_context](#input\_module\_context) | Input context for the module | <pre>object({<br>    metal_api_token = string<br>    project_id      = string<br>    metro           = string<br>    tags            = list(string)<br>  })</pre> | n/a | yes |
 
 ## Outputs
 

modules/eksa/README.md

@@ -14,5 +14,4 @@ module "eksa" {
   cluster_name        = var.module_config.cluster_name
   cp_device_count     = var.module_config.cp_device_count
   worker_device_count = var.module_config.worker_device_count
-
 }

modules/eksa/main.tf

@@ -1,5 +1,7 @@
 # Terraform Equinix Labs Invite from CSV Module
 
+This module reads a given filename `users.csv`, identifies each user entry in the file, then calls [collaborator-project](../collaborator-project/) module to create a project for them.
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -12,7 +14,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="provider_equinix"></a> [equinix](#provider\_equinix) | >= 1.10.0 |
+| <a name="provider_equinix"></a> [equinix](#provider\_equinix) | 1.14.1 |
 
 ## Modules
 
@@ -30,8 +32,8 @@
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 | <a name="input_csv_file"></a> [csv\_file](#input\_csv\_file) | Path to a CSV file containing a list of projects to provision: email,metro,plan. Email address is used as the project name and the collaborator. Metro and plan are used to provision the project. | `string` | `"users.csv"` | no |
+| <a name="input_metal_organization_id"></a> [metal\_organization\_id](#input\_metal\_organization\_id) | Equinix Metal organization id | `string` | n/a | yes |
 
 ## Outputs