Deploy Waypoint to AWS Elastic Container Service

AWS Elastic Container Service is one of the easiest platforms to get started on. With Waypoint's AWS ECS plugin, you'll only need an Elastic Container Registry to use Waypoint to quickly deploy an application.

»Prerequisites

You'll need to clone the examples repository, set up your AWS credentials, and create an Elastic Container Registry.

You'll be most comfortable if you have already used Waypoint to do a local deployment with our Get Started collection.

OPTIONAL: Provision a Kubernetes cluster and install the Waypoint server to Kubernetes in order to unlock all Waypoint functionality (including logs, exec, and ui).

»Clone the examples repository

The code for this tutorial is in the hashicorp/waypoint-examples repository. Clone the repository with git.

$ git clone https://github.com/hashicorp/waypoint-examples.git

Change into the subdirectory for the AWS ECS project. This project uses NodeJS but the following instructions will work with any language that can be built with a cloud native buildpack.

$ cd waypoint-examples/aws-ecs/nodejs

»Create an Elastic Container Registry

To create an ECR repository, visit the ECR home page.

This example will deploy a project named waypoint-example in us-east-1 region. If you choose a different name or region, edit the Waypoint configuration to match.

After you create the registry, it will appear in the list of your container registries.

»Install the Waypoint server

The Waypoint server must be installed. You may install it locally which requires fewer steps but limits the functionality of some Waypoint commands. Or, install to a remote Kubernetes cluster for full functionality (including the logs, exec, and ui commands).

$ docker pull hashicorp/waypoint:latest

$ waypoint install --platform=docker -accept-tos

»Explore waypoint.hcl

Open the waypoint.hcl file. In this section, you will explore the build and deploy steps for this project.

The waypoint.hcl file uses the aws-ecr registry plugin during the build stage. The aws-ecr plugin uses your AWS credentials and internally builds the correct URL to the AWS API.

It is also possible to configure this manually with the docker plugin. Other configuration options are listed in the plugin documentation.

Other configuration options are listed in the plugin documentation.

build {
  use "pack" {}
  registry {
    use "aws-ecr" {
      region     = "us-east-1"
      repository = "waypoint-example"
      tag        = "latest"
    }
  }
}

Use the aws-ecr plugin for the deploy stage. You can specify the region, memory, and cpu as well as a count of how many instances to launch or a log_group to store the logs in a CloudWatch log group.

See the plugin documentation for other configuration options.

deploy {
  use "aws-ecs" {
    region = "us-east-1"
    memory = "512"
  }
}

The full waypoint.hcl looks like this.

project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env" = "dev"
  }

  build {
    use "pack" {}
    registry {
      use "aws-ecr" {
        region = "us-east-1"
        repository = "waypoint-example"
        tag = "latest"
      }
    }
  }

  deploy {
    use "aws-ecs" {
      region = "us-east-1"
      memory = "512"
    }
  }
}

»Initialize Waypoint

Initialize the project with the init command.

$ waypoint init

✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "example-nodejs" and all apps are registered with the server.
✓ Plugins loaded and configured successfully
✓ Authentication requirements appear satisfied.

Project initialized!

You may now call 'waypoint up' to deploy your project or
commands such as 'waypoint build' to perform steps individually.

Read the troubleshooting page if you run into any errors.

»Build, deploy, and release the application

Deploy the application with up.

$ waypoint up

» Building...
» Deploying...
✓ Created new ECS cluster: waypoint
✓ Found existing IAM role to use: ecr-example-nodejs
✓ Created CloudWatchLogs group to store logs in: waypoint-logs
✓ Created ALB target group
✓ Created new ALB Listener
✓ Configured security group: example-nodejs-inbound-internal
✓ Created ECS Service (example-nodejs-24MX1ZSG9QC8Y4TJH, cluster-name: waypoint)

» Releasing...

The deploy was successful! A Waypoint deployment URL is shown below. This
can be used internally to check your deployment and is not meant for external
traffic. You can manage this hostname using "waypoint hostname."

   Release URL: http://waypoint-ecs-example-nodejs-1945800883.us-east-1.elb.amazonaws.com
Deployment URL: https://personally-endless-lobster--v1.waypoint.run

Visit the Release URL or the Deployment URL to view the application running on ECS.

You can visit the ECS console to view the server side of the cluster.

The cluster also lists individual tasks.

»Destroy the instance

To deprovision the container, run destroy.

$ waypoint destroy

» Destroying releases...
» Destroying deployments...
Destroy successful!

If there is an error, try again after a few seconds.

»Next steps

Learn more about Waypoint by following along with the other tutorials for Azure, Google Cloud, and others, or read the documentation for other Waypoint plugins.