attp-bootstrap.cfn.yaml

---
AWSTemplateFormatVersion: "2010-09-09"

Description: |-
  Quick-start CloudFormation template to deploy the Amazon Textract Transformer Pipeline sample via
  AWS CodeBuild - with no local CDK/Docker/Python/etc developer setup required.

  This stack sets up a CodeBuild Project to deploy the main solution and triggers the build once
  (via AWS Lambda) on stack create, plus again whenever the CodeBuildTrigger resource is updated.
  On deletion, it triggers another CodeBuild job to attempt to destroy the CDK stack. Grants broad
  permissions to CodeBuild - not recommended for use in production environments.

Parameters:
  # TODO: Would be nice to support https:// S3 zip URLs here rather than only git repositories
  CodeRepo:
    Type: String
    Default: https://github.com/aws-samples/amazon-textract-transformer-pipeline
    Description: URL of the public git repository to use.

  CodeRepoBranch:
    Type: String
    Default: main
    Description: Branch (or commit hash) of the repository to deploy from.

  ProjectId:
    Type: String
    Default: ocr-transformers-demo
    Description: |-
      Prefix for created SSM parameters, and ID with which users can look up the deployed pipeline
      from notebooks. Alphanumeric with internal hyphens allowed.
    AllowedPattern: "[a-zA-Z](-?[a-zA-Z0-9])*"

  UseThumbnails:
    Type: String
    Default: Yes
    Description: |-
      When 'Yes', the pipeline generates page image thumbnails for incoming documents and passes
      these through to SageMaker enrichment model - which improves accuracy with models that
      consume page images, but is not necessary for those that don't. Set 'No' to disable this if
      you'll ONLY be working with layout-only model architectures (e.g. LayoutLMv1).
    AllowedValues:
      - Yes
      - No

  BuildSageMakerOCRs:
    Type: String
    Default: ""
    Description: |-
      Comma-separated list of alternative OCR engine names for which SageMaker container images
      should be prepared. Currently only 'tesseract' is supported.

  DeploySageMakerOCRs:
    Type: String
    Default: ""
    Description: |-
      Comma-separated list of alternative OCR engine names for which SageMaker endpoints should be
      actually deployed. Any names in here MUST also be included in BuildSageMakerOCRs.

  UseSageMakerOCR:
    Type: String
    Default: ""
    Description: |-
      Optionally set ONE open-source OCR engine name to be actually used by the deployed pipeline
      instead of Amazon Textract. This may be useful if you need to read docs in languages not
      currently supported by the Amazon Textract service.
    AllowedValues:
      - ""
      - tesseract

Metadata:
  AWS::CloudFormation::Interface:
    ParameterGroups:
      - Label:
          default: Pipeline Setup
        Parameters:
          - ProjectId
          - UseThumbnails
      - Label:
          default: OCR Alternatives
        Parameters:
          - BuildSageMakerOCRs
          - DeploySageMakerOCRs
          - UseSageMakerOCR

