feat(apigateway): add VPC and VPC endpoint identity fields to AccessLogField
- 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
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