putpaws 0.1.6 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d6d053460a5c78abad1e20f800e26aae412b0768b47a182380c9e876ebb616f9
4
- data.tar.gz: bbb6cd4158d334b4029b17cb6141cf52e6e490317f9d438d2af0d43856876728
3
+ metadata.gz: 2668a564f83925138616ef8787a87d3b681467d3f7d70b14f60b5c41993e3ec0
4
+ data.tar.gz: 55609a4d240893aaec2a064059fcfb4f87db4be230def50cf15243a5be4bb30a
5
5
  SHA512:
6
- metadata.gz: bdf0ff9f7a76d786532fe1b4a13991bd0542d2d584c9a1158996ff84f0479913062cc8b5ce9856a27fe3b7d83978e3c6d9e8816753733ac0a43db9e20ea9986b
7
- data.tar.gz: b3714483e120918f2c777b1dd8f0b010efc4f26268a283a9f1d1a426f0ea0e1b214c033b2fb0e19d2c5b77a498a22f373a994c8ad16620a792993b528e6faa37
6
+ metadata.gz: 9603dfcc06ac561fedff81463bb559e2e08ea920e920925703c0c17d514f217f686d15f802a72ac6db71c23f19a314aaddeacc126b9c1495a1cf93b8983bde3f
7
+ data.tar.gz: d49eb9ed9c72809cf49e8a6f016f514e07d54efdbe65b6d4642621645dc13fc6816a299e6fb2ea0126696d5c50ef36574ebf52d4320d7d3abb91aa219f467d0e
data/README.md CHANGED
@@ -10,6 +10,44 @@ The short commands follow a "put your paws ..." image:
10
10
  - `putpaws ahead` ... put paws ahead: — reach ahead and probe (dry-run)
11
11
  - `putpaws away` ... put paws away: — take your paws off and let AI take over
12
12
 
13
+ ## How it is organized
14
+
15
+ Every command starts with the environment:
16
+
17
+ ```
18
+ bundle exec putpaws <environment> <task> key=value ...
19
+ ```
20
+
21
+ Settings live in one folder per environment. Inside an environment, what you need to
22
+ **operate** things that are already running is kept apart from what you need to **start** tasks.
23
+
24
+ ```
25
+ .putpaws/
26
+ ├── infra.json # parts (network / target). Shared by all environments
27
+ ├── awesome-api-production/ # one folder per environment (folder name = first argument)
28
+ │ ├── application.json # environment settings: region / cluster + prefixes to find tasks, logs, builds
29
+ │ ├── launch.json # named launches: which task definition, on which network, with which overrides
30
+ │ └── schedule.json # schedules: a launch + when to run it
31
+ ├── awesome-api-staging/
32
+ │ └── ...
33
+ └── provisioning/ # provisioning inputs and state
34
+ ```
35
+
36
+ | File | Role | Written by | `putpaws up` |
37
+ |---|---|---|---|
38
+ | `infra.json` | parts used to start tasks (`network` / `target`) | putpaws (you can add parts) | writes its own keys only |
39
+ | `<environment>/application.json` | operate what is running | putpaws | generates / updates the keys it knows |
40
+ | `<environment>/launch.json` | named launches | you | adds missing names only, never rewrites |
41
+ | `<environment>/schedule.json` | schedules | you | never touched |
42
+
43
+ - The environments are the folders right under `.putpaws/` that hold `application.json`.
44
+ - A **launch** is a named combination of task definition, network and overrides.
45
+ `ecs:run`, `ecs:shell` and the scheduler all start tasks from the same launches,
46
+ so something you ran by hand is exactly what the schedule runs.
47
+ - ECS takes the network (subnets, security groups, public IP) when a task is started, not from the
48
+ task definition. That is why one task definition can be started on another network or in another
49
+ size just by overriding a launch.
50
+
13
51
  ## Provisioning
14
52
 
15
53
  Build service infra (security group / ECS cluster / task definitions / service / log groups / CodeBuild) idempotently.
@@ -67,27 +105,30 @@ Bundled presets (ECS Fargate, `awsvpc`):
67
105
  (maintenance pages, custom rewrites, proxy-level auth).
68
106
 
69
107
  Need another task definition (Ex: a batch worker)? Add an entry to `task_definitions` of the
