See it in action
Lightsail: deploy a public registry image
Complete author three-step public-image recipe. An already-created billable service must reach READY; set the actual region/name, review image trust and current price first, then verify ACTIVE and the actual URL. Not a deployed result.
Example input
1. Create the service and wait for `READY` (SKILL.md Workflow, step 1) — poll with:
```bash
aws lightsail get-container-services --service-name NAME --region REGION
```
2. Deploy with `create-container-service-deployment`. The `image` is the public reference (e.g.
`public.ecr.aws/nginx/nginx:latest` or `docker.io/library/nginx:latest`), and `publicEndpoint.containerPort` must
be the port the app listens on **and** appear in that container's `ports`.
```bash
aws lightsail create-container-service-deployment \
--service-name NAME \
--containers '{"web":{"image":"public.ecr.aws/nginx/nginx:latest","ports":{"80":"HTTP"}}}' \
--public-endpoint '{"containerName":"web","containerPort":80,"healthCheck":{"path":"/"}}' \
--region REGION
```
3. Poll the deployment to `ACTIVE` and verify the URL — see [deployment.md](references/deployment.md).License
Complete selected author section retained verbatim; surrounding chapter omitted. Source placeholders and limitations preserved. No cloud action, source installer, account sign-in, model, command or API execution. This is an author recipe/illustration, not a reproduced site result.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
Lightsail: web, cache and worker deployment shape
Complete original multi-container section and JSON shape. Image placeholders remain; CACHE_ADDR is non-secret. A new deployment replaces the full spec. Price/credentials, actual images, readiness and cleanup remain user-environment work.
Example input
Each entry in `containers` is independent, with its own image and ports. Only the one named by `publicEndpoint` is on
the public URL. To open communication between containers in the same deployment, add an environment variable that
references `localhost` (like `CACHE_ADDR` below); one that opens no ports, like `worker`, can still call out but
nothing on the public URL can reach it. From a different Lightsail resource in the same region, reach a service at
`<service>.service.local:<port>`.
```json
{
"containers": {
"web": {"image": "<web-image>", "ports": {"80": "HTTP"},
"environment": {"CACHE_ADDR": "localhost:6379"}},
"cache": {"image": "<cache-image>", "ports": {"6379": "TCP"}},
"worker": {"image": "<worker-image>"}
},
"publicEndpoint": {
"containerName": "web",
"containerPort": 80,
"healthCheck": {"path": "/"}
}
}
```
`CACHE_ADDR` is a non-secret address; anything sensitive placed here is readable via
`get-container-service-deployments` — see SKILL.md Security considerations.License
Complete selected author section retained verbatim; surrounding chapter omitted. Source placeholders and limitations preserved. No cloud action, source installer, account sign-in, model, command or API execution. This is an author recipe/illustration, not a reproduced site result.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill deploying-containers-to-amazon-lightsailBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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 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.exeand add it toPATH.
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
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 — a public registry image (no build, no push).
- 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 — clone and build from a GitHub repo, then follow the
local-image path.
- references/deployment.md — the deployment shape (
containers+publicEndpoint+ health
check), how to poll to ACTIVE, roll back, and tear down.
- references/troubleshooting.md —
lightsailctlnot found, aFAILEDdeployment,
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-powersis the single source. It returns each power's monthly price per
node, so quote that figure directly.
- Transfer quota — the
dataTransferQuotaattribute onLightsail Containersrecords, from the AWS Price List
operation get-products with service code AmazonLightsail.
- Egress rate — a separate
get-productsrecord, found with aTERM_MATCHfilter onoverageType=
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
- Create the service with a chosen power and scale; poll
get-container-servicesuntil itsstateisREADY.
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.
- Get the image in — the one source-specific step; follow the matching reference above.
- Deploy a version (its
containersplus onepublicEndpointwith a health check), then poll the deployment to
ACTIVE — see the deployment reference.
- 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 trips the execution timeouts (a single call still running after ~30 seconds can be cut off and drop the session). Return the URL only once the deployment is ACTIVE.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Confirm the monthly price before creating (unless told to proceed) | Create billable resources silently |
| Discover powers, regions, prices, and image versions from the API | Hardcode power, scale, region, prices, or an image version |
| Read the image-source reference before the image step | Guess the build/push sequence |
Poll with repeated short calls + a sleep between; return the URL only once ACTIVE | Wait inside one long-running call (a run_script loop or a long shell loop); return the URL early |
| For a public image, skip the build and push entirely | Require a local build when a registry image already exists |
Read get-container-log to diagnose a failure | Rebuild or redeploy blindly on a 502 or a FAILED deployment |
| Recommend ECS/EKS or ECS Express Mode for microservices/autoscaling | Present Lightsail as the answer to every container question |
| Always give the teardown command | Leave the user unable to stop charges |
Operations
Operation (aws lightsail …) | Purpose | Note |
|---|---|---|
get-container-service-powers | list the available powers with their specs and prices | read these instead of quoting remembered sizes or prices |
create-container-service | create the service | flat price = power × scale |
update-container-service | change capacity (power/scale) on a running service | re-deploys the current deployment automatically, with no downtime and keeps the same deployment version |
get-container-services | check state | READY before deploying; RUNNING after a deployment is active |
push-container-image | push a local image | needs the lightsailctl plugin and a running local Docker |
create-container-service-registry-login | get temporary registry credentials | first step of the plugin-free push |
register-container-image | register an already-pushed image by digest | the plugin-free alternative to push-container-image |
get-container-images | list the image versions in the service's registry | Lightsail assigns the version numbers - read them here rather than assuming them |
create-container-service-deployment | deploy an image | containers{} + publicEndpoint{containerName, containerPort, healthCheck} |
get-container-service-deployments | deployment state and history | ACTIVATING → ACTIVE; roll back by redeploying a prior version |
get-container-log | read container logs | first stop for diagnosing a failed deployment; don't log secrets or customer data |
delete-container-service | tear down | stops charges |
Security considerations
- Least-privilege IAM — scope the calling principal to the
lightsail:actions this workflow
actually uses (the Operations table above is the list) rather than lightsail:* or an administrator policy.
- Secrets —
environmentvalues are stored in the deployment spec and readable through
get-container-service-deployments, and there is no separate secret-injection mechanism, so a credential the container needs has to go there; pass only what it needs. When a value is credential-shaped — a password, token, API key, or connection string — you MUST warn the user before deploying and leave the choice to them; one option is an application that decrypts the value itself, so the deployment spec holds ciphertext and the key ships in the image instead. NEVER print or log those values, or the get-container-service-deployments response that carries them, back to the user or into any artifact.
- Public surface — the endpoint is HTTPS-only with an AWS-managed certificate, Shield Standard
covers common network-layer DDoS automatically, and only the container named in publicEndpoint is internet-reachable. There is no request throttling or WAF for a container service, and Lightsail does not inject security headers, so input validation, rate limiting, and CSP / HSTS / X-Content-Type-Options / X-Frame-Options are all the application's responsibility.
- Private network reach — a container has unfiltered network access to your other Lightsail resources in
the same account and Region, and no Lightsail firewall rule narrows it. Where VPC peering is active for the Region, the same access extends to your own VPC. The image is therefore the only control, so you MUST warn the user before deploying an image they did not build.
- Auditing — CloudTrail records all Lightsail API calls; Event history is on by default, and a trail
gives continuous delivery to S3.
Troubleshooting
If anything goes wrong — a deployment fails, or the URL won't serve — read references/troubleshooting.md; start by reading the container log to the root cause.
