deploying-containers-to-amazon-lightsail

Files (6)

• SKILL.md
• deployment.md · references/
• github-source.md · references/
• local-image.md · references/
• public-image.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# Deploying containers to Amazon Lightsail

## Overview

Amazon Lightsail Container Service runs a container image behind a managed, HTTPS URL for a flat monthly price. The
URL, TLS certificate, and load balancing are included — there is no cluster, VPC, load balancer, or registry to set
up.

This skill takes a container image from any source to a live, serving Lightsail deployment, and diagnoses one that
won't serve. Creating the service requires two choices: **`power`**, the memory and vCPUs of each node, and **`scale`**,
how many nodes run, each running a full copy of the deployment. Capacity never changes on its own — there is no
autoscaling and no scale-to-zero — so you raise `power` or `scale` yourself when a service needs more.

## Prerequisites

Before creating anything:

- **Clarify** the image source, the port the app listens on, and the region.
- **Discover options at runtime** — the available powers and regions — instead of hardcoding them.
- **Confirm the plan and price.** State the flat monthly price (power × scale, charged even with no traffic) and confirm
  before creating billable resources — unless the user has already told you to proceed. Never create them silently. See
  the Pricing section below for where to read the figures.
- **Fixed caps aren't adjustable.** The nodes-per-service cap is the ceiling on `scale`; containers per deployment and
  deployment versions are capped too. Read the values in
  [Lightsail quotas](https://docs.aws.amazon.com/general/latest/gr/lightsail.html) rather than offering an increase.
  An account's actual quota may be lower than the published default if the account was recently created or is used
  minimally.
- **Permissions.** The calling identity needs the Lightsail actions in the Operations table below; a missing one
  surfaces as an access-denied error on the first call, not as a tooling or quota problem. See the Security
  considerations section below for scoping them.

Tools: the **AWS CLI** (v2) is all a public-registry-image deploy needs — and its operations run either through
the AWS MCP tools (preferred, see below) or the CLI directly. A local build or push also needs `docker` (running)
and — for the `push-container-image` shortcut — the `lightsailctl` plugin (the plugin-free push uses `docker` +
`register-container-image` instead).

Running AWS operations: prefer the AWS MCP execution tool **`aws___run_script`** when it is available, and keep each
call **short** — one operation that returns right away, not a long-running one (a call still running after ~30
seconds is cut off and drops the session). It isn't required: the same operations run through the local **`aws` CLI**,
which is the fallback when no MCP tool is available. Note the build and push of a **local** image are
Docker/`lightsailctl` operations that run on your machine, never through the MCP tools.

Installing `lightsailctl`: needed only for the `push-container-image` shortcut, and it needs AWS CLI v2 plus a
running Docker:

- **macOS:** `brew install aws/tap/lightsailctl`
- **Linux:** `curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o /usr/local/bin/lightsailctl && chmod +x /usr/local/bin/lightsailctl`
- **Windows:** download `https://s3.us-west-2.amazonaws.com/lightsailctl/latest/windows-amd64/lightsailctl.exe` and add it to `PATH`.

If an install is blocked or the plugin still isn't found, see the troubleshooting reference — or skip the plugin
entirely with the plugin-free push in [references/local-image.md](references/local-image.md).

## References

The step-by-step detail lives in reference files bundled with this skill. **You MUST read the reference matching your
image source, or the step you're about to do, before doing it** — each carries the exact sequence and requirements
(ports, image architecture, push method) that are easy to get wrong.

To open one: on the AWS MCP server, retrieve it with the skill's content-retrieval tool; otherwise read it from this
skill's own directory (its location was shown to you when the skill loaded), e.g. `<skill-dir>/references/NAME.md`.
**DON'T read from a bare `references/NAME.md`** — it resolves against your working directory, not the skill, and
fails with "No files found"; if you hit that, prepend the skill directory and retry.

- [references/public-image.md](references/public-image.md) — a public registry image (no build, no push).
- [references/local-image.md](references/local-image.md) — build a local image and push it into the service's
  registry (`docker`; `push-container-image` or the plugin-free sequence).
- [references/github-source.md](references/github-source.md) — clone and build from a GitHub repo, then follow the
  local-image path.
- [references/deployment.md](references/deployment.md) — the deployment shape (`containers` + `publicEndpoint` + health
  check), how to poll to `ACTIVE`, roll back, and tear down.
- [references/troubleshooting.md](references/troubleshooting.md) — `lightsailctl` not found, a `FAILED` deployment,
  502/503, and `exec format error` (a CPU-architecture mismatch).

## Service, deployment, containers

- **Container service** — the long-lived resource you create first. It owns the capacity (`power` × `scale`), the
  public HTTPS URL, the private domain, and its own image registry. Billing runs from creation to deletion.
- **Deployment** — an immutable, versioned spec of what to run on that service. One is active at a time, and creating
  another replaces the spec entirely.
- **Containers** — entries inside a deployment (the per-deployment cap is in the Lightsail quotas linked above).
  Each has a name, an image, and ports; exactly one can be
  the public endpoint and the rest are reachable only by their siblings, over `localhost`.

## Pricing

Price is set by capacity under a transfer quota. The monthly cost is the power's price × the scale, charged from
creation until deletion whether or not any requests arrive. Each service includes one monthly data-transfer quota —
the quota does not change regardless of the power and scale that you choose for your service — and egress above it is
charged per GB at a rate that varies by Region. Inbound counts toward the quota but isn't charged when exceeded.

State a price only if you have just read it from one of the sources below — never from memory, and never a placeholder
such as `$0.00` for a rate you did not look up. Capacity cost is exact (power price × scale). Egress cost is not,
because it depends on traffic you cannot know, so give the per-GB rate rather than a total.

- **Power prices** — `get-container-service-powers` is the single source. It returns each power's monthly price per
  node, so quote that figure directly.
- **Transfer quota** — the `dataTransferQuota` attribute on `Lightsail Containers` records, from the AWS Price List
  operation `get-products` with service code `AmazonLightsail`.
- **Egress rate** — a separate `get-products` record, found with a `TERM_MATCH` filter on `overageType` =
  `ContainerSvc:Data Transfer`. Use `overageType`, not `productFamily`: `Lightsail Networking` also holds CDN, bucket,
  instance, and DNS overages. Narrow by `fromRegionCode`, not `regionCode`, since these records name the location they
  transfer out of.

## Workflow

1. **Create the service** with a chosen power and scale; poll `get-container-services` until its `state` is `READY`.
   `get-container-service-powers` returns each power's `name` (`nano`) and its `powerId` (`nano-1`) — when you create
   the service, pass the **`name`** to `--power`.
2. **Get the image in** — the one source-specific step; follow the matching reference above.
3. **Deploy** a version (its `containers` plus one `publicEndpoint` with a health check), then poll the deployment to
   `ACTIVE` — see the deployment reference.
4. **Verify and report** — only once the deployment is `ACTIVE`, read the generated URL from the service (it has a
   random id — read it, don't construct it), confirm it responds, and report the URL, the monthly price, and the
   teardown command.

**Polling:** create and deploy return immediately and finish asynchronously — expect ~5–10 min end to end, and a
still-`PENDING`/`ACTIVATING` state is normal. Poll by **repeating a short status check with a brief pause between
calls** — each check is its own quick call that returns right away, with a short `sleep` in between. Don't do the
waiting inside one long-running call (a loop inside a single `run_script`, or a long `shell` loop) — that's what

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws