canopycms-cdk 0.0.68-int.98 → 0.1.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.
@@ -1,7 +1,17 @@
1
1
  import { Construct } from 'constructs';
2
- import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
2
+ import { CfnParameter, Duration, RemovalPolicy, aws_cloudwatch as cloudwatch, aws_ec2 as ec2, aws_efs as efs, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_s3 as s3, aws_logs as logs } from 'aws-cdk-lib';
3
3
  import type { IBucket } from 'aws-cdk-lib/aws-s3';
4
+ import type * as sns from 'aws-cdk-lib/aws-sns';
5
+ import type { WorkerCode } from './worker-bundle.js';
4
6
  import type { CanopyCmsAttachOptions } from './editor-routing.js';
7
+ /**
8
+ * `lines` without their shell comment lines, outside heredoc bodies, so the comments stay in this
9
+ * file and out of the 16 KiB EC2 allows user data. A `#!` line is kept, and every line of a
10
+ * heredoc is kept as written. Only the quoted form, a line ending `<< 'DELIM'`, may open one: any
11
+ * other `<<` is refused, since its body would be read as commands and comments here.
12
+ * @internal Exported for tests.
13
+ */
14
+ export declare function withoutShellComments(...lines: string[]): string[];
5
15
  /**
6
16
  * Default CMS Lambda timeout.
7
17
  *
@@ -54,13 +64,13 @@ export interface CanopyCmsServiceProps {
54
64
  * A reservation costs nothing while idle; it is a ceiling, and a share of
55
65
  * the account's concurrency set aside so other functions cannot use it.
56
66
  * Lambda keeps 100 of the account's limit unreserved, so this plus every
57
- * other reservation (AssetSupport's transform Lambda reserves 10) must fit
67
+ * other reservation (AssetSupport's lazy transform Lambda reserves 10) must fit
58
68
  * within the account limit minus 100.
59
69
  */
60
70
  reservedConcurrency?: number;
61
71
  /**
62
72
  * Lambda architecture (default: `Architecture.ARM_64`, matching the EC2
63
- * worker and AssetSupport's transform Lambda).
73
+ * worker and AssetSupport's lazy transform Lambda).
64
74
  *
65
75
  * This also decides the image's architecture for
66
76
  * `DockerImageCode.fromImageAsset`: the construct always passes a resolved
@@ -73,14 +83,49 @@ export interface CanopyCmsServiceProps {
73
83
  * no build for CDK to steer, so it must already be built for this architecture.
74
84
  */
75
85
  architecture?: lambda.Architecture;
76
- /** EC2 spot max price (default: on-demand rate for t4g.nano) */
77
- spotMaxPrice?: string;
78
86
  /**
79
- * ADDITIONAL Secrets Manager ARNs the worker may read.
87
+ * What the single worker instance runs on. Default: one on-demand t4g.nano.
88
+ *
89
+ * `{ type: 'spot' }` costs less but can leave the deployment with NO worker:
90
+ * when no spot capacity is available in either zone the group keeps
91
+ * retrying, `/edit` answers 500 on a first deploy (nothing has created
92
+ * `remote.git`) and later publishes wait, while `cdk deploy` reports success. An Auto Scaling group
93
+ * has no automatic fallback from spot to on-demand. Spot uses a
94
+ * mixed-instances policy over several Graviton sizes, price-capacity-optimized,
95
+ * which makes a shortage less likely but cannot rule it out.
96
+ */
97
+ workerCapacity?: WorkerCapacity;
98
+ /**
99
+ * How long a terminating worker instance may wait for its worker to drain
100
+ * before termination continues anyway (default 5 minutes, at least
101
+ * {@link MIN_WORKER_TERMINATION_HEARTBEAT}, at most 2 hours). The worker
102
+ * completes the hook as soon as it has drained, normally within seconds, so
103
+ * this bounds only a worker that hangs.
104
+ */
105
+ workerTerminationHeartbeat?: Duration;
106
+ /**
107
+ * How long a worker instance may run before Auto Scaling replaces it
108
+ * (default 7 days; between 1 and 365 days; `null` never replaces it on
109
+ * age). Each replacement boots on the latest Amazon Linux packages, the
110
+ * kernel excepted, which is how a worker no deploy has touched still gets
111
+ * patched.
112
+ *
113
+ * A replacement pauses only the worker's half: saves keep working, while
114
+ * publishing, pull requests and sync wait for the new instance to boot.
115
+ */
116
+ workerMaxInstanceLifetime?: Duration | null;
117
+ /**
118
+ * Where the worker's bundle comes from (default `{ source: 'asset' }`).
119
+ * `{ source: 'parameter' }` lets a parameter-only change set roll the
120
+ * worker; see "Rolling the worker from CI" in docs/deploying-to-aws.md.
121
+ */
122
+ workerCode?: WorkerCode;
123
+ /**
124
+ * ADDITIONAL Secrets Manager ARNs the worker instance's role may read.
80
125
  *
81
126
  * You do NOT need to repeat `githubTokenSecretArn` or
82
- * `clerkSecretKeySecretArn` here — those are unioned into the worker's IAM
83
- * policy automatically. Use this only for secrets the construct does not
127
+ * `clerkSecretKeySecretArn` here — those are unioned into the instance
128
+ * role's policy automatically. Use this only for secrets the construct does not
84
129
  * know about.
85
130
  */
