configuration Submodule

Structs

AddDirectoryOptions

Options for the ShellCommands.addDirectory method.

Initializer 

import { configuration } from 'shady-island'

const addDirectoryOptions: configuration.AddDirectoryOptions = { ... }

Properties

Name Type Description
group string The group name or numeric group ID to assign as the directory group.
mode string The file mode, e.g. 2755, 0400.
owner string The username or numeric user ID to assign as the directory owner.
groupOptional 
public readonly group: string;

The group name or numeric group ID to assign as the directory group.

modeOptional 
public readonly mode: string;

The file mode, e.g. 2755, 0400.

ownerOptional 
public readonly owner: string;

The username or numeric user ID to assign as the directory owner.

ElasticFileSystemAddOnProps

Constructor properties for ElasticFileSystemAddOn.

Initializer 

import { configuration } from 'shady-island'

const elasticFileSystemAddOnProps: configuration.ElasticFileSystemAddOnProps = { ... }

Properties

Name Type Description
priority number The priority for the script added by this add-on.
chgrp string The intended Linux group name or ID of the group of the mounted directory.
chmod number The intended file mode of the mounted directory.
chown string The intended Linux username or ID of the owner of the mounted directory.
priorityOptional 
public readonly priority: number;

The priority for the script added by this add-on.

chgrpOptional 
public readonly chgrp: string;

The intended Linux group name or ID of the group of the mounted directory.

chmodOptional 
public readonly chmod: number;

The intended file mode of the mounted directory.

chownOptional 
public readonly chown: string;

The intended Linux username or ID of the owner of the mounted directory.

OutputFileOptions

Options for the ShellCommands.outputFile method.

Initializer 

import { configuration } from 'shady-island'

const outputFileOptions: configuration.OutputFileOptions = { ... }

Properties

Name Type Description
delimiter string The bash heredoc delimiter.
substitution boolean Use true to enable variable and command substitution inside the heredoc.
delimiterOptional 
public readonly delimiter: string;

The bash heredoc delimiter.

substitutionOptional 
public readonly substitution: boolean;

Use true to enable variable and command substitution inside the heredoc.

SinglePriorityProps

Properties for starter add-ons that add a single script.

Initializer 

import { configuration } from 'shady-island'

const singlePriorityProps: configuration.SinglePriorityProps = { ... }

Properties

Name Type Description
priority number The priority for the script added by this add-on.
priorityOptional 
public readonly priority: number;

The priority for the script added by this add-on.

Classes

BucketSyncAddOn

An add-on that synchronizes files from S3 to directories on the instance.

This add-on also grants read access to the bucket.

Initializers 

import { configuration } from 'shady-island'

new configuration.BucketSyncAddOn(bucket: IBucket, destinations: {[ key: string ]: string}, props?: SinglePriorityProps)
Name Type Description
bucket aws-cdk-lib.aws_s3.IBucket - The S3 bucket from which files can be downloaded.
destinations {[ key: string ]: string} - An object where keys are S3 object key prefixes and values are filesystem directories.
props SinglePriorityProps - Optional configuration properties.
bucketRequired

The S3 bucket from which files can be downloaded.

destinationsRequired

An object where keys are S3 object key prefixes and values are filesystem directories.

propsOptional

Optional configuration properties.

Methods

Name Description
configure Any configuration or customization of the virtual machine takes place here.
configure 
public configure(starter: Starter): void

Any configuration or customization of the virtual machine takes place here.

starterRequired

ElasticFileSystemAddOn

An add-on that configures a mount point for an EFS filesystem.

This add-on will produce a startup script to:

This visitor also configures the Security Groups on both ends.

Initializers 

import { configuration } from 'shady-island'

new configuration.ElasticFileSystemAddOn(filesystem: IFileSystem, destination: string, props?: ElasticFileSystemAddOnProps)
Name Type Description
filesystem aws-cdk-lib.aws_efs.IFileSystem - The elastic filesystem to mount.
destination string - The directory to use as the mount point.
props ElasticFileSystemAddOnProps - Optional configuration properties.
filesystemRequired

The elastic filesystem to mount.

destinationRequired

The directory to use as the mount point.

propsOptional

Optional configuration properties.

Methods

Name Description
configure Any configuration or customization of the virtual machine takes place here.
configure 
public configure(starter: Starter): void

Any configuration or customization of the virtual machine takes place here.

starterRequired

InstanceFirewall

Produces the appropriate commands to configure an on-instance firewall.

Initializers 

