AWS least-privilege idempotent deployment

[satra]

Summary

• OpenTofu IaC for all AWS resources (EC2, IAM, ECR, SSM, security groups)
• GitHub OIDC auth — no long-lived AWS access keys
• Deploy role scoped to 14 IAM permissions (SSM, ECR, EC2 describe only)
• SSM-based deployment — no SSH, no port 22
• Caddy reverse proxy with automatic TLS (replaces nginx + certbot)
• docker-rollout for zero-downtime deployments with health-check rollback
• Secrets in SSM Parameter Store (KMS-encrypted, never in images/logs/VCS)
• Concurrency group serializes deploys (no race conditions)
• Cost: ~$18-20/month (vs $120+ for Fargate equivalent)

Files Added/Changed

• infra/ — 14 OpenTofu files (HCL, scripts, tests, Makefile)
• deploy/Caddyfile — automatic TLS, /et/ legacy path support
• deploy/docker-compose.yml — caddy replaces nginx, server healthcheck
• .github/workflows/deploy.yml — OIDC + ECR + SSM (replaces SSH)
• .github/workflows/ci.yml — OpenTofu validation + IAM policy tests
• docs/bootstrap.md — full infrastructure setup guide
• docs/external-setup-guide.md — updated for OIDC (removed SSH secrets)

Test plan

• tofu validate and tofu fmt -check pass in CI
• IAM policy tests verify: 14 actions, no wildcards, no iam:* , correct trust
• Deploy smoke test: health endpoint, TLS cert, port 22 closed
• Secret audit: no secrets in images, logs, or VCS
• Idempotency: second tofu apply shows 0 changes
• Deploy workflow: OIDC auth, ECR push, SSM deploy, health check
• Concurrent deploys serialize via concurrency group

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust and secure AWS deployment strategy for the etelemetry project, transitioning from manual SSH-based deployments to a fully automated, least-privilege, and idempotent system. It leverages modern cloud practices like Infrastructure as Code with OpenTofu, GitHub OIDC for authentication, and SSM for secure remote execution. Concurrently, the core application stack has been migrated to a more efficient PostgreSQL/FastAPI architecture within a monorepo, complete with a new web dashboard and a tool for migrating existing data securely.

Highlights

• Infrastructure as Code (IaC): Implemented AWS infrastructure using OpenTofu, covering EC2, IAM, ECR, SSM, and security groups, ensuring an idempotent and version-controlled setup.
• Secure Authentication: Introduced GitHub OIDC for AWS authentication, eliminating the need for long-lived AWS access keys and enhancing security.
• Least-Privilege IAM Roles: Configured highly restricted IAM roles for deployment (14 specific permissions) and EC2 instances, adhering to the principle of least privilege.
• SSM-Based Deployment: Enabled SSM-based deployment for EC2 instances, removing SSH access (port 22) and improving security posture.
• Automated TLS and Zero-Downtime Deployments: Integrated Caddy as a reverse proxy for automatic TLS certificate management and docker-rollout for zero-downtime deployments with health-check rollbacks.
• Secure Secret Management: Utilized AWS SSM Parameter Store for KMS-encrypted secrets, ensuring they are never exposed in images, logs, or version control.
• Monorepo Structure and Stack Migration: Refactored the project into a monorepo, migrating the server stack from MongoDB/Sanic to PostgreSQL/FastAPI, and providing a migration tool for historical data.
• Web Dashboard: Developed a server-rendered web dashboard using Jinja2, htmx, and Leaflet.js to visualize usage statistics with geographic distribution.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Ignored Files

