소개

본 장에서는 AnyAPI 게이트웨이의 특징 및 설정 파일의 설정 방법에 대해 설명합니다.

개요

AnyAPI 게이트웨이는 클라이언트의 API 요청을 AnyAPI 게이트웨이에 등록된 라우팅 정보에 따라 각 API 서버들로 전달하고, 각 API 서버들로부터 받은 응답들을 취합하여 클라이언트에 전달합니다.

또한 라우팅 정보를 통하여 요청 URI 검사, 파라미터 검사 등을 수행합니다. 여러 검사 결과에 따라 라우팅할 Backend API 서버의 URI가 특정되면 해당 정보를 마스터로 전달하여 인증/인가, Qos 처리를 추가로 진행합니다. 이후 다시 게이트웨이를 통하여 실제 API 서버로 라우팅을 한 후 응답을 돌려 받습니다.

특징

AnyAPI 게이트웨이의 특징은 다음과 같습니다.

  • Non-Blocking 방식

    I/O 멀티플렉싱 방식의 입출력 처리를 하며, 특정 I/O 채널의 버퍼링에 다른 채널 처리가 영향받지 않도록 fully non-blocking 방식의 처리를 구현하고 있습니다. 기본적으로 1개의 프로세스로 이루어져 하나의 이벤트 스레드에서 non blocking I/O를 통해 HTTP 프로토콜을 처리하며 데이터에 대한 암복호화 처리, blocking I/O가 필요한 경우 워커 스레드를 통해 처리합니다.

  • HTTP 프로토콜 지원

    HTTP 버전으로 1.0, 1.1 두 종류를 지원하며, HTTPS 프로토콜을 지원합니다. 또한 HTTP로 들어온 요청을 HTTPS로 변환하는 기능도 지원합니다.

  • 라우팅 및 변환

    HTTP 요청이 들어오면 Path나 Method를 기반으로 API를 식별하는 라우팅을 지원합니다. Path에서 와일드카드(*)를 사용하여 모든 문자열에 대응할 수 있습니다. 또한 Path나 Method를 다른 Path, Method로 변환을 지원합니다. Path의 경우 특정 예약어를 통해 지정한 문자열로 대체할 수 있습니다.

    항목 설명

    {FullPath}

    들어온 요청의 전체 Path로 치환합니다.

    {StagePath}

    Stage의 basePath로 치환합니다.

    {Path}

    들어온 요청의 전체 Path에서 stage basePath를 제외한 Api Path로 치환합니다.

  • 목적지 설정

    서버나 서버 그룹 또는 IP를 직접 지정하여 해당 경로로 프록시 또는 리다이렉트 응답을 돌려주는 기능을 지원합니다. 서버 그룹을 설정하여 라운드로빈 방식, Weight 방식의 목적지 라우팅을 설정할 수 있습니다.

  • API 배포 및 테스트 기능

    구현한 API는 배포 버튼을 누르기 전까지 외부에 노출되지 않습니다. 배포하지 않은 API는 AnyAPI의 테스트 기능을 통해 정상적으로 동작하는지, API 서버가 어떤 응답을 돌려주는지, API 서버로부터 응답이 얼마나 걸리는지를 확인할 수 있습니다.

  • 인증/인가

    인증된 사용자를 확인하는 인증 기능과 API 호출 횟수를 제한할 수 있는 OQS 인가 기능을 제공합니다. QOS는 STAGE별로 설정이 가능하며 분당, 시간당, 하루당 얼만큼 처리할 것인지 지정할 수 있습니다.

    다음은 AnyAPI 게이트웨이에서 현재 제공하는 인증 방식의 종류입니다.

    구분 설명

    API Key 인증

    HTTP 헤더에 들어온 x-api-key 헤더를 확인하여 등록된 API Key인지 확인하여 사용자를 인증하는 방식입니다.

    OAuth 인증

    OAuth 서버로부터 접근 토큰을 발급받아 Authorization 헤더에 넣어서 요청하면 AnyAPI 게이트웨이는 Authorization 토큰이 유효한지 체크하여 사용자를 인증하는 방식입니다.

    Terminal 인증

    TerminalLogin API를 호출하여 단말 토큰을 생성한 후 x-api-token, x-api-pk-number 헤더에 넣어서 요청하면 AnyAPI 게이트웨이는 해당 토큰이 유효한지 체크하여 사용자를 인증하는 방식입니다.

게이트웨이 환경

게이트웨이 설정 파일

