Backstageとは
Backstageとは元はSpotifyが開発したOSSで、オフィシャルドキュメントを引用すると、
Backstage は、開発者ポータルを構築するためのオープンプラットフォームです。一元化されたソフトウェア・カタログを搭載したBackstageは、マイクロサービスやインフラの秩序を回復し、製品チームが自律性を損なうことなく、高品質のコードを迅速に出荷することを可能にします。
とあり、開発者向けのポータルを提供してくれることが分かる。
主要な機能は以下となる。
今回はBackstageを起動し、ソフトウェアカタログの機能からKubernetesのリソースの状態を取得してみる。
検証環境
今回は以下の環境で試している。
- Backstageの動作環境：Ubuntu 20.04.6 LTS
- ソースコード置き場：GitHub
- Kubernetes：EKS
事前準備
GitHubとの連携
公式ドキュメントはこちら。
OAuthを使ってGitHubと認証してソースコードを取得する。
最初にGitHubのClient IDとClient Secretを取得する。
アカウントのSettings->Developer settings->OAuth AppsからNew OAuth Appを選択し、
以下のような感じでOAuth applicationを作成する。
IPはBackstageを起動するホストのIPとなる。IPやPortの部分は各自の環境に置き換えること。localhostで実行する場合はlocalhostにして問題ない。
以下コピペ用。
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:7007/api/auth/github/handler/frame
作成後、Client Secretを作成し、Client IDと一緒に環境変数に設定しておく。
export AUTH_GITHUB_CLIENT_ID=xxxxx
export AUTH_GITHUB_CLIENT_SECRET=xxxxx
Databaseの用意
DBなしでも利用できるが、起動し直すたびにデータが消えるので、DBは用意しておいた方がいい。
こちらの記事のdocker-compose.ymlを利用させていただき、以下のような感じで起動しておく。
docker compose up -d
無事起動したら、以下の環境変数を設定しておく。
export POSTGRES_HOST=<ホストのIPアドレス>
export POSTGRES_PORT=5432
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
なお、ここのPOSTGRES_HOSTのIPはGitHubのapplicationで指定したIPと一致させておいた方がいい。
Backstageのインストール
前提パッケージを入れる。Node.jsはv16かv18じゃないと上手く動かないっぽいので注意。
sudo apt-get update -y
sudo apt install npm -y
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - &&\
sudo apt-get install -y nodejs
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
インストールする。
npx @backstage/create-app@latest
なお、前提パッケージが不足していると以下のようなエラーでコケる。
npx: installed 70 in 6.005s
TypeError: this.breakLines(...).flat is not a function
前提パッケージが足りていれば、以下のような感じでappの名前を聞かれる。
$ npx @backstage/create-app
? Enter a name for the app [required]
ここではGetting Startedにあわせてmy-backstage-appを入力した。
この後少し待つと（自環境では5分くらい掛かった）、以下のようなメッセージが出てインストールが完了する。
🥇 Successfully created my-backstage-app
指定したappの名前でディレクトリが作成されているので、移動する。
cd my-backstage-app/
デフォルトではfrontendをlocalhost:3000で公開する。これをIPによるアクセスに変更したいため設定ファイルを変更する。設定ファイルはapp-config.yamlという名前でディレクトリ内に配置されている。以下の3箇所を変更する。
app:
baseUrl: http://10.151.195.88:3000
backend:
baseUrl: http://10.151.195.88:7007
cors:
origin: http://10.151.195.88:3000
変更後、Backstageを起動する。
yarn dev
ブラウザでbaseUrlに指定したURLにアクセスすると、以下のような画面が表示される。
一度止めて、
- GitHubの認証情報の設定
- Postgresの設定
をapp-config.yamlに追加する。
GitHubの認証情報の設定内容は以下。
auth:
environment: development
providers:
github:
development:
clientId: ${AUTH_GITHUB_CLIENT_ID}
clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
Postgresの設定内容は以下。
backend:
database:
- client: better-sqlite3
- connection: ':memory:'
+ client: pg
+ connection:
+ host: ${POSTGRES_HOST}
+ port: ${POSTGRES_PORT}
+ user: ${POSTGRES_USER}
+ password: ${POSTGRES_PASSWORD}
追記後、再度yarn devで起動し直す。
動作確認
適当なGitHubのリポジトリを作成し、それをカタログに追加してみる。
Backstage起動後、右上のCREATEをクリックし、REGISTER EXISTING COMPONENTをクリックする。
Select URLでは本来はカタログを定義したyamlのパスを指定するが、初回はそのyamlがないので、リポジトリのURLを指定しANALYZEをクリックする。
Entity Ownerはguestsが選べるのでこちらを選択し、CREATE PRをクリックすると、Pull Requestが発行されるのでMergeすると、catalog-info.yamlがpushされる。
カタログ画面に追加したカタログが表示されるようになる。
Kubernetes Pluginの動作確認
BackstageのPluginは非常に種類が豊富である。
ここではKubernetes Pluginを試してみる。
Kubernetes Pluginのインストール
オフィシャルサイトはこちら。
Pluginをインストールする。
yarn add --cwd packages/app @backstage/plugin-kubernetes
エンティティのページを修正する。
packages/app/src/components/catalog/EntityPage.tsx
をエディタで開き、以下を追加する。
import { EntityKubernetesContent } from '@backstage/plugin-kubernetes';
また、既存のserviceEntityPageに以下のように追加する。
const serviceEntityPage = (
<EntityLayout>
{/* other tabs... */}
+ <EntityLayout.Route path="/kubernetes" title="Kubernetes">
+ <EntityKubernetesContent refreshIntervalMs={30000} />
+ </EntityLayout.Route>
</EntityLayout>
);
これにより、該当するカタログがKubernetesリソースを持っている場合、以下の様にタブが表示されるようになる。
なお、パラメータのrefreshIntervalMsの意味はコンテンツの自動更新の間隔で設定しない場合は10秒になる模様。
次にバックエンド側にもPluginを追加する。
Pluginをインストールする。
yarn add --cwd packages/backend @backstage/plugin-kubernetes-backend
KubernetesのバックエンドのPluginを呼び出すファイルを作成する。
cat << EOF > ./packages/backend/src/plugins/kubernetes.ts
import { KubernetesBuilder } from '@backstage/plugin-kubernetes-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
import { CatalogClient } from '@backstage/catalog-client';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const catalogApi = new CatalogClient({ discoveryApi: env.discovery });
const { router } = await KubernetesBuilder.createBuilder({
logger: env.logger,
config: env.config,
catalogApi,
permissions: env.permissions,
}).build();
return router;
}
EOF
バックエンドのindex.tsにKubernetesプラグインを利用するよう修正する。
packages/backend/src/index.tsをエディタで開いて以下を追加する。
import kubernetes from './plugins/kubernetes';
次に同じファイルのmainの中で以下を追加する。
async function main() {
// ...
+ const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
// ...
+ apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
クラスタ情報の設定（app-config.yaml)
後ほどKubernetes Pluginを使った検証を行うために、EKSとの連携設定を入れる。
公式ドキュメントで設定方法が見つけられず、stackoverflowのこちらを参考にした。
EKSにコンテキストをあわせ、kubectl cluster-infoでクラスタのエンドポイントのURLを取得する。
$ kubectl cluster-info
Kubernetes control plane is running at https://xxxxxxxxxx.gr7.us-east-1.eks.amazonaws.com
取得したURLを使ってapp-config.yamlに設定を追記する。以下のurl、nameを自環境のものに修正する。また、環境変数AWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYを使っていない場合はexportしておく。
kubernetes:
serviceLocatorMethod:
type: 'multiTenant'
clusterLocatorMethods:
- type: 'config'
clusters:
- url: https://xxxxxxxxxx.gr7.us-east-1.eks.amazonaws.com
name: my-cluster-eks
authProvider: 'aws'
skipTLSVerify: true
skipMetricsLookup: true
auth:
environment: 'development'
providers:
aws:
development:
accessKeyId: ${AWS_ACCESS_KEY_ID}
secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
設定後、backstageを再起動する。
動作確認
先程適当なGitHubリポジトリ内に作成したcatalog-info.yamlを以下のように修正する。
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: hello-tanzu-backstage
annotations:
github.com/project-slug: imurata/hello-tanzu-backstage
+ 'backstage.io/kubernetes-label-selector': 'app=hello-tanzu-backstage'
spec:
- type: other
+ type: service
lifecycle: unknown
owner: guests
上記の設定により、labelにapp=hello-tanzu-backstageを持つリソースはカタログ上で表示されるようになる。
また、typeを変更しないとカタログ上にKubernetesのタブが出てこないので、こちらも合わせて変更する。
なお、kind: Componentの説明はこちらを参照するとよい。
修正してpushしてしばらく待つと、カタログ上のtypeがserviceに書き換わる。
deploymentリソースをコマンドで作成した場合、自動的にapp=<deployment名>でラベルが付与されるため、コマンドでリソースを作成してみる。
kubectl create deploy hello-tanzu-backstage --image nginx --replicas 3 -n demo
しばらく待つと、カタログのKUBERNETESタブの中にラベルが一致するリソースの状態が出力される。
まとめ
BackstageのデプロイからKubernetes Pluginの導入まで体験し、クラスタ内のカタログに紐づくリソースが確認できるところまで確認できた。
導入の敷居が高いので、将来的に導入が楽になることを期待したい。