add docs

terraform-ncloud-modules · Oct 5, 2022 · 1161b2f · 1161b2f
1 parent 1b50a15
commit 1161b2f
Show file tree

Hide file tree

Showing 4 changed files with 250 additions and 132 deletions.
diff --git a/README.md b/README.md
@@ -1,127 +1,8 @@
-# Ncloud ACG Terraform module
+# Ncloud Access Control Group Terraform module
 
-## Module Usage
-
-You can manage ACGs using ACG module. But you can also manage ACGs within VPC module ([terraform-ncloud-modules/vpc/ncloud](https://registry.terraform.io/modules/terraform-ncloud-modules/vpc/ncloud)). The latter way is a little easier.
-
-### `main.tf`
-
-#### The ACG module support only multiple ACGs.
-``` hcl
-module "access_control_groups" {
-  source = "./terraform-ncloud-acg"
-
-  // Required
-  access_control_groups = [for acg in var.access_control_groups :
-    {
-      name           = acg.name
-      description    = acg.description
-      vpc_id         = module.vpc.vpc.id   // see "vpc_id reference scenario" below
-      inbound_rules  = acg.inbound_rules
-      outbound_rules = acg.outbound_rules
-    }
-  ]
-}
-```
-
-### vpc_id reference scenario
-
-with single VPC module (terraform-ncloud-modules/vpc/ncloud)
-``` hcl
-//variable
-# vpc_name = "vpc-sample"  (comment out)
-
-//module
-vpc_id = module.vpc.vpc.id
-```
-
-with multiple VPC module (terraform-ncloud-modules/vpc/ncloud)
-``` hcl
-//variable
-vpc_name = "vpc-sample"
-
-//module
-vpc_id = module.vpcs[acg.vpc_name].vpc.id
-```
-
-or you can just type vpc_id manually
-``` hcl
-//variable
-# vpc_name = "vpc-sample"  (comment out)
-vpc_id = "25322"           (add new)
-
-//module
-vpc_id = acg.vpc_id
-```
-
-
-
-## Variable Declaration
-
-### `terraform.tfvars`
-You can create `terraform.tfvars` and refer to the sample below to write variable specifications.
-``` hcl
-
-// Optional, Allow multiple
-// You can manage ACG within the VPC module (terraform-ncloud-modules/vpc/ncloud)
-// The order of writing inbound_rules & outbound_rules is as follows.
-// [protocol, ip_block|source_access_control_group, port_range, description]
-access_control_groups = [
-  {
-    name        = string
-    description = string
-    vpc_name    = string   // see "vpc_id reference scenario" above
-    inbound_rules = [
-      [
-        string,            // TCP | UDP | ICMP
-        string,            // CIDR | AccessControlGroupName
-        integer|string,    // PortNumber(22) | PortRange(1-65535)
-        string
-      ]
-    ]
-    outbound_rules = []    // same as above
-  }
-]  
-
-```
-
-
-#### Example
-``` hcl
-access_control_groups = [
-  {
-    name        = "acg-sample-public"
-    description = "ACG for public servers"
-    vpc_name    = "vpc-sample"
-    inbound_rules = [
-      ["TCP", "0.0.0.0/0", 22, "SSH allow form any"]
-    ]
-    outbound_rules = [
-      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
-      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
-    ]
-  },
-  {
-    name        = "acg-sample-private"
-    description = "ACG for private servers"
-    vpc_name    = "vpc-sample"
-    inbound_rules = [
-      ["TCP", "acg-sample-public", 22, "SSH allow form acg-sample-public"]
-    ]
-    outbound_rules = [
-      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
-      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
-    ]
-  }
-]
-
-
-```
-
-### `variable.tf`
-You also need to create `variable.tf` to enable `terraform.tfvars`
-``` hcl
-variable "access_control_groups" {}
-```
+You can use this module to create multiple Access Control Group. Choose one of the scenarios below.
 
+This module is intended to be used together with the [VPC module](https://registry.terraform.io/modules/terraform-ncloud-modules/vpc/ncloud/latest). Choose one of the two scenarios below depending on whether you are using [single VPC module](https://github.com/terraform-ncloud-modules/terraform-ncloud-vpc/blob/master/docs/single-vpc.md) or [multiple VPC module](https://github.com/terraform-ncloud-modules/terraform-ncloud-vpc/blob/master/docs/multiple-vpc.md).
 
+- [ACG module with Single VPC module](https://github.com/terraform-ncloud-modules/terraform-ncloud-acg/blob/master/docs/with-single-vpc-module.md)
+- [ACG module with Multiple VPC module](https://github.com/terraform-ncloud-modules/terraform-ncloud-acg/blob/master/docs/with-multiple-vpc-module.md)
diff --git a/docs/with-multiple-vpc-module.md b/docs/with-multiple-vpc-module.md
@@ -0,0 +1,112 @@
+# ACG Module with multiple VPC Module
+
+This document describes the Terraform module that creates `Ncloud Access Control Groups`.
+If you want to use `ACG module` with [multiple VPC Module](https://github.com/terraform-ncloud-modules/terraform-ncloud-vpc/blob/master/docs/multiple-vpc.md), please refer to this article.
+
+## Variable Declaration
+
+### `variable.tf`
+
+You need to create `variable.tf` and declare the ACG variable to recognize ACG variable in `terraform.tfvars`. You can change the variable name to whatever you want.
+
+``` hcl
+variable "access_control_groups" {}
+```
+
+### `terraform.tfvars`
+
+You can create `terraform.tfvars` and refer to the sample below to write variable declarations.
+File name can be `terraform.tfvars` or anything ending in `.auto.tfvars`
+
+#### Structure
+
+Unlike [ACG Module with single VPC Module](https://github.com/terraform-ncloud-modules/terraform-ncloud-acg/blob/master/docs/with-single-vpc-module.md), `ACG Module with multiple VPC Module` requires `vpc_name` additionally.
+
+``` hcl
+// ACG declaration (Optional, List)
+access_control_groups = [
+  {
+    name        = string
+    description = string
+    vpc_name    = string
+
+    // The order of writing inbound_rules & outbound_rules is as follows.
+    // [protocol, ip_block|source_access_control_group, port_range, description]
+    inbound_rules = [
+      [
+        string,            // TCP | UDP | ICMP
+        string,            // CIDR | AccessControlGroupName
+                           // Set to "default" to set "default ACG" to source_access_control_group.
+        integer|string,    // PortNumber(22) | PortRange(1-65535)
+        string
+      ]
+    ]
+    outbound_rules = []    // same as above
+  }
+]  
+
+```
+
+#### Example
+
+``` hcl
+access_control_groups = [
+  {
+    name          = "default"
+    description   = "Default ACG for vpc-multiple"
+    vpc_name      = "vpc-multiple"
+    inbound_rules = []
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  },
+  {
+    name        = "acg-multiple-public"
+    description = "ACG for public servers"
+    vpc_name    = "vpc-multiple"
+    inbound_rules = [
+      ["TCP", "0.0.0.0/0", 22, "SSH allow form any"]
+    ]
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  },
+  {
+    name        = "acg-multiple-private"
+    description = "ACG for private servers"
+    vpc_name    = "vpc-multiple"
+    inbound_rules = [
+      ["TCP", "acg-multiple-public", 22, "SSH allow form acg-multiple-public"]
+    ]
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  }
+]
+```
+
+## Module Usage
+
+### `main.tf`
+
+Map your (`ACG variable name` & `VPC module name`) to (`local ACG variable` & `local VPC variable`). `ACG module` are created using `local ACG variable`. This eliminates the need to change the variable name reference structure in the `ACG module`.
+
+``` hcl
+locals {
+  acgs = var.access_control_groups
+  vpcs = module.vpcs
+}
+```
+
+Then just copy and paste the module declaration below.
+
+``` hcl
+module "access_control_groups" {
+  source = "terraform-ncloud-modules/acg/ncloud"
+
+  access_control_groups = [for acg in local.acgs : merge(acg, { vpc_id = local.vpcs[acg.vpc_name].vpc.id })]
+}
+```
diff --git a/docs/with-single-vpc-module.md b/docs/with-single-vpc-module.md
@@ -0,0 +1,106 @@
+# ACG Module with single VPC Module
+
+This document describes the Terraform module that creates `Ncloud Access Control Groups`.
+If you want to use `ACG module` with [single VPC Module](https://github.com/terraform-ncloud-modules/terraform-ncloud-vpc/blob/master/docs/single-vpc.md), please refer to this article.
+
+## Variable Declaration
+
+### `variable.tf`
+
+You need to create `variable.tf` and declare the ACG variable to recognize ACG variable in `terraform.tfvars`. You can change the variable name to whatever you want.
+
+``` hcl
+variable "access_control_groups" {}
+```
+
+### `terraform.tfvars`
+
+You can create `terraform.tfvars` and refer to the sample below to write variable declarations.
+File name can be `terraform.tfvars` or anything ending in `.auto.tfvars`
+
+#### Structure
+
+``` hcl
+// ACG declaration (Optional, List)
+access_control_groups = [
+  {
+    name        = string
+    description = string
+
+    // The order of writing inbound_rules & outbound_rules is as follows.
+    // [protocol, ip_block|source_access_control_group, port_range, description]
+    inbound_rules = [
+      [
+        string,            // TCP | UDP | ICMP
+        string,            // CIDR | AccessControlGroupName
+                           // Set to "default" to set "default ACG" to source_access_control_group.
+        integer|string,    // PortNumber(22) | PortRange(1-65535)
+        string
+      ]
+    ]
+    outbound_rules = []    // same as above
+  }
+]  
+
+```
+
+#### Example
+
+``` hcl
+access_control_groups = [
+  {
+    name          = "default"
+    description   = "Default ACG for vpc-single"
+    inbound_rules = []
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  },
+  {
+    name        = "acg-single-public"
+    description = "ACG for public servers"
+    inbound_rules = [
+      ["TCP", "0.0.0.0/0", 22, "SSH allow form any"]
+    ]
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  },
+  {
+    name        = "acg-single-private"
+    description = "ACG for private servers"
+    inbound_rules = [
+      ["TCP", "acg-single-public", 22, "SSH allow form acg-single-public"]
+    ]
+    outbound_rules = [
+      ["TCP", "0.0.0.0/0", "1-65535", "All allow to any"],
+      ["UDP", "0.0.0.0/0", "1-65535", "All allow to any"]
+    ]
+  }
+]
+```
+
+## Module Usage
+
+### `main.tf`
+
+Map your (`ACG variable name` & `VPC module name`) to (`local ACG variable` & `local VPC variable`). `ACG module` are created using `local ACG variable`. This eliminates the need to change the variable name reference structure in the `ACG module`.
+
+``` hcl
+locals {
+  acgs = var.access_control_groups
+  vpc  = module.vpc
+}
+```
+
+Then just copy and paste the module declaration below.
+
+``` hcl
+module "access_control_groups" {
+  source = "terraform-ncloud-modules/acg/ncloud"
+
+  access_control_groups = [for acg in local.acgs : merge(acg, { vpc_id = local.vpc.vpc.id })]
+}
+```