aws-cdk
Version:
AWS CDK CLI, the command line tool for CDK apps
216 lines (215 loc) • 7.73 kB
TypeScript
import type { ResourceDifference } from '@aws-cdk/cloudformation-diff';
import type * as cxapi from '@aws-cdk/cx-api';
import type { ResourceIdentifierSummary, ResourceToImport } from '@aws-sdk/client-cloudformation';
import { type IoHelper } from '../../../../@aws-cdk/tmp-toolkit-helpers/src/api/io/private';
import type { DeploymentMethod, Deployments } from '../deployments';
import type { Tag } from '../tags';
export type ResourcesToImport = ResourceToImport[];
export type ResourceIdentifierSummaries = ResourceIdentifierSummary[];
export { removeNonImportResources } from '../../../../@aws-cdk/tmp-toolkit-helpers/src/api';
export interface ResourceImporterProps {
deployments: Deployments;
ioHelper: IoHelper;
}
export interface ImportDeploymentOptions {
/**
* Role to pass to CloudFormation for deployment
*
* @default - Default stack role
*/
readonly roleArn?: string;
/**
* Deployment method
*
* @default - Change set with default options
*/
readonly deploymentMethod?: DeploymentMethod;
/**
* Stack tags (pass through to CloudFormation)
*
* @default - No tags
*/
readonly tags?: Tag[];
/**
* 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;
}
/**
* Set of parameters that uniquely identify a physical resource of a given type
* for the import operation, example:
*
* ```
* {
* "AWS::S3::Bucket": [["BucketName"]],
* "AWS::DynamoDB::GlobalTable": [["TableName"], ["TableArn"], ["TableStreamArn"]],
* "AWS::Route53::KeySigningKey": [["HostedZoneId", "Name"]],
* }
* ```
*/
export type ResourceIdentifiers = {
[resourceType: string]: string[][];
};
type ResourceIdentifierProperties = Record<string, string>;
/**
* Mapping of CDK resources (L1 constructs) to physical resources to be imported
* in their place, example:
*
* ```
* {
* "MyStack/MyS3Bucket/Resource": {
* "BucketName": "my-manually-created-s3-bucket"
* },
* "MyStack/MyVpc/Resource": {
* "VpcId": "vpc-123456789"
* }
* }
* ```
*/
type ResourceMap = {
[logicalResource: string]: ResourceIdentifierProperties;
};
/**
* Resource importing utility class
*
* - Determines the resources added to a template (compared to the deployed version)
* - Look up the identification information
* - Load them from a file, or
* - Ask the user, based on information supplied to us by CloudFormation's GetTemplateSummary
* - Translate the input to a structure expected by CloudFormation, update the template to add the
* importable resources, then run an IMPORT changeset.
*/
export declare class ResourceImporter {
private _currentTemplate;
private readonly stack;
private readonly cfn;
private readonly ioHelper;
constructor(stack: cxapi.CloudFormationStackArtifact, props: ResourceImporterProps);
/**
* Ask the user for resources to import
*/
askForResourceIdentifiers(available: ImportableResource[]): Promise<ImportMap>;
/**
* Load the resources to import from a file
*/
loadResourceIdentifiers(available: ImportableResource[], filename: string): Promise<ImportMap>;
/**
* Based on the provided resource mapping, prepare CFN structures for import (template,
* ResourcesToImport structure) and perform the import operation (CloudFormation deployment)
*
* @param importMap Mapping from CDK construct tree path to physical resource import identifiers
* @param options Options to pass to CloudFormation deploy operation
*/
importResourcesFromMap(importMap: ImportMap, options?: ImportDeploymentOptions): Promise<void>;
/**
* Based on the app and resources file generated by cdk migrate. Removes all items from the template that
* cannot be included in an import change-set for new stacks and performs the import operation,
* creating the new stack.
*
* @param resourcesToImport The mapping created by cdk migrate
* @param options Options to pass to CloudFormation deploy operation
*/
importResourcesFromMigrate(resourcesToImport: ResourcesToImport, options?: ImportDeploymentOptions): Promise<void>;
private importResources;
/**
* Perform a diff between the currently running and the new template, ensure that it is valid
* for importing and return a list of resources that are being added in the new version
*
* @return mapping logicalResourceId -> resourceDifference
*/
discoverImportableResources(allowNonAdditions?: boolean): Promise<DiscoverImportableResourcesResult>;
/**
* Resolves the environment of a stack.
*/
resolveEnvironment(): Promise<cxapi.Environment>;
/**
* Get currently deployed template of the given stack (SINGLETON)
*
* @returns Currently deployed CloudFormation template
*/
private currentTemplate;
/**
* Return the current template, with the given resources added to it
*/
private currentTemplateWithAdditions;
/**
* Get a list of import identifiers for all resource types used in the given
* template that do support the import operation (SINGLETON)
*
* @returns a mapping from a resource type to a list of property names that together identify the resource for import
*/
private resourceIdentifiers;
/**
* Ask for the importable identifier for the given resource
*
* There may be more than one identifier under which a resource can be imported. The `import`
* operation needs exactly one of them.
*
* - If we can get one from the template, we will use one.
* - Otherwise, we will ask the user for one of them.
*/
private askForResourceIdentifier;
/**
* Convert the internal "resource mapping" structure to CloudFormation accepted "ResourcesToImport" structure
*/
private makeResourcesToImport;
/**
* Convert CloudFormation logical resource ID to CDK construct tree path
*
* @param logicalId CloudFormation logical ID of the resource (the key in the template's Resources section)
* @returns Forward-slash separated path of the resource in CDK construct tree, e.g. MyStack/MyBucket/Resource
*/
private describeResource;
/**
* Removes CDKMetadata and Outputs in the template so that only resources for importing are left.
* @returns template with import resources only
*/
private removeNonImportResources;
}
/**
* Information about a resource in the template that is importable
*/
export interface ImportableResource {
/**
* The logical ID of the resource
*/
readonly logicalId: string;
/**
* The resource definition in the new template
*/
readonly resourceDefinition: any;
/**
* The diff as reported by `cloudformation-diff`.
*/
readonly resourceDiff: ResourceDifference;
}
/**
* The information necessary to execute an import operation
*/
export interface ImportMap {
/**
* Mapping logical IDs to physical names
*/
readonly resourceMap: ResourceMap;
/**
* The selection of resources we are actually importing
*
* For each of the resources in this list, there is a corresponding entry in
* the `resourceMap` map.
*/
readonly importResources: ImportableResource[];
}
export interface DiscoverImportableResourcesResult {
readonly additions: ImportableResource[];
readonly hasNonAdditions: boolean;
}