miniature-eureka

An AWS CDK stack that deploys a heartbeat canary. A scheduled client repeatedly calls a Lambda Function URL to prove the system is alive; if the heartbeat stops, CloudWatch raises alarms that are relayed to Telegram (and optionally email) so you know something is wrong before users do.

Overview

• Heartbeat canary core: Missing invocations or Lambda errors indicate that the heartbeat stopped. CloudWatch alarms (metricInvocations, metricErrors) detect the condition based on the configured interval.
• Optional dynamic DNS action: src/eureka-stack.healthcheck_function.ts can optionally receive the caller's public IP address via its Function URL, compare it with the existing Route53 A record, and upsert the record when the address changes. The Route53 integration is entirely optional—the healthcheck can function as a simple heartbeat without DNS management.
• Alert fan-out: src/eureka-stack.telegram_function.ts posts alarm state transitions to a Telegram chat/thread and redundantly notifies an SNS email subscription.
• Least-privilege IAM: The stack provisions an IAM user with permission to invoke the Function URL using AWS_IAM auth, plus all policies needed for Route53 (if configured), SNS, and SSM Parameter retrieval.

Architecture

• Heartbeat lifecycle: The orchestration centers on consistent Lambda invocations; any lapse is treated as a canary failure and trips the alarms.
• Telegram notifier Lambda (telegram_function): Consumes CloudWatch alarm events, fetches the Telegram bot token from the Parameters & Secrets extension (telegram_bot_token), and posts formatted messages to the configured chat/thread.
• CloudWatch alarms:
  • Invocation alarm: BREACHING if the healthcheck Lambda is not invoked within the expected interval (uses missing data treatment and a third of lambdaInvocationPeriod).
  • Error alarms: Trigger on any reported errors from both the healthcheck and Telegram functions.
• Notifications: Telegram is the primary channel; an SNS topic backs up error notifications and can email critical alerts.
• IAM invoke user: Exported as lambda_invoke_user_export, intended for the scheduler or external system that performs the regular Function URL calls via SigV4 signed requests.

Prerequisites

• Node.js 22+
• Yarn 3 (Berry)

Configuration

1. Clone & install dependencies

   yarn install

2. Environment variables: this project uses dotenv-flow. Create .env.local (or set variables in your shell) with:

   APP_TELEGRAM_CHAT_ID=123456789
   APP_TELEGRAM_THREAD_ID=optional-thread-id
   SNS_EMAIL=alerts@example.com

   • APP_TELEGRAM_THREAD_ID is optional; omit it for standard chats.
   • SNS_EMAIL is used when synthesizing the stack (see below).

3. Secrets: Store the Telegram bot token in Parameter Store with the name telegram_bot_token, encrypted with a KMS key the Lambda can decrypt.

4. CDK context: parameters are supplied when instantiating EurekaStack. The main entry point (src/eureka-stack.ts) expects:

   • recordName (optional): DNS record to manage (e.g. home.example.com). Omit if you don't need dynamic DNS functionality.
   • hostedZone (optional): Hosted zone attributes { hostedZoneId, zoneName } for the Route53 zone. Required only if recordName is provided.
   • snsEmail: Email address subscribed to the fallback SNS topic.
   • lambdaInvocationPeriod (optional): Seconds between expected invocations (defaults to 30 minutes). The missing-data alarm uses this to determine alert thresholds.

Deployment

1. Bootstrap CDK (one-time per account/region):

   yarn cdk bootstrap aws://<account>/<region>

2. Synthesize:

   yarn cdk synth

3. Deploy:

   yarn cdk deploy

   During deployment you will be prompted to confirm IAM and security-sensitive changes.

Operation

• Schedule the heartbeat: Use the exported IAM user credentials to sign HTTPS requests to the healthcheck Function URL. Invoke it every lambdaInvocationPeriod seconds (for example through an external cron, EventBridge Scheduler, or another automation platform).
• DNS failover (optional): If configured, each invocation ensures recordName points to the caller's IP address. If the canary stops calling, the Route53 record will eventually become stale, and the missing-invocation alarm fires.
• Alert flow: CloudWatch → telegram_function → Telegram chat/thread and SNS email. Alarm messages show the previous and current state, reason, and timestamp.

Development

• Format/lint using Prettier if desired.
• Update TypeScript sources under src/ and re-run yarn cdk synth to verify infrastructure changes.

Troubleshooting

• Telegram errors: The telegram_errors alarm publishes to both Telegram (loopback) and the email SNS topic. Check Lambda logs if messages fail.
• Invocation alarm noise: Ensure your scheduler interval evenly divides lambdaInvocationPeriod and that invocations succeed; adjust the period if you intentionally change the cadence.
• DNS permissions: The healthcheck Lambda assumes it can ListResourceRecordSets and ChangeResourceRecordSets for the provided hosted zone. Confirm the hosted zone ID is correct.

Cleanup

To remove all resources, run:

yarn cdk destroy

Note: You may need to manually delete the IAM user credentials and remove the Telegram bot token from Parameter Store if they were created outside of this stack.

License

MIT