4
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@yutaka_kozuka

Harmonix on AWSを構築・詳細解説してみた

4
Last updated at Posted at 2025-08-12

builders.flashで、Harmonix on AWS でクイックに始める開発者ポータルというマガジンが寄稿されていたので、実際にHarmonix on AWSを構築しました。

（以下画像はHarmonixのアーキ図概要）
architecture.png

本記事では、builders.flashではカバーしきれていない内容や、独自の要件、詳細なアーキテクチャについて記載しています。

Harmonix on AWSとは？

Harmonix on AWSの前に、Backstageについて説明します。BackstageはSpotifyが開発し、Cloud Native Computing Foundation (CNCF)に寄贈したOSSの開発者プラットフォームです。

Harmonix on AWSは、そのBackstageをベースにしたAWS向け開発者プラットフォームです。プラットフォームエンジニアリングの思想に基づき、開発者がインフラ（AWS）を意識せずに、アプリケーション開発に集中できる環境を提供します。

このプラットフォームは、ECSやEKSなど、AWSリソースのセルフサービスデプロイを実現し、開発者が必要なインフラストラクチャを自律的に構築・管理できるようにします。

つまり、開発者は、ECSやEKSなどの開発環境をインフラを気にせず、デプロイし、その上でアプリケーションを実行することができます。

実際の利用事例と導入効果

当初、大規模なプロジェクトで複数のアプリケーションチームが並行して開発を進める状況において、アプリチームがインフラを気にせずにコンテナを実行できる環境が求められていました。

従来の課題として、

  • アプリチームがECSクラスターを立ち上げるたびに、インフラチームへの依頼が必要で、環境追加に数日かかることもありました。また、IaCを利用していても、チーム内での構成や運用に差分が出てきました。

このような課題を解決するため、検証環境などでHarmonix on AWSを導入しました。

導入による効果

1. 開発速度の大幅な向上

  • アプリチームが必要な時に、数分で独自のECS環境を立ち上げ可能に
  • インフラチームへの依頼待ち時間が激減

2. インフラチームの負担軽減

  • 繰り返し発生する環境構築リクエストから解放
  • より戦略的なアーキテクチャ設計に注力できるように

3. 標準化と品質向上

  • テンプレートにより、セキュリティベストプラクティスが自動適用
  • チーム間でのインフラ構成の一貫性が担保

4. 可視化とガバナンス

  • すべてのリソースがBackstageポータルで一元管理
  • どのチームが何を使っているか、すぐに把握可能
  • コスト管理とリソース最適化が容易に

このように、Harmonix on AWSは単なるツールではなく、組織全体の開発文化を変革するプラットフォームとして機能しました。

2つのコンポーネント・アーキテクチャ

続いて、Harmonix on AWSのアーキテクチャについて、解説します。

以下のように、BackstageとGitLabとして、大きく二つのコンポーネントに分けられています。

architecture.png

1. Backstage（開発者ポータル）

役割: 開発者の統一インターフェース

  • アプリケーションテンプレートからの新規作成
  • デプロイ状況の可視化
  • AWSリソースの管理
  • チーム間のコラボレーション

アーキテクチャ:

[開発者] → [ALB] → [ECS Fargate] → [Aurora PostgreSQL]
                      ↓
                 [Backstageアプリ]
  • ECS Fargate: Backstageアプリケーションをコンテナで実行
  • Aurora PostgreSQL: カタログ情報、ユーザー情報、テンプレート定義を保存
  • ALB: Backstageへのアクセス
  • ※WAFやKMSなどのサービス等は省略

2. GitLab（ソースコード管理 + CI/CD）

役割: コード管理とデプロイメント自動化

  • ソースコードのバージョン管理
  • CI/CDパイプラインの実行
  • AWSリソースのプロビジョニング

アーキテクチャ:

