GitHub을 사용하여 NGINX 구성 관리

소프트웨어 설정, 옵션 및 구성은 다양한 형태로 존재합니다. 스펙트럼의 한 쪽 끝에는 직관적이면서도 잘못된 상태에 대한 보호 장치를 제공하도록 고안된 매끄럽고 반응성이 뛰어난 GUI가 있습니다. 반대쪽에는 텍스트 파일이 있습니다. 엔지니어와 DevOps 팀 모두 텍스트 파일을 명확성, 자동화 잠재력, 최소 사용 요구 사항(여러 개의 터미널 창을 열어 놓았을 가능성이 높죠?) 때문에 칭찬하지만, 이를 사용하여 소프트웨어를 구성하는 데에는 분명한 단점이 있습니다. 예를 들어, 텍스트 파일을 잘못 구성하여 소프트웨어 패키지를 충돌시킨 적이 없는 Linux 사용자를 찾아 보세요.

NGINX는 유일한 일체형 소프트웨어 프록시, 로드 밸런서, 웹 서버 및 API 게이트웨이로서 현대 인터넷 인프라의 핵심 구성 요소입니다. 대부분의 경우 Linux 커널을 기반으로 하는 운영 체제를 기반으로 하는 인프라입니다. 이러한 생태계와 이를 지원하는 전문가에 맞춰 NGINX는 텍스트 기반 구성을 크게 사용합니다.

F5 NGINX 인스턴스 관리자 모듈은 오랫동안 NGINX 관련 구성 오케스트레이션을 위한 최적의 솔루션이었습니다. 직관적인 사용자 인터페이스와 API를 통해 원격, 일괄 구성 관리를 위한 고급 기능을 제공하며, 지원 문서와 보호 장치도 제공됩니다. 그러나 개별 NGINX 구성 파일은 코드와 매우 유사하며 소프트웨어 팀은 이미 코드를 관리하기 위한 놀라운 도구를 보유하고 있습니다. 깃(Git) Git은 개발자와 운영팀에 텍스트 파일 워크플로를 관리하는 데 필요한 다양한 기능을 제공합니다.

Instance Manager가 Git 및 기타 외부 시스템과 새롭게 통합되어 버전 제어, 분산 기여, 승인 워크플로, 팀 조정과 같은 기능을 사용할 수 있습니다. GitHub 및 GitLab과 같은 플랫폼은 웹 기반 사용자 인터페이스를 통해 이 기능 세트를 지속적인 통합/지속적인 배포(CI/CD), 협업, 문제 추적 및 기타 귀중한 기능으로 확장합니다.

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

인스턴스 관리자 API

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

GitHub 액션

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

이 블로그의 예에서는 기본 제공 GitHub Actions와 Linux 명령을 사용합니다. Instance Manager API를 통해 NGINX 인스턴스에서 GitHub 관리 NGINX 구성 파일을 업데이트하는 방법을 배우게 됩니다. 시작하려면 GitHub Docs에서 다음 단계를 따라 저장소에서 Actions를 실행하기 위한 새 YAML을 만듭니다.

설정 작업 비밀

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

Instance Manager 자격 증명을 저장소에 저장하는 대신, GitHub에서는 비밀을 저장소 변수로 정의 할 수 있습니다. 이러한 변수는 Actions 환경에서는 접근할 수 있지만 로그에는 숨겨져 있습니다. 다음 단계 에 따라 Instance Manager 사용자 이름과 비밀번호 키를 비밀로 저장하면 이를 사용하여 API 호출을 인증할 수 있습니다.

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

동작 변수 설정

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

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

NGINX 구성 업데이트를 위한 Instance Manager REST API 호출의 해부학

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

이 예제에서는 API 호출을 사용하여 단일 인스턴스를 업데이트합니다. 하지만 Instance Manager 내에서 인스턴스 그룹을 구성하는 것도 가능합니다. 그렇게 하면 GitHub에서 새로운 구성이 푸시될 때마다 그룹의 모든 인스턴스를 업데이트할 수 있습니다. 자세한 내용은 게시 구성에 대한 방법 가이드를 참조하세요.

Instance Manager의 구성 업데이트 REST API 호출에 대한 세부 내용은 다음과 같습니다.

https://{인스턴스 관리자 호스트 이름}/api/platform/v1/systems/{시스템 ID}/인스턴스/{인스턴스 ID}/config' 
--헤더 "수락: application/json" 
--헤더 "권한 부여: 기본 {로그인 자격 증명}" 
--header 'Content-Type: application/json'
--data '{
"configFiles": '{
"rootDir": "/etc/nginx",
"files": [{
"contents": "{NGINX 구성 파일}",
"name": "{시스템의 구성 파일 경로}"
}]
},
"externalIdType": "{구성 소스}",
"externalId": "{커밋 해시}",
"updateTime": "{타임스탬프}"
}'}'

URI 매개변수

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

