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 +4 -4
- data/README.md +268 -61
- data/lib/putpaws/ai/guide.rb +35 -21
- data/lib/putpaws/all.rb +3 -0
- data/lib/putpaws/application.rb +11 -0
- data/lib/putpaws/application_config.rb +66 -37
- data/lib/putpaws/config_file.rb +73 -0
- data/lib/putpaws/ecs/launch_request.rb +144 -0
- data/lib/putpaws/ecs/run_command.rb +33 -55
- data/lib/putpaws/ecs/tasks/ecs_task.rake +48 -25
- data/lib/putpaws/env.rb +12 -0
- data/lib/putpaws/iam/grant_command.rb +16 -3
- data/lib/putpaws/infra_network_config.rb +12 -18
- data/lib/putpaws/infra_target_config.rb +26 -19
- data/lib/putpaws/launch_config.rb +141 -0
- data/lib/putpaws/launch_resolver.rb +104 -0
- data/lib/putpaws/provision/config_writer.rb +95 -34
- data/lib/putpaws/provision/runner.rb +4 -2
- data/lib/putpaws/provision/tasks/provision.rake +1 -1
- data/lib/putpaws/resolved_launch.rb +142 -0
- data/lib/putpaws/schedule_config.rb +75 -41
- data/lib/putpaws/scheduler/schedule_command.rb +50 -34
- data/lib/putpaws/scheduler/tasks/scheduler_task.rake +32 -12
- data/lib/putpaws/setup.rb +17 -5
- data/lib/putpaws/tasks/info.rake +14 -16
- data/lib/putpaws/version.rb +1 -1
- metadata +6 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 2668a564f83925138616ef8787a87d3b681467d3f7d70b14f60b5c41993e3ec0
|
|
4
|
+
data.tar.gz: 55609a4d240893aaec2a064059fcfb4f87db4be230def50cf15243a5be4bb30a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
`
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
|
90
|
-
so `scheduler:deploy` works any time by just writing
|
|
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
|
|
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 `{
|
|
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
|
|
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
|
-
|
|
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
|
|
188
|
-
|
|
189
|
-
|
|
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
|
|
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
|
-
|
|
211
|
-
|
|
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
|
-
##
|
|
353
|
+
## Settings
|
|
253
354
|
|
|
254
|
-
`.putpaws
|
|
355
|
+
### `.putpaws/<environment>/application.json`
|
|
255
356
|
|
|
256
|
-
|
|
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
|
-
"
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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
|
-
"
|
|
275
|
-
"
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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
|
-
"
|
|
417
|
+
"command": "bin/rails db:migrate"
|
|
285
418
|
},
|
|
286
|
-
"
|
|
287
|
-
"
|
|
288
|
-
"
|
|
289
|
-
"
|
|
290
|
-
"
|
|
291
|
-
"
|
|
292
|
-
"
|
|
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
|
+
```
|
data/lib/putpaws/ai/guide.rb
CHANGED
|
@@ -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.
|
|
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:
|
|
51
|
-
`bundle exec putpaws <
|
|
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
|
|
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 <
|
|
68
|
+
bundle exec putpaws <environment> <command> key=value
|
|
69
69
|
|
|
70
|
-
|
|
71
|
-
|
|
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 <
|
|
78
|
-
- `bundle exec putpaws <
|
|
79
|
-
- `bundle exec putpaws <
|
|
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 <
|
|
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.
|
|
87
|
-
|
|
88
|
-
- `bundle exec putpaws <
|
|
89
|
-
- `bundle exec putpaws <
|
|
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
|
|
99
|
-
- `.putpaws
|
|
100
|
-
- `.putpaws
|
|
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
|
data/lib/putpaws/application.rb
CHANGED
|
@@ -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?
|