Skip to content

docs(hosting,pipeline): props and errors tables, front doors first, custom door guide in its own file - #1636

Open
xyos wants to merge 5 commits into
aws:mainfrom
xyos:docs/readme-hosting-pipeline
Open

xyos wants to merge 5 commits into
aws:mainfrom
xyos:docs/readme-hosting-pipeline

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • packages/hosting/README.md was 1,669 lines (12,969 words). ## Secrets & config, more than 200 lines, came before the choice of front door, and about 235 lines for authors of a custom door sat inside ## Front doors.
  • It had no quick start, no list of HostingConstructProps and no list of errors. Many sentences said "fails synth" or "throws" without the error name.
  • Some statements were wrong. The paragraph on Next.js behind the alb and stacked doors called it "the exception" and told the reader to "serve it there through CloudFront"; synth fails there. The custom-door wiring check was said to fail "with ServeStaticAsset", which is a rule name in the message of UnsupportedFrontDoorError. The stacked custom-door example sent the origin secret over plain HTTP.
  • The allowPlainHttp rule and the streaming/buffered rule were each restated in several sections.
  • packages/pipeline/README.md (124 lines) documented none of its props and said of Pipeline.create() only that async stage factories need it.

Issue #, if available:

Changes

This pull request has four commits. The first, 74bea9719, moves "Bring your own front door" verbatim into packages/hosting/CUSTOM-FRONT-DOOR.md and adds that file to files in packages/hosting/package.json. The README keeps the heading, a summary, a link from the front-door table, and what AWS Blocks checks and enforces for such a door. The other three commits are on top of it.

packages/hosting/README.md

Corrections:

  • Next.js behind alb and stacked fails synth with StreamingServerNeedsStreamingDoorError; behind the HTTP API the adapter builds it buffered (packages/hosting/src/constructs/hosting_construct.ts:3002-3015, packages/hosting/src/adapters/shared/build_profile.ts:5-11).
  • getSecret throws no secret reference found; the README gave only the getConfig message (packages/hosting/src/secret-runtime.ts:141).
  • HostingConstruct is exported from @aws-blocks/hosting/constructs (packages/hosting/src/constructs/index.ts:18), not @aws-blocks/hosting.
  • The codec example imports the five names it uses (packages/hosting/src/index.ts:19-48); it imported four it did not use and omitted config, secret and isSecret.
  • An unknown door and an unknown door option have one row each, with UnsupportedFrontDoorError and InvalidFrontDoorOptionError (packages/hosting/src/constructs/front_door_options.ts:620,651,669).

Added, derived from the source:

  • ## Quick start: a runnable adapter call, the adapter table (src/adapters/{nextjs,nitro,astro,sveltekit,spa}.ts), the entry-point table (package.json exports) and the HostingConstructProps table (src/constructs/hosting_construct.ts:170-607).
  • ## Errors: 29 HostingError names, each condition taken from its throw site in src/constructs/*.ts and packages/core/src/hosting.ts:2037,2239.
  • Option tables for secretStore / configStore (src/secret-resolve.ts:50-68), serverOrigin (src/constructs/front_door_options.ts:100-137) and the SSR cache options (src/constructs/cdn_construct.ts:810-963).
  • ### Streaming and buffered servers, a table by door and framework, the one statement of that rule.

Reordered: quick start and props, front doors, Next.js, SSR compute, build retention, access logging, SSR caching, custom domains, monitoring, secrets and config, errors. allowPlainHttp is stated once, under "Running a plain-HTTP door in production"; the other sections link to it.

Removed: ## Overview, ## Main exports, ## Architecture (the introduction and quick start cover them), ## Development, ## License, the link to #968, the reference D-016, and how a Web Function is packaged (code bucket key, revision ids, entry shim).

