
Backstage ã WSL2 ã§åãããŠæ¥åå°å ¥ãæ€èšããŠã¿ã
ã¯ããã«
ã瀟å ã®éçºè ããŒã¿ã«ãæŽåãããããšæã£ãããšã¯ãªãã ãããã
ãã€ã¯ããµãŒãã¹ãå¢ããã«ã€ããŠãã©ãã«äœããããããããªããªããããã¥ã¡ã³ã㯠Confluenceãã³ãŒã㯠GitHubãã€ã³ãã©ã¯ Terraform ãš AWS ã³ã³ãœãŒã«ã«æ£åšããŠããŠãæ°ããã¡ã³ããŒããªã³ããŒãã£ã³ã°ãããã³ã«åãããšãå£é ã§èª¬æããŠããââãããªç¶æ³ã解決ããããŒã«ãšããŠãSpotify ã OSS ãšããŠå ¬éãã Backstage ãæ€èšŒããŠã¿ãã
ãã®èšäºã§ã¯ãWSL2 ç°å¢ã§ã®ã»ããã¢ãããããå®éã®æ¥åãŠãŒã¹ã±ãŒã¹ïŒTerraform ã¢ãžã¥ãŒã«ç®¡çã»Scaffolder ã«ãããªããžããªèªåçæã»TechDocsïŒã®æ€èšŒãéããŠåŸãããããã€ã³ããšç¥èŠããŸãšããã
Backstage ãšã¯
Backstage 㯠Spotify ãéçºã»OSS åããéçºè ããŒã¿ã«ãã¬ãŒã ã¯ãŒã¯ãã³ã³ããŒãã³ããšããŠã®äžæ žæ©èœã¯ä»¥äžã®4ã€ã
äžèšã§ãããšã瀟å ã®æè¡è³ç£ãæ€çŽ¢ã»é²èЧã»äœæã§ããããŒã¿ã«ãã§ãå€§èŠæš¡ãªçµç¹ã»ã©å¹æãåºãããã
ç°å¢æ§ç¯
åæ
WSL2 (Ubuntu)
Node.js v22 以äž
npm 10 以äžïŒNode.js ã«å梱ïŒ
確èªã³ãã³ãïŒ
node --version # v22.0.0 以äž
npm --version # 10.0.0 以äžStep 1: éçºç°å¢ã®ã»ããã¢ãã
1.1 Node.js ã®ã€ã³ã¹ããŒã«
Ubuntu ã« Node.js ãã€ã³ã¹ããŒã«ããæ¹æ³ã¯è€æ°ãããçŽæ¥ã€ã³ã¹ããŒã«ããããããŒãžã§ã³ç®¡çããŒã«ïŒnvmïŒã䜿ãã
æ¹æ³ A: çŽæ¥ã€ã³ã¹ããŒã«ïŒç°¡åïŒ
# Node.js ã®ææ° LTS ãã€ã³ã¹ããŒã«
curl -sL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejsæ¹æ³ B: nvm ã§è€æ°ããŒãžã§ã³ç®¡çïŒæšå¥šïŒ
# nvm ãã€ã³ã¹ããŒã«
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
# Node.js v22 ãã€ã³ã¹ããŒã«
nvm install 22
nvm use 221.2 Yarn ã®ã»ããã¢ãã
Backstage 㯠Yarn v4 ãæšå¥šããŠãããNode.js ã«ä»å±ãã `corepack` ã§ç®¡çããã
# corepack ãæå¹åïŒNode v16.13+ ã«å«ãŸããïŒ
corepack enable
# ããŒãžã§ã³ç¢ºèª
yarn --version # yarn 4.x.x ãåºåãããããšcorepack 㯠Node.js ã®å ¬åŒããã±ãŒãžãããŒãžã£ãŒããŒãžã§ã³ç®¡çããŒã«ã`package.json` ã® `packageManager` ãã£ãŒã«ãã§æå®ãããããŒãžã§ã³ãèªåçã«äœ¿ãããã
Step 2: Backstage ã¢ããªã®äœæ
# Backstage ã¢ããªãäœæ
npx @backstage/create-app@latestããã³ãããåºããããããžã§ã¯ãåãå ¥åãããããã§ã¯ `my-backstage` ãšããïŒ
? Enter the app name » my-backstage
? What would you like to do » Create a new Backstage Appäœæå®äºåŸã¯ä»¥äžã®ãã£ã¬ã¯ããªæ§æãçæãããïŒ
my-backstage/
âââ app/ # ããã³ããšã³ãïŒReactïŒ
âââ packages/
â âââ backend/ # ããã¯ãšã³ãïŒExpressïŒ
â âââ backend-common/ # å
±éãŠãŒãã£ãªãã£
âââ app-config.yaml # ã¢ããªèšå®ïŒéèŠïŒ
âââ app-config.production.yaml
âââ docker-compose.yml # PostgreSQL çšïŒäžèŠãªãåé€å¯ïŒ
âââ package.json
âââ yarn.lock
âââ README.mdcreate-app 㯠Backstage ã®å ¬åŒãã³ãã¬ãŒããã boilerplate ãçæããã³ãã³ããæ¯åææ°ããŒãžã§ã³ã§çæããããããæ¢åãããžã§ã¯ãã®ã¢ããã°ã¬ãŒãã§ã¯ãªãåžžã«æ°èŠäœæãšãªãã
Step 3: ååèµ·å
cd my-backstage
# ååèµ·åïŒåæåå«ãã®ã§ 3ã5 åãããïŒ
yarn startååèµ·åæã®åºåäŸïŒ
[0] info starting app
[0] info listening on :3000
[0] info Database started successfullyStep 4: ãã©ãŠã¶ã§ç¢ºèª
`http://localhost:3000` ã«ã¢ã¯ã»ã¹ããã以äžã®ç»é¢ã衚瀺ãããã°æåïŒ
å·Šäžã« Backstage ããŽ
ç»é¢äžå€®ã«ãEnter as Guestããã¿ã³
äžéšã«æ€çŽ¢ããŒãå·Šãµã€ãããŒã«ããã²ãŒã·ã§ã³ã¡ãã¥ãŒ
ãEnter as Guestããã¯ãªãã¯ãããšãåæç¶æ ã®ã«ã¿ãã°ã衚瀺ãããã
ããããã€ã³ãâ : `yarn dev` ã¯ååšããªã
Backstage ã®èµ·åã¹ã¯ãªãã㯠`yarn start`ãäžè¬ç㪠React / Node.js éçºã§ã¯ `yarn dev` ã䜿ãããããšãå€ãã®ã§æ³šæã
yarn start # â
æ£ãã
yarn dev # â ãšã©ãŒ: ã¹ã¯ãªãããèŠã€ãããŸããããããã€ã³ãâ¡: SQLite ã®èšå®ãå€ãã£ãŠãã
ããã©ã«ãã§ã¯ SQLite ã䜿ããããæ°ãã BackstageïŒv1.x 以éïŒã§ã¯æ¥ç¶æ¹æ³ãå€ãã£ãŠããã
# NGïŒå€ãæžãæ¹ â v0.x ã§å»æ¢ïŒ
database:
client: better-sqlite3
connection: './backstage.db'
# OKïŒçŸåšã®æžãæ¹ïŒ
database:
client: better-sqlite3
connection:
directory: './db'ããã©ã«ãã® `app-config.yaml` ã§æ¢ã«æ£ããèšå®ãããŠããããã«ã¹ã¿ã èšå®ããå Žåã¯ãã®åœ¢åŒãå®ãå¿ èŠãããã
ãã®èšå®ãééã£ãŠãããš DB åæåã倱æãã以äžã®çç¶ãåºãïŒ
â ãã¹ãŠã®ããŒãžã§ 401 Unauthorized ãè¿ããã
â ãèªèšŒãæ£ããèšå®ãããŠããªãããšæã蟌ã
â å®ã¯èªèšŒã§ã¯ãªã DB æ¥ç¶ãšã©ãŒ
DB ã®åæåç¶æ ã確èªããã«ã¯ä»¥äžãå®è¡ããïŒ
# db ãã£ã¬ã¯ããªãšãã®ãã¡ã€ã«ãååšããã確èª
ls -la db/ããããã€ã³ãâ¢: Docker ç°å¢ã§ã®ã¡ã¢ãªäžè¶³ãšã©ãŒ
ç¹ã« WSL2 ã§è€æ°ã® Docker ã³ã³ãããèµ·åããŠããå Žåãã¡ã¢ãªãè¶³ããªããªãããšãããã
Error: Cannot find module '@backstage/cli'ãããã¯
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memoryå¯ŸåŠæ³ïŒ
1.WSL2 ã®ã¡ã¢ãªäžéã確èªã»å¢å
# WSL2 ã®çŸåšã®ã¡ã¢ãªäœ¿çšé確èª
free -h
# Windows PowerShellïŒç®¡çè
ïŒã§å®è¡
# wsl --shutdown
# ãã®åŸãC:\Users\<YourName>\.wslconfig ãã¡ã€ã«ãç·šé
[wsl2]
memory=8GB
processors=42.yarn install ãã¹ãããã㊠dependencies ãã€ã³ã¹ããŒã«
ããããã€ã³ãâ£: ããŒã 3000 ãæ¢ã«äœ¿ãããŠãã
æ¢åã®ã¢ããªã±ãŒã·ã§ã³ã `:3000` ã䜿ã£ãŠããå Žåãèµ·åã«å€±æããã
# ããŒã 3000 ã®å©çšç¶æ³ç¢ºèª
lsof -i :3000
# ç°ãªãããŒãã§èµ·åããå Žå
BROWSER=none PORT=3001 yarn startSoftware CatalogïŒTerraform ã¢ãžã¥ãŒã«ã管çãã
ã«ã¿ãã°ã®ç»é²ã¯ `catalog-info.yaml` ã1ãã¡ã€ã«æžãã ãã
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: terraform-module-vpc
description: "AWS VPC ããããžã§ãã³ã°çš Terraform ã¢ãžã¥ãŒã«"
tags: [terraform, aws, networking]
annotations:
backstage.io/techdocs-ref: dir:.
spec:
type: library
lifecycle: production
owner: group:default/infra-team
system: aws-service-catalog
dependsOn:
- component:terraform-module-eks`dependsOn` ã䜿ããšã³ã³ããŒãã³ãéã®äŸåé¢ä¿ãã°ã©ããšããŠå¯èŠåããããããã®ã¢ãžã¥ãŒã«ã¯äœã«äŸåããŠããããããã®ã¢ãžã¥ãŒã«ã䜿ã£ãŠããã®ã¯äœããã UI äžã§äžç®ã§ãããã
Terraform ã®ã¢ãžã¥ãŒã«çŸ€ã System + Component ã®éå±€ã§ç®¡çãããšä»¥äžã®ãããªæ§æã«ãªã:
aws-service-catalog (System)
âââ terraform-module-vpc (production)
âââ terraform-module-ecs-fargate (experimental) â vpc ã«äŸå
âââ terraform-module-rds-aurora (experimental) â vpc ã«äŸåScaffolderïŒãªããžããªé圢ãèªåçæãã
Scaffolder ã¯ããã©ãŒã å ¥å â ãªããžããªçæ â ã«ã¿ãã°èªåç»é²ããäžæ°é貫ã§å®è¡ã§ããæ©èœã
ãã³ãã¬ãŒã㯠`template.yaml` ãš `skeleton/` ãã£ã¬ã¯ããªã§æ§æãããã
# template.yamlïŒæç²ïŒ
steps:
- id: fetch-base
action: fetch:template # skeleton/ ã倿°å±éããŠãã¡ã€ã«çæ
input:
url: ./skeleton
values:
moduleName: ${{ parameters.moduleName }}
repoUrl: ${{ parameters.repoUrl }} # â values ã«æç€ºçã«æž¡ã
- id: publish
action: publish:github # GitHub ã«ãªããžããªãäœæã㊠push
- id: register
action: catalog:register # ã«ã¿ãã°ã«èªåç»é²ããããã€ã³ãâ€: `parameters` ãš `values` ã¯å¥ç©
`skeleton/` å ã®ãã³ãã¬ãŒããã¡ã€ã«ã§äœ¿ãã倿°ã¯ `values.xxx` ã®ã¿ã`parameters.xxx` ã¯åç §ã§ããªãã
# skeleton/catalog-info.yamlïŒNGïŒ
github.com/project-slug: ${{ (parameters.repoUrl | parseRepoUrl).owner }}/...
# skeleton/catalog-info.yamlïŒOKïŒ
github.com/project-slug: ${{ (values.repoUrl | parseRepoUrl).owner }}/...`fetch-base` ã¹ãããã® `values` ã«æç€ºçã«æž¡ãå¿ èŠãããããšã©ãŒã¡ãã»ãŒãžã `No matching integration configuration for host undefined` ãšåºãããåå ã«æ°ã¥ãã«ããã
ããããã€ã³ãâ¥: `owner` ãééãããšæå³ããªãå Žæã«ãªããžããªãäœããã
`publish:github` ã¯æå®ãã `owner` ãžã®ã¢ã¯ã»ã¹æš©ããªãå Žåããšã©ãŒã«ãªããããŒã¯ã³ææè ã®ã¢ã«ãŠã³ãã«ãã©ãŒã«ããã¯ããŠãªããžããªãäœæããã
æ¥åã§ã¯ `allowedOwners` ã§å ¥åå€ãå¶éããããšã§é²ãã:
ui:options:
allowedHosts:
- github.com
allowedOwners:
- my-org # äŒç€Ÿã® Org åã®ã¿éžæå¯èœã«ããTechDocsïŒããã¥ã¡ã³ããã³ãŒããšäžç·ã«ç®¡çãã
TechDocs ã¯ãªããžããªå ã® Markdown ã Backstage äžã§ã¬ã³ããªã³ã°ããæ©èœã`mkdocs.yml` ã眮ãã ãã§äœ¿ããã
# mkdocs.yml
site_name: my-service
docs_dir: docs
nav:
- ããŒã : index.md
plugins:
- techdocs-core# catalog-info.yaml
metadata:
annotations:
backstage.io/techdocs-ref: dir:.ããŒã«ã«ç°å¢ã§ã®èšå®
ããã©ã«ã㯠Docker ã§ãã«ãããããšãããããDocker ã䜿ããªãç°å¢ã§ã¯ä»¥äžã«å€æŽ:
# app-config.yaml
techdocs:
generator:
runIn: 'local' # Docker ã§ã¯ãªã pip ã§ã€ã³ã¹ããŒã«ãã mkdocs ã䜿ãpip3 install mkdocs-techdocs-coreæ¥åå°å ¥ã«åããŠæããããš
è¯ãã£ãç¹
Scaffolder ã®å®æåºŠãé«ã: ãã©ãŒã å ¥åãã GitHub ãªããžããªçæã»ã«ã¿ãã°ç»é²ãŸã§ UI äžã§å®çµãããæ°èŠãªããžããªäœææã®ãåœåèŠåãå®ã£ãŠããããªãããcatalog-info.yaml ãæžãã®ãå¿ãããåé¡ãæ§é çã«è§£æ±ºã§ãã
GitLab 察å¿ãã»ãŒåãèšå®ã§åã: `publish:github` â `publish:gitlab`ã`integrations.github` â `integrations.gitlab` ã«å€ããã ãã§ç§»è¡ã§ããïŒãããïŒ
TechDocs ã§ããã¥ã¡ã³ãæ£åšãé²ãã: Confluence ã Notion ã«æ£ãã°ããã¡ãªããã¥ã¡ã³ãããªããžããªã«åŒãæ»ãã
課é¡ã»æ³šæç¹
æ¬çªéçšã¯ããŒã¯ã³ç®¡çãéèŠ: å人 PAT ã䜿ãåããšæ åœè éè·æã«é£æºãæ¢ãŸããGitHub AppïŒOrg ç°å¢ïŒãŸã㯠GitLab Group Access Token ã䜿ãã¹ã
TechDocs ã®ããŒã«ã«ãã«ãã¯æ¬çªåãã§ã¯ãªã: æ¬çªç°å¢ã§ã¯ CI ã§ãã«ãã㊠S3 ãªã©ã«ä¿åãã `builder: external` æ§æãå¿ èŠ
èªèšŒãæªæŽå: ããã©ã«ãã¯ã²ã¹ããã°ã€ã³ã®ã¿ãæ¬çªå°å ¥åã« GitHub OAuth ã SAML èªèšŒã®èšå®ãå¿ èŠ
æ¥åå°å ¥ã®åªå é äœ
èªèšŒãããã€ããŒã®èšå®ïŒã²ã¹ããã°ã€ã³ã®å»æ¢ïŒ
Permissions ãã¬ãŒã ã¯ãŒã¯ïŒScaffolder ã®å®è¡æš©éå¶åŸ¡ïŒ
GitHub/GitLab DiscoveryïŒæ¢åãªããžããªã®èªåã¹ãã£ã³ç»é²ïŒ
TechDocs ã®å€éšãã«ãåïŒS3 飿ºïŒ
ãŸãšã
Backstage ã¯ã»ããã¢ããã®è€éãã¯ãããã®ã®ãäžåºŠåãããŠã¿ããšãããã¯ç¢ºãã«æ¬²ããã£ããã®ããšããæèŠããã£ããç¹ã« Scaffolder ã«ãããªããžããªèªåçæãšã«ã¿ãã°ãžã®èªåç»é²ã®æµãã¯ãããŒã ã倧ãããªãã»ã©å¹ããŠããä»çµã¿ã ãšæããã
ãããªãå šç€Ÿå°å ¥ã§ã¯ãªãããã€ããããªããžããªã§åãäœã£ãŠæ®µéçã«åºããŠããã¢ãããŒããçŸå®çããŸãã¯1ã2ããŒã ã§è©ŠããŠãããã䟿å©ã ãããšããæè§Šãäœãããšã倧äºã ãšæãã
次ã®èšäº