NGINX Agent 컨테이너 이미지 빌드

NGINX Agent 는 NGINS OSS 혹은 NGINX Plus 인스턴스를 위한 companion daemon으로, 동일한 컨테이너 내부에서 동작해야 합니다. NGINX Agent GitHub 리포지토리에는 NGINX Agent와 NGINX OSS 혹은 NGINX Plus가 번들로 구성된 커스팀 컨테이너 이미지를 빌드할 때 사용할 수 있는 Dockerfile이 있습니다.

목차

1. 환경 설정
 1-1. 컨테이너 엔진 설치
 1-2. GNU Make 패키지 설치
 1-3. nginx-agent 리포지토리 복제
 1-4. agent 바이너리 다운로드
 1-5. NGINX Plus 인증서, 키 다운로드
2. Docker을 사용한 NGINX Agent 공식 이미지 빌드
3. NGINX Agent 컨테이너 실행
 3-1. gRPC 인터페이스 활성화
 3-2. REST 인터페이스 활성화
4. 특정 OS 대상 NGINX Agent 이미지 빌드
 4-1. NGINX OSS 이미지 빌드
 4-2. 배포판별 빌드 명령어 예제
 4-3. NGINX Plus 이미지 빌드
 4-4. 배포판별 NGINX Plus 빌드 명령어 예제

1. 환경 설정

1-1. 컨테이너 엔진 설치

Docker 혹은  Podman을 통해 NGINX Agent 컨테이너 이미지를 관리할 수 있습니다. 서비스의 실행 상태를 확인 후, 선호하는 컨테이너 엔진에 대한 설치 지침을 따르세요.

Note:

이 문서의 예제는 주로 Docker 명령어를 사용합니다. Docker을 사용하지 않을 경우 적절한 Podman 명령어로 대체하세요.

1-2. GNU Make 패키지 설치

nginx-agent GitHub 리포지토리에서 제공하는 NGINX Agent 컨테이너 이미지를 빌드하기 위해서는 GNU Make 패키지를 사용해야합니다.

Make가 사전에 설치되지 않은 경우, 운영 체제의 적절한 패키지 매니저를 통해서 설치하세요.

예를 들어, Ubuntu Advanced Packaging Tool (APT)를 사용해서 make를 설치하는 경우 예시의 apt install 명령어를 사용하세요. 어떤 경우에는 진행하기 전에 운영 체제에서 패키지 소스 목록을 업데이트하는 것이 도움이 될 수 있습니다.

1. 패키지 소스 목록을 업데이트합니다.

$ sudo apt update

2. make 패키지를 설치합니다.

$ sudo apt install make

1-3. nginx-agent 리포지토리 복제

NGINX Agent GitHub 리포지토리에는 Dockerfile과 이미지 빌드에 도움을 주는 스크립트가 있습니다.

아래의 명령어를 사용하여 HTTPS 혹은 SSH로 GitHub 리포지토리를 복제하세요.

HTTPS
$ git clone https://github.com/nginx/agent.git
SSH
$ git clone git@github.com:nginx/agent.git

1-4. agent 바이너리 다운로드

NGINX와 컨테이너 이미지를 빌드하기 전에, agent 바이너리를 빌드하거나 다운로드 해야합니다.

agent 바이너리 패키지는 GitHub의 NGINX Agent 릴리즈 페이지에서 다운로드 할 수 있습니다.

컨테이너 이미지에 사용할 운영 체제에 맞는 바이너리 패키지를 다운로드하세요.

다운로드한 패키지의 위치와 이름을 확인하세요. 이미지를 빌드하는 make 명령어를 사용할 때 필요로 합니다. (예제 명령어에선 [PATH-TO-PACKAGE]로 참조됨)

1-5. NGINX Plus 인증서, 키 다운로드

이 과정은 NGINX Plus를 사용할 경우 필요합니다. NGINX OSS를 사용할 경우 생략해도 됩니다.

NGINX Plus와 이미지를 빌드하려면, NGINX Plus 라이센스와 함께 SSL 인증서와 개인 키 파일을 필요로 합니다. 이 파일들은 스크립트가 NGINX Plus 패키지를 다운로드할 패키지 리포지토리에 대한 엑세스 권한을 부여합니다.

  1. MyF5 사용자 포털에 로그인합니다.
  2.  My Products and Plans > Subscriptions으로 이동합니다.
  3. 구독중인 제품을 선택합니다.
  4. SSL 인증서 파일과 개인 키 파일을 다운로드합니다.
  5. SSL 인증서와 개인 키 파일을 nginx-agent 리포지토리를 복제한 디렉토리로 옮깁니다.
  • Makefile은 해당 파을들을 ./build/certs 경로에서 찾습니다. nginx-agent 리포지토리를 $HOME 디렉토리로 복제했다 가정할 경우, 파일의 이름을 다음과 같이 변경하고 옮겨야합니다.
$ mkdir -p $HOME/nginx-agent/build/certs
$ mv nginx-repo-S-X00012345.key $HOME/nginx-agent/build/certs/nginx-repo.key
$ mv nginx-repo-S-X00012345.crt $HOME/nginx-agent/build/certs/nginx-repo.crt
  • 예시의 인증서 파일과 키 파일의 이름을 실제 파일 이름으로 변경하세요.
  • build/certs 디렉토리의 파일 이름은 예제의 파일 이름과 동일해야 합니다.

2. Docker을 사용한 NGINX Agent 공식 이미지 빌드

NGINX OSS

Dockerfile이 위치한 디렉토리로 변경합니다.

$ cd scripts/docker/official/nginx-oss-with-nginx-agent/alpine/
  • 최신 NGINX Agent와 최신 mainline 버전의 NGINX가 포함된 이미지를 빌드하려면 다음 명령어를 사용합니다.
$ docker build -t nginx-agent . --no-cache -f ./Dockerfile.mainline
  • 최신 NGINX Agent와 최신 stable 버전의 NGINX가 포함된 이미지를 빌드하려면 다음 명령어를 사용합니다.
$ docker build -t nginx-agent . --no-cache -f ./Dockerfile.stable
NGINX Plus

1. MyF5 사용자 포털로 로그인하여 “nginx-repo.crt”, “nginx-repo.key” 파일을 다운로드합니다. 해당 파일들은 NGINX Plus 체험 패키지에서도 제공됩니다.

2. 파일들을 Dockerfile이 위치한 scripts/docker/official/nginx-plus-with-nginx-agent/alpine/로 복사합니다.

3. 최신 NGINX Agent와 최신 버전의 NGINX Plus가 포함된 이미지를 빌드하려면 다음 명령어를 사용합니다.

$ cd scripts/docker/official/nginx-plus-with-nginx-agent/alpine/

다음 명령어를 사용하여 이미지를 빌드합니다.

$ docker build -t nginx-agent . \
  --no-cache -f ./Dockerfile \
  --secret id=nginx-crt,src=nginx-repo.crt \
  --secret id=nginx-key,src=nginx-repo.key

3. NGINX Agent 컨테이너 실행

Docker를 사용해서 NGINX Agent 컨테이너를 실행하는 예제입니다.

$ docker run --name nginx-agent -d nginx-agent

Note:

더 많은 설정 옵션을 알아보려면, NGINX Agent 설정 가이드를 참고하세요.

3-1. gRPC 인터페이스 활성화

NGINX Agent 컨테이너를 NGINX One 혹은 Nginx Instance Manager 인스턴스에 연결하려면, gRPC 인터페이스를 활성화해야 합니다. 활성화하기 위해선 NGINX Agent 설정 파일인 nginx-agent.conf 파일을 수정해야 합니다. 예시는 다음과 같습니다.

server:
  host: 127.0.0.1 # mock control plane host
  grpcPort: 54789 # mock control plane gRPC port

# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION
tls:
  enable: false
  skip_verify: true

3-2. REST 인터페이스 활성화

컨트롤 플레인이 REST API를 필요로 하면, NGINX Agent 설정 파일인 nginx-agent.conf 파일을 수정하여 NGINX Agent의 REST API를 노출시킬 수 있습니다. 예시는 다음과 같습니다.

api:
  host: 0.0.0.0
  port: 8038

 nginx-agent.conf 파일을 업데이트한 후에는 다음 명령어를 사용해 업데이트된 nginx-agent.conf 마운트하고 8038 포트를 노출하여 컨테이너를 실행할 수 있습니다.

