Ansible Role: christiangda.amazon_cloudwatch_agent

This role installs the AWS CloudWatch Agent. For details, see this AWS guide.

To install this role, you can use the command ansible-galaxy install christiangda.amazon_cloudwatch_agent. Find it on Ansible Galaxy.

The repository is available at GitHub.

Features:

• Works with AWS EC2 instances and On-Premise Instances.
• Supports different versions of Python, Ansible, and Operating Systems (detailed in the Continuous integration matrix).
• Automatically downloads and installs the CloudWatch Agent from an AWS package.
• Reloads the service if configuration changes.
• Provides a default agent configuration file (minimal configuration, not recommended).
• Rotates the CloudWatch Agent log file.
• Allows loading your own JSON or YAML file for agent, metrics, and logs.
• Supports amd64 and arm64 architectures.

Notes:

• Version 2.x.y is not compatible with version 1.x.y.
• Starting with version 2.x.y, the role does not install the EPEL Repository by default. You will need to manage this yourself; I recommend my ansible role christiangda.epel_repo.
• The role no longer creates AWS CLI profiles (config and credentials). You need to manage this yourself, using my ansible roles christiangda.awscli and christiangda.awscli_configure. See examples where cwa_agent_mode: "onPremise".
• Automatically installs the collectd OS package if it detects usage of Custom Metrics with collectd in the configuration file. Depending on your OS, the collectd package may require EPEL Repository.
• For RedHat users: A valid subscription is necessary to avoid issues during package installation.

For more details, see VERSION.md.

Requirements

This role works on RedHat, CentOS, Amazon Linux, Debian, and Ubuntu distributions.

• RedHat: 7, 8
• CentOS: 7, 8, stream8
• Rocky Linux: 8, 9
• Amazon Linux: 2
• Ubuntu: 14.04 (), 16.04 (), 18., 20., 21., 22.
• Debian: Stretch (9), Buster (10), Bullseye (11), Bookworm (12)

To check the compatibility of Python with Ansible versions, see the Travis-CI build matrix.

Role Variables

Variable	Default Value
cwa_conf_json_file_content	"" --> Empty
cwa_agent_mode	"ec2"
cwa_aws_region	""
cwa_use_credentials	false
cwa_profile	"AmazonCloudWatchAgent"
cwa_agent_profile_path	/root
cwa_http_proxy	"" --> Empty
cwa_https_proxy	"" --> Empty
cwa_no_proxy	"169.254.169.254"
cwa_logrotate_file_size	"10M"
cwa_logrotate_files	5
cwa_debug	false

More Details: See the defaults/main.yaml file.

Dependencies

• For RedHat/Centos OS family, the EPEL Repository may be needed.
• If using cwa_agent_mode: "onPremise", AWS CLI Profile configuration is required.
• If using Custom Metrics with collectd, the collectd package will be installed automatically, and the EPEL Repository may be necessary depending on the OS.

Example Playbook

When cwa_agent_mode: "onPremise"

# Use ansible-vault for sensitive data
# Example:
# ansible-vault encrypt_string --ask-vault-pass --name 'cwa_access_key' 'AKIAIOSFODNN7EXAMPLE'
# ansible-vault encrypt_string --ask-vault-pass --name 'cwa_secret_key' 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'

- hosts: servers
    gather_facts: True
    roles:
      - role: christiangda.epel_repo # If you haven't installed the EPEL Repository
        when: >
          ansible_os_family == 'RedHat' and (
            ansible_distribution == 'CentOS' or
            ansible_distribution == 'RedHat' or
            ansible_distribution == 'Amazon'
          )
      - role: christiangda.awscli_configure # If you need to configure AWS CLI Profiles
        vars:
          awscliconf_path: '/root'
          awscliconf_files:
            credentials:
              - AmazonCloudWatchAgent:
                  aws_access_key_id: !vault |
                    $ANSIBLE_VAULT;1.1;AES256
                    30376338613338326663373366303234623665633339303338613463313564633832363237306137
                    ...
                  aws_secret_access_key: !vault |
                    $ANSIBLE_VAULT;1.1;AES256
                    65643230613939303737336632346432393234616437383532386139616364316233333933643735
                    ...
            config:
              - profile AmazonCloudWatchAgent:
                  region: "eu-west-1"
      - role: christiangda.amazon_cloudwatch_agent # Using minimal agent configuration from the role
          vars:
              cwa_agent_mode: "onPremise"
              cwa_aws_region: "eu-west-1"
              cwa_profile: "AmazonCloudWatchAgent"

When cwa_agent_mode: "ec2"

Using config file from JSON file

---
- hosts: servers
    gather_facts: True
    roles:
      - role: christiangda.amazon_cloudwatch_agent # Use your JSON file at `files/CloudWatch.json` for this playbook
          vars:
              cwa_agent_mode: "ec2"
              cwa_conf_json_file_content: "{{ lookup('file', 'files/CloudWatch.json') | from_json }}"

Using config file from YAML file

---
- hosts: servers
    gather_facts: True
    roles:
      - role: christiangda.amazon_cloudwatch_agent # Use your YAML file at `files/CloudWatch.yaml` for this playbook
          vars:
              cwa_agent_mode: "ec2"
              cwa_conf_json_file_content: "{{ lookup('file', 'files/CloudWatch.yaml') | from_yaml }}"

Using INLINE YAML configuration

---
- hosts: centos7, centos6, ubuntu1804, ubuntu1810, debian8, debian9, amzn2
  become: True
  roles:
    - role: christiangda.epel_repo # Ensure EPEL Repository is installed
        when: >
          ansible_os_family == 'RedHat' and (
            ansible_distribution == 'CentOS' or
            ansible_distribution == 'RedHat' or
            ansible_distribution == 'Amazon'
          )
      - role: christiangda.awscli_configure # Configure AWS CLI Profiles if needed
        vars:
          awscliconf_path: '/root'
          awscliconf_files:
            credentials:
              - AmazonCloudWatchAgent:
                  aws_access_key_id: !vault |
                    ...
                  aws_secret_access_key: !vault |
                    ...
            config:
              - profile AmazonCloudWatchAgent:
                  region: "eu-west-1"
    - role: christiangda.amazon_cloudwatch_agent # Configure your agent using ONLINE YAML
      vars:
        cwa_agent_mode: onPremise
        cwa_aws_region: "eu-west-1"
        cwa_profile: "AmazonCloudWatchAgent"
        cwa_conf_json_file_content:
          agent:
            metrics_collection_interval: 60
            region: es-west-1
            logfile: "/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log"
            debug: false
          metrics:
            ...

Minimal configuration on AWS EC2 instance

---
- hosts: all
    gather_facts: True
    become: true
    become_user: root
    become_method: sudo
    remote_user: ec2-user
    roles:
    - role: christiangda.amazon_cloudwatch_agent # Use default configuration for EC2 instance

Sample Inventory File

[all]
10.14.x.y
10.14.v.z

[amazon-1]
10.14.x.y

[amazon-2]
10.14.v.z

How to Use

ansible-playbook my-playbook.yml \
    --inventory inventory \
    --private-key [~/location of my key.pem] \
    --become \
    --become-user=ec2-user \
    --user ec2-user

Development / Contributing

This role is tested using Molecule and developed using Python Virtual Environments.

Branches:

• master
• develop

To contribute, follow these steps:

1. Fork the project.
2. Prepare your environment.
3. Fix issues in the develop branch.
4. Run molecule test.
5. Create a Pull Request to the official project's develop branch.

Prepare your environment:

• Python 3

mkdir ansible-roles
cd ansible-roles/

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install ansible molecule
pip install 'molecule[docker]' 'molecule[podman]' 'molecule[lint]' molecule-vagrant python-vagrant selinux docker pytest pytest-mock pylint rope autopep8 yamllint flake8 ansible-lint

Clone the role repository and create a symbolic link:

Note: First, fork the main repository.

git clone https://github.com/<your github user>/ansible-role-amazon-cloudwatch-agent.git
ln -s ansible-role-amazon-cloudwatch-agent christiangda.amazon_cloudwatch_agent
cd christiangda.amazon_cloudwatch_agent

Execute the molecule test:

Available scenarios:

• default: --driver-name docker
• podman: --driver-name podman
• vagrant: --driver-name vagrant

To run a scenario step by step:

molecule create [--scenario-name default]
molecule converge [--scenario-name default]
molecule verify [--scenario-name default]
molecule destroy [--scenario-name default]

Or all in one command:

molecule test [--scenario-name default]

License

This module is released under the GNU General Public License Version 3:

• http://www.gnu.org/licenses/gpl-3.0-standalone.html

Author Information

• Christian González Di Antonio