​
Prerequisites

To get the most out of this guide, you will need to:

​
Overview

This connection uses a wrapper script available in the hoophq/hoopdev image called ecs-exec.sh. This script requires the following permissions to work:

  • ecs:ListTasks
  • ecs:DescribeTasks
  • ecs:ExecuteCommand

It’s important to configure the ECS tasks before trying this feature. Please refer to the AWS documentation first

​
Connection Configuration

NameTypeDescription
CLUSTER_NAMEenv-varThe name or arn of the ECS Cluster
SERVICE_NAMEenv-varThe name of the service on ECS
CONTAINERenv-varThe name of the container defaults to the first one.
AWS_ACCESS_KEY_IDenv-varThe access key credential
AWS_SECRET_ACCESS_KEYenv-varThe secret key credential
AWS_DEFAULT_REGIONenv-varThe AWS region

​
Connection Configuration (Assume Role)

NameTypeValueDescription
CLUSTER_NAMEenv-var-The name or arn of the ECS Cluster
SERVICE_NAMEenv-var-The name of the service on ECS
CONTAINERenv-var-The name of the container defaults to the first one.
ECS_AGENT_URIenv-varsystem.agent.envsThe access key credential
AWS_EXECUTION_ENVenv-varsystem.agent.envsECS launch type
AWS_CONTAINER_CREDENTIALS_RELATIVE_URIenv-varsystem.agent.envsfull HTTP URL endpoint when making a request for credentials
ECS_CONTAINER_METADATA_URI_V4env-varsystem.agent.envsThis path returns metadata for the container.
AWS_DEFAULT_REGIONenv-varsystem.agent.envsThe default AWS region

The value system.agent.envs will expose the upstream environment variable from the agent to the connection, allowing the wrapper script to use the IAM task role.

​
AWS ECS - Interactive Sessions

The AWS Elastic Container Service allows users to connect to tasks and start interactive sessions. These commands can be mapped to Hoop to obtain interactive sessions by allocating a pseudo TTY.

Before attempting to use this feature, it’s essential to configure the ECS tasks. Please refer to the AWS documentation for guidance.

​
Connection Command

ecs-exec.sh --interactive --cluster=$CLUSTER_NAME --service-name=$SERVICE_NAME

​
How to Use

Start an interactive session.

hoop connect my-ecs -- --interactive --pipe /bin/bash
hoop connect my-ecs -- --interactive --pipe 'rails console'
hoop connect my-ecs -- --interactive --pipe clojure

​
AWS ECS - Execute one-off commands

​
Connection Command

ecs-exec.sh --cluster=$CLUSTER_NAME --service-name=$SERVICE_NAME

​
How to Use

Now it’s possible to execute the Ruby script straight from Hoop.dev

hoop exec ecs-exec -- --pipe 'rails runner -' <<EOF
myvar='Hello from Rails'
puts myvar
EOF
hoop exec ecs-exec -i 'puts Rails.env' -- --pipe 'rails runner -'

The --pipe option necessitates the availability of the base64 command in the image. This command decodes the input content, preventing leakage of shell content such as single or double quotes. This helps address a limitation of the aws ecs execute-command.

It’s possible to pipe any command.

hoop exec ecs-exec -i '(println "Clojure REPL")' -- --pipe 'clojure'
hoop exec ecs-exec -- --pipe 'python3' <<EOF
import os
print(os.environ.get("CLUSTER_NAME"))
EOF
# defaults to /bin/bash
hoop exec ecs-exec --input 'echo "hello world from bash"'

Easily call the scripts.

hoop exec ecs-exec -i '/path/to/my/script.sh'
# override the ecs task-id
hoop exec ecs-exec -i '/path/to/my/script.sh' -- --task mytaskid
# execute a rails script
hoop exec ecs-exec -i 'rails runner /path/to/script.rb'