86
131
  secretsArns?: string[];
@@ -97,6 +142,24 @@ export interface CanopyCmsServiceProps {
97
142
  environment?: Record<string, string>;
98
143
  /** EFS removal policy (default: RETAIN) */
99
144
  efsRemovalPolicy?: RemovalPolicy;
145
+ /**
146
+ * Daily AWS Backup of the EFS file system, kept 35 days (default true).
147
+ * Branches nobody has submitted yet exist only on EFS. Backup storage is
148
+ * billed per GB-month on top of EFS itself, and recovery points outlive the
149
+ * stack: their vault refuses deletes until its access policy is changed.
150
+ */
151
+ efsBackup?: boolean;
152
+ /**
153
+ * Give the file system a policy that refuses clients without TLS or without
154
+ * IAM authorization (default true). The worker and the Lambda mount with
155
+ * both, through the access point their roles are granted.
156
+ *
157
+ * A stack deployed before the worker mounted with IAM upgrades in two
158
+ * deploys, `false` first: CloudFormation updates the file system before it
159
+ * replaces the worker, so in one deploy the policy lands while the outgoing
160
+ * worker still holds an anonymous mount. See CHANGELOG.md.
161
+ */
162
+ efsEnforceIamAndTls?: boolean;
100
163
  /** GitHub owner for worker git operations (e.g., 'safeinsights') */
101
164
  githubOwner: string;
102
165
  /** GitHub repo name for worker git operations (e.g., 'docs-site') */
@@ -206,24 +269,26 @@ export interface CanopyCmsServiceProps {
206
269
  */
207
270
  clerkSecretKeySecretJsonField?: string;
208
271
  /**
209
- * The GitHub repository's default branch name (default: 'main').
272
+ * The branch editing branches fork from (default: unset, so the worker
273
+ * detects it: the branch remote.git's HEAD names, or before remote.git exists
274
+ * GitHub's default branch).
210
275
  *
211
276
  * Interpolated straight into a git ref (`refs/heads/{baseBranch}`) and into
212
277
  * the worker's `.env` heredoc, so an invalid value is rejected at synth (see
213
278
  * `assertValidGitBranchName` above). A branch that git accepts but the repo
214
279
  * does not have fails permanently at boot instead: `verifyBaseBranchExists`
215
280
  * (packages/canopycms/src/worker/cms-worker.ts) throws, `worker/index.ts`
216
- * exits 1, systemd's `Restart=always` repeats that forever, and
217
- * `rebaseActiveBranches` rebases against the wrong lineage in the meantime.
281
+ * exits 1, and systemd's `Restart=always` repeats that forever.
218
282
  *
219
283
  * MUST match the shared repo's `canopycms.config.ts`'s `defaultBaseBranch`
220
- * (both default to 'main' when unset) — the two are resolved by different
221
- * processes (this stamps the worker's `.env`; the Lambda reads
222
- * `config.defaultBaseBranch` at request time) with no automatic reconciliation
223
- * between them. `infrastructure/lib/cms-stack.ts`, as scaffolded by
284
+ * whenever that is set. Leaving `defaultBaseBranch` unset is safe whether or
285
+ * not this is set: the worker points remote.git's HEAD at the branch it uses,
286
+ * and the Lambda reads that HEAD. Setting `defaultBaseBranch` alone is not:
287
+ * the two are resolved by different processes, and a Lambda configured with
288
+ * one name against a worker that detected another forks and rebases against
289
+ * different lineages. `infrastructure/lib/cms-stack.ts`, as scaffolded by
224
290
  * `canopycms init-deploy aws`, derives this prop FROM that config file so the
225
- * two cannot drift; a hand-rolled stack must set it explicitly whenever
226
- * `defaultBaseBranch` is anything other than 'main'.
291
+ * two cannot drift.
227
292
  */
228
293
  baseBranch?: string;
229
294
  /**
@@ -250,6 +315,18 @@ export interface CanopyCmsServiceProps {
250
315
  * drift.
251
316
  */
252
317
  settingsBranch?: string;
318
+ /**
319
+ * Branches the worker never pushes, deletes or opens a pull request from, beside `baseBranch`
320
+ * and GitHub's default branch, which it always protects (default: none). Each entry is a branch
321
+ * name or a glob in which `*` matches any run of characters, `/` included (`release/*`),
322
+ * matched case-sensitively, as GitHub names refs. No entry may start with `canopycms-settings-`:
323
+ * a glob never matches a settings branch, and protecting one by name would stop the deployment's
324
+ * settings reaching GitHub. At most 1024 entries, and fewer when long: synth refuses any set
325
+ * that could take the worker's user data past EC2's 16 KiB. Stamped, comma-separated, into the
326
+ * GitHub gateway's `CANOPYCMS_PROTECTED_BRANCHES` (the worker's, for a bundle older than the
327
+ * split), and validated at synth.
328
+ */
329
+ protectedBranches?: string[];
253
330
  /**
254
331
  * Deployment name (default: 'prod'). Namespaces the settings branch
255
332
  * (`canopycms-settings-{deploymentName}`) so this stack's CMS Lambda/worker
@@ -295,6 +372,21 @@ export interface CanopyCmsServiceProps {
295
372
  * default name would collide).
296
373
  */
297
374
  workerLogGroupName?: string;
375
+ /**
376
+ * SNS topic notified when the worker has stopped syncing git (and again when
377
+ * it recovers). Creating the topic and subscribing to it (email, Slack,
378
+ * PagerDuty) is the adopter's job. Default: none, and then no metric filter,
379
+ * alarm or alarm action is created.
380
+ *
381
+ * The alarm fires when the worker's log shows no git-sync cycle for 30
382
+ * minutes, which covers a crash loop, a boot loop, a worker that never
383
+ * started and a worker whose loops have stopped. A deploy or a spot
384
+ * replacement does not trip it. See `workerDownAlarm`.
385
+ *
386
+ * The topic is also notified when a worker boot could not upgrade its
387
+ * packages and started on the AMI's. See `workerUnpatchedAlarm`.
388
+ */
389
+ alarmTopic?: sns.ITopic;
298
390
  /**
299
391
  * Execution role for the CMS Lambda (default: CDK creates one).
300
392
  *
@@ -335,6 +427,31 @@ export interface CanopyCmsServiceProps {
335
427
  */
336
428
  cmsLogGroupName?: string;
337
429
  }
430
+ /**
431
+ * The worker instance's capacity: one on-demand instance, or spot through a
432
+ * mixed-instances policy. Every instance type must be Graviton (arm64), since
433
+ * the launch template's AMI is.
434
+ */
435
+ export type WorkerCapacity = {
436
+ type: 'on-demand';
437
+ /** Default t4g.nano. */
438
+ instanceType?: ec2.InstanceType;
439
+ } | {
440
+ type: 'spot';
441
+ /** The pools to choose from, most preferred first. Default t4g.nano, t4g.micro, t4g.small. */
442
+ instanceTypes?: readonly ec2.InstanceType[];
443
+ /** USD per hour. Default: each type's on-demand price. */
444
+ maxPrice?: string;
445
+ /**
446
+ * Auto Scaling Capacity Rebalancing: replace a spot instance EC2 marks at
447
+ * elevated risk of interruption (default true). A replacement that starts
448
+ * before the old instance stops cannot run a worker until the old one
449
+ * releases the worker lock.
450
+ */
451
+ capacityRebalance?: boolean;
452
+ };
453
+ /** The worker's internal drain deadline (core's DEFAULT_DRAIN_DEADLINE_MS) plus two minutes. */
454
+ export declare const MIN_WORKER_TERMINATION_HEARTBEAT: Duration;
338
455
  /**
339
456
  * Core CDK construct for CanopyCMS deployment.
340
457
  *
@@ -343,7 +460,8 @@ export interface CanopyCmsServiceProps {
343
460
  * - EFS filesystem with access point at /workspace
344
461
  * - Lambda function (Docker image, EFS mount, private subnet, no internet)
345
462
  * - Lambda Function URL (for CloudFront origin)
346
- * - EC2 Worker (t4g.nano spot in ASG, public subnet, EFS mount, systemd) -
463
+ * - EC2 Worker (on-demand t4g.nano by default, in an ASG, public subnet, EFS
464
+ * mount, systemd, a terminating lifecycle hook it completes once drained) -
347
465
  * rolled via the ASG's UpdatePolicy by every deploy that changes its launch
348
466
  * template, so a changed worker bundle reaches the instance instead of
349
467
  * sitting unused in a launch template until the next spot interruption (see
@@ -385,6 +503,20 @@ export declare class CanopyCmsService extends Construct {
385
503
  readonly workerAsg: autoscaling.AutoScalingGroup;
386
504
  /** The EC2 worker's CloudWatch log group (worker stdout/stderr) */
387
505
  readonly workerLogGroup: logs.LogGroup;
506
+ /** Alarms when the worker logs no git-sync cycle for 30 minutes. Set only with `alarmTopic`. */
507
+ readonly workerDownAlarm?: cloudwatch.Alarm;
508
+ /** Alarms when a worker boot started without its package upgrade. Set only with `alarmTopic`. */
509
+ readonly workerUnpatchedAlarm?: cloudwatch.Alarm;
510
+ /**
511
+ * With `workerCode: { source: 'parameter' }`: the bucket worker bundles are
512
+ * uploaded to, as `canopy-worker/<sha256>.js`.
513
+ */
514
+ readonly workerBundleBucket?: s3.Bucket;
515
+ /**
516
+ * With `workerCode: { source: 'parameter' }`: the template parameter naming
517
+ * the bundle to run by its sha256; its logical id is also a stack output.
518
+ */
519
+ readonly workerBundleSha256Parameter?: CfnParameter;
388
520
  constructor(scope: Construct, id: string, props: CanopyCmsServiceProps);
389
521
  /**
390
522
  * Serve the editor from a CloudFront distribution you already own, such as