From 23a96e874318614f185797191586e4327f4782e3 Mon Sep 17 00:00:00 2001 From: Anton Babenko Date: Mon, 17 Dec 2018 09:52:18 +0100 Subject: [PATCH] Added pre-commit-terraform to update docs (#217) * Added pre-commit-terraform to update docs * Updated .github/PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 1 - .pre-commit-config.yaml | 27 ++++----- README.md | 32 +++++----- main.tf | 101 ------------------------------- 4 files changed, 28 insertions(+), 133 deletions(-) delete mode 100644 main.tf diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9cffbd4..5a32376 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,6 +9,5 @@ Please explain the changes you made here and link to any relevant issues. - [ ] `terraform fmt` and `terraform validate` both work from the root and `examples/eks_test_fixture` directories (look in CI for an example) - [ ] Tests for the changes have been added and passing (for bug fixes/features) - [ ] Test results are pasted in this PR (in lieu of CI) -- [ ] Docs have been updated using `terraform-docs` per `README.md` instructions - [ ] I've added my change to CHANGELOG.md - [ ] Any breaking changes are highlighted above diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1064dd4..911dd1f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,16 +1,13 @@ -# See http://pre-commit.com for more information -# See http://pre-commit.com/hooks.html for more hooks repos: -- repo: git://github.com/antonbabenko/pre-commit-terraform - rev: v1.7.1 - hooks: - - id: terraform_fmt - # - id: terraform_docs -- repo: git://github.com/pre-commit/pre-commit-hooks - rev: v1.2.3 - hooks: - - id: check-merge-conflict - - id: trailing-whitespace - # - id: end-of-file-fixer - - id: check-yaml - - id: check-added-large-files + - repo: git://github.com/antonbabenko/pre-commit-terraform + rev: v1.7.4 + hooks: + - id: terraform_fmt + - id: terraform_docs + - repo: git://github.com/pre-commit/pre-commit-hooks + rev: v2.0.0 + hooks: + - id: check-merge-conflict + - id: trailing-whitespace + - id: check-yaml + - id: check-added-large-files diff --git a/README.md b/README.md index 48f71e2..c0cbd9d 100644 --- a/README.md +++ b/README.md @@ -65,13 +65,11 @@ kubectl get nodes --watch --kubeconfig kubeconfig ## Doc generation -Documentation should be modified within `main.tf` and generated using [terraform-docs](https://github.com/segmentio/terraform-docs). +Code formatting and documentation for variables and outputs is generated using [pre-commit-terraform hooks](https://github.com/antonbabenko/pre-commit-terraform) which uses [terraform-docs](https://github.com/segmentio/terraform-docs). -Install it with `go get github.com/segmentio/terraform-docs` or `brew install terraform-docs` and then use it to generate the `README.md` file: +Follow [these instructions](https://github.com/antonbabenko/pre-commit-terraform#how-to-install) to install pre-commit locally. -``` -terraform-docs --with-aggregate-type-defaults md ./ | sed -e '$ d' -e 'N;/^\n$/D;P;D' > README.md -``` +And install `terraform-docs` with `go get github.com/segmentio/terraform-docs` or `brew install terraform-docs`. ## Contributing @@ -97,6 +95,7 @@ Many thanks to [the contributors listed here](https://github.com/terraform-aws-m MIT Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/LICENSE) for full details. + ## Inputs | Name | Description | Type | Default | Required | @@ -108,29 +107,29 @@ MIT Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-a | cluster\_security\_group\_id | If provided, the EKS cluster will be attached to this security group. If not given, a security group will be created with necessary ingres/egress to work with the workers and provide API access to your current IP/32. | string | `` | no | | cluster\_version | Kubernetes version to use for the EKS cluster. | string | `1.10` | no | | config\_output\_path | Where to save the Kubectl config file (if `write_kubeconfig = true`). Should end in a forward slash `/` . | string | `./` | no | -| kubeconfig\_aws\_authenticator\_additional\_args | Any additional arguments to pass to the authenticator such as the role to assume. e.g. ["-r", "MyEksRole"]. | list | `` | no | +| kubeconfig\_aws\_authenticator\_additional\_args | Any additional arguments to pass to the authenticator such as the role to assume. e.g. ["-r", "MyEksRole"]. | list | `[]` | no | | kubeconfig\_aws\_authenticator\_command | Command to use to to fetch AWS EKS credentials. | string | `aws-iam-authenticator` | no | -| kubeconfig\_aws\_authenticator\_command\_args | Default arguments passed to the authenticator command. Defaults to [token -i $cluster_name]. | list | `` | no | -| kubeconfig\_aws\_authenticator\_env\_variables | Environment variables that should be used when executing the authenticator. e.g. { AWS_PROFILE = "eks"}. | map | `` | no | +| kubeconfig\_aws\_authenticator\_command\_args | Default arguments passed to the authenticator command. Defaults to [token -i $cluster_name]. | list | `[]` | no | +| kubeconfig\_aws\_authenticator\_env\_variables | Environment variables that should be used when executing the authenticator. e.g. { AWS_PROFILE = "eks"}. | map | `{}` | no | | kubeconfig\_name | Override the default name used for items kubeconfig. | string | `` | no | -| local\_exec\_interpreter | Command to run for local-exec resources. Must be a shell-style interpreter. If you are on Windows Git Bash is a good choice. | list | `` | no | +| local\_exec\_interpreter | Command to run for local-exec resources. Must be a shell-style interpreter. If you are on Windows Git Bash is a good choice. | list | `[ "/bin/sh", "-c" ]` | no | | manage\_aws\_auth | Whether to write and apply the aws-auth configmap file. | string | `true` | no | -| map\_accounts | Additional AWS account numbers to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `` | no | +| map\_accounts | Additional AWS account numbers to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `[]` | no | | map\_accounts\_count | The count of accounts in the map_accounts list. | string | `0` | no | -| map\_roles | Additional IAM roles to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `` | no | +| map\_roles | Additional IAM roles to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `[]` | no | | map\_roles\_count | The count of roles in the map_roles list. | string | `0` | no | -| map\_users | Additional IAM users to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `` | no | +| map\_users | Additional IAM users to add to the aws-auth configmap. See examples/eks_test_fixture/variables.tf for example format. | list | `[]` | no | | map\_users\_count | The count of roles in the map_users list. | string | `0` | no | | subnets | A list of subnets to place the EKS cluster and workers within. | list | - | yes | -| tags | A map of tags to add to all resources. | map | `` | no | +| tags | A map of tags to add to all resources. | map | `{}` | no | | vpc\_id | VPC where the cluster and workers will be deployed. | string | - | yes | -| worker\_additional\_security\_group\_ids | A list of additional security group ids to attach to worker instances | list | `` | no | +| worker\_additional\_security\_group\_ids | A list of additional security group ids to attach to worker instances | list | `[]` | no | | worker\_create\_security\_group | Whether to create a security group for the workers or attach the workers to `worker_security_group_id`. | string | `true` | no | | worker\_group\_count | The number of maps contained within the worker_groups list. | string | `1` | no | -| worker\_groups | A list of maps defining worker group configurations. See workers_group_defaults for valid keys. | list | `` | no | +| worker\_groups | A list of maps defining worker group configurations. See workers_group_defaults for valid keys. | list | `[ { "name": "default" } ]` | no | | worker\_security\_group\_id | If provided, all workers will be attached to this security group. If not given, a security group will be created with necessary ingres/egress to work with the EKS cluster. | string | `` | no | | worker\_sg\_ingress\_from\_port | Minimum port number from which pods will accept communication. Must be changed to a lower value if some pods in your cluster will expose a port lower than 1025 (e.g. 22, 80, or 443). | string | `1025` | no | -| workers\_group\_defaults | Override default values for target groups. See workers_group_defaults_defaults in locals.tf for valid keys. | map | `` | no | +| workers\_group\_defaults | Override default values for target groups. See workers_group_defaults_defaults in locals.tf for valid keys. | map | `{}` | no | | write\_kubeconfig | Whether to write a Kubectl config file containing the cluster configuration. Saved to `config_output_path`. | string | `true` | no | ## Outputs @@ -149,3 +148,4 @@ MIT Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-a | worker\_security\_group\_id | Security group ID attached to the EKS workers. | | workers\_asg\_arns | IDs of the autoscaling groups containing workers. | | workers\_asg\_names | Names of the autoscaling groups containing workers. | + diff --git a/main.tf b/main.tf deleted file mode 100644 index d5d039a..0000000 --- a/main.tf +++ /dev/null @@ -1,101 +0,0 @@ -/** -# terraform-aws-eks - -* A terraform module to create a managed Kubernetes cluster on AWS EKS. Available -* through the [Terraform registry](https://registry.terraform.io/modules/terraform-aws-modules/eks/aws). -* Inspired by and adapted from [this doc](https://www.terraform.io/docs/providers/aws/guides/eks-getting-started.html) -* and its [source code](https://github.com/terraform-providers/terraform-provider-aws/tree/master/examples/eks-getting-started). -* Read the [AWS docs on EKS to get connected to the k8s dashboard](https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html). - -* | Branch | Build status | -* | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -* | master | [![build Status](https://travis-ci.org/terraform-aws-modules/terraform-aws-eks.svg?branch=master)](https://travis-ci.org/terraform-aws-modules/terraform-aws-eks) | - -* ## Assumptions - -** You want to create an EKS cluster and an autoscaling group of workers for the cluster. -** You want these resources to exist within security groups that allow communication and coordination. These can be user provided or created within the module. -** You've created a Virtual Private Cloud (VPC) and subnets where you intend to put the EKS resources. -** If `manage_aws_auth = true`, it's required that both [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) (>=1.10) and [`aws-iam-authenticator`](https://github.com/kubernetes-sigs/aws-iam-authenticator#4-set-up-kubectl-to-use-authentication-tokens-provided-by-aws-iam-authenticator-for-kubernetes) are installed and on your shell's PATH. - -* ## Usage example - -* A full example leveraging other community modules is contained in the [examples/eks_test_fixture directory](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/examples/eks_test_fixture). Here's the gist of using it via the Terraform registry: - -* ```hcl -* module "eks" { -* source = "terraform-aws-modules/eks/aws" -* cluster_name = "test-eks-cluster" -* subnets = ["subnet-abcde012", "subnet-bcde012a"] -* tags = {Environment = "test"} -* vpc_id = "vpc-abcde012" -* } -* ``` - -* ## Other documentation -* -* - [Autoscaling](docs/autoscaling.md): How to enabled worker node autoscaling. - -* ## Release schedule - -* Generally the maintainers will try to release the module once every 2 weeks to -* keep up with PR additions. If particularly pressing changes are added or maintainers -* come up with the spare time (hah!), release may happen more often on occasion. - -* ## Testing - -* This module has been packaged with [awspec](https://github.com/k1LoW/awspec) tests through [kitchen](https://kitchen.ci/) and [kitchen-terraform](https://newcontext-oss.github.io/kitchen-terraform/). To run them: - -* 1. Install [rvm](https://rvm.io/rvm/install) and the ruby version specified in the [Gemfile](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/Gemfile). -* 2. Install bundler and the gems from our Gemfile: -* -* ```bash -* gem install bundler && bundle install -* ``` -* -* 3. Ensure your AWS environment is configured (i.e. credentials and region) for test. -* 4. Test using `bundle exec kitchen test` from the root of the repo. - -* For now, connectivity to the kubernetes cluster is not tested but will be in the -* future. Once the test fixture has converged, you can query the test cluster from -* that terminal session with -* ```bash -* kubectl get nodes --watch --kubeconfig kubeconfig -* ``` -* (using default settings `config_output_path = "./"` & `write_kubeconfig = true`) - -* ## Doc generation - -* Documentation should be modified within `main.tf` and generated using [terraform-docs](https://github.com/segmentio/terraform-docs). -* -* Install it with `go get github.com/segmentio/terraform-docs` or `brew install terraform-docs` and then use it to generate the `README.md` file: -* -* ``` -* terraform-docs --with-aggregate-type-defaults md ./ | sed -e '$ d' -e 'N;/^\n$/D;P;D' > README.md -* ``` - -* ## Contributing - -* Report issues/questions/feature requests on in the [issues](https://github.com/terraform-aws-modules/terraform-aws-eks/issues/new) section. - -* Full contributing [guidelines are covered here](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/CONTRIBUTING.md). - -* ## IAM Permissions - -* Testing and using this repo requires a minimum set of IAM permissions. Test permissions -* are listed in the [eks_test_fixture README](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/examples/eks_test_fixture/README.md). - -* ## Change log - -* The [changelog](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/CHANGELOG.md) captures all important release notes. - -* ## Authors - -* Created and maintained by [Brandon O'Connor](https://github.com/brandoconnor) - brandon@atscale.run. -* Many thanks to [the contributors listed here](https://github.com/terraform-aws-modules/terraform-aws-eks/graphs/contributors)! - -* ## License - -* MIT Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-eks/tree/master/LICENSE) for full details. -*/ -