view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        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

That's it...you just created a scheduled job that will run at 10 AM every day!

## Disabling and Resetting

Use the `--no-history` option to temporarily disable this feature for a single
run. This allows you to override stored values without modifying or deleting
them.

To clear all saved defaults entirely, use the `reset-history` command. This
removes all of the tracked values from the `.fargatestack/defaults.json` file,
but preserves the file itself.

## Notes

Only explicitly provided CLI options are tracked. Values derived from
environment variables or configuration files are not saved.

README.md  view on Meta::CPAN

The framework supports both individual rule sets and pre-configured
"bundles" for common application types. It also supports a subtractive
syntax (prefixing a keyword with a `-`) to remove rule sets from a
bundle.

#### Rule Set Keywords

- **base**: A strong baseline including `AWSManagedRulesCommonRuleSet`, `AWSManagedRulesAmazonIpReputationList`, and `AWSManagedRulesKnownBadInputsRuleSet`.
- **admin**: Protects exposed administrative pages (`AWSManagedRulesAdminProtectionRuleSet`).
- **sql**: Protects against SQL injection attacks (`AWSManagedRulesSQLiRuleSet`).
- **linux**: Includes rules for Linux and Unix-like environments.
- **php**: Includes rules for applications running on PHP.
- **wordpress**: Includes rules specific to WordPress sites.
- **windows**: Includes rules for Windows Server environments.
- **anonymous**: **Use with caution.** Blocks traffic from anonymous sources like VPNs and proxies, which may block legitimate users.
- **ddos**: Mitigates application-layer (Layer 7) DDoS attacks like HTTP floods.
- **premium**: **Warning: Extra Cost.** Enables advanced, paid protections for bot control and account takeover prevention.

#### Rule Bundles

- **default**: Includes `base` and `sql`. This is the recommended starting point for most applications.
- **linux-app**: Includes `default` and `linux`.
- **wordpress-app**: Includes `default`, `linux`, and `wordpress`.
- **windows-app**: Includes `default` and `windows`.
- **all**: Includes all standard, non-premium rule sets. **Warning:** This will likely exceed the default WCU quota and may incur additional costs.

### The Bootstrap Process (First Run)

On the first `apply` run with WAF enabled, the framework will perform
a one-time bootstrap:

1. It generates a default `web-acl.json` file in your project
directory. This file contains the complete definition of your Web ACL,
including the rules generated from your `managed_rules` keywords.
2. It calls `aws wafv2 create-web-acl` to create a new Web ACL.
3. It calls `aws wafv2 associate-web-acl` to link the new Web ACL to
your Application Load Balancer.
4. It updates your configuration file with the state of the new
WAF resources, including its Name, ID, ARN, LockToken, and a checksum
of the `web-acl.json` file.
5. The `waf` block in your `fargate-stack.yml` is updated to reflect
the bootstrapped state. If the `managed_rules` key was not present,
it will be added with the default value of `[default]`.

### Ongoing Management (Subsequent Runs)

After the initial creation, you take full control of the rules. To
add, remove, or modify rules, you simply edit the `web-acl.json` file
directly.

On subsequent runs of `apply`, `App::FargateStack` will:

- Calculate a checksum of your `web-acl.json` file.
- If the checksum has changed, it will safely update the remote Web ACL
with your new rule set.
- If the checksum has not changed, it will skip the update to avoid
unnecessary API calls.

This model gives you the best of both worlds: the "minimal
configuration, maximum results" of a secure default, and the full
"transparent box" control to customize your security posture as your
application's needs evolve.

### Conflict and Drift Management

The framework includes robust safety checks to prevent accidental data
loss. If it detects that the Web ACL has been modified in the AWS
Console _and_ you have also modified your local `web-acl.json` file,
it will detect the state conflict, refuse to make any changes, and
provide a clear error message with instructions on how to resolve it.

### Estimated Cost

The default WAF configuration is designed to provide a strong security
baseline while remaining cost-effective. When you enable WAF without
specifying any `managed_rules`, the framework applies the `default`
bundle, which includes the `base` and `sql` rule sets.

The approximate monthly cost for this default configuration is
**~$9.00 per month**, plus per-request charges.

The cost is broken down as follows:

- **$5.00 / month** for the Web ACL itself.
- **$4.00 / month** for the four AWS Managed Rule Groups included
in the `default` bundle (3 in 'base', 1 in 'sql').
- **$0.60 / per 1 million requests** processed by the Web ACL.

**Warning:** Enabling the `premium` rule set will incur significant
additional monthly and per-request fees for services like Bot Control
and Account Takeover Prevention. Always review the [AWS WAF
pricing](https://aws.amazon.com/waf/pricing/) page before enabling
premium features.

## Roadmap for HTTP Services

- path based routing on ALB listeners

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

# AUTOSCALING

## Overview

For services that experience variable load, such as HTTP applications or
background job processors, `App::FargateStack` can automate the process of
scaling the number of running tasks up or down to meet demand. This ensures
high availability during traffic spikes and saves costs during quiet periods.

The framework integrates with AWS Application Auto Scaling to provide target
tracking scaling policies. This allows you to define a target metric - such as
average CPU utilization or the number of requests per minute - and the framework
will automatically manage the number of Fargate tasks to keep that metric at
your desired level.

## Enabling Autoscaling

To enable autoscaling for a service, add an `autoscaling` block to its task
configuration in your .yml configuration file.

tasks: