Skip to main content
Recommended Setup - For self-hosted deployments on AWS EKS, use IAM Roles for Service Accounts (IRSA) instead of access keys for enhanced security.

​
Overview

Self-hosted Relvy deployments on AWS EKS can connect to AWS CloudWatch using IAM role assumption instead of static access keys. This provides several security benefits:

​
Benefits of IRSA Authentication

  • No Credential Rotation - No need to manage or rotate access keys
  • Enhanced Security - Temporary credentials with automatic rotation
  • Better Audit Trail - CloudTrail logs show which role assumed another role
  • Least Privilege - Fine-grained permissions per AWS account

​
How It Works

The IRSA setup uses a two-role architecture:
  1. IRSA Role (in Relvy deployment account) - Kubernetes service account assumes this role using OIDC
  2. CloudWatch Role (in customer’s AWS account) - The IRSA role assumes this role to access CloudWatch
Relvy Pod → Service Account → IRSA Role → CloudWatch Role → CloudWatch Logs/Metrics
  (EKS)      (via OIDC)      (Account A)    (Account B)         (Account B)

​
Prerequisites

Before starting, ensure you have:
  • ✅ EKS Cluster - Relvy deployed on AWS EKS with OIDC provider enabled
  • ✅ AWS CLI - Configured with permissions to create IAM roles
  • ✅ kubectl Access - Access to your Relvy Kubernetes cluster
  • ✅ Helm - For updating Relvy configuration
  • ✅ OIDC Details - Your EKS cluster’s OIDC provider URL and ID

​
Get Your OIDC Provider Details

You’ll need your EKS OIDC provider information. Find it using: 
# Get your cluster's OIDC provider URL
aws eks describe-cluster --name YOUR-CLUSTER-NAME \
  --query "cluster.identity.oidc.issuer" --output text

# Output example: https://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
Extract:
  • Region: us-east-1 (from URL)
  • OIDC ID: EXAMPLED539D4633E53DE1B71EXAMPLE (the hash after /id/)

​
Step 1: Create IRSA Role (Relvy Deployment Account)

The IRSA role runs in the same AWS account where Relvy is deployed. This role allows your Relvy pods to assume other roles.

​
1.1 Create Trust Policy

Create a file named irsa-trust-policy.json: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR-RELVY-ACCOUNT-ID:oidc-provider/oidc.eks.REGION.amazonaws.com/id/OIDC-ID"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.REGION.amazonaws.com/id/OIDC-ID:sub": "system:serviceaccount:NAMESPACE:SERVICE-ACCOUNT-NAME"
        }
      }
    }
  ]
}
Replace:
  • YOUR-RELVY-ACCOUNT-ID - AWS account ID where Relvy is deployed
  • REGION - Your EKS cluster region (e.g., us-east-1)
  • OIDC-ID - Your OIDC provider ID from prerequisites
  • NAMESPACE - Kubernetes namespace where Relvy is deployed (usually default)
  • SERVICE-ACCOUNT-NAME - Kubernetes service account name (usually relvy-serviceaccount)

​
1.2 Create Permission Policy

Create a file named irsa-permission-policy.json: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/RelvyCloudWatchRole"
    }
  ]
}
Role Name Flexibility - The Resource field uses a wildcard (*) to allow assuming roles named RelvyCloudWatchRole in any AWS account. You can customize this name, but make sure it matches the role name you create in Step 2.

​
1.3 Create the IAM Role

# Create the IRSA role
aws iam create-role \
  --role-name RelvyIRSARole \
  --assume-role-policy-document file://irsa-trust-policy.json

# Attach the permission policy
aws iam put-role-policy \
  --role-name RelvyIRSARole \
  --policy-name AssumeCloudWatchRole \
  --policy-document file://irsa-permission-policy.json

# Get the role ARN (save this for Step 3)
aws iam get-role --role-name RelvyIRSARole --query 'Role.Arn' --output text
Save the Role ARN - You’ll need this ARN for Helm configuration in Step 3. Example ARN: arn:aws:iam::111122223333:role/RelvyIRSARole

​
Step 2: Create CloudWatch Role (Customer’s AWS Account)

For each AWS account where you want to access CloudWatch, create a CloudWatch role that trusts your IRSA role.

​
2.1 Create Trust Policy

