Skip to main content

Deployment Guide

Complete guide for deploying AWSops to a new AWS account.

Prerequisites​

ItemRequirement
AWS AccountAppropriate IAM permissions (Admin or PowerUser)
CDK CLIInstalled locally (npm install -g aws-cdk)
Dockerarm64 build support (docker buildx)
Node.jsv20 or higher
AWS CLIv2, profile configured

Quick Install​

install-all.sh

A convenience script that automatically runs Step 1 → 2 → 3 → 10 in sequence. Use after deploying CDK infrastructure (Step 0).

bash scripts/install-all.sh

Deployment Steps​

Step 0: CDK Infrastructure (Local)​

cd infra-cdk && cdk deploy --all

Resources deployed by CDK:

  • VPC: 10.10.0.0/16, 2 AZs, NAT Gateway, Public + Private Subnets (configurable via CDK context parameter newVpcCidr)
  • EC2: t4g.2xlarge (ARM64 Graviton), 100GB GP3, Private Subnet
  • ALB: Internet-facing, Custom Header validation
  • CloudFront: CACHING_DISABLED, ALB Origin
  • Cognito: User Pool + Lambda@Edge (us-east-1)

Step 1: Install Steampipe (EC2)​

bash scripts/01-install-base.sh

Installs Steampipe + AWS/K8s/Trivy plugins. 380+ AWS tables available via PostgreSQL on port 9193.

Step 2: Setup Next.js (EC2)​

bash scripts/02-setup-nextjs.sh

Installs Next.js 14 app, registers Steampipe service, auto-detects MSP environment.

Step 3: Production Build (EC2)​

bash scripts/03-build-deploy.sh

Runs npm run build + npm start for production server.

Step 4: EKS Access Setup (EC2)​

bash scripts/04-setup-eks-access.sh

Configures EKS cluster access:

  • kubectl installation (ARM64 binary)
  • Auto-discovery of EKS clusters in the region
  • kubeconfig setup (aws eks update-kubeconfig)
  • EKS access entry registration
  • Steampipe Kubernetes plugin + Trivy plugin connection setup
No EKS in your environment?

You can skip this step if there are no EKS clusters in the account. Only Kubernetes-related pages will be disabled.

Step 5: Cognito Auth (EC2)​

bash scripts/05-setup-cognito.sh

Creates Cognito User Pool users and configures app client.

Step 6a-6f: AgentCore (EC2)​

A wrapper script can run steps 6a through 6e sequentially:

bash scripts/06-setup-agentcore.sh
ScriptDescription
06a-setup-agentcore-runtime.shIAM role, ECR, Docker arm64 build, Runtime Endpoint
06b-setup-agentcore-gateway.shCreate 8 Gateways (MCP)
06c-setup-agentcore-tools.sh19 Lambda + register 125 tools across 8 Gateways
06d-setup-agentcore-interpreter.shCreate Code Interpreter
06e-setup-agentcore-config.shAuto-configure route.ts / agent.py (ARNs, Gateway URLs, etc.)
06f-setup-agentcore-memory.shCreate Memory Store (365-day retention) — must be run manually
07-setup-opencost.shPrometheus + OpenCost (EKS cost analysis)

Step 8: CloudFront Auth Integration (EC2)​

bash scripts/08-setup-cloudfront-auth.sh

Connects Lambda@Edge to CloudFront viewer-request.

Step 9: Start All Services (EC2)​

bash scripts/09-start-all.sh

Starts the following services in sequence:

  • Steampipe service (PostgreSQL port 9193)
  • Next.js production server (port 3000)
  • OpenCost (EKS cost analysis, if EKS is configured)

Step 10: Stop All Services (EC2)​

bash scripts/10-stop-all.sh

Gracefully stops all running AWSops services. Use for maintenance or updates.

Step 11: Verify & Health Check (EC2)​

bash scripts/11-verify.sh

Performs a 5-stage automated verification:

  1. Service status — Steampipe, Next.js process checks
  2. Steampipe tables — Verifies 18 core tables exist
  3. Page access — HTTP response code validation for 20+ pages
  4. API response — Key API endpoint functionality checks
  5. Config file — data/config.json validity check
Required after deployment

Run 11-verify.sh after Step 3 or any update to confirm all components are healthy. It is also included in install-all.sh.

Step 12: Multi-Account Setup (EC2, Optional)​

bash scripts/12-setup-multi-account.sh

Configures multiple AWS accounts to be managed from a single AWSops instance:

  • Steampipe Aggregator connection setup (aws = all accounts merged)
  • Cross-account IAM role creation and trust relationship configuration
  • Updates accounts[] array in data/config.json
Optional step

Not required for single-account environments. Only run this if you need multi-account support.

Configuration File​

data/config.json is auto-generated after deployment. For new account deployments, only update this file.

{
  "costEnabled": true,
  "agentRuntimeArn": "arn:aws:bedrock-agentcore:REGION:ACCOUNT:runtime/RUNTIME_ID",
  "codeInterpreterName": "awsops_code_interpreter_XXXXX",
  "memoryId": "awsops_memory_XXXXX",
  "memoryName": "awsops_memory",
  "adminEmails": ["admin@example.com"],
  "accounts": [
    {
      "accountId": "111111111111",
      "alias": "Host",
      "connectionName": "aws_111111111111",
      "region": "ap-northeast-2",
      "isHost": true,
      "features": { "costEnabled": true, "eksEnabled": true, "k8sEnabled": true }
    },
    {
      "accountId": "222222222222",
      "alias": "Staging",
      "connectionName": "aws_222222222222",
      "region": "ap-northeast-2",
      "isHost": false,
      "features": { "costEnabled": false, "eksEnabled": false, "k8sEnabled": false }
    }
  ],
  "customerLogo": "default.png"
}
No Code Changes Required

For per-account deployment, just update data/config.json. No source code changes needed.

Known Issues​

Deployment caveats

1. Memory Store must be run manually 06f-setup-agentcore-memory.sh is not included in the wrapper script (06-setup-agentcore.sh), so it must be run manually:

bash scripts/06f-setup-agentcore-memory.sh

2. systemd service configuration The default generated systemd service file may still reference proxy.js. The correct start command is npm run start. In nvm environments, use the full Node.js path (/home/ec2-user/.nvm/versions/node/v20.x.x/bin/node).

3. Docker arm64 required AgentCore Runtime Docker images must be built for arm64:

docker buildx build --platform linux/arm64 --load -t awsops-agent .