aws / aws/aws-cdk

feat(apigateway): add VPC and VPC endpoint identity fields to AccessLogField

Open Beginner friendly
#38,302 1 comment 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-ec2 feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
1d 19h
Merged PRs (30d)
71

Description

### Describe the feature

Add two static methods to `AccessLogField` (`packages/aws-cdk-lib/aws-apigateway/lib/access-log.ts`) exposing the VPC-related `$context.identity` variables that API Gateway supports for access logging but the L2 construct does not:

- `contextIdentityVpcId()` → `$context.identity.vpcId`
- `contextIdentityVpceId()` → `$context.identity.vpceId`

### Use Case

Private REST APIs are reached through interface VPC endpoints. When multiple VPCs / VPC endpoints are associated with a private API, the only way to attribute a request to its originating VPC or VPC endpoint is the `$context.identity.vpcId` / `$context.identity.vpceId` access-log context variables. These are essential for auditing, per-consumer traffic attribution, and debugging cross-account private API access.

Both variables are documented by API Gateway ([Variables for access logging](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-variables-for-access-logging.html)): `$context.identity.vpceId` is populated only for private APIs; `$context.identity.vpcId` for the requesting VPC.

`AccessLogField` already exposes the sibling identity variables (`contextIdentitySourceIp()`, `contextIdentityUserArn()`, `contextIdentityAccountId()`, etc.), so these two are a natural, consistent addition.

### Proposed Solution

Add to the `AccessLogField` class:

```ts
/**
* The VPC ID of the VPC making the request to the API Gateway endpoint.
*/
public static contextIdentityVpcId(): string {
return '$context.identity.vpcId';
}

/**
* The VPC endpoint ID of the VPC endpoint making the request to the API Gateway endpoint.
* Present only for private APIs.
*/
public static contextIdentityVpceId(): string {
return '$context.identity.vpceId';
}
```

Consumed the same way as existing fields:

```ts
apigateway.AccessLogFormat.custom(JSON.stringify({
vpcId: apigateway.AccessLogField.contextIdentityVpcId(),
vpceId: apigateway.AccessLogField.contextIdentityVpceId(),
}));
```

### Other Information

Today this requires a raw string workaround, since `AccessLogFormat.custom()` takes a string and there is no field helper:

```ts
apigateway.AccessLogFormat.custom(JSON.stringify({
vpceId: '$context.identity.vpceId', // no AccessLogField helper exists
}));
```

Naming follows the existing `contextIdentity*` convention in the class.

### Acknowledgements

- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

2.258.1

### AWS CDK CLI version

2.1129.0 (build 629ca49)

### Environment details (OS name and version, etc.)

- OS: Amazon Linux 2 (Karoo), kernel 5.10.259 x86_64 - Node.js: v26.0.0 - npm: 11.12.1

Contributor guide

Open the contributing guide

Research direction

Start in packages/aws-cdk-lib/aws-apigateway/lib/access-log.ts and review the existing contextIdentity* methods on AccessLogField for naming and placement. Add the two VPC identity helpers described in the issue, ensuring they return the documented context variables and can be used with AccessLogFormat.custom().

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
api
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.