Edge Microgateway용 Docker 사용

Apigee Edge 문서를 보고 있습니다.
Apigee X 문서로 이동하세요. info

이 주제에서는 Docker 컨테이너에서 Edge Microgateway를 실행하는 방법을 설명합니다. 이 주제에서 다루는 단계에서는 Docker, Docker 명령어, Edge Microgateway 설정 및 구성에 대한 기본적인 이해가 있다고 가정합니다. 자세한 내용은 Docker 및 Edge Microgateway 문서를 참고하세요.

기본 요건

Docker 컨테이너에서 Edge Microgateway를 실행하기 전에 다음 작업을 실행해야 합니다.

  • Apigee 조직/환경에 대해 Edge Microgateway를 구성합니다.

    edgemicro configure -o your_org -e your_env -u your_username

    구성 관련 자세한 내용은 1부: Edge Microgateway 구성을 참고하세요.

  • 구성 단계를 실행한 후 구성 파일을 찾습니다. 기본 위치는 다음과 같습니다.

    $HOME/.edgemicro/your_org-your_env-config.yaml

    여기서 your_org 및 your_env은 edgemicro config 명령어를 실행할 때 사용한 조직 및 환경입니다. Docker 컨테이너에서 Edge Microgateway를 시작할 때 이 파일이 필요합니다.

  • edgemicro config 명령어를 실행할 때 반환된 키 및 보안 비밀 사용자 인증 정보가 있어야 합니다. 예를 들면 다음과 같습니다.

    The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

  • Docker 컨테이너에서 Edge Microgateway를 시작하기 전에 인증된 API 프록시 호출을 만드는 데 필요한 Apigee Edge 엔티티를 만들어야 합니다. 이러한 항목에는 Edge Microgateway 인식 프록시, API 제품, 개발자, 개발자 앱이 포함됩니다. 전체 안내는 Apigee Edge에서 항목 만들기를 참고하세요.

