feat(aws-ec2): AutoScalingGroup rolling updates

packages/@aws-cdk/assert/lib/assertions/have-resource.ts

@@ -9,16 +9,24 @@ import { StackInspector } from "../inspector";
  * - An object, in which case its properties will be compared to those of the actual resource found
  * - A callable, in which case it will be treated as a predicate that is applied to the Properties of the found resources.
  */
-export function haveResource(resourceType: string, properties?: any): Assertion<StackInspector> {
- return new HaveResourceAssertion(resourceType, properties);
+export function haveResource(resourceType: string, properties?: any, comparison?: ResourcePart): Assertion<StackInspector> {
+ return new HaveResourceAssertion(resourceType, properties, comparison);
 }
 
+type PropertyPredicate = (props: any) => boolean;
+
 class HaveResourceAssertion extends Assertion<StackInspector> {
  private inspected: any[] = [];
+ private readonly part: ResourcePart;
+ private readonly predicate: PropertyPredicate;
 
  constructor(private readonly resourceType: string,
- private readonly properties?: any) {
+ private readonly properties?: any,
+ part?: ResourcePart) {
  super();
+
+ this.predicate = typeof properties === 'function' ? properties : makeSuperObjectPredicate(properties);
+ this.part = part !== undefined ? part : ResourcePart.Properties;
  }
 
  public assertUsing(inspector: StackInspector): boolean {
@@ -27,16 +35,9 @@ class HaveResourceAssertion extends Assertion<StackInspector> {
  if (resource.Type === this.resourceType) {
  this.inspected.push(resource);
 
- let matches: boolean;
- if (typeof this.properties === 'function') {
- // If 'properties' is a callable, invoke it
- matches = this.properties(resource.Properties);
- } else {
- // Otherwise treat as property bag that we check superset of
- matches = isSuperObject(resource.Properties, this.properties);
- }
+ const propsToCheck = this.part === ResourcePart.Properties ? resource.Properties : resource;
 
- if (matches) {
+ if (this.predicate(propsToCheck)) {
  return true;
  }
  }
@@ -57,6 +58,15 @@ class HaveResourceAssertion extends Assertion<StackInspector> {
  }
 }
 
+/**
+ * Make a predicate that checks property superset
+ */
+function makeSuperObjectPredicate(obj: any) {
+ return (resourceProps: any) => {
+ return isSuperObject(resourceProps, obj);
+ };
+}
+
 /**
  * Return whether `superObj` is a super-object of `obj`.
  *
@@ -89,3 +99,20 @@ export function isSuperObject(superObj: any, obj: any): boolean {
  }
  return superObj === obj;
 }
+
+/**
+ * What part of the resource to compare
+ */
+export enum ResourcePart {
+ /**
+ * Only compare the resource's properties
+ */
+ Properties,
+
+ /**
+ * Check the entire CloudFormation config
+ *
+ * (including UpdateConfig, DependsOn, etc.)
+ */
+ CompleteDefinition
+}

packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts

@@ -65,6 +65,63 @@ export interface AutoScalingGroupProps {
  * @default true
  */
  allowAllOutbound?: boolean;
+
+ /**
+ * What to do when an AutoScalingGroup's instance configuration is changed
+ *
+ * This is applied when any of the settings on the ASG are changed that
+ * affect how the instances should be created (VPC, instance type, startup
+ * scripts, etc.). It indicates how the existing instances should be
+ * replaced with new instances matching the new config. By default, nothing
+ * is done and only new instances are launched with the new config.
+ *
+ * @default UpdateType.None
+ */
+ updateType?: UpdateType;
+
+ /**
+ * Configuration for rolling updates
+ *
+ * Only used if updateType == UpdateType.RollingUpdate.
+ */
+ rollingUpdateConfiguration?: RollingUpdateConfiguration;
+
+ /**
+ * Configuration for replacing updates.
+ *
+ * Only used if updateType == UpdateType.ReplacingUpdate. Specifies how
+ * many instances must signal success for the update to succeed.
+ */
+ replacingUpdateMinSuccessfulInstancesPercent?: number;
+
+ /**
+ * If the ASG has scheduled actions, don't reset unchanged group sizes
+ *
+ * Only used if the ASG has scheduled actions (which may scale your ASG up
+ * or down regardless of cdk deployments). If true, the size of the group
+ * will only be reset if it has been changed in the CDK app. If false, the
+ * sizes will always be changed back to what they were in the CDK app
+ * on deployment.
+ *
+ * @default true
+ */
+ ignoreUnmodifiedSizeProperties?: boolean;
+
+ /**
+ * How many ResourceSignal calls CloudFormation expects before the resource is considered created
+ *
+ * @default 1
+ */
+ resourceSignalCount?: number;
+
+ /**
+ * The length of time to wait for the resourceSignalCount
+ *
+ * The maximum value is 43200 (12 hours).
+ *
+ * @default 300 (5 minutes)
+ */
+ resourceSignalTimeoutSec?: number;
 }
 
 /**
@@ -136,6 +193,10 @@ export class AutoScalingGroup extends cdk.Construct implements ec2.IClassicLoadB
  const maxSize = props.maxSize || 1;
  const desiredCapacity = props.desiredCapacity || 1;
 
+ if (desiredCapacity < minSize || desiredCapacity > maxSize) {
+ throw new Error(`Should have minSize (${minSize}) <= desiredCapacity (${desiredCapacity}) <= maxSize (${maxSize})`);
+ }
+
  const asgProps: cloudformation.AutoScalingGroupResourceProps = {
  minSize: minSize.toString(),
  maxSize: maxSize.toString(),
@@ -162,6 +223,8 @@ export class AutoScalingGroup extends cdk.Construct implements ec2.IClassicLoadB
 
  this.autoScalingGroup = new cloudformation.AutoScalingGroupResource(this, 'ASG', asgProps);
  this.osType = machineImage.os.type;
+
+ this.applyUpdatePolicies(props);
  }
 
  public attachToClassicLB(loadBalancer: ec2.ClassicLoadBalancer): void {
@@ -186,4 +249,213 @@ export class AutoScalingGroup extends cdk.Construct implements ec2.IClassicLoadB
  public addToRolePolicy(statement: cdk.PolicyStatement) {
  this.role.addToPolicy(statement);
  }
+
+ /**
+ * Apply CloudFormation update policies for the AutoScalingGroup
+ */
+ private applyUpdatePolicies(props: AutoScalingGroupProps) {
+ if (props.updateType === UpdateType.ReplacingUpdate) {
+ this.asgUpdatePolicy.autoScalingReplacingUpdate = { willReplace: true };
+
+ if (props.replacingUpdateMinSuccessfulInstancesPercent !== undefined) {
+ // Yes, this goes on CreationPolicy, not as a process parameter to ReplacingUpdate.
+ // It's a little confusing, but the docs seem to explicitly state it will only be used
+ // during the update?
+ //
+ // https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-creationpolicy.html
+ this.asgCreationPolicy.autoScalingCreationPolicy = {
+ minSuccessfulInstancesPercent: validatePercentage(props.replacingUpdateMinSuccessfulInstancesPercent)
+ };
+ }
+ } else if (props.updateType === UpdateType.RollingUpdate) {
+ this.asgUpdatePolicy.autoScalingRollingUpdate = renderRollingUpdateConfig(props.rollingUpdateConfiguration);
+ }
+
+ // undefined is treated as 'true'
+ if (props.ignoreUnmodifiedSizeProperties !== false) {
+ this.asgUpdatePolicy.autoScalingScheduledAction = { ignoreUnmodifiedGroupSizeProperties: true };
+ }
+
+ if (props.resourceSignalCount !== undefined || props.resourceSignalTimeoutSec !== undefined) {
+ this.asgCreationPolicy.resourceSignal = {
+ count: props.resourceSignalCount,
+ timeout: props.resourceSignalTimeoutSec !== undefined ? renderIsoDuration(props.resourceSignalTimeoutSec) : undefined,
+ };
+ }
+ }
+
+ /**
+ * Create and return the ASG update policy
+ */
+ private get asgUpdatePolicy() {
+ if (this.autoScalingGroup.options.updatePolicy === undefined) {
+ this.autoScalingGroup.options.updatePolicy = {};
+ }
+ return this.autoScalingGroup.options.updatePolicy;
+ }
+
+ /**
+ * Create and return the ASG creation policy
+ */
+ private get asgCreationPolicy() {
+ if (this.autoScalingGroup.options.creationPolicy === undefined) {
+ this.autoScalingGroup.options.creationPolicy = {};
+ }
+ return this.autoScalingGroup.options.creationPolicy;
+ }
+}
+
+/**
+ * The type of update to perform on instances in this AutoScalingGroup
+ */
+export enum UpdateType {
+ /**
+ * Don't do anything
+ */
+ None = 'None',
+
+ /**
+ * Replace the entire AutoScalingGroup
+ *
+ * Builds a new AutoScalingGroup first, then delete the old one.
+ */
+ ReplacingUpdate = 'Replace',
+
+ /**
+ * Replace the instances in the AutoScalingGroup.
+ */
+ RollingUpdate = 'RollingUpdate',
+}
+
+/**
+ * Additional settings when a rolling update is selected
+ */
+export interface RollingUpdateConfiguration {
+ /**
+ * The maximum number of instances that AWS CloudFormation updates at once.
+ *
+ * @default 1
+ */
+ maxBatchSize?: number;
+
+ /**
+ * The minimum number of instances that must be in service before more instances are replaced.
+ *
+ * This number affects the speed of the replacement.
+ *
+ * @default 0
+ */
+ minInstancesInService?: number;
+
+ /**
+ * The percentage of instances that must signal success for an update to succeed.
+ *
+ * If an instance doesn't send a signal within the time specified in the
+ * pauseTime property, AWS CloudFormation assumes that the instance wasn't
+ * updated.
+ *
+ * This number affects the success of the replacement.
+ *
+ * If you specify this property, you must also enable the
+ * waitOnResourceSignals and pauseTime properties.
+ *
+ * @default 100
+ */
+ minSuccessfulInstancesPercent?: number;
+
+ /**
+ * The pause time after making a change to a batch of instances.
+ *
+ * This is intended to give those instances time to start software applications.
+ *
+ * Specify PauseTime in the ISO8601 duration format (in the format
+ * PT#H#M#S, where each # is the number of hours, minutes, and seconds,
+ * respectively). The maximum PauseTime is one hour (PT1H).
+ *
+ * @default 300 if the waitOnResourceSignals property is true, otherwise 0
+ */
+ pauseTimeSec?: number;
+
+ /**
+ * Specifies whether the Auto Scaling group waits on signals from new instances during an update.
+ *
+ * AWS CloudFormation must receive a signal from each new instance within
+ * the specified PauseTime before continuing the update.
+ *
+ * To have instances wait for an Elastic Load Balancing health check before
+ * they signal success, add a health-check verification by using the
+ * cfn-init helper script. For an example, see the verify_instance_health
+ * command in the Auto Scaling rolling updates sample template.
+ *
+ * @default true if you specified the minSuccessfulInstancesPercent property, false otherwise
+ */
+ waitOnResourceSignals?: boolean;
+
+ /**
+ * Specifies the Auto Scaling processes to suspend during a stack update.
+ *
+ * Suspending processes prevents Auto Scaling from interfering with a stack
+ * update.
+ *
+ * @default HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, ScheduledActions.
+ */
+ suspendProcesses?: ScalingProcess[];
+}
+
+export enum ScalingProcess {
+ Launch = 'Launch',
+ Terminate = 'Terminate',
+ HealthCheck = 'HealthCheck',
+ ReplaceUnhealthy = 'ReplaceUnhealthy',
+ AZRebalance = 'AZRebalance',
+ AlarmNotification = 'AlarmNotification',
+ ScheduledActions = 'ScheduledActions',
+ AddToLoadBalancer = 'AddToLoadBalancer'
+}
+
+/**
+ * Render the rolling update configuration into the appropriate object
+ */
+function renderRollingUpdateConfig(config: RollingUpdateConfiguration = {}): cdk.AutoScalingRollingUpdate {
+ const waitOnResourceSignals = config.minSuccessfulInstancesPercent !== undefined ? true : false;
+ const pauseTimeSec = config.pauseTimeSec !== undefined ? config.pauseTimeSec : (waitOnResourceSignals ? 300 : 0);
+
+ return {
+ maxBatchSize: config.maxBatchSize,
+ minInstancesInService: config.minInstancesInService,
+ minSuccessfulInstancesPercent: validatePercentage(config.minSuccessfulInstancesPercent),
+ waitOnResourceSignals,
+ pauseTime: renderIsoDuration(pauseTimeSec),
+ suspendProcesses: config.suspendProcesses !== undefined ? config.suspendProcesses :
+ // Recommended list of processes to suspend from here:
+ // https://aws.amazon.com/premiumsupport/knowledge-center/auto-scaling-group-rolling-updates/
+ [ScalingProcess.HealthCheck, ScalingProcess.ReplaceUnhealthy, ScalingProcess.AZRebalance,
+ ScalingProcess.AlarmNotification, ScalingProcess.ScheduledActions],
+ };
+}
+
+/**
+ * Render a number of seconds to a PTnX string.
+ */
+function renderIsoDuration(seconds: number): string {
+ const ret: string[] = [];
+
+ if (seconds >= 3600) {
+ ret.push(`${Math.floor(seconds / 3600)}H`);
+ seconds %= 3600;
+ }
+ if (seconds >= 60) {
+ ret.push(`${Math.floor(seconds / 60)}M`);
+ seconds %= 60;
+ }
+ if (seconds > 0) {
+ ret.push(`${seconds}S`);
+ }
+
+ return 'PT' + ret.join('');
+}
+
+function validatePercentage(x?: number): number | undefined {
+ if (x === undefined || (0 <= x && x <= 100)) { return x; }
+ throw new Error(`Expected: a percentage 0..100, got: ${x}`);
 }

packages/@aws-cdk/aws-autoscaling/test/integ.asg-w-loadbalancer.expected.json

@@ -452,6 +452,11 @@
  "Ref": "VPCPrivateSubnet3Subnet3EDCD457"
  }
  ]
+ },
+ "UpdatePolicy": {
+ "AutoScalingScheduledAction": {
+ "IgnoreUnmodifiedGroupSizeProperties": true
+ }
  }
  },
  "LBSecurityGroup8A41EA2B": {