putpaws 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5383c31d8b2b94dcb948e565f9ab5784137a0b946aa53e2ade93fc5e1bf3152
-  data.tar.gz: 30babace1c15c9675752567795e4c43414be155cc0f9affccfdb8bd8907a215d
+  metadata.gz: cbb1de2cdc7c119427ca5dfa073f5e8d07f504ff73f93a464f2912a8ef5168ed
+  data.tar.gz: 042f6202ae3cb0396b0ab7210b2d299504f7e099e8a0cf43d9c6314f0b6384ba
 SHA512:
-  metadata.gz: f506cafed6700e2fc5bff6334e7e3374e528652740de99c03a36e89a031603b891b77133b5264fff51f8d1d3bc7db22f8549c88a32658f87883249c8cfe9d331
-  data.tar.gz: 941ceaa13526fd71c3a37d5d6541490950472dea6bff75aff2b495acc10adb41f46b270e14a6c279d542863792594896443aeca882655321b856a745c38306e0
+  metadata.gz: 12b7e736fe78e9a49569627fd296e9f5540cbea849f8b78a7edbb56c8652de73b82d1b2ac92fef279a682f64e4e83e061ba20e2c3afe1b3c99dce7fd35526fe1
+  data.tar.gz: efad6347afdc46833694e48070afd0330fe42f8bb0bc16638b6b88a7d5b6d1a091ce50f5ce1ddec4f92cc07e54796f42cc9802c2b5aa07ed4af1d96ba5ebd171

data/README.md

