Skip to main content

Deploy control for ECS

Project description

Paaws

Build

Paaws is a CLI that makes AWS services feel more like a PaaS such as Heroku or Dokku. It is designed to work with:

Paaws was created by Lincoln Loop to help developers manage and monitor services running on AWS without needing deep knowledge of the AWS itself. We are currently using it manage services in production.

Internally we have created a Terraform module to spin up services using Buildpacks and a Procfile, allowing developers to run new applications on AWS with very little configuration. We hope to release this as a Terraform and/or Cloudformation module in the future. In the meantime, however, the CLI is designed to work with existing systems via some configuration stored in AWS' Parameter Store.

If you're interested in commercial support for Paaws, please contact us.

🚧 This is an early release and under active development. APIs and commands may change between releases.

Installation

The CLI requires Python 3.6+. It can be installed via pip:

pip install paaws

Or you can download the most recent release from the Releases page and run it via python3 paaws ... or run chmod +x paaws and run it directly, ./paaws ....

Goals

  1. Developer friendly Developers should be able to use the PaaS without being AWS experts. When in doubt, see how Heroku does it.
  2. Cloud native Leverage AWS services wherever possible. Avoid running any additional services just to make the PaaS functional. No additional maintenance is required.
  3. Secure Follows general best practice and is compatible with locked down IAM policies.

Development

python -m venv .venv && . .venv/bin/activate
pip install flit
flit install --symlink --deps develop

In development, you can run the CLI with:

python -m paaws ...

Distribution

The app can be bundled into a Python zipapp with shiv:

make paaws.pyz

Terminology

AWS

Task (ECS)

One or more containers that are usually run as part of a Service, but may be run as a one-off process, e.g. shell access, release process, etc.

Service (ECS)

A task that should run forever like a daemon process. Can be scaled up to run multiple instances.

Log Group (Cloudwatch)

Log storage/aggregation

Container Instance (ECS/EC2)

A virtual server that runs the Docker daemon which executes the Tasks. Each Instance is part of a single Cluster (see below)

Fargate (ECS)

An AWS managed Task runner that does not require running Container Instances.

Cluster (ECS)

All Tasks run within a Cluster which serves as both a logical and security boundary.

Parameter Store (SSM)

A set of key/value strings stored with or without encryption. Usually used to inject environment variables into Tasks. Keys use a path-style notation and permissions can include a wildcard, so often keys are defined as /{application_name}/{key} and permissions are granted on /{application_name}/*.

Paaws

Application

An application consists of all the necessary AWS Resources to run. This is typically one or more Services, a Database, a Load Balancer, and multiple Parameters.

Configuration

The resources associated with an Application are determined via a "sane" set of defaults which can be overridden via configuration in the Parameter Store.

The default configuration is generated via the provided app name. If my-app were your app name, the configuration would be:

{
  "cluster": {"name": "my-app"},
  "log_group": {"name": "my-app"},
  "parameter_store": {
      "prefix": "/my-app",
      "chamber_compatible": false
  },
  "codebuild_project": {"name": "my-app"},
  "shell": {
      "task_amily": "my-app-shell",
      "command": "bash -l"
  },
  "db_utils": {
      "shell_task_family": "my-app-dbutils-shell",
      "dumpload_task_family": "my-app-dbutils-dumpload",
      "s3_bucket": "myapp-dbutils"
  },
  "tags": []
}

The tags value can be used to filter the set of Services and Tasks displayed from the Cluster. Keep in mind this is only a visual separation. IAM permissions are handled at the Cluster level, so no additional security is provided here.

Overrides

You can override the defaults by creating a parameter store key named /paaws/apps/{appname}/settings with a JSON string in it. An example using the AWS CLI:

$ aws ssm put-parameter \
  --name /paaws/apps/$APPNAME/settings \
  --value '{"cluster": {"name": "default"}, "log_group": {"name": "/aws/ecs/default/my-app"}}' \
  --type String \
  --overwrite

Available Commands

builds

View build information

  • list List most recent builds
  • view View status for a specific build
  • logs View build or test logs for a specific build

config

View/edit environment variables

  • list Environment variables for applications
  • get Get the value for a variable
  • set Get the value for a variable
  • unset Unset (delete) a variable

db

Perform database tasks

  • dump Dump database to local file
  • load Replace remote database with local dump
  • shell Run an interactive database shell

deployments

List deployments

logs

View application logs

  • view Show application logs
  • console Open logs in web console

ps

Show running containers

shell

Open an interactive shell in the remote environment

Thanks

Paaws is the result of a few years of learning while working with clients hosting applications on ECS. The Paaws CLI was born out of work we've been doing with Wharton Interactive and received their blessing to continue as an independent open source project. Thanks Sarah! 🎉

Project details


Release history Release notifications | RSS feed

This version

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

paaws-0.1.tar.gz (13.5 kB view details)

Uploaded Source

Built Distribution

paaws-0.1-py3-none-any.whl (16.8 kB view details)

Uploaded Python 3

File details

Details for the file paaws-0.1.tar.gz.

File metadata

  • Download URL: paaws-0.1.tar.gz
  • Upload date:
  • Size: 13.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.23.0

File hashes

Hashes for paaws-0.1.tar.gz
Algorithm Hash digest
SHA256 cec91e25d6191e87aea7f900e36d3e6b264219c04c9012aa81c81031d8be781c
MD5 3e3763f427709732374c136c42f5c42e
BLAKE2b-256 978987a40847511f445db450452ebc0fa197296a329072d22011776f60bbed70

See more details on using hashes here.

File details

Details for the file paaws-0.1-py3-none-any.whl.

File metadata

  • Download URL: paaws-0.1-py3-none-any.whl
  • Upload date:
  • Size: 16.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.23.0

File hashes

Hashes for paaws-0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2416429b7e944326c9148d9c1f9b79ba5a7022037f96de2e306a6f3da411c1e3
MD5 d2021c7905bf25bb6b57834d375e4aa0
BLAKE2b-256 8bdbacdaeb867890b1979dd19090ad1e3a646e1fde9207b2a0aedf4d2fd3f5b6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page