GitHub로 NGINX 구성 관리하기

소프트웨어 설정, 옵션 및 구성은 다양한 형태로 존재합니다. 한쪽 끝에는 직관적이면서도 잘못된 상태에 대한 가드레일을 제공하는 매끄럽고 반응이 빠른 GUI가 있습니다. 다른 쪽 끝에는 텍스트 파일이 있습니다. 텍스트 파일은 명확성, 자동화 가능성, 최소한의 사용 요구 사항(터미널 창이 몇 개 열려 있을 가능성이 높죠?)으로 인해 엔지니어와 DevOps 팀 모두에게 찬사를 받고 있지만, 텍스트 파일로 소프트웨어를 구성하는 데는 분명한 장단점이 있습니다. 예를 들어, 텍스트 파일을 잘못 구성하여 소프트웨어 패키지를 다운시킨 경험이 없는 Linux 사용자를 찾아보세요.

유일한 올인원 소프트웨어 프록시, 로드 밸런서, 웹 서버, API 게이트웨이인 NGINX는 최신 인터넷 인프라의 핵심 구성 요소입니다. 대부분의 경우 Linux 커널로 구동되는 운영 체제를 기반으로 하는 인프라입니다. 이러한 에코시스템과 이를 지원하는 전문가를 준수하기 위해 NGINX는 텍스트 기반 구성에 크게 의존합니다.

F5 NGINX 인스턴스 관리자 모듈는 오랫동안 NGINX 관련 구성 오케스트레이션을 위해 널리 사용되어 왔습니다. 직관적인 사용자 인터페이스와 API를 통해 원격 일괄 구성 관리를 위한 고급 기능을 제공하며, 부팅을 위한 지원 문서와 가드레일을 제공합니다. 하지만 개별 NGINX 구성 파일은 코드와 매우 유사하며 소프트웨어 팀에는 이미 코드를 관리할 수 있는 훌륭한 도구가 있습니다: 바로 Git입니다. Git은 개발자와 운영팀에 텍스트 파일 워크플로우를 관리하기 위한 다양한 기능을 제공합니다.

인스턴스 관리자는 Git 및 기타 외부 시스템과의 새로운 통합을 통해 버전 관리, 분산된 기여, 승인 워크플로 및 팀 조정과 같은 기능을 사용할 수 있습니다. GitHub 및 GitLab과 같은 플랫폼은 웹 기반 사용자 인터페이스를 통해 이 기능 세트를 지속적인 통합/지속 배포(CI/CD), 협업, 이슈 추적 및 기타 유용한 기능으로 확장합니다.

이 블로그 게시물에서는 GitHub를 사용하여 변경이 있을 때마다 자동으로 인스턴스에 푸시하여 NGINX 구성을 관리하는 방법을 설명합니다.

인스턴스 관리자 API

인스턴스 관리자는 웹 사용자 인터페이스를 보완하는 다양한 REST API 세트를 제공합니다. 이 API의 주요 장점은 관리 중인 데이터 플레인 인스턴스의 구성 파일을 업데이트할 수 있다는 점입니다. 최근에는 구성 업데이트를 특정 버전의 파일에 연결할 수 있는 기능을 활성화하여 이 기능을 확장했습니다. Git 리포지토리에서 관리할 때 구성에 Git 커밋 해시를 사용하여 태그를 지정할 수 있습니다. 또한 외부에서 관리되는 설정에 대해 인스턴스 관리자 내에 새로운 상태를 구현하여 파일 편집자에게 설정이 외부에서 관리되고 있음을 경고합니다.

GitHub 액션

GitHub에서는 개발자가 Actions라는 기능을 사용하여 리포지토리에서 사용자 지정 배포 파이프라인을 만들 수 있습니다. 사용자는 직접 작업을 정의하거나 YAML 정의를 통해 기존 스크립트를 호출하도록 선택할 수 있습니다. 이러한 파이프라인은 커밋 또는 풀 리퀘스트 병합으로 리포지토리가 업데이트될 때와 같이 다양한 방식으로 트리거될 수 있습니다.