Create a file named cloudwatch-trust-policy.json: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::YOUR-RELVY-ACCOUNT-ID:role/RelvyIRSARole"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
Replace:
  • YOUR-RELVY-ACCOUNT-ID - AWS account ID where Relvy is deployed (same as Step 1)
  • RelvyIRSARole - The IRSA role name from Step 1

​
2.2 Create Permission Policy

Create a file named cloudwatch-permission-policy.json: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:GetLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms"
      ],
      "Resource": "*"
    }
  ]
}
Scoped Permissions - For tighter security, replace Resource: "" with specific log group ARNs like “arn:aws:logs:REGION:ACCOUNT-ID:log-group:YOUR-LOG-GROUP:“

​
2.3 Create the IAM Role

Run these commands in the AWS account where CloudWatch data resides: 
# Create the CloudWatch role
aws iam create-role \
  --role-name RelvyCloudWatchRole \
  --assume-role-policy-document file://cloudwatch-trust-policy.json

# Attach the permission policy
aws iam put-role-policy \
  --role-name RelvyCloudWatchRole \
  --policy-name CloudWatchAccess \
  --policy-document file://cloudwatch-permission-policy.json

# Get the role ARN (save this for Step 4)
aws iam get-role --role-name RelvyCloudWatchRole --query 'Role.Arn' --output text
Save the Role ARN - You’ll need this ARN when configuring Relvy UI in Step 4. Example ARN: arn:aws:iam::444455556666:role/RelvyCloudWatchRole

​
Step 3: Configure Kubernetes Service Account

Update your Relvy Helm deployment to use the IRSA role.

​
3.1 Update Helm Values

Add or update the serviceAccount section in your Helm values file (values.yaml): 
# Service Account Configuration for IRSA
serviceAccount:
  create: true
  name: relvy-serviceaccount
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::111122223333:role/RelvyIRSARole"
Replace the role-arn with your IRSA role ARN from Step 1.

​
3.2 Upgrade Helm Deployment

Apply the configuration to your cluster: 
# Update Helm repository
helm repo update

# Upgrade Relvy with new service account configuration
helm upgrade relvy relvy/relvy \
  --values values.yaml \
  --namespace default

# Verify the service account was created
kubectl get serviceaccount relvy-serviceaccount -o yaml

# You should see the annotation:
# eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/RelvyIRSARole

​
3.3 Restart Deployments

Restart Relvy deployments to pick up the new service account: 
kubectl rollout restart deployment/relvy-web
kubectl rollout restart deployment/relvy-celery
kubectl rollout restart deployment/relvy-celery-beat

# Wait for rollout to complete
kubectl rollout status deployment/relvy-web
kubectl rollout status deployment/relvy-celery
kubectl rollout status deployment/relvy-celery-beat

​
Step 4: Configure Relvy UI

Now configure the CloudWatch connection in the Relvy web interface.

​
4.1 Access Data Sources Configuration

  1. Log in to your Relvy instance (https://relvy.yourdomain.com)
  2. Navigate to Settings → Data Sources
  3. Locate the AWS CloudWatch section

​
4.2 Configure Authentication

In the AWS CloudWatch configuration:
  1. Select Authentication Method: Choose IAM Role (instead of Access Keys)
  2. Enter AWS Role ARN: The CloudWatch role ARN from Step 2
    • Example: arn:aws:iam::444455556666:role/RelvyCloudWatchRole
  3. Enter AWS Region: The region where your CloudWatch data resides
    • Example: us-east-1
  4. Click Connect

​
4.3 Verify Connection

After clicking Connect, you should see:
  • ✅ Connected status badge
  • Available log groups discovered from CloudWatch

​
Alternative: Using Access Keys

If IRSA is not suitable for your setup, you can still use access keys:
  1. In Relvy UI, select Authentication Method: Access Keys
  2. Provide AWS Access Key ID and Secret Access Key
  3. Enter AWS Region
  4. Click Connect
Refer to the AWS CloudWatch integration guide for access key setup details.

​
Next Steps

Your AWS CloudWatch integration with IRSA is now complete! Next steps:
  1. Configure Log Groups - Select which log groups to analyze in Relvy settings
  2. Set Up Dashboards - Configure CloudWatch metrics dashboards
  3. Create Queries - Define reference queries for common investigations
  4. Test Investigations - Run investigations using CloudWatch logs and metrics
Need Help? - Contact Relvy support at [email protected] for assistance with AWS CloudWatch setup.