Skip to content

Commit

Permalink
cleaning up the api and updating README
Browse files Browse the repository at this point in the history
  • Loading branch information
@corymhall
corymhall committed Oct 29, 2024
1 parent c7271f7 commit bfa47d5
Show file tree
Hide file tree
Showing 4 changed files with 168 additions and 148 deletions.
141 changes: 83 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
# Pulumi CDK Adapter (preview)

The Pulumi CDK Adapter is a library that enables [Pulumi](https://github.com/pulumi/pulumi) programs to use [AWS CDK](https://github.com/aws/aws-cdk) constructs.
The Pulumi CDK Adapter is a library that enables
[Pulumi](https://github.com/pulumi/pulumi) programs to use [AWS
CDK](https://github.com/aws/aws-cdk) constructs.

The adapter allows writing AWS CDK code as part of an AWS CDK Stack inside a Pulumi program, and having the resulting AWS resources be deployed and managed via Pulumi. Outputs of resources defined in a Pulumi program can be passed into AWS CDK Constructs, and outputs from AWS CDK stacks can be used as inputs to other Pulumi resources.
The adapter allows writing AWS CDK code as part of an AWS CDK Stack inside a
Pulumi program, and having the resulting AWS resources be deployed and managed
via Pulumi. Outputs of resources defined in a Pulumi program can be passed
into AWS CDK Constructs, and outputs from AWS CDK stacks can be used as inputs
to other Pulumi resources.

> Note: Currently, the Pulumi CDK Adapter preview is available only for TypeScript/JavaScript users.
> Note: Currently, the Pulumi CDK Adapter preview is available only for
> TypeScript/JavaScript users.
For example, to construct an [AWS AppRunner `Service` resource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-apprunner-alpha-readme.html) from within a Pulumi program, and export the resulting service's URL as as Pulumi Stack Output you write the following:
For example, to construct an [AWS AppRunner `Service`
resource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-apprunner-alpha-readme.html)
from within a Pulumi program, and export the resulting service's URL as as
Pulumi Stack Output you write the following:

```ts
import * as pulumi from '@pulumi/pulumi';
Expand All @@ -27,18 +37,21 @@ class AppRunnerStack extends pulumicdk.Stack {
});

this.url = this.asOutput(service.serviceUrl);

this.synth();
}
}

const stack = new AppRunnerStack('teststack');
export const url = stack.url;
const app = new pulumicdk.App('app', (scope: pulumicdk.App): pulumicdk.AppOutputs => {
const stack = new AppRunnerStack('teststack');
return {
url: stack.url,
};
});
export const url = app.outputs['url'];
```

And then deploy with `pulumi update`:

```
```console
> pulumi up

Updating (dev)
Expand All @@ -60,7 +73,7 @@ Resources:

And curl the endpoint:

```
```console
> curl https://$(pulumi stack output url)

______ __ __ __ _ __
Expand All @@ -81,99 +94,111 @@ Try the workshop at https://apprunnerworkshop.com
Read the docs at https://docs.aws.amazon.com/apprunner
```

## Getting Started

### Bootstrapping

AWS CDK requires that your AWS account and target region are "bootstrapped" for use with CDK, so in order to use CDK on Pulumi, you'll need to do that first. We recommend using the latest bootstrap template (v2, as of this writing). [See the AWS documentation](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) for details. (Note that resources deployed with Pulumi on CDK are deployed and managed with Pulumi, not CloudFormation; the bootstrapping step is required by CDK for additional runtime support.)

## API

### `Stack`
### `App`

A Construct that represents an AWS CDK stack deployed with Pulumi. In order to deploy a CDK stack with Pulumi, it must derive from this class. The `synth` method must be called after all CDK resources have been defined in order to deploy the stack (usually, this is done as the last line of the subclass's constructor).
A Pulumi CDK App component. This is the entrypoint to your Pulumi CDK application.
In order to deploy a CDK application with Pulumi, you must start with this class.

#### `constructor`

Create and register an AWS CDK stack deployed with Pulumi.
Create and register an AWS CDK app deployed with Pulumi.

```ts
constructor(name: string, options?: StackOptions)
constructor(id: string, createFunc: (scope: App) => void | AppOutputs, props?: AppResourceOptions)
```

Parameters:
* `name`: The _unique_ name of the resource.
* `options`: A bag of options that control this resource's behavior.

### `urn`

The URN of the underlying Pulumi component.
* `id`: The _unique_ name of the app
* `createFunc`: A callback function where all CDK Stacks must be created
* `options`: A bag of options that control the resource's behavior

#### `outputs`

The collection of outputs from the AWS CDK Stack represented as Pulumi Outputs. Each `CfnOutput` defined in the AWS CDK Stack will populate a value in the outputs.
The collection of outputs from the AWS CDK Stack represented as Pulumi Outputs.
Each `CfnOutput` defined in the AWS CDK Stack will populate a value in the
outputs.

```ts
outputs: { [outputId: string]: pulumi.Output<any> }
```

#### `synth`

Finalize the stack and deploy its resources.

```ts
protected synth()
```

#### `asOutput`

Convert a CDK value to a Pulumi output.
#### `AppResourceOptions`

Parameters:
* `v`: A CDK value.
Options specific to the App Component

```ts
asOutput<T>(v: T): pulumi.Output<T>
```

### `StackOptions`

Options specific to the Stack component.

```ts
interface StackOptions
interface AppResourceOptions
```

#### `remapCloudControlResource`

This optional method can be implemented to define a mapping to override and/or provide an implementation for a CloudFormation resource type that is not (yet) implemented in the AWS Cloud Control API (and thus not yet available in the Pulumi AWS Native provider). Pulumi code can override this method to provide a custom mapping of CloudFormation elements and their properties into Pulumi CustomResources, commonly by using the AWS Classic provider to implement the missing resource.
This optional method can be implemented to define a mapping to override and/or
provide an implementation for a CloudFormation resource type that is not (yet)
implemented in the AWS Cloud Control API (and thus not yet available in the
Pulumi AWS Native provider). Pulumi code can override this method to provide a
custom mapping of CloudFormation elements and their properties into Pulumi
CustomResources, commonly by using the AWS Classic provider to implement the
missing resource.

```ts
remapCloudControlResource(element: CfnElement, logicalId: string, typeName: string, props: any, options: pulumi.ResourceOptions): { [key: string]: pulumi.CustomResource } | undefined
remapCloudControlResource(logicalId: string, typeName: string, props: any, options: pulumi.ResourceOptions): { [key: string]: pulumi.CustomResource } | undefined
```

Parameters:
* `element`: The full CloudFormation element object being mapped.
* `logicalId`: The logical ID of the resource being mapped.
* `typeName`: The CloudFormation type name of the resource being mapped.
* `props`: The bag of input properties to the CloudFormation resource being mapped.
* `options`: The set of Pulumi ResourceOptions to apply to the resource being mapped.

Returns an object containing one or more logical IDs mapped to Pulumi resources that must be created to implement the mapped CloudFormation resource, or else undefined if no mapping is implemented.
Returns an object containing one or more logical IDs mapped to Pulumi resources
that must be created to implement the mapped CloudFormation resource, or else
undefined if no mapping is implemented.

#### `appId`

This is a unique identifier for the application. It will be used in the names of the
staging resources created for the application. This `appId` should be unique across apps.

### `Stack`

A Construct that represents an AWS CDK stack deployed with Pulumi. In order to
deploy a CDK stack with Pulumi, it must derive from this class.

#### `create`
#### `constructor`

Create and register an AWS CDK stack deployed with Pulumi.

```ts
create(name: string, ctor: typeof Stack, opts?: pulumi.CustomResourceOptions): StackComponent
constructor(app: App, name: string, options?: StackOptions)
```

Parameters:
* `app`: The Pulumi CDK App
* `name`: The _unique_ name of the resource.
* `stack`: The CDK Stack subclass to create.
* `parent`: The Pulumi CDKStackComponent parent resource.
* `opts`: A bag of options that control this resource's behavior.
* `options`: A bag of options that control this resource's behavior.


#### `asOutput`

Convert a CDK value to a Pulumi output.

Parameters:
* `v`: A CDK value.

```ts
asOutput<T>(v: T): pulumi.Output<T>
```

### `StackOptions`

Options specific to the Stack component.

```ts
interface StackOptions
```


### `asString`

Expand Down
5 changes: 3 additions & 2 deletions src/converters/app-converter.ts
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import * as cdk from 'aws-cdk-lib/core';
import * as pulumi from '@pulumi/pulumi';
import { AssemblyManifestReader, StackManifest } from '../assembly';
import { ConstructInfo, GraphBuilder } from '../graph';
import { ArtifactConverter } from './artifact-converter';
import { lift, Mapping, AppComponent, PulumiStack } from '../types';
import { lift, Mapping, AppComponent } from '../types';
import { CdkConstruct, ResourceMapping } from '../interop';
import { debug } from '@pulumi/pulumi/log';
import {
Expand Down Expand Up @@ -90,7 +91,7 @@ export class StackConverter extends ArtifactConverter {
readonly parameters = new Map<string, any>();
readonly resources = new Map<string, Mapping<pulumi.Resource>>();
readonly constructs = new Map<ConstructInfo, pulumi.Resource>();
private readonly cdkStack: PulumiStack;
private readonly cdkStack: cdk.Stack;

private _stackResource?: CdkConstruct;

Expand Down
Loading

0 comments on commit bfa47d5

Please sign in to comment.