이 블로그의 예제에서는 기본 제공되는 GitHub 액션과 Linux 명령을 사용합니다. 이를 사용하여 인스턴스 관리자 API를 통해 NGINX 인스턴스에서 GitHub 관리 NGINX 구성 파일을 업데이트하는 방법을 배우게 됩니다. 시작하려면 GitHub 문서에서 다음 단계를 따라 리포지토리에서 Actions를 실행하기 위한 새 YAML을 만드세요.

작업 비밀 설정하기 (Secret)

인스턴스 관리자는 다양한 형태의 인증을 지원합니다. 이 예에서는 기본 인증 방법을 사용하지만, 프로덕션 환경에서는 OIDC 인증을 프로비저닝하는 것이 좋습니다.

리포지토리에 인스턴스 관리자 자격 증명을 저장하는 대신 GitHub를 사용하면 리포지토리 변수로 비밀을 정의할 수 있습니다. 이러한 변수는 Actions 환경에서 액세스할 수 있지만 로그에는 숨겨져 있습니다. 이 단계에 따라 인스턴스 관리자 사용자 이름 및 비밀번호 키를 비밀로 저장하여 API 호출을 인증하는 데 사용할 수 있도록 하세요.

여기서는 이러한 변수를 NMS_USERNAME 및 NMS_PASSWORD로 설정했습니다.

액션 변수 설정

마찬가지로 YAML에서 상수 변수를 정의하는 대신 GitHub 사용자 인터페이스에서 관리할 수 있도록 변수를 구분하는 것이 도움이 될 수 있습니다. 변수 페이지에서 모든 리포지토리 작업에 걸쳐 변수를 정의하는 방법에 대한 지침을 찾을 수 있습니다. 이 예제에서는 이 기회를 사용하여 인스턴스 관리자 FQDN 또는 IP(NMS_HOSTNAME), NGINX가 실행 중인 시스템의 식별자(SYSTEM_ID), 업데이트할 특정 NGINX 인스턴스의 식별자(INSTANCE_ID)를 정의하고 있습니다.

주: 예제를 단순화하기 위해 이러한 변수를 설정했지만 다른 방식으로 인스턴스 관리자, 시스템 및 NGINX 식별 정보를 관리하도록 선택할 수도 있습니다. 예를 들어 리포지토리에 다양한 인스턴스별 구성이 포함된 디렉터리를 만들고 시스템 또는 인스턴스 ID로 디렉터리 이름을 지정할 수 있습니다. 그런 다음 디렉토리 이름을 읽고 해당 인스턴스에서 구성 파일을 업데이트하도록 YAML 또는 작업 스크립트를 수정할 수 있습니다.

NGINX 구성을 업데이트하기 위한 인스턴스 관리자 REST API 호출의 구조

인스턴스 관리자 구성 업데이트 REST API 호출이 작동하려면 몇 가지 주요 구성 요소가 필요합니다. YAML에서 이러한 각 매개변수를 정의하고 적절한 형식으로 API 호출에 패키징해야 합니다.

이 예에서는 단일 인스턴스를 업데이트하기 위해 API 호출을 사용합니다. 그러나 인스턴스 관리자 내에서 인스턴스 그룹을 구성할 수도 있습니다. 이렇게 하면 GitHub에서 새 구성이 푸시될 때마다 그룹의 모든 인스턴스를 업데이트할 수 있습니다. 자세한 내용은 설정 게시 방법 가이드를 참조하세요.

다음은 인스턴스 관리자의 구성 업데이트 REST API 호출에 대한 분석입니다:

