Current Status (January 16, 2020)

After developing and using this Clojure wrapper for AWS CDK for the pastsix months, we've decided to use TypeScript and AWS' library directly. We arediscontinuing maintenance moving forward. If a member of the community wouldlike to volunteer for future maintenance, please file an issue or reach outdirectly 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 itstable. 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 developmentframework to define cloud infrastructure in code and provision it through AWSCloudFormation.

It offers a high-level object-oriented abstraction to define AWS resourcesimperatively using the power of modern programming languages. Using the CDK'slibrary of infrastructure constructs, you can easily encapsulate AWS bestpractices in your infrastructure definition and share it without worrying aboutboilerplate logic.

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

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

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

Prerequisites

cdk-clj requires:

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

Quick Start

0. Ensure you have configured appropriate AWS Credentials.The following commands assume a default profile.

1. Install aws-cdk:

npm install -g aws-cdk

2. Create a new project directory with the following in a deps.ednfile. You will also need to include the Maven dependency for anyCDK modules you are using. You can find all the available moduleshere.

{: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"}
                               }}}}

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

4. Createcdk.json inthe 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 isdefined.

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

Implementation Details

jsii is a protocol that allows TypeScript classes and objects to beconsumed 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 programminglanguages to benefit from the functionality it provides.cdk-clj maps these operations into Clojure friendly equivalents. The CDK libraryrelies heavily on object oriented principles and cdk-clj does not shy away fromthose concepts. Instead, it embraces them and maps them into a Clojure-friendlyinterface. In doing so, it makes the CDK documentation directly mappable toClojure.

There are two types introduced by this library: CDKClass andCDKObject. Together, they expose all of the functionality of the jsiiprotocol by implementing the clojure.lang.ILookup and clojure.lang.IFninterfaces:

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 aLambda deployed behind API Gateway
• Check out the CDK API Docs to see what modules are available and how touse them

Troubleshooting

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

This error is non-specific and is raised on any failure to launchthe runtime process, not just the missing executable named; that the causativeexception 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 orvirtual environment manager, add the appropriate directory to the JVMenvironment.

Contributing

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

License

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

See LICENSE for more information.