@ashishpandeyone/cdk-lambda-web-function 0.1.11 → 0.1.13

package/API.md

@@ -64,6 +64,7 @@ new NodejsWebFunction(scope: Construct, id: string, props: NodejsWebFunctionProp
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addPermission">addPermission</a></code> | Allows a principal in another account, an AWS service or an organization to call the function's endpoints, through the function's resource policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addToRolePolicy">addToRolePolicy</a></code> | Adds a statement to the execution role's policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.encryptionKeyPolicyStatement">encryptionKeyPolicyStatement</a></code> | The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets). |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement">logEncryptionKeyPolicyStatement</a></code> | The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`). |
 
 ---
 
@@ -363,6 +364,25 @@ The key-policy statement Lambda needs to start this function's environments with
 It's added to `encryptionKey` when the key is defined in this app. Add it to every replica of a multi-Region key
 yourself: replicas don't share their primary's policy.
 
+##### `logEncryptionKeyPolicyStatement` <a name="logEncryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement"></a>
+
+```typescript
+public logEncryptionKeyPolicyStatement(region: string): PolicyStatement
+```
+
+The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`).
+
+It's added to `logEncryptionKey` for the key's own region when the key is defined in this app. Add it to the
+replica in every other region the function serves from yourself: replicas don't share their primary's policy.
+
+###### `region`<sup>Required</sup> <a name="region" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement.parameter.region"></a>
+
+- *Type:* string
+
+the region of the key or replica.
+
+---
+
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
 | **Name** | **Description** |
@@ -542,6 +562,7 @@ Imports an existing Web Function in this stack's account and region by its name.
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.revisionId">revisionId</a></code> | <code>string</code> | The ID of the current revision. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.role">role</a></code> | <code>aws-cdk-lib.aws_iam.IRole</code> | The execution role. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's revisions, if any. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's log groups, if any. |
 
 ---
 
@@ -727,6 +748,18 @@ The customer managed key of the function's revisions, if any.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's log groups, if any.
+
+---
+
 #### Constants <a name="Constants" id="Constants"></a>
 
 | **Name** | **Type** | **Description** |
@@ -814,6 +847,7 @@ new WebFunction(scope: Construct, id: string, props: WebFunctionProps)
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.addPermission">addPermission</a></code> | Allows a principal in another account, an AWS service or an organization to call the function's endpoints, through the function's resource policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.addToRolePolicy">addToRolePolicy</a></code> | Adds a statement to the execution role's policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.encryptionKeyPolicyStatement">encryptionKeyPolicyStatement</a></code> | The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets). |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement">logEncryptionKeyPolicyStatement</a></code> | The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`). |
 
 ---
 
@@ -1113,6 +1147,25 @@ The key-policy statement Lambda needs to start this function's environments with
 It's added to `encryptionKey` when the key is defined in this app. Add it to every replica of a multi-Region key
 yourself: replicas don't share their primary's policy.
 
+##### `logEncryptionKeyPolicyStatement` <a name="logEncryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement"></a>
+
+```typescript
+public logEncryptionKeyPolicyStatement(region: string): PolicyStatement
+```
+
+The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`).
+
+It's added to `logEncryptionKey` for the key's own region when the key is defined in this app. Add it to the
+replica in every other region the function serves from yourself: replicas don't share their primary's policy.
+
+###### `region`<sup>Required</sup> <a name="region" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement.parameter.region"></a>
+
+- *Type:* string
+
+the region of the key or replica.
+
+---
+
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
 | **Name** | **Description** |
@@ -1292,6 +1345,7 @@ Imports an existing Web Function in this stack's account and region by its name.
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.revisionId">revisionId</a></code> | <code>string</code> | The ID of the current revision. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.role">role</a></code> | <code>aws-cdk-lib.aws_iam.IRole</code> | The execution role. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's revisions, if any. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's log groups, if any. |
 
 ---
 
@@ -1477,6 +1531,18 @@ The customer managed key of the function's revisions, if any.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's log groups, if any.
+
+---
+
 #### Constants <a name="Constants" id="Constants"></a>
 
 | **Name** | **Type** | **Description** |
@@ -3018,6 +3084,7 @@ const nodejsWebFunctionProps: NodejsWebFunctionProps = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -3121,6 +3188,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRemovalPolicy"></a>
 
 ```typescript
@@ -3688,6 +3775,7 @@ const webFunctionOptions: WebFunctionOptions = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -3786,6 +3874,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRemovalPolicy"></a>
 
 ```typescript
@@ -4469,6 +4577,7 @@ const webFunctionProps: WebFunctionProps = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -4570,6 +4679,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRemovalPolicy"></a>
 
 ```typescript

package/README.md

@@ -314,6 +314,35 @@ new kms.CfnReplicaKey(replicaStack, 'KeyReplica', {
 - **Changing the key creates a new revision.** Earlier revisions keep their key, including the ones kept as rollback targets (`revisionRetention`). Keep the old key enabled while any of them might serve traffic again.
 - **Disabling the key, or removing Lambda's access, stops new execution environments from starting.** Running ones keep their decrypted copy for a while, so this doesn't contain traffic immediately.
 
+Log groups are encrypted by CloudWatch Logs. To use your own key for them too, pass `logEncryptionKey`. It can be the same key:
+
+```ts
+declare const key: kms.Key;              // multiRegion: true, in the function's region
+declare const replica: kms.CfnReplicaKey; // in us-east-1
+
+const api = new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('build'),
+  authType: WebFunctionAuthType.AWS_IAM,
+  endpoint: { endpointType: WebFunctionEndpointType.PER_REGION, regions: ['us-east-1'] },
+  logEncryptionKey: key,
+});
+
+// The replica's policy also allows CloudWatch Logs in its region, for this function's groups.
+replica.keyPolicy = new iam.PolicyDocument({
+  statements: [
+    new iam.PolicyStatement({ principals: [new iam.AccountRootPrincipal()], actions: ['kms:*'], resources: ['*'] }),
+    api.logEncryptionKeyPolicyStatement('us-east-1'),
+  ],
+});
+```
+
+- **CloudWatch Logs only uses a key in the group's own region.** The groups in the key's region use the key. Groups in other regions use the multi-Region key's replica there, which has the same key ID. With a single-Region key, synthesis fails as soon as a group is in another region.
+- **A key defined in your app gets CloudWatch Logs' statement for its own region.** It allows `logs.<region>.amazonaws.com` to use the key for this function's log groups only. Add `logEncryptionKeyPolicyStatement(region)` to each replica's policy, and to an imported key's.
+- **The construct's provider sets the key on each group, and needs `kms:DescribeKey` on it to do so.** The construct grants that through IAM, which a key's default policy allows. If a key's policy doesn't delegate to IAM, allow the provider's role in the key policy.
+- **Adding or changing the key encrypts new events only.** Existing events stay encrypted with the key they were written with. Removing `logEncryptionKey` sets the groups back to CloudWatch Logs' encryption.
+- **Retained log groups need their key to stay readable.** The default `logRemovalPolicy` is `RETAIN`, so keep the key while you keep the logs.
+
 ### Defaults for every function (property injection)
 
 To give every function under a scope the same defaults, register a property injector for `WebFunction.PROPERTY_INJECTION_ID`, as you would for aws-cdk-lib's constructs. For example, a team's log retention: