はじめに
「プラットフォームエンジニアリング」という言葉は様々な IT 組織に浸透し始めており、AWS を利用する場合においても開発者向けのプラットフォーム、いわゆる「内部開発者プラットフォーム」を構築する取り組みが多くの組織で注目されています。しかし、実際にゼロから開発者ポータルを作り、開発者がセルフサービスで AWS リソースを利用できる環境を整えるのは簡単なことではありません。
AWS は、多くのサービスや機能、そしてそれぞれに適用すべきベストプラクティスを提供しています。AWS の様々なサービスがよく「ビルディングブロック」として紹介されるように、これらのサービスは組み合わせることで多くの組織、多くのワークロードにマッチする膨大な設計パターンを生み出せる仕組みになっています。
クラウドジャーニーの初期段階や、組織が小規模なうちは、少数のクラウドエキスパートが深い知識をもとに適切なサービスを選び、ブロックを組み立てていきます。しかし、組織が成長するにつれて、「どのブロックをどのように組み合わせるか」という知識や経験を組織全体に共有し、再利用可能にする必要が出てきます。
このとき、エキスパートの知見をドキュメントとしてまとめた Wiki ページという形もあれば、より高度な形として、開発者がワンクリックでユースケースに応じた AWS リソースを立ち上げられるテンプレートカタログが整備された、開発者ポータルという仕組みを作る場合もあります。
この記事では、AWS が提供するオープンソースソリューション、Harmonix on AWS を使い、開発者がすばやく、安全に AWS リソースを利用できるプラットフォームを作る方法を、ステップバイステップで紹介していきます。
ご注意
本記事で紹介する AWS サービスを起動する際には、料金がかかります。builders.flash メールメンバー特典の、クラウドレシピ向けクレジットコードプレゼントの入手をお勧めします。
builders.flash メールメンバー登録
builders.flash メールメンバー登録で、毎月の最新アップデート情報とともに、AWS を無料でお試しいただけるクレジットコードを受け取ることができます。
1. プラットフォームエンジニアリングとは ?
プラットフォームエンジニアリングは、近年、開発者体験を向上させる取り組みとして注目を集めているアプローチです。
単なる技術的なプラクティスではなく、DevOps、チーム構成、開発文化、ガバナンスなど、組織運営全体に関わる幅広い領域を横断するテーマでもあります。開発者がよりスムーズに、自律的にプロダクト開発に集中できるよう、共通の基盤やサービスを整備することがプラットフォームエンジニアリングの中心的な目的です。
プラットフォームエンジニアリングの全体像や実践例については、AWS でも過去にウェビナーを実施していますので、そのアーカイブも併せてぜひ、ご参照ください。
【開催報告】プラットフォームエンジニアリングって何？〜基本から AWS での実現方法について〜
本記事は、この広範なプラットフォームエンジニアリングというテーマの中でも、シンプルに「開発者ポータルを立ち上げ、セルフサービスで AWS リソースを利用できる体験を作る」ことにフォーカスします。
2. Harmonix on AWSとは ?
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, the Windows Subsystem for Linux) が必要です。また、以下のソフトウェアをその環境にインストールしておく必要もあります。
参考の情報
最新の情報については インストールガイド も併せてご参照ください。
この記事では、参考までに 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 infinityDockerfile
# Dockerfile
FROM public.ecr.aws/ubuntu/ubuntu:24.04
RUN apt update \
&& apt install -y rsync jq Dev Container
JSON
セットアップ全体像
準備が整ったら、次のような流れで Harmonix on AWS を展開していきます。
- リポジトリをクローン
- 環境変数ファイル (.env) を作成・編集
- Harmonix に用意されている Makefile を実行。以下のようなリソースが AWS 上にセットアップされる
1. Amazon ECS (Fargate) 上に Backstage がデプロイされる
2. GitLab が Amazon EC2 にデプロイされる
3. 様々な認証情報や設定情報が AWS Secrets Manager や AWS Systems Manager Parameter Store に保存される
4. 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/.envconfig/.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 Portal にログインし、以下の情報を取得、生成して 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 分かかる場合があります。
5. セルフサービス体験
Harmonix on AWS の開発者ポータル (Backstage) が立ち上がったら、いよいよセルフサービスでアプリケーションを作成する体験をしてみましょう。
この章では、Harmonix のチュートリアル を実施し、アプリケーション開発者が Node.js アプリケーションを Amazon ECS にデプロイする流れを体験します。
5-1. ポータルにアクセスする
ブラウザで、設定した独自ドメインの URL にアクセスします。
https://(設定したドメイン)開発者ポータルにログイン
Okta 認証を経て、Backstage ベースの開発者ポータルにログインします。
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」を作成してみましょう。
コンポーネントを作成
まず、メニューの「Create...」を選択し、さらに「AWS ECS Fargate Environment Provider」の「CHOOSE」を押下します。
値を設定
チュートリアル を参考に、図の通り値を入力してください。
「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 の Entity 作成
続けて、AWS Environment の Entity を作成します。
各種設定
チュートリアル を参考に、こちらの通り入力します。上記で作成した AWS Environment Provider が Development 環境であり、承認が不要であることなどを設定しています。
5-4. アプリケーションを作成する
では、作成した「AWS Environment」にアプリケーションをデプロイしましょう。これは、アプリケーション開発者が実行するステップです。
Node.js ウェブアプリケーションを選択
「Create...」から「ECS - Node.js Express Web App」を選択します。
値を入力
ここも、チュートリアル を参考に、図のように値を入力します。
2 つのパイプライン完了を待つ
「CREATE」を選択してコンポーネントを作成すると、「OPEN IN CATALOG」から図のようなアプリケーションのダッシュボードを確認できます。
「CI/CD」タブから 2 つのパイプラインが完了するのを待機します。一つはコンテナイメージのビルド、もう一つはコンテナイメージを ECS にデプロイするパイプラインです。
デプロイ完了
デプロイが完了すると、ダッシュボードから様々なアプリケーションの情報や、オペレーションのためのボタンなどが表示されるようになります。
アプリケーションを開始
アプリケーション開発者は、「START TASK」を実行することで、デプロイしたアプリケーションを開始できます。
アプリケーションにアクセス
アプリケーションが正常に実行されたら、「Links」にある「Go to app」からアプリケーションにアクセスできます。
アプリケーションログ確認
また、APP LOGS タブから、アプリケーションのログを表示できます。
5-5. アプリケーションを更新する
続いて、アプリケーション開発者として、デプロイしたアプリケーションを更新してみましょう。
コードリポジトリの確認
開発者に払い出されたコードリポジトリは以下の通り demo-app コンポーネントのページに表示されています。
git の clone コマンドをコピー
上記の 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
コードをコミットして push します。
$ git add src/index.ts
$ git commit -m "update index.js"
$ git pushコンテナイメージビルド完了
CI/CD タブから、CI が実行され、コンテナイメージが再度ビルドされたことを確認できます。
アプリケーションの変更完了
開発用としてビルドされたコンテナイメージは 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 を実行した環境から、以下の二つのコマンドを実行します。
1) destroy-platform
$ 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): destroyed2) delete-secrets
$ make delete-secrets
./build-script/secure-secrets-creation.sh "delete"
...7. 次のステップに向けて
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 でのコンテナ運用や開発プロセス構築を中心にソリューションアーキテクトとして活動中。
