view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

...so as you can see, rolling all of this by hand could be a daunting
task and one made even more difficult when you decide to use other AWS
resources inside your task like buckets, queues or an EFS file
systems!

## Web Applications

Creating a web application using a minimal configuration works too. To
build a web application you can start with this minimal configuration:

    ---
    app:
      name: my-web-app
    domain: my-web-app.example.com
    tasks:
      apache:
        type: https
        image: my-web-app:latest

This will create an externally facing web application for you with
these resources:

- A certificate for your domain
- A Fargate cluster
- IAM roles and policies
- A listener and listener rules
- A CloudWatch log group
- Security groups
- A target group
- A task definition
- An ALB if one is not detected

Once again, launching a Fargate service requires a
lot of fiddling with AWS resources! Getting all of the plumbing
installed and working requires a lot of what and how knowledge.

## Adding or Changing Resources

Adding or updating resources for an existing application should also
be easy. Updating the infrastructure should just be a matter of
updating the configuration and re-running the framework's script. When
you update the configuration the `App::FargateStack` will detect the
changes and update the necessary resources.

Currently the framework supports adding a single SQS queue, a single
S3 bucket, volumes using EFS mount points, environment variables and
secrets from AWS Secrets Manager.

    my-worker:
      image: my-worker:latest
      command: /usr/local/bin/my-worker.pl
      type: task
      schedule: cron(00 15 * * * *)   
      bucket:
        name: my-worker-bucket
      queue:
        name: my-worker-queue
      environment:
        ENVIRONMENT=prod
      secrets:
        db_password:DB_PASSWORD
      efs:
        id: fs-abcde12355
        path: /
        mount_point: /mnt/my-worker

Adding new resources would normally require you to update your
policies to allow your worker to access these resource. However, the
framework automatically detects that the policy needs to be updated
when new resources are added (even secrets) and takes care of that for
you.

See `app-Fargate help configuration` for more information about
resources and options.

## Configuration as State

The framework attempts to be as transparent as possible regarding what
it is doing, how long it takes, what the result was and most
importantly _what defaults were used during resource
provisioning_. Every time the framework is run, the configuration file
is updated based on any new resources provisioned or configured.  For
example, if you did not specify subnets, they are inferred by
inspecting your VPC and automatically added to the configuration file.

This gives you a single view into your Fargate application

