Backstage란? 개념부터 설치까지

실습 절차

1. Backstage 설치
2. Github 로그인 인증 연동
3. 소스코드 수정
4. Backstage 설정
5. Backstage 접속

배경

개발 및 운영 환경은 갈수록 다양하면서 복잡해지고 있다. 규모가 조금 있는 기업에서는 다양한 팀들이 각기 다른 도구와 기술 스택을 사용하고 있기 때문에 회사 모범 사례에 대한 표준을 세우기가 어렵고, 서비스 상태 모니터링을 위한 도구가 다양하기 때문에 문제가 발생하면 이를 해결하는 과정에서도 어려움을 겪게 된다. 또한 새로운 엔지니어가 입사하면 이러한 복잡한 환경을 익히기 위해서는 많은 시간이 소요될 수밖에 없다. 

 

이러한 문제들을 해결하기 위해, Spotify는 통합된 플랫폼을 개발하였고, 그 플랫폼이 바로 Backstage이다.

 

Backstage란?

Backstage는 오픈 소스 내부 개발자 포털(IDP:Internal Developer Platform) 구축 프레임워크로 모든 서비스와 도구를 중앙에서 관리하고, 표준화된 인터페이스를 제공하여 개발자들이 효율적으로 작업할 수 있도록 하는 것을 목표로 만들어졌다.

 

소프트웨어 템플릿을 통해 모범 사례에 대한 표준화를 수립하고, 이에 대한 문서를 생성하여 관리할 수 있다. 또한 오픈소스 플러그인을 제공하여 다양한 도구를 Backstage에 통합할 수 있는 소프트웨어 카탈로그를 제공하기 때문에 다양한 도구를 한 곳에서 관리할 수 있다. 이 외에도 Search 기능을 통해 사용자가 직접 검색엔진을 사용하여 필요한 리소스를 쉽게 찾을 수 있고, KUBERNETES 플러그인을 사용해서 쿠버네티스 클러스터를 통합하여 클러스터와 파드에 대한 상태 모니터링도 가능하다.

 

즉, 모든 개발 및 인프라 도구, 서비스 및 문서를 통합된 개발 환경에서 관리할 수 있게 되는 것이다.

참고: https://backstage.io/docs/overview/architecture-overview

 

Backstage는 2020년 9월 8일 CNCF(Cloud Native Computing Foundation)에 승인되었고, 2022년 3월 15일에 Incubating 성숙도 단계로 올라 빠르게 발전하고 있다.

이번 글에서는 Backstage를 간단하게 standalone으로 구성하고 Github provider 인증을 통해 로그인하는 실습을 다룬다.

 

구성 환경

• Amazon EC2 Instance

구성 버전

• Backstage : 1.28.0
• EC2 : Amazon2023-6.1.59-84.139.amzn2023.x86_64
• fnm : 1.37.1
• npm : 10.5.2
• Node.js : 20.13.1

전제 조건

• Github 계정

 

 

1. Backstage 설치

Node.js 버전관리를 수행하는 fnm (Fast Node Manager)를 설치한다.

$ curl -fsSL https://fnm.vercel.app/install | bash
$ export PATH="~/.local/share/fnm:$PATH"
$ source ~/.bashrc

 

fnm 명령어로 Node.js 버전 20을 사용하도록 설정한다.

$ fnm use --install-if-missing 20
Using Node v20.13.1

$ node -v
v20.13.1

 

npm 명령어로 yarn 패키지 매니저를 전역으로 설치한다.

$ npm install --global yarn

참고

의존성 오류가 나오면 다음과 같이 관련 패키지를 설치한다.

$ dnf install python3 make gcc gcc-c++ zlib-devel brotli-devel openssl-devel.

 

Node.js 패키지 실행 도구(npx)로 Backstage 최신 앱을 생성한다.

$ npx @backstage/create-app@latest
Need to install the following packages:
@backstage/create-app@0.5.16
Ok to proceed? (y) y
? Enter a name for the app [required] backstage