[開発者] → [ALB] → [EC2] → [GitLab CE]
                     ↓
              [GitLab Runner EC2]
                     ↓
              [AWS環境へデプロイ]
  • EC2インスタンス: GitLab Community Editionをホスト
  • GitLab Runner EC2: CI/CDジョブを実行
  • ALB: GitLabへのアクセス
  • ※WAFやKMSなどのサービス等は省略

Git統合におけるBackstageとの違い

Backstage単体では、Gitサービスは提供されていません。Backstageは：

  • 既存のGitプロバイダー（GitHub、GitLab、Bitbucket等）と連携する
  • Git統合のためのプラグインシステムを提供

Harmonix on AWSでは：

  • 参考実装としてGitLab Community Editionを含めている
  • 企業がすぐに試せる完全な環境を提供するため
  • 実際の本番環境では、企業の既存GitプロバイダーやGitHub等に置き換え可能

Harmonix on AWSでの開発

主要なパターンを含むAWS構成テンプレートやサンプルアプリケーションを構築するためのテンプレートが含まれています。開発者はポータル上からテンプレートを選び、EKSやECSなどのAWSサービスを利用したリソースを素早く作成できます。

提供されるテンプレート例

  • コンテナ環境: ECS、EKS環境プロバイダー
  • サーバーレス: Lambda、API Gateway構成
  • データベース: RDS、DynamoDB統合
  • アプリケーション: Node.js、Python Flask、Spring Boot

セルフサービスデプロイメントの仕組み

開発者がテンプレートを選択すると、CloudFormationスタックとしてリソースがデプロイされます。

デプロイされるリソース例（テンプレートによる）：

  • ネットワーク基盤: VPC、サブネット、セキュリティグループ
  • コンピューティング: ECSクラスター、サービス、タスク定義
  • ロードバランサー: ALB、ターゲットグループ
  • セキュリティ: IAMロール、ポリシー
  • データストア: RDS、DynamoDB

特徴：

  • 各アプリケーションごとに独立したCloudFormationスタックが作成
  • Envitonment作成時のオプションとして、別アカウントへのCloudFormationスタックのデプロイが指定可能
  • Infrastructure as Codeでリソース管理
  • 開発者はAWSコンソールを直接操作せずに、Backstageでリソース作成、デプロイ状況を一元管理可能

開発フロー

  1. 開発者がBackstageでアプリテンプレートを選択
  2. BackstageがGitLabに新しいリポジトリを作成
  3. GitLab RunnerがCI/CDパイプラインを実行
  4. AWS CDK/CloudFormationが同じAWSアカウントにリソースをデプロイ
  5. Backstageでデプロイ状況とリソースを可視化

Harmonix on AWS デプロイ手順

実際にHarmonix on AWSを構築した際の手順と注意を以下に記載します。

1. サブドメインの作成

Builders.flashでは、Harmonix on AWSを構築する際に、ドメインと Amazon Route 53 Hosted Zoneが必要であるという記載があります。

既存のドメイン（wakaru-blog.com）は、既に別システム用に使用していたため、Harmonix専用のサブドメイン（harmonix.wakaru-blog.com）を作成しました。

Route 53で新しくホストゾーンを作成し、NSレコードを委譲しています。

2. デプロイ用のネットワーク・EC2インスタンスの作成

AWS上で、Harmonix on AWSをデプロイするために、EC2等を起動する必要があります。

CloudFormationテンプレートを使用してネットワーク基盤を構築します：

ネットワーク基盤CloudFormationテンプレート 
AWSTemplateFormatVersion: '2010-09-09'
Description: Harmonix on AWSデプロイ用最小ネットワーク構成

Parameters:
  VpcCidr:
    Type: String
    Default: 10.0.0.0/16
  PublicSubnet1Cidr:
    Type: String
    Default: 10.0.0.0/24
  PrivateSubnet1Cidr:
    Type: String
    Default: 10.0.10.0/24

