Deployment Groups

Within a given stack, it is possible to bundle the following resource types into a single deployment, this can significantly reduce deployment times, particularly when there are dependencies between the resources in the deployment group.

To use this feature it is necessary to mark resources as being part of a deployment, and then create a deployment group resource in the same stack. It is required that if any resource is marked with the deploymentGroup flag that it is referenced in exactly one deployment group, and this is validated during CDK deployment.

The following resources currently support deploymentGroups, and more may be added in future:

• Dataset
• Location
• Executor

Using a DeploymentGroup

For example, to deploy 2 datasets and a location using a DeploymentGroup:

const myLocation = new Location.DynamoDB(this, "DDBLocation", {
    environment: depotEnvironment,
    capacityMode: DynamoDBLocationCapacityMode.ONDEMAND,
    deploymentGroup: true
});

const myDs1 = new Dataset(this, 'Ds1', {
    environment: depotEnvironment,
    name: 'sample.ds1',
    location: myLocation,
    package: myPackage1,
    deploymentGroup: true
});

const myDs2 = new Dataset(this, 'Ds2', {
    environment: depotEnvironment,
    name: 'sample.ds2',
    location: myLocation,
    package: myPackage2,
    deploymentGroup: true
});

new DeploymentGroup(this, "DeploymentGroup", {
    datasets: [myDs1, myDs2],
    locations: [myLocation]
});

When this stack deploys, the datasets and location will deploy as custom resources, but this is only to obtain ids which can be used to reference those resources (and automatic cloudformation dependency ordering is maintained), early validation (where applicable) will also be performed on deployment of the original resources.

When the deployment group deploys, it passes information for all referenced resources and a single execution of the internal depot configuration stack occurs, in this example it would be expected that deployment time would drop to the longest time to deploy any single resource, rather than the time to run each resource update sequentially (according to dependency order).

info

Resources referenced from other stacks using "from" style initializers (e.g. Dataset.fromDatasetProps) are not applicable to DeploymentGroups. They can be used in dependency chain references for other concrete Dataset types, but not as the actual resources referenced in the DeploymentGroup resource arrays references.

If a deployment group is not created to reference all deploymentGroup: true resources in a given stack, it is an error:

// No deployment group resource exists that references myLocation
const myLocation = new Location.DynamoDB(this, "DDBLocation", {
    environment: depotEnvironment,
    capacityMode: DynamoDBLocationCapacityMode.ONDEMAND,
    deploymentGroup: true
});

// ERROR: Resource of type Custom::Location must be bound to exactly one deployment group

Similarly, if a DeploymentGroup references a resource which does not have deploymentGroup: true it is also an error:

const myLocation = new Location.DynamoDB(this, "DDBLocation", {
    environment: depotEnvironment,
    capacityMode: DynamoDBLocationCapacityMode.ONDEMAND
});

new DeploymentGroup(this, "DeploymentGroup", {
    locations: [myLocation]
});

// ERROR: Resource of type Custom::Executor cannot be bound to a deployment group

If a DeploymentGroup exists in a Stack, along with other Depot resources which are supported (see above) along the DeploymentGroup, and they are not referenced by the DeploymentGroup, it is an error:

const myLocation = new Location.DynamoDB(this, "DynamoDBLocation", {
    environment: depotEnvironment,
    capacityMode: DynamoDBLocationCapacityMode.ONDEMAND
});

new DeploymentGroup(this, "DeploymentGroup", {
    environment: depotEnvironment
});

// ERROR: Construct at path ExampleStack/DynamoDBLocation/Resource of type DynamoDB must be included in the Stack's Deployment Group

warning

Be careful when creating a DeploymentGroup in a stack and adding resources to it. At a later stage, if the DeploymentGroup is deleted, the concrete resources referenced by it will be deleted too if their deploymentGroup flag is set to true.

Removing resources from a DeploymentGroup

Note the following important information which relates to removing a DeploymentGroup and two different outcomes - one where the referenced resources will also be deleted, and one where the referenced resources can be retained.

info

To safely de-reference resources from a DeploymentGroup without removing the resources themselves, ensure you set their deploymentGroup flag is set to false at the same time that you remove the DeploymentGroup. In this scenario, the resources will be modified each to set their deploymentGroup flag to false, and the DeploymentGroup deletion follows shortly after. The deletion process of the DeploymentGroup checks the state of the resources on the environment's 'master' branch for their latest state in order to decide whether or not they should be removed.