Creating the app...

 Checking if the directory is available:
  checking      backstage ✔

 Creating a temporary app directory:

 Preparing files:
  copying       .eslintignore ✔
  copying       .dockerignore ✔
  templating    .eslintrc.js.hbs ✔
  templating    .gitignore.hbs ✔
  copying       .prettierignore ✔
  copying       README.md ✔
  copying       app-config.local.yaml ✔
  copying       app-config.production.yaml ✔
  templating    app-config.yaml.hbs ✔
  templating    backstage.json.hbs ✔
  templating    catalog-info.yaml.hbs ✔
  copying       lerna.json ✔
  templating    package.json.hbs ✔
  copying       playwright.config.ts ✔
  copying       tsconfig.json ✔
  copying       yarn.lock ✔
  copying       README.md ✔
  copying       entities.yaml ✔
  copying       org.yaml ✔
  copying       template.yaml ✔
  copying       catalog-info.yaml ✔
  copying       index.js ✔
  copying       package.json ✔
  copying       README.md ✔
  templating    .eslintrc.js.hbs ✔
  copying       Dockerfile ✔
  templating    package.json.hbs ✔
  copying       README.md ✔
  copying       index.ts ✔
  copying       .eslintignore ✔
  templating    .eslintrc.js.hbs ✔
  templating    package.json.hbs ✔
  copying       app.test.ts ✔
  copying       android-chrome-192x192.png ✔
  copying       apple-touch-icon.png ✔
  copying       favicon-32x32.png ✔
  copying       favicon-16x16.png ✔
  copying       favicon.ico ✔
  copying       manifest.json ✔
  copying       index.html ✔
  copying       robots.txt ✔
  copying       safari-pinned-tab.svg ✔
  copying       App.test.tsx ✔
  copying       App.tsx ✔
  copying       apis.ts ✔
  copying       index.tsx ✔
  copying       setupTests.ts ✔
  copying       LogoIcon.tsx ✔
  copying       LogoFull.tsx ✔
  copying       Root.tsx ✔
  copying       index.ts ✔
  copying       EntityPage.tsx ✔
  copying       SearchPage.tsx ✔

 Moving to final location:
  moving        backstage ✔
  fetching      yarn.lock seed ✔
  init          git repository ◜
 Installing dependencies:
  init          git repository ✔
  determining   yarn version ✔
  executing     yarn install ✔
  executing     yarn tsc ✔

🥇  Successfully created backstage


 All set! Now you might want to:
  Run the app: cd backstage && yarn dev
  Set up the software catalog: https://backstage.io/docs/features/software-catalog/configuration
  Add authentication: https://backstage.io/docs/auth/

 

위 절차가 완료되면 backstage 이름의 디렉터리에 backstage앱이 생성된 것을 확인할 수 있다.

$ ls
backstage

 

생성된 폴더 구조는 다음과 같다.

app
├── app-config.yaml
├── catalog-info.yaml
├── package.json
└── packages
    ├── app
    └── backend

• app-config.yaml : 앱의 주요 구성 파일로 앱의 전체적인 설정을 관리한다.
• catalog-info.yaml : 카탈로그 메타데이터를 정의하는 파일이다.
• package.json : 프로젝트의 메타데이터 및 의존성을 정의한다. 주의할 점은 추가로 필요한 의존성은 여기에 정의하지 않고 각 워크스페이스에 설치해야 한다.
• packages/ : Backstage 프로젝트의 개별 패키지를 포함하는 디렉터리.
• packages/app/ : Backstage 프런트엔드 앱 디렉터리.
• packages/backend/ : 인증, 소프트웨어 카탈로그, 소프트웨어 템플릿, 기술 문서 등 의 기능을 구동하는 백엔드 앱 디렉터리.

 

 

2. Github 로그인 인증 연동

먼저 Github 로그인 인증 연동을 위해서 Github에서 Backstage에서 사용할 "OAuth Apps"을 생성해야 한다.

다음은 Oauth Apps 생성 예시이므로 환경에 맞게 입력하면 된다.