import { configuration } from 'shady-island'

new configuration.InstanceFirewall()

| Name | Type | Description | | — | — | — |

Static Functions

Name Description
iptables Define an instance firewall using iptables/ip6tables.
iptables 
import { configuration } from 'shady-island'

configuration.InstanceFirewall.iptables()

Define an instance firewall using iptables/ip6tables.

InstanceFirewallAddOn

An add-on that configures an on-instance firewall.

Initializers 

import { configuration } from 'shady-island'

new configuration.InstanceFirewallAddOn(rules: IFirewallRules, props?: SinglePriorityProps)
Name Type Description
rules IFirewallRules - The instance firewall rules.
props SinglePriorityProps - Optional configuration properties.
rulesRequired

The instance firewall rules.

propsOptional

Optional configuration properties.

Methods

Name Description
configure Any configuration or customization of the virtual machine takes place here.
configure 
public configure(starter: Starter): void

Any configuration or customization of the virtual machine takes place here.

starterRequired

ShellCommands

A utility class that provides POSIX shell commands for User Data scripts.

Initializers 

import { configuration } from 'shady-island'

new configuration.ShellCommands()

| Name | Type | Description | | — | — | — |

Static Functions

Name Description
addDirectory Uses either mkdir or install to create a directory.
changeOwnership Gets a command to change the ownership and/or group membership of a file.
disableUnattendedUpgrades Gets a command to disable unattended package upgrades on Debian/Ubuntu.
downloadSecret Gets the command to download a Secrets Manager secret to the filesystem.
mountElasticFileSystem Gets the command to mount an EFS filesystem to a destination path.
outputFile Writes the literal contents of a string to a destination file.
syncFromBucket Gets commands to synchronize objects from an S3 bucket to the filesystem.
addDirectory 
import { configuration } from 'shady-island'

configuration.ShellCommands.addDirectory(name: string, options?: AddDirectoryOptions)

Uses either mkdir or install to create a directory.

nameRequired

The name of the directory to create.

optionsOptional

Configuration options.

changeOwnership 
import { configuration } from 'shady-island'

configuration.ShellCommands.changeOwnership(filename: string, uid?: string, gid?: string)

Gets a command to change the ownership and/or group membership of a file.

If both uid and gid are provided, this method returns a single chown command to set both values. If just uid is provided, this method returns a single chown command that sets the owner. If just gid is provided, this method returns a single chgrp command. If neither are provided, this method returns an empty array.

filenameRequired

The local filesystem path to the file or directory.

uidOptional

Optional.

The owner username or uid.

gidOptional

Optional.

The group name or gid.

disableUnattendedUpgrades 
import { configuration } from 'shady-island'

configuration.ShellCommands.disableUnattendedUpgrades()

Gets a command to disable unattended package upgrades on Debian/Ubuntu.

downloadSecret 
import { configuration } from 'shady-island'

configuration.ShellCommands.downloadSecret(secret: ISecret, destination: string)

Gets the command to download a Secrets Manager secret to the filesystem.

Be sure to grant your autoscaling group or EC2 instance read access.

secretRequired

The secret to download.

destinationRequired

The local filesystem path where the secret is stored.

mountElasticFileSystem 
import { configuration } from 'shady-island'

configuration.ShellCommands.mountElasticFileSystem(filesystem: IFileSystem, destination: string)

Gets the command to mount an EFS filesystem to a destination path.

Be sure to grant your autoscaling group or EC2 instance network access.

filesystemRequired

The EFS filesystem.

destinationRequired

The local filesystem path for the mount point.

outputFile 
import { configuration } from 'shady-island'

configuration.ShellCommands.outputFile(contents: string, destination: string, options?: OutputFileOptions)

Writes the literal contents of a string to a destination file.

contentsRequired

The file contents.

destinationRequired

The filename to output.

optionsOptional

Configuration options.

syncFromBucket 
import { configuration } from 'shady-island'

configuration.ShellCommands.syncFromBucket(bucket: IBucket, destinations: {[ key: string ]: string})

Gets commands to synchronize objects from an S3 bucket to the filesystem.

e.g. syncFromBucket(bucket, {"nginx-config": "/etc/nginx"}).

Be sure to grant your autoscaling group or EC2 instance read access.

bucketRequired

The source bucket.

destinationsRequired

Record with S3 object keys to filesystem path values.

Starter

Orchestrates the startup process of EC2 instances.

A Starter is a registry for add-ons. Each add-on can add permissions to the role, network rules to the security group, or scripts to the user data.

