Customer Onboarding Guide

What You'll Deploy

That's it — no changes to existing resources, no code, no agents.

Step 1 — Deploy the CloudFormation Template

This creates the IAM Role and SNS Topic ConvOps needs.

The CloudFormation Template

AWSTemplateFormatVersion: '2010-09-09'
Description: ConvOps Infrastructure Setup — IAM Role + Alert Topic

Parameters:
  CustomerExternalId:
    Type: String
    Description: Unique external ID provided by ConvOps (keep this secret)
    Default: YOUR_CUSTOMER_EXTERNAL_ID

  ConvOpsApiKey:
    Type: String
    Description: Your ConvOps API key (provided during onboarding)
    Default: YOUR_CONVOPS_API_KEY
    NoEcho: true

Resources:

  # SNS Topic: receives CloudWatch alarms and forwards to ConvOps
  ConvOpsAlertTopic:
    Type: AWS::SNS::Topic
    Properties:
      TopicName: ConvOpsAlerts
      Subscription:
        - Protocol: https
          Endpoint: https://api.convops.io/v1/ingest
          DeliveryPolicy:
            healthyRetryPolicy:
              numRetries: 3
              minDelayTarget: 20
              maxDelayTarget: 20

  ConvOpsAlertTopicPolicy:
    Type: AWS::SNS::TopicPolicy
    Properties:
      Topics:
        - !Ref ConvOpsAlertTopic
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: cloudwatch.amazonaws.com
            Action: sns:Publish
            Resource: !Ref ConvOpsAlertTopic

  # IAM Role: allows ConvOps to read and take approved actions
  ConvOpsAccessRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: ConvOpsAccessRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::009001720832:role/convops-executor
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !Ref CustomerExternalId
      Policies:
        - PolicyName: ConvOpsReadPolicy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - cloudwatch:GetMetricData
                  - cloudwatch:GetMetricStatistics
                  - cloudwatch:DescribeAlarms
                  - logs:FilterLogEvents
                  - logs:GetLogEvents
                  - logs:DescribeLogGroups
                  - logs:DescribeLogStreams
                  - ec2:DescribeInstances
                  - ecs:DescribeTasks
                  - ecs:DescribeServices
                  - ecs:ListTasks
                  - ecs:ListServices
                  - rds:DescribeDBInstances
                  - rds:DescribeEvents
                  - lambda:ListFunctions
                  - lambda:GetFunctionConfiguration
                Resource: "*"

        - PolicyName: ConvOpsActionPolicy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action: ecs:UpdateService
                Resource: "*"
                Condition:
                  StringEquals:
                    aws:ResourceTag/ConvOpsManaged: "true"
              - Effect: Allow
                Action: ec2:RebootInstances
                Resource: "*"
                Condition:
                  StringEquals:
                    aws:ResourceTag/ConvOpsManaged: "true"
              - Effect: Allow
                Action: rds:RebootDBInstance
                Resource: "*"
                Condition:
                  StringEquals:
                    aws:ResourceTag/ConvOpsManaged: "true"
              - Effect: Allow
                Action: ssm:SendCommand
                Resource:
                  - !Sub "arn:aws:ssm:*:*:document/AWS-RestartService"
                  - !Sub "arn:aws:ssm:*:*:document/AWS-RunShellScript"
                  - !Sub "arn:aws:ec2:*:${AWS::AccountId}:instance/*"
                Condition:
                  StringEquals:
                    aws:ResourceTag/ConvOpsManaged: "true"

Outputs:
  RoleArn:
    Description: Share this with ConvOps during onboarding
    Value: !GetAtt ConvOpsAccessRole.Arn
  SNSTopicArn:
    Description: Use this as your CloudWatch alarm action
    Value: !Ref ConvOpsAlertTopic

Deploy via AWS CLI

aws cloudformation deploy \
  --template-file customer-convops-setup.yaml \
  --stack-name convops-setup \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    CustomerExternalId=YOUR_EXTERNAL_ID \
    ConvOpsApiKey=YOUR_API_KEY

Or via AWS Console

1. Go to CloudFormation → Create Stack → Upload template file
2. Paste your CustomerExternalId and ConvOpsApiKey when prompted
3. Check I acknowledge that AWS CloudFormation might create IAM resources with custom names
4. Click Create Stack and wait ~60 seconds

Step 2 — Tag Resources You Want ConvOps to Manage

ConvOps uses tags to determine what it can act on. Investigation (reading metrics and logs) works on all resources — but actions like restarts and reboots are restricted to tagged resources only.

Tag an ECS service

aws ecs tag-resource \
  --resource-arn arn:aws:ecs:eu-central-1:YOUR_ACCOUNT:service/my-cluster/my-service \
  --tags key=ConvOpsManaged,value=true

Tag an EC2 instance

aws ec2 create-tags \
  --resources i-0abc123def456 \
  --tags Key=ConvOpsManaged,Value=true

Tag an RDS instance

aws rds add-tags-to-resource \
  --resource-name arn:aws:rds:eu-central-1:YOUR_ACCOUNT:db:my-db \
  --tags Key=ConvOpsManaged,Value=true

Step 3 — Connect Your CloudWatch Alarms

Add the ConvOpsAlerts SNS topic as an action on any alarm you want ConvOps to monitor.

Via AWS CLI

# Get your SNS Topic ARN from the CloudFormation stack outputs
SNS_ARN=$(aws cloudformation describe-stacks \
  --stack-name convops-setup \
  --query "Stacks[0].Outputs[?OutputKey=='SNSTopicArn'].OutputValue" \
  --output text)

# Add ConvOps as an alarm action on an existing alarm
aws cloudwatch put-metric-alarm \
  --alarm-name "prod-api-cpu-high" \
  --alarm-actions $SNS_ARN \
  --metric-name CPUUtilization \
  --namespace AWS/ECS \
  --statistic Average \
  --period 300 \
  --threshold 85 \
  --comparison-operator GreaterThanThreshold \
  --evaluation-periods 2

Via AWS Console

1. Go to CloudWatch → Alarms
2. Select an alarm → click Edit
3. Under Notification, click Add notification
4. Select In alarm state → SNS topic → choose ConvOpsAlerts
5. Click Update alarm

Step 4 — Complete Onboarding with ConvOps

Onboarding is currently handled directly with the ConvOps team — no self-serve signup yet.

1. Email nitesh@convops.io to start onboarding — we'll send you your ExternalId and API key
2. Deploy the CloudFormation template from Step 1 using those values
3. Reply with the IAM Role ARN from your stack outputs — we'll confirm the SNS subscription on our end
4. Send us your WhatsApp number — we'll register it to receive alerts
5. We'll trigger a test alert together to confirm end-to-end delivery

What ConvOps Can and Cannot Do

Security Notes

Troubleshooting