• Ignored by pattern: .github/workflows/** (4)
  • .github/workflows/ci.yml
  • .github/workflows/deploy.yml
  • .github/workflows/publish.yml
  • .github/workflows/release.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive and well-designed infrastructure-as-code setup for AWS using OpenTofu. The move to GitHub OIDC, SSM for deployments, and Caddy for automatic TLS represents a significant improvement in security and maintainability. The code is well-structured and follows best practices for least-privilege IAM roles and idempotent deployments. I've identified a few areas for improvement, primarily concerning potential IP address logging, security hardening of the deployment scripts, and cleanup of outdated documentation and configuration files. Overall, this is an excellent contribution.

I am having trouble creating individual review comments. Click here to see my feedback.

deploy/Caddyfile (3-8)

The comment on line 6 states that IP addresses are excluded from logs, but the current configuration for format json will still include the client's IP address by default. To align with the privacy requirement of not logging IPs (FR-005, FR-016), you should explicitly configure the JSON logger to exclude IP-related fields.

	log {
		output stdout
		format json {
			exclude_keys "remote_ip" "remote_port" "client_ip"
		}
		# IP addresses are excluded from logs — only method, path, status
		level INFO
	}

deploy/Dockerfile (28)

The uvicorn command includes the --access-log flag. While app.py disables the uvicorn.access logger, enabling this flag is still problematic as it can log sensitive information like IP addresses, which contradicts the project's privacy goals (FR-005, FR-016). Since Caddy is the front-end reverse proxy and handles access logging, Uvicorn's access logs are redundant and should be disabled by removing this flag.

CMD ["sh", "-c", "cd server && python -m alembic upgrade head && cd .. && uvicorn etelemetry_server.app:app --host 0.0.0.0 --port 8000 --workers 2"]

docs/external-setup-guide.md (1-310)

This document appears to be largely outdated and contains instructions that conflict with the new OpenTofu-based, SSM-driven deployment architecture. For example, it references manual EC2 setup, certbot for TLS, and SSH-based deployment secrets, all of which have been replaced. This will likely cause confusion for operators. This guide should be either removed or completely rewritten to align with the new process detailed in docs/bootstrap.md.

CLAUDE.md (19)

This line appears to contain placeholder text or a generation artifact instead of a valid command. It should be corrected to a valid example command or removed if it's not intended to be there.

cd src && pytest && ruff check .

deploy/Dockerfile (28)

The CMD instruction runs database migrations (alembic upgrade head) before starting the application. This pattern can be risky in a containerized environment, especially during rollouts where multiple new containers might start simultaneously and attempt to run migrations concurrently. This can lead to race conditions or failures. It is a more robust practice to run migrations as a separate, explicit step in your deployment script (infra/scripts/deploy.sh) before the application containers are rolled out.

CMD ["sh", "-c", "cd server && uvicorn etelemetry_server.app:app --host 0.0.0.0 --port 8000 --workers 2"]

deploy/nginx.conf (1-37)

This nginx.conf file appears to be a leftover from the previous architecture. The new setup uses Caddy as the reverse proxy, as defined in deploy/docker-compose.yml and deploy/Caddyfile. To avoid confusion and keep the repository clean, this file should be removed.

infra/iam.tf (151-156)

The ECRPull statement in the instance role policy uses "Resource": "*". While ecr:GetAuthorizationToken is an account-level permission, the other actions (ecr:BatchGetImage, ecr:GetDownloadUrlForLayer) can be scoped to the specific ECR repository ARN. To adhere to the principle of least privilege, it's recommended to restrict these permissions to the etelemetry repository.

        Action = [
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer"
        ]
        Resource = aws_ecr_repository.etelemetry.arn
      },
      {
        Sid    = "ECRAuth"
        Effect = "Allow"
        Action = [
          "ecr:GetAuthorizationToken"
        ]
        Resource = "*"

infra/scripts/deploy.sh (30)

This line constructs and writes DATABASE_URL to the .env file. However, deploy/docker-compose.yml also defines DATABASE_URL in its environment section, and its definition will take precedence over the one in the .env file. This makes the line in this script redundant and potentially misleading, especially since it hardcodes the username etelemetry. It's better to remove this line and rely on the docker-compose.yml definition, which correctly uses variables from the .env file.

infra/scripts/user-data.sh (17-19)

The docker-rollout tool is installed by curling a script directly from the main branch of a GitHub repository. This poses a security risk and lacks reproducibility, as the content of main can change at any time. It is safer to download a specific, versioned release artifact and, ideally, verify its checksum before execution.