@btc-embedded/cdk-extensions 0.22.15 → 0.22.17

package/API.md

@@ -2489,6 +2489,154 @@ Whether termination protection is enabled for this stack.
 ---
 
 
+### AuroraPostgresCluster <a name="AuroraPostgresCluster" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster"></a>
+
+Provisions an Aurora PostgreSQL Serverless v2 cluster and exports connection metadata.
+
+Exports:
+- `aurora-postgres-db:secret-arn`
+- `aurora-postgres-db:credentials-secret-arn`
+- `aurora-postgres-db:cluster-endpoint`
+- `aurora-postgres-db:security-group-id`
+- `aurora-postgres-db:tunnel-instance-id` (only when tunnel host is enabled)
+
+#### Initializers <a name="Initializers" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer"></a>
+
+```typescript
+import { AuroraPostgresCluster } from '@btc-embedded/cdk-extensions'
+
+new AuroraPostgresCluster(scope: Construct, id: string, props: AuroraPostgresClusterProps)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.props">props</a></code> | <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps">AuroraPostgresClusterProps</a></code> | *No description.* |
+
+---
+
+##### `scope`<sup>Required</sup> <a name="scope" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+---
+
+##### `id`<sup>Required</sup> <a name="id" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.id"></a>
+
+- *Type:* string
+
+---
+
+##### `props`<sup>Required</sup> <a name="props" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.Initializer.parameter.props"></a>
+
+- *Type:* <a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps">AuroraPostgresClusterProps</a>
+
+---
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.toString">toString</a></code> | Returns a string representation of this construct. |
+
+---
+
+##### `toString` <a name="toString" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.toString"></a>
+
+```typescript
+public toString(): string
+```
+
+Returns a string representation of this construct.
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
+
+---
+
+##### `isConstruct` <a name="isConstruct" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.isConstruct"></a>
+
+```typescript
+import { AuroraPostgresCluster } from '@btc-embedded/cdk-extensions'
+
+AuroraPostgresCluster.isConstruct(x: any)
+```
+
+Checks if `x` is a construct.
+
+Use this method instead of `instanceof` to properly detect `Construct`
+instances, even when the construct library is symlinked.
+
+Explanation: in JavaScript, multiple copies of the `constructs` library on
+disk are seen as independent, completely different libraries. As a
+consequence, the class `Construct` in each copy of the `constructs` library
+is seen as a different class, and an instance of one class will not test as
+`instanceof` the other class. `npm install` will not create installations
+like this, but users may manually symlink construct libraries together or
+use a monorepo tool: in those cases, multiple copies of the `constructs`
+library can be accidentally installed, and `instanceof` will behave
+unpredictably. It is safest to avoid using `instanceof`, and using
+this type-testing method instead.
+
+###### `x`<sup>Required</sup> <a name="x" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.isConstruct.parameter.x"></a>
+
+- *Type:* any
+
+Any object.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.cluster">cluster</a></code> | <code>aws-cdk-lib.aws_rds.DatabaseCluster</code> | Aurora database cluster. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.securityGroup">securityGroup</a></code> | <code>aws-cdk-lib.aws_ec2.SecurityGroup</code> | Security group attached to the Aurora cluster. |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `cluster`<sup>Required</sup> <a name="cluster" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.cluster"></a>
+
+```typescript
+public readonly cluster: DatabaseCluster;
+```
+
+- *Type:* aws-cdk-lib.aws_rds.DatabaseCluster
+
+Aurora database cluster.
+
+---
+
+##### `securityGroup`<sup>Required</sup> <a name="securityGroup" id="@btc-embedded/cdk-extensions.AuroraPostgresCluster.property.securityGroup"></a>
+
+```typescript
+public readonly securityGroup: SecurityGroup;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.SecurityGroup
+
+Security group attached to the Aurora cluster.
+
+---
+
+
 ### BTCLogGroup <a name="BTCLogGroup" id="@btc-embedded/cdk-extensions.BTCLogGroup"></a>
 
 A log group with sensible defaults.
@@ -9233,6 +9381,243 @@ public readonly secret: ISecret;
 
 ---
 
