ecspresso advent calendar 2020 day 3 - Importing Existing ECS Services

This is Day 3 of the ecspresso Advent calendar, where I am putting together a guide on how to use ecspresso, a deployment tool for Amazon ECS.

Importing an Existing Service

To deploy an ECS service, you need task and service definitions in addition to a cluster. In ecspresso, task and service definitions are handled using JSON files in the same format used by the AWS CLI.

Since these are complex JSON structures that can be difficult for beginners to write by hand from scratch, ecspresso has a feature to generate configuration and definition files based on information from an already running ECS service.

ecspresso init

The command to generate configuration files from an existing service is init.

$ ecspresso init --help
usage: ecspresso init --region=REGION --service=SERVICE [<flags>]

create service/task definition files by existing ECS service

Flags:
  --help               Show context-sensitive help (also try --help-long and --help-man).
  --config=CONFIG      config file
  --debug              enable debug log
  --region=REGION      AWS region name
  --cluster="default"  cluster name
  --service=SERVICE    service name
  --task-definition-path="ecs-task-def.json"  
                       output task definition file path
  --service-definition-path="ecs-service-def.json"  
                       output service definition file path

Now, let's actually convert an ECS service into configuration files. Here, we will use an ECS service created with the Amazon ECS console first-run wizard by referring to Getting started with Amazon ECS using Fargate.

Credential Settings

ecspresso retrieves authentication information from standard environment variables to access AWS.

Minimum required value: AWS_REGION Region name to use (e.g., ap-northeast-1)

If configuration files for the AWS CLI (~/.aws/config, ~/.aws/credentials) exist, they will be used automatically. If a profile is defined in the configuration file, you can use the credentials for that profile by specifying AWS_SDK_LOAD_CONFIG=true and the profile name in AWS_PROFILE.

Running init

Run the init command by specifying --config, --region, --cluster, and --service according to the information of your existing ECS service.

$ ecspresso init --config config.yaml --region ap-northeast-1 --cluster ecspresso-demo --service nginx-service
2020/12/03 11:47:12 nginx-service/ecspresso-demo save service definition to ecs-service-def.json
2020/12/03 11:47:12 nginx-service/ecspresso-demo save task definition to ecs-task-def.json
2020/12/03 11:47:12 nginx-service/ecspresso-demo save config to config.yaml

When it finishes successfully, three files are generated. In ecspresso, these files are used to manage ECS services and tasks as code.
By managing the code in a repository, you can review configuration changes for ECS services and tasks and manage their history.

ecspresso configuration file config.yaml

This is in YAML format. It configures the region, cluster, service name, and the filenames for the service and task definition files.

region: ap-northeast-1
cluster: ecspresso-demo
service: nginx-service
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
timeout: 10m0s
plugins: []
appspec: null

ecs-service-def.json

This is a JSON format file that defines the configuration of the ECS service. It contains settings for networking (Subnet, SecurityGroup) and the load balancer.

{
  "deploymentConfiguration": {
    "deploymentCircuitBreaker": {
      "enable": false,
      "rollback": false
    },
    "maximumPercent": 200,
    "minimumHealthyPercent": 100
  },
  "desiredCount": 1,
  "enableECSManagedTags": false,
  "healthCheckGracePeriodSeconds": 0,
  "launchType": "FARGATE",
  "loadBalancers": [
    {
      "containerName": "nginx",
      "containerPort": 80,
      "targetGroupArn": "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/EC2Co-Defau-SA0YF35VBLCJ/b491afabf44765de"
    }
  ],
  "networkConfiguration": {
    "awsvpcConfiguration": {
      "assignPublicIp": "ENABLED",
      "securityGroups": [
        "sg-043eab2d606362f03"
      ],
      "subnets": [
        "subnet-0089ed3e1bdff1fc9",
        "subnet-0d750adbd139f411d"
      ]
    }
  },
  "placementConstraints": [],
  "placementStrategy": [],
  "platformVersion": "LATEST",
  "schedulingStrategy": "REPLICA",
  "serviceRegistries": []
}

ecs-task-def.json

This is a JSON format file for the ECS Task Definition. It describes information about the containers included in the task (images, execution commands, environment variables, etc.) as well as information such as CPU and Memory allocated to the task.

{
  "containerDefinitions": [
    {
      "command": [],
      "cpu": 256,
      "entryPoint": [],
      "environment": [],
      "essential": true,
      "image": "nginx:latest",
      "links": [],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/first-run-task-definition",
          "awslogs-region": "ap-northeast-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "memoryReservation": 512,
      "mountPoints": [],
      "name": "nginx",
      "portMappings": [
        {
          "containerPort": 80,
          "hostPort": 80,
          "protocol": "tcp"
        }
      ],
      "volumesFrom": []
    }
  ],
  "cpu": "256",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "family": "first-run-task-definition",
  "memory": "512",
  "networkMode": "awsvpc",
  "placementConstraints": [],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "volumes": []
}

That's it for the import!

By running ecspresso init, we have successfully imported the configuration of an existing ECS service into files.

On Day 4, I will explain how to modify these files and deploy the changes.

https://zenn.dev/fujiwara/articles/b5cb8bc64c83a6c8ca12