Resources:
  CodeBuildServiceRole:
    Type: "AWS::IAM::Role"
    Metadata:
      cfn_nag:
        rules_to_suppress:
          - id: W11
            reason: "Not recommended for use in production environments: Grants CodeBuild broad access to deploy/destroy the CDK solution without scoping down individual required services & resources"
          - id: W44
            reason: "Not recommended for use in production environments: Grants CodeBuild broad access to deploy/destroy the CDK solution without scoping down individual required services & resources"
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: codebuild.amazonaws.com
            Action: "sts:AssumeRole"
      Policies:
        - PolicyName: StackDeploymentPerms
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: IAMAccess
                Effect: Allow
                Action:
                  - "iam:AttachRolePolicy"
                  - "iam:CreatePolicy"
                  - "iam:CreatePolicyVersion"
                  - "iam:CreateRole"
                  - "iam:DeletePolicy"
                  - "iam:DeletePolicyVersion"
                  - "iam:DeleteRole"
                  - "iam:DeleteRolePolicy"
                  - "iam:GetPolicy"
                  - "iam:GetPolicyVersion"
                  - "iam:GetRole"
                  - "iam:GetRolePolicy"
                  - "iam:PutRolePolicy"
                  - "iam:TagPolicy"
                  - "iam:TagRole"
                  - "iam:UpdateRole"
                  - "iam:UpdateRoleDescription"
                Resource: "*"
      ManagedPolicyArns:
        - "arn:aws:iam::aws:policy/PowerUserAccess"

  CodeBuildProject:
    Type: "AWS::CodeBuild::Project"
    Metadata:
      cfn_nag:
        rules_to_suppress:
          - id: W32
            reason: "Use default S3 encryption - no actual artifacts being created"
    Properties:
      Artifacts:
        Type: NO_ARTIFACTS
      ConcurrentBuildLimit: 1
      Description: "CDK stack deployer"
      Environment:
        ComputeType: BUILD_GENERAL1_MEDIUM
        EnvironmentVariables:
          - Name: NO_PREBUILT_LAMBDA
            Type: PLAINTEXT
            Value: '1'  # TODO: https://github.com/cdklabs/cdk-ecr-deployment/issues/651
          - Name: PUBLIC_REPO
            Type: PLAINTEXT
            Value: !Ref CodeRepo
          - Name: PUBLIC_REPO_BRANCH
            Type: PLAINTEXT
            Value: !Ref CodeRepoBranch
          - Name: DEFAULT_PROJECT_ID
            Type: PLAINTEXT
            Value: !Ref ProjectId
          - Name: USE_THUMBNAILS
            Type: PLAINTEXT
            Value: !Ref UseThumbnails
          - Name: BUILD_SM_OCRS
            Type: PLAINTEXT
            Value: !Ref BuildSageMakerOCRs
          - Name: DEPLOY_SM_OCRS
            Type: PLAINTEXT
            Value: !Ref DeploySageMakerOCRs
          - Name: USE_SM_OCR
            Type: PLAINTEXT
            Value: !Ref UseSageMakerOCR
        Image: "aws/codebuild/standard:7.0"
        ImagePullCredentialsType: CODEBUILD
        PrivilegedMode: true # Need to build container images within the project
        Type: LINUX_CONTAINER
      QueuedTimeoutInMinutes: 80
      ServiceRole: !GetAtt CodeBuildServiceRole.Arn
      Source:
        BuildSpec: |
          version: 0.2
          env:
            variables:
              CDK_NEW_BOOTSTRAP: "1"
          phases:
            pre_build:
              commands:
                - set -ex
                - curl -sSL https://install.python-poetry.org/ | python3 -
                - export PATH="/root/.local/bin:$PATH"
                - npm install -g aws-cdk
                # Up-front install to fail early (but we reinst later in case it's overwritten):
                - pip3 install "requests>=2.27,<3"
            build:
              commands:
                - set -ex
                - git clone --single-branch -b $PUBLIC_REPO_BRANCH --depth 1 $PUBLIC_REPO code
                - cd code
                - poetry install --no-root
                - poetry run cdk bootstrap
                - if [ "$CFN_EVENT_TYPE" = "Delete" ]; then poetry run cdk destroy --all --force; else poetry run cdk deploy --all --require-approval never; fi
              finally:
                # Re-install requests in case it got overwritten:
                - pip3 install "requests>=2.27,<3"
                - |
                  cat <<EOS | python3 -
                  import json
                  import os
                  import requests  # (You'll need to install this!)
                  resp_url = os.environ.get("CFN_EVENT_RESPONSE_URL")
                  if not resp_url:
                      print("No CloudFormation response URL provided")
                      exit(0)
                  try:
                      data = json.loads(os.environ["CFN_EVENT_DATA"])
                      data["Status"] = "SUCCESS" if int(os.environ["CODEBUILD_BUILD_SUCCEEDING"]) else "FAILED"
                      build_arn = os.environ["CODEBUILD_BUILD_ARN"]
                      data["PhysicalResourceId"] = build_arn
                      log_stream = os.environ.get("CODEBUILD_LOG_PATH")
                      data["Reason"] = "See details in " + (
                          f"CodeBuild's CloudWatch Log Stream {log_stream}" if log_stream else f"AWS CodeBuild {build_arn}"
                      )
                      response = requests.put(resp_url, data=json.dumps(data))
                      print(f"Notified CloudFormation of {data['Status']}")
                  except Exception as e:
                      print(f"Failed to send response to CloudFormation event handler")
                      raise e
                  EOS
        SourceIdentifier: coderepo
        Type: NO_SOURCE
      TimeoutInMinutes: 60

  # Creating a CodeBuild project in CloudFormation doesn't automatically start a build, so below we
  # set up an AWS Lambda Function based Custom Resource to trigger the build whenever the stack is
  # created or updated:

  LambdaExecutionRole:
    Type: "AWS::IAM::Role"
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - lambda.amazonaws.com
            Action:
              - "sts:AssumeRole"
      ManagedPolicyArns:
        - 'arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole' # (CloudWatch Logs)
      Policies:
        - PolicyName: RunCodeBuildProject
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: RunCodeBuild
                Effect: Allow
                Action:
                  - "codebuild:StartBuild"
                Resource:
                  - !GetAtt CodeBuildProject.Arn

  CodeBuildTriggerFunction:
    Type: "AWS::Lambda::Function"
    Metadata:
      cfn_nag:
        rules_to_suppress:
          - id: W89
            reason: "IAM will authorize access to this rarely-used function: No need to put in VPC"
          - id: W92
            reason: "Only to be invoked by CREATE/UPDATE/DELETE CFN events for this stack: no reserved concurrency required"
    Properties:
      Description: "CloudFormation custom resource implementation for running CodeBuild project"
      Code:
        ZipFile: |
          # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
          """Custom CloudFormation Resource to kick off CodeBuild project builds

          CFn Properties
          --------------
          ProjectName : string
              Name of the AWS CodeBuild project to run
          BuildOnDelete : Optional[bool]
              Set `True` to also run a build on CloudFormation `Delete` events (i.e. if your CodeBuild
              script will detect that `CFN_EVENT_TYPE` is `Delete` and destroy its resources)
          CodeBuildCallback : Optional[bool]
              Set `True` if your CodeBuild project will handle the CloudFormation CR callback, or leave
              default (False) to report success as soon as the build is triggered.
          IgnoreUpdate : Optional[bool]
              Set `True` to only trigger a build on initial `Create` events and ignore subsequent `Update`s

          CodeBuild Env Var Overrides
          ---------------------------
          CFN_EVENT_TYPE : Union["Create", "Update", "Delete"]
              Type of CloudFormation event that triggered the build
          CFN_EVENT_DATA : str
              JSON object containing LogicalResourceId, RequestId, StackId, NoEcho, and (empty) Data that
              your CodeBuild should post back to CloudFormation on completion/failure (when provided). Note
              your build project will need to add the `Status`, `Reason`, and `PhysicalResourceId` fields.
          CFN_EVENT_RESPONSE_URL : str
              URL to which the CloudFormation response data should be `PUT` (if provided)
          """

          # Python Built-Ins:
          import json
          import logging
          import traceback

          # External Dependencies:
          import boto3
          import cfnresponse

          codebuild = boto3.client("codebuild")

          def lambda_handler(event, context):
              try:
                  request_type = event["RequestType"]
                  if request_type == "Create":
                      handle_create(event, context)
                  elif request_type == "Update":
                      handle_update(event, context)
                  elif request_type == "Delete":
                      handle_delete(event, context)
                  else:
                      cfnresponse.send(
                          event,
                          context,
                          cfnresponse.FAILED,
                          { "Reason": f"Unsupported CFN RequestType '{request_type}'" },
                      )
              except Exception as e:
                  logging.error("Uncaught exception in CFN custom resource handler - reporting failure")
                  traceback.print_exc()
                  cfnresponse.send(
                      event,
                      context,
                      cfnresponse.FAILED,
                      { "Reason": str(e) },
                  )
                  raise e


          def get_cfn_env_var_overrides(event):
              res_config = event.get("ResourceProperties", {})
              result = [
                  {"name": "CFN_EVENT_TYPE", "type": "PLAINTEXT", "value": event["RequestType"]},
              ]
              if res_config.get("CodeBuildCallback"):
                  result += [
                      {
                          "name": "CFN_EVENT_DATA",
                          "type": "PLAINTEXT",
                          "value": json.dumps({
                              "LogicalResourceId": event["LogicalResourceId"],
                              "RequestId": event["RequestId"],
                              "StackId": event["StackId"],
                              "NoEcho": event["ResourceProperties"].get("NoEcho", False),
                              "Data": {},
                          }),
                      },
                      {
                          "name": "CFN_EVENT_RESPONSE_URL",
                          "type": "PLAINTEXT",
                          "value": event["ResponseURL"],
                      },
                  ]
              return result


          def handle_create(event, context):
              logging.info("**Received create request - running CodeBuild job")
              res_config = event["ResourceProperties"]
              codebuild_env_vars = get_cfn_env_var_overrides(event)
              result = codebuild.start_build(
                  projectName=res_config["ProjectName"],
                  environmentVariablesOverride=codebuild_env_vars,
              )
              if not res_config.get("CodeBuildCallback"):
                  cfnresponse.send(
                      event,
                      context,
                      cfnresponse.SUCCESS,
                      { "Reason": f"Started CodeBuild #{result['build']['buildNumber']}" },
                      physicalResourceId=result["build"]["arn"],
                  )

          def handle_delete(event, context):
              logging.info("**Received delete event - no-op")
              res_config = event.get("ResourceProperties", {})
              build_on_delete = res_config.get("BuildOnDelete", False)
              if build_on_delete:
                  codebuild_env_vars = get_cfn_env_var_overrides(event)
                  codebuild.start_build(
                      projectName=res_config["ProjectName"],
                      environmentVariablesOverride=codebuild_env_vars,
                  )
                  reason = "Deletion build initiated"
              else:
                  reason = "Delete is a no-op"
              if not (build_on_delete and res_config.get("CodeBuildCallback")):
                  cfnresponse.send(
                      event,
                      context,
                      cfnresponse.SUCCESS,
                      { "Reason": reason },
                      physicalResourceId=event["PhysicalResourceId"],
                  )

          def handle_update(event, context):
              logging.info("**Received update event - re-running build")
              res_config = event.get("ResourceProperties", {})
              ignore_update = res_config.get("IgnoreUpdate", False)
              if ignore_update:
                  reason = "Update is a no-op"
              else:
                  codebuild_env_vars = get_cfn_env_var_overrides(event)
                  result = codebuild.start_build(
                      projectName=res_config["ProjectName"],
                      environmentVariablesOverride=codebuild_env_vars,
                  )
                  if res_config.get("CodeBuildCalback"):
                      reason = None
                  else:
                      reason = f"Started CodeBuild #{result['build']['buildNumber']}"
              if reason is not None:
                  cfnresponse.send(
                      event,
                      context,
                      cfnresponse.SUCCESS,
                      { "Reason": reason },
                      physicalResourceId=event["PhysicalResourceId"],
                  )

      Handler: "index.lambda_handler"
      MemorySize: 128
      Role: !GetAtt LambdaExecutionRole.Arn
      Runtime: python3.10
      Timeout: 900

  ATTPDeployment:
    Type: "Custom::CodeBuildTrigger"
    Properties:
      ServiceToken: !GetAtt CodeBuildTriggerFunction.Arn
      ProjectName: !Ref CodeBuildProject
      BuildOnDelete: true
      # NOTE: If CDK deployment takes longer than 1 hour, this CodeBuild-based callback to
      # CloudFormation *will not work* because CFn will time out. In that case can comment out /
      # unset `CodeBuildCallback`, and the ATTP stack will "succeed" as soon as the CodeBuild job
      # is triggered, without waiting for it to complete.
      CodeBuildCallback: true

Outputs:
  CodeBuildProjectArn:
    Description: ARN of the AWS CodeBuild project created to deploy the solution
    Value: !GetAtt CodeBuildProject.Arn
  CodeBuildProjectName:
    Description: Name of the AWS CodeBuild project created to deploy the solution
    Value: !Ref CodeBuildProject
  CodeBuildConsoleLink:
    Description: Link to project in AWS CodeBuild Console
    Value: !Sub "https://${AWS::Region}.console.aws.amazon.com/codesuite/codebuild/${AWS::AccountId}/projects/${CodeBuildProject}"