https://{INSTANCE MANAGER HOSTNAME}/api/platform/v1/systems/{SYSTEM ID}/instances/{INSTANCE ID}/config' 
--header "accept: application/json" 
--header "Authorization: Basic {LOGIN CREDENTIALS}" 
--header 'Content-Type: application/json'
--data '{
    "configFiles": '{
        "rootDir": "/etc/nginx",
        "files": [{
            "contents": "{NGINX CONFIGURATION FILE}",
            "name": "{PATH TO CONFIGURATION FILE ON SYSTEM}"
        }]
    },
    "externalIdType": "{SOURCE OF CONFIGS}",
    "externalId": "{COMMIT HASH}",
    "updateTime": "{TIMESTAMP}"
}'}'

NGINX 구성

다음으로 관리하려는 NGINX 구성을 리포지토리에 추가합니다. 

GitHub 리포지토리에 파일을 추가하는 방법에는 여러 가지가 있습니다. 

자세한 내용은 GitHub 문서에서 이 가이드를 따르세요를 참조하세요. 

이 예제를 따라 하려면 인스턴스의 디렉터리 구조를 미러링하는 디렉터리 구조를 GitHub 리포지토리에 만들 수 있습니다.

아래의 YAML 항목은 리포지토리에서 구성 파일을 읽고, 그 내용을 Base64로 인코딩한 다음, 

이전과 마찬가지로 결과를 환경 변수에 추가합니다.

run: echo "NGINX_CONF_CONFIG_FILE=`cat nginx-server/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV

이 예제에서는 GitHub 리포지토리의 모든 구성 파일에 대해 이 과정을 반복합니다.

모든 것을 종합하기

마지막으로 GitHub의 샘플 참조 구현을 사용하여 배운 내용을 실제 작동하는 YAML 파일로 조합할 수 있습니다. 파일에 정의된 대로 사용자가 커밋 또는 풀 리퀘스트를 통해 리포지토리를 업데이트할 때마다 관련된 모든 GitHub Actions 스크립트가 실행됩니다. YAML의 마지막 항목은 인스턴스 관리자가 모든 관련 구성 파일을 업데이트하는 데 필요한 데이터를 포함하는 적절한 API 호출을 수행하는 curl 명령을 실행합니다.>

참고: YAML에서 여러 줄로 된 실행 항목(run: |)을 사용하면 YAML 인터프리터가 항목의 매개변수 부분에서 콜론 ":"을 텍스트로 처리하도록 지시하므로 curl 명령을 실행할 수 있습니다.

name: Managing NGINX configs with GitHub and GitHub Actions 
# Controls when the workflow will run 
on: 
  # Triggers the workflow on push or pull request events but only for the "main" branch 
  push: 
    branches: [ "main" ] 
  pull_request: 
    branches: [ "main" ] 
  
  # Allows you to run this workflow manually from the Actions tab 
  workflow_dispatch: 

# A workflow run is made up of one or more jobs that can run sequentially or in parallel 
jobs: 
  # This workflow contains a single job called "build" 
  build: 
    # The type of runner that the job will run on 
    runs-on: ubuntu-latest 

    # Steps represent a sequence of tasks that will be executed as part of the job 
    steps: 
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it 
      - uses: actions/checkout@v4 

      - name: Set environment variable for NMS API login credentials 
        run: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

      - name: Set environment variable for NMS API timestamp 
        run: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: API call to Instance Manager 
        run: | 
          curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept: application/json" --header "Authorization: Basic ${{ env.NMS_LOGIN }}" --header 'Content-Type: application/json' --data '{"configFiles": {"rootDir": "/etc/nginx","files": [{"contents": "${{ env.NGINX_CONF_CONFIG_FILE }}","name": "/etc/nginx/nginx.conf"},{"contents": "${{ env.MIME_TYPES_CONFIG_FILE }}","name": "/etc/nginx/mime.types"},{"contents": "${{ env.DEFAULT_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/default.conf"},{"contents": "${{ env.SSL_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/ssl.conf"}]},"externalIdType": "git","externalId": "${{ github.sha }}","updateTime": "${{ env.NMS_TIMESTAMP }}"}'