Cloudwatch Agent support — Additional metrics

docs/configuration.md

@@ -0,0 +1,16 @@
+# fck-nat Configuration
+
+## Configuration file
+
+Upon starting, fck-nat evaluates a configuration file describing how the instance should behave as well as what features
+shall be enabled. To configure fck-nat, ensure a file `/etc/fck-nat.conf` exists with your configuration. fck-nat
+requires the service to be restarted by running `service fck-nat-resart`. In most implementations this configuration is
+passed only once via EC2's user data.
+
+The following describes available options:
+| name                    | description |
+| ----------------------- | ----------- |
+| `eni_id`                | The ID of the Elastic Network Interface to attach to the instance and use as a consistent endpoint to send traffic to fck nat. This is required when using high-availability mode. |
+| `eip_id`                | The ID of an Elastic IP to be attached to the public network interface. This ensures the NAT gateway public traffic is always routed through the same public IP address. |
+| `cwagent_enabled`       | If set, enables Cloudwatch agent and forward instance metrics to Cloudwatch. Requires `cwagent_cfg_param_name` to be set. |
+| `cwagent_cfg_param_name` | The name of the SSM Parameter holding the Cloudwatch agent configuration and which the agent shall pull from. Requires `cwagent_enabled` to be set. |

docs/features.md

@@ -7,19 +7,72 @@ autoscaling group, fck-nat can be configured to always attach a specific ENI at
 a consistent internal-facing IP address. Additionally, it is also possible to configure an already allocated EIP address
 that would be carried through instance refreshs.
 
-To enable these features, you'll need to create a config file at `/etc/fck-nat.conf` like this:
+Those features are controlled by `eni_id` and `eip_id` directive in the configuration file.  
 
-```
-eni_id=<YOUR_ENI_ID>
-eip_id=<YOUR_EIP_ALLOCATION_ID>
-```
+**IAM requirements**: `ec2:AttachNetworkInterface`, `ec2:ModifyNetworkInterfaceAttribute` on `*` for ha-mode, plus
+`ec2:AssociateAddress`, `ec2:DisassociateAddress` on `*` when using a static EIP.
 
-Once the fck-nat configuration is created, be sure to restart the service by running `service fck-nat restart`.
+## Metrics
 
-In the official fck-nat CDK construct, we configure this via UserData on the autoscaling group.
+One of the objectives of fck-nat is to offer as close as possible metric parity with Managed NAT Gateway. While the
+project supports various metrics similar to the managed NAT Gateway via Cloudwatch agent, each provider is responsible
+for passing their configuration to the agent via fck-nat's `cwagent_enabled`, and `cwagent_cfg_param_name` directives
+within its configuration file.
 
-## Metrics
+As an example, you might use the following configuration file which have Cloudwatch agent report most of metrics
+provided in the managed NAT Gateway:
+
+``` json
+{
+  "agent": {
+    "metrics_collection_interval": 60,
+    "run_as_user": "root",
+    "usage_data": false
+  },
+  "metrics": {
+    "namespace": "fck-nat",
+    "metrics_collected": {
+      "net": {
+        "resources": ["eth0", "eth1"],
+        "measurement": [
+          { "name": "bytes_recv", "rename": "BytesIn",  "unit": "Bytes" },
+          { "name": "bytes_sent", "rename": "BytesOut",  "unit": "Bytes" },
+          { "name": "packets_sent", "rename": "PacketsOutCount",  "unit": "Count" },
+          { "name": "packets_recv", "rename": "PacketsInCount",  "unit": "Count" },
+          { "name": "drop_in", "rename": "PacketsDropInCount",  "unit": "Count" },
+          { "name": "drop_out", "rename": "PacketsDropOutCount",  "unit": "Count" }
+        ]
+      },
+      "netstat": {
+        "measurement": [
+          { "name": "tcp_syn_sent", "rename": "ConnectionAttemptOutCount",  "unit": "Count" },
+          { "name": "tcp_syn_recv", "rename": "ConnectionAttemptInCount",  "unit": "Count" },
+          { "name": "tcp_established", "rename": "ConnectionEstablishedCount",  "unit": "Count" }
+        ]
+      },
+      "ethtool": {
+        "interface_include": ["eth0", "eth1"],
+        "metrics_include": [
+          "bw_in_allowance_exceeded",
+          "bw_out_allowance_exceeded",
+          "conntrack_allowance_exceeded",
+          "pps_allowance_exceeded"
+        ]
+      },
+      "mem": {
+        "measurement": [
+          { "name": "used_percent", "rename": "MemoryUsed",  "unit": "Percent" }
+        ]
+      }
+    },
+    "append_dimensions": {
+      "InstanceId": "$${aws:InstanceId}"
+    }
+  }
+}
+```
+
+Ensure you are aware of Cloudwatch metrics costs before enabling Cloudwatch agent. The above configuration would
+cost you about $17/monthly, excluding free tier.  
 
-One of the objectives of fck-nat is to offer as close as possible metric parity with Managed NAT Gateway. If this
-feature is important to you, help us prioritize it by +1'ing the following issue: [Report additional metrics from
-fck-nat](https://github.com/AndrewGuenther/fck-nat/issues/16)
+**IAM requirements**: `ssm:GetParameter` on the SSM Parameter ARN, and `cloudwatch:PutMetricData` on `*`.

mkdocs.yml

@@ -18,6 +18,7 @@ theme:
 nav:
   - Introduction: index.md
   - Deploying: deploying.md
+  - Configuration: configuration.md
   - Features: features.md
 
 repo_url: https://github.com/AndrewGuenther/fck-nat

packer/fck-nat.pkr.hcl

@@ -96,7 +96,8 @@ build {
 
   provisioner "shell" {
     inline = [
-      "sudo yum --nogpgcheck -y localinstall /tmp/fck-nat-${var.version}-any.rpm"
+      "sudo yum --nogpgcheck -y localinstall /tmp/fck-nat-${var.version}-any.rpm",
+      "sudo yum install amazon-cloudwatch-agent -y"
     ]
   }
 }

service/fck-nat.sh

@@ -70,4 +70,10 @@ iptables -t nat -F
 echo "Adding NAT rule..."
 iptables -t nat -A POSTROUTING -o "$nat_interface" -j MASQUERADE -m comment --comment "NAT routing rule installed by fck-nat"
 
+if test -n "$cwagent_enabled" && test -n "$cwagent_cfg_param_name"; then
+    echo "Found cwagent_enabled and cwagent_cfg_param_name configuration, starting CloudWatch agent..."
+    systemctl enable amazon-cloudwatch-agent
+    /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c "ssm:$cwagent_cfg_param_name"
+fi
+
 echo "Done!"