+### AuroraPostgresClusterOverrides <a name="AuroraPostgresClusterOverrides" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides"></a>
+
+Supported override options for Aurora cluster tuning.
+
+#### Initializer <a name="Initializer" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.Initializer"></a>
+
+```typescript
+import { AuroraPostgresClusterOverrides } from '@btc-embedded/cdk-extensions'
+
+const auroraPostgresClusterOverrides: AuroraPostgresClusterOverrides = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.clusterIdentifier">clusterIdentifier</a></code> | <code>string</code> | Optional DB cluster identifier. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.serverlessV2MaxCapacity">serverlessV2MaxCapacity</a></code> | <code>number</code> | Maximum Aurora Serverless v2 capacity. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.serverlessV2MinCapacity">serverlessV2MinCapacity</a></code> | <code>number</code> | Minimum Aurora Serverless v2 capacity. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.storageEncrypted">storageEncrypted</a></code> | <code>boolean</code> | Whether storage encryption should be enabled. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.vpcSubnets">vpcSubnets</a></code> | <code>aws-cdk-lib.aws_ec2.SubnetSelection</code> | Subnets used for cluster instances. |
+
+---
+
+##### `clusterIdentifier`<sup>Optional</sup> <a name="clusterIdentifier" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.clusterIdentifier"></a>
+
+```typescript
+public readonly clusterIdentifier: string;
+```
+
+- *Type:* string
+- *Default:* generated by CDK
+
+Optional DB cluster identifier.
+
+---
+
+##### `serverlessV2MaxCapacity`<sup>Optional</sup> <a name="serverlessV2MaxCapacity" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.serverlessV2MaxCapacity"></a>
+
+```typescript
+public readonly serverlessV2MaxCapacity: number;
+```
+
+- *Type:* number
+- *Default:* 1
+
+Maximum Aurora Serverless v2 capacity.
+
+---
+
+##### `serverlessV2MinCapacity`<sup>Optional</sup> <a name="serverlessV2MinCapacity" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.serverlessV2MinCapacity"></a>
+
+```typescript
+public readonly serverlessV2MinCapacity: number;
+```
+
+- *Type:* number
+- *Default:* 0
+
+Minimum Aurora Serverless v2 capacity.
+
+---
+
+##### `storageEncrypted`<sup>Optional</sup> <a name="storageEncrypted" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.storageEncrypted"></a>
+
+```typescript
+public readonly storageEncrypted: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Whether storage encryption should be enabled.
+
+---
+
+##### `vpcSubnets`<sup>Optional</sup> <a name="vpcSubnets" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides.property.vpcSubnets"></a>
+
+```typescript
+public readonly vpcSubnets: SubnetSelection;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.SubnetSelection
+- *Default:* SubnetType.PRIVATE_WITH_EGRESS
+
+Subnets used for cluster instances.
+
+---
+
+### AuroraPostgresClusterProps <a name="AuroraPostgresClusterProps" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps"></a>
+
+Properties for {@link AuroraPostgresCluster}.
+
+#### Initializer <a name="Initializer" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.Initializer"></a>
+
+```typescript
+import { AuroraPostgresClusterProps } from '@btc-embedded/cdk-extensions'
+
+const auroraPostgresClusterProps: AuroraPostgresClusterProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.instanceName">instanceName</a></code> | <code>string</code> | Instance name used for the optional tunnel host. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.vpc">vpc</a></code> | <code>aws-cdk-lib.aws_ec2.IVpc</code> | VPC to deploy the Aurora cluster into. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.clusterProps">clusterProps</a></code> | <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides">AuroraPostgresClusterOverrides</a></code> | Optional Aurora cluster overrides. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.tunnelHost">tunnelHost</a></code> | <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps">AuroraPostgresTunnelHostProps</a></code> | Optional settings for the tunnel host. |
+
+---
+
+##### `instanceName`<sup>Required</sup> <a name="instanceName" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.instanceName"></a>
+
+```typescript
+public readonly instanceName: string;
+```
+
+- *Type:* string
+
+Instance name used for the optional tunnel host.
+
+---
+
+##### `vpc`<sup>Required</sup> <a name="vpc" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.vpc"></a>
+
+```typescript
+public readonly vpc: IVpc;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.IVpc
+
+VPC to deploy the Aurora cluster into.
+
+---
+
+##### `clusterProps`<sup>Optional</sup> <a name="clusterProps" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.clusterProps"></a>
+
+```typescript
+public readonly clusterProps: AuroraPostgresClusterOverrides;
+```
+
+- *Type:* <a href="#@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides">AuroraPostgresClusterOverrides</a>
+
+Optional Aurora cluster overrides.
+
+---
+
+##### `tunnelHost`<sup>Optional</sup> <a name="tunnelHost" id="@btc-embedded/cdk-extensions.AuroraPostgresClusterProps.property.tunnelHost"></a>
+
+```typescript
+public readonly tunnelHost: AuroraPostgresTunnelHostProps;
+```
+
+- *Type:* <a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps">AuroraPostgresTunnelHostProps</a>
+
+Optional settings for the tunnel host.
+
+---
+
+### AuroraPostgresTunnelHostProps <a name="AuroraPostgresTunnelHostProps" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps"></a>
+
+Optional settings for the SSM-managed tunnel host used by `catnip pg-tunnel`.
+
+#### Initializer <a name="Initializer" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.Initializer"></a>
+
+```typescript
+import { AuroraPostgresTunnelHostProps } from '@btc-embedded/cdk-extensions'
+
+const auroraPostgresTunnelHostProps: AuroraPostgresTunnelHostProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.createSsmVpcEndpoints">createSsmVpcEndpoints</a></code> | <code>boolean</code> | Whether to create SSM interface endpoints in the VPC (ssm, ssmmessages, ec2messages). |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.enabled">enabled</a></code> | <code>boolean</code> | Whether a dedicated EC2 tunnel host should be provisioned. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.instanceType">instanceType</a></code> | <code>aws-cdk-lib.aws_ec2.InstanceType</code> | Instance type used for the tunnel host. |
+| <code><a href="#@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.subnetType">subnetType</a></code> | <code>aws-cdk-lib.aws_ec2.SubnetType</code> | Subnet type where the tunnel host will be placed. |
+
+---
+
+##### `createSsmVpcEndpoints`<sup>Optional</sup> <a name="createSsmVpcEndpoints" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.createSsmVpcEndpoints"></a>
+
+```typescript
+public readonly createSsmVpcEndpoints: boolean;
+```
+
+- *Type:* boolean
+- *Default:* false
+
+Whether to create SSM interface endpoints in the VPC (ssm, ssmmessages, ec2messages).
+
+Useful for environments without NAT internet egress.
+
+---
+
+##### `enabled`<sup>Optional</sup> <a name="enabled" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.enabled"></a>
+
+```typescript
+public readonly enabled: boolean;
+```
+
+- *Type:* boolean
+- *Default:* false
+
+Whether a dedicated EC2 tunnel host should be provisioned.
+
+---
+
+##### `instanceType`<sup>Optional</sup> <a name="instanceType" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.instanceType"></a>
+
+```typescript
+public readonly instanceType: InstanceType;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.InstanceType
+- *Default:* t3.nano
+
+Instance type used for the tunnel host.
+
+---
+
+##### `subnetType`<sup>Optional</sup> <a name="subnetType" id="@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps.property.subnetType"></a>
+
+```typescript
+public readonly subnetType: SubnetType;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.SubnetType
+- *Default:* SubnetType.PRIVATE_WITH_EGRESS
+
+Subnet type where the tunnel host will be placed.
+
+---
+
 ### BTCLogGroupLookupOptions <a name="BTCLogGroupLookupOptions" id="@btc-embedded/cdk-extensions.BTCLogGroupLookupOptions"></a>
 
 #### Initializer <a name="Initializer" id="@btc-embedded/cdk-extensions.BTCLogGroupLookupOptions.Initializer"></a>