70
- copied preset with its own template; `up` creates it and writes an `application.json` entry for it.
108
+ copied preset with its own template; `up` creates it, writes its `target` into `infra.json`
109
+ and adds a launch named after its suffix.
71
110
 
72
111
  Security groups are either specified (one or more existing ones; putpaws never touches their rules)
73
112
  or a new one is created for the service when left empty on `ready`.
74
113
 
75
- When the service step completes, the new service is reflected into
76
- `.putpaws/application.json` and `.putpaws/infra.json` (diff is shown and confirmed),
77
- so `ecs:attach`, `ecs:shell`, `ecs:run` and `log:*` work immediately.
78
- One entry is written per task definition of the preset, keyed by the task definition
79
- family `{service_name}-{suffix}` (Ex: `awesome-api-staging-app` / `awesome-api-staging-web`),
80
- each pointing at the `infra.target` of the same name. Only the entry of the preset's
81
- `service_task_definition` carries `service` (for `ecs:deploy` / `ecs:attach`); the others have
82
- `service: null` and are meant for one-off tasks (`ecs:run` / `ecs:shell` / scheduler),
83
- so with `rails-nginx` `db:migrate` keeps running on the plain `app` task definition while the
84
- service runs `web` (nginx + app). `infra.network` is written once as `{service_name}`.
85
- Existing keys are never deleted; remove stale ones by hand.
114
+ When the service step completes, the new service is reflected into the operation settings
115
+ (`service_name` is the environment name), so `ecs:attach`, `ecs:shell`, `ecs:run` and `log:*`
116
+ work immediately. `up` writes only what it knows the right answer for and never overrides your choices:
117
+
118
+ | Target | What `up` does |
119
+ |---|---|
120
+ | `{service_name}/application.json` | generated / updated after showing the diff. Keys you added by hand (`log_region` ...) are kept |
121
+ | `infra.json` `network.{service_name}` | generated / updated after showing the diff |
122
+ | `infra.json` `target.{family}` | generated / updated, one per task definition of the preset (`{service_name}-{suffix}`) |
123
+ | `{service_name}/launch.json` | a launch named after each suffix (`app` ...) is added **when that name is absent**: `{"target": "{family}", "network": "{service_name}"}`. Existing launches are never rewritten |
124
+ | `{service_name}/schedule.json` | never touched |
125
+
126
+ Parts you added to `infra.json` (Ex: a public network) and launches you edited stay as they are.
86
127
  Secrets are handled by reference only: task definitions point to existing
87
128
  SSM parameters (Ex: `/{service_name}/RAILS_MASTER_KEY`) and putpaws never touches the values.
88
129
 
89
- A scheduler role is always created too, and the `target` entry of infra.json carries it,
90
- so `scheduler:deploy` works any time by just writing `.putpaws/schedule.json`.
130
+ A scheduler role is always created too, and every `target` of infra.json carries it,
131
+ so `scheduler:deploy` works any time by just writing `{service_name}/schedule.json`.
91
132
 
92
133
  The CPU architecture is declared once as `cpu_architecture` (`ARM64` / `X86_64`) in the preset
93
134
  defaults (overridable per service via `overrides`), and applied consistently to both
@@ -105,7 +146,7 @@ builds can reach GitHub / ECR / CloudWatch Logs.
105
146
  ## Operator permissions
106
147
 
107
148
  Declare named operator profiles in `.putpaws/operators.json` (generated with examples on first run),
108
- then resolve them into managed policies per service, idempotently
149
+ then resolve them into managed policies per environment, idempotently
109
150
  (CREATE / UPDATE as a new policy version / SKIP — re-running never piles up policies):
110
151
 
111
152
  ```
@@ -123,7 +164,7 @@ Groups map to putpaws command namespaces: `attach` (ecs:attach/forward), `shell`
123
164
  note this implies reading all secrets of the service), `deploy` (ecs:deploy), `logs` (log:*),
124
165
  `codebuild` (code_build:build), `scheduler` (scheduler:deploy).
125
166
  `extra_statements` on a profile appends raw IAM statements.
126
- The policy is named `{service}-operator-{profile}`. Attaching it to users/groups is left to your admin
167
+ The policy is named `{environment}-operator-{profile}`. Attaching it to users/groups is left to your admin
127
168
  (an attach command example is printed).
128
169
 
129
170
  ## AI setup
@@ -141,7 +182,7 @@ bundle exec putpaws away
141
182
 
142
183
  ### Info
143
184
 
144
- Show resolved settings for a service without touching AWS
185
+ Show the settings of an environment with its launches and schedules, without touching AWS
145
186
 
146
187
  ```
