ansible-role-cyhy-commander

An Ansible role for installing cisagov/cyhy-commander.

Pre-requisites (Ignore Until the COOL Migration)

In order to execute the Molecule tests for this Ansible role in GitHub Actions, a test user must exist in AWS. The accompanying Terraform code will create the user with the appropriate name and permissions. This only needs to be run once per project, per AWS account. This user can also be used to run the Molecule tests on your local machine.

Before the test user can be created, you will need a profile in your AWS credentials file that allows you to read and write your remote Terraform state. (You almost certainly do not want to use local Terraform state for this long-lived test user.) If the test user is to be created in the CISA COOL environment, for example, then you will need the cool-terraform-backend profile.

The easiest way to set up the Terraform remote state profile is to make use of our aws-profile-sync utility. Follow the usage instructions in that repository before continuing with the next steps, and note that you will need to know where your team stores their remote profile data in order to use aws-profile-sync.

Creating a test user

You will need to create a test user for each environment that you use. The following steps show how to create a test user for an environment named "dev". You will need to repeat this process for any additional environments.

1. Change into the terraform directory:

   cd terraform

2. Create a backend configuration file named dev.tfconfig containing the name of the bucket where "dev" environment Terraform state is stored - this file is required to initialize the Terraform backend in each environment:

   bucket = "my-dev-terraform-state-bucket"

3. Initialize the Terraform backend for the "dev" environment using your backend configuration file:

   terraform init -backend-config=dev.tfconfig

   [!NOTE] When performing this step for additional environments (i.e. not your first environment), use the -reconfigure flag:

   terraform init -backend-config=other-env.tfconfig -reconfigure

4. Create a Terraform variables file named dev.tfvars containing all required variables (currently only terraform_state_bucket):

   terraform_state_bucket = "my-dev-terraform-state-bucket"

5. Create a Terraform workspace for the "dev" environment:

   terraform workspace new dev

6. Initialize and upgrade the Terraform workspace, then apply the configuration to create the test user in the "dev" environment:

   terraform init -upgrade=true
   terraform apply -var-file=dev.tfvars

Once the test user is created you will need to update the repository's secrets with the new encrypted environment variables. This should be done using the terraform-to-secrets tool available in the development guide. Instructions for how to use this tool can be found in the "Terraform IAM Credentials to GitHub Secrets" section. of the Project Setup README.

If you have appropriate permissions for the repository you can view existing secrets on the appropriate page in the repository's settings.

Requirements

None.

Role Variables

Variable	Description	Default	Required
cyhy_commander_file_owner_group	The name of the group that should own any non-system files or directories created by this role.	Omitted	No
cyhy_commander_file_owner_username	The name of the user that should own any non-system files or directories created by this role.	Omitted	No
cyhy_commander_install_geoipupdate	Whether to install the MaxMind geoipupdate tool.	false	No
cyhy_commander_maxmind_account_id	The MaxMind account ID for access to a GeoIP2 database subscription.	n/a	Yes
cyhy_commander_maxmind_license_key	The MaxMind license key that provides access to a GeoIP2 database subscription.	n/a	Yes

Dependencies

• cisagov/ansible-role-cyhy-core
• cisagov/ansible-role-pip
• cisagov/ansible-role-python

Installation

This role can be installed via the command:

ansible-galaxy install --role-file path/to/requirements.yml

where requirements.yml looks like:

---
- name: cyhy_commander
  src: https://github.com/cisagov/ansible-role-cyhy-commander

and may contain other roles as well.

For more information about installing Ansible roles via a YAML file, please see the ansible-galaxy documentation.

Example Playbook

Here's how to use it in a playbook:

- hosts: all
  become: true
  become_method: sudo
  tasks:
    - name: Install the CyHy commander
      ansible.builtin.include_role:
        name: cyhy_commander

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is in the worldwide public domain.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

Author Information

Shane Frasier - [email protected]