Scripts are prioritized, so add-ons can be registered out of order but their scripts will appear in the user data in order of priority.

Methods

Name Description
addScript Add one or more commands to the user data at a specific priority.
withAddOns Register add-ons with this Starter.
addScript 
public addScript(priority: number, commands: ...string[]): Starter

Add one or more commands to the user data at a specific priority.

priorityRequired

The priority of these lines (lower executes earlier).

commandsRequired

The lines to add.

withAddOns 
public withAddOns(addons: ...IStarterAddOn[]): Starter

Register add-ons with this Starter.

addonsRequired

The add-ons to register.

Static Functions

Name Description
forAutoScalingGroup Create a Starter for an auto-scaling group.
forInstance Create a Starter for a single EC2 instance3.
forLaunchTemplate Create a Starter for a Launch Template.
forAutoScalingGroup 
import { configuration } from 'shady-island'

configuration.Starter.forAutoScalingGroup(group: AutoScalingGroup)

Create a Starter for an auto-scaling group.

groupRequired

The auto-scaling group.

forInstance 
import { configuration } from 'shady-island'

configuration.Starter.forInstance(instance: Instance)

Create a Starter for a single EC2 instance3.

instanceRequired

The instance.

forLaunchTemplate 
import { configuration } from 'shady-island'

configuration.Starter.forLaunchTemplate(template: LaunchTemplate)

Create a Starter for a Launch Template.

The launch template must have a defined user data property, or this method will throw an error.

templateRequired

The launch template.

Properties

Name Type Description
connections aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
orderedLines string[] All lines of the startup script in priority order.
connectionsRequired 
public readonly connections: Connections;

The network connections associated with this resource.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;

The principal to grant permissions to.

orderedLinesRequired 
public readonly orderedLines: string[];

All lines of the startup script in priority order.

Protocols

IFirewallRules

Used to configure on-instance firewall rules (e.g. iptables, firewalld).

Methods

Name Description
buildCommands Retrieves the shell commands used to configure the instance firewall.
inbound Declare an inbound rule.
inboundFromAnyIpv4 Declare an inbound rule that covers all IPv4 addresses.
inboundFromAnyIpv6 Declare an inbound rule that covers all IPv6 addresses.
outbound Declare an outbound rule.
outboundToAnyIpv4 Declare an outbound rule that covers all IPv4 addresses.
outboundToAnyIpv6 Declare an outbound rule that covers all IPv6 addresses.
buildCommands 
public buildCommands(): string[]

Retrieves the shell commands used to configure the instance firewall.

inbound 
public inbound(port: Port, address: Address): IFirewallRules

Declare an inbound rule.

Only the following protocols are allowed: TCP, UDP, ICMP, and ICMPv6. The address can be a single address or a range of addresses in CIDR notation.

portRequired

The ingress port.

addressRequired

The source address.

inboundFromAnyIpv4 
public inboundFromAnyIpv4(port: Port): IFirewallRules

Declare an inbound rule that covers all IPv4 addresses.

Only the following protocols are allowed: TCP, UDP, ICMP, and ICMPv6.

portRequired

The ingress port.

inboundFromAnyIpv6 
public inboundFromAnyIpv6(port: Port): IFirewallRules

Declare an inbound rule that covers all IPv6 addresses.

Only the following protocols are allowed: TCP, UDP, ICMP, and ICMPv6.

portRequired

The ingress port.

outbound 
public outbound(port: Port, address: Address): IFirewallRules

Declare an outbound rule.

Only the following protocols are allowed: TCP, UDP, ICMP, and ICMPv6. The address can be a single address or a range of addresses in CIDR notation.

portRequired

The egress port.

addressRequired

The target address.

outboundToAnyIpv4 
public outboundToAnyIpv4(port: Port): IFirewallRules

Declare an outbound rule that covers all IPv4 addresses.

Only the following protocols are allowed: TCP, UDP, and ICMP.

portRequired

The egress port.

outboundToAnyIpv6 
public outboundToAnyIpv6(port: Port): IFirewallRules

Declare an outbound rule that covers all IPv6 addresses.

Only the following protocols are allowed: TCP, UDP, and ICMPv6.

portRequired

The egress port.

IStarterAddOn

A component involved in the startup process of an EC2 instance.

Methods

Name Description
configure Any configuration or customization of the virtual machine takes place here.
configure 
public configure(starter: Starter): void

Any configuration or customization of the virtual machine takes place here.

starterRequired

The starter that can be configured.