Amazon ECS with Portworx

This document presents the non-Kubernetes method of installing Portworx on Amazon ECS. Please refer to the AWS page for details on installing Portworx with Kubernetes on AWS.

This guide shows you how you can easily deploy Portworx on Amazon Elastic Container Service ECS

Step 1: Create an ECS cluster

In this example, we create an ECS cluster called ecs-demo1 using default AWS AMI (ami-b2df2ca4) and create two EC2 instances in the US-EAST-1 region.

As of this guide is written, the default ECS AMI uses Docker 1.12.6. Note that Portworx, Inc. recommends a minimum cluster size of 3 nodes.

Create the cluster in the console

Log into the ECS console and create an ecs cluster called “ecs-demo1”.

ecs-clust-create

In the above example, the Container Instance IAM role is used by the ECS container agent. This ECS container agent is deployed by default with the EC2 instances from the ECS wizard. Note that this agent makes calls to AWS ECS API actions on your behalf. Thus, these EC2 instances that are running the ECS container agent require an IAM role that has permission to join ECS cluster and launch containers within the cluster.

Create a custom IAM role and Select Role Type “Amazon EC2 Role for Container Service”. This is the minimal required permission to launch ECS cluster. And depending on your use case, you may need to set up additional AWS policies for your ECS to access and use other AWS resources. Below is the policy for the “AmazonEC2ContainerServiceRole”:

    {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
            "ec2:AuthorizeSecurityGroupIngress",
            "ec2:Describe*",
            "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
            "elasticloadbalancing:DeregisterTargets",
            "elasticloadbalancing:Describe*",
            "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
            "elasticloadbalancing:RegisterTargets"
             ],
            "Resource": "*"
          }
          ]
     }

Use the created custom IAM role ECS for this ECS cluster and the security group should allow inbound ssh access from your network.

Your EC2 instances must have the correct IAM role set.

After the ECS cluster “ecs-demo1” successfully launches, the corresponding EC2 instances that belong to this ECS cluster can be found under the “ECS instance” tab of ECS console or from AWS EC2 console. Each of this EC2 instances is running with an amazon-ecs-agent in the docker container.

ecs-clust-create

Add storage capacity to each EC2 instance

This section explains how to provision storage for these EC2 instances by creating new EBS volumes and attaching them to these EC2 instances. Portworx will be using the EBS volumes to provision storage to your containers. Below, we are creating a 20GB EBS volume in the same region “us-east-1b” of the launched EC2 instances. Ensure all ECS instances are attached with the EBS volumes.

ecs-clust-create

Note that there is no need to format the EBS volumes once they are created and attached to the EC2 instance. Portworx will pick up the available unformatted drives (if you use the -a option as show below in the next step) or you can point to the appropriate block device for the Portworx to pick up by using the -s option when you launch Portworx with the docker run command.

Step 2: Deploy Portworx

Install Portworx on each ECS instance. Portworx will use the EBS volumes you provisioned in step 4.

The installation and setup of Portworx OCI bundle is a 4-step process:

Install the Portworx OCI bundle
Configure Portworx under runC
Download and activate the Portworx service
Enable log rotation

Step 2.1: Install the Portworx OCI bundle

Portworx provides a Docker based installation utility to help deploy the Portworx OCI bundle. This bundle can be installed by running the following Docker container on your host system:

latest_stable=$(curl -fsSL "https://install.portworx.com?type=dock&stork=false&aut=false" | awk '/image: / {print $2}' | head -1)
# Download OCI bits (reminder, you will still need to run `px-runc install ..` after this step)
sudo docker run --entrypoint /runc-entry-point.sh \
    --rm -i --privileged=true \
    -v /opt/pwx:/opt/pwx -v /etc/pwx:/etc/pwx \
    $latest_stable

Step 2.2: Configure Portworx under runC

Now that the Portworx OCI bundle has been deployed, we have to configure it by running the following:

# Basic installation
sudo /opt/pwx/bin/px-runc install -sysd /dev/null -c MY_CLUSTER_ID \
  -k etcd://myetc.company.com:2379 \
  -s /dev/xvdb -s /dev/xvdc {{ include.sched-flags }}

Step 2.3: Download and activate the Portworx service

Since the Amazon ECS systems do not have the systemd service available, we will need to start Portworx service via the custom init-script:

sudo curl "https://docs.portworx.com/samples/ecs/portworx-sysvinit.sh" -o /etc/rc.d/init.d/portworx
sudo chmod 755 /etc/rc.d/init.d/portworx
sudo chkconfig --add portworx
sudo service portworx start

Step 2.4: Enable log rotation

Finally, since the Portworx service creates some amount of log-files, we need to ensure these logs are recycled on regular basis, using systems’ “logrotate” service:

cat > /etc/logrotate.d/portworx << _EOF
/var/log/portworx.log {
  minsize 50M
  daily
  rotate 5
  missingok
  compress
  notifempty
  nocreate
  postrotate
      service portworx restart >/dev/null 2>&1 || true
  endscript
}
_EOF

Step 3: Setup ECS task with Portworx volume from ECS CLI workstation

From your linux workstation download and setup AWS ECS CLI utilities

Download and install ECS CLI (detail instructions)

sudo curl -o /usr/local/bin/ecs-cli "https://s3.amazonaws.com/amazon-ecs-cli/ecs-cli-linux-amd64-latest"
sudo chmod +x /usr/local/bin/ecs-cli

Configure AWS ECS CLI on your workstation

export AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXX
export AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXX
ecs-cli configure --region us-east-1 --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY --cluster ecs-demo1

Create a 1GB Portworx volume using the Docker CLI. ssh into one of the ECS instances and create this Portworx volumes.

ssh -i ~/.ssh/id_rsa ec2-user@52.91.191.220
docker volume create -d pxd --name=demovol --opt size=1 --opt repl=3 --opt shared=true

demovol

docker volume ls

DRIVER              VOLUME NAME
pxd                 demovol

From your ECS CLI workstation, which has the ecs-cli command, setup and launch the ECS task definition with previously created Portworx volume. Create a task definition file “redis.yml” which will launch two containers: redis based on redis image, and web based on binocarlos/moby-counter. Then, use the ecs-cli command to post this task definition and launch it.

cat redis.yml

  web:
  image: binocarlos/moby-counter
  links:
    -  redis:redis
  redis:
  image: redis
  volumes:
    -  demovol:/data

ecs-cli compose --file redis.yml up

INFO[0001] Using ECS task definition                     TaskDefinition="ecscompose-root:1"
INFO[0001] Starting container...                         container="59701c44-c267-4c85-a8c0-ff87910af535/web"
INFO[0001] Starting container...                         container="59701c44-c267-4c85-a8c0-ff87910af535/redis"
INFO[0001] Describe ECS container status                 container="59701c44-c267-4c85-a8c0-ff87910af535/redis" desiredStatus=RUNNING lastStatus=PENDING taskDefinition="ecscompose-root:1"
INFO[0001] Describe ECS container status                 container="59701c44-c267-4c85-a8c0-ff87910af535/web" desiredStatus=RUNNING lastStatus=PENDING taskDefinition="ecscompose-root:1"
INFO[0013] Started container...                          container="59701c44-c267-4c85-a8c0-ff87910af535/redis" desiredStatus=RUNNING lastStatus=RUNNING taskDefinition="ecscompose-root:1"
INFO[0013] Started container...                          container="59701c44-c267-4c85-a8c0-ff87910af535/web" desiredStatus=RUNNING lastStatus=RUNNING taskDefinition="ecscompose-root:1"

ecs-cli ps

Name                                               State    Ports                                                          TaskDefinition
59701c44-c267-4c85-a8c0-ff87910af535/redis         RUNNING                                                                 ecscompose-root:1
59701c44-c267-4c85-a8c0-ff87910af535/web           RUNNING                                                                 ecscompose-root:1

You can also view the task status in the ECS console.
On the above ECS console, Clusters -> pick your cluster ecs-demo1 and click on the Container Instance ID that corresponding to the running task. This will display the containers’ information including where are these containers deployed, into which EC2 instance. Below, we find that the task defined containers are deployed on EC2 instance with public IP address 52.91.191.220.

From above, ssh into the EC2 instance 52.91.191.220 and verify Portworx volume is attached to running container.

sudo docker ps -a

CONTAINER ID        IMAGE                            COMMAND                  CREATED             STATUS              PORTS                                             NAMES
7ba93d51918b        binocarlos/moby-counter          "node index.js"          12 hours ago        Up 12 hours         80/tcp                                            ecs-ecscompose-root-1-web-c2fbfff3bf92b1dad401
e25ba9131f9b        redis                            "docker-entrypoint.sh"   12 hours ago        Up 12 hours         6379/tcp                                          ecs-ecscompose-root-1-redis-a6a6a2fcb4a6d188e601

pxctl volume list

ID                      NAME                    SIZE    HA      SHARED  ENCRYPTED       IO_PRIORITY     SCALE   STATUS
1061916907972944739     demovol                 1 GiB   3       yes     no              LOW             0       up - attached on 172.31.31.61

Check the ecs-ecscompose-root-1-redis-a6a6a2fcb4a6d188e601 redis container and verify that a 1GB pxfs volume is mounted on /data:

sudo docker exec -it ecs-ecscompose-root-1-redis-a6a6a2fcb4a6d188e601 sh -c 'df -kh'

Filesystem                                                                                        Size  Used Avail Use% Mounted on
/dev/mapper/docker-202:1-263203-3f7e353e23d7ba722fc74d1fb7db60e34f98933355ac65f78e6b4f2bcde19778  9.8G  215M  9.0G   3% /
tmpfs                                                                                             3.9G     0  3.9G   0% /dev
tmpfs                                                                                             3.9G     0  3.9G   0% /sys/fs/cgroup
pxfs                                                                                              976M  2.5M  907M   1% /data
/dev/xvda1                                                                                        7.8G  1.3G  6.5G  16% /etc/hosts
shm                                                                                                64M     0   64M   0% /dev/shm

Step 4: Setup ECS task with Portworx volume via AWS ECS console

Optional: the same process of step3 but do it on AWS GUI

Create a ECS tasks definition directly via the ECS console (GUI) and using Portworx volume.

ssh into one of the EC2 instance and create a new Portworx volume using Docker CLI.

docker volume create -d pxd --name=demovol --opt size=1 --opt repl=3 --opt shared=true

In AWS ECS console, choose the previously created cluster ecs-demo1; then create a new task definition.
From the new task definition screen, enter the task definition name redis-demo and click Add volume near the bottom of the page.
Enter the Name in the Add volume screen, that is just the name for your volume defined in this task definition and no need to be the same as the Portworx volume name. Then enter the Source path, and this is the Portworx volume name demovol.
After added the volume, click Add container button to define your containers specification.
From the Add container screen, enter the Container name “redis” and Image* “redis” ; then click the Add button.
To add another container, on the same Create a Task Definition screen, click Add container button. On the Add container screen, enter the Container name “web” and Image* “binocarlos/moby-counter” and on NETWORK SETTINGS Links enter “redis:redis” ; then on STORAGE AND LOGGING Mount Points select from drop down “volume0” and enter the Container path “/data” ; and then click the Add button.
On the same task definition screen, click create button at the of the screen.
From the AWS ECS console, Task Definitions, select the definition “redis-demo” and click Actions and select run
Click Run Task
You will see the task is submitted and change status from PENDING to RUNNING.