Edge Micro를 Docker 컨테이너로 실행

  1. Edge Microgateway용 Docker 이미지를 다운로드합니다.

    docker pull gcr.io/apigee-microgateway/edgemicro:latest

  2. 다음 단계로 진행하기 전에 기본 요건 섹션의 모든 단계를 완료했는지 확인하세요.

  3. 다음 명령어를 실행하여 $HOME/.edgemicro에 있는 Edge Microgateway 구성 파일을 base64로 인코딩합니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    여기서 your_org 및 your_env은 edgemicro config 명령어를 실행할 때 사용한 조직 및 환경입니다.

    명령어는 백틱 (`)으로 묶어야 합니다. 예를 들면 다음과 같습니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. Edge Microgateway를 컨테이너로 실행합니다. 이 명령어는 컨테이너 런타임에서 Edge Microgateway를 시작하는 데 사용되는 여러 환경 변수를 설정합니다.

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL \
gcr.io/apigee-microgateway/edgemicro:latest

    매개변수

    매개변수 설명
    -P 노출된 모든 포트를 호스트에 게시합니다. Docker 실행 참조도 참고하세요.
    -p 단일 포트 또는 포트 범위를 명시적으로 매핑합니다. Docker 실행 참조도 참고하세요.
    -d 분리된 모드로 실행합니다. Docker 실행 참조도 참고하세요.
    -v, --volume 볼륨 마운트를 지정합니다. Docker 컨테이너에서 TLS를 사용하도록 Edge Microgateway를 구성하는 경우 로그 파일 디렉터리를 마운트하면 포트 8443을 노출해야 합니다. 볼륨[공유 파일 시스템]도 참고하세요. Docker 컨테이너에서 TLS 사용도 참고하세요.
    EDGEMICRO_ORG Edge Microgateway를 구성하는 데 사용한 Apigee 조직의 이름입니다.
    EDGEMICRO_ENV Edge Microgateway를 구성하는 데 사용한 Apigee 환경의 이름입니다.
    EDGEMICRO_PROCESSES 시작할 프로세스 수입니다.
    EDGEMICRO_KEY Edge Microgateway를 구성할 때 반환된 키입니다.
    EDGEMICRO_SECRET Edge Microgateway를 구성할 때 반환된 보안 비밀입니다.
    EDGEMICRO_CONFIG base64로 인코딩된 Edge Microgateway 구성 파일이 포함된 변수입니다.
    SERVICE_NAME Kubernetes를 사용하는 경우 이 매개변수가 자동으로 채워집니다. 그렇지 않으면 원하는 대로 설정할 수 있습니다. 아무것도 지정하지 않으면 서비스 이름이 default로 설정됩니다.
    DEBUG 디버깅을 사용 설정하려면 *로 설정합니다.
    HTTP_PROXY HTTPS_PROXY Edge Microgateway가 방화벽 뒤에서 실행되고 게이트웨이가 Apigee Edge와 통신할 수 없는 경우에 사용합니다. 자세한 내용은 회사 방화벽 뒤에 Edge Microgateway 설정을 참고하세요.

    예: HTTP_PROXY=http://10.203.0.1:5187/
    NO_PROXY Edge Microgateway가 프록시하면 안 되는 도메인의 쉼표로 구분된 목록입니다. 자세한 내용은 회사 방화벽 뒤에 Edge Microgateway 설정을 참고하세요.

    예: localhost,127.0.0.1,localaddress,.localdomain.com
    NODE_EXTRA_CA_CERTS (선택사항) Node.js에서 기본적으로 신뢰하지 않는 CA를 사용하는 경우 이 매개변수를 사용합니다. 이 매개변수의 값을 PEM 형식의 신뢰할 수 있는 인증서가 하나 이상 포함된 파일의 경로로 설정합니다. 자세한 내용은 TLS 인증서를 참고하세요.
    --security-opt (선택사항) 원하는 Docker 보안 옵션을 설정합니다. Docker 문서의 보안 구성을 참고하세요.
    --cap-drop (선택사항) 컨테이너에서 허용되는 Linux 기능의 제한을 설정합니다. Docker 문서의 런타임 권한 및 Linux 기능을 참고하세요.

    예를 들면 다음과 같습니다.

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-e EDGEMICRO_PROCESS=1 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL \
gcr.io/apigee-microgateway/edgemicro

  5. 컨테이너가 실행 중인지 확인하려면 다음을 실행합니다.

    docker ps

    다음과 비슷한 출력이 표시됩니다.

    CONTAINER ID    IMAGE         COMMAND                CREATED          STATUS          PORTS                                             NAMES
8b92e082ea9c    edgemicro    "/tmp/entrypoint.sh"   12 minutes ago   Up 12 minutes    0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp    edgemicro

API 호출 테스트

컨테이너에서 Edge Microgateway를 시작한 후 API를 호출할 수 있습니다. 예를 들어 API의 기본 경로가 /hello인 경우 다음 명령어를 사용합니다.

http://localhost:8000/hello

샘플 출력:

{"error":"missing_authorization","error_description":"Missing Authorization header"}

이 응답이 표시되면 Edge Microgateway가 API 호출을 성공적으로 처리한 것입니다. 하지만 기본적으로 Edge Microgateway는 인증을 위해 API 키가 필요합니다. 다음 섹션에서는 유효한 API 키로 API를 테스트합니다.

유효한 API 키로 API 테스트

Edge UI에서 이전에 만든 개발자 앱으로 이동합니다. 개발자 앱 페이지에서 소비자 키를 표시하고 복사합니다. 이 값은 API 키입니다. 이 키를 사용하여 인증된 API 호출을 수행합니다.

다음과 같이 x-api-key 헤더로 API를 호출합니다. 개발자 앱에서 복사한 소비자 키 값이 API 키입니다. 기본적으로 Edge Microgateway는 다음과 같이 x-api-key라는 헤더에 키를 전달할 것으로 예상합니다.

curl -i http://localhost:8000/hello -H "x-api-key:apikey"

예를 들면 다음과 같습니다.

curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

API 키와 OAuth 토큰을 사용하여 Edge Microgateway를 통해 인증된 API 호출을 만드는 방법을 자세히 알아보려면 4부: Edge Microgateway 보안을 참고하세요.

Edge Microgateway 중지

다음 Docker 명령어를 사용하여 Edge Microgateway를 중지합니다.

docker stop edgemicro

Edge Microgateway 다시 시작

Edge Microgateway를 중지한 후 다음 Docker 명령어를 사용하여 다시 시작할 수 있습니다.

docker start edgemicro

Docker 컨테이너에서 TLS 사용

이 섹션에서는 Docker 컨테이너에서 실행되는 Edge Microgateway에 TLS를 구성하는 방법을 설명합니다. 들어오는 요청 (북바운드 방향)에 TLS를 사용하도록 Edge Microgateway 서버를 구성할 수 있으며, 대상 엔드포인트로 전송되는 요청(사우스바운드 방향)에 TLS 클라이언트가 되도록 Edge Microgateway를 구성할 수 있습니다.

인증서 파일을 저장할 위치

Edge Microgateway를 실행하는 Docker 컨테이너에는 /opt/apigee/.edgemicro에 마운트 지점이 있습니다. TLS 인증서를 사용하도록 Edge Microgateway를 구성할 때 해당 마운트 지점에서 인증서 파일을 사용할 수 있도록 하고 Edge Microgateway 구성 파일에서 이를 참조할 수 있습니다. 이 구성 파일은 일반적으로 $HOME/.edgemicro 디렉터리에 있으며 이름은 your_org-your_env-config.yaml입니다. 예를 들면 다음과 같습니다.

...
edgemicro:
  ssl:
   key: /opt/apigee/.edgemicro/southbound/tls.key
   cert: /opt/apigee/.edgemicro/southbound/tls.crt
...

Node.js에서 신뢰하지 않는 CA 사용

Node.js에서 기본적으로 신뢰하지 않는 인증 기관 (CA)(예: 자체 서명된 인증서)을 사용하는 경우 컨테이너를 실행할 때 NODE_EXTRA_CA_CERTS 매개변수를 사용하는 것이 좋습니다.

이 매개변수를 PEM 형식의 신뢰할 수 있는 인증서가 하나 이상 포함된 파일의 경로로 설정합니다. 이 매개변수가 사용되는 방식을 확인하려면 북향 TLS 구성 방법 및 남향 TLS 구성 방법의 예를 참고하세요.

예를 들면 다음과 같습니다.

docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

Edge Micro를 Docker 컨테이너로 실행도 참고하세요.

TLS 유효성 검사 사용 중지

권장되지는 않지만 경우에 따라 컨테이너에서 실행되는 Edge Microgateway의 TLS 유효성 검사를 사용 중지할 수 있습니다. TLS를 사용 중지하는 기능은 기본적으로 Edge Microgateway Docker 컨테이너에 내장되어 있지 않습니다. 이 작업을 완료하려면 Edge Microgateway용 맞춤 Docker 이미지를 만들어야 합니다. 아래는 맞춤 이미지를 빌드하고 TLS 유효성 검사를 사용 중지하는 일반적인 안내입니다.

  1. https://github.com/apigee-internal/microgateway에서 Edge Microgateway 소스 저장소를 클론하거나 다운로드합니다.

  2. cd 명령어를 사용하여 소스 코드 디렉터리의 microgateway/kubernetes/docker/edgemicro 디렉터리로 이동합니다.

    예를 들면 다음과 같습니다.

    cd $HOME/git/microgateway/kubernetes/docker/edgemicro

  3. entrypoint.sh 파일을 열고 NODE_TLS_REJECT_UNAUTHORIZED 환경 변수를 허용하도록 코드를 수정합니다. 나중에 컨테이너를 실행할 때 이 변수의 값을 지정합니다.

  4. Docker 컨테이너를 빌드합니다.

    docker build -t edgemicro .

  5. 컨테이너를 실행할 때 -e NODE_TLS_REJECT_UNAUTHORIZED = 1 옵션을 지정합니다. 예를 들면 다음과 같습니다.

docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_TLS_REJECT_UNAUTHORIZED = 1 \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

예: 업스트림 TLS를 구성하는 방법

이 섹션에서는 Edge Microgateway 서버에서 북바운드 (수신) TLS 연결을 설정하는 방법을 설명합니다. 업스트림 TLS를 사용하면 클라이언트가 Edge Microgateway에 API를 호출할 때 HTTPS를 사용할 수 있습니다. 아래 예에서는 자체 서명된 인증서를 사용합니다.

1. 초기 설정 단계

  1. 시스템에서 openssl.cnf 파일을 찾습니다. 예를 들면 다음과 같습니다. /etc/ssl/openssl.cnf
  2. 수정할 opensssl.cnf 파일을 엽니다.

  3. req_extensions이 구성 파일에 있는지 확인합니다. 예를 들어 파일에 다음과 유사한 정보가 있어야 합니다.

    [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

  4. openssl.cnf에 다음 스탠자를 추가하여 올바른 SNI 속성을 생성합니다.

    [ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

    opensssl.cnf 파일 예시:

    [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

  5. 아직 하지 않았다면 기본 요건 섹션에 제공된 단계에 따라 Edge Microgateway를 초기화하고 구성합니다. 완료되면 Edge Microgateway 인식 프록시, API 제품, 개발자, 개발자 앱이 생성됩니다. 또한 edgemicro configure 명령어를 실행하고 키와 보안 비밀을 수신해야 합니다.

2. 자체 서명 인증서 생성

다음으로 TLS를 설정하는 데 필요한 인증서와 키를 생성합니다.

  1. cd 명령어를 사용하여 $HOME/.edgemicro 디렉터리로 이동합니다.

  2. 다음 bash 스크립트를 만듭니다. 원하는 이름을 지정할 수 있습니다. 예를 들면 keygen.sh입니다.

    #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

  3. bash 파일에서 openssl.cnf 파일의 경로가 올바른지 확인합니다.

  4. bash 파일을 실행합니다. 인증서 정보를 입력하라는 메시지가 표시됩니다. 일반 이름에 localhost을 사용해야 합니다.

  5. 다음 파일이 생성되었는지 확인합니다.

    • rootca.key
    • rootca.pem
    • tls.key
    • tls.csr
    • rootca.srl
    • tls.crt

3. Edge Microgateway 구성 파일 수정

  1. 편집기에서 Edge Micro 구성 파일을 엽니다. 예를 들면 다음과 같습니다.

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. 다음과 같이 edgemicro 스탠자를 수정합니다. port 및 ssl 속성을 변경하고 있습니다.

    edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

  3. 다음 명령어를 실행하여 $HOME/.edgemicro에 있는 Edge Microgateway 구성 파일을 base64로 인코딩합니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    여기서 your_org 및 your_env은 edgemicro config 명령어를 실행할 때 사용한 조직 및 환경입니다.

    명령어는 백틱 (`)으로 묶어야 합니다. 예를 들면 다음과 같습니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