AnyAPI 게이트웨이에서 사용하는 설정 파일은 초기 게이트웨이 설정과 동적으로 반영되는 게이트웨이 설정을 저장하기 위해 사용합니다.

설치 초기에 설정 파일은 다음과 같은 위치에 존재합니다.

${GATEWAY_HOME}/config/defaultApiGateway21

다음은 AnyAPI 게이트웨이 설정 파일의 작성 예시입니다. (현재 JSON 형식만 지원)

IP, PORT, Monitoring 설정을 제외하고는 사용자가 직접 수정할 수 없으며, WebAdmin을 통해서만 수정이 가능합니다.

  • gatewayConfig

    게이트웨이에 대한 기본 메타 데이터 설정 정보입니다.

    "gatewayConfig": {
    "gatewayGroupId": "${GROUP_ID}", (1)
    "id": "${ID}", (2)
    "name": "${NAME}", (3)
    "protocol": "HTTP" (4)
    "thread_pool": { (5)
       "min":10,
       "max":50
       }
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) gatewayGroupId

    게이트웨이가 배포되는 그룹의 ID입니다.

    (2) id

    게이트웨이의 고유 ID입니다.

    (3) name

    게이트웨이의 이름입니다. 설정하지 않는 경우 ID를 사용합니다.

    (4) protocol

    게이트웨이가 사용하는 프로토콜입니다. (기본값: HTTP)

    (5) thread_pool

    기본 스레드 풀을 설정합니다.

    실제 파싱이나 매핑이 이루어질 때 사용됩니다. 이때 스레드 풀은 선형적으로 증가하지는 않으며, 상황에 맞게 max 값까지 증가합니다.

    • min: 부팅 시 최소로 뜨는 스레드 개수

    • max: 최대로 늘어나는 스레드 개수

  • staticResources

    게이트웨이가 처음 부팅될 때 필요한 설정 정보입니다. 이때 "endpoints" 필드는 외부와의 통신 정보이고, "applications" 필드는 게이트웨이에 등록된 애플리케이션의 정보입니다.

    "staticResources": {
    "endpoints": [{
        "endpoint": {
            "physicalName": "poClientEndpoint",
            "protocol": "HTTP",
            "direction": "OUTBOUND",
            "bootState": "RUNNING",
            "connectType": "CLIENT",
            "httpUrl": {
                "split": true,
                "scheme": "http",
                "host": "${MS_IP}",
                "port": "${MS_PORT}"
            }
        }
    },
    {
        "endpoint": {
            "physicalName": "poServerEndpoint",
            "protocol": "HTTP",
            "bootState": "RUNNING",
            "connectionPool": {
                "max": "1000"
            },
            "httpUrl": {
                "split": true,
                "scheme": "http",
                "host": "${GW_IP}",
                "port": "${GW_PORT}"
            },
                "rulesetId": "anylink.system.SystemServiceRuleSet"
        }
    },
    {
        "endpoint": {
            "physicalName": "httpEndpoint",
            "protocol": "HTTP",
            "bootState": "Running",
            "connectType": "Server",
            "connection_pool": {
                "max": "100"
            },
            "httpUrl": {
                "scheme": "http",
                "port": "${HTTP_PORT}"
            },
            "rulesetId": "ApiApplication.ApiServiceGroup.ApiDefaultRuleChain",
            "errorRulesetId": "anylink.system.ApiGatewayErrorRuleSet"
        }
    },
    {
        "endpoint": {
            "physicalName": "httpsEndpoint",
            "protocol": "HTTP",
            "bootState": "Running",
            "connectType": "Server",
            "connectionPool": {
                "max": "100"
            },
            "useSsl": true,
            "ssl": {
                "keystore": {
                    "storeType": "PEM",
                    "storeLocation": "${SSL_STORE}"
                }
            },
            "httpUrl": {
                "scheme": "http",
                "port": "${HTTPS_PORT}"
            },
            "rulesetId": "ApiApplication.ApiServiceGroup.ApiDefaultRuleChain",
            "errorRulesetId": "anylink.system.ApiGatewayErrorRuleSet"
        }
    }],
    "applications": [{
        "id": <string>, (1)
        "version": <int>, (2)
        "servicegroups": [{ (3)
            "id": <string>, (4)
            "version": <int>, (5)
            "rulesets": [{ (6)
                "id": <string>, (7)
                "rule_chains": <RuleChainInfo> (8)
            }],
            "libpath": <string> (9)
        }]
    }]
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) id

    애플리케이션의 ID입니다.

    (2) version

    애플리케이션의 버전입니다.

    (3) servicegroups

    애플리케이션의 하위 서비스 그룹입니다.

    (4) id

    서비스 그룹의 ID입니다.

    (5) version

    서비스 그룹의 버전입니다.

    (6) rulesets

    서비스 그룹의 룰셋입니다.

    (7) id

    룰셋의 ID입니다.

    (8) rule_chains

    체인으로 정의한 룰셋의 실제 내용입니다.

    (9) libpath

    읽어들일 SharedLibrary의 경로입니다.

    "endpoints" 필드의 설정 방법에 대한 자세한 내용은 엔드포인트 설정을 참고합니다.

  • dynamicResources

    게이트웨이가 웹 어드민으로부터 받아온 동적 설정 정보입니다. 해당 필드는 부팅 시 자동으로 설정되며, 웹 어드민을 통해서만 수정이 가능합니다.

    "dynamicResources": {
    "string": <int>
    "endpoints": [<EndpointType>], (1)
    "applications": [<ApplicationType>], (2)
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) endpoints

    엔드포인트 목록입니다.

    (2) applications

    애플리케이션 목록입니다.

  • EndpointInfo

    게이트웨이에 등록된 endpoint 설정 정보입니다. 해당 필드는 웹 어드민을 통해서만 수정이 가능합니다.

    "EndpointInfo": {
    "logical_name": <string>, (1)
    "physical_name": <string>, (2)
    "protocol": ("PO", "HTTP", "TCP"), (3)
    "direction": ("INBOUND", "OUTBOUND", "BOTH"),
    "boot_state": ("STOPPED", "RUNNING"),
    "http_url": { (4)
        "split": <bool>, (5)
        "url": <string>, (6)
        "scheme": ("HTTP", "HTTPS"), (7)
        "host": <string>, (8)
        "port": <string> (9)
    }
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) logical_name

    엔드포인트의 논리적인 이름입니다.

    (2) physical_name

    엔드포인트의 ID입니다.

    (3) protocol

    엔드포인트의 프로토콜입니다. (현재 HTTP만 사용 가능)

    (4) http_url

    연결할 원격 HTTP 서버의 URL입니다.

    (5) split

    URL의 분리 여부입니다.

    • true: URL을 분리함

    • false: URL을 분리 안 함

    (6) url

    전체 URL입니다. 단, split이 'false’일 때 설정합니다.

    (7) scheme

    URL Scheme입니다. 단, split이 'true’일 때 설정합니다.

    • HTTP

    • HTTPS

    (8) host

    HTTP 호스트 이름입니다. 단, split이 'true’일 때 설정합니다.

    (9) port

    HTTP 포트 번호입니다. 단, split이 'true’일 때 설정합니다.

  • EndpointGroupInfo

    게이트웨이에 등록된 endpointgroup 설정 정보입니다. 해당 필드는 웹 어드민을 통해서만 수정이 가능합니다.

    "EndpointGroupInfo":{
    "logical_name": <string>, (1)
    "physical_name": <string>, (2)
    "routing_type": ("ROUND_ROBIN", "WEIGHT_BASED", "PRIORITY"), (3)
    "routing": [{
        "endpoint_id": <string>, (4)
        "priority": <int>, (5)
        "weight": <int> (6)
    }]
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) logical_name

    엔드포인트의 논리적인 이름입니다.

    (2) physical_name

    엔드포인트의 ID입니다.

    (3) routing_type

    엔드포인트의 라우팅 정책입니다. (현재 WEIGHT_BASED만 지원)

    (4) endpoint_id

    라우팅을 설정할 하위 엔드포인트의 ID입니다.

    (5) priority

    엔드포인트의 우선순위입니다. 숫자가 낮을수록 우선됩니다.

    (6) weight

    엔드포인트의 가중치입니다. 숫자가 높을수록 많은 비율로 라우팅됩니다.

  • loggerSystems

    게이트웨이에서 사용하는 로거에 대한 설정 정보입니다. 해당 필드는 웹 어드민을 통해서만 수정이 가능합니다.

    "loggerSystems": [{
    "path": "anylink",
    "level": "debug", (1)
    "rotatetype": "TIMEBASE", (2)
    "rotateparam": "daily", (3)
    "times": "local", (4)
    "format": "[%Y-%m-%d %L%H:%M:%S][%P][%q][%[THREAD]]: %t", (5)
    "expire": "none" (6)
}]

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) level

    로거의 레벨입니다.

    • FATAL

    • CRITICAL

    • ERROR

    • WARN

    • NOTICE

    • INFO

    • DEBUG

    • TRACE

    • NONE

    (2) rotatetype

    로거 로테이트 방식입니다.

    • SIZE

    • TIMEBASE

    (3) rotateparam

    로거 로테이트에 사용할 단위입니다.

    • never: 로테이트 안 함

    • <n>: 파일 크기가 <n> 바이트를 초과하면 로테이트

    • <n> K: 파일 크기가 <n> 킬로바이트를 초과하면 로테이트

    • <n> M: 파일 크기가 <n> 메가바이트를 초과하면 로테이트

    • [day,][hh:][mm]: 지정된 요일 및 시간에 로테이트

    • daily/weekly/monthly: 지정된 일간/주간/월간에 로테이트

    • <n> hours/weeks/months: 매 <n> 시간/주/월에 로테이트

    (4) times

    로그 시간 타입입니다.

    • locacl: 현재 서버 시간 기준으로 로깅

    • UTC: UTC 시간 기준으로 로깅

    (5) format

    로깅되는 포맷입니다.

    • [%Y-%m-%d %L%H:%M:%S]: 년-월-일 시:분:초

    • [%P]: 프로세스 ID

    • [%q]: 로그 레벨

    • [%[THREAD]]: 스레드 정보

    • [%t]: 로그 내용

    (6) expire

    로그 파일의 만료기간입니다.

    • none: 없음

    • [day,][hh:][mm] : 지정된 요일 및 시간

    • daily/weekly/monthly: 지정된 일간/주간/월간

    • <n> hours/weeks/months: 매 <n> 시간/주/월

  • Monitoring

    게이트웨이 모니터링에 대한 설정 정보입니다. 해당 필드는 사용자가 직접 수정이 가능합니다.

    "Monitoring": {
    "trace": {
        "enable" : "<bool>" (1)
        "option": {
            "fileEnable": "<bool>", (2)
            "fileName": "trace_log", (3)
            "path": "/var/log/anyapi", (4)
            "rotateParam": "30 M", (5)
            "rotateFileNum": "5", (6)
            "flushBufferSize": "32", (7)
            "interval": "3000",
            "endpoint": [ (8)
                "<grpc ip:grpc port>"
            ],
            "includeBody": "<bool>" (9)
        }
    },
    "stat": { (10)
        "enable": "<bool>",
        "option": {
            "endpoint": [
                "<grpc ip:grpc port>"
            ],
        }
    }
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) enable

    모니터링의 사용 여부입니다.

    • true: 모니터링 ON

    • false: 모니터링 OFF

    (2) fileEnable

    파일 저장 여부입니다.

    • true: TRACE 정보를 파일로 저장

    • false: 파일 저장 사용 안 함

    (3) fileName

    저장될 파일 이름입니다.

    (4) path

    파일 저장 경로입니다.

    (5) rotateParam

    파일의 로테이션 크기입니다.

    (6) rotateFileNum

    로테이션되는 파일의 개수입니다.

    (7) flushBufferSize

    Span을 저장하는 버퍼 사이즈입니다.

    (8) endpoint

    gRPC의 IP 주소와 포트 번호입니다.

    (9) includeBody

    TRACE 정보에 body값의 포함 여부입니다.

    (10) stat

    통계 데이터의 전송 여부입니다.

    • true: 전송

    • false: 전송 안 함

  • loggerAccess

    게이트웨이에서 사용하는 액세스 로거에 대한 설정 정보입니다. 해당 필드는 웹 어드민을 통해서만 수정이 가능합니다.

    "loggerAccess": {
    "enable": "true", (1)
    "format": "%h %l %u %t %r %s %b", (2)
    "fileName": "access_log", (3)
    "path": "default", (4)
    "rotatetype": "TIMEBASE", (5)
    "rotateparam": "daily", (6)
    "times": "local", (7)
    "expire": "none" (8)
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) enable

    액세스 로그의 사용 여부입니다.

    • true: 사용

    • false: 사용 안 함

    (2) format

    로깅되는 포맷입니다.

    • %h: 원격 호스트 주소

    • %l: 원격 로그인 이름

    • %u: Frank, HTTP 인증으로 알아낸 문서를 요청한 사용자의 ID

    • %t: 서버 요청 처리를 마친 시간

    • %r: 요청의 첫 번째 줄

    • %s: 상태

    • %b: HTTP 헤더를 제외한 전송 바이트 수

    (3) fileName

    로그 파일의 이름입니다. (기본값: access_log)

    (4) path

    로그 파일이 저장되는 경로입니다. (기본값: ${GATEWAY_HOME}/protocol/HTTP/gw_id_test/logs/access_log)

    (5) rotatetype

    로거 로테이트 방식입니다.

    • SIZE

    • TIMEBASE

    (6) rotateparam

    로거 로테이트에 사용할 단위입니다.

    • never: 로테이트 안 함

    • <n>: 파일 크기가 <n> 바이트를 초과하면 로테이트

    • <n> K: 파일 크기가 <n> 킬로바이트를 초과하면 로테이트

    • <n> M: 파일 크기가 <n> 메가바이트를 초과하면 로테이트

    • [day,][hh:][mm]: 지정된 요일 및 시간에 로테이트

    • daily/weekly/monthly: 지정된 일간/주간/월간에 로테이트

    • <n> hours/weeks/months: 매 <n> 시간/주/월에 로테이트

    (7) times

    로그 시간 타입입니다.

    • locacl: 현재 서버 시간 기준으로 로깅

    • UTC: UTC 시간 기준으로 로깅

    (8) expire

    로그 파일의 만료기간입니다.

    • none: 없음

    • [day,][hh:][mm] : 지정된 요일 및 시간

    • daily/weekly/monthly: 지정된 일간/주간/월간

    • <n> hours/weeks/months: 매 <n> 시간/주/월

  • environment

    게이트웨이의 타임아웃 관련 설정 정보입니다. 해당 필드는 웹 어드민을 통해서만 수정이 가능합니다.

    "environment": {
    "connectionTimeout": "3000", (1)
    "readTimeout": "30000", (2)
    "failoverTimeout": "60000" (3)
}

    각 설정 항목에 대한 설명은 다음과 같습니다.

    항목 설명

    (1) connectionTimeout

    connectionTimeout 설정값입니다.

    (2) readTimeout

    readTimeout 설정값입니다.

    (3) failoverTimeout

    failoverTimeout 설정값입니다.

