almacdkproject

package module
v0.0.32 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2024 License: Apache-2.0 Imports: 9 Imported by: 0

README




🚧 Work-in-Progress: Breaking changes may occur at any given point during v0.x.






Alma CDK Project 

npm i -D @alma-cdk/project

Opinionated CDK “framework” with constructs & utilities for:

  • deploying multiple environments to multiple accounts (with many-to-many relationship)

  • managing account configuration through standardized props (no more random config files)

  • querying account and/or environment specific information within your CDK code

  • enabling dynamic & short-lived “feature-environments”

  • enabling well-defined tagging

  • providing structure & common conventions to CDK projects

  • choosing the target account & environment by passing in runtime context:

    npx cdk deploy -c account=dev -c environment=feature/abc-123

    ... which means you don't need to define all the possibile environments ahead of time!


Account Strategies

Depending on the use case, you may choose a configuration between 1-3 AWS accounts with the following environments:

  1. Shared account (shared):

    default-multi

  2. Multi-account (dev+prod)– RECOMMENDED:

    default-multi


  1. Multi-account (dev+preprod+prod):

    default-multi


Getting Started

Steps required to define a environmental project resources; At first, it might seem complex but once you get into the habbit of defining your projects this way it starts to make sense:

  1. Choose your Account Strategy

  2. Initialize a new Project instead of cdk.App:

    // bin/app.ts
import { Project, AccountStrategy } from '@alma-cdk/project';

const project = new Project({
  // Basic info, you could also read these from package.json if you want
  name: 'my-cool-project',
  author: {
    organization: 'Acme Corp',
    name: 'Mad Scientists',
    email: 'mad.scientists@acme.example.com',
  },

  // If not set, defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1
  defaultRegion: 'eu-west-1',

  // Configures the project to use 2 AWS accounts (recommended)
  accounts: AccountStrategy.two({
    dev: {
      id: '111111111111',
      config: {
        // whatever you want here as [string]: any
        baseDomain: 'example.net',
      },
    },
    prod: {
      id: '222222222222',
      config: {
        // whatever you want here as [string]: any
        baseDomain: 'example.com',
      },
    },
  }),
})

  3. Define a stack which extends SmartStack with resources:

    // lib/my-stack.ts
import { Construct } from 'constructs';
import { StackProps, RemovalPolicy } from 'aws-cdk-lib';
import { SmartStack, Name, UrlName, PathName, EC } from '@alma-cdk/project';

export class MyStack extends SmartStack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new dynamodb.Table(this, 'Table', {
      removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,

      tableName: Name.it(this, 'MyTable'),
      partitionKey: {
        type: dynamodb.AttributeType.STRING,
        name: 'pk',
      },
      // StagingMyTable
    });

    new events.EventBus(this, 'EventBus', {
      eventBusName: Name.withProject(this, 'MyEventBus'),
      // MyCoolProjectStagingMyEventBus
    });

    new s3.Bucket(this, 'Bucket', {

      removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
      autoDeleteObjects: EC.isStable(this) ? false : true,

      bucketName: UrlName.globally(this, 'MyBucket'),
      // acme-corp-my-cool-project-feature-foo-bar-my-bucket
    });

    new ssm.StringParameter(this, 'Parameter', {
      stringValue: 'Foo',
      tier: ssm.ParameterTier.ADVANCED,
      parameterName: PathName.withProject(this, 'MyNamespace/MyParameter'),
      // /MyCoolProject/Staging/MyNamespace/MyParameter
    });
  }
}

  4. Define a new environmental which extends EnvironmentWrapper and initialize all your environmental SmartStack stacks within:

    // lib/environment.ts
import { Construct } from 'constructs';
import { EnvironmentWrapper } from '@alma-cdk/project';
import { MyStack } from './my-stack';

export class Environment extends EnvironmentWrapper {
  constructor(scope: Construct) {
    super(scope);
    new MyStack(this, 'MyStack', { description: 'This is required' });
  }
}

    Resulting Stack properties (given environment=staging):

    Property Example value
    stackName "MyCoolProject-Environment-Staging-MyExampleStack"
    terminationProtection true
    env.account "111111111111"
    env.region "eu-west-1"

    Resulting Tags for the Stack and its resources (given environment=staging):

    Property Example value
    Account dev
    Environment staging
    Project my-cool-project
    Author Mad Scientists
    Organization Acme Corp
    Contact mad.scientists@acme.example.com

  5. Finally initialize the environment with the Project scope:

    // bin/app.ts
import { Project, Accounts } from '@alma-cdk/project';
import { Environment } from '../lib/environment';

const project = new Project({/* removed for brevity, see step 1 */})

new Environment(project);

Documentation

See detailed documentation for specific classes & methods at constructs.dev.

Generally speaking you would be most interested in the following:

  • Project
  • AccountStrategy
  • SmartStack
  • AccountWrapper & EnvironmentWrapper
  • AccountContext (AC)
  • EnvironmentContext (EC)
  • Name / UrlName / PathName

Documentation

Overview

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Opinionated CDK Project “Framework”

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AccountContext_GetAccountConfig 

func AccountContext_GetAccountConfig(scope constructs.Construct, key *string) interface{}

Experimental.

func AccountContext_GetAccountId 

func AccountContext_GetAccountId(scope constructs.Construct) *string

Experimental.

func AccountContext_GetAccountType 

func AccountContext_GetAccountType(scope constructs.Construct) *string

Experimental.

func AccountContext_IsDev 

func AccountContext_IsDev(scope constructs.Construct) *bool

Experimental.

func AccountContext_IsMock 

func AccountContext_IsMock(scope constructs.Construct) *bool

