Transitioning a microservice application to the Amazon Web Services (AWS) cloud infrastructure can be a daunting and complex task for a development team new to AWS. The XebiaLabs blueprints for AWS can streamline the process of creating the AWS infrastructure, orchestrating the pipeline using XL Release, and deploying applications using XL Deploy.

This tutorial provides a working example to help you get started with DevOps as Code blueprints for AWS in XL Deploy and XL Release using a sample application provided in a public GitHub repository. The tutorial specifically demonstrates how you can use the XebiaLabs microservice-ecommerce blueprint to deploy a simple microservice demo application that consists of separate store, notification and invoice applications on Amazon Elastic Container Service for Kubernetes (EKS).

Review the prerequisites

AWS prerequisites

This tutorial requires AWS credentials including an AWS access key ID and AWS secret access key. Note: In a scenario in which you are already interacting with AWS using the AWS CLI, the blueprint configuration can pull existing credentials from your local configuration. If not, you can provide the credentials directly when configuring the blueprint.

GitHub repository

This tutorial utilizes a XebiaLabs GitHub repository that includes a folder and file structure for an sample microservices application that you will deploy to an EKS cluster in AWS using blueprint specifications.

Docker

A pre-built set of Docker containers is provided to simplify this tutorial. If not installed already, download and install:

You will also need a Docker Hub repository. You can use an existing Docker Hub repository or create a new one for this tutorial.

Step 1 Clone the GitHub branch

To get started, clone the sample GitHub repository.

For example, to clone the repository from the command line:

git clone https://github.com/xebialabs/e-commerce-microservice.git

Step 2 Review the sample application architecture

The cloned repository includes the components and files for the microservices e-commerce demo application.

sample app

The sample application consists of three microservices applications:

  • A gateway application (online store)
  • An invoice application
  • A notifications application

The following supporting files are included:

  • Docker compose files
  • Kubernetes files

For details on the contents of each of these files, refer to the accompanying README file in each directory of the sample GitHub repository.

Step 3 Create your Docker environment

A docker-compose.yaml file is provided to build the following Docker containers:

  • An XL Deploy server
  • An XL Release server with Shared Configuration settings that includes a defined connection to the XL Deploy server
  • A Jenkins server with a pre-defined job
  • A dockerproxy container
  • A container with the XL CLI installed. Note: This instance of XL CLI is used internally among the Docker containers. You will also install the XL CLI on your local host later in this tutorial.

Step 4 Customize Docker credentials and add licenses

Before running the docker-compose.yaml file, you must first customize it with your Docker credentials and provide licenses for XL Deploy and XL Release.

Add your Docker credentials to docker-compose.yaml

  1. Navigate to e-commerce-microservice/docker-compose/xebialabs
  2. Edit the docker-compose.yaml file and replace the ${DOCKER_USER} and ${DOCKER_PASS} values with your own license information. For example:

     - DOCKER_USER=mydockername
     - DOCKER_PASS=mydockerpassword
    
  3. Save the file.

Add the XL Deploy license file

Existing license

If you are an existing XL Deploy user and you already have a running instance of the product, you can copy and paste your deployit-license.lic file from your existing installation directory into e-commerce-microservice/docker-compose/xebialabs/xl-deploy/default-conf

New license

If you do not have an existing license, you must apply for a trial license.

  1. Go to the XebiaLabs trial site and follow the steps to obtain a trial license for XL Deploy.
  2. Navigate to e-commerce-microservice/docker-compose/xebialabs/xl-deploy/default-conf
  3. Create a new file named deployit-license.lic
  4. Open this file and paste the XL Deploy license you received in email and save it.

Add the XL Release license file

Existing license

If you are an existing XL Deploy user and you already have a running instance of the product, you can copy and paste your xl-release-license.lic from your existing installation directory into e-commerce-microservice/docker-compose/xebialabs/xl-release/default-conf

New license

If you do not have an existing license, you must apply for a trial license.

  1. Go to the XebiaLabs trial site and follow the steps to obtain a trial license for XL Release.
  2. Navigate to e-commerce-microservice/docker-compose/xebialabs/xl-release/default-conf
  3. Create a new file named xl-release-license.lic
  4. Open this file and paste the XL Release license you received in email and save it.