헤더 매개변수

• 인증 – Instance Manager가 API 호출을 인증하는 데 사용하는 인증 방법 및 Base64 인코딩된 자격 증명입니다. 이 예제에서는 저장소에 설정된 비밀에서 나온 자격 증명 데이터를 사용하여 기본 인증을 사용합니다.

JSON 데이터 매개 변수

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

Base64 인코딩

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

인스턴스 관리자 자격 증명

먼저, 앞서 비밀로 정의한 인스턴스 관리자 로그인 자격 증명을 참조하여 연결합니다. 그런 다음 문자열을 Base64로 변환하고 Linux 변수( NMS_LOGIN )로 echo한 후 결과를 Actions 러너에서 액세스할 수 있는 미리 정의된 환경 변수( GITHUB_ENV )에 추가합니다.

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

타임스탬프

Instance Manager API는 특정 API 페이로드와 함께 특정 형식의 타임스탬프를 전송하도록 요구합니다. Linux의 date 명령을 사용하여 해당 형식으로 타임스탬프를 구성할 수 있습니다. 이전 예제와 유사하게, 생성된 문자열을 Linux 환경에 변수로 추가합니다.

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

NGINX 구성

다음으로, 관리하려는 NGINX 구성을 저장소에 추가합니다. GitHub 저장소에 파일을 추가하는 방법에는 여러 가지가 있습니다. 자세한 내용은 GitHub 설명서의 가이드를 참조하세요 . 예를 들어, 인스턴스의 구조를 미러링하는 GitHub 저장소에 디렉토리 구조를 만들 수 있습니다.

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

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

우리의 예제에서는 GitHub 저장소의 모든 설정 파일에 대해 이 작업을 반복합니다.

모두 합치기

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

메모: YAML에서 다중 줄 실행 항목( run: | )을 사용하여 curl 명령을 실행합니다. 이는 YAML 인터프리터가 항목의 매개변수 부분에서 콜론 ":"을 텍스트로 처리하도록 지시하기 때문입니다.

이름: GitHub 및 GitHub Actions로 NGINX 구성 관리 # 워크플로가 실행되는 시점을 제어합니다.# 푸시 또는 풀 요청 이벤트에서 워크플로를 트리거하지만 "main" 브랜치에만 해당합니다.push: branches: [ "main" ] pull_request: branches: [ "main" ] # Actions 탭에서 이 워크플로를 수동으로 실행할 수 있습니다.workflow_dispatch: # 워크플로 실행은 순차적으로 또는 병렬로 실행할 수 있는 하나 이상의 작업으로 구성됩니다.jobs: # 이 워크플로에는 "build"라는 단일 작업이 포함됩니다.build: # 작업이 실행되는 러너 유형 runs-on: ubuntu-latest # 단계는 작업의 일부로 실행되는 일련의 작업을 나타냅니다.steps: # 작업에서 액세스할 수 있도록 $GITHUB_WORKSPACE에서 리포지토리를 체크아웃합니다.- uses: actions/checkout@v4 - name: NMS API 로그인 자격 증명에 대한 환경 변수 설정: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME } }:${{ secrets.NMS_PASSWORD } }" | base64`" >> $GITHUB_ENV - 이름: NMS API 타임스탬프 실행을 위한 환경 변수 설정: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV - name: base64로 인코딩된 구성 파일을 위한 환경 변수를 설정합니다. echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV - name: base64로 인코딩된 구성 파일에 대한 환경 변수를 설정합니다. echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV - name: base64로 인코딩된 구성 파일에 대한 환경 변수를 설정합니다. echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV - name: base64로 인코딩된 구성 파일에 대한 환경 변수를 설정합니다. echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV - name: Instance Manager 실행에 대한 API 호출: | curl --location 'https://${{ vars.NMS_HOSTNAME } }/api/플랫폼/v1/시스템/${{ vars.SYSTEM_ID } }/인스턴스/${{ vars.INSTANCE_ID } }/config' --header "수락: application/json" --header "권한 부여: 기초적인${{ env.NMS_LOGIN } }" --header '콘텐츠 유형: 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 } }","업데이트시간": "${{ env.NMS_TIMESTAMP } }"}' 

NGINX 참조 구현

파일이 변경된 후에 구성 업데이트 API 호출을 실행하는 방법은 여러 가지가 있습니다. GitHub Actions는 GitHub을 사용하는 사람들에게 가장 편리한 방법이지만, GitLab이나 독립형 Git 구현에는 작동하지 않습니다. 이러한 사용 사례를 해결하기 위해 명령줄에서 트리거하거나 사용자 정의 스크립트에서 호출할 수 있는 동반 셸 스크립트 참조 구현을 개발했습니다.

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

여러분의 의견을 듣고 싶습니다! 시도해 보시고 의견을 댓글로 알려주시거나 NGINX 커뮤니티 Slack 채널에 가입해 주시기 바랍니다.