Automate Ansible playbook deployment with Amazon EC2 and GitHub
Ansible is an open-source automation tool that uses playbooks to enable you to make deployments faster and scale to various environments. Think of playbooks as recipes that lay out the steps needed to deploy policies, applications, configurations, and IT infrastructure. You can use playbooks repeatedly across multiple environments. Customers who use Ansible playbooks typically deploy periodic changes manually. As complex workloads increase, you might be looking for ways to automate them. In this post, we show you how to automate an Ansible playbook deployment using Amazon Elastic Compute Cloud (Amazon EC2) and GitHub.
In the section “Walkthrough for automating Ansible playbook deployment,” we explain how to configure the pipeline, step by step. In the section “Alternative procedure: Use an AWS CloudFormation template,” we present a quick and repeatable solution. You can modify either method to suit your requirements.
|About this blog post|
|Time to read||8 min.|
|Time to complete
|~10 min. using CloudFormation
~30 min. following the walkthrough steps
|Cost to test the solution||~ $0|
|Learning level||Advanced (300)|
|AWS services||Amazon EC2
Amazon Linux 2
The following diagram shows the pipeline flow.
A push event triggers a webhook request, which is sent to an Amazon EC2 instance. We use NGINX to route the request to an Express server running on the EC2 instance. The Express server then runs an Ansible command to pull and run the newly pushed playbook.
First, set up Ansible on an Amazon EC2 instance running an Amazon Linux 2 Amazon Machine Image (AMI) connected to a GitHub repository that stores your playbooks. Second, configure a webhook, which is a way for an app to send other applications real-time information during a push event. This allows you to automatically configure multiple environments, which saves you the time and energy that would have otherwise been spent on manual processes.
For this walkthrough, you need the following:
- An AWS account
- An Amazon EC2 key pair
- An Amazon EC2 instance running an Amazon Linux 2 AMI
- A security group that allows SSH (Secure Shell) and HTTPS access
- A GitHub repository to store playbooks
Step 1: Set up webhook processing
To use Ansible with GitHub webhooks, set up webhook processing on the EC2 instance. This procedure uses NGINX as a reverse proxy to route the request to an Express server. Git is not required to process the webhook, but it is necessary for Ansible to pull the playbook from the repository.
- Access the EC2 instance using SSH. See Connecting to your Linux instance using SSH.
- Enable the Extra Packages for Enterprise Linux (EPEL) repository by running the following command.
The output looks like this:
- Apply the updates to the packages.
- Install Ansible, NGINX, and Git.
Your webhook processing is now set up.
Step 2. Install Node.js and set up the Express server
- Install Node.js.
- Choose a location for the Express server. In this example, we create a directory called
serverto store the relevant files.
app.jsthat runs the
ansible-pullcommand to pull and run the
playbook.ymlfile from a GitHub repository. The server is configured to listen on port 8080. You must know that the server is configured to listen on port 8080 because the NGINX configuration needs to know where to route the traffic that it receives. The port number is arbitrary, but the specification in the NGINX configuration file must match the port that is defined in the Express server code. In this example, replace
<playbook>with your information.
- Specify the GitHub user and repository where the playbooks are stored. This is required by the
ansible-pullcommand. In this example, replace
<playbook>with your information.
- Run the Express server.
Step 3. Set up a deploy key for your repository
- Create an SSH key on your instance. In this example, replace
<firstname.lastname@example.org>with your email address.
Keep the default settings, and press Enter to skip through the prompts.
- When the key is created, run the following code.
The output looks similar to this:
You will use this deploy key later in the procedure.
Step 4. Configure NGINX to route traffic
- Use the following basic configuration to listen on port 80 and route traffic to the port that the Express server listens to.
- Start NGINX.
Step 5. Set up GitHub to configure the webhook
- Log in to your GitHub account, and navigate to your repository settings. The page looks like this:
- Add the deploy key from Step 3.
- On your instance, navigate to the .ssh directory, where the public key is stored.
- Open the id_rsa.pub file and copy its contents. In this example, replace
<email@example.com>with your email address. It should look like the following.
- Choose Add deploy key, and paste the contents into the Key section. The page looks like this:
- On the Webhooks tab, choose Add webhook.
- Copy and paste your EC2 instance’s public IP address into the Payload URL section. This adds the webhook that is triggered when a push event occurs. When the webhook is created and a request is sent to the EC2 instance, the Recent Deliveries section looks like this:
This response indicates that the Express server received the request.
Alternative procedure: Use an AWS CloudFormation template
Use the following AWS CloudFormation template to provision the Ansible stack. (See Creating a stack on the AWS CloudFormation console). This stack does not create the web server code or the NGINX configuration file. For a sample configuration and sample code, see the previous section, “Walkthrough for automating Ansible playbook deployment.” This AWS CloudFormation template runs only in the US East (N. Virginia) Region, and you must use a public subnet with internet access. To use this template in another Region, configure the Mappings section to match your Region with the latest AMI ID.
This procedure provisions an EC2 instance in your AWS account. If you choose an instance type within the free tier, it incurs no costs as long as it follows free-tier limits.
To remove your stack, see Deleting a stack on the AWS CloudFormation console. To remove your instance after provisioning the environment through the console, see Terminate your instance.
In this post, we walked through setting up a pipeline that enables you to deploy your Ansible playbooks through a push event using a combination of webhooks and Amazon EC2. We also provided an AWS CloudFormation template that spins up the resources automatically. Whichever method you choose, the configuration of multiple environments is automated to save time and energy. When you no longer must push playbooks manually, your system can respond to events in seconds using automated playbooks. This allows you to engineer a process that maintains consistency in your environment and ensures quality performance.
Learn about another way to use Ansible on AWS: Running Ansible playbooks using EC2 Systems Manager Run Command and State Manager.
Please let us know your thoughts in the comments.