# Seer — AWS Console Deployment Guide

This guide walks you through deploying Seer using the AWS Management Console. No CLI required.

There are two deployment options:
- **MVP** — Minimal proof-of-concept (16 resources, ~3 min deploy)
- **Full Production** — Complete platform with observability, security, and all delivery channels (~88 resources, ~10-15 min deploy)

Both options require deploying the cross-account member role first.

> **What's automated in the Full Production template:**
> - SNS alarm email subscription — auto-subscribes the first email recipient
> - SES email identity — auto-registers the first email recipient as a sender
> - No manual SNS or SES console steps needed (just confirm the emails that arrive)

---

## Prerequisites

Before you begin, confirm you have:

- [ ] **AWS Organizations** enabled with a management account
- [ ] **Your Organization ID** (starts with `o-`, found in AWS Organizations console)
- [ ] **Admin access** to the management account (or permissions to create CloudFormation stacks, IAM roles, Lambda functions, DynamoDB tables, S3 buckets, Step Functions)
- [ ] The template files on your Desktop at `~/Desktop/seer-templates/`

For **Full Production** only:
- [ ] **An email address** you control (for alarm notifications and SES sender — verification emails are sent automatically during deployment)
- [ ] **A domain prefix** for the Cognito User Pool (or willingness to use the default)

> **To regenerate templates** (e.g., with your real Org ID), run:
> ```bash
> cd ~/Library/CloudStorage/OneDrive-amazon.com
> python3 -m seer_deployment_templates --profile both --org-id o-YOUR-ORG-ID --output-dir ~/Desktop/seer-templates/
> ```

---

## Phase 1: Deploy the Cross-Account Member Role

This IAM role is deployed to every member account in your Organization so Seer can discover their running services. You deploy it once via **CloudFormation StackSets** from the management account.

### Step 1.1 — Open CloudFormation StackSets

1. Sign in to the **AWS Management Console** as the management account
2. Navigate to **CloudFormation** → **StackSets** (left sidebar)
3. Click **Create StackSet**

### Step 1.2 — Upload the Member Role Template

1. Under **Prerequisite**, select **Service-managed permissions** (this lets StackSets deploy to all accounts in your Organization automatically)
2. Under **Specify template**, select **Upload a template file**
3. Click **Choose file** and select `~/Desktop/seer-templates/seer-member-role.yaml`
4. Click **Next**

### Step 1.3 — Configure Parameters

1. **StackSet name**: `SeerMemberRole`
2. **StackSet description**: `Cross-account IAM role for Seer service discovery`
3. Fill in the parameters:
   - **ManagementAccountId**: Your 12-digit management account ID (e.g., `123456789012`). Find this in the top-right corner of the console.
   - **ExternalId**: A unique string for security (e.g., `seer-ext-abc123`). Write this down — you'll need it when configuring Seer.
4. Click **Next**

### Step 1.4 — Set Deployment Options

1. Under **Add stacks to stack set**, select **Deploy to organization**
2. Under **Automatic deployment**, enable **Activated** (so new accounts automatically get the role)
3. Under **Account removal behavior**, select **Delete stacks**
4. Under **Specify regions**, select **one region** (IAM roles are global — you only need one region, e.g., `us-east-1`)
5. Under **Deployment options**:
   - **Maximum concurrent accounts**: `10` (or higher for large orgs)
   - **Failure tolerance**: `1`
6. Click **Next**

### Step 1.5 — Review and Submit

1. Check the box: **I acknowledge that AWS CloudFormation might create IAM resources with custom names**
2. Click **Submit**
3. Wait for the StackSet to show **SUCCEEDED** status (usually 2-5 minutes)

### Step 1.6 — Verify

1. Go to **CloudFormation** → **StackSets** → **SeerMemberRole** → **Stack instances**
2. Confirm all member accounts show **CURRENT** status
3. Optionally, switch to a member account and verify the `SeerDiscoveryRole` exists in **IAM** → **Roles**

---

## Phase 2A: Deploy Seer MVP

Use this if you want a quick proof-of-concept with just the core pipeline.

### Step 2A.1 — Open CloudFormation

1. Navigate to **CloudFormation** → **Stacks** (in the management account)
2. Click **Create stack** → **With new resources (standard)**

### Step 2A.2 — Upload the MVP Template

1. Under **Specify template**, select **Upload a template file**
2. Click **Choose file** and select `~/Desktop/seer-templates/seer-mvp.yaml`
3. Click **Next**

### Step 2A.3 — Configure Stack Parameters

1. **Stack name**: `seer-mvp`
2. Fill in the parameters:

| Parameter | Value | Notes |
|-----------|-------|-------|
| **OrganizationId** | `o-your-org-id` | From AWS Organizations console |
| **IncludedAccounts** | *(leave empty)* | Empty = scan all accounts |
| **ExcludedAccounts** | *(leave empty)* | Optional — comma-separated account IDs to skip |
| **IncludedRegions** | `us-east-1,us-west-2` | Regions to scan (comma-separated) |
| **ExcludedRegions** | *(leave empty)* | Optional |
| **ScheduleExpression** | `rate(1 day)` | How often Seer runs |

3. Click **Next**

### Step 2A.4 — Configure Stack Options

1. **Tags** (optional): Add `Project: Seer`, `Environment: Dev`
2. **Permissions**: Leave as default (CloudFormation will use your current role)
3. **Stack failure options**: Select **Roll back all stack resources**
4. Click **Next**

### Step 2A.5 — Review and Create

1. Scroll to the bottom
2. Check the box: **I acknowledge that AWS CloudFormation might create IAM resources with custom names**
3. Click **Submit**
4. Wait for the stack to show **CREATE_COMPLETE** (usually 3-5 minutes)

### Step 2A.6 — Verify MVP Deployment

1. Go to the **Outputs** tab of the `seer-mvp` stack
2. Note the key outputs:
   - **StateMachineArn** — the Step Functions pipeline
   - **DataBucketName** — where recommendations are stored
   - **ScheduleRuleArn** — the EventBridge schedule
3. Navigate to **Step Functions** → find `seer-pipeline` → click **Start execution** to trigger a test run
4. After the run completes (~2-5 minutes), check the S3 data bucket for recommendation output files

---

## Phase 2B: Deploy Seer Full Production

Use this for a complete deployment with dashboard, email delivery, observability, and security hardening.

### Step 2B.1 — Open CloudFormation

1. Navigate to **CloudFormation** → **Stacks** (in the management account)
2. Click **Create stack** → **With new resources (standard)**

### Step 2B.2 — Upload the Full Template

1. Under **Specify template**, select **Upload a template file**
2. Click **Choose file** and select `~/Desktop/seer-templates/seer-full.yaml`
3. Click **Next**

### Step 2B.3 — Configure Stack Parameters

1. **Stack name**: `seer-production`
2. Fill in the parameters:

| Parameter | Value | Notes |
|-----------|-------|-------|
| **OrganizationId** | `o-your-org-id` | From AWS Organizations console |
| **IncludedAccounts** | *(leave empty)* | Empty = scan all accounts |
| **ExcludedAccounts** | *(leave empty)* | Optional |
| **IncludedRegions** | `us-east-1,us-west-2,eu-west-1` | Regions to scan |
| **ExcludedRegions** | *(leave empty)* | Optional |
| **ScheduleExpression** | `cron(0 8 * * ? *)` | Daily at 8 AM UTC |
| **EmailRecipients** | `your-team@example.com` | SES-verified email(s), comma-separated |
| **CognitoDomain** | `seer-prod` | Prefix for Cognito hosted UI domain |
| **EnableWaf** | `true` | WAF protection on API Gateway |
| **EnableXray** | `true` | X-Ray distributed tracing |
| **RetentionDays** | `90` | CloudWatch log retention |

3. Click **Next**

### Step 2B.4 — Configure Stack Options

1. **Tags**: Add `Project: Seer`, `Environment: Production`
2. **Permissions**: Leave as default
3. **Stack failure options**: Select **Roll back all stack resources**
4. **Advanced options** → **Termination protection**: **Enabled** (recommended for production)
5. Click **Next**

### Step 2B.5 — Review and Create

1. Scroll to the bottom
2. Check **both** boxes:
   - **I acknowledge that AWS CloudFormation might create IAM resources with custom names**
   - **I acknowledge that AWS CloudFormation might require the following capability: CAPABILITY_AUTO_EXPAND** (if shown)
3. Click **Submit**
4. Wait for **CREATE_COMPLETE** (10-15 minutes — CloudFront distribution takes ~5 min)

### Step 2B.6 — Verify Full Production Deployment

1. Go to the **Outputs** tab of the `seer-production` stack
2. Key outputs to note:

| Output | What it is |
|--------|-----------|
| **ApiGatewayUrl** | REST API endpoint for on-demand runs |
| **DashboardUrl** | CloudFront URL for the web dashboard |
| **CognitoUserPoolId** | User Pool for authentication |
| **CognitoClientId** | App Client ID for the dashboard |
| **StateMachineArn** | Step Functions pipeline |
| **AlarmTopicArn** | SNS topic for failure alerts |
| **KmsKeyArn** | Encryption key |

3. **Test the pipeline**: Go to **Step Functions** → `seer-pipeline` → **Start execution**
4. **Access the dashboard**: Open the **DashboardUrl** in your browser. You'll be prompted to sign in via Cognito — create a user first in the Cognito console.
5. **Check email delivery**: After a run completes, verify the summary email arrives at your configured recipients.
6. **Check alarms**: Go to **CloudWatch** → **Alarms** → verify `seer-pipeline-failure` alarm exists.

---

## Phase 3: Create Your First Cognito User (Full Production Only)

> **This step is now automated.** The full production template auto-creates an admin user using the first email in your `EmailRecipients` parameter. A temporary password is sent to that email during deployment.

1. Check the inbox of your `EmailRecipients` email
2. Look for an email from **Amazon Cognito** with a temporary password
3. Open the **DashboardUrl** from the stack outputs
4. Sign in with your email and the temporary password
5. Set a new permanent password when prompted

---

## Phase 4: Confirm Automated Email Subscriptions (Full Production Only)

The full production template automatically creates two email subscriptions during deployment. You just need to confirm them:

### Step 4.1 — Confirm SNS Alarm Subscription

1. Check the inbox of the **first email** in your `EmailRecipients` parameter
2. Look for an email from **AWS Notifications** with subject "AWS Notification - Subscription Confirmation"
3. Click **Confirm subscription** in the email
4. You'll now receive alerts when Seer pipeline runs fail

### Step 4.2 — Verify SES Email Identity

1. Check the same inbox for an email from **Amazon Web Services** with subject "Amazon SES Email Identity Verification"
2. Click the **verification link** in the email
3. This allows Seer to send recommendation emails from this address

> Both emails arrive within 1-2 minutes of stack creation completing. If you don't see them, check your spam folder.

---

## Troubleshooting

### Stack creation fails with "Access Denied"
- Ensure your IAM user/role has `cloudformation:*`, `iam:*`, `lambda:*`, `dynamodb:*`, `s3:*`, `states:*`, `events:*` permissions
- For full production: also need `apigateway:*`, `cognito-idp:*`, `wafv2:*`, `cloudfront:*`, `ses:*`, `sns:*`, `kms:*`, `logs:*`, `cloudtrail:*`

### Stack creation fails with "Resource limit exceeded"
- Check your account's CloudFormation stack resource limit (default 500 per stack)
- The full template uses ~85 resources — well within limits

### Step Functions execution fails
- Check **CloudWatch Logs** for the Lambda function that failed
- Common issue: `SeerDiscoveryRole` not deployed to member accounts (Phase 1 incomplete)
- Common issue: Lambda timeout — increase timeout in the stack parameters

