Current Status (January 16, 2020)

After developing and using this Clojure wrapper for AWS CDK for the past six months, we've decided to use TypeScript and AWS' library directly. We are discontinuing maintenance moving forward. If a member of the community would like to volunteer for future maintenance, please file an issue or reach out directly to discuss a possible transfer.

cdk-clj

#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.

Purpose

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 Python, 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.

For a general introduction, watch the Clojure/Conj talk:

Prerequisites

cdk-clj requires:

Quick Start

Ensure you have configured appropriate AWS Credentials. The following commands assume a default profile.
Install aws-cdk:

npm install -g aws-cdk

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 "https://github.com/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.20.0"}
                               }}}}

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

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

(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" {}))

Create cdk.json in the root of your project to tell the CDK toolchain how to invoke the app:

{"app":"clojure -A:dev -i cdk/stedi/my_app/cdk.clj"}

where the argument to -i is the path to the file in which the cdk-clj app is defined.

List your stacks to verify correct configuration:

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

See the YAML that this deployment will produce for CloudFormation:

cdk synth my-app-dev

Deploy the stack to AWS:

cdk deploy my-app-dev

Implementation Details

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")

Next Steps

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

Troubleshooting

Cannot find the 'jsii-runtime' executable (JSII_RUNTIME or PATH)

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.

Contributing

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

License

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

See LICENSE for more information.

Stedi-Public-Archive / cdk-clj