Merge pull request #2 from SamuelBagattin/feature/documentation

Added detailed documentation and examples +semver:patch

Author: SamuelBagattin

.terraform-docs.yml

@@ -1,10 +1,12 @@
 formatter: "markdown table"
 
-header-from: main.tf
-
 output:
   file: "./README.md"
-  mode: replace
+  mode: inject
+  template: |-
+    <!-- BEGIN_TF_DOCS -->
+    {{ .Content }}
+    <!-- END_TF_DOCS -->
 
 recursive:
   enabled: true

README.md

@@ -1,3 +1,63 @@
+
+# AWS Github OIDC Provider Terraform Module
+
+## Purpose
+This module allows you to create a GitHub OIDC provider and the associated IAM roles, that will help Github Actions to securely authenticate against the AWS API using an IAM role
+
+## Features
+* Create an AWS OIDC provider for GitHub Actions
+* Create one or more IAM role that can be assumed by GitHub Actions
+* IAM roles can be scoped to :
+  * One or more GitHub organisations
+  * One or more GitHub repository
+  * One or more branches in a repository
+
+| Feature                                                                                                | Status |
+|--------------------------------------------------------------------------------------------------------|--------|
+| Create a role for all repositories in a specific Github organisation                                   | ✅      |
+| Create a role specific to a repository for a specific organisation                                     | ✅      |
+| Create a role specific to a branch in a repository                                                     | ✅      |
+| Create a role for multiple organisations/repositories/branches                                         | ✅      |
+| Create a role for organisations/repositories/branches selected by wildcard (e.g. `feature/*` branches) | ✅      | 
+| Create multiple roles for a repository, each one with his own set of branches                          | ❌      |
+| Create the OIDC provider and multiple roles configurations in separate terraform root modules          | ✅      |
+
+## Usage
+TL;DR :
+```hcl
+module "aws_github_actions_oidc" {
+  source  = "registry.terraform.io/SamuelBagattin/github-oidc-provider/aws"
+  permissions = {
+    "my-org" : { # Specify the GitHub organisation name
+      role_name = "default-org-role" # Default role name for subsequent repositories
+      allowed_branches = ["main"] # Default branches for subsequent repositories
+      repositories = {
+        "my-repository" = { # GitHub repository name
+          role_name : "my-role" # IAM role specific to a repository
+          allowed_branches : ["my-branch","my-other-branch", "feature/*"] # List of branches allowed to assume the specific role
+        }
+        "another-repository" = {} # Will inherit role_name and allowed_branches from the organisation
+      }
+    }
+    # The wildcard "*" can be used to allow any org, repository or branch
+    "*": { # Allow any organisation
+      repositories = {
+        "*": { # Allow any repository
+          role_name : "my-role"
+          allowed_branches : ["*"] # Allow any branch
+        }
+      }
+    }
+  }
+}
+```
+
+For more simple or detailed use cases, please refer to the following examples :
+- [Simple example](./examples/simple)
+- [Complete example](./examples/complete)
+- [Separated OIDC provider and IAM roles](./examples/separate_configuration)
+
+
 <!-- BEGIN_TF_DOCS -->
 # AWS Github OIDC Provider Terraform Module
 
