> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-update-to-meta-tags.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS ECS

> Interact with Elastic Container Service, executing one-off sessions into ECS tasks/containers.

## Prerequisites

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

* Either [create an account in our managed instance](https://use.hoop.dev) or [deploy your own hoop.dev instance](/getting-started/installation/overview)
* You must be your account administrator to perform the following commands

## 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`

<Info>
  It’s important to configure the ECS tasks before trying this feature. Please refer to the [AWS documentation first](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html)
</Info>

## Connection Configuration

| Name                     | Type    | Description                                          |
| ------------------------ | ------- | ---------------------------------------------------- |
| CLUSTER\_NAME            | env-var | The name or arn of the ECS Cluster                   |
| SERVICE\_NAME            | env-var | The name of the service on ECS                       |
| CONTAINER                | env-var | The name of the container defaults to the first one. |
| AWS\_ACCESS\_KEY\_ID     | env-var | The access key credential                            |
| AWS\_SECRET\_ACCESS\_KEY | env-var | The secret key credential                            |
| AWS\_DEFAULT\_REGION     | env-var | The AWS region                                       |

## Connection Configuration (Assume Role)

| Name                                       | Type    | Value             | Description                                                  |
| ------------------------------------------ | ------- | ----------------- | ------------------------------------------------------------ |
| CLUSTER\_NAME                              | env-var | -                 | The name or arn of the ECS Cluster                           |
| SERVICE\_NAME                              | env-var | -                 | The name of the service on ECS                               |
| CONTAINER                                  | env-var | -                 | The name of the container defaults to the first one.         |
| ECS\_AGENT\_URI                            | env-var | system.agent.envs | The access key credential                                    |
| AWS\_EXECUTION\_ENV                        | env-var | system.agent.envs | ECS launch type                                              |
| AWS\_CONTAINER\_CREDENTIALS\_RELATIVE\_URI | env-var | system.agent.envs | full HTTP URL endpoint when making a request for credentials |
| ECS\_CONTAINER\_METADATA\_URI\_V4          | env-var | system.agent.envs | This path returns metadata for the container.                |
| AWS\_DEFAULT\_REGION                       | env-var | system.agent.envs | The 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.

<Info>
  Before attempting to use this feature, it's essential to configure the ECS tasks. Please refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html) for guidance.
</Info>

### Connection Command

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

### How to Use

Start an interactive session.

```bash
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

```bash
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

```bash
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 -'
```

<Info>
  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`.
</Info>

It’s possible to pipe any command.

```bash
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.

```bash
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'
```