chore: adding a basic example and updating the documentation

README.md

@@ -1,21 +1,45 @@
 ![Github Actions](../../actions/workflows/terraform.yml/badge.svg)
 
-# Terraform <NAME>
+# Terraform Nuke Module
 
 ## Description
 
-Add a description of the module here
+The purpose of this module is to provide a method of automated cleanup of resources, using the [aws-nuke](https://ekristen.github.io/aws-nuke/) tool. This module will create a scheduled task that will run an ECS task on a regular basis to clean up resources that are no longer needed.
+
+It is intended to be used in a non-production environment, such as a development or testing account, to ensure that resources are not left running and incurring costs when they are no longer needed.
 
 ## Usage
 
-Add example usage here
+The following provides an example of how to use this module:
 
 ```hcl
-module "example" {
-  source  = "appvia/<NAME>/aws"
-  version = "0.0.1"
-
-  # insert variables here
+module "nuke" {
+  source = "github.com/appvia/terraform-aws-nuke?ref=main"
+
+  ## Indicates if we should create a KMS key for the log group
+  create_kms_key = false
+  ## Indicates if the schedule is enabled
+  enabled        = true
+  ## This is the location of the aws-nuke configuration file, this is
+  ## copied into the container via a parameter store value
+  nuke_configuration = file("${path.module}/assets/nuke-config.yml.example")
+  ## This will create a task that runs every day at midnight
+  schedule_expression = "cron(0 0 * * ? *)"
+  ## The tags to apply to resources created by this module
+  tags = {
+    "Environment" = "Testing"
+    "GitRepo"     = "https://github.com/appvia/terraform-aws-nuke"
+    "Owner"       = "Testing"
+    "Product"     = "Terraform AWS Nuke"
+  }
+  ## This will create an VPC called 'nuke' with 2 availability zones
+  ## and a private netmask of 28
+  network = {
+    name               = "nuke"
+    availability_zones = 2
+    private_netmask    = 28
+    vpc_cidr           = "172.16.0.0/25"
+  }
 }
 ```
 
@@ -91,7 +115,7 @@ The `terraform-docs` utility is used to generate this README. Follow the below s
 | <a name="input_log_group_kms_key_id"></a> [log\_group\_kms\_key\_id](#input\_log\_group\_kms\_key\_id) | The KMS key id to use for encrypting the log group | `string` | `null` | no |
 | <a name="input_log_group_name"></a> [log\_group\_name](#input\_log\_group\_name) | The name of the log group to create | `string` | `"nuke"` | no |
 | <a name="input_log_retention_in_days"></a> [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | The number of days to retain logs for | `number` | `7` | no |
-| <a name="input_network"></a> [network](#input\_network) | The network to use for the endpoints and optinal resolvers | <pre>object({<br/>    availability_zones = optional(number, 2)<br/>    # Indicates if we should create a new network or reuse an existing one<br/>    enable_default_route_table_association = optional(bool, true)<br/>    # Whether to associate the default route table  <br/>    enable_default_route_table_propagation = optional(bool, true)<br/>    # Whether to propagate the default route table<br/>    ipam_pool_id = optional(string, null)<br/>    # The id of the ipam pool to use when creating the network<br/>    name = optional(string, "nuke")<br/>    # The name of the network to create<br/>    private_netmask = optional(number, 28)<br/>    # The ids of the private subnets to if we are reusing an existing network<br/>    transit_gateway_id = optional(string, "")<br/>    ## The transit gateway id to use for the network<br/>    vpc_cidr = optional(string, "")<br/>    # The vpc id to use when reusing an existing network <br/>    vpc_netmask = optional(number, null)<br/>    # When using ipam this the netmask to use for the VPC<br/>  })</pre> | `null` | no |
+| <a name="input_network"></a> [network](#input\_network) | The network to use for the endpoints and optinal resolvers | <pre>object({<br/>    availability_zones = optional(number, 2)<br/>    # The id of the ipam pool to use when creating the network<br/>    name = optional(string, "nuke")<br/>    # The name of the network to create<br/>    private_netmask = optional(number, 28)<br/>    ## The transit gateway id to use for the network<br/>    vpc_cidr = optional(string, "")<br/>    # The vpc id to use when reusing an existing network <br/>  })</pre> | `null` | no |
 | <a name="input_schedule_expression"></a> [schedule\_expression](#input\_schedule\_expression) | The schedule expression to use for the event rule | `string` | `"cron(0 0 * * ? *)"` | no |
 | <a name="input_task_role_additional_policies"></a> [task\_role\_additional\_policies](#input\_task\_role\_additional\_policies) | A map of inline policies to attach to the IAM role | <pre>map(object({<br/>    policy = string<br/>  }))</pre> | `null` | no |
 | <a name="input_task_role_permissions_arns"></a> [task\_role\_permissions\_arns](#input\_task\_role\_permissions\_arns) | A list of permissions to attach to the IAM role | `list(string)` | <pre>[<br/>  "arn:aws:iam::aws:policy/AdministratorAccess"<br/>]</pre> | no |
@@ -101,6 +125,7 @@ The `terraform-docs` utility is used to generate this README. Follow the below s
 
 | Name | Description |
 |------|-------------|
+| <a name="output_parameter_store_arn"></a> [parameter\_store\_arn](#output\_parameter\_store\_arn) | The ARN of the parameter store containing the nuke configuration |
 | <a name="output_private_subnet_id_by_az"></a> [private\_subnet\_id\_by\_az](#output\_private\_subnet\_id\_by\_az) | The private subnets to use for the nuke service |
 | <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The VPC where the nuke service is running |
 <!-- END_TF_DOCS -->

examples/basic/README.md

@@ -12,7 +12,9 @@ No providers.
 
 ## Modules
 
-No modules.
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_nuke"></a> [nuke](#module\_nuke) | ../../ | n/a |
 
 ## Resources
 
@@ -24,5 +26,7 @@ No inputs.
 
 ## Outputs
 
-No outputs.
+| Name | Description |
+|------|-------------|
+| <a name="output_parameter_store_arn"></a> [parameter\_store\_arn](#output\_parameter\_store\_arn) | The ARN of the parameter store containing the nuke configuration |
 <!-- END_TF_DOCS -->

assets/nuke-config.yml.example → examples/basic/assets/nuke-config.yml.example

@@ -4,7 +4,7 @@ blocklist:
 
 regions:
   - global
-  - eu-west-2
+  - ${region}
 
 resource-types:
   includes:
@@ -401,7 +401,8 @@ presets:
           value: "^CID-DC.*"
 
 accounts:
-  503440911135:
+  ## Provided to the template function
+  ${account_id}:
     presets:
       - cloud-intelligence
       - control-tower

examples/basic/main.tf

@@ -3,3 +3,33 @@
 # per use-case. The code below should not be copied directly but referenced in order
 # to build your own root module that invokes this module
 #####################################################################################
+
+module "nuke" {
+  source = "../../"
+
+  create_kms_key = false
+  enabled        = true
+
+  ## This is the location of the aws-nuke configuration file, this is 
+  ## copied into the container via a parameter store value
+  nuke_configuration = file("${path.module}/assets/nuke-config.yml.example")
+
+  ## This will create a task that runs every day at midnight
+  schedule_expression = "cron(0 0 * * ? *)"
+
+  tags = {
+    "Environment" = "Testing"
+    "GitRepo"     = "https://github.com/appvia/terraform-aws-nuke"
+    "Owner"       = "Testing"
+    "Product"     = "Terraform AWS Nuke"
+  }
+
+  ## This will create an VPC called 'nuke' with 2 availability zones 
+  ## and a private netmask of 28
+  network = {
+    name               = "nuke"
+    availability_zones = 2
+    private_netmask    = 28
+    vpc_cidr           = "172.16.0.0/25"
+  }
+}

examples/basic/outputs.tf

@@ -0,0 +1,5 @@
+
+output "parameter_store_arn" {
+  description = "The ARN of the parameter store containing the nuke configuration"
+  value       = module.nuke.parameter_store_arn
+}

main.tf

@@ -5,18 +5,16 @@ module "vpc" {
   source  = "appvia/network/aws"
   version = "0.3.1"
 
-  availability_zones                     = var.network.availability_zones
-  enable_default_route_table_association = var.network.enable_default_route_table_association
-  enable_default_route_table_propagation = var.network.enable_default_route_table_propagation
-  enable_ipam                            = var.network.ipam_pool_id != null ? true : false
-  enable_transit_gateway                 = true
-  ipam_pool_id                           = var.network.ipam_pool_id
-  name                                   = var.network.name
-  private_subnet_netmask                 = var.network.private_netmask
-  tags                                   = var.tags
-  transit_gateway_id                     = var.network.transit_gateway_id
-  vpc_cidr                               = var.network.vpc_cidr
-  vpc_netmask                            = var.network.vpc_netmask
+  availability_zones     = var.network.availability_zones
+  enable_ipam            = false
+  enable_transit_gateway = false
+  ipam_pool_id           = null
+  name                   = var.network.name
+  private_subnet_netmask = var.network.private_netmask
+  tags                   = var.tags
+  transit_gateway_id     = null
+  vpc_cidr               = var.network.vpc_cidr
+  vpc_netmask            = null
 }
 
 ## Provision a KMS for the log group to use, if required 

outputs.tf

@@ -1,10 +1,16 @@
 
-output "vpc_id" {
-  description = "The VPC where the nuke service is running"
-  value       = local.vpc_id
+output "parameter_store_arn" {
+  description = "The ARN of the parameter store containing the nuke configuration"
+  value       = aws_ssm_parameter.configuration.arn
 }
 
 output "private_subnet_id_by_az" {
   description = "The private subnets to use for the nuke service"
   value       = local.private_subnet_id_by_az
 }
+
+output "vpc_id" {
+  description = "The VPC where the nuke service is running"
+  value       = local.vpc_id
+}
+

tests/module.tftest.hcl

@@ -19,7 +19,7 @@ run "basic" {
       vpc_cidr           = "10.90.0.0/21"
       transit_gateway_id = "tgw-04ad8f026be8b7eb6"
     }
-    nuke_configuration = "./assets/nuke-config.yml.example"
+    nuke_configuration = "./examples/basic/assets/nuke-config.yml.example"
     tags = {
       "Environment" = "Testing"
       "GitRepo"     = "https://github.com/appvia/terraform-aws-dns"

variables.tf

@@ -113,23 +113,13 @@ variable "network" {
   description = "The network to use for the endpoints and optinal resolvers"
   type = object({
     availability_zones = optional(number, 2)
-    # Indicates if we should create a new network or reuse an existing one
-    enable_default_route_table_association = optional(bool, true)
-    # Whether to associate the default route table  
-    enable_default_route_table_propagation = optional(bool, true)
-    # Whether to propagate the default route table
-    ipam_pool_id = optional(string, null)
     # The id of the ipam pool to use when creating the network
     name = optional(string, "nuke")
     # The name of the network to create
     private_netmask = optional(number, 28)
-    # The ids of the private subnets to if we are reusing an existing network
-    transit_gateway_id = optional(string, "")
     ## The transit gateway id to use for the network
     vpc_cidr = optional(string, "")
     # The vpc id to use when reusing an existing network 
-    vpc_netmask = optional(number, null)
-    # When using ipam this the netmask to use for the VPC
   })
   default = null
 }