@@ -28,14 +88,26 @@ This module allows you to create a Github OIDC provider for your AWS account, th
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_create_iam_roles"></a> [create\_iam\_roles](#input\_create\_iam\_roles) | Whether or not to create IAM roles. | `bool` | `true` | no |
-| <a name="input_create_oidc_provider"></a> [create\_oidc\_provider](#input\_create\_oidc\_provider) | Whether or not to create the associated oidc provider. If true, variable 'oidc\_provider\_arn is required' | `bool` | `true` | no |
+| <a name="input_create_oidc_provider"></a> [create\_oidc\_provider](#input\_create\_oidc\_provider) | Whether or not to create the associated oidc provider. If true, variable 'oidc\_provider\_arn' is required | `bool` | `true` | no |
 | <a name="input_oidc_provider_arn"></a> [oidc\_provider\_arn](#input\_oidc\_provider\_arn) | Used if create\_oidc\_provider is true | `string` | `""` | no |
-| <a name="input_permissions"></a> [permissions](#input\_permissions) | Github Repositories than can assumerole | `map(any)` | n/a | yes |
+| <a name="input_permissions"></a> [permissions](#input\_permissions) | Permissions configuration. See 'Permissions specifications' below | `map(any)` | n/a | yes |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
 | <a name="output_oidc_provider_arn"></a> [oidc\_provider\_arn](#output\_oidc\_provider\_arn) | OIDC provider ARN |
 | <a name="output_roles_arns"></a> [roles\_arns](#output\_roles\_arns) | Roles to be assumed by github actions |
-<!-- END_TF_DOCS -->
+<!-- END_TF_DOCS -->
+
+## Permissions specifications
+```hcl
+permissions = map(object({
+  "role_name": string, # optional, default: "githubActions-iamRole"
+  "allowed_branches": list(string), # optional, default: ["master"]
+  "repositories": map(object({ # optional, default: ["*":{}]
+    "role_name": string, # optional, defaults to the organisation role_name
+    "allowed_branches": list(string), # optional, defaults to the organisation allowed_branches
+  }))
+}))
+```

examples/complete/README.md

@@ -0,0 +1,9 @@
+# Complete example
+This example will create the following IAM resources/configurations for the `my-org` GitHub organisation :
+- `githubActions-default-role` IAM role scoped to :
+  - `another-repository` from the `main` branches
+  - `third-repository` from the `my-branch`and `my-other-branch` branches
+- `my-role` IAM role scoped to : 
+  - `my-repository` from the `main` branch
+- `global-role` IAM role scoped to :
+  - ANY repository from any branch that begins with `feature/*`

examples/complete/main.tf

@@ -0,0 +1,34 @@
+provider "aws" {
+  region = "us-east-1"
+}
+
+terraform {
+  required_version = ">= 0.13.0"
+  required_providers {
+    aws = "~> 3.0"
+  }
+}
+
+module "aws_github_actions_oidc" {
+  source  = "registry.terraform.io/SamuelBagattin/github-oidc-provider/aws"
+  version = "0.3.0"
+  permissions = {
+    "my-org" : { # Specify the GitHub organisation name
+      role_name : "githubActions-default-role"
+      allowed_branches : ["main"]
+      repositories = {
+        "my-repository" = {     # GitHub repository name
+          role_name : "my-role" # IAM role name
+        }
+        "another-repository" = {}
+        "third-repository" = {
+          allowed_branches : ["my-branch", "my-other-branch"]
+        }
+        "*" = {
+          role_name : "global-role"
+          allowed_branches : ["feature/*"]
+        }
+      }
+    }
+  }
+}

examples/complete/outputs.tf

@@ -0,0 +1,59 @@
+config {
+  module              = false
+  force               = false
+  disabled_by_default = false
+}
+
+plugin "aws" {
+  enabled = true
+  version = "0.11.0"
+  source  = "github.com/terraform-linters/tflint-ruleset-aws"
+}
+
+rule "terraform_comment_syntax" {
+  enabled = true
+}
+
+rule "terraform_deprecated_index" {
+  enabled = true
+}
+
+rule "terraform_deprecated_interpolation" {
+  enabled = true
+}
+
+rule "terraform_documented_outputs" {
+  enabled = true
+}
+
+rule "terraform_documented_variables" {
+  enabled = true
+}
+
+rule "terraform_module_pinned_source" {
+  enabled = true
+}
+
+rule "terraform_naming_convention" {
+  enabled = true
+}
+
+rule "terraform_required_providers" {
+  enabled = true
+}
+
+rule "terraform_standard_module_structure" {
+  enabled = true
+}
+
+rule "terraform_typed_variables" {
+  enabled = true
+}
+
+rule "terraform_unused_declarations" {
+  enabled = true
+}
+
+rule "terraform_unused_required_providers" {
+  enabled = true
+}

examples/complete/tflint.hcl

@@ -0,0 +1,6 @@
+# Separated configuration
+This example show how the OIDC provider and the IAM roles can be created separately :
+1. Creates the OIDC provider
+2. Stores the ARN of the OIDC provider in an SSM parameter
+3. Retrieves the ARN of the OIDC provider from the SSM parameter in another root module
+4. Creates the IAM role and attaches it to the OIDC provider

examples/complete/variables.tf

@@ -0,0 +1,24 @@
+provider "aws" {
+  region = "us-east-1"
+}
+
+terraform {
+  required_version = ">= 0.13.0"
+  required_providers {
+    aws = "~> 3.0"
+  }
+}
+
+module "aws_github_actions_oidc" {
+  source               = "registry.terraform.io/SamuelBagattin/github-oidc-provider/aws"
+  version              = "0.3.0"
+  create_oidc_provider = true
+  create_iam_roles     = false
+  permissions          = {}
+}
+
+resource "aws_ssm_parameter" "github_actions_oidc_provider_arn" {
+  name  = "githubActions-oidcProviderArn-ssmParam"
+  type  = "String"
+  value = module.aws_github_actions_oidc.oidc_provider_arn
+}