AWS App Runner Service Active Instance Scaling Sentinel

id: aws-apprunner-service-active-instance-scaling-sentinel
namespace: company.cloud

description: Audits AWS App Runner services for active container instance
  saturation and provisioned concurrency limits.

concurrency:
  limit: 1

inputs:
  - id: awsRegion
    type: STRING
    displayName: AWS Region
    defaults: us-east-1
    description: Target AWS region hosting App Runner services.

  - id: serviceArn
    type: STRING
    displayName: App Runner Service ARN
    defaults: arn:aws:apprunner:us-east-1:123456789012:service/payment-api/abc123def456
    description: Amazon Resource Name (ARN) of the App Runner service to audit.

  - id: maxActiveInstancesThreshold
    type: INT
    displayName: Max Active Instances Threshold
    defaults: 20
    description: Maximum active container instance count threshold before flagging
      autoscaling saturation.

  - id: requestConcurrencyThreshold
    type: FLOAT
    displayName: Request Concurrency Threshold
    defaults: 80.0
    description: Average concurrent requests per active instance triggering scaling alerts.

  - id: slackWebhookUri
    type: SECRET
    displayName: Slack Webhook URI
    defaults: https://hooks.slack.com/services/T00/B00/XXXX
    description: Encrypted Slack Incoming Webhook endpoint for alerting platform SRE teams.

tasks:
  - id: evaluate_apprunner_scaling
    type: io.kestra.plugin.scripts.python.Script
    description: Queries AWS CloudWatch metrics for App Runner ActiveInstances and
      Concurrency.
    containerImage: python:3.11-slim
    beforeCommands:
      - pip install boto3
    env:
      AWS_ACCESS_KEY_ID: "{{ secret('AWS_ACCESS_KEY_ID') }}"
      AWS_SECRET_ACCESS_KEY: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
      AWS_DEFAULT_REGION: "{{ inputs.awsRegion }}"
    script: |
      import os
      import json
      from datetime import datetime, timedelta, timezone
      import boto3

      service_arn = "{{ inputs.serviceArn }}"
      service_name = service_arn.split('/')[-2] if '/' in service_arn else "unknown-service"
      max_instances_threshold = {{ inputs.maxActiveInstancesThreshold }}
      concurrency_threshold = {{ inputs.requestConcurrencyThreshold }}

      cloudwatch = boto3.client('cloudwatch', region_name=os.getenv('AWS_DEFAULT_REGION'))

      end_time = datetime.now(timezone.utc)
      start_time = end_time - timedelta(minutes=30)

      instance_metric = cloudwatch.get_metric_data(
          MetricDataQueries=[
              {
                  'Id': 'm1',
                  'MetricStat': {
                      'Metric': {
                          'Namespace': 'AWS/AppRunner',
                          'MetricName': 'ActiveInstances',
                          'Dimensions': [{'Name': 'ServiceName', 'Value': service_name}]
                      },
                      'Period': 300,
                      'Stat': 'Maximum'
                  },
                  'ReturnData': True
              },
              {
                  'Id': 'm2',
                  'MetricStat': {
                      'Metric': {
                          'Namespace': 'AWS/AppRunner',
                          'MetricName': 'Concurrency',
                          'Dimensions': [{'Name': 'ServiceName', 'Value': service_name}]
                      },
                      'Period': 300,
                      'Stat': 'Average'
                  },
                  'ReturnData': True
              }
          ],
          StartTime=start_time,
          EndTime=end_time
      )

      active_instances = 0
      avg_concurrency = 0.0

      for result in instance_metric.get('MetricDataResults', []):
          if result['Id'] == 'm1' and result['Values']:
              active_instances = int(max(result['Values']))
          elif result['Id'] == 'm2' and result['Values']:
              avg_concurrency = float(sum(result['Values']) / len(result['Values']))

      is_saturated = active_instances >= max_instances_threshold or avg_concurrency >= concurrency_threshold

      report = {
          'service_name': service_name,
          'service_arn': service_arn,
          'active_instances': active_instances,
          'avg_concurrency': round(avg_concurrency, 2),
          'max_instances_threshold': max_instances_threshold,
          'concurrency_threshold': concurrency_threshold,
          'is_saturated': is_saturated,
          'recommended_action': f'aws apprunner update-service --service-arn {service_arn} --auto-scaling-configuration-arn <NEW_SCALING_ARN>' if is_saturated else 'No scaling intervention needed.'
      }

      with open('scaling_report.json', 'w') as f:
          json.dump(report, f)

      print(f'Audited App Runner service {service_name}: {active_instances} active instances, {avg_concurrency:.2f} concurrency.')

  - id: check_scaling_saturation
    type: io.kestra.plugin.core.flow.If
    description: Branch execution based on whether App Runner instance or
      concurrency thresholds were breached.
    condition: "{{ fromJson(read('scaling_report.json')).is_saturated }}"
    then:
      - id: notify_slack_saturation_alert
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatches high-priority scaling saturation alert to Platform SRE
          team on Slack.
        url: "{{ inputs.slackWebhookUri }}"
        payload: |
          {
            "text": "AWS App Runner Scaling Alert: Service *{{ fromJson(read('scaling_report.json')).service_name }}* reached active instance capacity ceiling! Active Instances: {{ fromJson(read('scaling_report.json')).active_instances }}/{{ inputs.maxActiveInstancesThreshold }}, Concurrency: {{ fromJson(read('scaling_report.json')).avg_concurrency }}. Runbook: {{ fromJson(read('scaling_report.json')).recommended_action }}"
          }
    else:
      - id: log_healthy_scaling_state
        type: io.kestra.plugin.core.log.Log
        description: Logs nominal autoscaling metrics when App Runner instances operate
          within limits.
        message: "App Runner service {{
          fromJson(read('scaling_report.json')).service_name }} is operating
          nominally with {{
          fromJson(read('scaling_report.json')).active_instances }} active
          instances and {{ fromJson(read('scaling_report.json')).avg_concurrency
          }} average concurrency."

  - id: export_scaling_manifest
    type: io.kestra.plugin.core.debug.Return
    description: Exports structured autoscaling diagnostic report for downstream
      workflow consumption.
    format: "{{ fromJson(read('scaling_report.json')) }}"

triggers:
  - id: hourly_apprunner_scaling_audit
    type: io.kestra.plugin.core.trigger.Schedule
    description: Scheduled hourly audit evaluating App Runner instance scaling headroom.
    cron: "15 * * * *"