지난 아티클에서 Backstage 앱을 로컬 환경에 빌드하고 주요 컴포넌트를 이해하기 위해 관련된 설정 파일과 소스코드를 살펴보는 실습을 진행했다.
이번에는 Backstage 앱과 현재 소유 중인 GitHub 계정을 연동해보겠다. 본 아티클에서 다룰 주제는 2가지이다.
- GitHub OAuth로 Backstage 앱에 로그인하도록 연동
- 샘플 데이터가 아닌 개발용
catalog-info.yaml에 카탈로그 엔티티 추가
이전에 로컬 빌드한 Backstage 앱을 이어서 사용할 예정이다. 만약 Backstage를 로컬에서 빌드해본 적이 없다면 지난 실습 가이드를 확인해보자.
1. GitHub OAuth로 Backstage 앱에 로그인
Backstage 앱에서는 조직의 자산과 민감 정보를 다룰 수 있으므로 각 사용자의 인증이 필수이다. 지난 번에 Backstage 앱을 로컬에 빌드할 때 Guest 인증을 사용했지만, 이는 초기 데모 편의를 위해 준비된 것이므로 계속 사용하기엔 좋지 않다.
그래서 Backstage가 지원하는 다른 인증 프로바이더 중 GitHub 인증을 먼저 구현하도록 하겠다. GitHub 인증은 우리에게 익숙하고 무료이기 때문에 실습용으로 제격이다.
먼저 GitHub 웹페이지에서 OAuth App을 생성하자. GitHub OAuth는 외부 애플리케이션(Backstage)에 GitHub 계정으로 안전하게 로그인할 수 있는 인증 시스템이다.
해당 페이지에서 설정은 아래와 같이 하면 된다.
- Application name: 연동할 외부 애플리케이션 이름 지정
- Homepage URL: Backstage 앱의 프론트엔드 URL
- Authorization callback URL:
- Backstage 앱의 백엔드 주소와 인증용 라우팅 규칙 사용
http://localhost:7007/api/auth/github/handler/frame으로 지정
Register application 버튼을 눌러 등록을 완료하면 상세 페이지에서 Client ID를 확인할 수 있고, Generate a new client secret 버튼을 눌러 Client Secret을 생성할 수 있다. 두 가지 모두 아래와 같이 로컬의 환경 변수로 저장하자. 이들을 이용해서 Backstage의 GitHub 인증 설정을 진행할 것이다.
export AUTH_GITHUB_CLIENT_ID={자신의 Client ID}
export AUTH_GITHUB_CLIENT_SECRET={새로 생성한 Client Secret}다음은 app-config.yaml 파일을 손볼 차례다. 아래와 같이 auth 필드를 수정하자.
...
auth:
environment: development
providers:
# guest: {}
github:
development:
clientId: ${AUTH_GITHUB_CLIENT_ID}
clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
signIn:
resolvers:
- resolver: usernameMatchingUserEntityName
...auth.environment:- 인증 기능의 동작 환경을 명시
- 현재는
development로 명시되어 있어github.development아래에 명시된 인증 설정이 동작
signIn.resolvers.resolver:- 로그인 성공 조건을 명시
- 현재는 GitHub 계정명과 Backstage의 User 엔티티 이름이 같아야 로그인 성공
Backstage 앱은 직접 소스코드를 작성하며 개발해야 한다고 했다. 인증 기능을 구현할 때에도 마찬가지이다. 먼저 백엔드 코드를 수정해보자.
GitHub 인증 프로바이더를 사용하려면 해당 패키지를 설치한 다음 백엔드 코드에 추가해야 한다. Backstage 앱의 루트 경로에서 아래 명령어를 실행해 패키지를 먼저 설치한다.
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider그리고 백엔드 소스코드 파일(packages/backend/src/index.ts)의 // auth plugin 부분을 아래처럼 수정한다. 방금 전에 설치한 패키지를 사용하기 위한 코드이다.
...
// auth plugin
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
...다음은 프론트엔드 코드를 작성할 차례다. 먼저 GitHub 로그인 페이지 구현에 필요한 패키지를 설치하자. Backstage 루트 경로에 아래 명령어를 실행한다.
yarn --cwd packages/app add @backstage/core-plugin-api @backstage/plugin-app-react이제 Backstage 웹 UI에 GitHub 로그인 화면을 표시할 수 있도록 컴포넌트를 추가해야 한다. packages/app/src/App.tsx 소스코드를 아래와 같이 수정한다.
import { createApp } from '@backstage/frontend-defaults';
import catalogPlugin from '@backstage/plugin-catalog/alpha';
import { navModule } from './modules/nav';
import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPageBlueprint } from '@backstage/plugin-app-react';
import { SignInPage } from '@backstage/core-components';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
const signInPage = SignInPageBlueprint.make({
params: {
loader: async () => props =>
(
<SignInPage
{...props}
provider={{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Sign in using GitHub',
apiRef: githubAuthApiRef,
}}
/>
),
},
});
export default createApp({
features: [
catalogPlugin,
navModule,
createFrontendModule({
pluginId: 'app',
extensions: [signInPage],
}),
],
});signInPage: GitHub 인증 창을 표시할 컴포넌트 정의createApp: 기존 프론트엔드 앱에signInPage컴포넌트 추가
2. 카탈로그에 User와 Group 엔티티 추가하기
마지막으로 연동한 GitHub 계정 사용자를 Backstage 카탈로그 엔티티로 추가해보자.
Backstage에서 관리하는 모든 요소를 카탈로그 엔티티(Catalog Entity)라고 부른다고 했다. 여기서 모든 요소란, 조직이 개발하는 서비스와 라이브러리뿐만 아니라 DB, 조직 내 개발자, 그룹, 도메인 등을 포함한다.
아까 app-config.yaml 파일에서 GitHub 계정명과 User 엔티티의 이름이 같은지 확인하는 조건을 설정했던 걸 기억할 것이다. 연동한 GitHub 계정명에 대한 User 엔티티를 정의해야 한다.
Backstage 앱 루트 경로에 위치한 catalog-info.yaml 파일을 연 다음, 아래와 같이 개발용 Group과 User를 추가하자. 여기서 유의할 점은, 새로 추가할 User 엔티티의 metadata.name이 연동할 GitHub 계정명과 일치해야 한다는 점이다. Group 엔티티는 예시이므로 원하는 대로 설정하면 된다.
{기존에 있던 Component}
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
name: guide-to-devops
spec:
profile:
displayName: Platform Engineer
email: aiden@example.com
memberOf: [platform-team]
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
name: platform-team
spec:
type: team
children: []초기 Backstage 앱은 데모를 위해 examples 폴더 안에 있는 샘플 엔티티 데이터를 함께 참조하도록 설정되어 있다. 이제 우리는 루트 경로의 catalog-info.yaml만을 사용할 것이므로 샘플 데이터를 참조하는 설정은 주석 처리하도록 하자. app-config.yaml 파일의 catalog.locations 필드로 이동 후 아래와 같이 수정한다.
...
catalog:
...
locations:
# Local example data, file locations are relative to the backend process, typically `packages/backend`
# - type: file
# target: ../../examples/entities.yaml
# Local example template
# - type: file
# target: ../../examples/template/template.yaml
# rules:
# - allow: [Template]
# Local example organizational data
# - type: file
# target: ../../examples/org.yaml
# rules:
# - allow: [User, Group]
- type: file
target: ../../catalog-info.yaml
rules:
- allow: [User, Group]
...catalog-info.yaml 파일 설정
지금은 초기 개발 단계이므로 Backstage 앱의 루트 경로에 있는
catalog-info.yaml을 사용했다. 하지만 프로덕션 환경에서는 GitHub 등의 레파지토리마다catalog-info.yaml파일을 따로 관리하고app-config.yaml에서는type: url로 각catalog-info.yaml파일의 URL을 명시하는 것이 좋다.
이제 yarn start Backstage 앱을 다시 켠다. 그럼 이제 Guest 모드 대신 GitHub 로그인 박스가 표시될 것이다. SIGN IN 버튼을 누르자.
그럼 아래와 같이 GitHub 로그인할 수 있는 창이 새로 뜰 것이다.
GitHub 로그인이 완료되면 아래와 같이 Backstage 웹 UI에 접속할 수 있게 된다. 현재 catalog-info.yaml 파일에 이미 정의되어 있던 my-backstage Component가 보인다.
이렇게 Backstage 앱에 GitHub 인증에 성공했다. 아래와 같이 Catalog 페이지의 Kind를 User로 바꾸면 Platform Engineer라는 이름의 사용자가 하나 뜨는 것을 확인할 수 있다.
이것이 바로 우리가 아까 catalog-info.yaml에 추가한 GitHub 로그인 대상 User 엔티티이다.spec.profile.displayName 필드의 값을 Platform Engineer로 지정했기 때문에 위와 같이 표시되는 것이다. 이렇게 등록된 내부 개발자와 팀을 Backstage에서 관리할 수 있는 것이다.
마무리
이번 아티클에서는 Backstage와 GitHub을 연동해서 인증 기능을 직접 구현하고, catalog-info.yaml에 User와 Group 엔티티를 추가해 Backstage에 반영해봤다.
인증과 카탈로그 엔티티 설정은 Backstage 개발 환경을 만들기에 좋은 시작점이므로 Backstage로 사내 개발자 플랫폼 구축에 관심이 있다면 큰 도움이 될 것이다.
아마 실습을 진행하면서 느꼈을 수 있지만, Backstage 프로젝트로 IDP를 개발하는 경우에도 공수가 꽤나 드는 것이 사실이다.
하지만 조직에서 관리하는 인원이나 서비스가 증가함에 따라 정보의 파편화가 너무 심해졌다면, 이런 내부 개발자 플랫폼을 구축해서 하나의 지점에서 관리해 개발자들의 인지 부하를 줄이고 운영 리스크도 완화할 수 있을 것이다.