@aws-cdk/toolkit-lib 0.3.2 → 0.3.4

package/lib/api/deployments/deployment-method.d.ts

@@ -0,0 +1,24 @@
+export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
+export interface DirectDeploymentMethod {
+    readonly method: 'direct';
+}
+export interface ChangeSetDeploymentMethod {
+    readonly method: 'change-set';
+    /**
+     * Whether to execute the changeset or leave it in review.
+     *
+     * @default true
+     */
+    readonly execute?: boolean;
+    /**
+     * Optional name to use for the CloudFormation change set.
+     * If not provided, a name will be generated automatically.
+     */
+    readonly changeSetName?: string;
+    /**
+     * Indicates if the change set imports resources that already exist.
+     *
+     * @default false
+     */
+    readonly importExistingResources?: boolean;
+}

package/lib/api/deployments/deployment-method.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVwbG95bWVudC1tZXRob2QuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJkZXBsb3ltZW50LW1ldGhvZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHR5cGUgRGVwbG95bWVudE1ldGhvZCA9IERpcmVjdERlcGxveW1lbnRNZXRob2QgfCBDaGFuZ2VTZXREZXBsb3ltZW50TWV0aG9kO1xuXG5leHBvcnQgaW50ZXJmYWNlIERpcmVjdERlcGxveW1lbnRNZXRob2Qge1xuICByZWFkb25seSBtZXRob2Q6ICdkaXJlY3QnO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIENoYW5nZVNldERlcGxveW1lbnRNZXRob2Qge1xuICByZWFkb25seSBtZXRob2Q6ICdjaGFuZ2Utc2V0JztcblxuICAvKipcbiAgICogV2hldGhlciB0byBleGVjdXRlIHRoZSBjaGFuZ2VzZXQgb3IgbGVhdmUgaXQgaW4gcmV2aWV3LlxuICAgKlxuICAgKiBAZGVmYXVsdCB0cnVlXG4gICAqL1xuICByZWFkb25seSBleGVjdXRlPzogYm9vbGVhbjtcblxuICAvKipcbiAgICogT3B0aW9uYWwgbmFtZSB0byB1c2UgZm9yIHRoZSBDbG91ZEZvcm1hdGlvbiBjaGFuZ2Ugc2V0LlxuICAgKiBJZiBub3QgcHJvdmlkZWQsIGEgbmFtZSB3aWxsIGJlIGdlbmVyYXRlZCBhdXRvbWF0aWNhbGx5LlxuICAgKi9cbiAgcmVhZG9ubHkgY2hhbmdlU2V0TmFtZT86IHN0cmluZztcblxuICAvKipcbiAgICogSW5kaWNhdGVzIGlmIHRoZSBjaGFuZ2Ugc2V0IGltcG9ydHMgcmVzb3VyY2VzIHRoYXQgYWxyZWFkeSBleGlzdC5cbiAgICpcbiAgICogQGRlZmF1bHQgZmFsc2VcbiAgICovXG4gIHJlYWRvbmx5IGltcG9ydEV4aXN0aW5nUmVzb3VyY2VzPzogYm9vbGVhbjtcbn1cbiJdfQ==

package/lib/api/deployments/deployment-result.d.ts

@@ -0,0 +1,21 @@
+export type DeployStackResult = SuccessfulDeployStackResult | NeedRollbackFirstDeployStackResult | ReplacementRequiresRollbackStackResult;
+/** Successfully deployed a stack */
+export interface SuccessfulDeployStackResult {
+    readonly type: 'did-deploy-stack';
+    readonly noOp: boolean;
+    readonly outputs: {
+        [name: string]: string;
+    };
+    readonly stackArn: string;
+}
+/** The stack is currently in a failpaused state, and needs to be rolled back before the deployment */
+export interface NeedRollbackFirstDeployStackResult {
+    readonly type: 'failpaused-need-rollback-first';
+    readonly reason: 'not-norollback' | 'replacement';
+    readonly status: string;
+}
+/** The upcoming change has a replacement, which requires deploying with --rollback */
+export interface ReplacementRequiresRollbackStackResult {
+    readonly type: 'replacement-requires-rollback';
+}
+export declare function assertIsSuccessfulDeployStackResult(x: DeployStackResult): asserts x is SuccessfulDeployStackResult;