디렉터리 구조

다음은 게이트웨이를 설치하고, 한번 실행한 후에 사용하는 디렉터리 구조입니다.

${GATEWAY_HOME}
  |-- bin
  |-- inc
  |-- lib
  |-- config
  |-- protocol
  |       |-- ${PROTOCOL}
  |       |       |-- ${GATEWAY_NAME}
  |       |-- logs
  |-- uds
bin

AnyAPI 게이트웨이의 부팅을 위한 바이너리가 위치합니다.

inc

AnyAPI 게이트웨이 헤더 파일들이 위치합니다.

lib

AnyAPI 게이트웨이에서 사용하는 라이브러리들이 위치합니다.

config

AnyAPI 게이트웨이 설정 파일이 위치합니다.

protocol

AnyAPI 게이트웨이에서 사용하는 리소스가 위치합니다.

다음은 하위 경로에 대한 설명입니다.

하위 경로 설명

${PROTOCOL}

게이트웨이가 사용하는 프로토콜 이름이 표시됩니다. AnyAPI에는 HTTP로 고정됩니다.

${GATEWAY_NAME}

게이트웨이 리소스가 저장되는 디렉터리입니다.

logs

lib 디렉터리의 export 대상 디렉터리입니다.
uds

도메인 소켓 통신을 하는 경우 필요한 파일이 위치합니다.