### No recommendations generated
- Verify the Organization has running services in the scanned regions
- Check the intelligence sources are reachable (AWS What's New feed, etc.)
- Check the S3 data bucket for intermediate files (`inventory/`, `intelligence/`)

### Dashboard shows "Unauthorized"
- Create a Cognito user (Phase 3)
- Verify the Cognito domain is correctly configured
- Check browser console for CORS errors

---

## Cleanup

To remove Seer completely:

1. **Delete the main stack**: CloudFormation → Stacks → `seer-mvp` or `seer-production` → **Delete**
2. **Delete the StackSet**: CloudFormation → StackSets → `SeerMemberRole` → **Delete stacks from stack set** (all accounts) → then **Delete StackSet**
3. **Empty and delete S3 buckets**: The data bucket has `DeletionPolicy: Retain` — you'll need to empty and delete it manually in the S3 console

---

## Quick Reference

### One-Click Deploy (CLI)

For those who prefer the command line, a deploy script handles everything:

```bash
# Make the script executable (one time)
chmod +x ~/Library/CloudStorage/OneDrive-amazon.com/deploy.sh

# Deploy MVP
./deploy.sh --profile mvp --org-id o-YOUR-ORG-ID

# Deploy Full Production with email
./deploy.sh --profile full --org-id o-YOUR-ORG-ID --email team@example.com

# Deploy Full Production + member role via StackSets
./deploy.sh --profile full --org-id o-YOUR-ORG-ID --email team@example.com --deploy-member-role
```

The script automatically: packages Lambda code → uploads to S3 → deploys CloudFormation → applies stack policy → shows outputs.

---

## Unified Template — Upgrade MVP → Full via Parameter Change

When you generate templates with `--profile both`, a **unified template** (`seer-unified.yaml`) is produced alongside the separate MVP and Full templates. The unified template contains ALL resources but uses a `DeploymentProfile` CloudFormation parameter to control which resources are created.

### How it works

- The `DeploymentProfile` parameter accepts `mvp` (default) or `full`
- Full-only resources have a `Condition: IsFullProfile` that only creates them when `DeploymentProfile=full`
- **Upgrading from MVP to Full is a stack UPDATE** — just change the parameter value

### Deploy with the unified template

```bash
# Deploy as MVP initially
aws cloudformation deploy \
  --template-file seer-unified.yaml \
  --stack-name seer-platform \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    OrganizationId=o-YOUR-ORG-ID \
    DeploymentProfile=mvp

# Later, upgrade to Full by changing the parameter
aws cloudformation deploy \
  --template-file seer-unified.yaml \
  --stack-name seer-platform \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    OrganizationId=o-YOUR-ORG-ID \
    DeploymentProfile=full \
    EmailRecipients=team@example.com
```

No need to delete and recreate the stack — your data bucket and DynamoDB tables are preserved.

---

## Stack Policy Protection

A `stack-policy.json` file is generated alongside the templates. It prevents accidental deletion or replacement of critical stateful resources during stack updates:

- **SeerDataBucket** — S3 bucket containing all Seer data
- **SeerRecommendationsTable** — DynamoDB table with recommendation history

The deploy script automatically applies this policy. For manual deployments:

```bash
aws cloudformation set-stack-policy \
  --stack-name seer-platform \
  --stack-policy-body file://stack-policy.json
```

To temporarily override the policy for a specific update (e.g., intentional table replacement):

```bash
aws cloudformation update-stack \
  --stack-name seer-platform \
  --template-body file://seer-full.yaml \
  --stack-policy-during-update-body '{"Statement":[{"Effect":"Allow","Action":"Update:*","Principal":"*","Resource":"*"}]}'
```

---

## Auto-Detect Regions (Full Profile)

The Full Production template includes a **region auto-detection** Custom Resource that calls `ec2:DescribeRegions` to discover all enabled regions in your account.

- If you leave the `IncludedRegions` parameter empty, Seer can use the auto-detected regions
- The detected regions are available via `!GetAtt SeerDetectedRegions.Regions`
- This is useful for organizations that enable new regions over time — Seer automatically picks them up

The auto-detection resources include:
- `SeerRegionDetectorRole` — IAM role with `ec2:DescribeRegions` permission
- `SeerRegionDetectorFunction` — Lambda function (inline Python) that calls the API
- `SeerDetectedRegions` — Custom Resource that invokes the detector

---

## Service Catalog — Self-Service Deployment

For organizations that want governed, self-service Seer deployment, a **Service Catalog template** (`seer-service-catalog.yaml`) is generated when using `--profile both`.

### What it creates

- **Portfolio**: "Seer Advisory Platform" — groups the Seer product
- **Product**: References the unified template so users can choose MVP or Full
- **Launch Role**: IAM role with permissions to create all Seer resources
- **Launch Constraint**: Ensures all deployments use the governed launch role

### Deploy the Service Catalog product

1. Upload `seer-unified.yaml` to an S3 bucket
2. Deploy the Service Catalog template:

```bash
aws cloudformation deploy \
  --template-file seer-service-catalog.yaml \
  --stack-name seer-service-catalog \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    UnifiedTemplateUrl=https://s3.amazonaws.com/my-bucket/seer-unified.yaml \
    PortfolioOwner="Cloud Platform Team" \
    SupportEmail=cloud-platform@example.com
```

3. Grant access to the portfolio for IAM users/groups/roles via the Service Catalog console
4. Users can then launch Seer from the Service Catalog console with governed parameters

---

### Profile Comparison

| Item | MVP | Full Production |
|------|-----|----------------|
| Deploy time | ~3 min | ~10-15 min |
| Resources | 16 | ~88 |
| Dashboard | ❌ | ✅ CloudFront + S3 |
| Email delivery | ❌ | ✅ SES (auto-verified) |
| S3 output | ✅ | ✅ |
| Observability | ❌ | ✅ CloudWatch + X-Ray |
| WAF | ❌ | ✅ |
| Encryption | AWS-managed | KMS customer-managed |
| DLQs | ❌ | ✅ |
| Alarm subscription | ❌ | ✅ Auto-subscribed |
| SES verification | ❌ | ✅ Auto-registered |
| Manual post-deploy steps | 0 | 2 (confirm emails) |
| Cost (idle) | ~$0/month | ~$5-10/month (CloudTrail, KMS) |
| Cost (active) | ~$1-5/run | ~$2-10/run |