Resources:

  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: !Ref VpcCidr
      EnableDnsSupport: true
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: harmonix-vpc

  InternetGateway:
    Type: AWS::EC2::InternetGateway
    Properties:
      Tags:
        - Key: Name
          Value: harmonix-igw

  AttachGateway:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref VPC
      InternetGatewayId: !Ref InternetGateway

  # Public Subnet 1 (for NAT Gateway)
  PublicSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: !Ref PublicSubnet1Cidr
      MapPublicIpOnLaunch: true
      AvailabilityZone: !Select [0, !GetAZs '']
      Tags:
        - Key: Name
          Value: harmonix-public-subnet-1 (for NAT Gateway)

  # Private Subnet 1 (for EC2)
  PrivateSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: !Ref PrivateSubnet1Cidr
      AvailabilityZone: !Select [0, !GetAZs '']
      Tags:
        - Key: Name
          Value: harmonix-private-subnet-1

  ElasticIP:
    Type: AWS::EC2::EIP
    DependsOn: AttachGateway

  NATGateway:
    Type: AWS::EC2::NatGateway
    Properties:
      AllocationId: !GetAtt ElasticIP.AllocationId
      SubnetId: !Ref PublicSubnet1
      Tags:
        - Key: Name
          Value: harmonix-natgw

  PublicRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref VPC
      Tags:
        - Key: Name
          Value: harmonix-public-rt

  PublicRoute:
    Type: AWS::EC2::Route
    Properties:
      RouteTableId: !Ref PublicRouteTable
      DestinationCidrBlock: 0.0.0.0/0
      GatewayId: !Ref InternetGateway

  PublicSubnet1RouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PublicSubnet1
      RouteTableId: !Ref PublicRouteTable

  PrivateRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref VPC
      Tags:
        - Key: Name
          Value: harmonix-private-rt

  PrivateRoute:
    Type: AWS::EC2::Route
    Properties:
      RouteTableId: !Ref PrivateRouteTable
      DestinationCidrBlock: 0.0.0.0/0
      NatGatewayId: !Ref NATGateway

  PrivateSubnet1RouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PrivateSubnet1
      RouteTableId: !Ref PrivateRouteTable

  EC2SecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: EC2 Security Group for SSM access
      VpcId: !Ref VPC
      SecurityGroupEgress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: 0.0.0.0/0
      Tags:
        - Key: Name
          Value: harmonix-ec2-sg

CloudFormationテンプレートを使用してEC2インスタンスを作成します：

注意①：EC2インスタンスのAMIは、us-east-1用のAMIを記載しています。適宜修正してください。
注意②：userData で各種ソフトウェアをインストールしています。EC2に接続した後、 /var/log/cloud-init-output.log で実行結果を確認してください。

EC2インスタンスCloudFormationテンプレート 
AWSTemplateFormatVersion: '2010-09-09'
Description: Harmonix on AWSデプロイ用EC2インスタンス

Parameters:
  System:
    Type: String
    Default: harmonix
  SubnetId:
    Type: AWS::EC2::Subnet::Id
  SecurityGroupId:
    Type: AWS::EC2::SecurityGroup::Id

Resources: 
  EC2IAMRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Sub ${System}-ec2-role
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - ec2.amazonaws.com
            Action:
              - sts:AssumeRole
      Path: /
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AdministratorAccess

  EC2InstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      Path: /
      Roles:
        - Ref: EC2IAMRole
      InstanceProfileName: !Sub ${System}-ec2-instance-profile
     
  EC2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: ami-05ffe3c48a9991133 # us-east-1 Amazon Linux 2023 AMI ID
      InstanceType: t3.large
      IamInstanceProfile: !Ref EC2InstanceProfile
      SubnetId: !Ref SubnetId
      SecurityGroupIds:
        - !Ref SecurityGroupId
      Tags:
        - Key: Name
          Value: !Sub ${System}-ec2
      UserData: # check the result at /var/log/cloud-init-output.log
        Fn::Base64: !Sub |
          #!/bin/bash
          set -ex

          # パッケージ更新
          sudo dnf update -y

          # 基本ツールのインストール（unzip, jq, rsync, wget, curl はすでにインストールされている）
          sudo dnf install -y git make

          # Dockerインストール・起動
          sudo dnf install -y docker
          sudo systemctl enable docker
          sudo systemctl start docker
          sudo usermod -a -G docker ec2-user

          # Python3とpipのインストール
          sudo dnf install -y python3 python3-pip

          # Node.js 18.20以上のインストール
          curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
          sudo dnf install -y nodejs

          # Yarnのインストール
          sudo npm install -g yarn

          # AWS CDKのインストール
          sudo npm install -g aws-cdk