147
188
  bundle exec putpaws awesome-api-staging info
@@ -177,38 +218,98 @@ bundle exec putpaws awesome-api-staging ecs:deploy desired=2 taskdef=awesome-api
177
218
  ```
178
219
 
179
220
  Run a command on a temporary task. The task terminates itself when the command finishes.
221
+ What gets started is a **launch** of the environment (`launch.json`).
180
222
 
181
223
  ```
182
- bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate'
224
+ # A saved launch as it is (the launch carries its own command)
225
+ bundle exec putpaws awesome-api-staging ecs:run launch=seed
183
226
 
227
+ # A saved launch with the command given on the spot.
184
228
  # Pass wait=true to wait until the task stops and check the exit code
185
- bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake db:migrate' wait=true
229
+ bundle exec putpaws awesome-api-staging ecs:run launch=app cmd='bundle exec rake db:migrate' wait=true
186
230
 
187
- # Override the task size for this launch only (must be a valid Fargate combination).
188
- # Also available on ecs:shell.
189
- bundle exec putpaws awesome-api-staging ecs:run cmd='bundle exec rake heavy:job' cpu=1024 memory=2048 wait=true
231
+ # Override part of a saved launch for this run only
232
+ bundle exec putpaws awesome-api-staging ecs:run launch=seed network=awesome-api-staging cpu=8192 memory=32768
233
+
234
+ # Assemble a launch on the spot without saving anything
235
+ bundle exec putpaws awesome-api-staging ecs:run target=awesome-api-staging-app network=awesome-api-staging cmd='bin/rails db:migrate:status'
236
+
237
+ # Save what you tried under another name, then run it
238
+ bundle exec putpaws awesome-api-staging ecs:run launch=seed cpu=4096 memory=16384 save=seed-small
239
+
240
+ # Show what would be started, and start nothing
241
+ bundle exec putpaws awesome-api-staging ecs:run launch=seed dry=true
190
242
  ```
191
243
 
244
+ | Parameter | Meaning |
245
+ |---|---|
246
+ | `launch=` | name of the launch to use. Without it, `target=` and `network=` are required |
247
+ | `target=` / `network=` | names in `infra.json` |
248
+ | `cmd=` | command (a string, run through `/bin/sh -c`) |
249
+ | `container=` / `cpu=` / `memory=` | container to override / task size (a valid Fargate combination) |
250
+ | `env='NAME=value NAME2=value2'` | environment variables (space separated, merged into those of the launch) |
251
+ | `capacity_provider=` / `task_role=` / `ephemeral_storage=` | `FARGATE` or `FARGATE_SPOT` / task role ARN / GiB |
252
+ | `save=name` | save the resolved launch into `launch.json` under that name. An existing name shows the diff and asks first |
253
+ | `dry=true` | show the resolved launch and start nothing |
254
+ | `wait=true` / `ttl=` / `keep=true` | how this run behaves; never saved into a launch |
255
+
256
+ With neither `launch=` nor `target=` / `network=`, the launches of the environment are listed to choose from.
257
+ `ecs:run` needs a command, either saved in the launch or given as `cmd=`.
258
+
192
259
  Launch a temporary task for operation and attach to it (like SSH-ing into the environment).
193
- 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.
260
+ The task follows the launch except that its command is replaced by `sleep <ttl>`,
261
+ so it always terminates itself when ttl passes even if your shell is gone.
194
262
 
195
263
  ```
196
264
  # ttl is 30 minutes by default
197
- bundle exec putpaws awesome-api-staging ecs:shell
265
+ bundle exec putpaws awesome-api-staging ecs:shell launch=app
198
266
 
199
267
  # Specify ttl: "45" and "45m" mean 45 minutes, "90s" and "2h" also work
200
- bundle exec putpaws awesome-api-staging ecs:shell ttl=45m
268
+ bundle exec putpaws awesome-api-staging ecs:shell launch=app ttl=45m
201
269
 
202
270
  # The task is stopped immediately when you exit the shell.
203
271
  # Pass keep=true to keep it running until ttl passes.
