Skip to content

Latest commit

 

History

History
332 lines (243 loc) · 16.4 KB

README.md

File metadata and controls

332 lines (243 loc) · 16.4 KB
Raw

AWS CDK for Java
Maven Plugin | Standalone

Synthesize, bootstrap and deploy without Node.js nor CDK Toolkit

Contents

Getting Started

Requirements:

Depdenency Version
Java >= 8
Maven >= 3.5
AWS CDK <= 2.134.0
AWS Cloud Assembly Schema <= 36.0.0

To bump up, open an issue or see here

As a standalone library

Import the library using Maven:

<dependency>
    <groupId>io.dataspray</groupId>
    <artifactId>aws-cdk</artifactId>
    <version><!-- Latest version: https://search.maven.org/artifact/io.dataspray/aws-cdk --></version>
</dependency>

And use it directly with your CDK stacks:

// Build your stack
CloudAssembly assembly = app.synth();

// Bootstrap
AwsCdk.bootstrap().execute(cloudAssembly);

// Deploy
AwsCdk.deploy().execute(cloudAssembly);

// Destroy
AwsCdk.destroy().execute(cloudAssembly);

As a Maven plugin

You can also perform actions using our Maven Plugin:

<plugin>
    <groupId>io.dataspray</groupId>
    <artifactId>aws-cdk-maven-plugin</artifactId>
    <version><!-- Latest version: https://search.maven.org/artifact/io.dataspray/aws-cdk-maven-plugin --></version>
    <executions>
        <execution>
            <id>deploy-cdk-app</id>
            <goals>
                <goal>synth</goal>
                <goal>bootstrap</goal>
                <goal>deploy</goal>
                <!-- <goal>destroy</goal> -->
            </goals>
            <configuration>
                <!-- Full class name of the app class defining your stacks -->
                <app>${cdk.app}</app>
                <!-- Input parameters for the stacks. -->
                <parameters>
                    <ParameterName>...</ParameterName>
                    ...
                </parameters>
            </configuration>
        </execution>
    </executions>
</plugin>

Please take a look at the example project. It is based on the project generated using cdk init with the difference that it uses aws-cdk-maven-plugin instead of the CDK CLI. You can also find more examples in the integration test directory.

Actions documentation

There are several actions you can perform using this library or Maven plugin outlined below:

Action Plugin Goal Library Description
Synthesize synth software.amazon.awscdk. App.synth() Synthesizes CloudFormation templates based on the resources defined in your CDK application.
Bootstrap bootstrap io.dataspray.aws.cdk. AwsCdk.bootstrap() Deploys toolkit stacks required by the CDK application to an AWS.
Deploy deploy io.dataspray.aws.cdk. AwsCdk.deploy() Deploys the CDK application to an AWS (based on the synthesized resources)
Destroy destroy io.dataspray.aws.cdk. AwsCdk.destroy() Destroys the CDK application from AWS

Synthesize

Library

Synthesize your stack using the AWS CDK library as normal using app.synth() which will produce a software.amazon.awscdk.cxapi.CloudAssembly. This CloudAssembly can be used for subsequent actions to bootstrap, deploy and destroy a stack.

App app = new App();
new MyStack(app);
CloudAssembly assembly = app.synth();

Maven Plugin

During the execution of synth goal, a cloud assembly is synthesized. The cloud assembly is a directory (target/cdk.out by default) containing the artifacts required for the deployment, i.e. CloudFormation templates, AWS Lambda bundles, file and Docker image assets etc. The artifacts in the cloud assembly directory are later used by bootstrap and deploy goals.

The only mandatory parameter required by the goal is <app>, which is a full class name of the CDK app class defining the cloud infrastructure. The application class must either extend software.amazon.awscdk.App or define a main method which is supposed to create an instance of App, define cloud constructs and call App#synth() method in order to produce a cloud assembly with CloudFormation templates.

Extending App class:

import software.amazon.awscdk.App;

public class MyApp extends App {

    public Mypp() {
        new MyStack(this, "my-stack");
    }

}

Defining main method:

import software.amazon.awscdk.App;

public class MyApp {

    public static void main(String[] args) {
        App app = new App();
        new MyStack(app, "my-stack");
        app.synth();
    }
    
}

Configuration

Parameter Type Since Description
<app>
-Daws.cdk.app		 String 0.0.1 Full class name of the CDK app class defining the cloud infrastructure.
<profile>
-Daws.cdk.profile		 String 0.0.1 A profile that will be used to find credentials and region.
<cloudAssemblyDirectory>
-Daws.cdk.cloud.assembly.directory		 String 0.0.1 A directory where the cloud assembly will be synthesized.
<arguments>
-Daws.cdk.arguments		 List<String> 0.0.5 A list of arguments to be passed to the CDK application.
<skip>
-Daws.cdk.skip		 boolean 0.0.7 Enables/disables the execution of the goal.

Bootstrap

CDK applications require a "toolkit stack" that includes the resources required for the application operation. For example, the toolkit stack may include S3 bucket used to store templates and assets for the deployment.

You may also choose to omit bootstrapping if you don't want to rely on the plugin and control this process by yourself. If you choose to omit, you will need to install the toolkit stack the first time you deploy an AWS CDK application into an environment (account/region) by running cdk bootstrap command (please refer to AWS CDK Toolkit for the details).

Library

Passing in a cloud assembly, the toolkit stack will be deployed in all the environemnts the stacks reside in.

AwsCdk.bootstrap().execute(cloudAssembly, "myStack1", "myStack2");

Maven Plugin