환경 변수

다음은 게이트웨이를 구동하기위해 필요한 환경 변수에 대한 설명입니다.

환경변수 설명

GATEWAY_HOME

게이트웨이가 설치된 홈 디렉터리입니다. (필수 사항)

GATEWAY_HOME=/home/anylink/gateway

GATEWAY_ENCODING

게이트웨이 인코딩 방식입니다.

GATEWAY_ENCODING=utf8

GATEWAY_INACTIVE_CACHE

게이트웨이의 캐싱 여부입니다.

  • true: 캐싱 비활성화

  • false: 캐싱 활성화

GATEWAY_INACTIVE_CACHE=false

LD_LIBRARY_PATH

lib 디렉터리를 export할 대상 경로입니다.

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${GATEWAY_HOME}/lib

CURLPOT_LOW_SPEED_TIME

CURLOPT_LOW_SPEED_LIMIT 옵션으로 지정된 속도 이하로 전송될 수 있는 최대 시간입니다.

이때 초 단위로 지정하며, 해당 시간 이상 지속되면 전송이 취소됩니다.

CURLOPT_LOW_SPEED_LIMIT

최하 전송 속도입니다.

이때 초당 전송될 바이트 단위로 지정하며, 해당 속도가 CURLOPT_LOW_SPEED_TIME 옵션으로 지정된 시간만큼 지속되면 전송이 취소됩니다.