AWS で実践するプラットフォームエンジニアリング
Harmonix on AWS でクイックに始める開発者ポータル
Author : 林 政利
「プラットフォームエンジニアリング」という言葉は様々な IT 組織に浸透し始めており、AWS を利用する場合においても開発者向けのプラットフォーム、いわゆる「内部開発者プラットフォーム」を構築する取り組みが多くの組織で注目されています。しかし、実際にゼロから開発者ポータルを作り、開発者がセルフサービスで AWS リソースを利用できる環境を整えるのは簡単なことではありません。
AWS は、多くのサービスや機能、そしてそれぞれに適用すべきベストプラクティスを提供しています。AWS の様々なサービスがよく「ビルディングブロック」として紹介されるように、これらのサービスは組み合わせることで多くの組織、多くのワークロードにマッチする膨大な設計パターンを生み出せる仕組みになっています。
クラウドジャーニーの初期段階や、組織が小規模なうちは、少数のクラウドエキスパートが深い知識をもとに適切なサービスを選び、ブロックを組み立てていきます。しかし、組織が成長するにつれて、「どのブロックをどのように組み合わせるか」という知識や経験を組織全体に共有し、再利用可能にする必要が出てきます。
このとき、エキスパートの知見をドキュメントとしてまとめた Wiki ページという形もあれば、より高度な形として、開発者がワンクリックでユースケースに応じた AWS リソースを立ち上げられるテンプレートカタログが整備された、開発者ポータルという仕組みを作る場合もあります。
この記事では、AWS が提供するオープンソースソリューション、Harmonix on AWS を使い、開発者がすばやく、安全に AWS リソースを利用できるプラットフォームを作る方法を、ステップバイステップで紹介していきます。
目次
4-1. リポジトリのクローンと初期設定
4-2. インフラリソースのデプロイ
4-3. 開発者ポータルへのアクセス
5. セルフサービス体験
5-1. ポータルにアクセスする
5-2. Harmonix on AWS のモデルを理解する
5-3. AWS Environment を作成する
5-4. アプリケーションを作成する
5-5. アプリケーションを更新する
6. クリーンアップ
7. 次のステップに向けて
7-1. 組織の要件に沿ったテンプレートの作成
7-2. 開発者ポータルを変更、拡張する
7-3. プラットフォームで利用しているソフトウェアのバージョンアップ対応
8. まとめ
ご注意
本記事で紹介する AWS サービスを起動する際には、料金がかかります。builders.flash メールメンバー特典の、クラウドレシピ向けクレジットコードプレゼントの入手をお勧めします。
1. プラットフォームエンジニアリングとは ?
プラットフォームエンジニアリングは、近年、開発者体験を向上させる取り組みとして注目を集めているアプローチです。
単なる技術的なプラクティスではなく、DevOps、チーム構成、開発文化、ガバナンスなど、組織運営全体に関わる幅広い領域を横断するテーマでもあります。開発者がよりスムーズに、自律的にプロダクト開発に集中できるよう、共通の基盤やサービスを整備することがプラットフォームエンジニアリングの中心的な目的です。
プラットフォームエンジニアリングの全体像や実践例については、AWS でも過去にウェビナーを実施していますので、そのアーカイブも併せてぜひ、ご参照ください。
【開催報告】プラットフォームエンジニアリングって何?〜基本から AWS での実現方法について〜
本記事は、この広範なプラットフォームエンジニアリングというテーマの中でも、シンプルに「開発者ポータルを立ち上げ、セルフサービスで AWS リソースを利用できる体験を作る」ことにフォーカスします。
2. Harmonix on AWSとは ?
Harmonix on AWS は、AWS がオープンソースで提供する開発者向けポータルのリファレンス実装です。
Harmonix on AWS のベースとなっているのは、Cloud Native Computing Foundation (CNCF) プロジェクトでもある Backstage です。Backstage は、900 社以上の企業に採用されている開発者ポータルであり、100 以上のプラグインが利用可能です。Harmonix on AWS は、この Backstage をベースに AWS サービスとシームレスに統合し、さらにエンタープライズ利用を見据えたテンプレートや運用パターンをパッケージ化しています。
Harmonix on AWS が提供する主な機能は次のとおりです。
- カスタマイズ可能な開発者プラットフォーム
ソースコードはすべて公開されており、自社のニーズに合わせたカスタマイズが可能です - AWS リソースのセルフサービスデプロイ
主要なパターンを含む AWS 構成テンプレートやサンプルアプリケーションを構築するためのテンプレートが含まれています。開発者はポータル上からテンプレートを選び、Amazon EKS や Amazon ECS などの AWS サービスを利用したリソースを素早く作成できます - CI/CD パイプラインの実装
主要な開発パターンに対応する CI/CD が定義済みで、すぐに継続的デリバリーを始めることができます
3. Harmonix on AWS を使うための準備
Harmonix on AWS でポータルを実際に立ち上げるためには、いくつかの事前準備が必要です。このセクションでは、環境構築に必要なものと、事前にやっておくべき作業を整理します。
必要な前提条件
1. AWSアカウント
管理者権限を持った AWS アカウントが必要です。AWS アカウント ID (12 桁) と、デプロイするリージョンを確認しておきましょう。
2. ドメインと Amazon Route 53 Hosted Zone
Harmonix on AWS では、開発者ポータルに独自ドメインを使用します。また、本記事で紹介するのチュートリアルでは、ドメインを Amazon Route 53 の Public Hosted Zone で設定するようになっています。あらかじめ Route 53で、開発者ポータルとして利用するドメインを Public Hosted Zone で作成しておく必要があります。(参考:AWS ドキュメント - パブリックホストゾーンの作成)
3. 認証基盤 (Okta)
Harmonix on AWS では、ユーザー認証に Okta を利用します。もし、Okta のアカウントがない場合は作成しておいてください。本チュートリアルにおいては無料で利用できる Okta Developer Edition のアカウントで問題ありません。
なお、実際の開発者ポータルの構築では Okta 以外の 認証プロバイダーに変更することも可能です。こちら をご参照ください。
ローカル環境のセットアップ
Harmonix を AWS にデプロイするには、Unix ベースの環境 (Linux, MacOS, he Windows Subsystem for Linux) が必要です。また、以下のソフトウェアをその環境にインストールしておく必要もあります。
ツール | 説明 |
---|---|
Node.js (v18.20 以上推奨) | AWS CDK での Backstage 環境デプロイなど |
Yarn | Backstage 自体のビルドなど |
AWS CLI | Harmonix で利用する AWS リソースの操作 |
AWS CDK | AWS インフラの IaC ツール |
Docker | Backstage のコンテナイメージをビルド、Amazon ECR に Push |
Git | Backstage テンプレートの Push、アプリケーション開発の体験 |
make, jq, rsync, Python (3.12 推奨) | Harmonix デプロイスクリプト実行用 |
最新の情報については インストールガイド も併せてご参照ください。
この記事では、参考までに Visual Studio Code で Harmonix on AWS をデプロイするための Dev Container の設定をご紹介します。本記事の内容は、macOS 上の Visual Studio Code で、以下の Dev Container の設定内容で実施したものになります。
Dev Container 設定例
ディレクトリ構成例
.devcontainer/
+ compose.yaml
+ Dockerfile
+ devcontainer.json
各ファイルの設定例
# compose.yaml
services:
main:
build:
context: .
dockerfile: ./Dockerfile
init: true
command: sleep infinity
# Dockerfile
FROM public.ecr.aws/ubuntu/ubuntu:24.04
RUN apt update \
&& apt install -y rsync jq
# devcontainer.json
{
"name": "HarmonixDev",
"workspaceFolder": "/workspace",
"dockerComposeFile": ["./compose.yaml"],
"service": "main",
"runServices": [],
"features": {
"ghcr.io/devcontainers/features/git:1": {},
"ghcr.io/devcontainers/features/aws-cli:1": {},
"ghcr.io/devcontainers/features/docker-in-docker:2": {},
"ghcr.io/devcontainers/features/python:1": {},
"ghcr.io/devcontainers/features/node:1": {},
"ghcr.io/devcontainers-extra/features/aws-cdk:2": {}
},
"remoteEnv": {
"AWS_CONFIG_FILE": "/.aws/config",
"AWS_SHARED_CREDENTIALS_FILE": "/.aws/credentials"
},
"mounts": [
"source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind,consistency=delegated",
"source=${localEnv:HOME}/.aws,target=/.aws,type=bind"
]
}
セットアップ全体像
準備が整ったら、次のような流れで Harmonix on AWS を展開していきます。
- リポジトリをクローン
- 環境変数ファイル (.env) を作成・編集
- Harmonix に用意されている Makefile を実行。以下のようなリソースが AWS 上にセットアップされる
- Amazon ECS (Fargate) 上に Backstage がデプロイされる
- GitLab が Amazon EC2 にデプロイされる
- 様々な認証情報や設定情報が AWS Secrets Manager や AWS Systems Manager Parameter Store に保存される
- Backstage、GitLab の ドメイン名が Route 53 で設定される
- 設定されたドメイン経由で開発者ポータルにアクセスして動作確認
4. Harmonix on AWS ハンズオン
ここからは、実際に Harmonix on AWS をデプロイして、開発者ポータルを立ち上げる手順を紹介します。
4-1. リポジトリのクローンと初期設定
まず、Harmonix on AWS の公式リポジトリをクローンします。Harmonix on AWS のソースコードは、以下の GitHub リポジトリで公開されています。
$ git clone https://github.com/awslabs/harmonix.git
$ cd harmonix
次に、環境変数ファイルを準備します。テンプレートが用意されているので、以下のコマンドでコピーして使用してください。
$ cp config/sample.env config/.env
作成した config/.env ファイルをエディタで開き、次の項目を適切に設定してください。
# --- BEGIN CONFIGURATIONS NEEDED BEFORE EXECUTING THE PLATFORM IaC ---------
# Harmonix の Backstage を実際にデプロイする AWS アカウント IDを設定します
AWS_ACCOUNT_ID="000000000000"
# 適当な名前を設定します。Harmonix が作成する AWS リソースのリソース名に付記されます。
# リソース名の長さ上の制限を回避するために短い文字列します
APP_NAME="hmx"
# Harmonix (Backstage や GitLab) をデプロイする先のリージョン
AWS_DEFAULT_REGION=us-west-2
# EC2 でインストールされる GitLab のバージョン。そのままにしておきます
# なお、コメントアウトすると最新版が利用されます
GITLAB_VERSION=17.10.3
# 未設定にしてください
AUTOMATION_KEY=""
# Okta 関連の情報が保存される Secret Manager のリソース名です。
# 英字のみの任意の文字列を設定します。ハイフンは入れないでください
OKTA_SECRET_NAME="hmxoktasec"
# あらかじめ作成しておいた、Route 53 パブリックホスティッドゾーンを入力してください
R53_HOSTED_ZONE_NAME="mycompany.com"
# Backstage へアクセスできるIPのCIDR レンジを設定します。
# ご自身の IP は https://checkip.amazonaws.com/ で取得できます。
ALLOWED_IPS="xx.xx.xx.xx/32"
# Okta 関連の情報は、以下の詳細をご確認ください
OKTA_API_TOKEN=
OKTA_AUDIENCE=
OKTA_AUTH_SERVER_ID=
OKTA_CLIENT_ID=
OKTA_CLIENT_SECRET=
OKTA_IDP=
#Backstage の GitHub 統合を有効化します。GitHub へアクセスし、以下から Personal Access Token を取得してください
# https://github.com/settings/personal-access-tokens
GITHUB_TOKEN="TODO"
# --- END CONFIGURATIONS NEEDED BEFORE EXECUTING THE PLATFORM IaC -----------
...
# Harmonix で構築される Gitlab のドメイン名です。git.<R53_HOSTED_ZONE_NAME の値> を設定します
# 例: git.mycompany.com
GITLAB_HOSTNAME="git.<R53_HOSTED_ZONE_NAME の値>"
GITLAB_URL="https://git.<R53_HOSTED_ZONE_NAME の値>"
Okta の設定
本チュートリアルでは、ポータルサイトへアクセスするための認証に Harmonix のデフォルトである Okta を利用します。Okta の Developer Potal にログインし、以下の情報を取得、生成して config/.env に設定します。
以下の項目は、ダブルクォートを利用せず、値のみを設定してください。(例: OKTA_API_TOKEN=xxxxxx)
- OKTA_API_TOKEN
Okta のユーザー情報を Backstage で利用できるようにする Plugin で設定される API Token です。「Security → API」メニューから Token を作成 して設定します - OKTA_AUDIENCE
Okta のドメイン名を設定します。Okta の Developer ポータルに表示される dev-xxx.okta.com という形式の文字列です。https://dev-xxx.okta.com という形式で設定します - OKTA_CLIENT_ID, OKTA_CLIENT_SECRET
Backstage のドキュメント を参考に、Okta のポータルから Application を作成し、Client ID と Client Secret を設定します - OKTA_AUTH_SERVER_ID, OKTA_IDP
未入力のままとします
4-2. インフラリソースのデプロイ
環境設定が完了したら、Harmonix に付属する Makefile を利用して、 make コマンドで Harmonix をデプロイします。
$ make install
...
Updating the ECS service to start 2 tasks
Updating the desired count of the backstage service to 2
Attempting to set backstage service desired count to 2...
Update Succeeded
make[1]: Leaving directory '/workspace'
Installation complete and the application is starting!
Visit the application at https://(設定した独自ドメイン)
上記のコマンドは、AWS CDK を使ってインフラリソースをデプロイします。
AWS CDK (Cloud Development Kit) は、プログラムコード (TypeScript、Python など) で AWS インフラを定義し、コマンドひとつで AWS リソースを自動作成できる IaC ツールです。Harmonix on AWS でも、インフラ構成をコード化して迅速にデプロイできるようになっています。
Harmonix の Makefile は、AWS CDK により以下のようなリソースを作成します。
- Backstage をホストする Amazon ECS のクラスター
- GitLab をホストする Amazon EC2 のインスタンス
- 各種設定情報やパスワードなどを保存する AWS Secrets Manager や AWS Systems Manager Parameter Store リソース
- Route 53 を設定し、Backstage や GitLab の DNS 名を設定
デプロイは、環境やリージョンにもよりますが、おおよそ 20 ~ 30 分かかる場合があります。
4-3. 開発者ポータルへのアクセス
デプロイが完了すると、エンドポイント URL が出力されます。その URL にブラウザでアクセスしてください。
https://(設定した独自ドメイン)
最初に Okta の認証画面が表示されるので、事前に設定した Okta アカウントでログインします。ログイン後、Backstage の開発者ポータルにアクセスできます。ポータル画面では以下の機能を利用できます。
- AWS リソーステンプレートの一覧表示
- テンプレートからのリソース作成
- プロジェクトやアプリケーションの管理
これで、開発者向けポータルのセットアップが完了しました !
5. セルフサービス体験
Harmonix on AWS の開発者ポータル (Backstage) が立ち上がったら、いよいよセルフサービスでアプリケーションを作成する体験をしてみましょう。
この章では、Harmonix のチュートリアル を実施し、アプリケーション開発者が Node.js アプリケーションを Amazon ECS にデプロイする流れを体験します。
5-1. ポータルにアクセスする
ブラウザで、設定した独自ドメインの URL にアクセスします。
https://(設定したドメイン)
5-2. Harmonix on AWS のモデルを理解する
Harmonix on AWS では、AWS 環境と、そこにデプロイされるアプリケーションを、以下のようにモデル化しています。
AWS Environment Provider
Environment Provider は、実際にデプロイされる環境を表す Entity です。Provider で表される環境は相互に排他的で、以下のように、単一アカウント、単一リージョン、かつ単独 VPC 、単独 ECS クラスターが含まれることが一般的です。この Provider が作成されると、GitLab で IaC が実行され AWS 上に環境が作成されます。
AWS Environment
AWS Environment は、Environment Provider で表される環境に意味づけを行う Entity です。「この Environment Provider の環境は dev 環境で、デプロイに承認は不要」のような設定を行います。
Application (Component)
Application は、複数の AWS Environment を持つソフトウェアコンポーネントです。以下のような構成になっていて、このコンポーネントが作成されると GitLab で IaC が実行され、所有する複数の AWS Environment へのデプロイが実行されます。
5-3. AWS Environment を作成する
上記の概念に沿って、開発者がアプリケーションを Harmonix で作成するには、まず、アプリケーションをデプロイする先の「AWS Environment Provider」と「AWS Environment」を作成する必要があります。
この作業は、多くのケースでプラットフォームチームが実施します。
ここでは、Amazon ECS のクラスターを持つ「AWS Environment Provider」を作成してみましょう。
チュートリアル を参考に、図の通り値を入力してください。
「Environment role arn」は、Backstage から AWS インフラストラクチャーを作成するために使用する IAM Role です。ここに設定する値は、make install 実行時にサンプルのロールが作成されています。arn:aws:iam::(AWS Account ID):role/opa-envprovisioning-role という値を設定してください。
「CREATE」を実行すると、ECS クラスターを含む環境が AWS に作成されます。「OPEN IN CATALOG」リンクからダッシュボードに移動し、CI/CD タブで環境が作成されるまで待機します。
チュートリアル を参考に、以下の通り入力します。上記で作成した AWS Environment Provider が Development 環境であり、承認が不要であることなどを設定しています。
5-4. アプリケーションを作成する
では、作成した「AWS Environment」にアプリケーションをデプロイしましょう。これは、アプリケーション開発者が実行するステップです。
ここも、チュートリアル を参考に、図のように値を入力します。
「CREATE」を選択してコンポーネントを作成すると、「OPEN IN CATALOG」から図のようなアプリケーションのダッシュボードを確認できます。
「CI/CD」タブから 2 つのパイプラインが完了するのを待機します。一つはコンテナイメージのビルド、もう一つはコンテナイメージを ECS にデプロイするパイプラインです。
5-5. アプリケーションを更新する
続いて、アプリケーション開発者として、デプロイしたアプリケーションを更新してみましょう。
上記の CLONE URL より git の clone コマンドをコピーして、実行します。
$ git clone https://oauth2:glpat-xxx@git.xx.com/aws-app/demo-app.git
ソースコードを編集します。
// src/index.js
const express = require('express');
const app = express();
const port = 8080 || '??port??';
app.get('/', (req, res) => {
res.send('Hello demo-app 2!'); // 編集する
})
app.listen(port, () => {
console.log(`Example app listening on port ${port}`)
})
コードをコミットして push します。
$ git add src/index.ts
$ git commit -m "update index.js"
$ git push
開発用としてビルドされたコンテナイメージは latest タグがつけられています。新しく最新のイメージでサービスを起動し直すため、タスクを終了し、再度起動します。
Overview タブの「Application State」から、「STOP TASK」 → 「START TASK」と起動すると、アプリケーションの変更が反映されます。
このように、アプリケーション開発者は、AWS のマネージメントコンソールで複雑な設定をすることなく、開発に必要なリソースへポータルからアクセスできるようになっています。
6. クリーンアップ
デプロイしたアプリケーションの削除
AWS CloudFormation のコンソールから以下の二つの Stack を順番に削除します
- demo-app-ecs-resources-ecs-dev-provider
- ECS-ENV-ecsdev-ecs-dev-provider-Stack
Harmonix on AWS の削除
make install を実行した環境から、以下の二つのコマンドを実行します。
$ make destroy-platform
. ./build-script/destroy-platform.sh
Are you sure you want to delete: OPAStack (y/n)? y
OPAStack (opa-platform): destroying... [1/1]
...
OPAStack (opa-platform): destroyed
$ make delete-secrets
./build-script/secure-secrets-creation.sh "delete"
...
7. 次のステップに向けて
ここまでで、Harmonix on AWS を使い、開発者ポータルから AWS リソースをセルフサービスで作成し、アプリケーションをデプロイする体験ができました。
しかし、開発者ポータルの作成は言い換えれば開発者体験の作り込みであり、組織ごとに異なって然るべきです。Harmonix で構築した環境はあくまで開始点であり、ここから先は、さらに組織のニーズに合わせて拡張・カスタマイズしていくことになるでしょう。拡張方法については、こちらのドキュメント も併せてご参照ください。
実際、ここまで実行された方は、ご自身の組織の現状と照らして、様々な点をカスタマイズしたくなったはずです。
7-1. 組織の要件に沿ったテンプレートの作成
Harmonix ではあらかじめ、一般的なベストプラクティスが組み込まれたテンプレートを提供していますが、実際のポータル環境では、各組織に応じた独自のルールやベストプラクティスを組み込む必要があります。
- 社内セキュリティ要件に対応した IAM ロール設計
- 社内標準 CI/CD ツールチェインへの接続 (例 : GitHub Actions、CodePipeline)
- ネーミングポリシーに沿ったリソース作成
- Kubernetes クラスターへのデプロイ
- モニタリング・アラート設定 (Amazon CloudWatch, Datadog 連携など)
7-2. 開発者ポータルを変更、拡張する
Harmonix で利用されている Backstage も、組織ごとに拡張して独自のポータルを作ることを意図したツールです。そのために、数多くのプラグインや拡張ポイントが用意されています。また、独自プラグインを開発して、社内専用機能 (例 : オンボーディングサポート、コスト可視化など) を追加することもできます。代表的な例として以下のような変更、拡張が考えられます。
- 組織で利用している認証プロバイダーを利用する
- 組織で開発者が参照する必要があるリンク集やサービスアップデート情報の集約
- Kubernetes クラスターの可視化
- API ドキュメント自動生成 (Open API 連携)
- セキュリティスキャンレポート表示
7-3. プラットフォームで利用しているソフトウェアのバージョンアップ対応
Harmonix on AWS や Backstage は、今後も継続的にアップデートされます。
定期的にリリースされるアップデート情報をウォッチし、セキュリティアップデートや新機能を積極的に取り込むことも、プラットフォーム運営には重要です。
8. まとめ
本記事では、プラットフォームエンジニアリングの実践方法として、Harmonix on AWS を活用した開発者ポータルの構築と運用について解説してきました。
開発者が AWS リソースを効率的に利用するためには、組織としての知見やベストプラクティスを共有可能な形で提供することが重要です。Harmonix on AWS は、Backstage というオープンソースプロジェクトをベースとしながら、AWS サービスとの緊密な統合を実現し、エンタープライズでの利用を見据えた機能を提供しています。
Harmonix on AWS では、make コマンドでポータルを構築できるので、開発者ポータルのある環境を簡単に体験できます。本記事でも、ポータルにより開発者が直感的なウィザード形式で AWS リソースを作成し、すぐにアプリケーション開発に着手することができることをご紹介しました。
しかし、これはあくまでも開始点に過ぎません。プラットフォームエンジニアリングは、実際には組織の開発者体験への投資であり、今回構築したようなプラットフォームも継続的に投資していく必要があります。自社の要件に合わせてカスタマイズし、組織固有のベストプラクティスを組み込んでいく、またセキュリティ要件への対応、CI/CD パイプラインの統合、モニタリング設定など、組織の成熟度に応じて段階的に機能を拡張していくことで、より強力な開発者プラットフォームへと進化させることができます。
プラットフォームエンジニアリングは、単なる技術的な取り組みではなく、組織全体の開発生産性と品質を向上させるための戦略的な投資です。Harmonix on AWS は、そのような取り組みを始めるための具体的かつ実践的な第一歩を提供しています。
筆者プロフィール

林 政利 (@literalice)
アマゾン ウェブ サービス ジャパン合同会社
コンテナスペシャリスト ソリューションアーキテクト
フリーランスや Web 系企業で業務システムや Web サービスの開発、インフラ運用に従事。近年はベンダーでコンテナ技術の普及に努めており、現在、AWS Japan で Amazon ECS や Amazon EKS でのコンテナ運用や開発プロセス構築を中心にソリューションアーキテクトとして活動中。
AWS を無料でお試しいただけます