CloudFormation Custom Resource - Delete a non-empty S3 Bucket

AWSTemplateFormatVersion: '2010-09-09'
Description: 'Demo CloudFormation Native'

Parameters:
  BucketName:
    Type: String
    Default: d-s3-cmp-cleaning-on-delete-bucket
    Description: Name of the S3 bucket to create

Resources:
  # S3 Bucket
  demoBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Ref BucketName

This AWS::S3::Bucket resource is in a DELETE_FAILED state.
Resource handler returned message: "The bucket you tried to delete is not empty

AWSTemplateFormatVersion: '2010-09-09'
Description: 'Demo CloudFormation Custom Resource - safely delete a non-empty S3 Bucket'

Parameters:
  BucketPrefix:
    Type: String
    Default: d-s3-custom
    Description: Prefix for the S3 bucket name. Account ID is appended to keep it globally unique.
    AllowedPattern: '^[a-z0-9][a-z0-9-]{1,47}[a-z0-9]$'

Resources:

  # ---------------------------------------------------------------------------
  # S3 Bucket
  # ---------------------------------------------------------------------------
  demoBucket:
    Type: AWS::S3::Bucket
    # Explicit policies: default for S3 is already Delete, but being explicit
    # documents the intent and prevents surprises if someone copies this template.
    DeletionPolicy: Delete
    UpdateReplacePolicy: Delete
    Properties:
      # Bucket names are GLOBALLY unique -> never hardcode a bare name in a public lab.
      # No Region suffix here, so this stack can only exist in ONE region at a time.
      BucketName: !Sub '${BucketPrefix}-${AWS::AccountId}'
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
            BucketKeyEnabled: true
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

  # ---------------------------------------------------------------------------
  # IAM Role - least privilege, scoped to THIS bucket only
  # ---------------------------------------------------------------------------
  cleanupFunctionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: 'sts:AssumeRole'
      Policies:
        - PolicyName: logs-write-only
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              # CreateLogStream + PutLogEvents only.
              - Effect: Allow
                Action:
                  - 'logs:CreateLogStream'
                  - 'logs:PutLogEvents'
                Resource: !Sub 'arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/*:*'

        - PolicyName: s3-cleanup-scoped
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              # Bucket-level actions -> bucket ARN (no /*)
              # NOTE: we build the ARN from the PARAMETER, not !GetAtt demoBucket.Arn,
              #       otherwise Role -> Bucket -> ... creates an avoidable dependency chain.
              - Effect: Allow
                Action:
                  - 's3:ListBucket'
                  - 's3:ListBucketVersions'
                Resource: !Sub 'arn:${AWS::Partition}:s3:::${BucketPrefix}-${AWS::AccountId}'
              # Object-level actions -> object ARN (with /*)
              - Effect: Allow
                Action:
                  - 's3:DeleteObject'
                  - 's3:DeleteObjectVersion'
                Resource: !Sub 'arn:${AWS::Partition}:s3:::${BucketPrefix}-${AWS::AccountId}/*'

  # ---------------------------------------------------------------------------
  # Lambda function
  # ---------------------------------------------------------------------------
  cleanupFunction:
    Type: AWS::Lambda::Function
    Properties:
      Description: Empties an S3 bucket when the CloudFormation custom resource is deleted
      Handler: 'index.lambda_handler'
      Role: !GetAtt cleanupFunctionRole.Arn
      Runtime: 'python3.13'
      Timeout: 300
      MemorySize: 256
      Code:
        # cfnresponse is injected by CloudFormation ONLY when using inline ZipFile code.
        # If you move this code to S3 or a container image, you must vendor it yourself.
        ZipFile: |
          import json
          import signal
          import boto3
          import cfnresponse

          s3 = boto3.client('s3')

          # Stop this many seconds before the Lambda timeout so we can still answer CFN
          SAFETY_MARGIN_SEC = 20


          class NearTimeout(Exception):
              pass


          def _raise_near_timeout(signum, frame):
              raise NearTimeout('Lambda is about to time out - failing fast')


          def lambda_handler(event, context):
              print(f"Event received: {json.dumps(event)}")

              bucket_name = event.get('ResourceProperties', {}).get('BucketName', '')

              # Keep the physical ID STABLE and derived from the bucket.
              # If this value ever changes on Update, CFN treats it as a replacement and
              # sends a Delete for the OLD id -> it would wipe the bucket mid-update.
              physical_id = event.get('PhysicalResourceId') or f"s3cleanup-{bucket_name}"

              # Timer so we always send a response instead of dying silently (AWS best practice)
              remaining_sec = int(context.get_remaining_time_in_millis() / 1000)
              signal.signal(signal.SIGALRM, _raise_near_timeout)
              signal.alarm(max(remaining_sec - SAFETY_MARGIN_SEC, 1))

              try:
                  if event['RequestType'] == 'Delete':
                      deleted = empty_bucket(bucket_name)
                      cfnresponse.send(event, context, cfnresponse.SUCCESS,
                                       {'DeletedObjects': deleted}, physical_id)
                  else:
                      # Create / Update: nothing to do, just acknowledge immediately
                      cfnresponse.send(event, context, cfnresponse.SUCCESS, {}, physical_id)

              except Exception as e:
                  print(f"ERROR: {type(e).__name__}: {e}")
                  # ALWAYS answer CloudFormation. An unreported exception makes the stack
                  # wait for the 1h timeout, then wait AGAIN during rollback.
                  cfnresponse.send(event, context, cfnresponse.FAILED,
                                   {'Error': str(e)[:900]}, physical_id)
              finally:
                  signal.alarm(0)


          def empty_bucket(bucket_name):
              """Delete every object version AND delete marker. Idempotent."""
              total = 0
              try:
                  paginator = s3.get_paginator('list_object_versions')
                  for page in paginator.paginate(Bucket=bucket_name):
                      # list_object_versions also works on non-versioned buckets
                      # (VersionId is simply "null"), so one code path covers both.
                      keys = [
                          {'Key': o['Key'], 'VersionId': o['VersionId']}
                          for o in page.get('Versions', []) + page.get('DeleteMarkers', [])
                      ]
                      if not keys:
                          continue

                      # delete_objects accepts max 1000 keys per call - the paginator
                      # already caps each page at 1000.
                      resp = s3.delete_objects(
                          Bucket=bucket_name,
                          Delete={'Objects': keys, 'Quiet': True}
                      )

                      # CRITICAL: delete_objects returns HTTP 200 even for partial failures.
                      # Without this check we would report SUCCESS and the bucket delete
                      # would fail anyway - much harder to debug.
                      errors = resp.get('Errors', [])
                      if errors:
                          raise RuntimeError(f"Failed to delete {len(errors)} objects: {errors[:3]}")

                      total += len(keys)
                      print(f"Deleted {len(keys)} object versions (running total: {total})")

              except s3.exceptions.NoSuchBucket:
                  # Idempotency: a retried Delete on an already-gone bucket must succeed
                  print(f"Bucket {bucket_name} no longer exists - nothing to clean up")

              return total

  # ---------------------------------------------------------------------------
  # Log group - declared explicitly so it has retention AND is removed with the stack
  # ---------------------------------------------------------------------------
  cleanupFunctionLogGroup:
    Type: AWS::Logs::LogGroup
    DeletionPolicy: Delete
    Properties:
      LogGroupName: !Sub '/aws/lambda/${cleanupFunction}'
      RetentionInDays: 1

  # ---------------------------------------------------------------------------
  # Custom Resource
  # ---------------------------------------------------------------------------
  cleanupS3BucketOnDelete:
    Type: Custom::S3BucketCleanup
    # DependsOn drives the DELETE order (reverse of create order):
    #   create : demoBucket + logGroup  ->  cleanupS3BucketOnDelete
    #   delete : cleanupS3BucketOnDelete (empties bucket) -> demoBucket
    DependsOn:
      - demoBucket
      - cleanupFunctionLogGroup
    Properties:
      # ServiceToken creates an implicit dependency on cleanupFunction, so the Lambda
      # is guaranteed to still exist when the Delete event fires. Never reverse this.
      ServiceToken: !GetAtt cleanupFunction.Arn
      BucketName: !Ref demoBucket

Outputs:
  BucketName:
    Description: Name of the demo bucket
    Value: !Ref demoBucket

  BucketArn:
    Description: ARN of the demo bucket
    Value: !GetAtt demoBucket.Arn

  CleanupFunctionName:
    Description: Lambda function backing the custom resource
    Value: !Ref cleanupFunction

  LogGroupName:
    Description: Where to look when the custom resource misbehaves
    Value: !Ref cleanupFunctionLogGroup