Skip to content

Integra Cloud: AWS Integration Guide

This guide details how to integrate Integra Cloud into your AWS environment. Integra Cloud is available on AWS Marketplace and provides comprehensive billing & metering, security (TLS), observability (logs, metrics, traces), and storage integration.

1. Billing & Metering

[!IMPORTANT] Please read this section carefully to understand how you will be billed.

Billing Model: Capacity-Based

You are billed for allocated vCPU capacity, NOT actual CPU usage.

  • ✅ What you're billed for: The number of vCPUs allocated to the container
  • ❌ What you're NOT billed for: How much CPU the container actually uses

Example:

Container allocated: 4 vCPUs
Actual CPU usage: 10% (0.4 vCPUs)
You are billed for: 4 vCPU-hours per hour

Billing Frequency: Hourly

You are billed every hour for the vCPUs allocated to your container.

  • Billing occurs at the top of every hour (e.g., 10:00, 11:00, 12:00)
  • Minimum billing unit: 1 hour
  • Fractional vCPUs are rounded UP (e.g., 2.5 vCPUs → 3 vCPU-hours billed)

Upfront Billing on Container Start

When your container starts, you are billed immediately for the upcoming hour.

This ensures you have paid for the service before it begins.

Hybrid 30-Minute Strategy:

Container Start Time Time Left in Current Hour You Are Billed For Free Time
10:00 - 10:29 >30 minutes Current hour (10:00-11:00) 0-29 minutes
10:30 - 10:59 ≤30 minutes Next hour (11:00-12:00) 30-59 minutes

Example 1: Start at 10:15 (45 minutes left in hour)

10:15 - Container starts
      → You are billed for 10:00-11:00 (current hour)
      → You get 15 minutes free
      → Service starts immediately after billing succeeds

11:00 - Hourly billing
      → You are billed for 11:00-12:00

Example 2: Start at 10:45 (15 minutes left in hour)

10:45 - Container starts
      → You are billed for 11:00-12:00 (next hour)
      → You get 45 minutes free
      → Service starts immediately after billing succeeds

11:00 - Hourly billing
      → You are billed for 11:00-12:00 (same hour, no double billing)

Container Restarts: No Double Billing

If your container restarts within the same hour, you will NOT be double-billed.

All billing is aligned to hour boundaries (10:00, 11:00, 12:00, etc.). AWS Marketplace automatically deduplicates billing records with the same timestamp.

Fractional vCPUs: Always Rounded UP

Allocated vCPUs Billed vCPU-hours per Hour
0.5 1
1.0 1
1.5 2
2.0 2
2.5 3
4.0 4

Billing Transparency

Check your current billing status at any time:

curl http://localhost:8080/v1/metering/status

Response:

{
  "vcpu_count": 2.5,
  "vcpu_hours_billed": 3,
  "detection_method": "cgroup",
  "start_time": "2026-02-01T10:00:00Z",
  "uptime_hours": 5.2,
  "estimated_billings": 6,
  "total_failures": 0,
  "status": "healthy"
}

Status Values: - healthy: No failures - degraded: 1-2 consecutive failures - failing: 3+ consecutive failures (alerts should fire)

2. IAM Permissions

Required Permissions

