Github 사용하여 NGINX 구성 관리

이 포스트에서는 GitHub 및 Instance Manager 를 사용하여 변경 사항이 있을 때마다 자동으로 인스턴스에 푸시하여 NGINX 구성을 관리하는 방법을 설명합니다.

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

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

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

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

목차

1. Instance Manager API
2. GitHub Actions
2-1. Actions Secret 설정
2-2. Actions Variables 설정
2-3. NGINX 구성 업데이트를 위한 Instance Manager REST API 호출의 구조
2-4. Base64 인코딩
2-5. Instance Manager 자격 증명
2-6. TimeStamp
2-7. Github NGINX 구성
2-8. 하나로 합치기
3. NGINX 참조 구현

1. Instance Manager API

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

2. GitHub Actions

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

이 포스트의 예제에서는 바로 사용할 수 있는 GitHub Actions와 Linux 명령을 활용합니다. 이 두 가지를 사용하여 Instance Manager API를 통해 NGINX 인스턴스에서 GitHub에서 관리하는 NGINX 구성 파일을 업데이트 하는 방법을 배웁니다. 시작하려면 GItHub 문서에서 다음 단계에 따라 리포지토리에서 Actions를 실행하기 위한 새 YAML을 만듭니다.

2-1. Actions Secret 설정 (Github)

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

Instance Manager 자격 증명을 리포지토리에 저장하는 대신 GitHub를 사용하면 리포지토리 변수로 secret을 정의할 수 있습니다. 이러한 변수는 작업 환경에서 액세스할 수 있지만, 로그에는 숨겨져 있습니다. 다음 단계에 따라 Instance Manager username 및 password key를 secret으로 저장하여 API 호출을 인증하는 데 사용할 수 있습니다.

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

리포지토리 비밀 옵션이 표시된 기술 플랫폼 스크린샷

2-2. Actions Variables 설정 (Github)

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

리포지토리 변수 옵션을 표시하는 기술 플랫폼 스크린샷

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

2-3. NGINX 구성 업데이트를 위한 Instance Manager REST API 호출의 구조

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

이 예에서는 단일 인스턴스를 업데이트하기 위해 API 호출을 사용합니다. 하지만 Instance Manager 내에서 인스턴스 그룹을 구성할 수도 있습니다. 이렇게 하면 GitHub에서 새 구성이 푸시될 때마다 그룹의 인스턴스를 업데이트할 수 있습니다.

다음은 Instance Manager의 구성 업데이트 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}"

}'}'

URI Parameters:

  • System Identifier – NGINX가 실행 중인 시스템을 식별하는 고유 키입니다. 이 예제에서 이 데이터는 GitHub Actions Variables 인터페이스에 정의되어 있습니다.
  • NGINX Instance Identifier – 시스템에서 특정 NGINX 인스턴스를 식별하는 고유 키입니다. 이 예제에서 이 데이터는 GitHub Actions Variable 인터페이스에 정의되어 있습니다.

Header Parameters:

  • Authorization – Instance Manager가 API 호출을 인증하는 데 사용하는 권한 부여 방법 및 Base64로 인코딩된 자격 증명입니다. 이 예에서는 리포지토리에 설정된 secret에서 가져온 자격 증명 데이터와 함께 기본 인증을 사용합니다.

Json Data Parameter:

  • configFiles – 업데이트 중인 구성 파일의 Base64 인코딩된 내용과 NGINX를 실행하는 시스템에서의 해당 위치입니다. 또한 NGINX 구성 파일의 root 디렉토리 경로를 제공해야 하며, 가장 일반적으로 다음과 같이 구성됩니다: /etc/nginx
  • externalIdType – Instance Manager에 대한 구성 파일의 소스를 식별하는 레이블입니다. 가능한 값은 git 또는 other입니다. 이 예제에서는 이 매개 변수를 git으로 하드코딩했습니다.
  • externalId – 구성 파일의 변경 사항을 식별하는 Git commit Secure Hash Algorithm(SHA)입니다.
  • updateTime – 현재 날짜와 시간을 %T-%m-%dT%H:%M:%SZ 형식으로 포함하는 문자열입니다.

2-4. Base64 인코딩

Instance Manager의 API 사양을 수용하려면 특정 데이터를 Base64 형식으로 인코딩하여 변환해야 합니다. 기존 GitHub Actions를 사용하여 이 작업을 수행할 수 있는 기본 방법은 없지만 YAML 에서 액세스할 수 있는 Linux 도구를 사용할 수 있습니다.

2-5. Instance Manager 자격 증명

먼저 앞서 secret으로 정의한 Instance Manager 로그인 자격 증명을 참조하여 연결합니다. 그런 다음 문자열을 Base64로 변환하여 Linux 변수 (NMS_LOGIN)로 에코하고 그 결과를 Actions 런처에서 액세스할 수 있는 미리 정의된 환경 변수 (GITHUB_ENV)에 추가합니다.

실행: echo “NMS_LOGIN=echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64” >> $GITHUB_ENV

2-6. TimeStamp

Instance Manager API를 사용하려면 특정 API 페이로드와 함께 특정 형식의 timestamp가 전송되어야 합니다. Linux date 명령을 사용하여 해당 형식의 timestamp를 만들 수 있습니다. 앞의 예와 마찬가지로 구성된 문자열을 Linux 환경에 변수로 추가합니다.

실행: echo “NMS_TIMESTAMP=date -u +"%Y-%m-%dT%H:%M:%SZ"” >> $GITHUB_ENV

2-7. Github NGINX 구성

다음으로 리포지토리에 관리하려는 NGINX 구성을 추가합니다. GitHub 리포지토리에 파일을 추가하는 방법에는 여러 가지가 있습니다. 자세한 내용은 GitHub 문서에서 이 가이드를 참조하세요. 이 예제를 따라 하려면 인스턴스의 디렉토리 구조를 미러링하는 디렉토리 구조를 생성하면 됩니다.

아래의 YAML 항목은 리포지지토리에서 구성 파일을 읽고, 그 내용을 Base64로 인코딩한 다음 이전과 마찬가지로 그 결과를 환경 변수에 추가합니다.

실행: echo “NGINX_CONF_CONFIG_FILE=cat nginx-server/etc/nginx/nginx.conf | base64 -w 0” >> $GITHUB_ENV

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

2-8. 하나로 합치기

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

참고: YAML에서 여러 줄로 된 실행 항목(실행: |)을 사용하면 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 }}”}’

3. NGINX 참조 구현

There are several ways to issue a configuration update API call after a file has changed. GitHub Actions are the most convenient method for people who use GitHub, but they don’t work with GitLab or standalone Git implementations. To address these use cases, we developed a companion shell script reference implementation that can be triggered from the command line or called from a custom script.

결론적으로, Instance Manager API에 대한 새로운 확장 기능은 구성 업데이트, 롤백 및 버전 기록을 현대적이고 분산된 방식으로 관리할 수 있는 강력한 도구를 제공합니다. 이 확장 기능을 third-party 텍스트 파일 및 코드 관리 플랫폼(예: GitHub)과 결합하면 직관적인 웹 기반 사용자 인터페이스를 통해 추가적인 워크플로우, CI/CD, 협업 및 이슈 추적 기능을 사용할 수 있습니다.

NGINX Plus를 직접 사용해 보시려면 30일 무료 평가판을 신청하거나 NGINX STORE에 연락하여 논의하십시오.

NGINX에 대한 최신 정보들을 빠르게 전달받고 싶으시다면, 아래의 뉴스레터를 구독하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required