template.yml

---
AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31
Description: >-
  Step Functions and lambdas to interact with Stax to CUD (create-update-delete)
  workloads and monitor task operations in your AWS Account(s).

Parameters:
  PythonLoggingLevel:
    Type: String
    Description: Python logging level for Lambda functions
    Default: INFO
    AllowedValues:
      - INFO
      - DEBUG
      - WARNING
      - ERROR
      - CRITICAL
  DeployWorkloadStateMachine:
    Type: String
    Description: >-
      Deploy workload state machine to CUD (create-update-delete) workloads.
    Default: "false"
    AllowedValues:
      - "true"
      - "false"
  DeployWorkloadCloudwatchDashboard:
    Type: String
    Description: >-
      Deploy workload cloudwatch dashboard to view stax orchestrator
      step function metrics and logs.
    Default: "false"
    AllowedValues:
      - "true"
      - "false"
  DeployTaskWatcherCloudwatchDashboard:
    Type: String
    Description: >-
      Deploy workload cloudwatch dashboard to view stax orchestrator
      step function metrics and logs.
    Default: "false"
    AllowedValues:
      - "true"
      - "false"
  LambdaLogGroupRetentionInDays:
    Type: Number
    Description: >-
      Number of days to retain lambda function logs;
      applies to all lambda functions in this template
    AllowedValues:
      - 1
      - 3
      - 5
      - 7
      - 14
      - 30
      - 60
      - 90
      - 120
      - 150
      - 180
      - 365
      - 400
      - 545
      - 731
      - 1827
      - 2192
      - 2557
      - 2922
      - 3288
      - 3653
    Default: 60
  EnableStateMachineTracing:
    Type: String
    Description: Enable X-Ray tracing for state machines
    Default: "false"
    AllowedValues:
      - "true"
      - "false"
  EnableLambdaTracing:
    Type: String
    Description: Enable X-Ray tracing for lambda functions
    Default: "false"
    AllowedValues:
      - "true"
      - "false"
  EnableAlerting:
    Type: String
    Description: >-
      Get alerts for failed step function executions; alerts on
      failed workload deployments. Provide https endpoint or email
      address to send alerts to.
    Default: "true"
    AllowedValues:
      - "true"
      - "false"
  AlertsHttpsEndpoint:
    Type: String
    Description: >-
      HTTPS endpoint to send alerts to.
    Default: ""
  AlertsEmail:
    Type: String
    Description: >-
      Email address to send alerts to.
    Default: ""

Metadata:
  AWS::ServerlessRepo::Application:
    Name: stax-orchestrator
    Description: >-
      Stax Workloads Orchestrator -
      Interact with Stax to CUD (create-update-delete)
      workloads in your AWS Account(s).
    Author: Versent
    SpdxLicenseId: Apache-2.0
    LicenseUrl: LICENSE
    ReadmeUrl: README.md
    Labels: ['AWS', 'Stax', 'Serverless', 'Lambda', 'StepFunction']
    HomePageUrl: https://github.com/Versent/stax-orchestrator.git
    SourceCodeUrl: https://github.com/Versent/stax-orchestrator.git

Conditions:
  WorkloadStateMachineEnabled: !Equals [!Ref DeployWorkloadStateMachine, "true"]
  WorkloadCloudwatchDashboardEnabled: !And
    - !Equals [!Ref DeployWorkloadCloudwatchDashboard, "true"]
    - Condition: WorkloadStateMachineEnabled
  TaskWatcherCloudwatchDashboardEnabled: !Equals
    - !Ref DeployTaskWatcherCloudwatchDashboard
    - "true"
  StateMachineTracingEnabled: !Equals [!Ref EnableStateMachineTracing, "true"]
  LambdaTracingEnabled: !Equals [!Ref EnableLambdaTracing, "true"]
  AlertHttpsEndpointProvided: !Not [!Equals [!Ref AlertsHttpsEndpoint, ""]]
  EnableAlerting: !Equals [!Ref EnableAlerting, "true"]
  SubscribeHttpsEndpoint: !And
    - Condition: EnableAlerting
    - Condition: WorkloadStateMachineEnabled
    - Condition: AlertHttpsEndpointProvided
  AlertEmailProvided: !Not [!Equals [!Ref AlertsEmail, ""]]
  SubscribeEmail: !And
    - Condition: EnableAlerting
    - Condition: WorkloadStateMachineEnabled
    - Condition: AlertEmailProvided