package/lib/api/deployments/deployment-result.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertIsSuccessfulDeployStackResult = assertIsSuccessfulDeployStackResult;
+const toolkit_error_1 = require("../../toolkit/toolkit-error");
+function assertIsSuccessfulDeployStackResult(x) {
+    if (x.type !== 'did-deploy-stack') {
+        throw new toolkit_error_1.ToolkitError(`Unexpected deployStack result. This should not happen: ${JSON.stringify(x)}. If you are seeing this error, please report it at https://github.com/aws/aws-cdk/issues/new/choose.`);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVwbG95bWVudC1yZXN1bHQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJkZXBsb3ltZW50LXJlc3VsdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQTRCQSxrRkFJQztBQWhDRCwrREFBMkQ7QUE0QjNELFNBQWdCLG1DQUFtQyxDQUFDLENBQW9CO0lBQ3RFLElBQUksQ0FBQyxDQUFDLElBQUksS0FBSyxrQkFBa0IsRUFBRSxDQUFDO1FBQ2xDLE1BQU0sSUFBSSw0QkFBWSxDQUFDLDBEQUEwRCxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyx1R0FBdUcsQ0FBQyxDQUFDO0lBQzdNLENBQUM7QUFDSCxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgVG9vbGtpdEVycm9yIH0gZnJvbSAnLi4vLi4vdG9vbGtpdC90b29sa2l0LWVycm9yJztcblxuZXhwb3J0IHR5cGUgRGVwbG95U3RhY2tSZXN1bHQgPVxuICB8IFN1Y2Nlc3NmdWxEZXBsb3lTdGFja1Jlc3VsdFxuICB8IE5lZWRSb2xsYmFja0ZpcnN0RGVwbG95U3RhY2tSZXN1bHRcbiAgfCBSZXBsYWNlbWVudFJlcXVpcmVzUm9sbGJhY2tTdGFja1Jlc3VsdFxuICA7XG5cbi8qKiBTdWNjZXNzZnVsbHkgZGVwbG95ZWQgYSBzdGFjayAqL1xuZXhwb3J0IGludGVyZmFjZSBTdWNjZXNzZnVsRGVwbG95U3RhY2tSZXN1bHQge1xuICByZWFkb25seSB0eXBlOiAnZGlkLWRlcGxveS1zdGFjayc7XG4gIHJlYWRvbmx5IG5vT3A6IGJvb2xlYW47XG4gIHJlYWRvbmx5IG91dHB1dHM6IHsgW25hbWU6IHN0cmluZ106IHN0cmluZyB9O1xuICByZWFkb25seSBzdGFja0Fybjogc3RyaW5nO1xufVxuXG4vKiogVGhlIHN0YWNrIGlzIGN1cnJlbnRseSBpbiBhIGZhaWxwYXVzZWQgc3RhdGUsIGFuZCBuZWVkcyB0byBiZSByb2xsZWQgYmFjayBiZWZvcmUgdGhlIGRlcGxveW1lbnQgKi9cbmV4cG9ydCBpbnRlcmZhY2UgTmVlZFJvbGxiYWNrRmlyc3REZXBsb3lTdGFja1Jlc3VsdCB7XG4gIHJlYWRvbmx5IHR5cGU6ICdmYWlscGF1c2VkLW5lZWQtcm9sbGJhY2stZmlyc3QnO1xuICByZWFkb25seSByZWFzb246ICdub3Qtbm9yb2xsYmFjaycgfCAncmVwbGFjZW1lbnQnO1xuICByZWFkb25seSBzdGF0dXM6IHN0cmluZztcbn1cblxuLyoqIFRoZSB1cGNvbWluZyBjaGFuZ2UgaGFzIGEgcmVwbGFjZW1lbnQsIHdoaWNoIHJlcXVpcmVzIGRlcGxveWluZyB3aXRoIC0tcm9sbGJhY2sgKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmVwbGFjZW1lbnRSZXF1aXJlc1JvbGxiYWNrU3RhY2tSZXN1bHQge1xuICByZWFkb25seSB0eXBlOiAncmVwbGFjZW1lbnQtcmVxdWlyZXMtcm9sbGJhY2snO1xufVxuXG5leHBvcnQgZnVuY3Rpb24gYXNzZXJ0SXNTdWNjZXNzZnVsRGVwbG95U3RhY2tSZXN1bHQoeDogRGVwbG95U3RhY2tSZXN1bHQpOiBhc3NlcnRzIHggaXMgU3VjY2Vzc2Z1bERlcGxveVN0YWNrUmVzdWx0IHtcbiAgaWYgKHgudHlwZSAhPT0gJ2RpZC1kZXBsb3ktc3RhY2snKSB7XG4gICAgdGhyb3cgbmV3IFRvb2xraXRFcnJvcihgVW5leHBlY3RlZCBkZXBsb3lTdGFjayByZXN1bHQuIFRoaXMgc2hvdWxkIG5vdCBoYXBwZW46ICR7SlNPTi5zdHJpbmdpZnkoeCl9LiBJZiB5b3UgYXJlIHNlZWluZyB0aGlzIGVycm9yLCBwbGVhc2UgcmVwb3J0IGl0IGF0IGh0dHBzOi8vZ2l0aHViLmNvbS9hd3MvYXdzLWNkay9pc3N1ZXMvbmV3L2Nob29zZS5gKTtcbiAgfVxufVxuIl19

package/lib/api/deployments/deployments.d.ts

@@ -0,0 +1,289 @@
+import type * as cxapi from '@aws-cdk/cx-api';
+import * as cdk_assets from 'cdk-assets';
+import type { DeploymentMethod } from './deployment-method';
+import type { DeployStackResult } from './deployment-result';
+import type { SdkProvider } from '../aws-auth/private';
+import type { Template, RootTemplateWithNestedStacks } from '../cloudformation';
+import { EnvironmentAccess } from '../environment';
+import type { HotswapMode, HotswapPropertyOverrides } from '../hotswap/common';
+import { type IoHelper } from '../io/private';
+import type { ResourceIdentifierSummaries, ResourcesToImport } from '../resource-import';
+import type { Tag } from '../tags';
+export interface DeployStackOptions {
+    /**
+     * Stack to deploy
+     */
+    readonly stack: cxapi.CloudFormationStackArtifact;
+    /**
+     * Execution role for the deployment (pass through to CloudFormation)
+     *
+     * @default - Current role
+     */
+    readonly roleArn?: string;
+    /**
+     * Topic ARNs to send a message when deployment finishes (pass through to CloudFormation)
+     *
+     * @default - No notifications
+     */
+    readonly notificationArns?: string[];
+    /**
+     * Override name under which stack will be deployed
+     *
+     * @default - Use artifact default
+     */
+    readonly deployName?: string;
+    /**
+     * Name of the toolkit stack, if not the default name
+     *
+     * @default 'CDKToolkit'
+     */
+    readonly toolkitStackName?: string;
+    /**
+     * List of asset IDs which should NOT be built or uploaded
+     *
+     * @default - Build all assets
+     */
+    readonly reuseAssets?: string[];
+    /**
+     * Stack tags (pass through to CloudFormation)
+     */
+    readonly tags?: Tag[];
+    /**
+     * Stage the change set but don't execute it
+     *
+     * @default - true
+     * @deprecated Use 'deploymentMethod' instead
+     */
+    readonly execute?: boolean;
+    /**
+     * Optional name to use for the CloudFormation change set.
+     * If not provided, a name will be generated automatically.
+     *
+     * @deprecated Use 'deploymentMethod' instead
+     */
+    readonly changeSetName?: string;
+    /**
+     * Select the deployment method (direct or using a change set)
+     *
+     * @default - Change set with default options
+     */
+    readonly deploymentMethod?: DeploymentMethod;
+    /**
+     * Force deployment, even if the deployed template is identical to the one we are about to deploy.
+     * @default false deployment will be skipped if the template is identical
+     */
+    readonly forceDeployment?: boolean;
+    /**
+     * Extra parameters for CloudFormation
+     * @default - no additional parameters will be passed to the template
+     */
+    readonly parameters?: {
+        [name: string]: string | undefined;
+    };
+    /**
+     * Use previous values for unspecified parameters
+     *
+     * If not set, all parameters must be specified for every deployment.
+     *
+     * @default true
+     */
+    readonly usePreviousParameters?: boolean;
+    /**
+     * Rollback failed deployments
+     *
+     * @default true
+     */
+    readonly rollback?: boolean;
+    readonly hotswap?: HotswapMode;
+    /**
+     * Properties that configure hotswap behavior
+     */
+    readonly hotswapPropertyOverrides?: HotswapPropertyOverrides;
+    /**
+     * The extra string to append to the User-Agent header when performing AWS SDK calls.
+     *
+     * @default - nothing extra is appended to the User-Agent header
+     */
+    readonly extraUserAgent?: string;
+    /**
+     * List of existing resources to be IMPORTED into the stack, instead of being CREATED
+     */
+    readonly resourcesToImport?: ResourcesToImport;
+    /**
+     * If present, use this given template instead of the stored one
+     *
+     * @default - Use the stored template
+     */
+    readonly overrideTemplate?: any;
+    /**
+     * Whether to build/publish assets in parallel
+     *
+     * @default true To remain backward compatible.
+     */
+    readonly assetParallelism?: boolean;
+    /**
+     * Whether to deploy if the app contains no stacks.
+     *
+     * @deprecated this option seems to be unsed inside deployments
+     * @default false
+     */
+    readonly ignoreNoStacks?: boolean;
+}
+export interface RollbackStackOptions {
+    /**
+     * Stack to roll back
+     */
+    readonly stack: cxapi.CloudFormationStackArtifact;
+    /**
+     * Execution role for the deployment (pass through to CloudFormation)
+     *
+     * @default - Current role
+     */
+    readonly roleArn?: string;
+    /**
+     * Name of the toolkit stack, if not the default name
+     *
+     * @default 'CDKToolkit'
+     */
+    readonly toolkitStackName?: string;
+    /**
+     * Whether to automatically orphan all failed resources during the rollback
+     *
+     * This will force a rollback that otherwise would have failed.
+     *
+     * @default false
+     */
+    readonly orphanFailedResources?: boolean;
+    /**
+     * Orphan the resources with the given logical IDs
+     *
+     * @default - No orphaning
+     */
+    readonly orphanLogicalIds?: string[];
+    /**
+     * Whether to validate the version of the bootstrap stack permissions
+     *
+     * @default true
+     */
+    readonly validateBootstrapStackVersion?: boolean;
+}
+export type RollbackStackResult = {
+    readonly stackArn: string;
+} & ({
+    readonly notInRollbackableState: true;
+} | {
+    readonly success: true;
+    notInRollbackableState?: undefined;
+});
+interface AssetOptions {
+    /**
+     * Stack with assets to build.
+     */
+    readonly stack: cxapi.CloudFormationStackArtifact;
+    /**
+     * Execution role for the building.
+     *
+     * @default - Current role
+     */
+    readonly roleArn?: string;
+}
+export interface BuildStackAssetsOptions extends AssetOptions {
+    /**
+     * Stack name this asset is for
+     */
+    readonly stackName?: string;
+}
+interface PublishStackAssetsOptions extends AssetOptions {
+    /**
+     * Stack name this asset is for
+     */
+    readonly stackName?: string;
+    /**
+     * Always publish, even if it already exists
+     *
+     * @default false
+     */
+    readonly forcePublish?: boolean;
+}
+export interface DestroyStackOptions {
+    stack: cxapi.CloudFormationStackArtifact;
+    deployName?: string;
+    roleArn?: string;
+}
+export interface StackExistsOptions {
+    stack: cxapi.CloudFormationStackArtifact;
+    deployName?: string;
+    tryLookupRole?: boolean;
+}
+export interface DeploymentsProps {
+    readonly sdkProvider: SdkProvider;
+    readonly toolkitStackName?: string;
+    readonly ioHelper: IoHelper;
+}
+/**
+ * Scope for a single set of deployments from a set of Cloud Assembly Artifacts
+ *
+ * Manages lookup of SDKs, Bootstrap stacks, etc.
+ */
+export declare class Deployments {
+    private readonly props;
+    readonly envs: EnvironmentAccess;
+    /**
+     * SDK provider for asset publishing (do not use for anything else).
+     *
+     * This SDK provider is only allowed to be used for that purpose, nothing else.
+     *
+     * It's not a different object, but the field name should imply that this
+     * object should not be used directly, except to pass to asset handling routines.
+     */
+    private readonly assetSdkProvider;
+    /**
+     * SDK provider for passing to deployStack
+     *
+     * This SDK provider is only allowed to be used for that purpose, nothing else.
+     *
+     * It's not a different object, but the field name should imply that this
+     * object should not be used directly, except to pass to `deployStack`.
+     */
+    private readonly deployStackSdkProvider;
+    private readonly publisherCache;
+    private _allowCrossAccountAssetPublishing;
+    private readonly ioHelper;
+    constructor(props: DeploymentsProps);
+    /**
+     * Resolves the environment for a stack.
+     */
+    resolveEnvironment(stack: cxapi.CloudFormationStackArtifact): Promise<cxapi.Environment>;
+    readCurrentTemplateWithNestedStacks(rootStackArtifact: cxapi.CloudFormationStackArtifact, retrieveProcessedTemplate?: boolean): Promise<RootTemplateWithNestedStacks>;
+    readCurrentTemplate(stackArtifact: cxapi.CloudFormationStackArtifact): Promise<Template>;
+    resourceIdentifierSummaries(stackArtifact: cxapi.CloudFormationStackArtifact): Promise<ResourceIdentifierSummaries>;
+    deployStack(options: DeployStackOptions): Promise<DeployStackResult>;
+    rollbackStack(options: RollbackStackOptions): Promise<RollbackStackResult>;
+    destroyStack(options: DestroyStackOptions): Promise<import("./deploy-stack").DestroyStackResult>;
+    stackExists(options: StackExistsOptions): Promise<boolean>;
+    /**
+     * Build a single asset from an asset manifest
+     *
+     * If an assert manifest artifact is given, the bootstrap stack version
+     * will be validated according to the constraints in that manifest artifact.
+     * If that is not necessary, `'no-version-validation'` can be passed.
+     */
+    buildSingleAsset(assetArtifact: cxapi.AssetManifestArtifact | 'no-version-validation', assetManifest: cdk_assets.AssetManifest, asset: cdk_assets.IManifestEntry, options: BuildStackAssetsOptions): Promise<void>;
+    /**
+     * Publish a single asset from an asset manifest
+     */
+    publishSingleAsset(assetManifest: cdk_assets.AssetManifest, asset: cdk_assets.IManifestEntry, options: PublishStackAssetsOptions): Promise<void>;
+    private allowCrossAccountAssetPublishingForEnv;
+    /**
+     * Return whether a single asset has been published already
+     */
+    isSingleAssetPublished(assetManifest: cdk_assets.AssetManifest, asset: cdk_assets.IManifestEntry, options: PublishStackAssetsOptions): Promise<boolean>;
+    /**
+     * Validate that the bootstrap stack has the right version for this stack
+     *
+     * Call into envResources.validateVersion, but prepend the stack name in case of failure.
+     */
+    private validateBootstrapStackVersion;
+    private cachedPublisher;
+}
+export {};