Open in app

Sign in

Write

Sign in

Backstage 테스트를 위한 로컬 개발 환경 구성하기 #2

Paul
21 min readMay 12, 2024

--

Photo by Tim Mossholder on Unsplash

Backstage 환경을 구성하고 다양한 테스트를 하기 위한 로컬 환경을 생성하도록 하겠습니다. Vagrant 와 Virtual Box 를 사용하여 Ubuntu 20.04 가상 서버 1대에 구성을 하려고 합니다. 로컬 환경에서 Backstage 구성에 기본이 되는 Backstage, Gitea, Gitea Runner, k3s 환경에 ArgoCD 환경까지 구성을 해보도록 하겠습니다.

로컬 Backstage 테스트 환경 구성

전체 구성에 대한 소스는 아래의 Github 주소를 참고해 주시기 바랍니다.

GitHub - baiyongzhen/backstage-tutorial

Contribute to baiyongzhen/backstage-tutorial development by creating an account on GitHub.

github.com

Backstage Docker Image 생성하기

Docker 이미지를 사용하여 Backstage 테스트 환경을 구성합니다. 로컬 환경에서 Backstage를 설치할 때는 상당한 시간이 소요되며, 버전에 따라 추가적인 패키지 업그레이드가 필요할 수 있습니다. 아래 Dockerfile은 Backstage 설치를 위해 필요한 node 18 이상과 yarn을 포함하고 있습니다. Backstage 설치 중 네트워크 타임 아웃을 방지하기 위해 yarn 설정에 network-timeout 값을 설정하였습니다.

# Dockerfile for Backstage
FROM node:18

RUN apt-get update && \
apt-get install -y --no-install-recommends python3 g++ build-essential git vim && \
yarn config set python /usr/bin/python3

WORKDIR /backstage
ENV BACKSTAGE_APP_NAME=app
ENV BACKSTAGE_CREATE_APP_VERSION="0.5.8"

RUN yarn config set network-timeout 300000
RUN echo "Installing the latest Backstage app using Create App version $BACKSTAGE_CREATE_APP_VERSION"
RUN npx -y -q @backstage/create-app@$BACKSTAGE_CREATE_APP_VERSION

# Bug patch("Getting Started" failing)
# https://github.com/backstage/backstage/issues/22142
COPY ./package.json /backstage/app/package.json
WORKDIR /backstage/app
RUN yarn install

Backstage 설치는 backstage/create-app 통해서 설치가 되며, backstage/create-app 버전에 따라서 Backstage 설치 버전이 달라집니다. Backstage Upgrad Helper 사이트에서 backstage/create-app 버전 별 Backstage 버전의 정보를 확인 할 수 있으며, 업그레이드 시 변경되는 패키지 정보 및 소스 정보를 확인 할 수 있습니다.

https://backstage.github.io/upgrade-helper

Backstage 1.21.1 버전으로 설치 후 실행 시 swagger-ui-react 에러로 인해서 실행이 되지 않습니다. 따라서 package.json 업데이트 했습니다.

[0] ERROR in ../../node_modules/swagger-ui-react/node_modules/react-redux/dist/react-redux.mjs 1103:18-45
[0] export 'useSyncExternalStore' (imported as 'React2') was not found 
in 'react' (possible exports: Children, Component, Fragment, 
Profiler, PureComponent, StrictMode, Suspense, 
__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED, 
cloneElement, createContext, createElement, createFactory, 
createRef, forwardRef, isValidElement, lazy, memo, useCallback, 
useContext, useDebugValue, useEffect, useImperativeHandle, 
useLayoutEffect, useMemo, useReducer, useRef, useState, version)
Confirmed, the issue is with swagger-ui-react, if I add the following to 
the resolutions section of the root package.json file it works:

    "resolutions": {
        "@types/react": "^17",
        "@types/react-dom": "^17",
+      "swagger-ui-react": "5.10.5"
    },

yarn install
yarn tsc

