resouer / amazon-ecs-for-open-application-model

CLI that deploys OAM workloads to Amazon ECS on AWS Fargate

Amazon ECS for Open Application Model

The oam-ecs CLI is a proof-of-concept that partially implements the Open Application Model (OAM) specification, version v1alpha1.

The oam-ecs CLI provisions two of the core OAM workload types as Amazon ECS services running on AWS Fargate using AWS CloudFormation. A workload of type core.oam.dev/v1alpha1.Worker will deploy a CloudFormation stack containing an ECS service running in private VPC subnets with no accessible endpoint. A workload of type core.oam.dev/v1alpha1.Server will deploy a CloudFormation stack containing an ECS service running in private VPC subnets, behind a publicly-accessible network load balancer.

For a full comparison with the OAM specification, see the Compatibility page.

⚠️ Note that this project is a proof-of-concept and should not be used with production workloads. Use the --dry-run option to review all CloudFormation templates generated by this tool before deploying them to your AWS account.

Build & test

make
make test
export PATH="$PATH:./bin/local"
oam-ecs --help

To customize the CloudFormation templates generated by this tool (for example, to change the VPC configuration or security group rules), edit the following files and re-compile:

• environment template
• workload template

Deploy an oam-ecs environment

The oam-ecs environment deployment creates a VPC with public and private subnets where OAM workloads can be deployed.

oam-ecs env deploy

The environment attributes like VPC ID and ECS cluster name can be described.

oam-ecs env show

The CloudFormation template deployed by this command can be seen here.

Deploy OAM workloads with oam-ecs

The dry-run step outputs the CloudFormation template that represents the given OAM workloads. The CloudFormation templates are written to the ./oam-ecs-dry-run-results directory.

oam-ecs app deploy --dry-run \
  -f examples/example-app.yaml \
  -f examples/worker-component.yaml \
  -f examples/server-component.yaml

Then the CloudFormation resources, including load balancers and ECS services running on Fargate, can be deployed:

oam-ecs app deploy \
  -f examples/example-app.yaml \
  -f examples/worker-component.yaml \
  -f examples/server-component.yaml

The application component instances' attributes like ECS service name and endpoint DNS name can be described.

oam-ecs app show -f examples/example-app.yaml

Tear down

To delete all infrastructure provisioned by oam-ecs, first delete the deployed applications:

oam-ecs app delete -f examples/example-app.yaml

Then delete the environment infrastructure:

oam-ecs env delete

Credentials and Region

oam-ecs will look for credentials in the following order, using the default provider chain in the AWS SDK for Go.

1. Environment variables.
2. Shared credentials file. Profiles can be specified using the AWS_PROFILE environment variable.
3. If running on Amazon ECS (with task role) or AWS CodeBuild, IAM role from the container credentials endpoint.
4. If running on an Amazon EC2 instance, IAM role for Amazon EC2.

No credentials are required for dry-runs of the oam-ecs tool.

oam-ecs will determine the region in the following order, using the default behavior in the AWS SDK for Go.

1. From the AWS_REGION environment variable.
2. From the config file in the .aws/ folder in your home directory.

Security Disclosures

If you would like to report a potential security issue in this project, please do not create a GitHub issue. Instead, please follow the instructions here or email AWS Security directly.

License

This project is licensed under the Apache-2.0 License.