3. Okta Workforce Identity Integrator Free Planの登録

Harmonixの認証にはOktaを使用するため、アカウント登録が必要です。
builders.flash寄稿時以降で、おそらくOkta側でAuth0の買収やサービス提供があったと思われ、FREEプランが二つ表示されますが、Auth0は利用しないので、画面の右側にサインアップします。

okta-signup.png

  1. Okta Developer Portalにアクセス
  2. メール認証を完了
  3. 作成されたOktaドメインを確認（例：https://trial-8623494.okta.com）

4. Okta Verifyのモバイル設定

多要素認証のためにOkta Verifyアプリをモバイルデバイスにインストールし、設定を完了します。

5. Okta情報の取得と設定

Harmonixの設定ファイル（config/.env）に必要な以下の情報を設定します。

重要： Okta関連の環境変数にはダブルクォーテーション（"）を付けず、値のみを設定してください（例: OKTA_API_TOKEN=xxxxxx）。

これに関するIssueを報告済みです（GitHub Issue #176）が、まだ修正されていない可能性があります。

OKTA_API_TOKEN

  • Oktaのユーザー情報をBackstageで利用するためのAPIトークン
  • 「Security → API」メニューからトークンを作成

OKTA_AUDIENCE

注意：builders.flashには、https://dev-xxx.okta.com という記載がありますが、ここも変更になっていると思われます。

OKTA_CLIENT_ID, OKTA_CLIENT_SECRET

6. Harmonix on AWSデプロイ

セッションマネージャーでEC2に接続し、以下の作業を実行します：

# Harmonix on AWSリポジトリのクローン
git clone https://github.com/awslabs/harmonix.git
cd harmonix

# 環境設定ファイルの作成
cp config/sample.env config/.env
cd config
nano .env

# .envファイルの編集（builders.flash参照）
#   GitHubを使用しない場合：
#     GITHUB_TOKEN=TODO のまま残す
#     GITHUB_SECRET_NAME をコメントアウト

# Harmonix on AWSのデプロイ
cd ..
make install

7. Harmonix on AWSへのアクセス

デプロイが完了したら、設定したサブドメインからHarmonix on AWSにアクセスします。

https://サブドメイン

以下のようなサインイン画面が表示され、SIGN INをクリックするとOktaによる認証が実行されます。

signin.png

認証後は以下のようなホーム画面が表示されます。

home.png

これ以降の実際のアプリケーション開発については、builders.flashを参照してください。

8. Harmonix on AWSの削除

セッションマネージャーでEC2に接続し、以下の作業を実行します：

注意：完全な削除のためには、上記の手動削除項目も忘れずに削除してください。

# Harmonixディレクトリで実行
make destroy-platform
make delete-secrets

# 手動削除が必要な項目：
# - CloudFormationスタック（CDKToolkit）
# - S3バケット（cdk-hnb659fds-assets-<account-number>-us-east-1）

まとめ・感想

Harmonix on AWSは、Backstageをベースとした開発者プラットフォームです。
小規模な開発では、このようなプラットフォームは過剰であると思いますが、複数のアプリ開発が行われるような大規模な開発においては、アプリチームがインフラを意識せずに開発ができるため、プラットフォームエンジニアリングのメリットを実感できると思いました。

プラットフォームエンジニアリングに興味がある方は、ぜひ一度試してみることをお勧めします。

4
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?