How to Deploy WSO2 API Manager on Amazon ECS
At WSO2 we have been mostly using Kubernetes and DC/OS for deploying WSO2 middleware on containers in production. While those can be run on any public cloud platform some users may prefer to use Amazon’s own container cluster management platform EC2 Container Service (ECS) due to various reasons. Very recently we evaluated ECS on running WSO2 API Manager on it with Docker.
As we found the main advantage of using ECS on AWS over setting up Kubernetes or DC/OS on AWS is that for ECS we would not need to create any EC2 instances for it’s controller, rather it will be provided as a service. On the contrary, as of today Kubernetes and DC/OS provide much more rich container management features compared to ECS. Nevertheless, in this article I will explain how to deploy WSO2 API Manager on ECS and configure load balancing rules in five steps:
1. Create an ECS Cluster
1.1. First of all login to your AWS console, open “EC2 Container Service” page and click on the “Create Cluster” button to create a new ECS cluster:
1.2 Enter ECS cluster details as follows; select the EC2 instance type and number of instances according to your capacity plan. In this POC I have used one m4.xlarge instance, in a production environment you may need more than one EC2 instance to provide HA:
1.3 Keep the default networking configuration as it is; this will create a VPC, two subnets and a new security group. As I understood port 80 is opened in ECS instances for communicating with the ECS agent. Therefore, CIDR block might not need to have 0.0.0.0/0 even though its given by default:
1.4 Scroll down on the same page and select the option “Create new role” under “Container instance IAM role”. This will be used by the ECS container agent to makes calls to the Amazon ECS API actions:
1.5 Then press the “Create Cluster” button and wait for the ECS cluster to be created successfully. Once completed press the “View Cluster” button:
1.6 Now ECS will create EC2 instances and register them with the ECS cluster, this may take few minutes. Watch the “ECS Instances” tab for the instances to get activated:
2. Create an Application Load Balancer
2.1 Now we would need to create an application load balancer for routing requests to ECS containers. Open Load Balancers page under EC2 service and press the “Create Load Balancer” button:
2.2 Provide a load balancer name, HTTP and HTTPS listeners (keep the ports as 80 and 443):
2.3 Provide availability zones for the load balancer to register container instances:
2.4 Provide a SSL certificate and security policy for the load balancer. For this you can use the wso2carbon self-signed certificate shipped with API Manager, in a production environment you might need to use a CA signed certificate:
2.5 Configure a new security group for the load balancer. According to the clients that access the load balancer you may need to change the source CIDR:
2.6 Configure the routing target group as follows. Here the application load balancer will use the target group for providing the routing rules and health checks. For the health check we will be deploying an echo API in a future step with the path “/echo/wso2":
2.7 Select the ECS instance(s) from the instances list and press the “Add to registered” button and complete the load balancer creation wizard:
2.8 Review the configuration at the final step of the wizard and create the load balancer, target group and the security group.
3. Create an EC2 Container Registry
3.1. In this approach we will be using an EC2 container registry for maintaining our container images. Create a new EC2 container registry and note down the registry hostname:
In the above sample, registry hostname is “610968236798.dkr.ecr.us-west-1.amazonaws.com”.
3.2. Next, we would need to build a new Docker image based on the official WSO2 API Manager Docker image for including API manager configurations and few APIs for tunneling API manager UI requests through the gateway. To do this a WSO2 account would be needed. If you don’t have one please create one at https://wso2.com/user/register and login to WSO2 Docker registry on your local machine or on an EC2 instance using the following Docker command.
I would recommend to use an EC2 instance for this process as it might take some time to transfer Docker images from your local machine to the EC2 container registry depending on the internet brandwidth and latency.
$ docker login https://docker.wso2.com3.3. Pull the latest WSO2 API Manager docker image to your local machine:
$ docker pull docker.wso2.com/wso2am:2.1.03.4 Clone the following git repository, this has a Dockerfile and a set of configuration files for creating a custom API Manager Docker image with configurations:
$ git clone https://github.com/imesh/wso2-apim-docker.git3.5 Follow the README.md file and set load balancer hostname, http and https ports. You can find these details on the description tab of the load balancer:
$ cd wso2-apim-docker$ cat README.md
Similarly if any other configurations need to be added to the API-M container such as datasources, clustering configurations, etc copy those configuration files from the product distribution to the above conf directory and set the required values.
3.6 Build the Docker image after updating the configuration files with the following command:
$ cd wso2-apim-docker$ ./build.sh
3.7. Tag the Docker image with the EC2 container registry hostname and repository name:
$ docker tag wso2am-with-config:2.1.0 [EC2-Container-Registry-Hostname]/wso2am:2.1.0For an example:
$ docker tag docker.wso2.com/wso2am:2.1.0 610968236798.dkr.ecr.us-west-1.amazonaws.com/wso2am:2.1.03.8. Go to the above created container registry and press the “View Push Commands” button:
3.9. Execute the AWS CLI command shown in the below page to retrieve the Docker login credentials. Afterwards, execute the Docker login command printed on the shell. This will add Docker credentials in your local machine for pushing the above Docker image to EC2 container registry:
3.10. Push above API-M Docker image to the EC2 Container Registry created above:
$ docker push [EC2-Container-Registry-Hostname]/wso2am:2.1.0For an example:
$ docker push 610968236798.dkr.ecr.us-west-1.amazonaws.com/wso2am:2.1.0Once the container is pushed, it should be listed in the ECS container registry repository:
4. Create an ECS Task Definition
4.1 ECS uses tasks for scheduling containers in its container cluster. Create a new task definition by pressing the “Create new Task Definition” button on the “Task Definitions” page:
4.2 Provide a name for the task definition and keep networking mode as “Bridge”. With “Host” networking mode only one container will be able to create a given container port on the same host:
4.3 Press the “Add container” button:
4.4 Provide a container name and the API-M Docker Image:
4.5 Provide port mappings as follows. Zero has been used for the host ports to let it generate dynamic host ports:
Afterwards, add the container to the task definition and create the task definition.
5. Create an ECS Service
5.1 Next, we need to create an ECS service to let the load balancer discover the container host port mappings and for creating tasks from the task definition. Go to the above created task definition and create a service from the actions menu:
5.2 Provide a service name and set the number of tasks to one:
5.3 Select the application load balancer created above, select the container port 8243 (this is the HTTPS port of the API gateway) and press the “Add to ELB” button:
5.4 Select the target group created for the load balancer as shown below:
5.5 Press the “Save” button and press the “Create Service” button:
5.6 Once the service is created successfully, press the “View Service” button:
5.7 Now the service will get created and it will create a task for spinning a container. On the service page, wait for the task to be activated:
5.8 Go to the load balancer target group and wait for the container to get started. Once the API Manager server is completely started the health check will pass and the status will changed to “healthy”:
5.9 Now, find the load balancer DNS name from the load balancer description tab:
5.10 Open a new browser tab and access the API-M Publisher using the load balancer DNS name as follows:
5.11 Login to the API publisher using the default admin credentials (admin/admin):
6. Deploy Sample PizzaShack API
6.1 Now you can deploy the sample PizzaShack API bundled with the API manager and verify the deployment. To do this, press the Deploy Sample API button on the API Publisher home page:
6.2 Go to API Store and subscribe for the above API. Then generate keys and verify the API by using the API console:
Conclusion
In this article WSO2 API Manager was deployed on Amazon ECS using a single container with all-in-one profile which includes API Publisher, Store, Key Manager, Throttling Manager, Gateway, Message Broker, and CEP in one JVM. In this deployment the ECS service will auto-heal the container by scheduling another container via ECS tasks if the existing container fails to respond. This process can be verified by stopping the current task forcefully via the ECS console. As I found currently ECS services only allow to map one port of a container with an ELB. Therefore, the API Publisher and Store UIs were exposed via the API gateway. In a production deployment if needed API Manager components can be run in separate container clusters and scaled separately.