Edge Micro를 Docker 컨테이너로 실행도 참고하세요.

4. 컨테이너 실행

  1. 다음 명령어를 실행하여 Edge Microgateway로 Docker 컨테이너를 실행합니다.

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
gcr.io/apigee-microgateway/edgemicro:latest

  2. 명령어에 사용된 다음 매개변수는 Edge Micro를 Docker 컨테이너로 실행에 설명된 기본 명령어와 다릅니다.

    • port는 8443으로 설정됩니다.
    • 볼륨 마운트는 키 및 인증서 파일을 마운트하는 데 사용됩니다.
    • NODE_EXTRA_CA_CERTS 변수는 자체 서명 인증서의 경우 필요에 따라 맞춤 CA를 추가하는 데 사용됩니다.

5. TLS 구성 테스트

  1. 다음 cURL 명령어를 실행하여 설정을 테스트합니다. 명령어에 기본 경로와 API 키를 대체합니다. 다음 예시에서는 rootca.pem가 있는 디렉터리에 있고 생성한 프록시의 기본 경로가 /hello이라고 가정합니다.

    curl -v https://localhost:8443/hello --cacert rootca.pem \
-H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"

  2. 자세한 cURL 출력에는 TLS 핸드셰이크의 각 단계가 표시됩니다. HTTP 200 응답이 표시되면 구성이 성공한 것입니다.

    *   Trying ::1...ey:Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
