aws-cdk
- Version 2.111.0
- Published
- 58.8 MB
- 1 dependency
- Apache-2.0 license
Install
npm i aws-cdk
yarn add aws-cdk
pnpm add aws-cdk
Overview
CDK Toolkit, the command line tool for CDK apps
Index
Variables
Functions
Classes
SDK
- appendCustomUserAgent()
- appsync()
- cloudFormation()
- cloudWatchLogs()
- codeBuild()
- currentAccount()
- currentCredentials()
- currentRegion
- ec2()
- ecr()
- ecs()
- elbv2()
- forceCredentialRetrieval()
- getEndpointSuffix()
- iam()
- kms()
- lambda()
- removeCustomUserAgent()
- route53()
- s3()
- secretsManager()
- ssm()
- stepFunctions()
- validateCredentials()
Interfaces
Enums
Type Aliases
Variables
variable BOOTSTRAP_VARIANT_PARAMETER
const BOOTSTRAP_VARIANT_PARAMETER: string;
variable BOOTSTRAP_VERSION_OUTPUT
const BOOTSTRAP_VERSION_OUTPUT: string;
variable BOOTSTRAP_VERSION_RESOURCE
const BOOTSTRAP_VERSION_RESOURCE: string;
variable BUCKET_DOMAIN_NAME_OUTPUT
const BUCKET_DOMAIN_NAME_OUTPUT: string;
variable BUCKET_NAME_OUTPUT
const BUCKET_NAME_OUTPUT: string;
variable DEFAULT_BOOTSTRAP_VARIANT
const DEFAULT_BOOTSTRAP_VARIANT: string;
The assumed vendor of a template in case it is not set
variable DEFAULT_TOOLKIT_STACK_NAME
const DEFAULT_TOOLKIT_STACK_NAME: string;
variable REPOSITORY_NAME_OUTPUT
const REPOSITORY_NAME_OUTPUT: string;
Functions
function cli
cli: (args?: string[]) => void;
function defaultCliUserAgent
defaultCliUserAgent: () => string;
Find the package.json from the main toolkit.
If we can't read it for some reason, try to do something reasonable anyway. Fall back to argv[1], or a standard string if that is undefined for some reason.
function deployStack
deployStack: (options: DeployStackOptions) => Promise<DeployStackResult>;
function destroyStack
destroyStack: (options: DestroyStackOptions) => Promise<void>;
function exec
exec: (args: string[], synthesizer?: Synthesizer) => Promise<number | void>;
function isUnrecoverableAwsError
isUnrecoverableAwsError: (e: Error) => boolean;
Return whether an error should not be recovered from
function makeBodyParameterAndUpload
makeBodyParameterAndUpload: ( stack: cxapi.CloudFormationStackArtifact, resolvedEnvironment: cxapi.Environment, resources: EnvironmentResources, sdkProvider: SdkProvider, sdk: ISDK, overrideTemplate?: any) => Promise<TemplateBodyParameter>;
Prepare a body parameter for CFN, performing the upload
Return it as-is if it is small enough to pass in the API call, upload to S3 and return the coordinates if it is not.
Classes
class Bootstrapper
class Bootstrapper {}
constructor
constructor(source: BootstrapSource);
method bootstrapEnvironment
bootstrapEnvironment: ( environment: cxapi.Environment, sdkProvider: SdkProvider, options?: BootstrapEnvironmentOptions) => Promise<DeployStackResult>;
method showTemplate
showTemplate: (json: boolean) => Promise<void>;
class SDK
class SDK implements ISDK {}
Base functionality of SDK without credential fetching
constructor
constructor( _credentials: AWS.Credentials, region: string, httpOptions?: ConfigurationOptions, sdkOptions?: SdkOptions);
property currentRegion
readonly currentRegion: string;
method appendCustomUserAgent
appendCustomUserAgent: (userAgentData?: string) => void;
method appsync
appsync: () => AWS.AppSync;
method cloudFormation
cloudFormation: () => AWS.CloudFormation;
method cloudWatchLogs
cloudWatchLogs: () => AWS.CloudWatchLogs;
method codeBuild
codeBuild: () => AWS.CodeBuild;
method currentAccount
currentAccount: () => Promise<Account>;
method currentCredentials
currentCredentials: () => Promise<AWS.Credentials>;
Return the current credentials
Don't use -- only used to write tests around assuming roles.
method ec2
ec2: () => AWS.EC2;
method ecr
ecr: () => AWS.ECR;
method ecs
ecs: () => AWS.ECS;
method elbv2
elbv2: () => AWS.ELBv2;
method forceCredentialRetrieval
forceCredentialRetrieval: () => Promise<void>;
Force retrieval of the current credentials
Relevant if the current credentials are AssumeRole credentials -- do the actual lookup, and translate any error into a useful error message (taking into account credential provenance).
method getEndpointSuffix
getEndpointSuffix: (region: string) => string;
method iam
iam: () => AWS.IAM;
method kms
kms: () => AWS.KMS;
method lambda
lambda: () => AWS.Lambda;
method removeCustomUserAgent
removeCustomUserAgent: (userAgentData: string) => void;
method route53
route53: () => AWS.Route53;
method s3
s3: () => AWS.S3;
method secretsManager
secretsManager: () => AWS.SecretsManager;
method ssm
ssm: () => AWS.SSM;
method stepFunctions
stepFunctions: () => AWS.StepFunctions;
method validateCredentials
validateCredentials: () => Promise<void>;
Make sure the the current credentials are not expired
class SdkProvider
class SdkProvider {}
Creates instances of the AWS SDK appropriate for a given account/region.
Behavior is as follows:
- First, a set of "base" credentials are established - If a target environment is given and the default ("current") SDK credentials are for that account, return those; otherwise - If a target environment is given, scan all credential provider plugins for credentials, and return those if found; otherwise - Return default ("current") SDK credentials, noting that they might be wrong.
- Second, a role may optionally need to be assumed. Use the base credentials established in the previous process to assume that role. - If assuming the role fails and the base credentials are for the correct account, return those. This is a fallback for people who are trying to interact with a Default Synthesized stack and already have right credentials setup.
Typical cases we see in the wild: - Credential plugin setup that, although not recommended, works for them - Seeded terminal with
ReadOnly
credentials in order to docdk diff
--theReadOnly
role doesn't havests:AssumeRole
and will fail for no real good reason.
constructor
constructor( defaultChain: AWS.CredentialProviderChain, defaultRegion: string, sdkOptions?: ConfigurationOptions);
property defaultRegion
readonly defaultRegion: string;
Default region
method baseCredentialsPartition
baseCredentialsPartition: ( environment: cxapi.Environment, mode: Mode) => Promise<string | undefined>;
Return the partition that base credentials are for
Returns
undefined
if there are no base credentials.
method defaultAccount
defaultAccount: () => Promise<Account | undefined>;
The account we'd auth into if we used default credentials.
Default credentials are the set of ambiently configured credentials using one of the environment variables, or ~/.aws/credentials, or the *one* profile that was passed into the CLI.
Might return undefined if there are no default/ambient credentials available (in which case the user should better hope they have credential plugins configured).
Uses a cache to avoid STS calls if we don't need 'em.
method forEnvironment
forEnvironment: ( environment: cxapi.Environment, mode: Mode, options?: CredentialsOptions, quiet?: boolean) => Promise<SdkForEnvironment>;
Return an SDK which can do operations in the given environment
The
environment
parameter is resolved first (seeresolveEnvironment()
).
method resolveEnvironment
resolveEnvironment: (env: cxapi.Environment) => Promise<cxapi.Environment>;
Resolve the environment for a stack
Replaces the magic values
UNKNOWN_REGION
andUNKNOWN_ACCOUNT
with the defaults for the current SDK configuration (~/.aws/config
or otherwise).It is an error if
UNKNOWN_ACCOUNT
is used but the user hasn't configured any SDK credentials.
method withAwsCliCompatibleDefaults
static withAwsCliCompatibleDefaults: ( options?: SdkProviderOptions) => Promise<SdkProvider>;
Create a new SdkProvider which gets its defaults in a way that behaves like the AWS CLI does
The AWS SDK for JS behaves slightly differently from the AWS CLI in a number of ways; see the class
AwsCliCompatible
for the details.
class ToolkitInfo
abstract class ToolkitInfo {}
Information on the Bootstrap stack of the environment we're deploying to.
This class serves to:
- Inspect the bootstrap stack, and return various properties of it for successful asset deployment (in case of legacy-synthesized stacks). - Validate the version of the target environment, and nothing else (in case of default-synthesized stacks).
An object of this type might represent a bootstrap stack that could not be found. This is not an issue unless any members are used that require the bootstrap stack to have been found, in which case an error is thrown (default-synthesized stacks should never run into this as they don't need information from the bootstrap stack, all information is already encoded into the Cloud Assembly Manifest).
Nevertheless, an instance of this class exists to serve as a cache for SSM parameter lookups (otherwise, the "bootstrap stack version" parameter would need to be read repeatedly).
Called "ToolkitInfo" for historical reasons.
constructor
constructor();
property bootstrapStack
abstract readonly bootstrapStack: CloudFormationStack;
property bucketName
abstract readonly bucketName: string;
property bucketUrl
abstract readonly bucketUrl: string;
property found
abstract readonly found: boolean;
property stackName
abstract readonly stackName: string;
property variant
abstract readonly variant: string;
property version
abstract readonly version: number;
method bootstrapStackLookupError
static bootstrapStackLookupError: (stackName: string, e: Error) => ToolkitInfo;
method bootstrapStackNotFoundInfo
static bootstrapStackNotFoundInfo: (stackName: string) => ToolkitInfo;
method determineName
static determineName: (overrideName?: string) => string;
method fromStack
static fromStack: (stack: CloudFormationStack) => ToolkitInfo;
method lookup
static lookup: ( environment: cxapi.Environment, sdk: ISDK, stackName: string | undefined) => Promise<ToolkitInfo>;
Interfaces
interface Account
interface Account {}
An AWS account
An AWS account always exists in only one partition. Usually we don't care about the partition, but when we need to form ARNs we do.
interface BootstrapEnvironmentOptions
interface BootstrapEnvironmentOptions {}
Options for the bootstrapEnvironment operation(s)
property execute
readonly execute?: boolean;
Whether to execute the changeset or only create it and leave it in review. true
property force
readonly force?: boolean;
property parameters
readonly parameters?: BootstrappingParameters;
property roleArn
readonly roleArn?: string;
property tags
readonly tags?: Tag[];
Tags for cdktoolkit stack.
- None.
property terminationProtection
readonly terminationProtection?: boolean;
Whether the stacks created by the bootstrap process should be protected from termination.
See Also
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html true
property toolkitStackName
readonly toolkitStackName?: string;
property usePreviousParameters
usePreviousParameters?: boolean;
Use previous values for unspecified parameters
If not set, all parameters must be specified for every deployment.
true
interface BootstrappingParameters
interface BootstrappingParameters {}
Parameters for the bootstrapping template
property bucketName
readonly bucketName?: string;
The name to be given to the CDK Bootstrap bucket.
- a name is generated by CloudFormation.
property cloudFormationExecutionPolicies
readonly cloudFormationExecutionPolicies?: string[];
The ARNs of the IAM managed policies that should be attached to the role performing CloudFormation deployments. In most cases, this will be the AdministratorAccess policy. At least one policy is required if
trustedAccounts
were passed.- the role will have no policies attached
property createCustomerMasterKey
readonly createCustomerMasterKey?: boolean;
Whether or not to create a new customer master key (CMK)
Only applies to modern bootstrapping. Legacy bootstrapping will never create a CMK, only use the default S3 key.
false
property customPermissionsBoundary
readonly customPermissionsBoundary?: string;
Name for the customer's custom permissions boundary for bootstrapping
- No value, optional argument
property examplePermissionsBoundary
readonly examplePermissionsBoundary?: boolean;
Flag for using the default permissions boundary for bootstrapping
- No value, optional argument
property kmsKeyId
readonly kmsKeyId?: string;
The ID of an existing KMS key to be used for encrypting items in the bucket.
- use the default KMS key or create a custom one
property publicAccessBlockConfiguration
readonly publicAccessBlockConfiguration?: boolean;
Whether or not to enable S3 Staging Bucket Public Access Block Configuration
true
property qualifier
readonly qualifier?: string;
Identifier to distinguish multiple bootstrapped environments
- Default qualifier
property trustedAccounts
readonly trustedAccounts?: string[];
The list of AWS account IDs that are trusted to deploy into the environment being bootstrapped.
- only the bootstrapped account can deploy into this environment
property trustedAccountsForLookup
readonly trustedAccountsForLookup?: string[];
The list of AWS account IDs that are trusted to look up values in the environment being bootstrapped.
- only the bootstrapped account can look up values in this environment
interface ChangeSetDeploymentMethod
interface ChangeSetDeploymentMethod {}
property changeSetName
readonly changeSetName?: string;
Optional name to use for the CloudFormation change set. If not provided, a name will be generated automatically.
property execute
readonly execute?: boolean;
Whether to execute the changeset or leave it in review.
true
property method
readonly method: 'change-set';
interface CredentialsOptions
interface CredentialsOptions {}
Options for obtaining credentials for an environment
property assumeRoleArn
readonly assumeRoleArn?: string;
The ARN of the role that needs to be assumed, if any
property assumeRoleExternalId
readonly assumeRoleExternalId?: string;
External ID required to assume the given role.
interface DeployStackOptions
interface DeployStackOptions {}
property assetParallelism
readonly assetParallelism?: boolean;
Whether to build/publish assets in parallel
true To remain backward compatible.
property ci
readonly ci?: boolean;
Whether we are on a CI system
false
property deploymentMethod
readonly deploymentMethod?: DeploymentMethod;
What deployment method to use
- Change set with defaults
property deployName
readonly deployName?: string;
Name to deploy the stack under
- Name from assembly
property envResources
readonly envResources: EnvironmentResources;
Information about the bootstrap stack found in the target environment
property extraUserAgent
readonly extraUserAgent?: string;
The extra string to append to the User-Agent header when performing AWS SDK calls.
- nothing extra is appended to the User-Agent header
property force
readonly force?: boolean;
Deploy even if the deployed template is identical to the one we are about to deploy. false
property hotswap
readonly hotswap?: HotswapMode;
property notificationArns
readonly notificationArns?: string[];
Notification ARNs to pass to CloudFormation to notify when the change set has completed
- No notifications
property overrideTemplate
readonly overrideTemplate?: any;
If present, use this given template instead of the stored one
- Use the stored template
property parameters
readonly parameters?: { [name: string]: string | undefined;};
The collection of extra parameters (in addition to those used for assets) to pass to the deployed template. Note that parameters with
undefined
or empty values will be ignored, and not passed to the template.- no additional parameters will be passed to the template
property progress
readonly progress?: StackActivityProgress;
Display mode for stack deployment progress.
StackActivityProgress.Bar stack events will be displayed for the resource currently being deployed.
property quiet
readonly quiet?: boolean;
Quiet or verbose deployment
false
property resolvedEnvironment
readonly resolvedEnvironment: cxapi.Environment;
The environment to deploy this stack in
The environment on the stack artifact may be unresolved, this one must be resolved.
property resourcesToImport
readonly resourcesToImport?: ResourcesToImport;
If set, change set of type IMPORT will be created, and resourcesToImport passed to it.
property reuseAssets
readonly reuseAssets?: string[];
List of asset IDs which shouldn't be built
- Build all assets
property roleArn
readonly roleArn?: string;
Role to pass to CloudFormation to execute the change set
- Role specified on stack, otherwise current
property rollback
readonly rollback?: boolean;
Rollback failed deployments
true
property sdk
readonly sdk: ISDK;
The SDK to use for deploying the stack
Should have been initialized with the correct role with which stack operations should be performed.
property sdkProvider
readonly sdkProvider: SdkProvider;
SDK provider (seeded with default credentials)
Will exclusively be used to assume publishing credentials (which must start out from current credentials regardless of whether we've assumed an action role to touch the stack or not).
Used for the following purposes:
- Publish legacy assets. - Upload large CloudFormation templates to the staging bucket.
property stack
readonly stack: cxapi.CloudFormationStackArtifact;
The stack to be deployed
property tags
readonly tags?: Tag[];
Tags to pass to CloudFormation to add to stack
- No tags
property usePreviousParameters
readonly usePreviousParameters?: boolean;
Use previous values for unspecified parameters
If not set, all parameters must be specified for every deployment.
false
interface DeployStackResult
interface DeployStackResult {}
interface DestroyStackOptions
interface DestroyStackOptions {}
interface DirectDeploymentMethod
interface DirectDeploymentMethod {}
property method
readonly method: 'direct';
interface EcrCredentials
interface EcrCredentials {}
interface EcrRepositoryInfo
interface EcrRepositoryInfo {}
property repositoryUri
repositoryUri: string;
interface ISDK
interface ISDK {}
property currentRegion
readonly currentRegion: string;
The region this SDK has been instantiated for
(As distinct from the
defaultRegion()
on SdkProvider which represents the region configured in the default config).
method appendCustomUserAgent
appendCustomUserAgent: (userAgentData?: string) => void;
Appends the given string as the extra information to put into the User-Agent header for any requests invoked by this SDK. If the string is 'undefined', this method has no effect.
method appsync
appsync: () => AWS.AppSync;
method cloudFormation
cloudFormation: () => AWS.CloudFormation;
method cloudWatchLogs
cloudWatchLogs: () => AWS.CloudWatchLogs;
method codeBuild
codeBuild: () => AWS.CodeBuild;
method currentAccount
currentAccount: () => Promise<Account>;
The Account this SDK has been instantiated for
(As distinct from the
defaultAccount()
on SdkProvider which represents the account available by using default credentials).
method ec2
ec2: () => AWS.EC2;
method ecr
ecr: () => AWS.ECR;
method ecs
ecs: () => AWS.ECS;
method elbv2
elbv2: () => AWS.ELBv2;
method getEndpointSuffix
getEndpointSuffix: (region: string) => string;
method iam
iam: () => AWS.IAM;
method kms
kms: () => AWS.KMS;
method lambda
lambda: () => AWS.Lambda;
method removeCustomUserAgent
removeCustomUserAgent: (userAgentData: string) => void;
Removes the given string from the extra User-Agent header data used for requests invoked by this SDK.
method route53
route53: () => AWS.Route53;
method s3
s3: () => AWS.S3;
method secretsManager
secretsManager: () => AWS.SecretsManager;
method ssm
ssm: () => AWS.SSM;
method stepFunctions
stepFunctions: () => AWS.StepFunctions;
interface SdkForEnvironment
interface SdkForEnvironment {}
SDK configuration for a given environment 'forEnvironment' will attempt to assume a role and if it is not successful, then it will either: 1. Check to see if the default credentials (local credentials the CLI was executed with) are for the given environment. If they are then return those. 2. If the default credentials are not for the given environment then throw an error
'didAssumeRole' allows callers to whether they are receiving the assume role credentials or the default credentials.
property didAssumeRole
readonly didAssumeRole: boolean;
Whether or not the assume role was successful. If the assume role was not successful (false) then that means that the 'sdk' returned contains the default credentials (not the assume role credentials)
property sdk
readonly sdk: ISDK;
The SDK for the given environment
interface SdkHttpOptions
interface SdkHttpOptions {}
Options for individual SDKs
property caBundlePath
readonly caBundlePath?: string;
A path to a certificate bundle that contains a cert to be trusted.
No certificate bundle
property proxyAddress
readonly proxyAddress?: string;
Proxy address to use
No proxy
property userAgent
readonly userAgent?: string;
The custom user agent to use.
- /
interface SdkOptions
interface SdkOptions {}
Additional SDK configuration options
property assumeRoleCredentialsSourceDescription
readonly assumeRoleCredentialsSourceDescription?: string;
Additional descriptive strings that indicate where the "AssumeRole" credentials are coming from
Will be printed in an error message to help users diagnose auth problems.
interface SdkProviderOptions
interface SdkProviderOptions {}
Options for the default SDK provider
property containerCreds
readonly containerCreds?: boolean;
Whether we should check for container credentials
- Autodetect
property ec2creds
readonly ec2creds?: boolean;
Whether we should check for EC2 credentials
- Autodetect
property httpOptions
readonly httpOptions?: SdkHttpOptions;
HTTP options for SDK
property profile
readonly profile?: string;
Profile to read from ~/.aws
- No profile
Enums
enum Mode
enum Mode { ForReading = 0, ForWriting = 1,}
member ForReading
ForReading = 0
member ForWriting
ForWriting = 1
Type Aliases
type BootstrapSource
type BootstrapSource = | { source: 'legacy'; } | { source: 'default'; } | { source: 'custom'; templateFile: string; };
type DeploymentMethod
type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
Package Files (9)
Dependencies (1)
Dev Dependencies (57)
- @aws-cdk/cdk-build-tools
- @aws-cdk/cloud-assembly-schema
- @aws-cdk/cloudformation-diff
- @aws-cdk/cx-api
- @aws-cdk/pkglint
- @aws-cdk/region-info
- @jsii/check-node
- @octokit/rest
- @types/archiver
- @types/fs-extra
- @types/glob
- @types/jest
- @types/mockery
- @types/promptly
- @types/semver
- @types/sinon
- @types/source-map-support
- @types/table
- @types/uuid
- @types/wrap-ansi
- @types/yargs
- archiver
- aws-cdk-lib
- aws-sdk
- aws-sdk-mock
- axios
- camelcase
- cdk-assets
- cdk-from-cfn
- chalk
- chokidar
- constructs
- decamelize
- fast-check
- fs-extra
- glob
- jest
- jest-mock
- json-diff
- madge
- make-runnable
- minimatch
- nock
- promptly
- proxy-agent
- semver
- sinon
- source-map-support
- strip-ansi
- table
- ts-jest
- ts-mock-imports
- uuid
- wrap-ansi
- xml-js
- yaml
- yargs
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/aws-cdk
.
- Markdown[](https://www.jsdocs.io/package/aws-cdk)
- HTML<a href="https://www.jsdocs.io/package/aws-cdk"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 6556 ms. - Missing or incorrect documentation? Open an issue for this package.