How kayac/ecspresso works
Based on both the file tree and the README contents, “ecspresso” is a CLI deployment tool written in Go. It is designed to manage Amazon ECS services and Task Definitions, allowing users to perform operations such as deploy, diff, rollback, scale, run tasks, and integrate with AWS CodeDeploy for blue/green deployments. Moreover, it provides a robust plugin system for integrating with systems like Terraform state lookups, CloudFormation outputs, SSM Parameter Store, and Secrets Manager.
Main Components
• CLI Interface: At the center is the command-line interface (see “cli.go” and the “cmd/ecspresso” directory) that parses user input and invokes the proper command. This layer includes subcommands like deploy, diff, rollback, etc.
• Command Handlers / Core Modules:
– Separate modules (individual Go packages such as appspec, registry, secretsmanager, and others) are responsible for functionality like rendering configuration templates, handling AWS-specific logic, and interfacing with services.
– In particular, modules handling AWS deployments (e.g., deploy.go, register.go, scale.go) encapsulate calls to AWS ECS, CodeDeploy, and Auto Scaling.
• Configuration Management: A central configuration loader (supported formats include YAML, JSON, and Jsonnet) reads and interprets configuration files (like “ecspresso.yml”, “ecs-service-def.json”, “ecs-task-def.json”). This component also integrates template processing (utilizing “text/template” plus additional functions and plugins).
• Plugin Subsystem: A dedicated plugin module supports extensions – for instance, plugins for tfstate lookups, CloudFormation output fetching, SSM Parameter Store access, and resolving Secrets Manager ARNs.
• AWS Integration Layer: This layer represents the connection points for interacting with AWS services – ECS, CodeDeploy, Auto Scaling, ECR, CloudWatch logs, etc. The tool uses AWS SDK integrations and supports handling both Fargate and EC2 deployment scenarios.
• CI/CD Integrations: Although not part of the compiled code, documentation details integrations with Homebrew, asdf, aqua, GitHub Actions, and CircleCI (with provided YAML configurations); these external systems invoke ecspresso as part of the deployment pipeline.
Relationships and Data Flow
• User inputs a command via the CLI – e.g., “ecspresso deploy” – which is handled by the CLI module.
• The command handler loads the configuration (from files like ecspresso.yml), which may require template rendering. This rendering sometimes involves plugins (such as tfstate and cloudformation) to fetch dynamic values.
• The processed configuration instructs the AWS Integration Layer to invoke API calls to ECS and perhaps CodeDeploy to execute tasks such as registering a new task definition, updating a service, initiating rollbacks, or scaling services.
• For operations like “diff” or “verify”, the tool retrieves current remote state from AWS and compares it with the local configuration.
• CI/CD tools (GitHub Actions, CircleCI Orbs) call this CLI tool in automated pipelines, ensuring consistency across deployments.
Architectural Patterns and Design Principles
• Modular Design: The codebase is structured into fine-grained packages (e.g., appspec, registry, secretsmanager) that encapsulate specific responsibilities.
• Template & Plugin Extension: It separates core functionality from rendering (via Go’s “text/template” and additional Jsonnet processing), making it easy to extend with plugins.
• Command Pattern: Each operation (init, deploy, diff, etc.) is implemented as a distinct command, which helps in maintaining separation of concerns.
• Integration with External Tools: The design explicitly supports external integrations (CI/CD workflows, cloud configuration files) and encourages defining clear boundaries between configuration rendering and AWS API execution.