SpellCraft AWS Integration

Seamlessly integrate AWS SDK for JavaScript (v2) into your SpellCraft SpellFrames. This plugin allows you to natively expose authenticated AWS contexts or role-chains to your SpellFrames, and use the full power of the SDK in both JavaScript native functions and JSonnet.

npm install --save @c6fc/spellcraft @c6fc/spellcraft-aws-auth

This module will use credential sources in the same order as the AWS SDK for JavaScript, with role-assumption happening after the priority credential source is identified. If the role requires MFA, spellcraft will prompt for it.

# Show your current AWS credential context
npx spellcraft aws-identity

{
	"Account": "123456789012"
	"Arn": "arn:aws:iam::123456789012:user/you",
	"UserId": "AIDAEXAMPLEAAAAA"
}

You can perform an assumeRole operation using this initial context to chain into a different deployment role by setting the SPELLFRAME_ASSUMEROLE envvar:

export SPELLFRAME_ASSUMEROLE="arn:aws:iam::345678901234:role/deployment"

# She the new assumerole credential context:
npx spellcraft aws-identity

{
	"Account": "345678901234"
	"Arn": "arn:aws:iam::345678901234:assumed-role/deployment/spellcraft_assumerole_timestamp",
	"UserId": "AROAEXAMPLEBBBB:spellcraft_assumerole_timestamp"
}

Features

• Authenticate to AWS with native means, as well as role assumptions with SPELLFRAME_ASSUMEROLE
• Provide an authenticated aws instance to function contexts.
• Expose all AWS-SDK clients and methods directly to JSonnet.

CLI Commands

• spellcraft aws-identity Display the AWS IAM identity of the SpellCraft execution context
• spellcraft aws-exportcredentials Export the current credentials as environment variables

SpellFrame 'init()' features

Extends the SpellFrame's init() to include obtaining AWS credentials, and optionally performing an STS AssumeRole, before instantiating the AWS SDK for JavaScript.

JavaScript context features

Exposes an instance of the AWS-SDK v2 as aws for all native function executions.

JavaScript native functions

• aws(clientObj, method, params={}) - Wraps the authenticated instantiation of the AWS-SDK to allow for direct API calls
• callerId() - Returns the STS Caller Identity for the current context

API Reference

client(service, params={})

Creates an instance of the AWS service client which can be used to make API calls. This is only necessary if the client instantiation requires non-default parameters such as 'region'. Otherwise, aws.call() below is simpler.

• param {string} service
• param {object} params
• return {Class.AWS.service}

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";
local stsClient = aws.client('STS', { region: "us-east-1" });

{ identity: aws.api(stsClient,'getCallerIdentity') }

Another example here

api(clientObj, method, params="")

Makes an AWS API call using the provided client, of the specified method and with the supplied parameters.

• param {Class.AWS.service} client
• param {string} method
• param {object} [params={}]
• returns {string} result

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";
local stsClient = aws.client('STS', { region: "us-east-1" });

{ identity: aws.api(stsClient,'getCallerIdentity') }

callerId()

Makes an AWS API call using the provided client, of the specified method and with the supplied parameters.

• returns {string} result

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ callerId: aws.callerId() }

call(name, method, params="")

This is a shortcut for calling aws.api(aws.client(name, {}), method). Useful for when your service client requires no extra parameters.

• param {string} name
• param {string} method
• param {object} [params={}]
• returns {string} result

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ identity: aws.call('STS','getCallerIdentity') }

assertIdentity(arn)

Terminates manifestation if the current AWS identity ARN doesn't match the provided value. Useful for sanity checking prior to deployment.

• param {string} arn
• returns {bool} true || assertion failure

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ identity:: aws.assertIdentity('arn:aws:iam:123456789012:user/you') }

getCallerIdentity()

Returns details of the current AWS security principal context

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ identity: aws.getCallerIdentity() }

getRegionsList()

Returns an array of available AWS regions

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ regions: aws.getRegionList() }

getAvailabilityZones()

Returns an object containing the availability zones for each region; e.g. ["us-east-1"]: ["us-east-1a", "us-east-1b", ...]

Examples:

local aws = import "@c6fc/spellcraft-aws-auth/module.libsonnet";

{ availabilityZones: aws.getAvailabilityZones() }

Installation

Install the plugin as a dependency in your SpellCraft project:

npm install --save @c6fc/spellcraft-aws-auth

Then import the module into your Jsonnet code and use it.

local aws = import "@c6fc/spellcraft-aws-auth/module.jsonnet";

'identity.json': {
	aws: aws.getCallerIdentity()
}