view release on metacpan or  search on metacpan

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

__END__

=pod

=head1 NAME

app-FargateStack-env.pl - Preflight checker for ECS Fargate environments

=head1 USAGE

  app-FargateStack-env.pl [options]

=head1 DESCRIPTION

Runs read-only checks against the target AWS account and region to verify
that common ECS Fargate deployment scenarios are feasible. Produces an
ASCII table with PASS/WARN/FAIL rows and a capabilities summary for:

  - HTTP services
  - HTTPS service
  - Scheduled tasks
  - One-shot tasks
  - Daemon services

No resources are created or modified. Intended as a fast “can I deploy here?”
probe for humans and CI.

=head2 Options

=over 4

=item B<--profile> I<STR>

AWS config/credentials profile to use. Defaults to C<$ENV{AWS_PROFILE}> or the
SDK’s default behavior if unset.

=item B<--region> I<STR>

AWS region to target (e.g. C<us-east-1>). Defaults to C<$ENV{AWS_REGION}> if set.

=item B<--dns> | B<--no-dns>

Enable or disable Route 53 checks. Default: B<enabled>.
Use B<--no-dns> (or B<--nodns>) to skip DNS checks.

=item B<--dns-profile> I<STR>

Alternate AWS profile for Route 53 lookups. Useful when DNS is managed in a
separate account. Falls back to C<--profile> if not provided.

=item B<--https> | B<--no-https>

Enable or disable ACM certificate checks (same region as the load balancer).
Default: B<disabled>. Turn on if you plan to deploy HTTPS.

=item B<--secrets> | B<--no-secrets>

Enable or disable Secrets Manager reachability checks. Default: B<disabled>.
When enabled, the checker verifies control-plane reachability (e.g., VPC
endpoint present or NAT available). It does not validate individual
C<GetSecretValue> permissions for task roles.

=back

=head1 OUTPUT

The main table includes rows like:

  Credentials
  Service-linked roles
  VPC/Subnets
  Egress
  ECS perms
  ELBv2 perms
  CloudWatch Logs perms
  ECR
  Events perms
  iam:PassRole
  Route 53
  ACM
  Secrets Manager

Each row has a Status of B<PASS>, B<WARN>, or B<FAIL> and a Detail string.
Typical examples:

  - Egress: PASS with NAT present; missing VPC endpoints are called out as optional.
  - Events perms: PASS when EventBridge APIs are readable (e.g., list-event-buses).
  - iam:PassRole: PASS when simulation allows passing target roles to
    C<ecs-tasks.amazonaws.com> and C<events.amazonaws.com>.

=head2 CAPABILITIES SUMMARY

After the table, a summary lists readiness for common Fargate scenarios:

  YES   = all required checks PASS
  MAYBE = at least one required check WARN (no FAILs)
  NO    = at least one required check FAIL or a required check is missing

The gates for each capability are:

  HTTP services    : Credentials, VPC/Subnets, Egress, ECS perms,
                     ELBv2 perms, CloudWatch Logs perms, iam:PassRole
  HTTPS service    : HTTP services + ACM
  Scheduled tasks  : Credentials, VPC/Subnets, Egress, ECS perms,
                     Events perms, CloudWatch Logs perms, iam:PassRole
  One-shot tasks   : Credentials, VPC/Subnets, Egress, ECS perms,
                     CloudWatch Logs perms, iam:PassRole
  Daemon services  : Credentials, VPC/Subnets, Egress, ECS perms,
                     CloudWatch Logs perms, iam:PassRole

=head2 EXIT STATUS

  0  All checks PASS
  1  One or more checks WARN (no FAILs)
  2  One or more checks FAIL

These exit codes are designed for CI gating.

=head2 NOTES