Baseline commit of security group module definitions.

Author: apolloakora

README.md

@@ -0,0 +1,87 @@
+
+# Rules Terraform Modules | Creates Security Group | Adds Rules
+
+This security-group module **adds ingress and egress rules** to **either the default or a new** security group within a given VPC.
+
+## Simple Module Usage Example
+
+To use this module simply declare it like below supplying it with a mandatory VPC id. If you omit **in_ingress** a default ssh rule is created. A default **all traffic egress rule** is also created but you can override this behaviour if you so wish.
+
+    module security_group_module
+    {
+        source          = "rules"
+        in_vpc_id       = "${module.vpc.vpc_id}"
+        in_ingress   = [ "ssh", "http", "https" ]
+    }
+
+This module defines two **list outputs** called **out_default_security_group_ids** and **out_new_security_group_ids**. Use the first after creating rules against the VPC's default security group and the second after a new security group is created (see variable in_use_default).
+
+    vpc_security_group_ids = [ "${module.security_group_module.out_default_security_group_ids}" ]
+
+## Security Group Module Inputs
+
+The security group's input variables are vital to achieving the desired behaviour.
+
+| Imported | Type | Default | Comment |
+|:-------- |:---- |:------- |:------- |
+**in_vpc_id** | String | vpc-1234567890 | create security group/s under VPC with this id
+**in_use_default** | Boolean | [ true ] | use the default security group if true else create one
+**in_ingress** | List | [ "postgres", "https"] | identigy the ports to allow for inbound traffic
+**in_egress** | List | [ "all-traffic" ] | identigy the ports to allow for outbound traffic
+**in_ingress_cidr_blocks** | List | [ "0.0.0.0/0"] | list of source incoming traffic addresses to allow
+**in_egress_cidr_blocks** | List | [ "0.0.0.0/0"] | list of VPC source outgoing traffic addresses to allow
+**in_ecosystem_id** | String | kube-19188-2306 | the ecosystem's identifier including a timestamp
+
+## Alternate Module Inputs
+
+This security group module is simple but flexible as it needs to cater to many different tastes. Now follows a number of **overloading** facilities to craft your security group's behaviour.
+
+### Specify the Creation of a Security Group
+
+Passing **false** to the **in_use_default** flag causes the **creation of a security group**.
+
+    module security_group_module
+    {
+        source     = "security"
+        in_vpc_id  = "${module.xyz.out_vpc_id}"
+        in_ingress = [ "ssh", "http", "https" ]
+        in_egress  = [ "all-traffic" ]
+
+        in_use_default = false
+    }
+
+Note that this module only creates one security group at a time. To create two or more simply repeat the module declaration using a different name each time.
+
+### Specify Ingress and Egress Cidr Blocks
+
+Most security group **source cidr blocks** allow traffic originating from anywhere ( 0.0.0.0/0 ).
+
+This is true for both inress (incoming) and egress (outgoing) traffic. You can alter this by specifying these extra module inputs. The below allows traffic **in only from a given VPC** and **out only from a subnet** within the security group's VPC.
+
+    in_ingress_cidr_blocks = [ "172.30.0.0/16" ]
+    in_egress_cidr_blocks  = [ "10.2.0.4/24" ]
+
+The cidr blocks are lists of strings so you can also allow traffic from more than one source block.
+
+    in_ingress_cidr_blocks = [ "172.30.0.0/0", "82.9.72.144/31" ]
+
+### Specify Other Ingress and Egress Rules
+
+Clearly you will want to allow ingress and egress traffic for various middleware services.
+
+> @todo Author then link to sister page containing a table full of rule classifications.
+
+Note that if you create an all traffic egress rule and you have an **IPV6 cidr block**, AWS will create an extra **::/0** egress rule in addition to the 0.0.0.0/0 (IPV4) rule.
+
+## Running the Module's Tests
+
+Visit the README within the **ztest-security** folder for instructions on running this module's tests.
+
+## Creating New Rule Groups
+
+The outer list has no size restrictions but the inner list is expected to contain 4 elements.
+
+- the port [from] which [inbound] traffic should be allowed
+- the port [to] which [inbound] traffic should be allowed
+- the ICMA protocol that the traffic obeys
+- the (name) description of the traffic rule

security.groups-main.tf

