Configuring Jenkins on EC2 - A Step-by-Step Guide

Hello 👋

If you're interested in learning how to configure an EC2 instance as a Jenkins agent, this article may be helpful to you 😁

This follows on from my previous article running through Step-by-Step how to install Jenkins.

Before we get started, your EC2 Instance should be running, Security groups attached and the Key Pair in place. The Jenkins service should also be started and set to auto launch when the EC2 instance is started.

Please let me know what you think to this 👍

Connecting to EC2

Open a browser window and paste in your public IPv4 address from the AWS console followed by the 8080 port number. For example: ec2-xx-xxx-xxx-xxx.eu-west-2.compute.amazonaws.com:8080

You can also just type the IP Address followed by the port number too. This also works. For example: xx-xxx-xxx-xxx:8080

Unlocking Jenkins

This will bring you to the Jenkins sign in page and it'll be prompting you to unlock. 🔓

You'll see there is a file path provided which will contain the password. Establish a connection to the EC2 in your terminal and navigate to the path.

Running the command below will allow you to retrieve the password which you can copy and paste into the box on the Jenkins page.

sudo cat /var/lib/jenkins/secrets/initialAdminPassword        

 Initial Setup

There are two options you can choose here but for this we're going to chose Install suggested plugins.

A getting started page will appear installing all the pre-requisites.

Once this is complete, you'll be asked to setup an admin user.

Provide a username, password and an email address. You aren't able to proceed unless you specify an email address.  

By this point, you should be at the Instance Configuration page now where your EC2 address will already be populated in the Jenkins URL field.

🎉 Jenkins is setup and ready for configuration! 🥳

Setting up EC2 Instance as a Jenkins Agent 

Head back to the homepage of Jenkins and if you've used Jenkins before, it'll be a screen you most likely recognise. If you haven't used it before, it'll be the main Jenkins page ready for configuration. 🙂

Click on Manage Jenkins followed by Plugins, select Available Plugins, search for and select Amazon EC2. 

Install this plugin and you'll be redirected to a page where it cycles through progress.

After the install has completed, there will be an option you can chose to go back to the top of the page. Amazon EC2 plugin has now been successfully installed on Jenkins. 👍

At this point, just to confirm the plugin had installed correctly, I revisited the plugins section, selected Installed Plugins and confirmed the install was successful. 

Click on the Jenkins logo in the top left of the screen to return to the homepage. They'll be an an option you need to select called Configure a Cloud.

Select New cloud, Amazon EC2 and assign it a name of your choice. Select Create when you've entered the name.

Now you'll need to configure the Amazon EC2 credentials for Jenkins. Select the Add button and you’ll only have Jenkins available to select. Selecting Jenkins will display a new window.

In the Kind dropdown box, select AWS Credentials.

Scroll down and add in the IAM User Programmatic access keys. These keys must have the permissions to launch EC2 instances.

At this stage, I already had an IAM user setup. I created it when I was creating the infrastructure using Terraform. Details of how I did that are in my article here.

I went into IAM in the AWS console, found my user account and clicked on the Security Credentials tab. Previously, I’d downloaded the .csv containing the keys but I'd since removed it from my machine. Once you've downloaded the csv, you can't download it again.  

I selected the option to create a new access key and there was an option where the key will allow for an application to interact with an AWS compute service. As I wanted Jenkins to interact with the EC2 that’s what I chose. 

I downloaded the keys and entered them into the fields below

Once you’ve added the details, click Add and that portion is complete. ✔️

At this point I went on to choose a region but there was nothing listed. I had to go back to the Amazon EC2 Credentials and select my Key details from the dropdown box.

Scroll down and select your region. For my testing I selected eu-west-2.

We now have to add the EC2 Key Pair’s Private key. Underneath region, select Add and again, you should only see Jenkins available. 

In the Kind dropdown, select SSH username with private key. 

Set the username to ec2-user and select Enter directly under the Private Key section. 

Navigate to where your Private key is located on your machine, copy and paste all of it into this box. Once complete, click Add and this section is now finished ✔️

As above, you'll need to select the ec2-user from the dropdown box as it doesn't auto populate.

Click the test connection button and it should show success.😃 Click save for all the changes to be applied.

Congratulations! 🎉 You’re now ready to use an EC2 instance as a Jenkins agent.

Thank you for reading!