Experimental.

func AccountContext_IsPreProd 

func AccountContext_IsPreProd(scope constructs.Construct) *bool

Experimental.

func AccountContext_IsProd 

func AccountContext_IsProd(scope constructs.Construct) *bool

Experimental.

func AccountContext_IsShared 

func AccountContext_IsShared(scope constructs.Construct) *bool

Experimental.

func AccountStrategy_One 

func AccountStrategy_One(props *AccountStrategyOneProps) *map[string]*Account

Enables single account strategy.

1. `shared` account with environments:

  • development
  • feature/*
  • test
  • qaN
  • staging
  • preproduction

- production.

Example: 

AccountStrategy.one({
  shared: {
    id: '111111111111',
  },
}),

Experimental.

func AccountStrategy_Three 

func AccountStrategy_Three(props *AccountStrategyThreeProps) *map[string]*Account

Enables triple account strategy.

1. `dev` account with environments:

  • development
  • feature/*
  • test
  • staging

2. `preprod` account with environments:

  • qaN
  • preproduction

3. `prod` account with environments: - production.

Example: 

AccountStrategy.three({
  dev: {
    id: '111111111111',
  },
  preprod: {
    id: '222222222222',
  },
  prod: {
    id: '333333333333',
  },
}),

Experimental.

func AccountStrategy_Two 

func AccountStrategy_Two(props *AccountStrategyTwoProps) *map[string]*Account

Enables dual account strategy.

1. `dev` account with environments:

  • development
  • feature/*
  • test
  • qaN
  • staging

2. `prod` account with environments:

  • preproduction

- production.

Example: 

AccountStrategy.two({
  dev: {
    id: '111111111111',
  },
  prod: {
    id: '222222222222',
  },
}),

Experimental.

func AccountType_Get 

func AccountType_Get(scope constructs.Construct) *string

Experimental.

func AccountType_MatchFromEnvironment 

func AccountType_MatchFromEnvironment(scope constructs.Construct, accounts *map[string]*Account, environmentType *string) *string

Experimental.

func AccountType_Set 

func AccountType_Set(scope constructs.Construct, accountType *string)

Experimental.

func AccountWrapper_IsConstruct 

func AccountWrapper_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func EnvironmentContext_GetFeatureInfo 

func EnvironmentContext_GetFeatureInfo(scope constructs.Construct) *string

Get Feature Info.

If environment belongs to `feature` category, this will return a string describing the feature (sting after `feature/`-prefix).

If environment is not a feature environment, will return an empty string.

Returns: string indicating the feature this environment relates to, if not feature environment returns an empty string. Experimental.

func EnvironmentContext_GetName 

func EnvironmentContext_GetName(scope constructs.Construct) *string

Get Environment Name.

Returns: Environment Name (as given via `--context environment`).

Example: 

'mock1'
'mock2'
'mock3'
'development'
'feature/foo-bar'
'feature/ABC-123/new-stuff'
'test'
'staging'
'qa1'
'qa2'
'qa3'
'preproduction'
'production'

Experimental.

func EnvironmentContext_GetUrlName 

func EnvironmentContext_GetUrlName(scope constructs.Construct) *string

Get Environment URL/DNS Compatible Name.

Returns: Environment URL/DNS Compatible Name (as given via `--context environment` but `param-cased`).

Example: 

'mock1'
'mock2'
'mock3'
'development'
'feature-foo-bar'
'feature-abc-123-new-stuff'
'test'
'staging'
'qa1'
'qa2'
'qa3'
'preproduction'
'production'

Experimental.

func EnvironmentContext_IsDevelopment 

func EnvironmentContext_IsDevelopment(scope constructs.Construct) *bool

Check if Environment is part of `development` category.

Returns true for `development`, otherwise `false`.

Returns: boolean indicating does Environment belong to `development` category. Experimental.

func EnvironmentContext_IsFeature 

func EnvironmentContext_IsFeature(scope constructs.Construct) *bool

Check if Environment is part of `feature` category.

Returns `true` for environments with name beginning with `feature/`-prefix, otherwise `false`.

Returns: boolean indicating does Environment belong to `feature` category. Experimental.

func EnvironmentContext_IsMock 

func EnvironmentContext_IsMock(scope constructs.Construct) *bool

Check if Environment is part of `mock` category.

Returns: boolean indicating does Environment belong to `mock` category. Experimental.

func EnvironmentContext_IsStable 

func EnvironmentContext_IsStable(scope constructs.Construct) *bool

Check if Environment is part of `stable` category.

Returns `true` for `staging` & `production`, otherwise `false`.

Returns: boolean indicating does Environment belong to `stable` category. Experimental.

func EnvironmentContext_IsVerification 

func EnvironmentContext_IsVerification(scope constructs.Construct) *bool

Check if Environment is part of `verification` category.

Returns `true` for `test` & `preproduction`, otherwise `false`.

Returns: boolean indicating does Environment belong to `verification` category. Experimental.

func EnvironmentType_Get 

func EnvironmentType_Get(scope constructs.Construct, allowedEnvironments *[]*string) *string

Experimental.

func EnvironmentType_Set 

func EnvironmentType_Set(scope constructs.Construct, environmentType *string)

Experimental.

func EnvironmentType_TryGet 

func EnvironmentType_TryGet(scope constructs.Construct) *string

Experimental.

func EnvironmentWrapper_IsConstruct 

func EnvironmentWrapper_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func Name_Globally 

func Name_Globally(scope constructs.Construct, baseName *string, props *NameProps) *string

PascalCase naming with global prefixes (org, project…). Experimental.

func Name_It 

func Name_It(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func Name_WithProject 

func Name_WithProject(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func NewAccountContext_Override 

func NewAccountContext_Override(a AccountContext)

Experimental.

func NewAccountStrategy_Override 

func NewAccountStrategy_Override(a AccountStrategy)

Experimental.

func NewAccountType_Override 

func NewAccountType_Override(a AccountType)

Experimental.

func NewAccountWrapper_Override 

func NewAccountWrapper_Override(a AccountWrapper, scope constructs.Construct)

Experimental.

func NewEnvRegExp_Override 

func NewEnvRegExp_Override(e EnvRegExp, base *string)

Experimental.

func NewEnvironmentContext_Override 

func NewEnvironmentContext_Override(e EnvironmentContext)

Experimental.

func NewEnvironmentType_Override 

func NewEnvironmentType_Override(e EnvironmentType)

Experimental.

func NewEnvironmentWrapper_Override 

func NewEnvironmentWrapper_Override(e EnvironmentWrapper, scope constructs.Construct)

Experimental.

func NewName_Override 

func NewName_Override(n Name)

Experimental.

func NewPathName_Override 

func NewPathName_Override(p PathName)

Experimental.

func NewProjectContext_Override 

func NewProjectContext_Override(p ProjectContext)

Experimental.

func NewProject_Override 

func NewProject_Override(p Project, props *ProjectProps)

Initializes a new Project (which can be used in place of cdk.App). Experimental.

func NewSmartStack_Override 

func NewSmartStack_Override(s SmartStack, scope constructs.Construct, id *string, props *awscdk.StackProps)

Experimental.

func NewUrlName_Override 

func NewUrlName_Override(u UrlName)

Experimental.

func PathName_Globally 

func PathName_Globally(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func PathName_It 

func PathName_It(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func PathName_WithProject 

func PathName_WithProject(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func ProjectContext_GetAccountConfig 

func ProjectContext_GetAccountConfig(scope constructs.Construct, key *string, defaultValue interface{}) interface{}

Experimental.

func ProjectContext_GetAccountId 

func ProjectContext_GetAccountId(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetAccountType 

func ProjectContext_GetAccountType(scope constructs.Construct) *string

Returns the account type given in runtime/CLI context. Experimental.

func ProjectContext_GetAllowedEnvironments 

func ProjectContext_GetAllowedEnvironments(scope constructs.Construct) *[]*string

Experimental.

func ProjectContext_GetAuthorEmail 

func ProjectContext_GetAuthorEmail(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetAuthorName 

func ProjectContext_GetAuthorName(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetAuthorOrganization 

func ProjectContext_GetAuthorOrganization(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetDefaultRegion 

func ProjectContext_GetDefaultRegion(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetEnvironment 

func ProjectContext_GetEnvironment(scope constructs.Construct) *string

Experimental.

func ProjectContext_GetName 

func ProjectContext_GetName(scope constructs.Construct) *string

Experimental.

func ProjectContext_TryGetEnvironment 

func ProjectContext_TryGetEnvironment(scope constructs.Construct) *string

Experimental.

func Project_CONTEXT_SCOPE 

func Project_CONTEXT_SCOPE() *string

func Project_IsApp 

func Project_IsApp(obj interface{}) *bool

Checks if an object is an instance of the `App` class.

Returns: `true` if `obj` is an `App`. Experimental.

func Project_IsConstruct 

func Project_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func Project_IsStage 

func Project_IsStage(x interface{}) *bool

Test whether the given construct is a stage. Experimental.

func Project_Of 

func Project_Of(construct constructs.IConstruct) awscdk.Stage

Return the stage this construct is contained with, if available.

If called on a nested stage, returns its parent. Experimental.

func SmartStack_IsConstruct 

func SmartStack_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func SmartStack_IsStack 

func SmartStack_IsStack(x interface{}) *bool

Return whether the given object is a Stack.

We do attribute detection since we can't reliably use 'instanceof'. Experimental.

func SmartStack_Of 

func SmartStack_Of(construct constructs.IConstruct) awscdk.Stack

Looks up the first stack scope in which `construct` is defined.

Fails if there is no stack up the tree. Experimental.

func UrlName_Globally 

func UrlName_Globally(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func UrlName_It 

func UrlName_It(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

func UrlName_WithProject 

func UrlName_WithProject(scope constructs.Construct, baseName *string, props *NameProps) *string

Experimental.

Types

type Account 

type Account struct {
	// AWS Account ID.
	//
	// Example:
	//   '123456789012'
	//
	// Experimental.
	Id *string `field:"required" json:"id" yaml:"id"`
	// AWS account specific configuration.
	//
	// For example VPC IDs (for existing VPCs), Direct Connect Gateway IDs, apex domain names (for Route53 Zone lookups), etc. Basically configuration for resources that are defined outside of this CDK application.
	//
	// Example:
	//   {
	//     dev: {
	//       id: '111111111111',
	//       config: {
	//         baseDomain: 'example.net',
	//       },
	//     },
	//     prod: {
	//       id: '222222222222',
	//       config: {
	//         baseDomain: 'example.com',
	//       },
	//     },
	//   },
	//
	// Experimental.
	Config *map[string]interface{} `field:"optional" json:"config" yaml:"config"`
	// List of accepted environments for the given account.
	//
	// List of strings or strings representing regexp initialization (passed onto `new Regexp("^"+environment+"$", "i")`).
	//
	// Example:
	//   ["development", "feature/.*"]
	//
	// Experimental.
	Environments *[]*string `field:"optional" json:"environments" yaml:"environments"`
}

AWS account configuration. Experimental.

func Project_GetAccount 

func Project_GetAccount(scope constructs.Construct, accountType *string) *Account

Return account configuration. Experimental.

type AccountConfiguration 

type AccountConfiguration struct {
	// Experimental.
	Id *string `field:"required" json:"id" yaml:"id"`
	// Experimental.
	Config *map[string]interface{} `field:"optional" json:"config" yaml:"config"`
}

Interface for a single account type configuration. Experimental.

type AccountContext 

type AccountContext interface {
}

Experimental.

func NewAccountContext 

func NewAccountContext() AccountContext

Experimental.

type AccountStrategy 

type AccountStrategy interface {
}

Use static methods of `AccountStrategy` abstract class to define your account strategy.

Available strategies are: - One Account: `shared` - Two Accounts: `dev`+`prod` – _recommended_ - Three Accounts: `dev`+`preprod`+`prod`. Experimental.

type AccountStrategyOneProps 

type AccountStrategyOneProps struct {
	// Experimental.
	Shared *AccountConfiguration `field:"required" json:"shared" yaml:"shared"`
	// Experimental.
	Mock *AccountConfiguration `field:"optional" json:"mock" yaml:"mock"`
}

Props `AccountStrategy.one`. Experimental.

type AccountStrategyThreeProps 

type AccountStrategyThreeProps struct {
	// Experimental.
	Dev *AccountConfiguration `field:"required" json:"dev" yaml:"dev"`
	// Experimental.
	Preprod *AccountConfiguration `field:"required" json:"preprod" yaml:"preprod"`
	// Experimental.
	Prod *AccountConfiguration `field:"required" json:"prod" yaml:"prod"`
	// Experimental.
	Mock *AccountConfiguration `field:"optional" json:"mock" yaml:"mock"`
}

Props `AccountStrategy.three`. Experimental.

type AccountStrategyTwoProps 

type AccountStrategyTwoProps struct {
	// Experimental.
	Dev *AccountConfiguration `field:"required" json:"dev" yaml:"dev"`
	// Experimental.
	Prod *AccountConfiguration `field:"required" json:"prod" yaml:"prod"`
	// Experimental.
	Mock *AccountConfiguration `field:"optional" json:"mock" yaml:"mock"`
}

Props `AccountStrategy.two`. Experimental.

type AccountType 

type AccountType interface {
}

Internal class to handle set/get operations for Account Type. Experimental.

func NewAccountType 

func NewAccountType() AccountType

Experimental.

type AccountWrapper 

type AccountWrapper interface {
	constructs.Construct
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Wrapper for account-level stacks. Experimental.

func NewAccountWrapper 

func NewAccountWrapper(scope constructs.Construct) AccountWrapper

Experimental.

type Author 

type Author struct {
	// Human-readable name for the team/contact responsible for this project/service.
	//
	// Example:
	//   'Mad Scientists'
	//
	// Experimental.
	Name *string `field:"required" json:"name" yaml:"name"`
	// Email address for the team/contact responsible for this project/service.
	//
	// Example:
	//   'mad.scientists@acme.example.com'
	//
	// Experimental.
	Email *string `field:"optional" json:"email" yaml:"email"`
	// Human-readable name for the organization responsible for this project/service.
	//
	// Example:
	//   'Acme Corp'
	//
	// Experimental.
	Organization *string `field:"optional" json:"organization" yaml:"organization"`
}

Author information.

I.e. who owns/develops this project/service. Experimental.

type EnvRegExp 

type EnvRegExp interface {
	// Experimental.
	Test(value *string) *bool
}

Experimental.

func NewEnvRegExp 

func NewEnvRegExp(base *string) EnvRegExp

Experimental.

type EnvironmentCategory 

type EnvironmentCategory string

Availalbe Enviroment Categories.

Categories are useful grouping to make distinction between `stable` environments (`staging` & `production`) from `feature` or `verification` environments (such as `test` or `preproduction`). Experimental. 

const (
	// Experimental.
	EnvironmentCategory_MOCK EnvironmentCategory = "MOCK"
	// Experimental.
	EnvironmentCategory_DEVELOPMENT EnvironmentCategory = "DEVELOPMENT"
	// Experimental.
	EnvironmentCategory_FEATURE EnvironmentCategory = "FEATURE"
	// Experimental.
	EnvironmentCategory_VERIFICATION EnvironmentCategory = "VERIFICATION"
	// Experimental.
	EnvironmentCategory_STABLE EnvironmentCategory = "STABLE"
)

func EnvironmentContext_GetCategory 

func EnvironmentContext_GetCategory(scope constructs.Construct) EnvironmentCategory

Get Environment Category.

Categories are useful grouping to make distinction between `stable` environments (`staging` & `production`) from `feature` or `verification` environments (such as `test` or `preproduction`).

Returns: Environment Category.

Example: 

'mock'
'development'
'feature'
'verification'
'stable'

Experimental.

type EnvironmentContext 

type EnvironmentContext interface {
}

Experimental.

func NewEnvironmentContext 

func NewEnvironmentContext() EnvironmentContext

Experimental.

type EnvironmentLabel 

type EnvironmentLabel string

Available Environment Labels.

Labels are useful since Environment Name can be complex, such as `feature/foo-bar` or `qa3`, but we need to be able to “label” all `feature/*` and `qaN` environments as either `feature` or `qa`. Experimental. 

const (
	// Experimental.
	EnvironmentLabel_MOCK EnvironmentLabel = "MOCK"
	// Experimental.
	EnvironmentLabel_DEVELOPMENT EnvironmentLabel = "DEVELOPMENT"
	// Experimental.
	EnvironmentLabel_FEATURE EnvironmentLabel = "FEATURE"
	// Experimental.
	EnvironmentLabel_TEST EnvironmentLabel = "TEST"
	// Experimental.
	EnvironmentLabel_STAGING EnvironmentLabel = "STAGING"
	// Experimental.
	EnvironmentLabel_QA EnvironmentLabel = "QA"
	// Experimental.
	EnvironmentLabel_PREPRODUCTION EnvironmentLabel = "PREPRODUCTION"
	// Experimental.
	EnvironmentLabel_PRODUCTION EnvironmentLabel = "PRODUCTION"
)

func EnvironmentContext_GetLabel 

func EnvironmentContext_GetLabel(scope constructs.Construct) EnvironmentLabel

Get Environment Label.

Labels are useful since Environment Name can be complex, such as `feature/foo-bar` or `qa3`, but we need to be able to “label” all `feature/*` and `qaN` environments as either `feature` or `qa`.

Returns: Environment Label.

Example: 

'mock'
'development'
'feature'
'test'
'staging'
'qa'
'preproduction'
'production'

Experimental.

type EnvironmentType 

type EnvironmentType interface {
}

Internal class to handle set/get operations for Environment Type. Experimental.

func NewEnvironmentType 

func NewEnvironmentType() EnvironmentType

Experimental.

type EnvironmentWrapper 

type EnvironmentWrapper interface {
	constructs.Construct
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Wrapper for environmental stacks. Experimental.

func NewEnvironmentWrapper 

func NewEnvironmentWrapper(scope constructs.Construct) EnvironmentWrapper

Experimental.

type Name 

type Name interface {
}

Experimental.

type NameProps 

type NameProps struct {
	// Experimental.
	MaxLength *float64 `field:"optional" json:"maxLength" yaml:"maxLength"`
	// Experimental.
	Trim *bool `field:"optional" json:"trim" yaml:"trim"`
}

Experimental.

type PathName 

type PathName interface {
	UrlName
}

Experimental.

type Project 

type Project interface {
	awscdk.App
	// The default account for all resources defined within this stage.
	// Experimental.
	Account() *string
	// Artifact ID of the assembly if it is a nested stage. The root stage (app) will return an empty string.
	//
	// Derived from the construct path.
	// Experimental.
	ArtifactId() *string
	// The cloud assembly asset output directory.
	// Experimental.
	AssetOutdir() *string
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// The cloud assembly output directory.
	// Experimental.
	Outdir() *string
	// The parent stage or `undefined` if this is the app.
	//
	// *.
	// Experimental.
	ParentStage() awscdk.Stage
	// The default region for all resources defined within this stage.
	// Experimental.
	Region() *string
	// The name of the stage.
	//
	// Based on names of the parent stages separated by
	// hypens.
	// Experimental.
	StageName() *string
	// Synthesize this stage into a cloud assembly.
	//
	// Once an assembly has been synthesized, it cannot be modified. Subsequent
	// calls will return the same assembly.
	// Experimental.
	Synth(options *awscdk.StageSynthesisOptions) cxapi.CloudAssembly
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

High-level wrapper for `cdk.App` with specific requirements for props.

Use it like you would `cdk.App` and assign stacks into it.

Example: 

// new Project instead of new App
const project = new Project({
  name: 'my-cool-project',
  author: {
    organization: 'Acme Corp',
    name: 'Mad Scientists',
    email: 'mad.scientists@acme.example.com',
},
defaultRegion: 'eu-west-1', // defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1
accounts: {
dev: {
 id: '111111111111',
 environments: ['development', 'feature/.*', 'staging'],
 config: {
   baseDomain: 'example.net',
 },
},
prod: {
 id: '222222222222',
 environments: ['production'],
 config: {
   baseDomain: 'example.com',
 },
},
},
})

Experimental.

func NewProject 

func NewProject(props *ProjectProps) Project

Initializes a new Project (which can be used in place of cdk.App). Experimental.

type ProjectConfiguration 

type ProjectConfiguration struct {
	// Dictionary of AWS account specific configuration.
	//
	// The key value can be anything (such as AWS Account alias), but it's recommended to keep it short such as `dev` or `prod`.
	//
	// Example:
	//   accounts: {
	//     dev: {
	//       id: '111111111111',
	//       config: {
	//         baseDomain: 'example.net',
	//       },
	//     },
	//     prod: {
	//       id: '222222222222',
	//       config: {
	//         baseDomain: 'example.com',
	//       },
	//     },
	//   },
	//
	// Experimental.
	Accounts *map[string]*Account `field:"required" json:"accounts" yaml:"accounts"`
	// Author information.
	//
	// I.e. who owns/develops this project/service.
	// Experimental.
	Author *Author `field:"required" json:"author" yaml:"author"`
	// Name of your project/service.
	//
	// Prefer `hyphen-case`.
	//
	// Example:
	//   'my-cool-project'
	//
	// Experimental.
	Name *string `field:"required" json:"name" yaml:"name"`
	// Specify default region you wish to use.
	//
	// If left empty will default to one of the following in order:
	// 1. `$CDK_DEFAULT_REGION`
	// 2. `$AWS_REGION`
	// 3. 'us-east-1'
	// Experimental.
	DefaultRegion *string `field:"optional" json:"defaultRegion" yaml:"defaultRegion"`
}

Experimental.

func Project_GetConfiguration 

func Project_GetConfiguration(scope constructs.Construct) *ProjectConfiguration

Return the project configuration as given in ProjectProps. Experimental.

type ProjectContext 

type ProjectContext interface {
}

Experimental.

func NewProjectContext 

func NewProjectContext() ProjectContext

Experimental.

type ProjectProps 

type ProjectProps struct {
	// Dictionary of AWS account specific configuration.
	//
	// The key value can be anything (such as AWS Account alias), but it's recommended to keep it short such as `dev` or `prod`.
	//
	// Example:
	//   accounts: {
	//     dev: {
	//       id: '111111111111',
	//       config: {
	//         baseDomain: 'example.net',
	//       },
	//     },
	//     prod: {
	//       id: '222222222222',
	//       config: {
	//         baseDomain: 'example.com',
	//       },
	//     },
	//   },
	//
	// Experimental.
	Accounts *map[string]*Account `field:"required" json:"accounts" yaml:"accounts"`
	// Author information.
	//
	// I.e. who owns/develops this project/service.
	// Experimental.
	Author *Author `field:"required" json:"author" yaml:"author"`
	// Name of your project/service.
	//
	// Prefer `hyphen-case`.
	//
	// Example:
	//   'my-cool-project'
	//
	// Experimental.
	Name *string `field:"required" json:"name" yaml:"name"`
	// Specify default region you wish to use.
	//
	// If left empty will default to one of the following in order:
	// 1. `$CDK_DEFAULT_REGION`
	// 2. `$AWS_REGION`
	// 3. 'us-east-1'
	// Experimental.
	DefaultRegion *string `field:"optional" json:"defaultRegion" yaml:"defaultRegion"`
	// Include runtime versioning information in the Stacks of this app.
	// Experimental.
	AnalyticsReporting *bool `field:"optional" json:"analyticsReporting" yaml:"analyticsReporting"`
	// Automatically call `synth()` before the program exits.
	//
	// If you set this, you don't have to call `synth()` explicitly. Note that
	// this feature is only available for certain programming languages, and
	// calling `synth()` is still recommended.
	// Experimental.
	AutoSynth *bool `field:"optional" json:"autoSynth" yaml:"autoSynth"`
	// Additional context values for the application.
	//
	// Context set by the CLI or the `context` key in `cdk.json` has precedence.
	//
	// Context can be read from any construct using `node.getContext(key)`.
	// Experimental.
	Context *map[string]interface{} `field:"optional" json:"context" yaml:"context"`
	// The output directory into which to emit synthesized artifacts.
	//
	// You should never need to set this value. By default, the value you pass to
	// the CLI's `--output` flag will be used, and if you change it to a different
	// directory the CLI will fail to pick up the generated Cloud Assembly.
	//
	// This property is intended for internal and testing use.
	// Experimental.
	Outdir *string `field:"optional" json:"outdir" yaml:"outdir"`
	// Include construct creation stack trace in the `aws:cdk:trace` metadata key of all constructs.
	// Experimental.
	StackTraces *bool `field:"optional" json:"stackTraces" yaml:"stackTraces"`
	// Include construct tree metadata as part of the Cloud Assembly.
	// Experimental.
	TreeMetadata *bool `field:"optional" json:"treeMetadata" yaml:"treeMetadata"`
}

Props given to `Project`.

I.e. custom props for this construct and the usual props given to `cdk.App`. Experimental.

type SmartStack 

type SmartStack interface {
	awscdk.Stack
	// The AWS account into which this stack will be deployed.
	//
	// This value is resolved according to the following rules:
	//
	// 1. The value provided to `env.account` when the stack is defined. This can
	//     either be a concerete account (e.g. `585695031111`) or the
	//     `Aws.accountId` token.
	// 3. `Aws.accountId`, which represents the CloudFormation intrinsic reference
	//     `{ "Ref": "AWS::AccountId" }` encoded as a string token.
	//
	// Preferably, you should use the return value as an opaque string and not
	// attempt to parse it to implement your logic. If you do, you must first
	// check that it is a concerete value an not an unresolved token. If this
	// value is an unresolved token (`Token.isUnresolved(stack.account)` returns
	// `true`), this implies that the user wishes that this stack will synthesize
	// into a **account-agnostic template**. In this case, your code should either
	// fail (throw an error, emit a synth error using `Annotations.of(construct).addError()`) or
	// implement some other region-agnostic behavior.
	// Experimental.
	Account() *string
	// The ID of the cloud assembly artifact for this stack.
	// Experimental.
	ArtifactId() *string
	// Returns the list of AZs that are available in the AWS environment (account/region) associated with this stack.
	//
	// If the stack is environment-agnostic (either account and/or region are
	// tokens), this property will return an array with 2 tokens that will resolve
	// at deploy-time to the first two availability zones returned from CloudFormation's
	// `Fn::GetAZs` intrinsic function.
	//
	// If they are not available in the context, returns a set of dummy values and
	// reports them as missing, and let the CLI resolve them by calling EC2
	// `DescribeAvailabilityZones` on the target environment.
	//
	// To specify a different strategy for selecting availability zones override this method.
	// Experimental.
	AvailabilityZones() *[]*string
	// Indicates whether the stack requires bundling or not.
	// Experimental.
	BundlingRequired() *bool
	// Return the stacks this stack depends on.
	// Experimental.
	Dependencies() *[]awscdk.Stack
	// The environment coordinates in which this stack is deployed.
	//
	// In the form
	// `aws://account/region`. Use `stack.account` and `stack.region` to obtain
	// the specific values, no need to parse.
	//
	// You can use this value to determine if two stacks are targeting the same
	// environment.
	//
	// If either `stack.account` or `stack.region` are not concrete values (e.g.
	// `Aws.account` or `Aws.region`) the special strings `unknown-account` and/or
	// `unknown-region` will be used respectively to indicate this stack is
	// region/account-agnostic.
	// Experimental.
	Environment() *string
	// Indicates if this is a nested stack, in which case `parentStack` will include a reference to it's parent.
	// Experimental.
	Nested() *bool
	// If this is a nested stack, returns it's parent stack.
	// Experimental.
	NestedStackParent() awscdk.Stack
	// If this is a nested stack, this represents its `AWS::CloudFormation::Stack` resource.
	//
	// `undefined` for top-level (non-nested) stacks.
	// Experimental.
	NestedStackResource() awscdk.CfnResource
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns the list of notification Amazon Resource Names (ARNs) for the current stack.
	// Experimental.
	NotificationArns() *[]*string
	// The partition in which this stack is defined.
	// Experimental.
	Partition() *string
	// The AWS region into which this stack will be deployed (e.g. `us-west-2`).
	//
	// This value is resolved according to the following rules:
	//
	// 1. The value provided to `env.region` when the stack is defined. This can
	//     either be a concerete region (e.g. `us-west-2`) or the `Aws.region`
	//     token.
	// 3. `Aws.region`, which is represents the CloudFormation intrinsic reference
	//     `{ "Ref": "AWS::Region" }` encoded as a string token.
	//
	// Preferably, you should use the return value as an opaque string and not
	// attempt to parse it to implement your logic. If you do, you must first
	// check that it is a concerete value an not an unresolved token. If this
	// value is an unresolved token (`Token.isUnresolved(stack.region)` returns
	// `true`), this implies that the user wishes that this stack will synthesize
	// into a **region-agnostic template**. In this case, your code should either
	// fail (throw an error, emit a synth error using `Annotations.of(construct).addError()`) or
	// implement some other region-agnostic behavior.
	// Experimental.
	Region() *string
	// The ID of the stack.
	//
	// Example:
	//   // After resolving, looks like
	//   'arn:aws:cloudformation:us-west-2:123456789012:stack/teststack/51af3dc0-da77-11e4-872e-1234567db123'
	//
	// Experimental.
	StackId() *string
	// The concrete CloudFormation physical stack name.
	//
	// This is either the name defined explicitly in the `stackName` prop or
	// allocated based on the stack's location in the construct tree. Stacks that
	// are directly defined under the app use their construct `id` as their stack
	// name. Stacks that are defined deeper within the tree will use a hashed naming
	// scheme based on the construct path to ensure uniqueness.
	//
	// If you wish to obtain the deploy-time AWS::StackName intrinsic,
	// you can use `Aws.stackName` directly.
	// Experimental.
	StackName() *string
	// Synthesis method for this stack.
	// Experimental.
	Synthesizer() awscdk.IStackSynthesizer
	// Tags to be applied to the stack.
	// Experimental.
	Tags() awscdk.TagManager
	// The name of the CloudFormation template file emitted to the output directory during synthesis.
	//
	// Example value: `MyStack.template.json`
	// Experimental.
	TemplateFile() *string
	// Options for CloudFormation template (like version, transform, description).
	// Experimental.
	TemplateOptions() awscdk.ITemplateOptions
	// Whether termination protection is enabled for this stack.
	// Experimental.
	TerminationProtection() *bool
	// The Amazon domain suffix for the region in which this stack is defined.
	// Experimental.
	UrlSuffix() *string
	// Add a dependency between this stack and another stack.
	//
	// This can be used to define dependencies between any two stacks within an
	// app, and also supports nested stacks.
	// Experimental.
	AddDependency(target awscdk.Stack, reason *string)
	// Add a Transform to this stack. A Transform is a macro that AWS CloudFormation uses to process your template.
	//
	// Duplicate values are removed when stack is synthesized.
	//
	// Example:
	//   declare const stack: Stack;
	//
	//   stack.addTransform('AWS::Serverless-2016-10-31')
	//
	// See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html
	//
	// Experimental.
	AddTransform(transform *string)
	// Returns the naming scheme used to allocate logical IDs.
	//
	// By default, uses
	// the `HashedAddressingScheme` but this method can be overridden to customize
	// this behavior.
	//
	// In order to make sure logical IDs are unique and stable, we hash the resource
	// construct tree path (i.e. toplevel/secondlevel/.../myresource) and add it as
	// a suffix to the path components joined without a separator (CloudFormation
	// IDs only allow alphanumeric characters).
	//
	// The result will be:
	//
	//    <path.join(”)><md5(path.join('/')>
	//      "human"      "hash"
	//
	// If the "human" part of the ID exceeds 240 characters, we simply trim it so
	// the total ID doesn't exceed CloudFormation's 255 character limit.
	//
	// We only take 8 characters from the md5 hash (0.000005 chance of collision).
	//
	// Special cases:
	//
	// - If the path only contains a single component (i.e. it's a top-level
	//    resource), we won't add the hash to it. The hash is not needed for
	//    disamiguation and also, it allows for a more straightforward migration an
	//    existing CloudFormation template to a CDK stack without logical ID changes
	//    (or renames).
	// - For aesthetic reasons, if the last components of the path are the same
	//    (i.e. `L1/L2/Pipeline/Pipeline`), they will be de-duplicated to make the
	//    resulting human portion of the ID more pleasing: `L1L2Pipeline<HASH>`
	//    instead of `L1L2PipelinePipeline<HASH>`
	// - If a component is named "Default" it will be omitted from the path. This
	//    allows refactoring higher level abstractions around constructs without affecting
	//    the IDs of already deployed resources.
	// - If a component is named "Resource" it will be omitted from the user-visible
	//    path, but included in the hash. This reduces visual noise in the human readable
	//    part of the identifier.
	// Experimental.
	AllocateLogicalId(cfnElement awscdk.CfnElement) *string
	// Create a CloudFormation Export for a value.
	//
	// Returns a string representing the corresponding `Fn.importValue()`
	// expression for this Export. You can control the name for the export by
	// passing the `name` option.
	//
	// If you don't supply a value for `name`, the value you're exporting must be
	// a Resource attribute (for example: `bucket.bucketName`) and it will be
	// given the same name as the automatic cross-stack reference that would be created
	// if you used the attribute in another Stack.
	//
	// One of the uses for this method is to *remove* the relationship between
	// two Stacks established by automatic cross-stack references. It will
	// temporarily ensure that the CloudFormation Export still exists while you
	// remove the reference from the consuming stack. After that, you can remove
	// the resource and the manual export.
	//
	// ## Example
	//
	// Here is how the process works. Let's say there are two stacks,
	// `producerStack` and `consumerStack`, and `producerStack` has a bucket
	// called `bucket`, which is referenced by `consumerStack` (perhaps because
	// an AWS Lambda Function writes into it, or something like that).
	//
	// It is not safe to remove `producerStack.bucket` because as the bucket is being
	// deleted, `consumerStack` might still be using it.
	//
	// Instead, the process takes two deployments:
	//
	// ### Deployment 1: break the relationship
	//
	// - Make sure `consumerStack` no longer references `bucket.bucketName` (maybe the consumer
	//    stack now uses its own bucket, or it writes to an AWS DynamoDB table, or maybe you just
	//    remove the Lambda Function altogether).
	// - In the `ProducerStack` class, call `this.exportValue(this.bucket.bucketName)`. This
	//    will make sure the CloudFormation Export continues to exist while the relationship
	//    between the two stacks is being broken.
	// - Deploy (this will effectively only change the `consumerStack`, but it's safe to deploy both).
	//
	// ### Deployment 2: remove the bucket resource
	//
	// - You are now free to remove the `bucket` resource from `producerStack`.
	// - Don't forget to remove the `exportValue()` call as well.
	// - Deploy again (this time only the `producerStack` will be changed -- the bucket will be deleted).
	// Experimental.
	ExportValue(exportedValue interface{}, options *awscdk.ExportValueOptions) *string
	// Creates an ARN from components.
	//
	// If `partition`, `region` or `account` are not specified, the stack's
	// partition, region and account will be used.
	//
	// If any component is the empty string, an empty string will be inserted
	// into the generated ARN at the location that component corresponds to.
	//
	// The ARN will be formatted as follows:
	//
	//    arn:{partition}:{service}:{region}:{account}:{resource}{sep}}{resource-name}
	//
	// The required ARN pieces that are omitted will be taken from the stack that
	// the 'scope' is attached to. If all ARN pieces are supplied, the supplied scope
	// can be 'undefined'.
	// Experimental.
	FormatArn(components *awscdk.ArnComponents) *string
	// Allocates a stack-unique CloudFormation-compatible logical identity for a specific resource.
	//
	// This method is called when a `CfnElement` is created and used to render the
	// initial logical identity of resources. Logical ID renames are applied at
	// this stage.
	//
	// This method uses the protected method `allocateLogicalId` to render the
	// logical ID for an element. To modify the naming scheme, extend the `Stack`
	// class and override this method.
	// Experimental.
	GetLogicalId(element awscdk.CfnElement) *string
	// Look up a fact value for the given fact for the region of this stack.
	//
	// Will return a definite value only if the region of the current stack is resolved.
	// If not, a lookup map will be added to the stack and the lookup will be done at
	// CDK deployment time.
	//
	// What regions will be included in the lookup map is controlled by the
	// `@aws-cdk/core:target-partitions` context value: it must be set to a list
	// of partitions, and only regions from the given partitions will be included.
	// If no such context key is set, all regions will be included.
	//
	// This function is intended to be used by construct library authors. Application
	// builders can rely on the abstractions offered by construct libraries and do
	// not have to worry about regional facts.
	//
	// If `defaultValue` is not given, it is an error if the fact is unknown for
	// the given region.
	// Experimental.
	RegionalFact(factName *string, defaultValue *string) *string
	// Rename a generated logical identities.
	//
	// To modify the naming scheme strategy, extend the `Stack` class and
	// override the `allocateLogicalId` method.
	// Experimental.
	RenameLogicalId(oldId *string, newId *string)
	// Indicate that a context key was expected.
	//
	// Contains instructions which will be emitted into the cloud assembly on how
	// the key should be supplied.
	// Experimental.
	ReportMissingContextKey(report *cloudassemblyschema.MissingContext)
	// Resolve a tokenized value in the context of the current stack.
	// Experimental.
	Resolve(obj interface{}) interface{}
	// Splits the provided ARN into its components.
	//
	// Works both if 'arn' is a string like 'arn:aws:s3:::bucket',
	// and a Token representing a dynamic CloudFormation expression
	// (in which case the returned components will also be dynamic CloudFormation expressions,
	// encoded as Tokens).
	// Experimental.
	SplitArn(arn *string, arnFormat awscdk.ArnFormat) *awscdk.ArnComponents
	// Convert an object, potentially containing tokens, to a JSON string.
	// Experimental.
	ToJsonString(obj interface{}, space *float64) *string
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Experimental.

func NewSmartStack 

func NewSmartStack(scope constructs.Construct, id *string, props *awscdk.StackProps) SmartStack

Experimental.

type UrlName 

type UrlName interface {
	Name
}

Experimental.

Source Files

View all Source files

Directories

Path Synopsis
Package jsii contains the functionaility needed for jsii packages to initialize their dependencies and themselves.
 Package jsii contains the functionaility needed for jsii packages to initialize their dependencies and themselves.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.