[Back to Table of Contents](#table-of-contents)

# CLI OPTION DEFAULTS

When enabled, `App::FargateStack` automatically remembers the most recently
used values for several CLI options between runs. This feature helps streamline
repetitive workflows by eliminating the need to re-specify common arguments
such as the AWS profile, region, or config file.

The following options are tracked and persisted:

- `--profile`
- `--region`
- `--config`
- `--route53-profile`
- `--max-events`

These values are stored in `.fargatestack/defaults.json` within your current
project directory. If you omit any of these options on subsequent runs, the
most recently used value will be reused.

Typically, you would create a dedicated project directory for your
stack and place your configuration file there. Once you invoke a
command that includes any of the tracked CLI options, the
`.fargatestack/defaults.json` file will be created
automatically. Future commands run from that directory can then omit
those options. A typical workflow to create a new stack with a
scheduled job might look like this:

    mkdir my-project
    cd my-project
    app-FargateStack create-stack foo task:my-cron image:my-project 'schedule:cron(0 10 * * * *)'
    app-FargateStack plan
    app-FargateStack apply

share/README.md  view on Meta::CPAN

    small    => 512 CPU, 1 GB memory
    medium   => 1024 CPU, 2 GB memory
    large    => 2048 CPU, 4 GB memory
    xlarge   => 4096 CPU, 8 GB memory
    2xlarge  => 8192 CPU, 16 GB memory

When a `size` is provided, the framework will automatically populate the
corresponding `cpu` and `memory` values in the task definition. If you
manually specify `cpu` or `memory` alongside `size`, those manual values
will take precedence and override the defaults from the profile.

**Important:** If you change the `size` after an initial deployment, you should
remove any manually defined `cpu` and `memory` keys in your configuration.
This ensures that the framework can correctly apply the new profile values
without conflict.

If neither `size`, `cpu`, nor `memory` are provided, the framework will infer
a sensible default size based on the task type. For example:

    - "http" or "https" => "medium"
    - "task"            => "small"
    - "task" + schedule => "medium"
    - "daemon"          => "medium"

This behavior helps minimize configuration boilerplate while still providing
sane defaults.

[Back to Table of Contents](#table-of-contents)

# ENVIRONMENT VARIABLES

The Fargate stack framework allows you to define environment variables for each
task. These variables are included in the ECS task definition and made available
to your container at runtime.

Environment variables are specified under the `environment:` key within the task
configuration.

## BASIC USAGE

    task:
      apache:
        environment:
          ENVIRONMENT: prod
          LOG_LEVEL: info
          DEBUG_MODE: 0

Each key/value pair will be passed to the container as an environment
variable.

Environment variable values are treated literally; shell-style
expressions such as ${VAR} are not interpolated. If you need dynamic
values, populate them explicitly in the configuration or use the
`secrets:` block for sensitive data.

This mechanism is ideal for non-sensitive configuration such as
runtime flags, environment names, or log levels.

## SECURITY NOTE

Avoid placing secrets (such as passwords, tokens, or private keys) directly in the
`environment:` section. That mechanism is intended for non-sensitive configuration
data.

To securely inject secrets into the task environment, use the `secrets:` section
of your task configuration. This integrates with AWS Secrets Manager and ensures
secrets are passed securely to your container.

## INJECTING SECRETS FROM SECRETS MANAGER

To inject secrets into your ECS task from AWS Secrets Manager, define a `secrets:`
block in the task configuration. Each entry in this list maps a Secrets Manager
secret path to an environment variable name using the following format:

    /secret/path:ENV_VAR_NAME

Example:

    task:
      apache:
        secrets:
          - /my-stack/mysql-password:DB_PASSWORD

This configuration retrieves the secret value from `/my-stack/mysql-password`
and injects it into the container environment as `DB_PASSWORD`.

Secrets are referenced via their ARN using ECS's native secrets mechanism,
which securely injects them without placing plaintext values in the task definition.

## BEST PRACTICES

Avoid placing secrets in the `environment:` block. That block is for non-sensitive
configuration values and exposes data in plaintext.

Use clear, descriptive environment variable names (e.g., `DB_PASSWORD`, `API_KEY`)
and organize your Secrets Manager paths consistently with your stack naming.

[Back to Table of Contents](#table-of-contents)

# SQS QUEUES

The Fargate stack framework supports configuring and provisioning a
single AWS SQS queue, including an optional dead letter queue (DLQs).

A queue is defined at the stack level and is accessible to all tasks
and services within the same stack. IAM permissions are automatically
scoped to include only the explicitly configured queue and its
associated DLQ (if any).

_Only one queue and one optional DLQ may be configured per stack._

## BASIC CONFIGURATION

At minimum, a queue requires a name:

    queue:
      name: fu-man-q

If you define `max_receive_count` in the queue configuration, a DLQ
will be created automatically. You can optionally override its name
and attributes using the top-level `dlq` key:

    queue:
      name: fu-man-q
      max_receive_count: 5

    dlq:
      name: custom-dlq-name

If you do not specify a `dlq.name`, the framework defaults to appending `-dlq` to
the main queue name (e.g., `fu-man-q-dlq`).

## DEFAULT QUEUE ATTRIBUTES

If not specified, the framework applies default values to match AWS's standard SQS behavior:

    queue:
      name: fu-man-q
      visibility_timeout: 30
      delay_seconds: 0
      receive_message_wait_time_seconds: 0
      message_retention_period: 345600
      maximum_message_size: 262144
      max_receive_count: 5  # triggers DLQ creation