Backstage Docker 이미지를 빌드한 후 Docker Hub에 푸시하는 과정은 다음과 같습니다

  1. Docker Hub 접속 및 로그인: 웹 브라우저에서 Docker Hub를 열고 로그인하세요.
  2. 리포지토리 생성: Backstage 이미지를 저장할 리포지토리를 생성합니다.
  3. Docker에 로그인: docker login — username={dockerhub_username}
  4. 이미지 빌드: docker build — tag <dockerhub_username>/<repository_name>[:TAG] .
  5. 이미지 푸시: docker push <dockerhub_username>/<repository_name>[:TAG]

backstage-tutorial/docker/backstage at main · baiyongzhen/backstage-tutorial

Contribute to baiyongzhen/backstage-tutorial development by creating an account on GitHub.

github.com

Backstage 실행하기

Backstage 실행하기 위해 Docker Compose 작성해 보도록 하겠습니다. Docker Compose은 아래와 같습니다.


# docker-compose.yaml 파일
version: '3'
services:
  backstage:
    # DockerHub 주소
    image: <dockerhub_username>/<repository_name>[:TAG]
    container_name: backstage
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "./app/app-config.yaml:/backstage/app/app-config.yaml"
    env_file: .env
    ports:
      - 3000:3000
      - 7007:7007

app-config.yaml 파일을 수정합니다. 설정 값을 외부 환경 변수에 의해서 설정할 수 있도록 환경 변수 값으로 변경합니다.

# app-config.yaml 파일
app:
  title: Scaffolded Backstage App
  baseUrl: http://0.0.0.0:3000
..

backend:
  baseUrl: ${PROTOCOL}://${BACKSTAGE_HOSTNAME}:7007
..
  cors:
    origin: ${PROTOCOL}://${BACKSTAGE_HOSTNAME}:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true

app-config.yam 에 설정할 환경 변수 값을 위해서 .env 파일을 생성합니다.

# .env 파일 설정
PROTOCOL="http"
# Backstage backend 접속할 주소 (Vagrantfile 에 설정된 Private IP 정보)
BACKSTAGE_HOSTNAME="192.168.56.174"
CUSTOMER_NAME="My Company"

# Github Token 값 설정
GITHUB_TOKEN="1234567890"

Docker Compose UP 명령어를 실행합니다. 컨테이너가 정상적으로 실행이 되었다면 브라우저를 실행한 후에 http://192.168.56.174:3000/ 접속 합니다.

# virtualbox 가상서버 환경
vagrant@backstage:/vagrant/references/01.backstage-base$ tree -a
.
├── app
│   └── app-config.yaml
├── docker-compose.yaml
├── .env
└── .env.example

1 directory, 4 files
vagrant@backstage:/vagrant/references/01.backstage-base$ docker-compose up -d
[+] Running 1/1
 ⠿ Container backstage  Running                                                                                  0.0s
vagrant@backstage:/vagrant/references/01.backstage-base$ docker ps -a
CONTAINER ID   IMAGE                         COMMAND                  CREATED         STATUS         PORTS
                                                                      NAMES
caf3f69e36a1   gnu96/backstage-amd64:0.5.8   "docker-entrypoint.s…"   9 seconds ago   Up 6 seconds   0.0.0.0:3000->3000/tcp, :::3000->3000/tcp, 0.0.0.0:7007->7007/tcp, :::7007->7007/tcp   backstage
vagrant@backstage:/vagrant/references/01.backstage-base$

Docker Compose 및 Backstage 설정 파일 및 환경 정보는 아래의 GitHub 주소를 참고해 주시기 바랍니다.

backstage-tutorial/references/01.backstage-base at main · baiyongzhen/backstage-tutorial

Contribute to baiyongzhen/backstage-tutorial development by creating an account on GitHub.

github.com

로컬 Git 서버 구성하기

Backstage에서 다양한 소프트웨어 템플릿을 생성하고 관리하기 위해서는 Git 서비스와 연동이 필수적입니다. Gitea는 GitHub, GitLab, Bitbucket 서비스에 비해 간단하게 로컬 환경에 설치하고 구성할 수 있는 장점이 있습니다.

Gitea 환경 구성 시 고려 사항:

Important: As backstage will issue HTTPS/TLS requests to the gitea instance, it is needed to configure gitea with a valid certificate or at least with a self-signed certificate gitea cert — host localhost -ca trusted by a CA authority. Don’t forget to set the env var NODE_EXTRA_CA_CERTS to point to the CA file before launching backstage !

Backstage와 Gitea 연동을 위해서는 Gitea는 HTTPS/TLS 로 구성을 해야 합니다. Gitea 서버 구성에 대한 가이드는 아래의 링크를 참고해 주시기 바랍니다.

로컬 Gitea(Self-hosted Git service) 환경 구성하기

Gitea는 오픈 소스 소프트웨어이며, Go 언어로 작성된 자체 호스팅 Git 서버입니다. 저장소 파일 편집기, 프로젝트 이슈 추적, 사용자 관리, 알림, 내장 위키까지 포함된 서비스를 제공합니다. 또한 로컬…

medium.com

Gitea Runner 통한 Gitea Actions 구성하기

앞에서 Gitea 환경을 구성했습니다. 이번에는 Gitea Actions (Gitea 버전이 1.19.0 이상)활용해 CI/CD 파이프 라인을 구성하기 전에, Gitea Actions 작업을 실행할 Gitea…

medium.com

Gitea, Gite Runner 관련 도커 환경은 아래의 GitHub 주소를 참고해 주시기 바랍니다.

backstage-tutorial/docker at main · baiyongzhen/backstage-tutorial

Contribute to baiyongzhen/backstage-tutorial development by creating an account on GitHub.

github.com

# # virtualbox 가상서버 환경에서 Gitea, Gitea Runner 실행
vagrant@backstage:~$
vagrant@backstage:~$ cd /vagrant/docker/
vagrant@backstage:/vagrant/docker$ ls -al
total 12
drwxrwxrwx 1 vagrant vagrant 4096 May  5 11:37 .
drwxrwxrwx 1 vagrant vagrant 4096 May  6 02:30 ..
drwxrwxrwx 1 vagrant vagrant    0 May  5 11:37 backstage
drwxrwxrwx 1 vagrant vagrant    0 May  5 11:39 gitea
drwxrwxrwx 1 vagrant vagrant 4096 May  5 12:50 gitea-label
drwxrwxrwx 1 vagrant vagrant    0 May  5 12:55 gitea-runner
# gitea 서버 실행함.
vagrant@backstage:/vagrant/docker$ cd gitea
vagrant@backstage:/vagrant/docker/gitea$ docker-compose up -d
[+] Running 2/2
 ⠿ Network gitea_default  Created                                                                            0.4s
 ⠿ Container gitea        Started                                                                            2.5s
vagrant@backstage:/vagrant/docker/gitea$ cd ..
vagrant@backstage:/vagrant/docker$ ls
backstage  gitea  gitea-label  gitea-runner
# gitea runner 실행함.
vagrant@backstage:/vagrant/docker$ cd gitea-runner/
vagrant@backstage:/vagrant/docker/gitea-runner$ docker-compose up -d
[+] Running 1/1
 ⠿ Container act_runner  Started

Gitea 구성이 완료 되었다면, 브라우저를 실행 하고 https://192.168.56.174:3300/ 접속 후 로그인을 합니다.

k3s 환경구성 및 ArgoCD 설치하기

  1. k3s 설치하기

로컬에서 Kubernetes 환경을 구성 시 리소스 제한 때문에 전체 Kubernetes 클러스터를 설치하기 어려울 수 있습니다. 이런 경우, 경량화된 Kubernetes 배포판인 k3s가 이상적인 대안이 됩니다. k3s는 낮은 리소스 요구 사항으로 인해 로컬 개발 환경이나 테스트 환경 구축에 적합합니다. 아래와 같이 가상환경에 k3s를 설치하도록 하겠습니다.

