[SEO Subhead]
This Guidance illustrates how to implement Harmonix on AWS, an enterprise-grade developer portal that bridges AWS services with your development teams. Provided as a reference implementation, Harmonix on AWS is an open-source tool that enables developers to build applications seamlessly while giving platform engineers comprehensive visibility across accounts, applications, and resources through a single interface. While the reference implementation uses specific tooling choices (such as Okta and GitLab), developers can either build upon this implementation directly, customize it for different toolsets, or implement Harmonix plugins within their existing Backstage deployment. This Guidance includes pre-built templates based on common patterns, showing how to provision an AWS account, an Amazon Elastic Container Service (Amazon ECS) environment, an Amazon Kubernetes Service (Amazon EKS) environment, and a serverless environment, helping developers efficiently deploy code, monitor logs, manage applications, and connect to shared resources.
Please note: [Disclaimer]
Architecture Diagram

-
Provisioning the AWS account
-
Provisioning an Amazon ECS environment
-
Provisioning an Amazon EKS environment
-
Provisioning a serverless environment
-
Provisioning the AWS account
-
This architecture diagram illustrates how to provision an AWS account after cloning Harmonix from GitHub.
Step 1
Clone the Harmonix on AWS repository from GitHub. -
Provisioning an Amazon ECS environment
-
This architecture diagram shows how to provision an Amazon ECS environment using Harmonix on AWS.
Step 1
The developer uses Harmonix on AWS to create an Amazon ECS environment using the ECS Environment provider template.
-
Provisioning an Amazon EKS environment
-
This architecture diagram shows how to provision an Amazon EKS environment using Harmonix on AWS.
Step 1
The developer uses Harmonix on AWS to create an Amazon EKS environment using the EKS Environment provider template.
-
Provisioning a serverless environment
-
This architecture diagram shows how to provision a serverless environment with Amazon API Gateway using Harmonix on AWS.
Step 1
The developer uses Harmonix on AWS to create a serverless environment using the serverless provider template.
Get Started

Well-Architected Pillars

The AWS Well-Architected Framework helps you understand the pros and cons of the decisions you make when building systems in the cloud. The six pillars of the Framework allow you to learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems. Using the AWS Well-Architected Tool, available at no charge in the AWS Management Console, you can review your workloads against these best practices by answering a set of questions for each pillar.
The architecture diagram above is an example of a Solution created with Well-Architected best practices in mind. To be fully Well-Architected, you should follow as many Well-Architected best practices as possible.
-
Operational Excellence
CloudWatch provides logs and tracing for applications and infrastructure. DynamoDB audits requests executed outside of AWS, capturing user interactions in the GitLab pipeline API. CloudFormation maintains IAC orchestration, reducing deployment overhead. These services facilitate troubleshooting, support native cloud conventions for configuration management, and enable observation of numerous apps across multiple accounts. The composition provides isolated access control and segregated auditing, improving compliance, security, and operational efficiency.
-
Security
IAM limits permissions for infrastructure and application creation through specific roles, such as provisioning and operations. Access to environments requires assuming these roles. AWS Key Management Service (AWS KMS) provides encryption keys for each environment, used to encrypt all stored data. Appropriate roles are granted access to environment-specific keys. AWS Secrets Manager stores sensitive information using environment-specific AWS KMS keys, saving secrets with environment and application context.
-
Reliability
While Harmonix on AWS currently uses a single site, you can run multiple sites (ECS clusters) with route policies for improved reliability. Elastic Load Balancing (ELB) distributes requests across multiple ECS containers, sending traffic only to healthy containers. Amazon ECS maintains application and platform lifecycles, helping ensure that apps are running, scaling as needed, and provisioning new tasks on failure. These services provide resiliency and automatic recovery for apps and the platform, with automatic monitoring, recovery, and traffic redirection to appropriate running tasks.
-
Performance Efficiency
Amazon ECS and Amazon EKS provide automatic scaling of desired tasks to help increase performance. Autoscaling groups, used with provisioned apps and ELB, improve performance by spinning up more app instances and distributing traffic across them. Lambda, a managed serverless compute service, offers automatic scaling when invoked through API, allowing serverless apps to benefit from performance increases during high traffic or demand.
-
Cost Optimization
Serverless Lambda functions operate on a pay-as-you-go model, meaning you only pay for resources used. This allows you to scale up as necessary and optimize costs by only charging for active compute time. This eliminates the need for dedicated EC2 instances that may be underutilized during off-peak hours. Amazon ECS and Amazon EKS containerized services improve infrastructure utilization by running multiple jobs and containers on shared infrastructure, maximizing throughput and scaling tasks across multiple nodes when needed.
-
Sustainability
As managed services, Amazon ECS and Amazon EKS provide efficient application runtime environments, reducing redundant instances when no job is required. Serverless Lambda functions abstract hardware, allowing AWS to optimize existing infrastructure for more efficient runtimes instead of running underutilized hardware. By leveraging these services, you can optimize application execution, reduce costs, and decrease power consumption and emissions. This approach supports sustainability by maximizing resource utilization and minimizing idle infrastructure.
Related Content

[Title]
Disclaimer
The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.
References to third-party services or organizations in this Guidance do not imply an endorsement, sponsorship, or affiliation between Amazon or AWS and the third party. Guidance from AWS is a technical starting point, and you can customize your integration with third-party services when you deploy the architecture.