• Github 접속 > Settings > Developer Settings > Oauth Apps > New OAuth App

Backstage 설정 파일에 앞전에 생성한 'Oauth Apps'에서 'Client ID'와 'Client secrets'을 추가해야 하기 때문에 기록해 둔다. 

 

 

3. 소스코드 수정

먼저 frontend 코드를 수정 및 추가한다. 기본으로 추가되어 있는 guest는 주석처리 하고 github 관련 코드를 추가한다.

• packages/app/src/App.tsx

import { githubAuthApiRef } from '@backstage/core-plugin-api';

#...
const app = createApp({
#...
  components: {
    SignInPage: props => (
      <SignInPage
        {...props}
        auto
        provider={{
          id: 'github-auth-provider',
          title: 'GitHub',
          message: 'Sign in using GitHub',
          apiRef: githubAuthApiRef,
        }}
      />
    ),
//    SignInPage: props => <SignInPage {...props} auto providers={['guest']} />,
  },
});

 

다음으로 backend 코드를 수정 및 추가한다.

• packages/backend/src/index.ts

const backend = createBackend();
#...
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
#...
backend.start();

 

 

4. Backstage 설정

backstage앱 디렉터리로 이동하여 설정 파일을 다음과 같이 수정한다.

• app-config.yaml

app:
  baseUrl: http://0.0.0.0:3000

#...
backend:
  baseUrl: http://<BACKSTAGE_IP>:7007
  listen:
    port: 7007
  cors:
    origin: http://*:3000

#...
integrations:
  github:
    - host: github.com
      token: <Github Personal Access Token>

#...      
auth:
  experimentalExtraAllowedOrigins: ['http://<BACKSTAGE_IP>:3000']
  environment: development
  providers:
    guest: {}
    github:
      development:
        clientId: <Github Oauth client id>
        clientSecret: <Github Oauth client secret>
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

 

참고

외부 Postgresql을 사용할 경우 다음과 같이 설정 파일을 추가한다.

#...
backend: 
#...
  database:
    client: pg
    connection:
      host: ${POSTGRES_SERVICE_HOST}
      port: ${POSTGRES_SERVICE_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
#...

 

다음 파일에 Github 유저 아이디를 입력한다.

• examples/org.yaml

---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-user
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: <Github 유저 아이디>
spec:
  memberOf: [guests]
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: guests
spec:
  type: team
  children: []

 

 

5. Backstage 접속

웹브라이저를 통해 Backstage에 접속해서 Github을 인증을 통해 로그인이 되는지 확인한다.

• http://<BACKSTAGE_IP>:3000

 

Github ID/PASSWD를 입력하여 인증하면 다음과 같이 Backstage 대시보드 화면을 볼 수 있다.

"Settings"를 눌러 Github 사용자로 인증되었는지 확인한다.

 

 

마치며

Backstage는 다양한 팀이 표준화된 방식으로 애플리케이션 구축 및 운영 환경을 통합할 수 있게 도와주는 플랫폼이다. 사용자 입맛에 맞게 다양한 플러그인을 추가하고 커스터마이징하여 통합된 화면을 통해 다양한 문제를 빠르게 해결할 수 있다. 여러 서비스와 도구를 사용하는 대규모 조직에서는 이러한 통합 관리 시스템을 도입하는 것은 충분히 고려해 볼 만한 요소이다.

 

그러나 Backstage는 대규모 조직에서 사용하기에 적합할 것 같고 소규모 조직에서는 오히려 배보다 배꼽이 더 커지는 골치 아픈 일이 될 수 있다. 또한 Backstage를 유지보수 하고 플러그인을 개발하고 관리하려면 React에 대한 지식뿐만 아니라 아키텍처에 대한 깊은 이해도 필요하다. 그렇기 때문에 사용할 조직의 규모와 팀 내부적으로 이러한 사항을 충족할 수 있는 충분한 준비와 역량을 갖추고 있는지 검토하는 것도 중요하다.