# https://github.com/baiyongzhen/backstage-tutorial/blob/main/scripts/install_argocd_on_k3.sh
# Vagrant 환경의 ubuntu-20.04 가상머신 환경
# Install k3s 환경
vagrant@gitea:~$ curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC=" --write-kubeconfig-mode=644" sh -
# k3s 서비스 상태 체크
vagrant@gitea:~$ systemctl status k3s
● k3s.service - Lightweight Kubernetes
     Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2024-05-04 00:14:12 UTC; 4h 5min ago
       Docs: https://k3s.io
   Main PID: 807 (k3s-server)
      Tasks: 276
     Memory: 848.7M
     CGroup: /system.slice/k3s.service
             ├─ 807 /usr/local/bin/k3s server
             ├─1945 containerd
...
# kubectl 명령어를 통해서 네임스페이스 정보를 가지고 오기
vagrant@gitea:~$ kubectl get ns
NAME              STATUS   AGE
kube-system       Active   4d15h
kube-public       Active   4d15h
kube-node-lease   Active   4d15h
default           Active   4d15h
argocd            Active   4d15h
api-gateway       Active   3d3h

2. ArgoCD 설치하기

ArgoCD는 Kubernetes 환경에서 애플리케이션 배포와 관리를 지원하는 도구로, GitHub, Bitbucket, GitLab의 CI/CD(Git Actions, Pipelines)와의 연동이 가능합니다. 아래와 같이 k3s 환경에 ArgoCD 설치하도록 하겠습니다.

# https://github.com/baiyongzhen/backstage-tutorial/blob/main/scripts/install_argocd_on_k3.sh
# ArgoCD 네임스페이스 생성하기
vagrant@gitea:~$ kubectl create ns argocd
# ArgoCD mainifests 다운로드 
vagrant@gitea:~$ wget https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml -O install.yaml
# ArgoCD 설치
vagrant@gitea:~$ kubectl apply -n argocd -f install.yaml
# ArgoCD 설치 리소스를 정보를 출력함.
vagrant@gitea:~$ kubectl get all -n argocd
# ArgoCD 접속을 위한 패스워드 정보를 얻기
vagrant@gitea:~$ kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# ArgoCD 외부 접속이 가능하도록 NodePort로 변경
vagrant@gitea:~$ kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "NodePort"}}'

# ArgoCD 외부 접속이 가능하도록 서비스 Port
kubectl get svc -n argocd
NAME                                      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
....
argocd-repo-server                        ClusterIP   10.43.152.35    <none>        8081/TCP,8084/TCP            56m
argocd-server-metrics                     ClusterIP   10.43.186.128   <none>        8083/TCP                     56m
argocd-server                             NodePort    10.43.2.54      <none>        80:31263/TCP,443:32560/TCP   56m

ArgoCD 설치가 완료된 후에 브라우저를 실행하고 https://192.168.56.174:32567/ 접속 후 로그인을 합니다. 다음으로 ArgoCD CLI 설치 및 패스워드 변경해 보도록 하겠습니다.

# Install ArgoCD CLI
ARGOCD_VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
curl -sSL -o ./argocd-${ARGOCD_VERSION} https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-amd64
chmod +x ./argocd-${ARGOCD_VERSION}
sudo mv ./argocd-${ARGOCD_VERSION} /usr/local/bin/argocd 
argocd version --client

# ArgoCD 로그인
vagrant@backstage:~$ argocd login 192.168.56.174:32567
WARNING: server certificate had error: tls: failed to verify certificate: x509: cannot validate certificate for 192.168.56.174 because it doesn't contain any IP SANs. Proceed insecurely (y/n)? yes
Username: admin
Password:
'admin:login' logged in successfully
Context '192.168.56.174:32567' updated

# ArgoCD 패스워드 변경
argocd account update-password \
  --account admin \
  --current-password nfErZ9sCibIpMgVI \
  --new-password argocd1234!

마무리하며

가상환경과 Docker를 기반으로 로컬에서 Backstage 환경 구성을 완료했습니다. 이제부터는 Backstage의 다양한 통합(Integration) 및 핵심 기능(Software Catalog, Software Templates, TechDocs, Plugin)에 대해 알아보겠습니다.

참고사이트

Backstage
Platform Engineering
Gitea
Argo Cd

--

--

Paul

Written by Paul

73 Followers

DevOps Engineer

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams