[Azure] Azure Static Web Apps + GitlabCI로 애플리케이션 배포하기

 안녕하세요 Cloudraw 입니다.

 

 앞으로는 여러분들과 더 깊이 소통하기 위해 기술블로그를 운영해보고자 합니다. 유익한 글들을 통해 더 멋진 클라우드 환경에서 우리 함께 해요!!!!

 

 저희가 처음 정한 주제는 Azure Static Web Apps를 사용하여 애플리케이션(Cloudraw 홈페이지)배포하기 입니다. Azure Static Web Apps를 사용하여 React 기반의 정적 웹 애플리케이션을 호스팅하고 Gitlab CI를 적용하여 코드 수정 후 빌드부터 배포까지 자동으로 될 수 있도록 수행하는 과정을 담아보려고 합니다.

 

순서는 크게 네 가지로 나누었습니다.

 

첫 번째는 Azure Static Web App 생성하기,
두 번째 Gitlab-Runner 구성하기,
세 번째 Gitlab 프로젝트에서 파이프라인 구성하기,
마지막으로는 DNS CNAME 매핑하기 입니다.

 

우선 기본적으로 알아야할 것들에 대해 짧게 설명하고자 합니다.

정적 웹 애플리케이션이란?

HTML, CSS, JavaScript 및 다른 정적 파일로 구성되며, 서버 측 코드 또는 데이터베이스와 같은 백엔드 서비스가 필요하지 않는 웹 애플리케이션을 의미합니다.

Azure Static Web app이란?

Azure에서 제공하는 완전 관리형 서비스로 정적 웹 애플리케이션을 빌드하고 배포 및 호스팅까지 할 수 있습니다.

Cloudraw는 코드 저장소로 Gitlab을 채택하였고, Azure VM에 Gitlab을 설치하여 “Self-Managed Gitlab”형태로 서비스를 사용하고 있습니다. Azure Static Web app은 Gitlab에서 제공하는 Gitlab CI와 연결되어 지속적으로 통합하고 배포할 수 있는 환경을 제공하고 있습니다.

이제 생성 과정을 확인해보겠습니다.

1. Azure Static Web App 생성하기

첫 번째 작업은 Azure Portal에서 Azure Static Web App 서비스를 생성하는 것입니다.

• 사용할 구독과 리소스 그룹,Web static app 리소스의 이름을 설정합니다.
• Hosting plan은 사용할 환경에 맞게 선택하시면 됩니다.
• 배포할 소스는 Gitlab에 있으므로 Other를 선택합니다.

 

 Hosting plan을 간략히 비교해보면 모두 SSL Certificate를 지원하며 Standard는 free와 다르게 Private endpoints와 Custom authentication을 제공하고 있습니다.

다음은 Deployment Token을 발급해야 합니다. Azure Static Web Apps의 Deployment Token은 Gitlab CI도구와 통합하여 정적 웹 앱을 배포할 때 보안 인증 수단으로 사용됩니다.

 

 Static Web App 생성 시 자동으로 외부에서 접속할 수 있는 URL주소가 할당된 것을 확인할 수 있습니다.

생성된 리소스의 Overview 탭에서 Manage deployment token을 클릭합니다. Deployment Token 값을 따로 복사해둡니다. 이 토큰 값은 Gitlab CI 구성 시 필요합니다.

2. Docker로 Gitlab-Runner 구성하기

 두 번째 작업은 Gitlab-Runner를 구성하는 것입니다.

Gitlab CI와 Azure에서 제공하는 registry.gitlab.com/static-web-apps/azure-static-web-apps-deploy 라는 도커 이미지를 사용하여 정적 웹 애플리케이션을 자동으로 빌드하고 Azure Static Web App에 배포합니다.

Gitlab-Runner가 파이프라인에서 위 이미지를 사용하여 작업을 수행하기 위해서는 Gitlab-Runner의 executor를 도커로 설정해야 합니다. Gitlab-Runner는 Azure VM에 같이 설치가 되어 있으므로 VM안에 터미널로 접속하여 Gitlab-Runner를 구성해보도록 하겠습니다.

우선 Gitlab 프로젝트 Settings에서 확인해야할 값들이 있습니다.

Cloudraw 홈페이지의 파이프라인을 담당할 Gitlab-Runner는 Specific runner로 구성하였습니다.

• Gitlab 프로젝트 > Setting > CI/CD > Runners

 

Gitlab 서버 주소와 등록토큰을 복사해 둡니다.

• VM 터미널에서 아래의 명령어로 Gitlab-Runner를 등록합니다.

# gitlab-runner register 명령어로 등록해줍니다.
$ gitlab-runner register
                           
#url 입력                                                   
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://[gitlab server url]

#위의 registration token 입력
Enter the registration token:
[Registration token]#description 입력(선택)
Enter a description for the runner:#runner tag 입력
Enter tags for the runner (comma-separated): 
{사용할 gitlab-runner tag 입력}Enter optional maintenance note for the runner: (선택)#gitlab-runner executor - docker 선택
Registering runner... succeeded                     runner=Lxs7cUz-
Enter an executor: docker #default docker image 선택 - docker image 버전은 상황에 맞게 설정
Enter the default Docker image (for example, ruby:2.7):
docker:20.10.16
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

 

등록이 정상적으로 완료되면 /etc/gitlab-runner/config.toml에 Runner정보가 저장됩니다.

$ vi /etc/gitlab-runner/config.toml

...[[runners]]
  name = "{gitlab-runner tag}"
  url = "https://{cloudraw gitlab server url}"
  id = 7
  token = "[registration token]"
  token_obtained_at = 2023-08-28T09:06:20Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "docker:20.10.16"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    pull_policy = ["if-not-present"]
    shm_size = 0

• 프로젝트 > Settings > CI/CD > Runners > Specific Runners > Available Specific Runners에서 확인

녹색으로 표시되면 Runner가 정상 작동중인 상태입니다.

3. GitlabCI 파이프라인 구성하기

세 번 째 작업은 Gitlab CI로 파이프라인을 구성하는 작업입니다. 사용할 정적 웹 애플리케이션 소스코드가 관리되는 Gitlab 프로젝트에서 CI를 구성합니다. 우선 위에서 발급한 Deployment 토큰값을 변수로 설정해야 합니다.

• Gitlab 레포지토리 > 설정 > CI/CD > Variables
  Key값 : DEPLOYMENT_TOKEN
  Value값 : Deployment 토큰값을 입력합니다.

 

 다음으로는 .gitlab-ci.yml을 작성해야 합니다. .gitlab-ci.yml은 Gitlab CI 에서 파이프라인을 정의하는데 사용 되는 설정파일입니다. 이 파일은 Gitlab 프로젝트의 루트 디렉토리에 위치해야하며, 파이프라인이 어떻게 실행되고 어떤 작업을 수행해야 하는지를 명시적으로 정의합니다.

stages:
   - deploy
variables:
  API_TOKEN: $DEPLOYMENT_TOKEN
  APP_PATH: '$CI_PROJECT_DIR'
  OUTPUT_PATH: '$CI_PROJECT_DIR/out'
deploy:
  stage: deploy
  tags:
    - {사용할 gitlab-runner tag 설정}
  only:
    - main
  image: registry.gitlab.com/static-web-apps/azure-static-web-apps-deploy
  script:
    - echo "App deployed successfully."

• stages : 파이프라인에서 사용할 Stage를 정의합니다.
• variables : 환경 변수를 정의합니다.
  API_TOKEN : 위에서 설정한 Deployment token을 사용합니다.
  APP_PATH : 애플리케이션 코드의 위치를 명시합니다.
  OUTPUT_PATH : 애플리케이션 코드를 빌드했을 때 출력물의 폴더 위치를 나타냅니다.

만약 OUTPUT_PATH위치와 관련된 오류가 발생할 경우 빌드 출력물의 위치를 파이프라인에서 확인하고 수정해주면 됩니다. 이 파이프라인에서는 빌드 출력물이 /builds/application/cloudrawhome/out로 내보내진 것을 알 수 있습니다. /builds/application/cloudrawhome가 $CI_PROJECT_DIR에 해당합니다.

또한 리액트 기반의 웹 애프리케이션은 npm run build & npm run export 명령을 통해 코드가 빌드되고 출력되는데, 이 때 출력물의 default 위치는 빌드를 진행한 작업 디렉토리를 기준으로 /out 디렉토리에 생성되는 것입니다. 이는 변경이 가능하므로 사용자가 설정한 빌드 출력물 위치를 OUTPUT_PATH로 설정해주어야 합니다.

참고로 $CI_PROJECT_DIR는 Gitlab CI에서 사용하는 전역 환경변수로 Gitlab-Runner를 사용할 경우에 저장소가 복제되고 작업이 실행되는 전체 경로를 나타냅니다.

정리하면 Gitlab-Runner는 공통적으로 CI_PROJECT_DIR에서 빌드 작업을 실행하고 빌드 출력물의 위치는 웹 프레임워크마다 다르므로 확인이 필요합니다.

• deploy : 이 섹션은 “deploy” 스테이지에 속하는 작업을 정의합니다.
  stage: deploy : 작업이 “deploy”스테이지에 속하는 작업임을 정의합니다.
  tags: 사용할 Gitlab-runner Tag를 설정합니다.
  only: 이 작업이 main 브랜치에서만 작동하도록 정의하였습니다.
• image : registry.gitlab.com/static-web-apps/azure-static-web-apps-deploy
  작업을 실행할 Docker Image를 지정합니다. 이 이미지에는 정적 웹 애플리케이션을 Azure static Web apps로 배포하기 위해 미리 구성된 도구와 환경을 포함하고 있어 앱 빌드부터 배포까지 자동화하여 작업을 수행할 수 있습니다.

이제 해당 프로젝트의 main브랜치에서 event가 발생하면 빌드와 deploy 작업을 자동으로 수행하고 업데이트된 웹페이지 화면을 보여줍니다.

 

프로젝트 > CI/CD > Pipelines

 

작업을 눌러 파이프라인 작업 로그를 확인해보면 registry.gitlab.com/static-web-apps/azure-static-web-apps-deploy 이미지를 사용하여 Gitlab-runner가 도커로 실행중인 것을 알 수 있고 도커로 실행중인 Gitlab-Runner 안에서 앱이 빌드 되는 위치를 확인할 수 있습니다.

 

 

 

 빌드가 완료된 후 output이 출력되는 위치는 /builds/application/cloudrawhome/out로 확인할 수 있습니다.

Cloudraw 홈페이지는 리액트 기반의 정적 웹페이지입니다. npm run build & npm run export 명령을 통해 빌드하고 출력하는데 기본 디렉토리는 “빌드위치/out”에 생성됩니다.

 

 빌드 결과물을 Azure Static App에 업로드한 것을 확인할 수 있습니다.

이후 배포를 실행하고 “Thanks for using Azure Static Web Apps” 메세지가 나오면 정상적으로 배포 완료한 것을 확인할 수 있습니다.

 

Azure portal > Static Web Apps > Environments에서 Status가 Ready 인 것을 확인합니다.

4. 도메인설정

마지막 작업은 도메인 매핑작업입니다. Static web app을 만들면 자동으로 생성되는 Azure도메인과 사용할 사용자도메인을 CNAME 매핑하여 사용할 수도 있습니다.

• Azure Static Web apps > Setting > Custom domains

 

 Azure DNS zone을 사용하여 도메인을 구성하였으면 “Custom domain on Azure DNS”를 사용하고, 외부에서 도메인을 구성하였으면 “Custom domain on other DNS”를 선택합니다.

저희는 외부에서 구성한 도메인을 사용할 것이므로 Custom domain on other DNS를 선택합니다.

 

Hostname record type을 CNAME으로 선택합니다

 

 url 접속을 통해 도메인이 정상적으로 매핑 된 것을 확인하였습니다.

 

이상으로 Azure Static Web App을 사용하여 저희 클라우드로 홈페이지를 자동으로 빌드하고 배포하는 과정을 보여드렸습니다. 앞으로 더 성장하는 Cloudraw를 기대해주시고 더 유익한 글로 찾아 뵙도록 하겠습니다!

감사합니다.

---

 

Cloudraw는 쉽게 클라우드 인프라를 그리고 사용할 수 있는 서비스를 제공하기 위해 노력하고 있습니다.

 

클라우드가 있는 곳 어디든 Cloudraw가 함께합니다.

 

📨 help@cloudraw.kr