Step 5 Start Docker containers

Now that your Docker credentials and licenses are configured, you can start the Docker containers using the following command:

docker-compose up --build

Once the environment is successfully up and running, you can use the docker ps command to list the new containers:

  • XL Deploy
  • XL Release
  • Jenkins
  • XL CLI
  • Dockerproxy

Note: The XL CLI container will run, perform its tasks and exit, so will not be in constant running state. The docker ps command to see all containers, regardless of whether they are running.

Step 6 Verify applications are running

Ensure that you can successfully open the following applications in your browser:

  • XL Deploy: http://localhost:4516
  • XL Release: http://localhost:5516
  • Jenkins: http://localhost:8080

For each of these applications, the username and password are admin and admin.

Step 7 Run the XL CLI blueprint command

Run the blueprint command and answer a few simple questions specific to your deployment infrastructure.

Note: For this tutorial, we will use the XL CLI “wrapper” executable that is included in the root directory of the cloned repository to execute the commands. For details about the wrapper, see Using XL wrapper scripts.

  1. Navigate to the root directory for the cloned repository.
  2. Type xl blueprint. The list of available blueprints displays.
  3. Select aws/microservice-ecommerce. The XL CLI walks you through a series of prompts.
Prompt Description
What is the name of the application? Type a name. For this tutorial, type e-commerce.
Do you want to use AWS credentials from ~/.aws/credentials file? If you have the AWS CLI installed, type Yes and you will be given the choice of using credentials from the file or entering them manually.

If you do not have the AWS CLI installed, type No. You are prompted for your AWS Access Key ID and AWS Secret Access Key.
Select the AWS region: A list of available regions displays. Select the desired region.
Do you want to provision a new AWS EKS cluster? If you already have an EKS cluster configured, type No. You are prompted for the cluster name and endpoint.

If you do not have an EKS cluster configured, type Yes. You are prompted for a cluster name. For this tutorial, type ecommerce.
What is the name of the namespace? Kubernetes namespaces help different projects, teams, or customers to share a Kubernetes cluster. For this tutorial, type xl-demo.
  1. Press Enter to run the blueprint.

Step 8 Review folders and files generated by the blueprint

Executing the blueprint command generates the following folders and files in the repository:

  • A cloudformation folder: Includes CloudFormation templates required to provision the cluster. This folder is generated only if you elected to provision a new EKS cluster.
  • A xebialabs folder and the following new files:
    • .gitignore (this file is used for ignoring the secrets.xlvals file for security purposes)
    • README.md
    • values.xlvals
    • secrets.xlvals
    • xld-cloudformation-apps.yaml
    • xld-infra-env.yaml
    • xld-kubernetes-apps.yaml
    • xlr-pipeline-ci-cd.yaml
    • xlr-pipeline-destroy.yaml
  • A xebialabs.yaml file: A YAML file of the Import kind that lists multiple YAML files and executes them in order.
  • A new file in the kubernetes folder called aws-auth-cm.yaml

Step 9 Update a Kubernetes YAML file with your Docker repository name

The YAML files saved in the kubernetes > store folder are used to deploy to a Kubernetes cluster:

  • store-deployment.yml
  • store-mysql.yml
  • store-service.yml

In the store-deployment.yml file, you must replace the current Docker Hub organization and repository with your own.

Replace the Docker Hub organization and repository (xebialabsunsupported/ecommerce-store) in the following line:

image: xebialabsunsupported/ecommerce-store:@IMAGE_TAG@

with your own organization and repository. For example:

image: myorg/myrepo:@IMAGE_TAG@

The @IMAGE_TAG@ will be automatically populated later in the tutorial when the Jenkins job runs.

Step 10 Apply the XebiaLabs YAML files

The xebialabs.yaml that is generated by the blueprint is an Import kind YAML file that stacks the following YAML files into a single YAML and runs them sequentially:

apiVersion: xl/v1
kind: Import
metadata:
  imports:
    - xld-infra-env.yaml
    - xld-cloudformation-apps.yaml
    - xlr-pipeline-ci-cd.yaml
    - xlr-pipeline-destroy.yaml