204
- bundle exec putpaws awesome-api-staging ecs:shell keep=true
272
+ bundle exec putpaws awesome-api-staging ecs:shell launch=app keep=true
205
273
  ```
206
274
 
207
275
  Temporary tasks are launched with `group` / `started_by` set to `putpaws-run` or `putpaws-shell`,
208
276
  so you can identify them on the AWS console and on the task list of `ecs:attach` / `ecs:forward`.
209
277
 
210
- `ecs:run` and `ecs:shell` require `network` and `target` in `.putpaws/application.json`,
211
- which refer to the `network` / `target` sections of `.putpaws/infra.json` (the same ones used by scheduler).
278
+ ### Launch
279
+
280
+ List the launches of an environment
281
+
282
+ ```
283
+ bundle exec putpaws awesome-api-staging launch:list
284
+ ```
285
+
286
+ A launch is resolved in this order every time; later ones win field by field:
287
+
288
+ 1. defaults of the task definition (putpaws passes nothing)
289
+ 2. the launch in `launch.json`
290
+ 3. for a schedule: the overrides written in `schedule.json`
291
+ 4. for a manual run: the command-line parameters
292
+
293
+ `env` is merged name by name; every other field is replaced as a whole.
294
+ Before anything starts, putpaws checks that `target` and `network` exist in `infra.json` and that the
295
+ cluster of the target is the cluster of the environment (`region` / `cluster` of `application.json`),
296
+ so a launch that points at the parts of another environment by mistake is stopped.
297
+
298
+ ### Scheduler
299
+
300
+ Deploy a schedule of the environment to EventBridge Scheduler.
301
+ It is created (or updated) as `<environment>-<schedule>`, Ex: `awesome-api-staging-nightly-seed`.
302
+
303
+ ```
304
+ bundle exec putpaws awesome-api-staging scheduler:deploy schedule=nightly-seed
305
+
306
+ # Show what would be deployed, and deploy nothing
307
+ bundle exec putpaws awesome-api-staging scheduler:deploy schedule=nightly-seed dry=true
308
+
309
+ bundle exec putpaws awesome-api-staging scheduler:list
310
+ ```
311
+
312
+ Without `schedule=`, the schedules of the environment are listed to choose from.
212
313
 
213
314
  ### CodeBuild
214
315
 
@@ -249,47 +350,153 @@ bundle exec putpaws awesome-api-staging log:tail since=1d for=3h
249
350
  gem 'putpaws'
250
351
  ```
251
352
 
252
- ## Setting Example
353
+ ## Settings
253
354
 
254
- `.putpaws/application.json`
355
+ ### `.putpaws/<environment>/application.json`
255
356
 
256
- Keys are free-form names you pass to the CLI. The ones written by `putpaws up` follow
257
- `{service_name}-{suffix}`: `-app` for one-off tasks (`service: null`), `-web` for the
258
- long-running service.
357
+ One per environment. The folder name is the environment name, so there is no name inside the file.
259
358
 
