feat(ecs): Add forceNewDeployment feature for ecs service

Author: kg-aws

packages/aws-cdk-lib/aws-ecs/README.md

@@ -2234,3 +2234,31 @@ new ecs.ExternalService(this, 'ExternalService', {
   daemon: true,
 });
 ```
+
+### Force New Deployment
+
+You can force a new deployment of a service without changing the task definition or desired count. This can be useful to trigger a deployment when you want to deploy new tasks even if there are no changes to the service configuration.
+
+When enabled, ECS will start a new deployment even if there are no changes to the service configuration. This is accomplished by setting a unique timestamp nonce that forces CloudFormation to recognize the service as changed.
+
+```ts
+declare const cluster: ecs.Cluster;
+declare const taskDefinition: ecs.TaskDefinition;
+
+const service = new ecs.FargateService(this, 'Service', {
+  cluster,
+  taskDefinition,
+});
+
+// Force a new deployment
+service.forceNewDeployment(true);
+```
+
+You can also disable force new deployment by calling the method with `false`:
+
+```ts
+// Disable force new deployment
+service.forceNewDeployment(false);
+```
+
+The `forceNewDeployment` method works with all service types including `FargateService`, `Ec2Service`, and `ExternalService`. Each call to this method generates a unique timestamp nonce, ensuring that multiple services or multiple calls to the same service will have different nonces.

packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts

@@ -861,6 +861,25 @@ export abstract class BaseService extends Resource
     this.node.defaultChild = this.resource;
   }
 
+  /**
+   * Forces a new deployment of the service.
+   *
+   * This can be used to trigger a deployment without changing the task definition or desired count.
+   * When enabled, ECS will start a new deployment even if there are no changes to the service configuration.
+   *
+   * @param enable - Whether to enable force new deployment
+   */
+  public forceNewDeployment(enable: boolean) {
+    if (!this.isEcsDeploymentController) {
+      throw new ValidationError('forceNewDeployment requires the ECS deployment controller.', this);
+    }
+
+    this.resource.forceNewDeployment = {
+      enableForceNewDeployment: enable,
+      forceNewDeploymentNonce: enable? new Date().toISOString() : '',
+    };
+  }
+
   /**
    * Add a deployment lifecycle hook target
    * @param target The lifecycle hook target to add

packages/aws-cdk-lib/aws-ecs/test/base-service.test.ts

@@ -517,3 +517,181 @@ describe('Blue/Green Deployment', () => {
     expect(service.isUsingECSDeploymentController()).toBe(false);
   });
 });
+
+describe('forceNewDeployment', () => {
+  let stack: cdk.Stack;
+  let vpc: ec2.Vpc;
+  let cluster: ecs.Cluster;
+  let taskDefinition: ecs.FargateTaskDefinition;
+
+  beforeEach(() => {
+    stack = new cdk.Stack();
+    vpc = new ec2.Vpc(stack, 'Vpc');
+    cluster = new ecs.Cluster(stack, 'EcsCluster', { vpc });
+    taskDefinition = new ecs.FargateTaskDefinition(stack, 'FargateTaskDef');
+    taskDefinition.addContainer('web', {
+      image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
+    });
+  });
+
+  test('should enable force new deployment when called with true', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+    });
+
+    // WHEN
+    service.forceNewDeployment(true);
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: {
+        EnableForceNewDeployment: true,
+        ForceNewDeploymentNonce: Match.stringLikeRegexp('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
+      },
+    });
+  });
+
+  test('should disable force new deployment when called with false', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+    });
+
+    // WHEN
+    service.forceNewDeployment(false);
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: {
+        EnableForceNewDeployment: false,
+        ForceNewDeploymentNonce: '',
+      },
+    });
+  });
+
+  test('should work with EC2 service', () => {
+    // GIVEN
+    cluster.addCapacity('DefaultAutoScalingGroup', {
+      instanceType: new ec2.InstanceType('t3.micro'),
+      minCapacity: 1,
+    });
+    const ec2TaskDefinition = new ecs.Ec2TaskDefinition(stack, 'Ec2TaskDef');
+    ec2TaskDefinition.addContainer('web', {
+      image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
+      memoryLimitMiB: 512,
+    });
+    const service = new ecs.Ec2Service(stack, 'Ec2Service', {
+      cluster,
+      taskDefinition: ec2TaskDefinition,
+    });
+
+    // WHEN
+    service.forceNewDeployment(true);
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: {
+        EnableForceNewDeployment: true,
+        ForceNewDeploymentNonce: Match.stringLikeRegexp('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
+      },
+    });
+  });
+
+  test('should work with different deployment controllers', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+      deploymentController: {
+        type: ecs.DeploymentControllerType.ECS,
+      },
+    });
+
+    // WHEN
+    service.forceNewDeployment(true);
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: {
+        EnableForceNewDeployment: true,
+        ForceNewDeploymentNonce: Match.stringLikeRegexp('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
+      },
+    });
+  });
+
+  test('should allow multiple calls to forceNewDeployment', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+    });
+
+    // WHEN
+    service.forceNewDeployment(true);
+    service.forceNewDeployment(false);
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: {
+        EnableForceNewDeployment: false,
+        ForceNewDeploymentNonce: '',
+      },
+    });
+  });
+
+  test('should not set ForceNewDeployment property when not called', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+    });
+
+    // WHEN - not calling forceNewDeployment
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::ECS::Service', {
+      ForceNewDeployment: Match.absent(),
+    });
+  });
+
+  test('should throw error when forceNewDeployment is called with non-ECS deployment controller', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+      deploymentController: {
+        type: ecs.DeploymentControllerType.CODE_DEPLOY,
+      },
+    });
+
+    // WHEN & THEN
+    expect(() => {
+      service.forceNewDeployment(true);
+    }).toThrow('forceNewDeployment requires the ECS deployment controller.');
+  });
+
+  test('should throw error when forceNewDeployment is called with EXTERNAL deployment controller', () => {
+    // GIVEN
+    const service = new ecs.FargateService(stack, 'FargateService', {
+      cluster,
+      taskDefinition,
+      deploymentController: {
+        type: ecs.DeploymentControllerType.EXTERNAL,
+      },
+    });
+
+    // WHEN & THEN
+    expect(() => {
+      service.forceNewDeployment(true);
+    }).toThrow('forceNewDeployment requires the ECS deployment controller.');
+  });
+});