Skip to main content

Guidance for Deploying Harmonix on AWS

Overview

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.

How it works

Provisioning the AWS account

This architecture diagram illustrates how to provision an AWS account after cloning Harmonix from GitHub.

Architecture diagram showing the provisioning workflow for Harmonix on AWS. The diagram illustrates user interaction, client setup, and installation instructions, along with the deployment process using Amazon ECR, Amazon ECS, EC2 instance, IAM roles, and GitLab CI/CD for continuous integration and deployment within the AWS cloud.

Provisioning an Amazon ECS environment

This architecture diagram shows how to provision an Amazon ECS environment using Harmonix on AWS.

Architecture diagram showing the integration of Harmonix with AWS ECS, GitLab CI/CD, Amazon EC2, Virtual Private Cloud (VPC), IAM Roles, Amazon CloudWatch, and Amazon DynamoDB. The diagram illustrates the flow and relationship between developers, AWS accounts, and foundational application components.

Provisioning an Amazon EKS environment

This architecture diagram shows how to provision an Amazon EKS environment using Harmonix on AWS.

Architecture diagram illustrating the provisioning process for Amazon EKS using Harmonix on AWS. The diagram shows developers interacting with AWS Cloud, Amazon ECS, EC2 instances with GitLab CE, IAM roles for operations and provisioning, VPC, Amazon EKS, AWS Lambda (Kubectl), Amazon CloudWatch, and Amazon DynamoDB audit table.

Provisioning a serverless environment

This architecture diagram shows how to provision a serverless environment with Amazon API Gateway using Harmonix on AWS.

Architecture diagram showing the serverless environment for Harmonix on AWS, including components such as Amazon ECS, EC2 GitLab CI/CD, IAM roles, Virtual Private Cloud (VPC), API Gateway, Amazon CloudWatch, and Amazon DynamoDB audit table, with developer access flows.

Well-Architected Pillars

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.

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.

Read the Operational Excellence whitepaper 

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.

Read the Security whitepaper 

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.

Read the Reliability whitepaper 

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.

Read the Performance Efficiency whitepaper 

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.

Read the Cost Optimization whitepaper 

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.

Read the Sustainability whitepaper 

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.