From the root directory of the cloned repository, run the following command: xl apply -f xebialabs.yaml

View the resulting output that indicates the files were successfully applied.

Step 11 Check the results in XL Deploy

Check the XL Deploy UI which should reflect the results of running the xld-infra-env.yaml and the xld-cloudformation-apps.yaml specifications.

Applications node

Open XL Deploy, click Explorer in the top bar, and expand Applications > e-commerce.

sample app

Under the e-commerce application, you see:

  • EKS-CLOUDFORMATION: Includes the cloud formation stacks needed to create the infrastructure
  • EKS-LAMBDA: Includes an app needed to create keypairs in AWS.
  • K8S: Includes the Kubernetes applications. Note: At this point, the K8S node includes only the e-commerce-namespace application. Later, when we perform the deployment using the Jenkins CI/CD pipeline, multiple applications and a versioned package for the e-commerce-store microservice application will be created.

Environments and Infrastructure nodes

Now let’s look under the Environments and Infrastructure nodes in XL Deploy.

Expand Environments > e-commerce.

sample app

Under the e-commerce node, you now see the aws-cloudformation-e-commerce environment which references two infrastructure containers:

  • aws-e-commerce
  • eks-cloudformation

Under the Infrastructure node, you now see these infrastructure containers:

  • aws-e-commerce: An AWS.Cloud type container to which we will deploy the EKS-LAMDA application.
  • eks-cloudformation: An aws.cloudformation.Stack type container to which we will deploy the EKS-CLOUDFORMATION applications and our microservice applications.

Step 12 Check the results in XL Release

Finally, you can check XL Release which should reflect the results of running the xlr-pipeline-ci-cd.yaml and the xlr-pipeline-destroy.yaml specifications to create two new templates.

  1. Open XL Release and click Design > Folders.
  2. Click the e-commerce folder and the Templates tab. Note the two templates contained within:
  • e-commerce-ci-cd: A CI-CD template to execute the deployment.
  • e-commerce-destroy: A CI-CD template to destroy the deployment.

Step 13 Create and run a release in XL Release

  1. From the Templates tab, click the e-commerce-ci-cd. The template displays showing the release phases and tasks.
  2. Click New release.
  3. Type a name for the release. For this tutorial, type build 1.
  4. Click Create. The e-commerce/build 1 release is created.
  5. Click Start Release.

Phase 1: Provision infrastructure

The Provision infrastructure phase begins, provisioning the Lambda artifacts, the AWS VPC and IAM resources, and the AWS EKS cluster. You can observe the provisioning progress using the AWS CloudFormation UI.

Phase 2: Build e-commerce application

Once the infrastructure is successfully provisioned, the Build e-commerce application phase begins. In this phase a Docker image is created for the Store microservice. For this tutorial, this is done using the Jenkins pipeline that is connected to the JenkinsFile.

You can observe the progress using the Jenkins UI. The Jenkins build process will add the container with the contents in the repository branch. Once complete, Jenkins will push the images to your Docker Hub repository so that they can later be pulled into AWS EKS.

Once the Jenkins build is complete, you can log in to Docker Hub and observe the container that was built in the public repository.

sample app

Step 14 Check XL Deploy to verify Kubernetes applications are added

  1. Return to XL Deploy, click Explorer in the top bar, and expand Applications > e-commerce.
  2. Expand the K8S node.
  3. Note the additional applications that were created.

    sample app

    Before we started, the only application listed was e-commerce-namespace. Now, the full list of applications is included.

  4. Expand the e-commerce-namespace node. A package (version 1.0.1) is now listed with two applications.

    sample app

Step 15 Check XL Release pipeline progress

Return to XL Release and check the progress of the pipeline. Once the Deploy e-commerce application is complete, the Test phase starts, running integration and smoke tests.

When complete, a manual task called Verify application is highlighted. Click the Verify application task and open the provided URL in a new tab or browser.

The XebiaLabs E-Commerce Store application displays.

sample app

Conclusion

In this tutorial, we provisioned the AWS EKS infrastructure, deployed our e-commerce application and observed the process using the XL Deploy and XL Release UIs.