packages/hosting/CUSTOM-FRONT-DOOR.md

  • A failed wiring check throws UnsupportedFrontDoorError, whose message lists the unmet rules (packages/hosting/src/constructs/custom_door.ts:126,134,164).
  • The stacked example uses an HTTPS listener on 443 and an HTTPS_ONLY origin at a routerDomainName the reader supplies. The built-in stacked door rejects the plain-HTTP shape in production (packages/hosting/src/constructs/cloudfront_edge_door.ts:133-159).
  • A table of the eight cf.* helpers (src/constructs/cf_helpers.ts:195-310), with InvalidPropsError for cf.redirects / cf.headers (cf_helpers.ts:240,256).

packages/pipeline/README.md

  • new Pipeline() throws for an App scope, for appFile, for an async stageFactory and for a marker connectionArn (packages/pipeline/src/pipeline-construct.ts:172-196,364-370); a table compares it with Pipeline.create().
  • ## Options: tables for PipelineProps, source, branches[], stages[] and synth (src/types.ts, src/pipeline-construct.ts), plus the prefixes Pipeline from @aws-blocks/core defaults to (packages/core/src/pipeline/index.ts:33-41).
  • The first example is a complete aws-blocks/pipeline.cdk.ts with await Pipeline.create(app, ...).
File Lines Words Prose lines over 400 characters
packages/hosting/README.md 1669 → 1321 12969 → 10452 0 → 0
packages/hosting/CUSTOM-FRONT-DOOR.md (new) 0 → 253 0 → 1719 0 → 0
packages/pipeline/README.md 124 → 210 612 → 1535 0 → 0

The pipeline README grows because its props were not documented before. The hosting text as a whole (README plus the new file) goes from 1,669 to 1,574 lines.

Look hardest at:

  • The tables the READMEs did not have before: the 29 rows of ## Errors, HostingConstructProps, the store, serverOrigin and SSR cache options, and the pipeline options tables. Each row is a claim about the source.
  • The HTTPS stacked-door example in CUSTOM-FRONT-DOOR.md. It is standard CDK (certificates on addListener, HTTPS_ONLY) and was not synthesized.
  • The first pipeline example. As a complete file it is type-checked by the shipped-sample check (packages/blocks/src/test-support/doc-snippets.ts:19-23).
  • The new section order of the hosting README.

Not changed on purpose:

  • The upgrade steps for acceptLegacyVerifyHeader and the deprecated top-level props stay in the README, shortened: an app that still uses them needs the error names and the steps.

Open questions:

  • The pipeline README says to set cdk.json's app to the pipeline file, as test-apps/pipeline/cdk.json does. The app templates point at aws-blocks/index.cdk.ts; npx cdk synth --app … in synth.commands would keep both entry points usable. Which should the README recommend?
  • Should the acceptLegacyVerifyHeader upgrade steps, which are release-specific, move to a migration file?

Related pull requests: This supersedes the hosting part of #1496: the move of "Bring your own front door" is taken over unchanged as 74bea9719. Open pull requests that touch packages/hosting/README.md:

Whichever merges second rebases.

Part of a set of README revisions: #1635 (core), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.

Validation

Run on this branch alone at 12190ddb7, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in the changed files, and every link into them from another Markdown file, resolves (checked with a script)

Run once on all the README branches of this set combined, as they were on an earlier main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and the sandbox e2e suites. CI runs them.

Files other than Markdown in this pull request: packages/hosting/package.json.

No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.

Checklist

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: f74f277

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@aws-blocks/hosting Patch
@aws-blocks/pipeline Patch
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

xyos added 5 commits November 19, 2026 05:47
…R.md

The section is a guide for writing a door with defineFrontDoor, not for apps that pick a built-in door.
It moves verbatim into CUSTOM-FRONT-DOOR.md, which is added to the package's files.
The README keeps the heading, a summary, a link from the front-door table, and what AWS Blocks checks and enforces for such a door.
…ors before secrets and config

The README said a Next.js server behind the `alb` and `stacked` doors was "the exception" and should be served through CloudFront; it now says synth fails there with `StreamingServerNeedsStreamingDoorError`, and one table gives streaming and buffered behavior per door and framework.
Other corrections: `getSecret` throws `no secret reference found`, `HostingConstruct` is exported from `@aws-blocks/hosting/constructs`, the codec example imports the names it calls, and `allowPlainHttp` is listed among the door options.
The README had no quick start, no list of `HostingConstructProps` and no list of errors. It now has a `## Quick start` with adapter, entry-point and props tables, option tables for `secretStore` / `configStore`, `serverOrigin` and the SSR cache options, and an `## Errors` table of 29 `HostingError` names with the condition that throws each.
Sections are ordered quick start, front doors, Next.js, SSR compute, build retention, access logging, SSR caching, custom domains, monitoring, secrets and config, errors.
The `allowPlainHttp` rule and the streaming rule are each stated in one place, and the other sections link to it.
`## Overview`, `## Main exports`, `## Architecture`, `## Development`, `## License`, a pull request link, a decision reference and the description of how a Web Function is packaged are removed.
…s HTTPS in the stacked example

The guide said the wiring check fails synth "with `ServeStaticAsset`" or "with `ProxySameOriginApi`"; it throws `UnsupportedFrontDoorError`, and those are the rule names in its message.
The example of a door that stacks CloudFront over its own ALB sent the origin secret over plain HTTP to port 80; it now uses an HTTPS listener on 443 and an `HTTPS_ONLY` origin, and says why.
The `cf.*` helpers are in a table of eight rows, the three warnings of the wiring check are listed with their ids, and the shared exports are a list.
The two limits of the first example door (single-page-app deep links, request bodies to the server) are stated before the code.
…very prop

The README said only to use `Pipeline.create()` for async stage factories; `new Pipeline()` also throws for an `App` scope, for `appFile` and for a `config()` marker as `connectionArn`, and a table now compares the two forms.
The props were not documented. `## Options` now has tables for `PipelineProps`, `source`, `branches[]`, `stages[]` and `synth` with types and defaults, and states the store prefixes that `Pipeline` from `@aws-blocks/core` defaults to.
The first example is a complete `aws-blocks/pipeline.cdk.ts` that calls `await Pipeline.create(app, ...)` with the default `appFile` and a per-stage `environment`; the `stageFactory` form is the second example.
The one-time OAuth handshake of the CodeConnections connection is stated, and "Opt out of the Node.js 22 default" is folded into the `null` case of `synth.partialBuildSpec`.
@xyos
xyos force-pushed the docs/readme-hosting-pipeline branch from 8e92646 to 12190dd Compare November 19, 2026 06:11

@osama-rizk osama-rizk left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR moves the custom-door guide into its own file, adds props and errors tables to the hosting README, and documents every pipeline option. The tables are accurate and the corrections are real. I'm leaving comments, not blocking: a fact-by-fact comparison against main turned up a few dropped limitations and one security guarantee that should come back before merge, plus one row that is wrong for HostingConstruct users.

What's good

  • The StreamingServerNeedsStreamingDoorError correction for alb / stacked is right (hosting_construct.ts:3002-3015), and the single streaming table replaces three paragraphs that contradicted each other.
  • I checked every error name in ## Errors against its throw site. All 29 exist, and name === code holds (hosting_error.ts:17-24). The conditions I checked match the source: the skew range, 'none' with a server, geo type, the wiring check and the SSR cache errors.
  • The HostingConstructProps, adapter, serverOrigin, store and SSR-cache defaults match the source. The pipeline tables also match on every default and throw site.
  • CUSTOM-FRONT-DOOR.md ships in files[]. The wiring check now names the real error (custom_door.ts:164) and the real warning ids. The HTTPS stacked example type-checks against aws-cdk-lib 2 under tsc --strict, with only the @aws-blocks/hosting/constructs import stubbed.
  • Every anchor resolves, and nothing else in the repo links into a hosting README anchor that the restructure renamed.

