#cdk-clj on Clojurians

This library is a Clojure wrapper for AWS Cloud Development Kit (AWS CDK).

This is an alpha release. We use this library internally and consider it stable. Nonetheless, we may still make minor changes to the API.

From AWS:

The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework to define cloud infrastructure in code and provision it through AWS CloudFormation.

It offers a high-level object-oriented abstraction to define AWS resources imperatively using the power of modern programming languages. Using the CDK's library of infrastructure constructs, you can easily encapsulate AWS best practices in your infrastructure definition and share it without worrying about boilerplate logic.

CDK is built on Amazon's jsii project, which allows TypeScript projects to be shared across Ruby, JavaScript, Java and C# via code generation.

cdk-clj taps into this ecosystem directly by consuming the jsii protocol and bringing infrastructure to the REPL. REPL-driven infrastructure turns a frustrating practice with long feedback cycles into an enjoyable experience with immediate feedback and makes it possible for Clojure code to be deployed to AWS with minimal configuration.

cdk-clj requires:

1. Clojure
2. Node.js
3. AWS CDK CLI

0. Ensure you have configured appropriate AWS Credentials.

1. Install aws-cdk:

npm install -g aws-cdk

2. Create a new project directory with the following in a deps.edn file. You will also need to include the Maven dependency for any CDK modules you are using. You can find all the available modules here.

{:paths   ["src"]
 :deps    {org.clojure/clojure {:mvn/version "1.10.1"}}
 :aliases {:dev {:extra-paths ["cdk"]
                 :extra-deps  {stedi/cdk-clj {:git/url "[email protected]:StediInc/cdk-clj.git"
                                              :sha     "<LATEST SHA HERE>"}
                               ;; Required in order to use the "@aws-cdk/aws-s3" module below
                               software.amazon.awscdk/s3 {:mvn/version "1.12.0.DEVPREVIEW"}
                               }}}}

3. Create a CDK infrastructure file with the path ./cdk/stedi/cdk/my_app.clj.

(ns stedi.cdk.my-app
  (:require [stedi.cdk.alpha :as cdk]
            [stedi.my-app :as my-app]))

(cdk/import [[Stack] :from "@aws-cdk/core"]
            [[Bucket] :from "@aws-cdk/aws-s3")

(defn AppStack
  [scope id props]
  (let [stack (Stack scope id props)]
    (Bucket stack "my-bucket" {:versioned true})))

(cdk/defapp app [this]
  (AppStack this "my-app-dev" {}))

4. From the command line run:

clj -A:dev -m stedi.cdk.main config --aliases dev

This command will generate a cdk.json file which tells cdk how to enteract with cdk-clj.

5. List your stacks to verify correct configuration:

cdk ls
# should return `my-app-dev`

6. See the YAML that this deployment will produce for CloudFormation:

cdk synth my-app-dev

7. Deploy the stack to AWS:

cdk deploy my-app-dev

jsii is a protocol that allows TypeScript classes and objects to be consumed via an RPC protocol. This protocol exposes the ability to:

• Create objects from classes with optionally overloaded methods
• Get properties from objects
• Set properties on objects
• Call methods on objects
• Get static properties on classes
• Set static properties on classes
• Call static methods on classes
• Respond to callbacks on overloaded objects

CDK exposes its functionality via this API to allow non-JavaScript programming languages to benefit from the functionality it provides. cdk-clj maps these operations into Clojure friendly equivalents. The CDK library relies heavily on object oriented principles and cdk-clj does not shy away from those concepts. Instead, it embraces them and maps them into a Clojure-friendly interface. In doing so, it makes the CDK documentation directly mappable to Clojure.

There are two types introduced by this library: CDKClass and CDKObject. Together, they expose all of the functionality of the jsii protocol by implementing the clojure.lang.ILookup and clojure.lang.IFn interfaces:

Instantiate an object from a class

;; Creates a bucket based on the CDK class @aws-cdk/aws-s3.Bucket
(cdk/import [[Bucket] :from "@aws-cdk/aws-s3"])
(def bucket (Bucket parent "my-bucket" {}))

Get property of an object

;; Gets the bucketArn property off of the bucket instance
(:bucketArn bucket)

Set property of an object

;; TODO: not implemented yet

Call a method on an object

;; Grants READ permission to the lambda-function object
(cdk/import [[Bucket] :from "@aws-cdk/aws-s3"])
(Bucket/grantRead bucket lambda-function)

Get static property of a class

(cdk/import [[Runtime] :from "@aws-cdk/aws-lambda"])
;; Get the JAVA8 runtime instance
(:JAVA_8 Runtime)

Set static property of an object

;; TODO: not implemented yet

Call static method on class

(cdk/import [[Code] :from "@aws-cdk/aws-lambda"])
;; Refer to the src directory as an asset to be uploaded
(Code/asset "src")

• Check out the example app to see the minimum setup required to get a Lambda deployed behind API Gateway
• Check out the CDK API Docs to see what modules are available and how to use them

This error is non-specific and is raised on any failure to launch the runtime process, not just the missing executable named; that the causative exception is not chained makes this harder to debug.

One possible cause is not having the Node.js executable (i.e., node) on the PATH given to the JVM. If you're using a Node version or virtual environment manager, add the appropriate directory to the JVM environment.

Contributors are welcome to submit issues, bug reports, and feature requests. Presently, we do not accept pull requests.

cdk-clj is distributed under the Apache License, Version 2.0.

See LICENSE for more information.