260
359
  ```
261
360
  {
262
- "awesome-api-staging-app": {
263
- "region": "ap-northeast-1",
264
- "cluster": "cluster-staging",
265
- "service": null,
266
- "task_name_prefix": "awesome-api-staging-app",
267
- "log_group_prefix": "/ecs/awesome-api-staging",
268
- "log_region": null,
269
- "build_log_group_prefix": "/aws/codebuild/awesome-api-staging",
270
- "build_project_name_prefix": "awesome-api-staging",
271
- "network": "awesome-api-staging",
272
- "target": "awesome-api-staging-app"
361
+ "region": "ap-northeast-1",
362
+ "cluster": "awesome-api-staging",
363
+ "service": "awesome-api-staging",
364
+ "task_name_prefix": "awesome-api-staging",
365
+ "log_group_prefix": "/ecs/awesome-api-staging",
366
+ "build_project_name_prefix": "awesome-api-staging",
367
+ "build_log_group_prefix": "/aws/codebuild/awesome-api-staging"
368
+ }
369
+ ```
370
+
371
+ - `region` / `cluster` are used both to operate and to start tasks.
372
+ - The prefixes find what is running (tasks, logs, builds). With the service name as
373
+ `task_name_prefix`, tasks of `-app` / `-extract` / `-seed` are all found.
374
+ - `service` is the long-running service for `ecs:deploy`. When null, the services of the cluster are listed to choose from.
375
+ - Optional: `ecs_region` / `log_region` / `build_region`.
376
+ - `network` / `target` / `schedules` do not belong here (see `launch.json` / `schedule.json`).
377
+
378
+ ### `.putpaws/infra.json`
379
+
380
+ Parts, each with a unique name. They do not belong to an environment.
381
+
382
+ ```
383
+ {
384
+ "network": {
385
+ "awesome-api-staging": {
386
+ "subnets": ["subnet-0aaa", "subnet-0bbb"],
387
+ "security_groups": ["sg-0aaa"],
388
+ "assign_public_ip": "DISABLED"
389
+ },
390
+ "awesome-api-staging-public": {
391
+ "subnets": ["subnet-0ccc"],
392
+ "security_groups": ["sg-0aaa"],
393
+ "assign_public_ip": "ENABLED"
394
+ }
273
395
  },
274
- "awesome-api-staging-web": {
275
- "region": "ap-northeast-1",
276
- "cluster": "cluster-staging",
277
- "service": "awesome-api-staging",
278
- "task_name_prefix": "awesome-api-staging-web",
279
- "log_group_prefix": "/ecs/awesome-api-staging",
280
- "log_region": null,
281
- "build_log_group_prefix": "/aws/codebuild/awesome-api-staging",
282
- "build_project_name_prefix": "awesome-api-staging",
396
+ "target": {
397
+ "awesome-api-staging-app": {
398
+ "scheduler_role": "arn:aws:iam::123456789012:role/awesome-api-staging-scheduler",
399
+ "cluster": "arn:aws:ecs:ap-northeast-1:123456789012:cluster/awesome-api-staging",
400
+ "task_definition": "awesome-api-staging-app",
401
+ "container_name": "app"
402
+ }
403
+ }
404
+ }
405
+ ```
406
+
407
+ ### `.putpaws/<environment>/launch.json`
408
+
409
+ Named launches, unique within the environment.
410
+
411
+ ```
412
+ {
413
+ "app": { "target": "awesome-api-staging-app", "network": "awesome-api-staging" },
414
+ "migrate": {
415
+ "target": "awesome-api-staging-app",
283
416
  "network": "awesome-api-staging",
284
- "target": "awesome-api-staging-web"
417
+ "command": "bin/rails db:migrate"
285
418
  },
286
- "awesome-api-production": {
287
- "region": "ap-northeast-1",
288
- "cluster": "cluster-production",
289
- "service": null,
290
- "task_name_prefix": "awesome-api",
291
- "log_group_prefix": "/ecs/awesome/awesome-api-production",
292
- "log_region": null
419
+ "seed-small": {
420
+ "target": "awesome-api-staging-seed",
421
+ "network": "awesome-api-staging-public",
422
+ "cpu": 4096,
423
+ "memory": 16384,
424
+ "env": { "RAILS_LOG_LEVEL": "info" },
425
+ "command": "bin/rails runner 'Seed.new.perform'"
293
426
  }
294
427
  }
295
428
  ```