What needs work: 3 should-fix · 8 minor · 3 nit, all non-blocking; details are inline.

Open questions

  1. Was dropping the Web Functions internals (the code bucket, content-derived revisions, the lambda:InvokeWebFunctionEndpoint custom resource) meant to remove them from the docs entirely? Or should they go to a packages/hosting/DESIGN.md, the per-block convention, since this README was where they were recorded?
  2. For the pipeline question in the description: since the AWS Blocks templates point cdk.json at aws-blocks/index.cdk.ts, I'd recommend npx cdk synth --app … in synth.commands. That keeps one cdk.json for local deploys and the pipeline. Whichever you choose, the first example should import Pipeline from @aws-blocks/core/cdk (inline).

Cross-cutting

  • The secrets limits (region, account-global prefix, stage not a security boundary) moved from a callout near the top to a plain list at the end, after monitoring. They're the most common deploy-time surprises. Consider keeping a one-line pointer to them from the Quick start or the props table row for secretStore/configStore.
  • The changeset is about 30 lines of public changelog for a docs patch, and it repeats the HTTP API claim flagged inline. A shorter list of the corrections would read better in CHANGELOG.md.
  • Naming follows the "AWS Blocks" convention throughout. The repo moved to aws/cdk-blocks, but the product name and the package.json URLs on main are unchanged, so nothing here needs renaming.

| Door | Invokes the server | Next.js | Nitro `aws-lambda` preset |
|---|---|---|---|
| CloudFront; `apiGateway` with `api: 'rest'` | Streaming or buffered, as it was built | Works | Works with `awsLambda.streaming` on or off |
| `apiGateway` with `api: 'http'` | Buffered | Works: the adapter builds a buffered server. A hand-written `open-next.config.ts` with a streaming wrapper fails synth | Works with `awsLambda.streaming` off; fails synth with it on |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (should fix): This row (and the HTTP API bullets at 406-411) says Next.js works behind { kind: 'apiGateway' } because "the adapter builds a buffered server". That's only true when core Hosting runs the adapter, because it wraps the run in withBuildProfile({ serverInvoke: 'http-api' }, …) (packages/core/src/hosting.ts:1266-1268). A HostingConstruct user who calls nextjsAdapter({ projectDir }) as in the new Quick start gets the default profile. The server is emitted with streaming: true (src/adapters/nextjs.ts:2446), and synth fails with StreamingServerNeedsStreamingDoorError behind the HTTP API. The error's resolution doesn't mention the profile either. The Nitro node-server selection at 408-411 depends on the same profile. This README is the HostingConstruct reference, and this table is now the one statement of the rule, so it should be scoped.

Fix: scope the HTTP API row and bullets to Hosting from @aws-blocks/core, and add the same note the Web Functions section has for withComputeTarget. For example: "Running the adapter yourself in front of HostingConstruct, wrap it in withBuildProfile({ serverInvoke: 'http-api' }, () => nextjsAdapter(…)) from @aws-blocks/hosting/adapters." Please also adjust the matching sentence in the changeset.

(`/old//evil.example` never becomes `Location: //evil.example`). Every
redirect source is routed to the asset proxy (an ALB listener rule, an HTTP
API route, a REST resource);
(`/old/*` → `/new/*`), and the status is kept exactly (301, 302, 307, 308);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (should fix): The rewrite dropped the open-redirect guarantee from this bullet. Main said: "A spliced target that starts with extra slashes or backslashes keeps one (/old//evil.example never becomes Location: //evil.example). Every redirect source is routed to the asset proxy (an ALB listener rule, an HTTP API route, a REST resource)." It's a security property of the ALB and API Gateway doors that users rely on when they write wildcard redirects. After this change it isn't documented anywhere: hosting has no DESIGN.md, and nothing else in docs/ covers it.

Fix: restore both sentences at the end of the redirects bullet.

