Automating Apps Deployment to Amazon Lightsail

In this article I’m going through this documentation page where Mike Coleman takes us on Using AWS CodeDeploy and AWS CodePipeline to Deploy Applications to Amazon Lightsail. It’s basically a guide of the process of setting up a deployment pipeline. In it, we’ll start by creating a service role for CodeDeploy, an Amazon S3 bucket, and an IAM user. After deploying these services, we’ll create a Lightsail instance. In addition to that, we will install and configure the CodeDeploy agent, as well as registering the instance with CodeDeploy. Finally, we’ll create an application in CodeDeploy, and configure CodePipeline to kick off a new deployment whenever we push changes to GitHub.

While that might sound straightforward tutorial following to you, this got me into some interesting Q&As that weren’t yet openly available online

• Create a Lightsail instance and install the CodeDeploy agent
• Setup the application in CodeDeploy with Load balancer
• Setup CodePipeline – Deploy step has a status of failed
• The on-premises instance could not be registered because the request included an IAM user ARN that has already been used to register an instance

I’m also gratefull that this exercise lead me also to meet Marcin whose availability to share his experience and friendliness was crucial.

In order to progress, there’s a few prerequisites to complete this walkthrough

• GitHub account.
• git installed locally.
• AWS account.
• AWS CLI installed and configured locally.

As of now we’ll go through the following steps

1. Create a service role.
2. Create an S3 bucket.
3. Create an IAM policy.
4. Create an IAM user.
5. Create a Lightsail instance and install the CodeDeploy agent.
6. Verify the CodeDeploy agent.
7. Setup the application in CodeDeploy.
8. Fork the GitHub Repo.
9. Setup CodePipeline.
10. Test and Update the Application.

1. Create a service role. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/. On the Create role page, choose AWS service, and from the Choose the service that will use this role list, choose CodeDeploy. Near the bottom of the screen under Select your use case, choose CodeDeploy and click Next: Permissions.

On the Attached permissions policy page, the default permission policy (AWSCodeDeployRule) is displayed. You can click on the policy name if you’d like to review the details of the policy. Click Next: Tags, and then click Next: Review.

On the Create Role page, in Role name, enter a name for the service role (for example, CodeDeployServiceRole).

2. Create an S3 bucket. Sign in to the AWS Management Console and open the S3 console, and click Create Bucket. Enter a name under Bucket name. The name must be unique across all of S3 (Be sure to copy the S3 bucket name into your text document). Ensure Block all public access is checked. Click Create bucket.

3. Create an IAM policy. Sign in to the AWS Management Console and open the IAM console. In the navigation pane, choose Policies, and then choose Create policy.

Click on the JSON tab. Erase the content in the editor window, and paste in the code from below (NOTE: Be sure to replace <S3 Bucket Name> with the name of the S3 bucket you created in the previous step and do not change the date in Version)

{

  "Version": "2012-10-17",

  "Statement": [

    {

      "Effect": "Allow",

      "Action": [

        "s3:Get*",

        "s3:List*"

      ],

      "Resource": [

        "arn:aws:s3:::tiagocodedeploylightsailbucket/*"

      ]

    }

  ]

}

Click Review policy. Enter CodeDeployS3BucketPolicy for the policy name. Click Create policy.

4. Create an IAM user. Stay in the IAM console. In the navigation pane, choose Users, and then choose Add user. Enter LightSailCodeDeployUser for the User name and click Programmatic access under Select AWS access type (you use programmatic access since this user account will never need to log into the console). Click Next: permissions.  

Click Attach existing polices directly. Enter CodeDeployS3BucketPolicy in the search box, and check the box next to the CodeDeployS3BucketPolicy policy.  

Click Next: Tags. Click Next: Review.

Click Create user. Copy the Access key ID and Secret access key into your text document. You will need to click Show to display the secret access key. (Note: If you do not copy these values now, you cannot go back and retrieve them from the console. You will need to create a new set of credentials)

Click Close.

Click on the user you just and copy the User ARN into your document.

5. Create a Lightsail instance and install the CodeDeploy agent. Log in to the AWS Management Console, and navigate to the Lightsail home page. Click Create instance. Ensure that you’re creating your instance in the correct AWS Region. Under Pick your instance image click on Linux/Unix. Click on OS Only. Select Amazon Linux.

Scroll down and click + Add launch script. In the code below paste in your Access key ID, Secret access key, and IAM User ARN from your text document. Also replace <Desired Region> with the Region that you deployed instance into (e.g. eu-west-2).

After you edit the code below, paste it into the launch script edit window. The configuration below allows the CodeDeploy agent run with the permissions you assigned to the IAM user earlier. These permissions allow the CodeDeploy agent to download the deployment artifact created by the CodeDeploy service from the S3 bucket where it will be stored. Additionally, the agent will use the information in the artifact to deploy or update your application.

mkdir /etc/codedeploy-agent/

mkdir /etc/codedeploy-agent/conf

cat <<EOT >> /etc/codedeploy-agent/conf/codedeploy.onpremises.yml

---

aws_access_key_id: AKIAXUSNJRISPGN37YHX

aws_secret_access_key: <Secret Access Key>

iam_user_arn: arn:aws:iam::525221857828:user/LightSailCodeDeployUser

region: eu-west-2

EOT

wget https://aws-codedeploy-us-west-2.s3.us-west-2.amazonaws.com/latest/install

chmod +x ./install

sudo ./install auto

Note: For Amazon Linux 2 the script should be instead

mkdir -p /etc/codedeploy-agent/conf

cat <<EOT >> /etc/codedeploy-agent/conf/codedeploy.onpremises.yml
---

aws_access_key_id: ACCESS

aws_secret_access_key: SECRET

iam_user_arn: arn:aws:iam::525221857828:user/GeneralUser

region: eu-west-2

EOT

yum install -y wget ruby

wget https://aws-codedeploy-us-west-2.s3.us-west-2.amazonaws.com/latest/install

chmod +x ./install

env AWS_REGION=eu-west-2 ./install rpm

Enter codedeploy for the instance name under Identify your instance. Click Create Instance.

6. Verify the CodeDeploy agent. Start an SSH session by clicking on the terminal icon next to the name of your instance.

On the command line of the Lightsail terminal session enter the command below to verify the CodeDeploy agent is running.
sudo service codedeploy-agent status

Enter the command below using the AWS CLI in a terminal session on your local machine to register your Lightsail instance with CodeDeploy.

NOTE: Replace <IAM User ARN> with the value in your document and the <Desired Region> with the appropriate Region.
NOTE: If you did not name your Lightsail instance codedeploy you will need to adjust the –instance-name parameter accordingly.
NOTE: The command does not provide any output

aws deploy register-on-premises-instance --instance-name codedeploy --iam-user-arn <IAM User ARN> --region <Desired Region>

Enter the following command using the AWS CLI in a terminal session on your local machine to tag your Lightsail instance in CodeDeploy. The tag will be used by CodeDeploy to know where to install your code.
NOTE: If you did not name your Lightsail instance codedeploy you will need to adjust the –instance-name parameter accordingly.
NOTE: Replace <Desired Region> with the appropriate Region.
NOTE: The command does not provide any output

aws deploy add-tags-to-on-premises-instances --instance-names codedeploy --tags Key=Name,Value=CodeDeployLightsailDemo --region <Desired Region>

Enter the command below using the AWS CLI in a terminal session on your local machine to verify your machine was successfully registered:
NOTE: Replace <Desired Region> with the appropriate Region.

aws deploy list-on-premises-instances --region <Desired Region>

7. Setup the application in CodeDeploy. Navigate to the CodeDeploy console, make sure you’re in the correct Region, and click Create application. Enter CodeDeployLightsailDemo for the Application name and select EC2/On-premises under Compute platform. Click Create application.

In the Deployment groups section Click Create deployment group. Enter CodeDeployLightsailDemoDeploymentGroup for the Deployment group name. Click in the text box for Enter a service role and select the service role you created earlier (CodeDeployServiceRole).

Under Environment configuration check the box for On-premises instances. Under Key enter Name and under Value enter CodeDeployLightsailDemo.

Under Load balancer uncheck Enable load balancing. Click Create deployment group. (Note that in the following image it says the region is N. Virginia. I had to change it to London later on in the process or else the deployment pipeline would get a failed status).

8. Fork the GitHub Repo. Sign into GithHub. Navigate to the demo repository: http://github.com/mikegcoleman/codedeploygithubdemo. To the right of the repository name at the top click the Fork. Click on the account that you want to fork the repository into. After a few seconds the fork process completes, and you are redirected to the new repo in your account.

9. Setup CodePipeline. Navigate to the CodePipeline console, ensure you’re in the correct Region, and click Create pipeline. Enter CodeDeployLightsailDemoPipeline for the Pipeline name. Click on Advanced Settings. 

Under Artifact store click the radio button next to Custom Location. Click into the Bucket text box and select the S3 bucket you created earlier. Click Next.

From the Source provider drop down choose Click Connect to GitHub and follow any prompts to authorize CodePipeline to access your GitHub account.
Note: If you’ve connected GitHub previously there will not be any additional prompts.

Click in the Repository text box and select the repository you forked earlier. The name should be <your github username>/CodeDeployGitHubDemo. Click in the Branch box and choose master. Click Next.

Since there isn’t a build stage click Skip build stage and confirm by clicking Skip.

Choose AWS CodeDeploy from the Deploy provider Ensure the appropriate Region is selected. Choose CodeDeployLightsailDemo from the Application name list. Choose CodeDeployLightsailDemoDeploymentGroup from the Deployment group list. Click Next.

Click Create pipeline. You’ll be taken to the details page for your pipeline, and can watch the status of the pipeline update.

Once the Deploy step has a status of succeeded feel free to move on to the next section.

10. Test and Update the Application. Now if I go to the Public IP of the instance, can see the following page

Let’s now clone the repo locally (git clone git@github.com:tiago-peres/CodeDeployGitHubDemo.git), do some changes in the page and then add, commit and push to master to see it update.

Great, you now have an understanding of how to automate the deployment and updating an application running on Lightsail using CodeDeploy and CodePipeline.