App-FargateStack
view release on metacpan or search on metacpan
the EFS, but will validate its existence in the current AWS account
and region.
- mount\_point:
The container path to which the EFS volume will be mounted.
- path:
The path on the EFS filesystem to map to your container's mount point.
- readonly:
Optional. Set to `true` to mount the EFS as read-only. Defaults to
`false`.
## Additional Notes
- The ECS role's policy for your task is automatically modified
to allow read/write EFS access. Set `readonly:` in your task's
`efs:` section to "true" if only want read support.
- Your EFS security group must allow access from private subnets
where the Fargate tasks are placed.
- No changes are made to the EFS security group; the framework
assumes access is already configured
- Only one EFS volume is currently supported per task configuration.
- EFS volumes are task-scoped and reused only where explicitly configured.
- The framework does not automatically provision an EFS
filesystem for you. The framework does however validate that the
filesystem exists in the current account and region.
[Back to Table of Contents](#table-of-contents)
# CONFIGURATION
The `App::FargateStack` framework defines your application stack
using a YAML configuration file. This file describes your
application's services, their resource needs, and how they should be
deployed. Then configuration is updated whenever your run `plan` or
`apply`.
## GETTING STARTED
The fastest way to get up and running with `App::FargateStack` is to
use the `create-stack` command to generate a configuration file,
inspect the deployment plan, and then apply it.
### Step 1: Create a Configuration Stub
First, generate a minimal YAML configuration file. The `create-stack`
command provides a shorthand syntax to do this. You only need to
provide an overall application name, a service type, a service name,
and the container image to use.
This command will create a file named `my-stack.yml` in your current
directory. Make sure you have your AWS profile configured in your
environment or pass it using the `--profile` option.
app-FargateStack create-stack my-stack daemon:my-stack-daemon image:my-stack-daemon:latest
This will produce a configuration stub that looks like this:
app:
name: my-stack
tasks:
my-stack-daemon:
image: my-stack-daemon:latest
type: daemon
This file contains the three key pieces of information you provided:
the application name, the task name, and the image to use.
### Step 2: Plan the Deployment (Dry Run)
Next, run the `plan` command. This is a crucial step that acts as a
dry run. The framework will:
- Read your minimal configuration file.
- Intelligently discover resources in your AWS account (like your VPC and subnets).
- Determine what new resources need to be created (like IAM roles, a security group, an ECS cluster and a CloudWatch log group).
- Report a full plan of action without making any actual changes.
- Update your configuration file with the discovered values and
sensible defaults.
app-FargateStack plan
After this command completes, your `my-stack.yml` file will be fully
populated with all the information needed to provision your stack.
### Step 3: Apply the Plan
Once you have reviewed the plan and are satisfied with the proposed
changes, run the `apply` command. This will execute the plan and
create all the necessary AWS resources.
app-FargateStack apply
### Step 4: Deploy and Start the Service
The `apply` command creates all the necessary **infrastructure**, but
it does not start your service. This separation allows you to manage
your infrastructure and your application's runtime state
independently.
To create the ECS service and start your container, use the
`deploy-service` command.
app-FargateStack deploy-service my-stack-daemon
By default, this will start one instance of your task. To check its
status, use the `status` command:
app-FargateStack status my-stack-daemon
And to stop the service, simply run:
app-FargateStack stop-service my-stack-daemon
To restart a stopped service, run:
app-FargateStack start-service my-stack-daemon
| --> ALB DNS Name |
+----------+----------------+
|
+----------v----------+
| Application Load |
| Balancer (ALB) |
| [internal or |
| internet-facing] |
| |
| Listeners: |
| - Port 80 |
| - Port 443 w/ TLS |
| + ACM Cert |
| (TLS/SSL) |
| [if external] |
+----------+----------+
|
+------v-------+
| Target Group |
+------+-------+
|
+-------v---------+
| ECS Service |
| (Fargate Task) |
+-------+---------+
|
+---------v----------+
| VPC Private Subnet |
+--------------------+
This default architecture provides a repeatable, production-ready
deployment pattern for HTTP services with minimal configuration.
## Behavior by Task Type
For HTTP services, you set the task type to either "http" or "https"
(these are the only options that will trigger a task to be configured
for HTTP services). The table below summarizes the configurations by
task type.
+-------+----------+-------------+-----------+---------------+
| Type | ALB type | Certificate | Port | Hosted Zone |
+-------+----------+-------------+-----------+---------------+
| http | internal | No | 80 | private |
| https | external | Yes | 443 | public |
| | | | 80 => 443 | |
+-------+----------+-------------+-----------+---------------+
_NOTE: You must provide a domain name for both an internal and
external facing HTTP service. This also implies you must have a
both a **private** and **public** hosted zone for your domain._
Your task type will also determine which type of subnet is required
and where to search for an existing ALB to use. If you want to prevent
re-use of an existing ALB and force the creation of a new one use the
`--create-alb` option when you run your first plan.
In your initial configuration you do not need to specify the subnets
or the hosted zone id. The framework will discover those and report
if any required resources are unavailable. If the task type is
"https", the script looks for a public zone, public subnets and an
internet-facing ALB otherwise it looks for a private zone, private
subnets and an internal ALB.
## ACM Certificate Management
If the task type is "https" and no ACM certificate currently exists
for your domain, the framework will automatically provision one. The
certificate will be created in the same region as the ALB and issued
via AWS Certificate Manager. If the certificate is validated via DNS
and subsequently attached to the listener on port 443.
## Port and Listener Rules
For external-facing apps, a separate listener on port 80 is
created. It forwards traffic to port 443 using a default redirect rule
(301). If you do not want a redirect rule, set the `redirect_80:` in
the `alb:` section to "false".
If you want your internal application to listen on a port other than
80, set the `port:` key in the `alb:` section to a new port
value.
## Example Minimal Configuration
app:
name: http-test
domain: http-test.example.com
task:
apache:
type: http
image: http-test:latest
Based on this minimal configuration `app-FargateStack` will enrich
the configuration with appropriate defaults and proceed to provision
your HTTP service.
To do that, the framework attempts to discover the resources required
for your service. If your environment is not compatible with creating
the service, the framework will report the missing resources and
abort the process.
Given this minimal configuration for an internal ("http") or
external ("https") HTTP service, discovery entails:
- ...determining your VPC's ID
- ...identifying the private subnet IDs
- ...determining if there is and existing load balancer with the
correct scheme
- ...finding your load balancer's security group (if an ALB exists)
- ...looking for a listener rule on port 80 (and 443 if type is
"https"), including a default forwarding redirect rule
- ...validating that you have a private or public hosted zone
in Route 53 that supports your domain
- ...setting other defaults for additional resources to be built (log
groups, cluster, target group, etc)
- ...determining if an ACM certificate exists for your domain
(if type is "https")
_Note: Discovery of these resources is only done when they are
missing from your configuration. If you have multiple VPCs for example
you can should explicitly set `vpc_id:` in the configuration to
identify the target VPC. Likewise you can explicitly set other
resource configurations (subnets, ALBs, Route 53, etc)._
Resources are provisioned and your configuration file is updated
incrementally as `app-FargateStack` compares your environment to the
environment required for your stack. When either plan or
apply complete your configuration is updated giving you complete
insight into what resources were found and what resources will be
provisioned. See [CONFIGURATION](https://metacpan.org/pod/CONFIGURATION) for complete details on resource
configurations.>
Your environment will be validated against the criteria described
below.
- You have at least 2 private subnets available for deployment
Technically you can launch a task with only 1 subnet but for services
behind an ALB Fargate requires 2 subnets.
_When you create a service with a load balancer, you must specify
two or more subnets in different Availability Zones. - AWS Docs_
- You have a hosted zone for your domain of the appropriate type
(private for type "http", public for type "https")
As discovery progresses, existing and required resources are logged
and your configuration file is updated. If you are **NOT** running in
dryrun mode, resources will be created immediately as they are
discovered to be missing from your environment.
## Application Load Balancer
When you provision an HTTP service, whether or not it is secure, the
service will placed behind an application load balancer. Your Fargate
service is created in private subnets, so your VPC must contain at
least two private subnets. Your load balancer can either be
_internally_ or _externally facing_.
By default, the framework looks for and will reuse a load balancer
with the correct scheme (internal or internet-facing), in a subnet
aligned with your task type. The ALB will be placed in public subnets
if it is internet-facing. You can override that behavior by either
explicitly setting the ALB arn in the `alb:` section of the
configuration or pass `--create-alb` when you run our plan and apply.
If no ALB is found or you passed the `--create-alb` option, a new ALB
is provisioned. When creating a new ALB, `app-FargateStack` will also
create the necessary listeners and listener rules for the ports you
have configured.
### Why Does the Framework Force the Use of a Load Balancer?
While it is possible to avoid the use or the creation of a load balancer
for your service, the framework forces you to use one for at least two
reasons. Firstly, the IP address of your service may not be stable and
is not friendly for development or production purposes. The framework
is, after all trying its best to promote best practices while
preventing you from having to know how all the sausage is made.
Secondly, it is almost guaranteed that you will eventually want
a domain name for your production service - whether it is an
internally facing microservice or an externally facing web
application.
Creating an alias in Route 53 for your domain pointing to the ALB
ensures you don't need to update application configurations with the
service's dynamic IP address. Additionally, using a load balancer
allows you to create custom routing rules to your service. If you want
to run multiple tasks for your service to support handling more
traffice a load balancer is required.
With those things in mind the framework automatically uses an ALB for
HTTP services and creates an alias record (A) for your domain for both
internal and external facing services.
## AWS WAF Support
For external-facing HTTPS services, `App::FargateStack` can automate
the creation and association of an AWS Web Application Firewall (WAF)
to provide an essential layer of security. This protects your
application from common web exploits and bots that could affect
availability or compromise security.
The framework follows a "Hybrid Management Model" for WAF, designed to
provide a secure, sensible baseline out-of-the-box while giving you
full control over fine-grained rule customization.
### Enabling WAF Protection
To enable WAF, simply add a `waf` block with `enabled: true` to your
`alb` configuration:
alb:
# ... existing alb configuration ...
waf:
enabled: true
### Configuring Managed Rules
( run in 0.787 second using v1.01-cache-2.11-cpan-39bf76dae61 )