Suggested change
(`/old/*` → `/new/*`), and the status is kept exactly (301, 302, 307, 308);
(`/old/*` → `/new/*`), and the status is kept exactly (301, 302, 307, 308).
A spliced target that starts with extra slashes or backslashes keeps one
(`/old//evil.example` never becomes `Location: //evil.example`). Every
redirect source is routed to the asset proxy (an ALB listener rule, an HTTP
API route, a REST resource);

Comment on lines +810 to +812
`aws-blocks:build-state=superseded`, which a deploy's cutover sets. Builds
left by an aborted or rolled-back deploy are never tagged: remove them
yourself.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (should fix): This bullet keeps only the aborted or rolled-back case. It dropped the other half of main's cleanup caveat: "every build uploaded by a hosting release that didn't tag builds ... [is] never tagged, so the lifecycle rule never expires them and they accumulate until you remove them manually." That is the case every upgraded app is in. Its builds/ prefixes from before tagging stay in S3 for good, and the README now implies the 30-day rule covers them.

Fix:

Suggested change
`aws-blocks:build-state=superseded`, which a deploy's cutover sets. Builds
left by an aborted or rolled-back deploy are never tagged: remove them
yourself.
`aws-blocks:build-state=superseded`, which a deploy's cutover sets. Builds
uploaded by a hosting release that didn't tag builds, and builds left by an
aborted or rolled-back deploy, are never tagged: remove them yourself.

- The SSR server is exposed as `HostingConstruct.computeWebFunctions`, not in
`computeFunctions`. Grant it access to AWS resources through its
`grantPrincipal`.
- Superseded bundle zips expire after 30 days.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (minor): Most of main's "Under the hood" list for Web Functions was removed:

  • the versioned code bucket and its fixed key web-function/<fn>/code.zip;
  • revisions with content-derived logical IDs, so a deploy never needs a replacement update. That matters because sandbox Express Mode runs with rollback disabled and rejects replacements;
  • the entry shim;
  • the custom resource that grants lambda:InvokeWebFunctionEndpoint, which exists because CloudFormation has no resource type for that policy.

The PR says this was on purpose. But packages/hosting has no DESIGN.md, and this README has been where those decisions were recorded, so the rationale now exists only in source comments. The IAM grant in particular is something a security reviewer looks for. Left as it is, "Superseded bundle zips expire after 30 days" also no longer says where the zips live.

Fix: move the removed block into a packages/hosting/DESIGN.md (AGENTS.md: "DESIGN.md — internals + mock↔AWS differences (shipped per-BB convention)") and link it from here. Or keep a two-line summary here: "a versioned code bucket, whose superseded zips expire after 30 days; a custom resource grants the distribution lambda:InvokeWebFunctionEndpoint".

Comment on lines +879 to +880
| `cacheKeyCookies` | `string[]` | none | 8 names | `SsrCacheKeyCookieCapError` |
| `cacheKeyHeaders` | `string[]` | none | 5 names; `accept-encoding` is handled automatically and not allowed | `SsrCacheKeyHeaderCapError`, `SsrCacheKeyAcceptEncodingError` |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (minor): "8 names" and "5 names" (and "more than 8 / 5" in the errors table at 1302 and 1304) are the values under the default quota, not hard limits. The caps come from budget.limit('cacheKeyCookies' | 'cacheKeyHeaders') (src/constructs/cdn_construct.ts:828-833), which frontDoor.features.quotas raises. A reader with a raised CloudFront quota will think they can't use it.

Fix: write "8 names (10 under the default CloudFront quota, minus 2 reserved; raise it with quotas.cacheKeyCookies)" and do the same for headers, then mirror that in the two error rows.

Comment on lines +782 to +786
**`acceptLegacyVerifyHeader`.** A stack whose header value is still derived
from the stack name and construct path has the same window of 403s on the
deploy that moves it to the random secret. To avoid it, deploy once with
`serverOrigin: { acceptLegacyVerifyHeader: true }`, and then deploy again
without it. While it is set:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (nit): The new acceptLegacyVerifyHeader section is a good place for the warning that the option's JSDoc carries (src/constructs/front_door_options.ts:123-127): "while it is set, anyone who can derive that value can reach the server origin directly". The legacy value comes from the stack name and construct path, so while the option is on, the origin lock is effectively off. That's the reason "one deploy" matters.

Fix: add a bullet: "anyone who can derive the earlier value (stack name and construct path) can reach the server origin directly, so remove the option on the next deploy."

Comment on lines +272 to +276
**Deprecated top-level props.** `domain`, `waf`, `logging`, `monitoring`,
`skewProtection` and the `cdn.*` settings are deprecated aliases of the
`frontDoor.features` settings of the same name (`cdn.priceClass` is
`features.priceClass`; `cdn.webAclArn` is `features.waf.webAclArn`). They are
merged into the effective `frontDoor.features`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (nit): Main's migration note carried a backward-compatibility promise: "an existing app that sets them with no frontDoor (or 'cloudfront') synthesizes the same template". It also gave the instruction "Move each one into frontDoor.features under the same name". Both were dropped, and the promise is the part an upgrading user needs to read.

Fix: append "An app that sets them with no frontDoor (or 'cloudfront') synthesizes the same template; move each one into frontDoor.features under the same name."

npx hosting-config set FEATURE_FLAGS '{"beta":true}' --prefix /myapp/config
```

- `set` creates the entry or overwrites it, with no prompt. Run it again to

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (nit): "with no prompt" sits right below a command block whose first line is # hidden prompt. Main's "(no error, no prompt)" meant no overwrite confirmation, and that reading is lost.

Fix:

Suggested change
- `set` creates the entry or overwrites it, with no prompt. Run it again to
- `set` creates the entry or overwrites it, with no confirmation. Run it again to

```ts
// aws-blocks/pipeline.cdk.ts
import { App } from 'aws-cdk-lib';
import { Pipeline } from '@aws-blocks/pipeline';

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (minor): This example is labelled aws-blocks/pipeline.cdk.ts, a file in an AWS Blocks app, but it imports Pipeline from @aws-blocks/pipeline. That class defaults secretStore / configStore to /hosting/secrets and /hosting/config, while the AWS Blocks secret / config scripts write /blocks/<stackId>/…, as lines 103-106 explain. Once a reader swaps the literal ARN for config('CONNECTION_ARN'), or adds buildSecrets, the pipeline reads the wrong prefix and synth reports the value as missing. test-apps/pipeline/aws-blocks/pipeline.cdk.ts:5 imports from @aws-blocks/core/cdk for this reason.

Fix:

Suggested change
import { Pipeline } from '@aws-blocks/pipeline';
import { Pipeline } from '@aws-blocks/core/cdk';

Or keep @aws-blocks/pipeline, move the example out of aws-blocks/, and say it is for a CDK app without the AWS Blocks layer.

| `env` | `cdk.Environment` | the pipeline's account and region | Target account and region. |
| `requireApproval` | `boolean` | `false` | Manual approval before the stage deploys. |
| `approvalComment` | `string` | `Approve deployment to <name>` | Comment shown in the approval. |
| `bakeTime` | `cdk.Duration` | | Wait after the deploy before the pipeline proceeds. Must be positive. Runs as a CodeBuild `sleep` step with a timeout of `bakeTime` plus 10 minutes. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (minor): "Must be positive" isn't enough. The check is bakeTime.toMinutes() <= 0 and the timeout is Duration.minutes(bakeTime.toMinutes() + 10) (src/pipeline-construct.ts:586,602). CDK's toMinutes() defaults to integral: true and throws for a duration that isn't a whole number of minutes. So Duration.seconds(90) fails synth with a CDK error rather than this package's message.

Fix: "Must be a positive whole number of minutes (for example Duration.minutes(5))."

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants