README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#
# Name of this project
name: terraform-aws-cloudwatch-agent

# Tags of this project
tags:
  - aws
  - terraform
  - terraform-modules
  - platform
  - cloudwatch
  - agent
  - cloudwatch-agent

# Categories of this project
categories:
  - terraform-modules/platform

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-cloudwatch-agent

# Badges to display
badges:
  - name: "Build Status"
    image: "https://travis-ci.org/cloudposse/terraform-aws-cloudwatch-agent.svg?branch=master"
    url: "https://travis-ci.org/cloudposse/terraform-aws-cloudwatch-agent"
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-cloudwatch-agent.svg"
    url: "https://github.com/cloudposse/terraform-aws-cloudwatch-agent/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "terraform-aws-ec2-instance"
    description: "Terraform Module for provisioning a general purpose EC2 host."
    url: "https://github.com/cloudposse/terraform-aws-ec2-instance"

  - name: "terraform-aws-cloudtrail-cloudwatch-alarms"
    description: "Terraform module for creating alarms for tracking important changes and occurrences from cloudtrail."
    url: "https://github.com/cloudposse/terraform-aws-cloudtrail-cloudwatch-alarms"

  - name: "terraform-aws-rds-cloudwatch-sns-alarms"
    description: "Terraform module that configures important RDS alerts using CloudWatch and sends them to an SNS topic"
    url: "https://github.com/cloudposse/terraform-aws-rds-cloudwatch-sns-alarms"

  - name: "terraform-aws-cloudwatch-logs"
    description: "Terraform Module to Provide a CloudWatch Logs Endpoint"
    url: "https://github.com/cloudposse/terraform-aws-cloudwatch-logs"

  - name: "terraform-aws-alb-target-group-cloudwatch-sns-alarms"
    description: "Terraform module to create CloudWatch Alarms on ALB Target level metrics."
    url: "https://github.com/cloudposse/terraform-aws-alb-target-group-cloudwatch-sns-alarms"

  - name: "terraform-aws-cloudwatch-flow-logs"
    description: "Terraform module for enabling flow logs for vpc and subnets."
    url: "https://github.com/cloudposse/terraform-aws-cloudwatch-flow-logs"

  - name: "terraform-aws-ecs-cloudwatch-autoscaling"
    description: "Terraform module to autoscale ECS Service based on CloudWatch metrics"
    url: "https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-autoscaling"

  - name: "terraform-aws-elasticache-cloudwatch-sns-alarms"
    description: "Terraform module that configures CloudWatch SNS alerts for ElastiCache"
    url: "https://github.com/cloudposse/terraform-aws-elasticache-cloudwatch-sns-alarms"

  - name: "terraform-aws-efs-cloudwatch-sns-alarms"
    description: "Terraform module that configures CloudWatch SNS alerts for EFS"
    url: "https://github.com/cloudposse/terraform-aws-efs-cloudwatch-sns-alarms"

  - name: "terraform-aws-ecs-cloudwatch-sns-alarms"
    description: "Terraform module to create CloudWatch Alarms on ECS Service level metrics."
    url: "https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-sns-alarms"

  - name: "terraform-aws-ec2-cloudwatch-sns-alarms"
    description: "Terraform module that configures CloudWatch SNS alerts for EC2 instances"
    url: "https://github.com/cloudposse/terraform-aws-ec2-cloudwatch-sns-alarms"

  - name: "terraform-aws-sqs-cloudwatch-sns-alarms"
    description: "Terraform module for creating alarms for SQS and notifying endpoints"
    url: "https://github.com/cloudposse/terraform-aws-sqs-cloudwatch-sns-alarms"

  - name: "terraform-aws-lambda-cloudwatch-sns-alarms"
    description: "Terraform module for creating a set of Lambda alarms and outputting to an endpoint"
    url: "https://github.com/cloudposse/terraform-aws-lambda-cloudwatch-sns-alarms"

# Short description of this project
description: |-
  Terraform module to install the CloudWatch agent on EC2 instances using `cloud-init`.

# How to use this project

usage: |-

  ### Example with launch configuration:

  ```hcl
  module "cloudwatch_agent" {
    source = "git::https://github.com/cloudposse/terraform-aws-cloudwatch-agent?ref=master"

    name = "cloudwatch_agent"
  }

  resource "aws_launch_configuration" "multipart" {
    name_prefix          = "cloudwatch_agent"
    image_id             = "${data.aws_ami.ecs_optimized.id}"
    iam_instance_profile = "${aws_iam_instance_profile.cloudwatch_agent.name}"
    instance_type        = "t2.micro"
    user_data_base64     = "${module.cloudwatch_agent.user_data}"
    security_groups      = ["${aws_security_group.ecs.id}"]
    key_name             = "${var.ssh_key_pair}"

    lifecycle {
      create_before_destroy = true
    }
  }

  data "aws_ami" "ecs_optimized" {
    most_recent = true

    filter {
      name   = "name"
      values = ["amzn2-ami-ecs-hvm-*-x86_64-*"]
    }

    owners = [
      "amazon",
    ]
  }
  ```

  ### Example with using the iam_policy_document and aws_iam_role:

  ```hcl
  locals {
    application {
      name      = "cloudwatch_agent"
      stage     = "dev"
      namespace = "eg"
    }
  }

  module "label" {
    source      = "git::https://github.com/cloudposse/terraform-null-label.git?ref=master"
    stage       = "${local.application["stage"]}"
    name        = "${local.application["name"]}"
    namespace   = "${local.application["namespace"]}"
  }

  module "cloudwatch_agent" {
    source = "git::https://github.com/cloudposse/terraform-aws-cloudwatch-agent?ref=master"

    name      = "${module.label.name}"
    stage     = "${module.label.stage}"
    namespace = "${module.label.namespace}"
  }

  resource "aws_launch_configuration" "multipart" {
    name_prefix          = "${module.label.name}"
    image_id             = "${data.aws_ami.ecs_optimized.id}"
    iam_instance_profile = "${aws_iam_instance_profile.cloudwatch_agent.name}"
    instance_type        = "t2.micro"
    user_data_base64     = "${module.cloudwatch_agent.user_data}"
    security_groups      = ["${aws_security_group.ecs.id}"]
    key_name             = "${var.ssh_key_pair}"

    lifecycle {
      create_before_destroy = true
    }
  }

  data "aws_ami" "ecs_optimized" {
    most_recent = true

    filter {
      name   = "name"
      values = ["amzn2-ami-ecs-hvm-*-x86_64-*"]
    }

    owners = [
      "amazon",
    ]
  }

  data "aws_iam_policy_document" "ec2_cloudwatch" {
    statement {
      effect  = "Allow"
      actions = ["sts:AssumeRole"]

      principals = {
        type        = "Service"
        identifiers = ["ec2.amazonaws.com"]
      }
    }
  }

  resource "aws_iam_role" "ec2" {
    name = "${module.label.id}"

    assume_role_policy = "${data.aws_iam_policy_document.ec2_cloudwatch.json}"

    tags = {
      Name = "${module.label.id}"
    }
  }

  resource "aws_iam_role_policy" "cloudwatch_agent" {
    name   = "${module.label.id}"
    policy = "${module.cloudwatch_agent.iam_policy_document}"
    role   = "${aws_iam_role.ec2.id}"
  }

  resource "aws_iam_instance_profile" "cloudwatch_agent" {
    name_prefix = "${module.label.name}"
    role        = "${aws_iam_role.ec2.name}"
  }
  ```

  ### Example with passing user-data and using the role from the module using advanced metrics configuration:

  ```hcl
  module "cloudwatch_agent" {
    source = "git::https://github.com/cloudposse/terraform-aws-cloudwatch-agent?ref=master"

    name      = "cloudwatch_agent"
    stage     = "dev"
    namespace = "eg"

    metrics_config        = "advanced"
    userdata_part_content = "${data.template_file.cloud-init.rendered}"
  }

  data "template_file" "cloud-init" {
    template = "${file("${path.module}/cloud-init.yml")}"
  }

  resource "aws_launch_configuration" "multipart" {
    name_prefix          = "cloudwatch_agent"
    image_id             = "${data.aws_ami.ecs_optimized.id}"
    iam_instance_profile = "${aws_iam_instance_profile.cloudwatch_agent.name}"
    instance_type        = "t2.micro"
    user_data_base64     = "${module.cloudwatch_agent.user_data}"
    security_groups      = ["${aws_security_group.ecs.id}"]
    key_name             = "${var.ssh_key_pair}"

    lifecycle {
      create_before_destroy = true
    }
  }

  data "aws_ami" "ecs_optimized" {
    most_recent = true

    filter {
      name   = "name"
      values = ["amzn2-ami-ecs-hvm-*-x86_64-*"]
    }

    owners = [
      "amazon",
    ]
  }

  resource "aws_iam_instance_profile" "cloudwatch_agent" {
    name_prefix = "cloudwatch_agent"
    role        = "${module.cloudwatch_agent.role_name}"
  }
  ```

include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors:
  - name: "Nikola Velkovski"
    github: "parabolic"