429
+
430
+ | Field | Required | Meaning | Where it goes on RunTask |
431
+ |---|---|---|---|
432
+ | `target` | yes | name of a `target` in `infra.json` | `cluster` / `task_definition` |
433
+ | `network` | yes | name of a `network` in `infra.json` | `network_configuration` |
434
+ | `command` | | a string is wrapped in `/bin/sh -c`; an array is passed as it is | `overrides.container_overrides[].command` |
435
+ | `container` | | container to override. Defaults to `container_name` of the target | `overrides.container_overrides[].name` |
436
+ | `env` | | `{ "NAME": "value" }` | `overrides.container_overrides[].environment` |
437
+ | `cpu` / `memory` | | task size (a valid Fargate combination) | `overrides.cpu` / `overrides.memory` |
438
+ | `ephemeral_storage` | | ephemeral storage in GiB | `overrides.ephemeral_storage` |
439
+ | `task_role` | | task role ARN | `overrides.task_role_arn` |
440
+ | `capacity_provider` | | `FARGATE` (default) / `FARGATE_SPOT` | `capacity_provider_strategy` instead of `launch_type` |
441
+
442
+ Only what ECS lets you decide when a task is started can be written. Image, sidecars and log
443
+ destination belong to the task definition. An unknown field is an error, so that a setting which
444
+ has no effect cannot go unnoticed. `FARGATE_SPOT` needs the capacity provider to be associated with the cluster.
445
+
446
+ ### `.putpaws/<environment>/schedule.json`
447
+
448
+ A schedule is the name of a launch of the same environment plus when to run it.
449
+
450
+ ```
451
+ {
452
+ "nightly-seed": {
453
+ "launch": "seed-small",
454
+ "schedule_expression": "cron(0 18 * * ? *)",
455
+ "schedule_expression_timezone": "Asia/Tokyo"
456
+ },
457
+ "weekly-report": {
458
+ "launch": "app",
459
+ "command": "bin/rails runner 'Report.deliver_weekly'",
460
+ "cpu": 2048,
461
+ "memory": 4096,
462
+ "schedule_expression": "cron(0 9 ? * MON *)",
463
+ "schedule_expression_timezone": "Asia/Tokyo",
464
+ "state": "ENABLED"
465
+ }
466
+ }
467
+ ```
468
+
469
+ - `launch` is required. `network` / `target` / `region` come from the launch and the environment.
470
+ - Launch fields written here (`command` / `env` / `cpu` ...) override the launch for this schedule only.
471
+ - Everything else (`schedule_expression` ...) is passed to EventBridge Scheduler
472
+ `create_schedule` / `update_schedule` as it is.
473
+
474
+ ## Migrating from 0.1.x
475
+
476
+ 1.0 does not read the 0.1.x layout. While `.putpaws/application.json` or `.putpaws/schedule.json`
477
+ exists, commands that take an environment stop and tell you so.
478
+
479
+ 1. Run `bundle exec putpaws up`. It generates `.putpaws/{service_name}/application.json`,
480
+ the default launches in `launch.json` and reports the legacy files (it never reads or deletes them).
481
+ Without provisioning, write `application.json` by hand as shown above.
482
+ 2. Move what you had per entry into `launch.json`: an old entry `awesome-api-staging-seed` with
483
+ `network` / `target` becomes a launch `seed` with the same `network` / `target`.
484
+ 3. Move schedules into `{environment}/schedule.json`: replace `network` / `target` / `region` with
485
+ `"launch": "<name>"`. The schedule on AWS is now named `<environment>-<schedule>`, so a schedule
486
+ deployed by 0.1.x under its bare name stays there until you delete it.
487
+ 4. Delete `.putpaws/application.json` and `.putpaws/schedule.json`.
488
+ 5. Rewrite your commands:
489
+
490
+ | 0.1.x | 1.0 |
491
+ |---|---|
492
+ | `putpaws awesome-api-staging-app log:tailf` | `putpaws awesome-api-staging log:tailf` |
493
+ | `putpaws awesome-api-staging-app ecs:deploy` | `putpaws awesome-api-staging ecs:deploy` |
494
+ | `putpaws awesome-api-staging-app ecs:run cmd='...'` | `putpaws awesome-api-staging ecs:run launch=app cmd='...'` |
495
+ | `putpaws awesome-api-staging-app ecs:shell` | `putpaws awesome-api-staging ecs:shell launch=app` |
496
+ | `putpaws awesome-api-staging scheduler:deploy` | `putpaws awesome-api-staging scheduler:deploy schedule=<name>` |
497
+
498
+ ## Development
499
+
500
+ ```
501
+ bundle exec rake test
502
+ ```
@@ -13,10 +13,10 @@ module Putpaws
13
13
  END_MARK = '<!-- putpaws:end -->'
14
14
 
15
15
  def self.install!(root: '.', services: nil)
16
- services ||= Putpaws::ApplicationConfig.all.map(&:name)
16
+ services ||= Putpaws::ApplicationConfig.names
17
17
  skill_path = File.join(root, SKILL_PATH)
18
18
  FileUtils.mkdir_p(File.dirname(skill_path))
19
- File.write(skill_path, skill_content(services: services))
19
+ File.write(skill_path, skill_content(services: services), encoding: 'UTF-8')
20
20
  pointer_path = pointer_target(root)
21
21
  update_pointer!(pointer_path)
22
22
  [skill_path, pointer_path]
@@ -31,13 +31,13 @@ module Putpaws
31
31
 