Globals:
  Function:
    Runtime: python3.11
    MemorySize: 128
    Timeout: 300
    Environment:
      Variables:
        LOG_LEVEL: !Ref PythonLoggingLevel
    Layers:
      - !Ref StaxLibLayer
    Architectures:
      - arm64

Resources:
  WorkloadStateMachine:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: statemachines/workload.asl.json
      Tracing:
        Enabled: !If [StateMachineTracingEnabled, true, false]
      DefinitionSubstitutions:
        ValidateInputLambdaArn: !GetAtt ValidateInputLambda.Arn
        CreateWorkloadLambdaArn: !GetAtt CreateWorkloadLambda.Arn
        UpdateWorkloadLambdaArn: !GetAtt UpdateWorkloadLambda.Arn
        DeleteWorkloadLambdaArn: !GetAtt DeleteWorkloadLambda.Arn
        TaskFactoryArn: !GetAtt TaskWatcherStateMachine.Arn
      Role: !GetAtt WorkloadStateMachineRole.Arn

  WorkloadStateMachineRole:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::IAM::Role
    Properties:
      Description: >-
        Permissions for Stax Orchestrator Workload State Machine to invoke
        lambdas and start step function executions
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              Service: !Sub states.${AWS::Region}.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - !Ref StaxOrchestratorSfnPolicy
      Policies:
        - PolicyName: WorkloadStateMachinePolicy
          PolicyDocument:
            Statement:
              - Sid: InvokeLambdaPolicy
                Effect: Allow
                Action: lambda:InvokeFunction
                Resource:
                  - !GetAtt ValidateInputLambda.Arn
                  - !GetAtt CreateWorkloadLambda.Arn
                  - !GetAtt UpdateWorkloadLambda.Arn
                  - !GetAtt DeleteWorkloadLambda.Arn
              - Sid: StartStepFunctionExecutionPolicy
                Effect: Allow
                Action: states:StartExecution
                Resource:
                  - !Ref TaskWatcherStateMachine

  TaskWatcherStateMachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: statemachines/task_watcher.asl.json
      Tracing:
        Enabled: !If [StateMachineTracingEnabled, true, false]
      DefinitionSubstitutions:
        GetTaskStatusLambdaArn: !GetAtt GetTaskStatusLambda.Arn
      Role: !GetAtt TaskWatcherStateMachineRole.Arn

  TaskWatcherStateMachineRole:
    Type: AWS::IAM::Role
    Properties:
      Description: >-
        Permissions for Stax Orchestrator Task Watcher State Machine
        to assume role and invoke GetTaskStatusLambda
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              Service: !Sub states.${AWS::Region}.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - !Ref StaxOrchestratorSfnPolicy
      Policies:
        - PolicyName: TaskWatcherStateMachinePolicy
          PolicyDocument:
            Statement:
              - Sid: InvokeGetTaskStatusLambdaPolicy
                Effect: Allow
                Action: lambda:InvokeFunction
                Resource:
                  - !GetAtt GetTaskStatusLambda.Arn

  ValidateInputLambda:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Serverless::Function
    Properties:
      Description: >-
        Validate user input required to create/update/delete workloads
      CodeUri: functions/validate_input/
      Handler: app.lambda_handler
      Tracing: !If [LambdaTracingEnabled, Active, !Ref AWS::NoValue]
      Policies:
        - !Ref StaxOrchestratorLambdaPolicy
        - Fn::If:
            - LambdaTracingEnabled
            - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
            - !Ref AWS::NoValue

  CreateWorkloadLambda:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Serverless::Function
    Properties:
      Description: Invoke Stax API to create a workload
      CodeUri: functions/create_workload/
      Handler: app.lambda_handler
      Tracing: !If [LambdaTracingEnabled, Active, !Ref AWS::NoValue]
      Policies:
        - !Ref StaxOrchestratorLambdaPolicy
        - Fn::If:
            - LambdaTracingEnabled
            - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
            - !Ref AWS::NoValue

  UpdateWorkloadLambda:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Serverless::Function
    Properties:
      Description: Invoke Stax API to update a workload
      CodeUri: functions/update_workload/
      Handler: app.lambda_handler
      Tracing: !If [LambdaTracingEnabled, Active, !Ref AWS::NoValue]
      Policies:
        - !Ref StaxOrchestratorLambdaPolicy
        - Fn::If:
            - LambdaTracingEnabled
            - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
            - !Ref AWS::NoValue

  DeleteWorkloadLambda:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Serverless::Function
    Properties:
      Description: Invoke Stax API to delete a workload
      CodeUri: functions/delete_workload/
      Handler: app.lambda_handler
      Tracing: !If [LambdaTracingEnabled, Active, !Ref AWS::NoValue]
      Policies:
        - !Ref StaxOrchestratorLambdaPolicy
        - Fn::If:
            - LambdaTracingEnabled
            - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
            - !Ref AWS::NoValue

  GetTaskStatusLambda:
    Type: AWS::Serverless::Function
    Properties:
      Description: Get status of a workload task
      CodeUri: functions/get_task_status/
      Handler: app.lambda_handler
      Tracing: !If [LambdaTracingEnabled, Active, !Ref AWS::NoValue]
      Policies:
        - !Ref StaxOrchestratorLambdaPolicy
        - Fn::If:
            - LambdaTracingEnabled
            - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
            - !Ref AWS::NoValue

  StaxLibLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: orchestrator-stax-lib-lambda-layer
      Description: >-
        Lambda layer containing dependencies for stax
        orchestrator lambda functions
      LicenseInfo: Available under the Apache license.
      ContentUri: .
      CompatibleArchitectures:
        - arm64
      CompatibleRuntimes:
        - python3.11
      RetentionPolicy: Delete
    Metadata:
      BuildMethod: makefile
      BuildArchitecture: arm64

  StaxLibLayerPermission:
    Type: AWS::Lambda::LayerVersionPermission
    Properties:
      Action: lambda:GetLayerVersion
      LayerVersionArn: !Ref StaxLibLayer
      Principal: !Ref AWS::AccountId

  StaxOrchestratorLambdaPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      Description: >-
        Stax Orchestrator Managed Policy for
        lambda functions to interact with AWS Resources.
      PolicyDocument:
        Version: 2012-10-17
        Statement:
          - Sid: AllowGetStaxAccessKeyAndSecretPolicy
            Effect: Allow
            Action:
              - ssm:GetParameter
            Resource:
              # yamllint disable rule:line-length
              - !Sub arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/orchestrator/stax/access/key
              - !Sub arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/orchestrator/stax/access/key/secret
              # yamllint enable rule:line-length

  StaxOrchestratorSfnPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      Description: >-
        Stax Orchestrator Managed Policy for
        step functions to interact with AWS Resources.
      PolicyDocument:
        Version: 2012-10-17
        Statement:
          - Sid: AllowEventsPutAndDescribePolicy
            Effect: Allow
            Action:
              - events:PutTargets
              - events:PutRule
              - events:DescribeRule
            Resource:
              # yamllint disable rule:line-length
              - !Sub arn:aws:events:${AWS::Region}:${AWS::AccountId}:rule/StepFunctionsGetEventsForStepFunctionsExecutionRule
              # yamllint enable rule:line-length
          - !If
            - StateMachineTracingEnabled
            - Sid: AllowXrayTracingPolicy
              Effect: Allow
              Action:
                - xray:PutTraceSegments
                - xray:PutTelemetryRecords
                - xray:GetSamplingRules
                - xray:GetSamplingTargets
                - xray:GetSamplingStatisticSummaries
              Resource:
                - '*'
            - Ref: AWS::NoValue

  ValidateInputLambdaLogGroup:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${ValidateInputLambda}
      RetentionInDays: !Ref LambdaLogGroupRetentionInDays

  CreateWorkloadLambdaLogGroup:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${CreateWorkloadLambda}
      RetentionInDays: !Ref LambdaLogGroupRetentionInDays

  UpdateWorkloadLambdaLogGroup:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${UpdateWorkloadLambda}
      RetentionInDays: !Ref LambdaLogGroupRetentionInDays

  DeleteWorkloadLambdaLogGroup:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${DeleteWorkloadLambda}
      RetentionInDays: !Ref LambdaLogGroupRetentionInDays

  GetTaskStatusLambdaLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${GetTaskStatusLambda}
      RetentionInDays: !Ref LambdaLogGroupRetentionInDays

  StaxOrchestratorWorkloadDashboard:
    Condition: WorkloadCloudwatchDashboardEnabled
    Type: AWS::CloudWatch::Dashboard
    Properties:
      # yamllint disable rule:line-length
      DashboardBody: !Sub |
            {
              "widgets": [
                {
                  "type": "log",
                  "x": 10,
                  "y": 6,
                  "width": 14,
                  "height": 3,
                  "properties": {
                    "query": "SOURCE '/aws/lambda/${CreateWorkloadLambda}' | fields @message\r\n| filter @message like /ERROR/",
                    "region": "${AWS::Region}",
                    "stacked": false,
                    "title": "Create Workload Error Logs",
                    "view": "table"
                  }
                },
                {
                  "type": "log",
                  "x": 10,
                  "y": 6,
                  "width": 14,
                  "height": 3,
                  "properties": {
                    "query": "SOURCE '/aws/lambda/${UpdateWorkloadLambda}' | fields @message\r\n| filter @message like /ERROR/",
                    "region": "${AWS::Region}",
                    "stacked": false,
                    "title": "Update Workload Error Logs",
                    "view": "table"
                  }
                },
                {
                  "type": "log",
                  "x": 10,
                  "y": 6,
                  "width": 14,
                  "height": 3,
                  "properties": {
                    "query": "SOURCE '/aws/lambda/${DeleteWorkloadLambda}' | fields @message\r\n| filter @message like /ERROR/",
                    "region": "${AWS::Region}",
                    "stacked": false,
                    "title": "Delete Workload Error Logs",
                    "view": "table"
                  }
                },
                {
                  "type": "metric",
                  "x": 0,
                  "y": 0,
                  "width": 10,
                  "height": 3,
                  "properties": {
                    "view": "singleValue",
                    "metrics": [
                      [ "AWS/States", "ExecutionsFailed", "StateMachineArn", "${WorkloadStateMachine}", {"color": "#ff0000"} ],
                      [ ".", "ExecutionsSucceeded", ".", ".", {"color": "#2ca02c"} ],
                      [ ".", "ExecutionsAborted", ".", ".", {"color": "#ffa500"} ]
                    ],
                    "stat": "Sum",
                    "setPeriodToTimeRange": true,
                    "region": "${AWS::Region}",
                    "title": "WorkloadStateMachine Executions",
                    "period": 300
                  }
                },

                {
                  "type": "metric",
                  "x": 0,
                  "y": 9,
                  "width": 10,
                  "height": 4,
                  "properties": {
                      "view": "timeSeries",
                      "stacked": false,
                      "metrics": [
                          [ "AWS/States", "ExecutionsSucceeded", "StateMachineArn", "${WorkloadStateMachine}", {"color": "#2ca02c"} ],
                          [ ".", "ExecutionsFailed", ".", ".", {"color": "#ff0000"} ]
                      ],
                      "region": "${AWS::Region}",
                      "title": "Workload Operations Success Vs Failures"
                  }
                }
              ]
            }
      # yamllint enable rule:line-length

  StaxOrchestratorTaskDashboard:
    Condition: TaskWatcherCloudwatchDashboardEnabled
    Type: AWS::CloudWatch::Dashboard
    Properties:
      # yamllint disable rule:line-length
      DashboardBody: !Sub |
            {
              "widgets": [
                {
                  "type": "log",
                  "x": 10,
                  "y": 6,
                  "width": 14,
                  "height": 3,
                  "properties": {
                    "query": "SOURCE '/aws/lambda/${GetTaskStatusLambda}' | fields @message\r\n| filter @message like /ERROR/",
                    "region": "${AWS::Region}",
                    "stacked": false,
                    "title": "Get Task Status Error Logs",
                    "view": "table"
                  }
                },
                {
                  "type": "metric",
                  "x": 0,
                  "y": 0,
                  "width": 10,
                  "height": 3,
                  "properties": {
                    "view": "singleValue",
                    "metrics": [
                      [ "AWS/States", "ExecutionsFailed", "StateMachineArn", "${TaskWatcherStateMachine}", {"color": "#ff0000"} ],
                      [ ".", "ExecutionsSucceeded", ".", ".", {"color": "#2ca02c"} ],
                      [ ".", "ExecutionsAborted", ".", ".", {"color": "#ffa500"} ]
                    ],
                    "stat": "Sum",
                    "setPeriodToTimeRange": true,
                    "region": "${AWS::Region}",
                    "title": "TaskWatcherStateMachine Executions",
                    "period": 300
                  }
                },
                {
                  "type": "metric",
                  "x": 0,
                  "y": 9,
                  "width": 10,
                  "height": 4,
                  "properties": {
                      "view": "timeSeries",
                      "stacked": false,
                      "metrics": [
                          [ "AWS/States", "ExecutionsSucceeded", "StateMachineArn", "${TaskWatcherStateMachine}", {"color": "#2ca02c"} ],
                          [ ".", "ExecutionsFailed", ".", ".", {"color": "#ff0000"} ]
                      ],
                      "region": "${AWS::Region}",
                      "title": "TaskWatcher Operations Success Vs Failures"
                  }
                }
              ]
            }
      # yamllint enable rule:line-length

  FailedWorkloadStateMachineEventsRule:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::Events::Rule
    Properties:
      Description: Trigger SNS topic when WorkloadStateMachine fails
      Targets:
        - Arn: !Ref AlertsTopic
          Id: FailedWorkloadStateMachineEventsRule
      EventPattern:
        source:
          - aws.states
        detail-type:
          - Step Functions Execution Status Change
        detail:
          status:
            - FAILED
          stateMachineArn:
            - !Ref WorkloadStateMachine

  AlertsTopicPolicy:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::SNS::TopicPolicy
    Properties:
      PolicyDocument:
        Id: AlertsTopicPolicy
        Version: 2012-10-17
        Statement:
          - Sid: AllowEventsServiceToPublishToTopic
            Effect: Allow
            Principal:
              Service: events.amazonaws.com
            Action: sns:Publish
            Resource: !Ref AlertsTopic
      Topics:
        - !Ref AlertsTopic

  AlertsTopic:
    Condition: WorkloadStateMachineEnabled
    Type: AWS::SNS::Topic

  HttpEndpointSubscription:
    Condition: SubscribeHttpsEndpoint
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: https
      TopicArn: !Ref AlertsTopic
      Endpoint: !Ref AlertsHttpsEndpoint

  EmailSubscription:
    Condition: SubscribeEmail
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: email
      TopicArn: !Ref AlertsTopic
      Endpoint: !Ref AlertsEmail

Outputs:
  WorkloadStateMachineArn:
    Condition: WorkloadStateMachineEnabled
    Description: Stax orchestrator workload deployment step function arn
    Value: !Ref WorkloadStateMachine

  TaskWatcherStateMachineArn:
    Description: Stax orchestrator task watcher step function arn
    Value: !Ref TaskWatcherStateMachine

  AlertsTopicArn:
    Condition: WorkloadStateMachineEnabled
    Description: >-
      Stax orchestrator SNS topic arn to subscribe to for alert notifications
    Value: !Ref AlertsTopic