AWS CDK for Ruby

Getting started

Native Ruby bindings for the AWS CDK — the same construct library every other CDK language uses, generated from jsii. You write idiomatic Ruby and cdk deploy synthesises and deploys it exactly as it would from TypeScript.

Prerequisites

• Ruby ≥ 3.3 (MRI / CRuby).
• Node.js — the bindings talk to the jsii kernel (a small Node sidecar). You never write Node, but it must be installed.
• The CDK CLI: npm install -g aws-cdk.

Gemfile

The gems are published to https://rubygems.omarqureshi.net. During the preview they're pre-release, hence the >= 0.0.0.pre constraint. Then bundle install.

source 'https://rubygems.org'

source 'https://rubygems.omarqureshi.net' do
  gem 'aws-cdk-lib', '>= 0.0.0.pre'
  gem 'constructs', '>= 0.0.0.pre'
  gem 'jsii-ruby-runtime', '>= 0.0.0.pre'

  # aws-cdk-lib requires these asset packages at load time:
  gem 'aws-cdk-asset-awscli-v1', '>= 0.0.0.pre'
  gem 'aws-cdk-asset-node-proxy-agent-v6', '>= 0.0.0.pre'
  gem 'aws-cdk-cloud-assembly-schema', '>= 0.0.0.pre'
end

cdk.json

Tells the CDK CLI how to run your app:

{
  "app": "bundle exec ruby app.rb"
}

A first stack

Subclass AWSCDK::Stack, call super, and instantiate constructs with (self, 'LogicalId', props) — the same shape as every other CDK language.

# stacks/my_stack.rb
require 'aws-cdk-lib'

class MyStack < AWSCDK::Stack
  def initialize(scope, id, props = nil)
    super(scope, id, props)

    AWSCDK::S3::Bucket.new(
      self,
      'MyBucket',
      {
        versioned: true,
        removal_policy: AWSCDK::RemovalPolicy::DESTROY,
        auto_delete_objects: true
      }
    )
  end
end

# app.rb
require 'aws-cdk-lib'
require_relative 'stacks/my_stack'

app = AWSCDK::App.new

MyStack.new(app, 'MyStack', {
  env: AWSCDK::Environment.new(
    account: ENV['CDK_DEFAULT_ACCOUNT'],
    region: ENV.fetch('CDK_DEFAULT_REGION', 'us-east-1')
  )
})

app.synth

Deploy

$ bundle install
$ npm install -g aws-cdk @jsii/runtime
$ cdk deploy

Naming rules

The conventions you'll rely on reading these docs:

• Modules are PascalCase under AWSCDK: AWSCDK::S3, AWSCDK::DynamoDB, AWSCDK::APIGatewayv2.
• AWS acronyms are uppercased — in class names too. RestApi → AWSCDK::APIGateway::RestAPI; FunctionUrl → AWSCDK::Lambda::FunctionURL; …Arn → …ARN.
• Props are a Ruby Hash with snake_case keys — removal_policy:, not removalPolicy:.
• Enums are constants under ::: AWSCDK::RemovalPolicy::DESTROY.
• Static properties are method calls with a .: AWSCDK::Lambda::Runtime.RUBY_4_0.