The plugin will automatically deploy the toolkit stack (or update if needed) during the execution of bootstrap goal (provided that the required toolkit stack version wasn't already deployed).

Configuration

Parameter Type Since Description
String profile
<profile>
-Daws.cdk.profile		 String 0.0.1 A profile that will be used to find credentials and region.
CloudAssembly cloudAssembly
Path cloudAssemblyDirectory
<cloudAssemblyDirectory>
-Daws.cdk.cloud.assembly.directory		 String 0.0.1 A cloud assembly directory with the deployment artifacts (target/cdk.out by default). Using the library, you can also pass the CloudAssembly directly.
String toolkitStackName
<toolkitStackName>
-Daws.cdk.toolkit.stack.name		 String 0.0.1 The name of the CDK toolkit stack to use (CDKToolkit is used by default).
Map<String, String> bootstrapParameters
<bootstrapParameters>		 Map<String, String> 1.2.0 Input parameters for the bootstrap stack. In the case of an update, existing values will be reused.
Map<String, String> bootstrapTags
<bootstrapTags>		 Map<String, String> 1.2.0 Tags that will be added to the bootstrap stack.
Set<String> stacks
<stacks>
-Daws.cdk.stacks		 List<String> 0.0.4 Stacks to deploy. By default, all the stacks defined in your application will be deployed.
<skip>
-Daws.cdk.skip		 boolean 0.0.7 Enables/disables the execution of the goal.

Deploy

Library

To deploy a stack from either a synthesized application in a directory or directly from `app.synth()`` do so like this:

CloudAssembly assembly = app.synth();
AwsCdk.deploy().execute(cloudAssembly, "myStack1", "myStack2");
AwsCdk.deploy().execute(Path.of("/path/to/cdk.out"), "myStack1", "myStack2");

Maven Plugin

To deploy the synthesized application into an AWS, add deploy goal to the execution (deploy and bootstrap goals are attached to the deploy Maven phase).

Configuration

Parameter Type Since Description
String profile
<profile>
-Daws.cdk.profile		 String 0.0.1 A profile that will be used to find credentials and region.
CloudAssembly cloudAssembly
Path cloudAssemblyDirectory
<cloudAssemblyDirectory>
-Daws.cdk.cloud.assembly.directory		 String 0.0.1 A cloud assembly directory with the deployment artifacts (target/cdk.out by default). Using the library, you can also pass the CloudAssembly directly.
String toolkitStackName
<toolkitStackName>
-Daws.cdk.toolkit.stack.name		 String 0.0.1 The name of the CDK toolkit stack to use (CDKToolkit is used by default).
Set<String> stacks
<stacks>
-Daws.cdk.stacks		 List<String> 0.0.4 Stacks to deploy. By default, all the stacks defined in your application will be deployed.
Map<String, String> parameters
<parameters>		 Map<String, String> 0.0.4 Input parameters for the stacks. For the new stacks, all the parameters without a default value must be specified. In the case of an update, existing values will be reused.
Map<String, String> tags
<tags>		 Map<String, String> 1.1.0 Tags to be applied for all stacks.
Set<String> notificationArns
<notificationArns>		 Set<String> 2.1.0 SNS ARNs to publish stack related events.
<skip>
-Daws.cdk.skip		 boolean 0.0.7 Enables/disables the execution of the goal.

Destroy

Library

To destroy a stack from either a synthesized application in a directory or directly from `app.synth()`` do so like this:

CloudAssembly assembly = app.synth();
AwsCdk.destroy().execute(cloudAssembly, "myStack1", "myStack2");
AwsCdk.destroy().execute(Path.of("/path/to/cdk.out"), "myStack1", "myStack2");

Maven Plugin

To destroy an existing application into an AWS, add destroy goal to the execution.

Configuration

Parameter Type Since Description
String profile
<profile>
-Daws.cdk.profile		 String 0.0.1 A profile that will be used to find credentials and region.
CloudAssembly cloudAssembly
Path cloudAssemblyDirectory
<cloudAssemblyDirectory>
-Daws.cdk.cloud.assembly.directory		 String 0.0.1 A cloud assembly directory with the deployment artifacts (target/cdk.out by default). Using the library, you can also pass the CloudAssembly directly.
Set<String> stacks
<stacks>
-Daws.cdk.stacks		 List<String> 0.0.4 Stacks to deploy. By default, all the stacks defined in your application will be deployed.
<skip>
-Daws.cdk.skip		 boolean 0.0.7 Enables/disables the execution of the goal.

Authentication

The plugin tries to find the credentials and region in different sources in the following order:

  • If profile configuration parameter is defined, the plugin looks for the corresponding credentials and region in the default AWS credentials and config files (~/.aws/credentials and ~/.aws/config, the location may be different depending on the platform).
  • Using Java system properties aws.accessKeyId, aws.secretKey and aws.region.
  • Using environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION
  • Looking for the credentials and region associated with the default profile in the credentials and config files.

AWS CDK Dependency bump

In order to use the latest AWS CDK, this repository needs to be updated to support your version. This section describes the process of bumping these dependencies.

Bump the AWS versions

In pom.xml, bump the following versions: aws.cdk.version, aws.sdk.version, aws.cdk.jsii.version.

At the top of this README, update the CDK version and the version of the cloud assembly schema version that can be found here.

Bump the Bootstrap Stack version

In BootstrampImpl.java, under the TOOLKIT_STACK_VERSION constant, there are instructions on how to bring the latest version of the bootstrap stack.

Migration from LinguaRobot

This library is originally based off of LinguaRobot/aws-cdk-maven-plugin. Migrating from LinguaRobot Maven Plugin is simple as changing the Plugin's groupId from io.linguarobot to io.dataspray and bumping to the latest version from Maven Central.

Security Policy

Reporting a Vulnerability

Please report to security@smotana.com for all vulnerabilities or questions regarding security.