@@ -0,0 +1,80 @@
+
+### ####################################### ###
+### [[resource]] aws_default_security_group ###
+### ####################################### ###
+/*
+resource aws_security_group sgroup-new
+{
+    count = "${var.in_use_default == false ? 1 : 0}"
+
+    name        = "security-group-${var.in_ecosystem_id}"
+    description = "This security group ${var.in_history_note}"
+    vpc_id      = "${var.in_vpc_id}"
+
+    tags
+    {
+        Name   = "security-group-${var.in_ecosystem_id}"
+        Group  = "eco-system-${var.in_ecosystem_id}"
+        Desc   = "This security group ${var.in_history_note}"
+    }
+}
+*/
+
+
+### ####################################### ###
+### [[resource]] aws_default_security_group ###
+### ####################################### ###
+
+resource aws_default_security_group default
+{
+    vpc_id      = "${var.in_vpc_id}"
+
+    tags
+    {
+        Name   = "default-sg-${var.in_ecosystem_id}"
+        Group  = "eco-system-${var.in_ecosystem_id}"
+        Desc   = "This default VPC security group ${var.in_history_note}"
+    }
+
+}
+
+
+### #################################### ###
+### [[resource]] aws_security_group_rule ###
+### #################################### ###
+
+resource aws_security_group_rule ingress
+{
+    count = "${length(var.in_ingress)}"
+
+# ---@----@-->    security_group_id = "${var.in_use_default == true ? aws_default_security_group.default.id : aws_security_group.sgroup-new.id}"
+    security_group_id = "${aws_default_security_group.default.id}"
+
+    type        = "ingress"
+    cidr_blocks = ["${var.in_ingress_cidr_blocks}"]
+    description = "${element(var.rules[var.in_ingress[count.index]], 3)}"
+
+    from_port   = "${element(var.rules[var.in_ingress[count.index]], 0)}"
+    to_port     = "${element(var.rules[var.in_ingress[count.index]], 1)}"
+    protocol    = "${element(var.rules[var.in_ingress[count.index]], 2)}"
+}
+
+### #################################### ###
+### [[resource]] aws_security_group_rule ###
+### #################################### ###
+
+resource aws_security_group_rule egress
+{
+    count = "${length(var.in_egress)}"
+
+# ---@----@-->    security_group_id = "${var.in_use_default == true ? aws_default_security_group.default.id : aws_security_group.sgroup-new.id}"
+    security_group_id = "${aws_default_security_group.default.id}"
+
+    type        = "egress"
+    cidr_blocks = ["${var.in_egress_cidr_blocks}"]
+    description = "${element(var.rules[var.in_egress[count.index]], 3)}"
+
+    from_port   = "${element(var.rules[var.in_egress[count.index]], 0)}"
+    to_port     = "${element(var.rules[var.in_egress[count.index]], 1)}"
+    protocol    = "${element(var.rules[var.in_egress[count.index]], 2)}"
+}

security.groups-rules.tf

@@ -0,0 +1,79 @@
+
+# -- ###################################################################################
+# -- ###################################################################################
+
+# -- ############################ -- #
+# -- How to Add New Traffic Rules -- #
+# -- ############################ -- #
+
+# -- In order to add new rules be informed that 
+# --
+# --    - lists are in the form [ port-from, port-to, protocol, description ]
+# --    - the first two elements are integers and the final two are strings
+# --    - it pays to be conservative with the description characters and length
+# --    - ports can range from 0 to one less than 2^16 (which is 65,535)
+# --    - a -1 port signals that all ports are to be allowed (disallowed)
+# --    - the protocol can be one of [ tcp, udp, icmp, all ]
+# --    - the protocol can also be one of a small set of numbers
+
+# -- Note that if you create an all traffic egress rule and you have an
+# -- IPV6 Cidr block another will be created to ::/0 in addition to the
+# -- one with the 0.0.0.0/0 (IPV4) notation.
+
+variable "rules"
+{
+    description = "Modular rules allowing either TCP or UDP traffic."
+    type = "map"
+
+    default
+    {
+
+	# < ~~~ ssh secure shell ~~~ >
+        ssh = [ 22, 22, "tcp", "secure shell" ]
+
+	# < ~~~ http(s) - hyper text transfer protocol ~~~ >
+        http  = [  80,  80, "tcp", "http plaintext" ]
+        https = [ 443, 443, "tcp",   "http secured" ]
+
+	# < ~~~ gollum's webrick http server ~~~ >
+        gollum = [ 4567, 4567, "tcp", "gollum wiki" ]
+
+	# < ~~~ Kubernetes Services Suite ~~~ >
+        kubernetes   = [  6443,  6443, "tcp",  "kubernetes api" ]
+        kubelet-api  = [ 10250, 10250, "tcp",     "kubelet api" ]
+        kube-sched   = [ 10251, 10251, "tcp",  "kube scheduler" ]
+        kube-control = [ 10252, 10252, "tcp", "kube controller" ]
+        kube-read    = [ 10255, 10255, "tcp",  "kube read only" ]
+
+	# < ~~~ etcd client server api ~~~ >
+        etcd-1 = [ 2379, 2379, "tcp", "etcd services 1" ]
+        etcd-2 = [ 2380, 2380, "tcp", "etcd services 2" ]
+
+
+        # -- ElasticSearch (ELK) Stack Rules
+	# -- Remember that ElasticSearch (ELK stack) can require up
+	# -- to 3 extra inbound ports for the JAVA API (9300), then
+	# -- the HTTP (80) and HTTPS (443) for the Kibana UI.
+
+        elasticsearch = [ 9200, 9200, "tcp", "elasticsearch" ]
+
+
+        # -- Java services traditionally employ port 8080
+	# -- (tomcat, jenkins, nexus, jserve ...)
+
+        java = [ 8080, 8080, "tcp", "HTTP" ]
+
+
+        # Open all ports & protocols
+        all-traffic   = [ -1, -1, "-1", "All protocols" ]
+        all-tcp       = [ 0, 65535, "tcp", "All TCP ports" ]
+        all-udp       = [ 0, 65535, "udp", "All UDP ports" ]
+        all-icmp      = [ -1, -1, "icmp", "All IPV4 ICMP" ]
+        all-ipv6-icmp = [ -1, -1, 58, "All IPV6 ICMP" ]
+
+    }
+
+}
+
+# -- ###################################################################################
+# -- ###################################################################################

security.groups-vars.tf

@@ -0,0 +1,114 @@
+
+################ ######################################## ########
+################ Module [[[rules]]] Input Variables List. ########
+################ ######################################## ########
+
+### ####################### ###
+### [[variable]] in_ingress ###
+### ####################### ###
+
+variable in_ingress
+{
+    description = "4 element list defining traffic to allow in (see traffic-rules.tf)"
+    type        = "list"
+    default     = [ "ssh" ]
+}
+
+
+### ###################### ###
+### [[variable]] in_egress ###
+### ###################### ###
+
+variable in_egress
+{
+    description = "4 element list defining traffic to allow out (see traffic-rules.tf)"
+    type        = "list"
+    default = [ "all-traffic" ]
+}
+
+
+### ################################### ###
+### [[variable]] in_ingress_cidr_blocks ###
+### ################################### ###
+
+variable in_ingress_cidr_blocks
+{
+    description = "The IPv4 CIDR ranges from which traffic is allowed to originate."
+    type        = "list"
+    default     = [ "0.0.0.0/0" ]
+}
+
+
+### ################################## ###
+### [[variable]] in_egress_cidr_blocks ###
+### ################################## ###
+
+variable in_egress_cidr_blocks
+{
+    description = "List of IPv4 CIDR ranges to use on all egress rules"
+    type        = "list"
+    default     = [ "0.0.0.0/0" ]
+}
+
+
+### ###################### ###
+### [[variable]] in_vpc_id ###
+### ###################### ###
+
+variable in_vpc_id
+{
+    description = "Mandatory VPC ID to create the security group under."
+}
+
+
+### ########################### ###
+### [[variable]] in_use_default ###
+### ########################### ###
+
+variable in_use_default
+{
+    default = true
+}
+
+
+### ############################ ###
+### [[variable]] in_ecosystem_id ###
+### ############################ ###
+
+variable in_ecosystem_id
+{
+    description = "Identifier binding all infrastructure components created for this ecosystem instance."
+}
+
+
+### ############################ ###
+### [[variable]] in_history_note ###
+### ############################ ###
+
+variable in_history_note
+{
+    description = "Note describing the whys and wherefores of this creation."
+}
+
+
+### ######################################### ###
+### [[output]] out_default_security_group_ids ###
+### ######################################### ###
+
+output out_default_security_group_ids
+{
+    description = "If in_use_default is true this output variable will be set."
+# ---@----@-->    value       = "${aws_default_security_group.default.*.id}"
+    value       = "${aws_default_security_group.default.id}"
+}
+
+
+# ---@----@-->### ############################# ###
+# ---@----@-->### [[output]] out_new_security_group_ids ###
+# ---@----@-->### ############################# ###
+# ---@----@-->output "out_new_security_group_ids"
+# ---@----@-->{
+# ---@----@-->    description = "If in_use_default is false this output variable will be set."
+# ---@----@-->    value       = "${aws_security_group.sgroup-new.*.id}"
+# ---@----@-->}
+