The container requires the following IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MarketplaceMetering",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:MeterUsage"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3Access",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-input-bucket/*",
        "arn:aws:s3:::your-output-bucket/*",
        "arn:aws:s3:::your-input-bucket",
        "arn:aws:s3:::your-output-bucket"
      ]
    },
    {
      "Sid": "SecretsManager",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:*:*:secret:integra/*"
      ]
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": [
        "arn:aws:logs:*:*:log-group:/aws/integra/*"
      ]
    }
  ]
}

Note: When running on AWS Marketplace, metering permissions are automatically granted via the instance profile.

3. Cost Optimization

Right-Sizing vCPU Allocation

API Mode (Real-Time Processing): - Start with 2 vCPUs for low-volume workloads (<100 requests/hour) - Use 4 vCPUs for medium-volume (100-1000 requests/hour) - Scale to 8+ vCPUs for high-volume (>1000 requests/hour)

Pipeline Mode (Batch Processing): - Worker pool size = 2 × vCPU count (default) - For I/O-bound workloads (S3), increase worker pool size - For CPU-bound workloads (large files), match worker pool to vCPU count

Batch Mode Efficiency Tips

  1. Use Parquet for Output: Smaller file sizes = lower S3 costs
  2. Tune Worker Pool: Balance throughput vs. vCPU allocation
  3. Monitor Idle Time: Scale down during off-peak hours
  4. Use Spot Instances: For non-critical batch workloads

Monitoring Cost Metrics

Track these metrics to optimize costs:

# Average vCPU utilization
rate(process_cpu_seconds_total[5m]) / vcpu_count

# Files processed per vCPU-hour
rate(integra_pipeline_files_processed_total[1h]) / vcpu_count

# Cost per file processed
(vcpu_count * hourly_rate) / rate(integra_pipeline_files_processed_total[1h])

4. Security (TLS)

Integra supports termination of TLS directly within the container, ensuring encryption in transit from your load balancer (ALB/NLB) or other internal services.

Configuration

  1. Mount Certificates: Mount your server certificate and private key into the container (e.g., via AWS Secrets Manager sidecar or EFS).
  2. Environment Variables:
    • INTEGRA_TLS_CERT: Path to the certificate file (PEM).
    • INTEGRA_TLS_KEY: Path to the private key file (PEM).
    • INTEGRA_PORT: Port to listen on (default 8443 if TLS enabled, else 8080).
# Example ECS Task Definition Env Vars
INTEGRA_TLS_CERT=/etc/certs/server.crt
INTEGRA_TLS_KEY=/etc/certs/server.key
INTEGRA_PORT=8443

Note: If these variables are set, Integra will start in HTTPS mode.

5. Logging (S3)

Integra follows the 12-Factor App methodology and writes structured logs (JSON) to stdout.

Shipping Logs to S3

The recommended architecture on AWS is to use Amazon CloudWatch Logs with a subscription filter to Amazon Kinesis Data Firehose, which ultimately stores logs in S3.

  1. ECS/EKS: Configure the awslogs driver to send stdout to CloudWatch Logs.
  2. Firehose: Create a Kinesis Data Firehose delivery stream with S3 as the destination.
  3. Subscription: Create a CloudWatch Logs Subscription Filter to stream logs from your Integra log group to Firehose.

This approach ensures logs are durably archived in S3 for audit and compliance without complicating the application logic.

6. Metrics (Prometheus)

Integra exposes an endpoint compatible with Prometheus scraping.

  • Endpoint: GET /metrics
  • Port: Same as application port (e.g., 8080 or 8443).

AWS Managed Prometheus (AMP)

To integrate with AWS Managed Prometheus: 1. ADOT Collector: Deploy the AWS Distro for OpenTelemetry (ADOT) Collector as a sidecar. 2. Scrape Config: Configure ADOT to scrape localhost:{{ .Port }}/metrics. 3. Remote Write: Configure ADOT to remote-write to your AMP workspace.

Key Metering Metrics

# Total billing attempts
metering_billings_total{meter="aws",status="success|failure"}

# Consecutive failures (alert on ≥3)
metering_consecutive_failures

# Last failure timestamp
metering_last_failure_timestamp

7. Tracing (OpenTelemetry)

Integra is instrumented with OpenTelemetry (OTel) traces.

Configuration

Configure the OTLP exporter using standard environment variables:

  • OTEL_EXPORTER_OTLP_ENDPOINT: URL of your OTel collector (e.g., http://localhost:4317 for sidecar).
  • OTEL_SERVICE_NAME: integra-api (default).

Architecture

  1. Apps send traces to → ADOT Sidecar (via OTLP/gRPC).
  2. ADOT Sidecar sends traces to → AWS X-Ray or Tempo.

8. Troubleshooting

Upfront Billing Fails

Symptoms: - Container fails to start - Log: "upfront billing failed - cannot start"

Causes: 1. No AWS Marketplace permissions 2. Network connectivity issues 3. Invalid product code

Resolution:

# Check IAM permissions
aws sts get-caller-identity

# Check network connectivity
curl -I https://metering.marketplace.us-east-1.amazonaws.com

# Check logs
docker logs <container-id> | grep "billing"

Consecutive Billing Failures

Symptoms: - Prometheus alert: metering_consecutive_failures >= 3 - Status endpoint shows "status": "failing"

Causes: 1. AWS API throttling 2. Network issues 3. Invalid credentials

Resolution:

# Check metering status
curl http://localhost:8080/v1/metering/status

# Check Prometheus metrics
curl http://localhost:8080/metrics | grep metering

# Review logs
docker logs <container-id> | grep "billing failed"

9. Best Practices

Use UTC Timezone

ENV TZ=UTC

Why: Ensures consistent billing timestamps across regions.

Monitor Metering Health

# Prometheus alert
- alert: MeteringConsecutiveFailures
  expr: metering_consecutive_failures >= 3
  annotations:
    summary: "Critical: Metering system failing"

Set Customer ID

INTEGRA_CUSTOMER_ID="customer-12345"

Why: Helps with billing reconciliation and customer support.

Test in Staging

Before production deployment: 1. Deploy to staging environment 2. Trigger container restarts 3. Verify no double billing 4. Check metering status endpoint 5. Review Prometheus metrics

9. Deployment Options

Option 1: AWS CloudFormation (ECS Fargate)

Deploy using the provided CloudFormation template for a fully managed, serverless deployment:

aws cloudformation deploy \
  --template-file deploy/cloudformation/integra-stack.yaml \
  --stack-name integra-prod \
  --parameter-overrides \
    EnvironmentName=prod \
    VpcId=vpc-xxxxxxxx \
    SubnetIds=subnet-xxxx,subnet-yyyy \
    ImageUri=<aws-marketplace-container-uri> \
    IntegraMode=api \
    AllowedCidrForApi=10.0.0.0/16 \
    AssignPublicIp=DISABLED \
  --capabilities CAPABILITY_IAM

Key Parameters: - AllowedCidrForApi: CIDR block for API access (default: 10.0.0.0/8) - AssignPublicIp: Set to DISABLED for private subnets with NAT Gateway (recommended) - Cpu: Task CPU units (256, 512, 1024, 2048, 4096) - Memory: Task memory in MB (512, 1024, 2048, 4096, 8192)

Security Best Practices: - ✅ Use private subnets with NAT Gateway - ✅ Restrict AllowedCidrForApi to your VPC CIDR - ✅ Deploy across multiple Availability Zones - ✅ Enable CloudWatch Container Insights

Option 2: AWS EKS (Kubernetes)

Deploy using Helm chart for EKS clusters:

helm install integra ./deploy/helm/integra \
  --set mode=api \
  --set image.repository=<aws-marketplace-container-uri> \
  --set image.tag=v1.0.0 \
  --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::123456789012:role/integra-role

Features: - ✅ Horizontal Pod Autoscaler (HPA) enabled by default - ✅ Pod Disruption Budget for high availability - ✅ IRSA (IAM Roles for Service Accounts) support - ✅ Ingress template with AWS ALB support - ✅ Production-ready security context

10. Deployment Checklist

  • [ ] IAM Role: Ensure Task/Pod has permissions for aws-marketplace:MeterUsage and S3 access
  • [ ] Security Groups: Restrict access to VPC CIDR or specific IP ranges
  • [ ] Private Subnets: Deploy in private subnets with NAT Gateway (recommended)
  • [ ] Health Check: Configure health check to GET /health (returns 200 OK)
  • [ ] High Availability: Deploy across multiple Availability Zones
  • [ ] Monitoring: Set up CloudWatch alerts for metering failures
  • [ ] Cost Tracking: Monitor vCPU utilization and billing metrics
  • [ ] Product Code: Verify AWS Marketplace Product Code is hardcoded in application

Additional Resources