package/CHANGELOG.md

@@ -1,4 +1,19 @@
 
+## [0.22.16](https://github.com/btc-embedded/cdk-extensions/compare/v0.22.15...v0.22.16) (2026-02-27)
+
+
+### Features
+
+* **catnip:** add pg-tunnel command and Aurora tunnel host support ([9d6856b](https://github.com/btc-embedded/cdk-extensions/commit/9d6856bfebeedc75c9435e2d8f3bd6cc9d01dd7a))
+* **catnip:** use sdk-backed ssm tunnel lifecycle for pg-tunnel ([23fcc2a](https://github.com/btc-embedded/cdk-extensions/commit/23fcc2a3da487ed75342f5e0147d1a2093db55a1))
+
+
+### Bug Fixes
+
+* **catnip:** harden pg-tunnel runtime lifecycle and portability ([f15985b](https://github.com/btc-embedded/cdk-extensions/commit/f15985b9f999576e011727acf9bcc2befb61d187))
+
+## [0.22.15](https://github.com/btc-embedded/cdk-extensions/compare/v0.22.14...v0.22.15) (2026-02-27)
+
 ## [0.22.14](https://github.com/btc-embedded/cdk-extensions/compare/v0.22.13...v0.22.14) (2026-02-26)
 
 

package/README.md

@@ -139,6 +139,38 @@ Options:
 - `--output <token|json>` — print token only, or full response JSON (default: `token`)
   - `token` output is the `access_token`
 
+#### pg-tunnel
+
+Open a secure Session Manager tunnel to Aurora PostgreSQL and launch a local client.
+
+Usage:
+
+```bash
+catnip pg-tunnel --stack-name my-stack
+catnip pg-tunnel --stack-name my-stack --exec "psql"
+catnip pg-tunnel --stack-name my-stack --database app
+catnip pg-tunnel --stack-name my-stack --no-auto-launch
+catnip pg-tunnel --stage prod
+```
+
+Options:
+- `--stack-name <name>` — stack where the Aurora cluster is deployed (typically the base platform stack; optional when auto-discovery works)
+- `--stage <name>` — stage filter used during stack auto-discovery
+- `--local-port <port>` — preferred local port (default: `5432`)
+- `--database <name>` — overrides `PGDATABASE` for launched client/shell
+- `--exec <command>` — explicit command to run after tunnel starts
+- `--no-auto-launch` — keep tunnel attached without launching a client/shell
+- `--tunnel-instance-id <id>` — fallback EC2 instance ID when stack export is missing
+
+Database selection behavior:
+- if `--database` is provided, that value is used
+- if omitted, `catnip` infers database names from deployed ECS service task definitions (`POSTGRES_DATABASE`)
+- if exactly one database is inferred, it is applied as `PGDATABASE`
+- if multiple databases are inferred, they are printed with source stack/service and `PGDATABASE` remains unset
+
+Prerequisite:
+- `session-manager-plugin` must be installed and available in `PATH`
+
 ## Documentation
 
 - [API Reference](./API.md)