32
32
  def self.update_pointer!(path)
33
33
  block = pointer_block
34
- content = File.exist?(path) ? File.read(path) : ''
34
+ content = File.exist?(path) ? File.read(path, encoding: 'UTF-8') : ''
35
35
  if content.include?(BEGIN_MARK)
36
36
  content = content.sub(/#{Regexp.escape(BEGIN_MARK)}.*#{Regexp.escape(END_MARK)}/m, block.strip)
37
37
  else
38
38
  content = content.empty? ? block : content.rstrip + "\n\n" + block
39
39
  end
40
- File.write(path, content)
40
+ File.write(path, content, encoding: 'UTF-8')
41
41
  end
42
42
 
43
43
  def self.pointer_block
@@ -47,14 +47,14 @@ module Putpaws
47
47
 
48
48
  This project uses the putpaws gem for AWS/ECS operations (logs, deploy, migrations, one-off tasks).
49
49
  Read `.claude/skills/putpaws/SKILL.md` for commands and safety notes before running AWS operations.
50
- Quick reference: services are the top-level keys of `.putpaws/application.json`;
51
- `bundle exec putpaws <service> info` shows resolved settings without touching AWS.
50
+ Quick reference: environments are the folders under `.putpaws/` that hold `application.json`;
51
+ `bundle exec putpaws <environment> info` shows the settings, launches and schedules without touching AWS.
52
52
  #{END_MARK}
53
53
  MD
54
54
  end
55
55
 
56
56
  def self.skill_content(services: [])
57
- services_line = services.empty? ? '(none configured yet — check .putpaws/application.json)' : services.join(', ')
57
+ services_line = services.empty? ? '(none configured yet — check .putpaws/<environment>/application.json)' : services.join(', ')
58
58
  <<~MD
59
59
  ---
60
60
  name: putpaws
@@ -65,39 +65,52 @@ module Putpaws
65
65
 
66
66
  Capistrano-style AWS operation commands. General form:
67
67
 
68
- bundle exec putpaws <service> <command> key=value
68
+ bundle exec putpaws <environment> <command> key=value
69
69
 
70
- Services in this project: #{services_line}
71
- (services are the top-level keys of `.putpaws/application.json`)
70
+ The first argument is always the environment.
71
+ Environments in this project: #{services_line}
72
+ (environments are the folders under `.putpaws/` that hold `application.json`)
72
73
 
73
74
  Discover commands with `bundle exec putpaws -T` (or `-D` for full descriptions).
74
75
 
76
+ Starting a task always goes through a *launch*: a named combination of task definition,
77
+ network and overrides saved in `.putpaws/<environment>/launch.json`.
78
+ `launch=<name>` picks one; `cpu=` / `memory=` / `cmd=` / `env=` / `network=` override it for one run.
79
+
75
80
  ## Read-only commands (safe to run without asking)
76
81
 
77
- - `bundle exec putpaws <service> info` — resolved settings, no AWS access
78
- - `bundle exec putpaws <service> log:tail since=2h` — CloudWatch logs (units: s/m/h/d/w, add `for=1h` to bound the range)
79
- - `bundle exec putpaws <service> log:tailf` — follow logs (long-running; prefer `log:tail` in automation)
82
+ - `bundle exec putpaws <environment> info` — settings, launches and schedules, no AWS access
83
+ - `bundle exec putpaws <environment> launch:list` — launches with every field, no AWS access
84
+ - `bundle exec putpaws <environment> ecs:run launch=<name> dry=true` — show what would be started, starts nothing
85
+ - `bundle exec putpaws <environment> scheduler:deploy schedule=<name> dry=true` — show the schedule that would be deployed
86
+ - `bundle exec putpaws <environment> log:tail since=2h` — CloudWatch logs (units: s/m/h/d/w, add `for=1h` to bound the range)
87
+ - `bundle exec putpaws <environment> log:tailf` — follow logs (long-running; prefer `log:tail` in automation)
80
88
  - `bundle exec putpaws ahead` — dry-run of provisioning (CREATE/UPDATE/SKIP)
81
89
 
82
90
  ## Mutating commands (confirm with the user before running)
83
91
 
84
- - `bundle exec putpaws <service> ecs:run cmd='bundle exec rake db:migrate' wait=true`
92
+ - `bundle exec putpaws <environment> ecs:run launch=app cmd='bundle exec rake db:migrate' wait=true`
85
93
  — runs a one-off command on a temporary Fargate task and exits non-zero on failure.
86
- The best choice for migrations and rake tasks. Fully non-interactive.
87
- - `bundle exec putpaws <service> ecs:deploy wait=true` — redeploy the service (force new deployment)
88
- - `bundle exec putpaws <service> code_build:build branch=main` — start the CI build (build + push + deploy per buildspec)
89
- - `bundle exec putpaws <service> scheduler:deploy` — deploy schedules from `.putpaws/schedule.json`
94
+ The best choice for migrations and rake tasks. Non-interactive as long as `launch=` is given.
95
+ A launch that saves its own `command` needs no `cmd=`.
96
+ - `bundle exec putpaws <environment> ecs:deploy wait=true` — redeploy the service (force new deployment)
97
+ - `bundle exec putpaws <environment> code_build:build branch=main` — start the CI build (build + push + deploy per buildspec)
98
+ - `bundle exec putpaws <environment> scheduler:deploy schedule=<name>` — deploy a schedule to EventBridge Scheduler
99
+ - `save=<name>` on `ecs:run` writes the resolved launch into `launch.json`
90
100
 
91
101
  ## Interactive commands (avoid in non-TTY sessions; meant for humans)
92
102
 
93
103
  - `ecs:attach`, `ecs:shell`, `ecs:forward` — open live sessions into containers
104
+ - `ecs:run` without `launch=` / `target=` and `scheduler:deploy` without `schedule=` — ask which one to use
94
105
  - `ready`, `steady`, `up`, `iam:grant` — provisioning flows with confirmation prompts
95
106
 
96
107
  ## Config files (source of truth, safe to read)
97
108
 
98
- - `.putpaws/application.json` — services and their cluster/log/build settings
99
- - `.putpaws/infra.json` — network (subnets/security groups) and target (cluster/taskdef) definitions
100
- - `.putpaws/schedule.json` — named schedules, `.putpaws/operators.json` — operator permission profiles
109
+ - `.putpaws/<environment>/application.json` — region / cluster and the prefixes that find tasks, logs and builds
110
+ - `.putpaws/<environment>/launch.json` — named launches (`target` / `network` + overrides)
111
+ - `.putpaws/<environment>/schedule.json` — schedules (a launch name + when to run)
112
+ - `.putpaws/infra.json` — parts shared by all environments: network (subnets/security groups) and target (cluster/taskdef)
113
+ - `.putpaws/operators.json` — operator permission profiles
101
114
  - `.putpaws/provisioning/<service>/` — provisioning inputs (provision.json), state, IAM role drafts
102
115
 
103
116
  ## Suggested permission allowlist (.claude/settings.json)
@@ -106,6 +119,7 @@ module Putpaws
106
119
  "allow": [
107
120
  "Bash(bundle exec putpaws -T*)",
108
121
  "Bash(bundle exec putpaws * info)",
122
+ "Bash(bundle exec putpaws * launch:list)",
109
123
  "Bash(bundle exec putpaws * log:*)"
110
124
  ]
111
125
  }
data/lib/putpaws/all.rb CHANGED
@@ -4,7 +4,10 @@ require "rake"
4
4
  require "putpaws/version"
5
5
  require "putpaws/application"
6
6
 
7
+ require "putpaws/config_file"
7
8
  require "putpaws/application_config"
9
+ require "putpaws/launch_config"
10
+ require "putpaws/launch_resolver"
8
11
  require "putpaws/schedule_config"
9
12
 
10
13
  module Putpaws
@@ -14,6 +14,17 @@ module Putpaws
14
14
  super
15
15
  end
16
16
 
17
+ # Mistakes in settings or parameters (Putpaws::Error) are answered with
18
+ # the message alone; a backtrace would only bury it. --trace shows it.
19
+ def display_error_message(ex)
20
+ if ex.is_a?(Putpaws::Error) && !options.trace
21
+ trace "#{name} aborted!"
22
+ trace ex.message
23
+ else
24
+ super
25
+ end
26
+ end
27
+
17
28
  def find_rakefile_location
18
29
  putpawsfile = File.expand_path(File.join(File.dirname(__FILE__), "..", "Putpawsfile"))
19
30
  if (location = super).nil?