* TCP_NODELAY set
* Connected to localhost (::1) port 8443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: rootca.pem
  CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  start date: Dec 14 22:35:28 2018 GMT
*  expire date: Oct  3 22:35:28 2021 GMT
*  common name: localhost (matched)
*  issuer: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  SSL certificate verify ok.
> GET /hello HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key:Az82fdnfaONVCOE4NKhajxAboDA3FAo
>
< HTTP/1.1 200 OK
< x-powered-by: Apigee
< access-control-allow-origin: *
< x-frame-options: ALLOW-FROM RESOURCE-URL
< x-xss-protection: 1
< x-content-type-options: nosniff
< content-type: text/plain; charset=utf-8
< etag: W/"d-GHB1ZrJKk/wdVTdB/jgBsw"
< date: Fri, 14 Dec 2018 22:43:13 GMT
< via: 1.1 google
< alt-svc: clear
< x-response-time: 1325
< Connection: keep-alive
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
Hello, Guest!

예: 다운스트림 TLS를 구성하는 방법

이 섹션에서는 Edge Microgateway 서버와 백엔드 대상 애플리케이션 간에 다운스트림 (아웃바운드) TLS 연결을 설정하는 방법을 설명합니다. 아래 예에서는 자체 서명된 인증서를 사용합니다.

1. 초기 설정 단계

  1. 시스템에서 openssl.cnf 파일을 찾습니다. 예를 들면 다음과 같습니다. /etc/ssl/openssl.cnf
  2. 수정할 opensssl.cnf 파일을 엽니다.

  3. req_extensions이 구성 파일에 있는지 확인합니다. 예를 들어 파일에 다음과 유사한 정보가 있어야 합니다.

    [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

  4. openssl.cnf에 다음 스탠자를 추가하여 올바른 SNI 속성을 생성합니다.

    [ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

    opensssl.cnf 파일 예시:

    [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

  5. edgemicro configure 명령어를 실행합니다.

    edgemicro configure -o your_org -e your_env -u your_username

    구성 관련 자세한 내용은 1부: Edge Microgateway 구성을 참고하세요.

  6. edgemicro configure에서 반환된 키와 보안 비밀 사용자 인증 정보를 복사합니다. 컨테이너를 실행하려면 이러한 값이 필요합니다. 예를 들면 다음과 같습니다.

    The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

2. Node.js 타겟 애플리케이션 만들기

  1. cd 명령어를 사용하여 .edgemicro 디렉터리로 이동합니다.

  2. 다음 bash 스크립트를 만듭니다. 원하는 이름을 지정할 수 있습니다. 예를 들면 keygen.sh입니다.

    #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

  3. bash 파일에서 openssl.cnf 파일의 경로가 올바른지 확인합니다.

  4. bash 파일을 실행합니다. 인증서 정보를 입력하라는 메시지가 표시됩니다. 일반 이름에 hellworld을 사용해야 합니다.

  5. 다음 파일이 생성되었는지 확인합니다.

    • rootca.key
    • rootca.pem
    • tls.key
    • tls.csr
    • rootca.srl
    • tls.crt

  6. server.js라는 새 파일을 만듭니다.

    'use strict';

const express = require('express');
const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync("tls.key"),
  cert: fs.readFileSync("tls.crt")
};

// Constants
const PORT = 9443;
const HOST = '0.0.0.0';

// App
const app = express();
app.get('/', (req, res) => {
  res.send('Hello world\n');
});

https.createServer(options, app).listen(PORT);

  7. server.js과 동일한 디렉터리에 package.json 파일을 만듭니다. 예를 들면 다음과 같습니다.

    {
  "name": "helloworld",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.16.4",
    "fs": "0.0.1-security",
    "https": "^1.0.0"
  }
}

  8. npm install을 실행하여 종속 항목을 가져옵니다.

  9. server.js와 동일한 디렉터리에 새 Dockerfile을 만듭니다. 여기서 WORKDIR은 Node.js 앱의 루트 경로입니다.

    FROM node:8-alpine
WORKDIR path-to-your-node-app
COPY package*.json ./

RUN npm install
COPY . .
EXPOSE 9443
CMD [ "npm", "start" ]

  10. Docker 이미지를 빌드합니다.

    docker build -t helloworld .

  11. 샘플 앱을 시작합니다.

    docker run -P -p 9443:9443 --name helloworld helloworld

3. Apigee Edge에서 항목 만들기

  1. 이 설정으로 Edge Microgateway 인식 프록시를 만듭니다. 자세한 내용은 Edge에서 Edge Microgateway 인식 API 프록시 만들기를 참고하세요.

    • 프록시 이름: edgemicro_local
    • 버전: 1
    • Basepath: /local
    • 목표: https://helloworld:9443

  2. API 제품을 만듭니다. 자세한 내용은 제품 만들기를 참고하세요.

  3. 개발자를 만듭니다. 자세한 내용은 개발자 만들기를 참고하세요.

  4. 개발자 앱을 만듭니다. 자세한 내용은 개발자 앱 만들기를 참고하세요.

4. 컨테이너 실행

  1. 편집기에서 Edge Micro 구성 파일을 엽니다. 예를 들면 다음과 같습니다.

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. 다음과 같이 edgemicro 스탠자를 수정합니다. port 및 ssl 속성을 변경하고 있습니다.

    edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

  3. 다음 명령어를 실행하여 $HOME/.edgemicro에 있는 Edge Microgateway 구성 파일을 base64로 인코딩합니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    여기서 your_org 및 your_env은 edgemicro config 명령어를 실행할 때 사용한 조직 및 환경입니다.

    명령어는 백틱 (`)으로 묶어야 합니다. 예를 들면 다음과 같습니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. 다음 명령어를 실행하여 Docker 컨테이너에서 Edge Microgateway를 시작합니다.

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

5. TLS 구성 테스트

  1. 다음 cURL 명령어를 실행하여 설정을 테스트합니다. 마이크로게이트웨이 인식 프록시에서 사용한 기본 경로와 Apigee Edge에서 만든 개발자 앱에서 가져온 API 키를 대체합니다. 예를 들면 다음과 같습니다.

    curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

    다음과 같은 오류가 표시됩니다.

    ...
*  subject: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  start date: Dec 10 02:12:22 2018 GMT
*  expire date: Sep 29 02:12:22 2021 GMT
*  issuer: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 502 Bad Gateway
< Date: Wed, 12 Dec 2018 05:25:01 GMT
< Connection: keep-alive
< Content-Length: 93
<
* Connection #0 to host localhost left intact
{"message":"unable to verify the first certificate","code":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}

  2. Edge Microgateway를 다시 실행하되 이번에는 NODE_EXTRA_CA_CERTS 변수를 추가합니다.

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

  3. 다음 cURL 명령어를 실행합니다. 이전과 같이 기본 경로와 API 키를 대체합니다. 예를 들면 다음과 같습니다.

    curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

  4. 출력을 확인합니다. 성공하면 HTTP 200 상태 응답이 표시됩니다.

    ...
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 200 OK
< x-powered-by: Express
< content-type: text/html; charset=utf-8
< etag: W/"c-M6tWOb/Y57lesdjQuHeB1P/qTV0"
< date: Wed, 12 Dec 2018 05:49:28 GMT
< x-response-time: 421
< Connection: keep-alive
< Transfer-Encoding: chunked
<
Hello world

맞춤 플러그인 추가

맞춤 플러그인을 작성하여 마이크로게이트웨이에 새로운 기능과 역량을 추가할 수 있습니다. 맞춤 플러그인을 사용하면 마이크로게이트웨이를 통과하는 요청 및 응답과 프로그래매틱 방식으로 상호작용할 수 있습니다.

Docker 컨테이너에서 실행되는 Edge Microgateway 인스턴스에 플러그인을 배포하는 방법에는 두 가지가 있습니다.

이 섹션의 나머지 부분에서는 표준 Edge Microgateway 설정을 위한 플러그인을 작성하고 구성하는 데 익숙하다고 가정합니다. 그렇지 않으면 맞춤 플러그인 개발을 참고하세요.

옵션 A: 볼륨에 플러그인 디렉터리 마운트

(v.2.5.27에서 추가됨) 볼륨 마운트를 통해 플러그인을 추가하는 단계는 Edge Microgateway에 맞춤 플러그인을 추가하는 데 필요한 단계와 유사합니다. Docker 컨테이너를 실행할 때 로컬 시스템의 플러그인 디렉터리(볼륨)를 컨테이너 마운트 지점(/opt/apigee/plugins)에 마운트할 수 있습니다. 그런 다음 Edge Microgateway 구성 파일에서 로컬 볼륨 디렉터리를 지정합니다.

다음 단계에서는 Docker 마운트 지점을 사용하여 맞춤 플러그인을 포함하는 방법을 보여줍니다.

  1. Edge Microgateway를 중지합니다.

    edgemicro stop

  2. 맞춤 플러그인용 디렉터리를 만듭니다. 예를 들어

    $HOME/edgemicro/custom/plugins

  3. 맞춤 플러그인 디렉터리를 Edge Microgateway 구성 파일에 추가합니다. 예를 들면 다음과 같습니다.

      plugins:
    dir: $HOME/edgemicro/custom/plugins
    sequence:
      - oauth
      - response-uppercase
  ````

  4. 간단한 플러그인 작성의 안내에 따라 플러그인을 작성하고 테스트합니다. 플러그인 코드를 적절한 디렉터리 구조에 배치해야 합니다. 예를 들면 다음과 같습니다.

    custom
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

  5. 다음과 유사한 명령어로 Docker 컨테이너를 실행합니다. 여기서 -v 옵션을 사용하여 Docker 볼륨에 플러그인 디렉터리를 마운트합니다. 다음 예시 명령어에서는 플러그인 디렉터리 $HOME/edgemicro/custom/plugins(커스텀 플러그인이 있는 위치)이 컨테이너의 마운트 지점 /opt/apigee/plugins에 매핑됩니다.

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-v $HOME/edgemicro/custom/plugins:/opt/apigee/plugins \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=jdoe \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=39c4b561100cd7f258768d1072f3e1d7c17b5f36a18fe89972bb5c9ce7e58fb \
-e EDGEMICRO_SECRET=f5f9e239a38b4e6cc99c2aa067716a84aebdcff9580a7925fc500e402b1a5fa \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL gcr.io/apigee-microgateway/edgemicro:latest

  6. API를 호출하여 플러그인을 테스트합니다.

자세한 내용은 VOLUME [공유 파일 시스템]을 참고하세요.

옵션 B: 플러그인을 컨테이너에 빌드

이 옵션에서는 플러그인을 컨테이너에 빌드합니다.

1. 플러그인 패키징

  1. 간단한 플러그인 작성의 안내에 따라 플러그인을 작성하고 테스트합니다.

  2. 플러그인 코드를 적절한 디렉터리 구조에 배치합니다. 플러그인 디렉터리는 정해진 구조를 따라야 합니다. 다음 예시는 따라야 하는 구조를 보여줍니다. 여기서 response-uppercase과 request-headers은 맞춤 플러그인 코드가 포함된 폴더의 이름입니다 (이 이름은 예시일 뿐이며 폴더 이름은 다를 수 있음).

    plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

  3. cd 명령어를 사용하여 plugin 폴더로 이동합니다.

  4. plugin 폴더에서 전체 plugins 폴더를 압축합니다.

    zip -r plugins.zip plugins/

2. Docker 이미지 만들기

다음으로 Dockerfile을 만들어 Edge Microgateway 이미지에 플러그인 코드를 추가합니다.

  1. zip 파일이 있는 동일한 디렉터리에 Dockerfile라는 새 파일을 만듭니다.

  2. Dockerfile에 다음 코드를 추가하고 파일을 저장합니다.

    USER root
RUN apk update && \
    apk upgrade && \
    apk add zipapk add zip && \
    mkdir /opt/apigee/customplugins && \
    chown apigee:apigee /opt/apigee/customplugins
COPY plugins.zip /opt/apigee/customplugins
RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins"
EXPOSE 8000
EXPOSE 8443
USER apigee
ENTRYPOINT ["entrypoint"]

  3. 플러그인을 사용하여 새 Edge Microgateway Docker 이미지를 만듭니다.

    docker build -t image-name .

    예를 들면 다음과 같습니다.

    docker build -t edgemicroplugins .

3. Edge Microgateway 구성 업데이트

이제 플러그인이 패키징되었으므로 Edge Microgateway 구성 파일에 플러그인을 추가해야 합니다.

  1. 편집기에서 Edge Microgateway 구성 파일을 엽니다.

    $HOME/.edgemicro/org-env-config.yaml

    예를 들면 다음과 같습니다.

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. 구성 파일에 플러그인 디렉터리를 추가합니다. 다음 예에서 dir 속성은 플러그인 코드의 위치를 지정합니다 (Dockerfile에서 지정). 플러그인 디렉터리의 이름도 지정해야 합니다. 아래 예에서는 response-uppercase입니다. 

    edgemicro:
  ...
  plugins:
    dir: /opt/apigee/plugins
    sequence:
      - oauth
      - response-uppercase

4. 마이크로게이트웨이 시작

마지막으로 컨테이너에서 마이크로게이트웨이를 시작해야 합니다.

  1. 다음 명령어를 실행하여 $HOME/.edgemicro에 있는 Edge Microgateway 구성 파일을 base64로 인코딩합니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    여기서 your_org 및 your_env은 edgemicro config 명령어를 실행할 때 사용한 조직 및 환경입니다.

    명령어는 백틱 (`)으로 묶어야 합니다. 예를 들면 다음과 같습니다.

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  2. Edge Microgateway를 컨테이너로 실행합니다. 이 명령어는 컨테이너 런타임에서 Edge Microgateway를 시작하는 데 사용되는 여러 환경 변수를 설정합니다.

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins image_name

    예를 들면 다음과 같습니다.

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins edgemicroplugins

  3. API를 호출하여 플러그인을 테스트합니다.

    API를 호출하고 출력이 예상대로인지 확인하여 플러그인 코드가 실행되는지 테스트합니다.

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    예를 들어 response-uppercase 플러그인은 다음과 같은 대답을 반환할 수 있습니다.

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
  HELLO, WORLD!