@@ -0,0 +1,230 @@
+# Put your pAWS up!!
+
+## Command names
+
+The short commands follow a "put your paws ..." image:
+
+- `putpaws ready` ... put paws ready: — place your paws and prepare
+- `putpaws steady` ... put paws steady: — hold steady, right before the start
+- `putpaws up` ... put paws up: — everything is ready, raise them up
+- `putpaws ahead` ... put paws ahead: — reach ahead and probe (dry-run)
+- `putpaws away` ... put paws away: — take your paws off and let AI take over
+
+## Provisioning
+
+Build service infra (security group / ECS cluster / task definitions / service / log groups / CodeBuild) idempotently.
+Deletion is out of scope on purpose: putpaws only creates and updates.
+
+```
+# Interview basic infra (existing VPC / ECR / SES / S3 / SSM parameter prefix)
+# and generate provision.json + IAM role drafts
+bundle exec putpaws ready
+
+# After reviewing/editing the drafts under policies/, create the IAM roles
+# from them as-is and fill their ARNs into provision.json. Idempotent:
+# edit a draft and run again to update the role.
+bundle exec putpaws steady
+
+# Dry-run: show what would be created / updated / skipped
+bundle exec putpaws ahead
+
+# Build the rest as far as possible. `up` stops with instructions where a manual
+# step is required. Fix things by hand, then just run `up` again. Safe to re-run any time.
+bundle exec putpaws up
+```
+
+Running `steady` is your explicit confirmation of the drafts: `up` never touches IAM
+and stops until the role ARNs are filled. Filling in an existing role ARN in
+provision.json instead makes `steady` leave that role alone
+(useful when IAM is managed by another team).
+
+Files live under `.putpaws/provisioning/`:
+
+- `provisioning/{service_name}/provision.json` ... inputs (edit by hand; `steady` fills the role ARNs)
+- `provisioning/{service_name}/state.json` ... created resource info (written by putpaws)
+- `provisioning/{service_name}/policies/` ... IAM role drafts to review, applied as-is by `putpaws steady`
+- `provisioning/presets/{preset}/` ... defaults and task definition templates (copied here on `ready`, edit freely)
+
+Presets are searched in this order: project local (`.putpaws/provisioning/presets/`),
+user global (directories in `PUTPAWS_PRESETS_PATH`, then `~/.putpaws/presets/`), and the ones bundled in the gem.
+Whichever you pick on `ready` is copied into the project so the project owns its snapshot.
+
+Security groups are either specified (one or more existing ones; putpaws never touches their rules)
+or a new one is created for the service when left empty on `ready`.
+
+When the service step completes, the new service is reflected into
+`.putpaws/application.json` and `.putpaws/infra.json` (diff is shown and confirmed),
+so `ecs:attach`, `ecs:shell`, `ecs:run` and `log:*` work immediately.
+Secrets are handled by reference only: task definitions point to existing
+SSM parameters (Ex: `/{service_name}/RAILS_MASTER_KEY`) and putpaws never touches the values.
+
+A scheduler role is always created too, and the `target` entry of infra.json carries it,
+so `scheduler:deploy` works any time by just writing `.putpaws/schedule.json`.
+
+CodeBuild is created as CI: builds run inside the VPC with the same subnets and
+security group as the service, so `db:migrate` against RDS works from the build.
+Note that the private subnets need a NAT gateway (or VPC endpoints) so that
+builds can reach GitHub / ECR / CloudWatch Logs.
+
+## Operator permissions
+
+Declare named operator profiles in `.putpaws/operators.json` (generated with examples on first run),
+then resolve them into managed policies per service, idempotently
+(CREATE / UPDATE as a new policy version / SKIP — re-running never piles up policies):
+
+```
+bundle exec putpaws awesome-api-staging iam:grant profile=developer
+```
+
+```
+{
+  "developer": { "groups": ["attach", "shell", "deploy", "logs", "codebuild"] },
+  "viewer": { "groups": ["logs"] }
+}
+```
+
+Groups map to putpaws command namespaces: `attach` (ecs:attach/forward), `shell` (ecs:shell/run —
+note this implies reading all secrets of the service), `deploy` (ecs:deploy), `logs` (log:*),
+`codebuild` (code_build:build), `scheduler` (scheduler:deploy).
+`extra_statements` on a profile appends raw IAM statements.
+The policy is named `{service}-operator-{profile}`. Attaching it to users/groups is left to your admin
+(an attach command example is printed).
+
+## AI setup
+
+`putpaws away` installs a guide for AI agents (Claude Code etc.) into the project:
+`.claude/skills/putpaws/SKILL.md` (commands, read-only vs mutating classification,
+non-interactive recipes, suggested permission allowlist) and a pointer block in
+`CLAUDE.md` (or `AGENTS.md` when there is no CLAUDE.md). Re-run it after updating putpaws.
+
+```
+bundle exec putpaws away
+```
+
+## Example
+
+### Info
+
+Show resolved settings for a service without touching AWS
+
+```
+bundle exec putpaws awesome-api-staging info
+```
+
+### ECS
+
+Attach to staging specific container
+
+```
+bundle exec putpaws awesome-api-staging ecs:attach container=app
+```
+
+Run port forwarding session through specific container
+
+```
+bundle exec putpaws awesome-api-staging ecs:forward container=app remote=example-rds-host:3306 local=:1050
+# local=:1050 is optional by the way, then random number is selected.
+# Please check standard output in your shell for the auto-generated local port.
+
+# You can access specified remote host with subsequent command in another shell like:
+mysql -u awesome_user -p --port 1050 -h 127.0.0.1
+```
+
+Redeploy the service (update-service with force new deployment).
+With a mutable image tag like `latest`, this rolls out the newly pushed image.
+
+```
+bundle exec putpaws awesome-api-staging ecs:deploy
+
+# Optionally change desired count / task definition, and wait until stable
+bundle exec putpaws awesome-api-staging ecs:deploy desired=2 taskdef=awesome-api-staging-web wait=true
+```
+
+Run a command on a temporary task. The task terminates itself when the command finishes.
+
+```
+bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate'
+
+# Pass wait=true to wait until the task stops and check the exit code
+bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate' wait=true
+```
+
+Launch a temporary task for operation and attach to it (like SSH-ing into the environment).
+The task is launched with its command overridden by `sleep <ttl>`, so it always terminates itself when ttl passes even if your shell is gone.
+
+```
+# ttl is 30 minutes by default
+bundle exec putpaws awesome-api-staging ecs:shell
+
+# Specify ttl: "45" and "45m" mean 45 minutes, "90s" and "2h" also work
+bundle exec putpaws awesome-api-staging ecs:shell ttl=45m
+
+# The task is stopped immediately when you exit the shell.
+# Pass keep=true to keep it running until ttl passes.
+bundle exec putpaws awesome-api-staging ecs:shell keep=true
+```
+
+Temporary tasks are launched with `group` / `started_by` set to `putpaws-run` or `putpaws-shell`,
+so you can identify them on the AWS console and on the task list of `ecs:attach` / `ecs:forward`.
+
+`ecs:run` and `ecs:shell` require `network` and `target` in `.putpaws/application.json`,
+which refer to the `network` / `target` sections of `.putpaws/infra.json` (the same ones used by scheduler).
+
+### CloudWatch Logs
+
+`tail -f`
+
+```
+bundle exec putpaws awesome-api-staging log:tailf
+```
+
+Find logs between specific date range using time symbol
+
+- `s`: second
+- `m`: minute
+- `h`: hour
+- `d`: day
+- `w`: week
+
+```
+# Find logs since 2 hours ago
+bundle exec putpaws awesome-api-staging log:tailf since=2h
+
+# Find logs since 1 day ago for 3 hours
+bundle exec putpaws awesome-api-staging log:tail since=1d for=3h
+```
+
+## Set up
+
+```
+gem 'putpaws'
+```
+
+## Setting Example
+
+`.putpaws/application.json`
+
+```
+{
+  "awesome-api-staging": {
+    "region": "ap-northeast-1",
+    "cluster": "cluster-staging",
+    "service": null,
+    "task_name_prefix": "awesome-api",
+    "log_group_prefix": "/ecs/awesome/awesome-api-staging",
+    "log_region": null,
+    "build_log_group_prefix": "/aws/codebuild/awesome-api-staging",
+    "build_project_name_prefix": "awesome-api-staging",
+    "network": "awesome-private-staging",
+    "target": "awesome-staging"
+  },
+  "awesome-api-production": {
+    "region": "ap-northeast-1",
+    "cluster": "cluster-production",
+    "service": null,
+    "task_name_prefix": "awesome-api",
+    "log_group_prefix": "/ecs/awesome/awesome-api-production",
+    "log_region": null
+  }
+}
+```

