Cloud resources

Tag AWS ECS tasks to use them with your Release environments

In this guide, we'll look at how you can create and use cloud-native resources like AWS ECS tasks or Lambdas with your Release environments.

While Release can create complex environments that run services as Docker containers or static files, cloud-native resources required by your Release environments are hosted by your cloud provider outside your Release clusters.

To add cloud resources to a Release environment, you'll add two tags to your resources using your cloud provider's console or API or by using Terraform.

Once tagged, these resources will show up on the environment page, below your instances. Release adds helpful buttons to interact with your cloud resources directly from your environment page.

Supported cloud resources

Release currently supports AWS ECS tasks as the first available cloud resource. If you use other cloud resources that you'd like us to support, let us know.

How to add tags to AWS ECS tasks for Release environments

You can add AWS ECS tasks to your Release environments by adding two tags to your tasks in AWS.

Tag Key	Tag Value	Location in UI	Env variable
releasehub.com/app-name	(the app name)	Top of the environment page. In the screenshot below, the app name is terraform-runner-example.	RELEASE_APP_NAME (see default Release environment variables)
releasehub.com/env-id	(the environment handle)	In the screenshot below, the environment handle is terraform-example-cloud-resources.	RELEASE_ENV_ID (see default Release environment variables)

Find the app name and environment ID on the environment page

Follow the AWS documentation on tagging ECS resources to add these tags using the AWS console.

You can add tags to task definitions directly so that task containers inherit tags from the task definition or you can set the tags on running containers as shown below:

Editing AWS ECS tags using AWS console

Using Terraform to add tags to AWS ECS tasks

If you use Terraform with Release's infrastructure runners, Terraform can create your AWS ECS tasks and set the required tags and their values when your environment is deployed.

When Release executes Terraform, your Terraform plans can access Release-specific environment variables. Use the RELEASE_APP_NAME and RELEASE_ENV_ID environment variables in our Terraform to create your tags.

variable "RELEASE_APP_NAME" {
  type        = string
  description = "Name of the Release application"
}

variable "RELEASE_ENV_ID" {
  type        = string
  description = "Unique identifier for the Release environment"
}

resource "aws_ecs_task_definition" "service" {
  family = "service"
  container_definitions = jsonencode([ ... ])
  tags = {
    "releasehub.com/app-name" = var.RELEASE_APP_NAME
    "releasehub.com/env-id" = var.RELEASE_ENV_ID
    ...
  }
}

How to configure ECS logs for Release

To view your ECS logs using the Release log viewer, configure your ECS tasks to use the awslogs log driver. This log driver sends logs to AWS CloudWatch, which Release then reads and adds to your environment page.

See the AWS guide on using the awslogs log driver for ECS tasks. Your task execution IAM role needs the required permissions to create log groups and write to CloudWatch.

For logs to show up in Release, you need to set logDriver to awslogs, but you can set any values for awslogs-group or awslogs-stream-prefix.

The containerDefinitions section of your task definition should have a logConfiguration similar to the one below:

{
  "containerDefinitions": [
    {
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "firelens-container",
          "awslogs-region": "us-west-2",
          "awslogs-create-group": "true",
          "awslogs-stream-prefix": "firelens"
        }
      }
    }
  ]
}

Click the Logs button next to your AWS ECS task on the environment page in Release to see the logs generated by the task.

Logs button for an AWS ECS task in Release

When you click the Logs button, a new browser window will pop up showing the most recent logs.

Logs generated by an AWS ECS task in Release

How to configure the terminal access in Release for AWS ECS tasks

To open a terminal to an AWS ECS task, the following requirements must be met:

1. ECS Exec must be enabled for the task. See the AWS guide about turning on ECS Exec for your tasks and services.
2. The task's IAM role must have ECS Exec IAM permissions. See the AWS guide about IAM permissions required for ECS Exec.

If your task is configured with ECS Exec and the required IAM permissions, you can click on the Terminal button to open a terminal to your task.

Terminal button for an AWS ECS task in Release

After clicking the Terminal button, a new browser window will open, showing terminal output and a command line.

Terminal to an AWS ECS task in Release

If terminal access is not available for a task or if the task does not have ECS Exec enabled, the Terminal button will be grayed out in Release.

We recommend reading the AWS documentation on using Amazon ECS Exec for debugging to make sure you follow AWS recommended best practices.