APISIX Declarative CLI로 선언적으로 APISIX 관리하기

Navendu Pottekkat

Navendu Pottekkat

September 22, 2023

Technology

APISIX 사용자는 주로 Admin API를 사용하여 APISIX를 구성합니다. 하지만 구성이 복잡해질수록 Admin API만으로 이를 관리하는 것이 점점 더 어려워집니다.

이를 더 쉽게 하기 위해, 우리는 APISIX Declarative CLI, 즉 ADC를 개발했습니다. 이 도구는 APISIX 구성을 선언적으로 정의할 수 있게 해줍니다.

이 글에서는 ADC를 사용하여 APISIX 구성을 관리하는 방법을 살펴보겠습니다.

APISIX 배포

시작하기 전에, 먼저 APISIX 인스턴스를 실행하여 상호 작용하고 구성해야 합니다. Docker에서 APISIX를 실행하려면 다음 명령어를 실행합니다:

curl -sL https://run.api7.ai/apisix/quickstart | sh

APISIX 사용에 대해 더 알아보려면 APISIX 문서를 참조하세요.

ADC 설치

ADC는 go install 명령어로 설치할 수 있습니다:

go install github.com/api7/adc@latest

이 명령어는 adc 바이너리를 $GOPATH/bin 디렉토리에 설치합니다.

이를 $PATH 환경 변수에 추가해야 합니다:

export PATH=$PATH:$GOPATH/bin

Go가 설치되어 있지 않다면, 최신 adc 바이너리를 다운로드하여 /bin 폴더에 추가할 수도 있습니다:

wget https://github.com/api7/adc/releases/download/v0.2.0/adc_0.2.0_linux_amd64.tar.gz
tar -zxvf adc_0.2.0_linux_amd64.tar.gz
mv adc /usr/local/bin/adc

다른 운영 체제용 바이너리는 릴리스 페이지에서 찾을 수 있습니다. 앞으로 이러한 바이너리는 Homebrew와 같은 패키지 관리자에 게시될 예정입니다.

adc가 설치되었는지 확인하려면 다음 명령어를 실행하세요:

adc --help

모든 것이 정상이라면, 사용 가능한 하위 명령어 목록과 사용 방법이 표시됩니다.

APISIX 인스턴스와 ADC 구성

배포된 APISIX 인스턴스와 함께 ADC를 구성하려면 다음 명령어를 실행합니다:

adc configure

이 명령어는 APISIX 서버 주소('http://127.0.0.1:9180'로 따라왔다면)와 토큰을 입력하라는 메시지를 표시합니다.

모든 것이 정확하다면, 다음과 같은 메시지가 표시됩니다:

ADC configured successfully!
Connected to APISIX successfully!

ping 하위 명령어를 사용하여 언제든지 APISIX와의 연결 상태를 확인할 수 있습니다:

adc ping

APISIX 구성 파일 검증

트래픽을 업스트림으로 전달하는 라우트가 포함된 기본 APISIX 구성을 만들어 보겠습니다:

name: "Basic configuration"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET

ADC가 실행 중인 APISIX 인스턴스에 연결되면, 이 구성을 적용하기 전에 검증할 수 있습니다:

adc validate -f config.yaml

구성이 유효하다면, 다음과 같은 응답을 받게 됩니다:

Read configuration file successfully: config name: Basic configuration, version: 1.0.0, routes: 1, services: 1.
Successfully validated configuration file!

APISIX 인스턴스에 구성 동기화

이제 유효한 구성을 연결된 APISIX 인스턴스와 동기화할 수 있습니다. 이를 위해 다음 명령어를 실행합니다:

adc sync -f config.yaml

이 명령어는 구성 파일에 선언된 대로 라우트와 서비스를 생성합니다:

creating service: "httpbin-service"
creating route: "httpbin-route"
Summary: created 2, updated 0, deleted 0

라우트가 제대로 생성되었는지 확인하기 위해 요청을 보내보겠습니다:

curl localhost:9080/anything -H "host:api7.ai"

모든 것이 정상이라면, httpbin.org로부터 응답을 받게 됩니다.

로컬과 실행 중인 구성 비교

이제 config.yaml 파일의 로컬 구성을 업데이트하여 다른 라우트를 추가해 보겠습니다:

name: "Basic configuration"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route-anything
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET
  - name: httpbin-route-ip
    service_id: httpbin-service
    uri: "/ip"
    methods:
      - GET

이 구성을 APISIX와 동기화하기 전에, ADC를 사용하여 기존 APISIX 구성과의 차이점을 확인할 수 있습니다. 이를 위해 다음 명령어를 실행합니다:

adc diff -f config.yaml

구성의 추가 및 삭제 사항을 확인하고 적용하기 전에 무엇이 변경되었는지 이해할 수 있습니다.

OpenAPI 정의를 APISIX 구성으로 변환

ADC는 OpenAPI 정의 작업도 기본적으로 지원합니다. ADC는 OpenAPI 형식의 정의를 APISIX 구성으로 변환할 수 있습니다.

예를 들어, API를 OpenAPI 형식으로 문서화했다면:

openapi: 3.0.0
info:
  title: httpbin API
  description: Routes for httpbin API
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Returns anything that is passed in the request data
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Successfully return anything
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Returns the IP address of the requester
      operationId: getIP
      responses:
        "200":
          description: Successfully return IP
          content:
            application/json: {}

openapi2apisix 하위 명령어를 사용하여 이를 APISIX 구성으로 변환할 수 있습니다:

adc openapi2apisix -o config.yaml -f openAPI.yaml

이 명령어는 다음과 같은 구성 파일을 생성합니다:

name: ""
routes:
- desc: Returns anything that is passed in the request data
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Returns the IP address of the requester
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Routes for httpbin API
  id: ""
  name: httpbin API
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

보시다시피, 구성이 불완전하며 여전히 많은 구성을 수동으로 추가해야 합니다. 우리는 OpenAPI 정의와 APISIX 구성 간의 격차를 줄이기 위해 ADC를 개선하고 있습니다.

팁: 자동 완성 사용

ADC로 많은 작업을 할 수 있으며, 기능 목록은 계속 증가할 것입니다. 어떤 하위 명령어를 사용하는 방법을 배우려면 --help 또는 -h 플래그를 사용하여 하위 명령어의 문서를 볼 수 있습니다.

더 쉽게 하기 위해, completion 하위 명령어를 사용하여 셸 환경에 대한 자동 완성 스크립트를 생성할 수 있습니다. 예를 들어, zsh 셸을 사용한다면 다음 명령어를 실행합니다:

adc completion zsh

그런 다음 출력을 .zshrc 파일에 복사하여 붙여넣으면, adc를 사용할 때 힌트가 표시됩니다.

ADC는 아직 초기 단계이며 지속적으로 개선되고 있습니다. 프로젝트에 대해 더 알아보고, 버그를 보고하거나 기능을 제안하려면 github.com/api7/adc를 방문하세요.

Tags:
APISIX configuration
Declarative configuration
CLI