data/lib/Putpawsfile

@@ -4,4 +4,9 @@ require "putpaws/setup"
 require "putpaws/hello"
 require "putpaws/ecs/ecs_task"
 require "putpaws/cloud_watch/log_task"
-require "putpaws/scheduler/scheduler_task"
+require "putpaws/scheduler/scheduler_task"
+require "putpaws/code_build/build_task"
+require "putpaws/provision/provision_task"
+require "putpaws/iam/iam_task"
+require "putpaws/info"
+require "putpaws/ai/ai_task"

data/lib/putpaws/ai/ai_task.rb

@@ -0,0 +1 @@
+load File.expand_path("../tasks/ai_task.rake", __FILE__)

data/lib/putpaws/ai/guide.rb

@@ -0,0 +1,119 @@
+require 'fileutils'
+require 'putpaws/version'
+
+module Putpaws
+  module Ai
+    # `putpaws away`: put paws away — take your paws off and let AI take over.
+    # Installs a guide for AI agents (Claude Code etc.) into the host project:
+    # a skill file plus a pointer block in CLAUDE.md / AGENTS.md.
+    # Re-runnable: everything is regenerated in place.
+    class Guide
+      SKILL_PATH = File.join('.claude', 'skills', 'putpaws', 'SKILL.md')
+      BEGIN_MARK = '<!-- putpaws:begin -->'
+      END_MARK = '<!-- putpaws:end -->'
+
+      def self.install!(root: '.', services: nil)
+        services ||= Putpaws::ApplicationConfig.all.map(&:name)
+        skill_path = File.join(root, SKILL_PATH)
+        FileUtils.mkdir_p(File.dirname(skill_path))
+        File.write(skill_path, skill_content(services: services))
+        pointer_path = pointer_target(root)
+        update_pointer!(pointer_path)
+        [skill_path, pointer_path]
+      end
+
+      # Prefer an existing CLAUDE.md; otherwise use AGENTS.md (created if absent).
+      def self.pointer_target(root)
+        claude = File.join(root, 'CLAUDE.md')
+        return claude if File.exist?(claude)
+        File.join(root, 'AGENTS.md')
+      end
+
+      def self.update_pointer!(path)
+        block = pointer_block
+        content = File.exist?(path) ? File.read(path) : ''
+        if content.include?(BEGIN_MARK)
+          content = content.sub(/#{Regexp.escape(BEGIN_MARK)}.*#{Regexp.escape(END_MARK)}/m, block.strip)
+        else
+          content = content.empty? ? block : content.rstrip + "\n\n" + block
+        end
+        File.write(path, content)
+      end
+
+      def self.pointer_block
+        <<~MD
+          #{BEGIN_MARK}
+          ## putpaws (AWS operations)
+
+          This project uses the putpaws gem for AWS/ECS operations (logs, deploy, migrations, one-off tasks).
+          Read `.claude/skills/putpaws/SKILL.md` for commands and safety notes before running AWS operations.
+          Quick reference: services are the top-level keys of `.putpaws/application.json`;
+          `bundle exec putpaws <service> info` shows resolved settings without touching AWS.
+          #{END_MARK}
+        MD
+      end
+
+      def self.skill_content(services: [])
+        services_line = services.empty? ? '(none configured yet — check .putpaws/application.json)' : services.join(', ')
+        <<~MD
+          ---
+          name: putpaws
+          description: AWS operations for this project (CloudWatch logs, ECS deploy, db:migrate and one-off tasks on Fargate, CodeBuild CI) via the putpaws CLI. Use when asked to investigate logs, deploy, run rake tasks on AWS, or inspect ECS services.
+          ---
+
+          # putpaws
+
+          Capistrano-style AWS operation commands. General form:
+
+              bundle exec putpaws <service> <command> key=value
+
+          Services in this project: #{services_line}
+          (services are the top-level keys of `.putpaws/application.json`)
+
+          Discover commands with `bundle exec putpaws -T` (or `-D` for full descriptions).
+
+          ## Read-only commands (safe to run without asking)
+
+          - `bundle exec putpaws <service> info` — resolved settings, no AWS access
+          - `bundle exec putpaws <service> log:tail since=2h` — CloudWatch logs (units: s/m/h/d/w, add `for=1h` to bound the range)
+          - `bundle exec putpaws <service> log:tailf` — follow logs (long-running; prefer `log:tail` in automation)
+          - `bundle exec putpaws ahead` — dry-run of provisioning (CREATE/UPDATE/SKIP)
+
+          ## Mutating commands (confirm with the user before running)
+
+          - `bundle exec putpaws <service> ecs:run cmd='bundle exec rake db:migrate' wait=true`
+            — runs a one-off command on a temporary Fargate task and exits non-zero on failure.
+            The best choice for migrations and rake tasks. Fully non-interactive.
+          - `bundle exec putpaws <service> ecs:deploy wait=true` — redeploy the service (force new deployment)
+          - `bundle exec putpaws <service> code_build:build branch=main` — start the CI build (build + push + deploy per buildspec)
+          - `bundle exec putpaws <service> scheduler:deploy` — deploy schedules from `.putpaws/schedule.json`
+
+          ## Interactive commands (avoid in non-TTY sessions; meant for humans)
+
+          - `ecs:attach`, `ecs:shell`, `ecs:forward` — open live sessions into containers
+          - `ready`, `steady`, `up`, `iam:grant` — provisioning flows with confirmation prompts
+
+          ## Config files (source of truth, safe to read)
+
+          - `.putpaws/application.json` — services and their cluster/log/build settings
+          - `.putpaws/infra.json` — network (subnets/security groups) and target (cluster/taskdef) definitions
+          - `.putpaws/schedule.json` — named schedules, `.putpaws/operators.json` — operator permission profiles
+          - `.putpaws/provisioning/<service>/` — provisioning inputs (provision.json), state, IAM role drafts
+
+          ## Suggested permission allowlist (.claude/settings.json)
+
+              "permissions": {
+                "allow": [
+                  "Bash(bundle exec putpaws -T*)",
+                  "Bash(bundle exec putpaws * info)",
+                  "Bash(bundle exec putpaws * log:*)"
+                ]
+              }
+
+          ---
+          Generated by putpaws #{Putpaws::VERSION}. Refresh with `bundle exec putpaws away` after updating the gem.
+        MD
+      end
+    end
+  end
+end

data/lib/putpaws/ai/tasks/ai_task.rake

@@ -0,0 +1,14 @@
+require "putpaws/ai/guide"
+
+namespace :ai do
+  desc "Install the AI agent guide (.claude/skills/putpaws/SKILL.md + a pointer in CLAUDE.md/AGENTS.md). Re-runnable. (alias: away)"
+  task :install do
+    files = Putpaws::Ai::Guide.install!
+    puts "Generated:"
+    files.each{|f| puts "  #{f}"}
+    puts "Re-run `bundle exec putpaws away` after updating putpaws to refresh the guide."
+  end
+end
+
+desc "Alias of ai:install"
+task away: 'ai:install'

data/lib/putpaws/application_config.rb

@@ -1,13 +1,16 @@
 require 'json'
 require 'pathname'
 require "putpaws/schedule_config"
+require "putpaws/infra_network_config"
+require "putpaws/infra_target_config"
 
 class Putpaws::ApplicationConfig < Struct.new(
-  :name, :region, 
+  :name, :region,
   :cluster, :service, :task_name_prefix, :ecs_region,
   :log_group_prefix, :log_region,
-  :build_project, :build_log_group_prefix, :build_region,
+  :build_project_name_prefix, :build_log_group_prefix, :build_region,
   :schedules,
+  :network, :target,
   keyword_init: true)
   def self.load(path_prefix: '.putpaws')
     @application_data ||= begin
@@ -37,7 +40,7 @@ class Putpaws::ApplicationConfig < Struct.new(
     {
       region: ecs_region || region,
       cluster: cluster,
-      # service: service,
+      service: service,
       task_name_prefix: task_name_prefix,
     }
   end
@@ -59,4 +62,21 @@ class Putpaws::ApplicationConfig < Struct.new(
   def schedules
     @schedules ||= (self[:schedules] || []).map{|x| Putpaws::ScheduleConfig.find(x)}.compact
   end
+
+  def network
+    return nil unless self[:network]
+    @network ||= Putpaws::InfraNetworkConfig.find(self[:network])
+  end
+
+  def target
+    return nil unless self[:target]
+    @target ||= Putpaws::InfraTargetConfig.find(self[:target])
+  end
+
+  def codebuild_command_params
+    {
+      region: build_region || region,
+      project_name_prefix: build_project_name_prefix,
+    }
+  end
 end

data/lib/putpaws/code_build/build_task.rb

@@ -0,0 +1 @@
+load File.expand_path("../tasks/build_task.rake", __FILE__)

data/lib/putpaws/code_build/project_command.rb

@@ -0,0 +1,57 @@
+require 'aws-sdk-codebuild'
+# require 'aws-sdk-ssm'
+
+module Putpaws::CodeBuild
+  class ProjectCommand
+    def self.config(config)
+      new(**config.codebuild_command_params)
+    end
+
+    attr_reader :codebuild_client
+    attr_reader :region, :project_name_prefix
+    attr_accessor :codebuild_project
+    def initialize(region:, project_name_prefix: nil)
+      @codebuild_client = Aws::CodeBuild::Client.new({region: region})
+      @region = region
+      @project_name_prefix = project_name_prefix
+      @codebuild_project = nil
+    end
+
+    def list_codebuild_projects
+      res = codebuild_client.batch_get_projects(names: [project_name_prefix])
+      res.projects.select{|pr| pr.name.start_with?(project_name_prefix)}
+    end
+
+    def start_build_with_specific_version(source_version:, environment_variables: {}, buildspec_override: nil, artifacts_override: nil)
+      current_variables = codebuild_project.environment.environment_variables.map{|x| [x.name, {type: x.type, value: x.value}]}.to_h
+      new_variables = environment_variables.reduce(current_variables) {|acc,(k,v)| acc[k] = {type: 'PLANTTEXT', value: v}}
+      environment_variables_override = new_variables.map{|k,v| v.merge(name: k)}
+      params = {
+        project_name: codebuild_project.name,
+        source_version: source_version,
+        environment_variables_override: environment_variables_override,
+      }
+      if buildspec_override
+        params = params.merge(buildspec_override: buildspec_override)
+      end
+      if artifacts_override
+        params = params.merge(artifacts_override: artifacts_override)
+      end
+
+      codebuild_client.start_build(**params)
+    end
+
+    def build_source_version(type:, version:)
+      type = type.to_sym
+      if type == :branch
+        "refs/heads/#{version}"
+      elsif type == :tag
+        "refs/tags/#{version}"
+      elsif type == :commit_id
+        version
+      else
+        raise "Please specify valid type: branch or tag or commit_id"
+      end
+    end
+  end
+end

data/lib/putpaws/code_build/tasks/build_task.rake

@@ -0,0 +1,39 @@
+require "putpaws/prompt"
+require "putpaws/code_build/project_command"
+
+namespace :code_build do
+  desc "Set CodeBuild project."
+  task :set_project do
+    aws = Putpaws::CodeBuild::ProjectCommand.config(fetch(:app))
+    codebuild_projects = aws.list_codebuild_projects.map{|x| 
+      [x.name, x]
+    }.to_h
+    prompt = Putpaws::Prompt.safe
+    selected = prompt.select("Choose a project you're going to operate", codebuild_projects.keys)
+    codebuild_project = codebuild_projects[selected]
+
+    set :codebuild_project, codebuild_project
+  end
+
+  desc "Start build."
+  task build: :set_project do
+    aws = Putpaws::CodeBuild::ProjectCommand.config(fetch(:app))
+
+    source_version = if ENV['branch']
+      aws.build_source_version(type: :branch, version: ENV['branch'])
+    elsif ENV['tag']
+      aws.build_source_version(type: :tag, version: ENV['tag'])
+    elsif ENV['commit_id']
+      aws.build_source_version(type: :commit_id, version: ENV['commit_id'])
+    else
+      raise "Please specify required parameter like: branch=main or tag=release/20240601 or commit_id=0f0f0f0f"
+    end
+    codebuild_project = fetch(:codebuild_project)
+    aws.codebuild_project = codebuild_project
+    aws.start_build_with_specific_version(
+      source_version: source_version, 
+      environment_variables: ENV['env'] ? JSON.parse(ENV['env']) : {}, 
+      buildspec_override: ENV['buildspec']
+    )
+  end
+end

data/lib/putpaws/ecs/run_command.rb

@@ -0,0 +1,115 @@
+require 'aws-sdk-ecs'
+
+module Putpaws::Ecs
+  class RunCommand
+    DEFAULT_TTL = '30m'
+    SECONDS = {
+      's' => 1,
+      'm' => 60,
+      'h' => 60 * 60,
+    }
+
+    def self.config(config)
+      unless config.network && config.target
+        raise "Please set `network` and `target` at .putpaws/application.json\n" +
+          "They refer to `network` and `target` sections at .putpaws/infra.json\n" +
+          "(Ex) \"network\": \"awesome-private-staging\", \"target\": \"awesome-staging\""
+      end
+      new(
+        region: config.ecs_region || config.region,
+        network: config.network,
+        target: config.target,
+      )
+    end
+
+    # "45" and "45m" mean 45 minutes. "90s" and "2h" are also acceptable.
+    def self.parse_ttl(ut)
+      ut = DEFAULT_TTL if ut.nil? || ut.strip.empty?
+      matched, number, unit = ut.strip.match(/\A(\d+)([smh])?\z/).to_a
+      raise "Invalid ttl: #{ut} (Ex) ttl=30m ttl=2h ttl=90s" unless matched
+      number.to_i * SECONDS[unit || 'm']
+    end
+
+    attr_reader :ecs_client
+    attr_reader :region, :network, :target
+    def initialize(region:, network:, target:)
+      @ecs_client = Aws::ECS::Client.new({region: region})
+      @region = region
+      @network = network
+      @target = target
+    end
+
+    def cluster_name
+      target.cluster.split('/').last
+    end
+
+    def container_name
+      target.container_name || 'app'
+    end
+
+    # Launch a temporary task whose main process is overridden with the given
+    # command, so that the task terminates itself when the command finishes.
+    # started_by and group are set so that temporary tasks are identifiable.
+    def run_ecs_task(command:, started_by:, group:, container: nil)
+      res = ecs_client.run_task({
+        cluster: target.cluster,
+        task_definition: target.task_definition,
+        count: 1,
+        launch_type: 'FARGATE',
+        enable_execute_command: true,
+        started_by: started_by,
+        group: group,
+        network_configuration: {
+          awsvpc_configuration: {
+            subnets: network.subnets,
+            security_groups: network.security_groups,
+            assign_public_ip: network.assign_public_ip,
+          }
+        },
+        overrides: {
+          container_overrides: [
+            {
+              name: container || container_name,
+              command: ['/bin/sh', '-c', command],
+            }
+          ]
+        },
+      })
+      failure = res.failures.first
+      raise "Failed to run task: #{failure.reason} #{failure.detail}" if failure
+      res.tasks.first
+    end
+
+    def wait_until_attachable(task_arn, timeout: 600, interval: 5)
+      deadline = Time.now + timeout
+      loop do
+        res = ecs_client.describe_tasks(cluster: target.cluster, tasks: [task_arn])
+        task = res.tasks.first
+        if task.nil? || task.last_status == 'STOPPED'
+          raise "Task was stopped: #{task && task.stopped_reason}"
+        end
+        ctn = task.containers.detect{|c| c.name == container_name}
+        agent = ctn && (ctn.managed_agents || []).detect{|a| a.name == 'ExecuteCommandAgent'}
+        return task if task.last_status == 'RUNNING' && agent && agent.last_status == 'RUNNING'
+        raise "Timed out waiting for task to be attachable: #{task_arn}" if Time.now > deadline
+        sleep interval
+      end
+    end
+
+    def wait_until_stopped(task_arn, timeout: 3600, interval: 10)
+      deadline = Time.now + timeout
+      loop do
+        res = ecs_client.describe_tasks(cluster: target.cluster, tasks: [task_arn])
+        task = res.tasks.first
+        raise "Task not found: #{task_arn}" unless task
+        return task if task.last_status == 'STOPPED'
+        raise "Timed out waiting for task to stop: #{task_arn}" if Time.now > deadline
+        sleep interval
+      end
+    end
+
+    def stop_ecs_task(task_arn, reason: 'Stopped by putpaws')
+      ecs_client.stop_task(cluster: target.cluster, task: task_arn, reason: reason)
+    end
+  end
+end