$ docker run --name nginx-agent -d \
  --mount type=bind,source="$(pwd)"/nginx-agent.conf,target=/etc/nginx-agent/nginx-agent.conf,readonly \
  -p 127.0.0.1:8038:8038/tcp \
  nginx-agent

4. 특정 OS 대상 NGINX Agent 이미지 빌드

주의:

공식적으로 지원하는 유일한 기본 운영 체제는 Alpine 입니다. 하단의 다른 운영 체제의 지침은 정보 제공 및 테스트 목적으로만 제공됩니다.

NGINX Agent GitHub 리포지토리에는 특정 운영 체제와 버전의 이미지를 빌드할 때 사용할 수 있는 Make 명령어들이 있습니다.

  • make official-oss-image는 NGINX Agent와 NGINX OSS를 포함하는 이미지를 빌드합니다.
  • make official-plus-image는 NGINX Agent와 NGINX Plus를 포함하는 이미지를 빌드합니다.

NGINX Agent 이미지를 빌드하는 make 명령어에 다음과 같은 인자를 사용할 수 있습니다.

인자정의
PACKAGE_NAME필수. agent 바이너리 패키지의 전체경로. make 명령어보다 앞에 입력되어야 합니다.
OS_RELEASE베이스 이미지로 사용할 Linux 배포판. 리포지토리의 Makefile에서 설정할 수도 있습니다.
OS_VERSION베이스 이미지로 사용할 Linux 배포판의 버전. 리포지토리의 Makefile에서 설정할 수도 있습니다.

지원하는 배포판을 참고하여 사용할 수 있는 베이스 이미지를 확인하세요. Docker Hub에서 각 배포판의 공식 이미지와 버전을 확인할 수 있습니다.

NGINX Agent Dockerfile을 통해 컨테이너 이미지를 빌드할 때, 아래 내용을 명심하세요.

  • 몇몇 운영 체제에서는 make 명령어를 사용하기 위해 root 권한(sudo)을 필요로 합니다.
  • 제공된 make 명령어 대신 docker build 혹은 podman build 명령어를 사용하려면, nginx-agent 리포지토리의 root 디렉토리에서도 사용해야 합니다.

4-1. NGINX OSS 이미지 빌드

아래 make 명령어를 사용해 Alpine 3.19를 베이스 이미지로 사용하는 기본 이미지를 빌드합니다.

PACKAGE_NAME=[PATH-TO-PACKAGE] make official-oss-image

4-2. 배포판별 빌드 명령어 예제

ALMA LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=almalinux make oss-image
ALPINE LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=alpine make oss-image
AMAZON LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=amazonlinux make oss-image
DEBIAN
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=debian make oss-image
ORACLE LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=oraclelinux make oss-image
ROCKY LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=rockylinux make oss-image
UBUNTU

아래의 명령어는 최신 LTS 버전의 Ubuntu 이미지를 베이스 이미지로 사용합니다.

PACKAGE_NAME=[PATH-TO-PACKAGE] make oss-image OS_RELEASE=ubuntu

4-3. NGINX Plus 이미지 빌드

주의:

NGINX Agent를 NGINX Plus와 사용하려면 라이센스가 필요합니다. NGINX Plus 인증서, 키 다운로드 과정을 먼저 완료하세요.

아래 make 명령어를 사용해 Ubuntu 24.04 (Noble)를 베이스 이미지로 사용하는 기본 이미지를 빌드합니다.

PACKAGE_NAME=[PATH-TO-PACKAGE] make official-plus-image

4-4. 배포판별 NGINX Plus 빌드 명령어 예제

ALPINE LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=alpine make official-plus-image
AMAZON LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=alpine make official-plus-image
CENTOS
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=centos OS_VERSION=7 make official-plus-image
DEBIAN
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=debian OS_VERSION=bullseye-slim make official-plus-image
ORACLE LINUX
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=oraclelinux make official-plus-image
RHEL
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=redhatenterprise make official-plus-image
SUSE
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=suse OS_VERSION=sle15 make official-plus-image
UBUNTU
PACKAGE_NAME=[PATH-TO-PACKAGE] OS_RELEASE=ubuntu make official-plus-image

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

* indicates required