view release on metacpan or  search on metacpan

lib/App/FargateStack/Pod.pm  view on Meta::CPAN

   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:

=over 4

=item *  A certificate for your domain

=item * A Fargate cluster

=item * IAM roles and policies

=item * A listener and listener rules

=item * A CloudWatch log group

=item * Security groups

=item * A target group

=item * A task definition

=item * An ALB if one is not detected

=back

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.

=head2 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 C<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 C<app-Fargate help configuration> for more information about
resources and options.

=head2 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 I<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

=head1 CLI OPTION DEFAULTS

When enabled, C<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:

=over 4

=item * C<--profile>

=item * C<--region>

=item * C<--config>

=item * C<--route53-profile>

=item * C<--max-events>

=back

These values are stored in F<.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
F<.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:

lib/App/FargateStack/Pod.pm  view on Meta::CPAN

  tiny     => 256 CPU, 512 MB memory
  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 C<size> is provided, the framework will automatically populate the
corresponding C<cpu> and C<memory> values in the task definition. If you
manually specify C<cpu> or C<memory> alongside C<size>, those manual values
will take precedence and override the defaults from the profile.

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

If neither C<size>, C<cpu>, nor C<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.

=head1 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 C<environment:> key within the task
configuration.

=head2 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
C<secrets:> block for sensitive data.

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

=head2 SECURITY NOTE

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

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

=head2 INJECTING SECRETS FROM SECRETS MANAGER

To inject secrets into your ECS task from AWS Secrets Manager, define a C<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 C</my-stack/mysql-password>
and injects it into the container environment as C<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.

=head2 BEST PRACTICES

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

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

=head1 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).

I<Only one queue and one optional DLQ may be configured per stack.>

=head2 BASIC CONFIGURATION

At minimum, a queue requires a name:

  queue:
    name: fu-man-q

If you define C<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 C<dlq> key:

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

  dlq:
    name: custom-dlq-name

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

=head2 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

  dlq: