@rio-cloud/cdk-v2-constructs 9.0.0-alpha.4 → 9.0.0-alpha.6

package/docs/AGENTS_DOCUMENTATION.md

@@ -30,6 +30,219 @@ Prefer `import * as rio from '@rio-cloud/cdk-v2-constructs';` unless an exported
 
 Read the relevant declaration comments and examples before writing or changing infrastructure code.
 
+## Migration guidance for `9.0.0`
+
+This section applies when upgrading a consuming project to `9.0.0` or
+later. Confirm the installed package version and its `package.json` exports
+before applying it. The guidance below is based on the implementation and
+tests in this release; it intentionally does not prescribe replacements for
+environment variables for which this wrapper exposes no one-to-one prop.
+
+### Datadog Lambda instrumentation: Datadog v5 environment handling
+
+`DatadogLambdaInstrumentation` now uses `datadog-cdk-constructs-v2` v5. Before
+calling `addLambdaFunctions()`, the construct rejects a Lambda whose CDK
+environment already contains any of these variables:
+
+```text
+DD_TRACE_ENABLED
+DD_MERGE_XRAY_TRACES
+DD_LOGS_INJECTION
+DD_SERVERLESS_LOGS_ENABLED
+DD_CAPTURE_LAMBDA_PAYLOAD
+DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING
+DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING
+DD_LOG_LEVEL
+DD_APPSEC_ENABLED
+DD_SERVERLESS_APPSEC_ENABLED
+AWS_LAMBDA_EXEC_WRAPPER
+DD_TAGS
+```
+
+Datadog v4 read existing values differently. With v5, values configured
+before instrumentation can be overwritten, so remove these settings from the
+Lambda constructor and from any `addEnvironment()` call made before
+`addLambdaFunctions()`.
+
+Use the instrumentation props for settings that have a corresponding public
+prop. The direct mappings established by this package are:
+
+| Lambda environment variable | `DatadogLambdaInstrumentation` prop |
+| --- | --- |
+| `DD_TRACE_ENABLED` | `enableDatadogTracing` |
+| `DD_MERGE_XRAY_TRACES` | `enableMergeXrayTraces` |
+| `DD_LOGS_INJECTION` | `injectLogContext` |
+| `DD_SERVERLESS_LOGS_ENABLED` | `enableDatadogLogs` |
+| `DD_CAPTURE_LAMBDA_PAYLOAD` | `captureLambdaPayload` |
+| `DD_LOG_LEVEL` | `logLevel` |
+| `DD_TAGS` | `tags` |
+
+The wrapper also exposes `enableDatadogASM` and `datadogAppSecMode`, but the
+repository does not document a mechanical mapping for every AppSec-related
+environment variable. Do not invent one; inspect the installed declarations
+and the Datadog v5 behavior for the desired AppSec configuration. The same
+applies to the two cloud-payload-tagging variables and
+`AWS_LAMBDA_EXEC_WRAPPER`, for which this wrapper has no same-named prop.
+
+If a per-function override is intentional, apply it only after instrumentation:
+
+```typescript
+datadog.addLambdaFunctions([handler]);
+handler.addEnvironment('DD_LOG_LEVEL', 'debug');
+```
+
+An override of `DD_TAGS` at that point replaces all tags generated by the
+construct, including Git metadata added through `addGitCommitMetadata()`.
+`addLambdaFunctions()` validates the complete batch before changing any of its
+functions. The validation covers the underlying CDK `Function` environment,
+including `SingletonFunction` and values added with `addEnvironment()`; it
+does not inspect `CfnFunction` escape-hatch overrides.
+
+Source-code integration is enabled by default and can change generated
+`DD_TAGS`. For snapshot tests that must disable it, set this exact context key
+on the test `App` to either boolean `false` or string `"false"`:
+
+```typescript
+const app = new App({
+  context: {
+    '@rio-cloud/cdk-v2-constructs:enableSourceCodeIntegration': false,
+  },
+});
+```
+
+Do not substitute the unrelated `datadog-cdk-constructs-v2` context key. Layer
+version props remain required; choose versions compatible with the installed
+Datadog Lambda Node and extension layer releases rather than copying stale
+values from tests.
+
+### Pipeline license-checker prerequisite
+
+Before upgrading a project that uses the Team Transport pipeline, add
+`@rio-cloud/rio-license-checker` as a direct dev dependency and commit the
+corresponding lockfile:
+
+```bash
+npm install --save-dev @rio-cloud/rio-license-checker
+```
+
+The generated buildspecs call `npx rio-license-checker` after `npm ci`; the
+construct no longer supplies this package transitively. Add it to the package
+whose `npm ci` precedes the call:
+
+| Generated pipeline feature | Workspace in which the checker is invoked | Package that needs the dev dependency |
+| --- | --- | --- |
+| Infrastructure synth | `infrastructure/` | `infrastructure/package.json` |
+| `gradleBuild` | repository root | root `package.json` |
+| `npmBuild` | repository root | root `package.json` |
+
+If a project enables more than one of these generated build paths, make the
+checker available in each corresponding workspace. A custom main/branch or
+vulnerability buildspec is loaded instead of the generated one, so inspect
+that file separately for its own license-check command and install location.
+The package's release notes link to the internal [RIO license-check
+guidance](https://confluence.collaboration-man.com/spaces/RIOSHIPPER/pages/448924008/License+Checks).
+
+### Contribution imports and package dependencies
+
+Contribution constructs are no longer exported from the package root. Use the
+owner-level subpaths that are present in the installed package's `exports` map:
+
+| Owner | Public import path in `9.0.0` |
+| --- | --- |
+| Team Claid | `@rio-cloud/cdk-v2-constructs/contributions/team-claid` |
+| Team Outbound Order Book | `@rio-cloud/cdk-v2-constructs/contributions/team-outbound-order-book` |
+| Team Shipper Inbound Blue | `@rio-cloud/cdk-v2-constructs/contributions/team-shipper-inbound-blue` |
+| Smart Route / GitLab Runner | `@rio-cloud/cdk-v2-constructs/contributions/smart-route` |
+| Team Transport | `@rio-cloud/cdk-v2-constructs/contributions/team-transport` |
+| CoP Frontend | `@rio-cloud/cdk-v2-constructs/contributions/cop-frontend` |
+
+For example, change a root import while keeping the named imports:
+
+```diff
+-import { PipelineStack, PipelineType } from '@rio-cloud/cdk-v2-constructs';
++import { PipelineStack, PipelineType } from '@rio-cloud/cdk-v2-constructs/contributions/team-transport';
+```
+
+Team Transport was renamed from `team-transport-two` to `team-transport`.
+Import its pipeline, Datadog, and synthetics constructs from the single
+owner-level path above. Do not infer additional public subpaths from the
+source directory layout; the installed `package.json` `exports` map is the
+authority.
+
+GitLab Runner consumers must also install
+`@pepperize/cdk-autoscaling-gitlab-runner` as a direct project dependency:
+
+```bash
+npm install @pepperize/cdk-autoscaling-gitlab-runner
+```
+
+It is an optional peer dependency of this package, not a regular dependency
+that a consuming project can obtain transitively. This additional dependency
+is required only by projects importing the Smart Route GitLab Runner
+constructs.
+
+### TypeScript resolver required for contribution subpaths
+
+The contribution imports depend on Node package export maps. A legacy
+`moduleResolution: "node"` configuration does not resolve these imports
+reliably. Use a resolver that honors `exports` and keep the `module` and
+`moduleResolution` settings compatible. For example, a CommonJS-oriented
+project can use:
+
+```json
+{
+  "compilerOptions": {
+    "module": "Node16",
+    "moduleResolution": "node16"
+  }
+}
+```
+
+A bundler-managed project can instead use the corresponding `bundler`
+resolution mode with its existing bundler-compatible module setting. Do not
+change only `moduleResolution` in a configuration whose `module` setting is
+incompatible; preserve the consuming project's module model and verify it with
+the project's typecheck and synth commands.
+
+### Team Transport CodeBuild runtime options
+
+This is an alpha.4 pipeline feature rather than a breaking migration, but it
+is relevant when updating pipeline code. Generated main, branch, and
+vulnerability buildspecs continue to use Node.js 24 by default. To require an
+exact toolchain, set `codeBuildOptions.nodejsVersion` and/or
+`codeBuildOptions.npmVersion` to an exact `major.minor.patch` value. The
+generated install phase checks the selected versions before installing project
+dependencies; it does not install npm globally. These options affect only
+generated buildspecs. A custom buildspec supplied through
+`partialBuildSpecPath` or `vulnerabilityPartialBuildSpecPath` is responsible
+for its own runtime and version checks.
+
+### CloudFront certificates added in v9
+
+`CloudFrontCertificate` is exported from the package root. It creates a
+DNS-validated ACM certificate in `us-east-1` for a stack in any region and
+requires a public Route 53 hosted zone in the same account:
+
+```typescript
+import { CloudFrontCertificate } from '@rio-cloud/cdk-v2-constructs';
+import { Distribution } from 'aws-cdk-lib/aws-cloudfront';
+
+const certificate = new CloudFrontCertificate(this, 'CloudFrontCertificate', {
+  domainName: 'www.example.com',
+  hostedZone,
+});
+
+new Distribution(this, 'Distribution', {
+  certificate: certificate.certificate,
+  // ...other required Distribution props
+});
+```
+
+Use `certificate` (`acm.ICertificate`) when another CDK construct accepts a
+certificate. Use `certificateArn` only for integrations that require a string
+ARN. Changing the domain or hosted zone replaces the certificate; validation
+CNAME records are retained for renewal.
+
 ## Usage Guidance
 
 ### General

package/package.json

@@ -15,7 +15,7 @@
   ],
   "main": "lib/index.js",
   "license": "Apache-2.0",
-  "version": "9.0.0-alpha.4",
+  "version": "9.0.0-alpha.6",
   "types": "lib/index.d.ts",
   "stability": "stable",
   "exports": {
@@ -110,7 +110,7 @@
     "esbuild": "0.28.2",
     "jsii": "5.9.55",
     "jsii-diff": "1.141.0",
-    "jsii-docgen": "10.12.6",
+    "jsii-docgen": "10.12.7",
     "tmp": "^0.2.3",
     "ts-node": "^10.9.2",
     "typescript": "~5.6.3",

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "9.0.0-alpha.4"
+  "version": "9.0.0-alpha.6"
 }