3scale 설치

Red Hat 3Scale 2-saas

3scale API Management 설치 및 구성.

초록

이 가이드에서는 3scale API Management를 설치하고 구성하는 데 필요한 정보를 제공합니다.

preface

이 가이드는 3scale을 설치하고 구성하는 데 도움이 됩니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 용어를 교체하기 위해 최선을 다하고 있습니다. 먼저 마스터(master), 슬레이브(slave), 블랙리스트(blacklist), 화이트리스트(whitelist) 등 네 가지 용어를 교체하고 있습니다. 이러한 변경 작업은 작업 범위가 크므로 향후 여러 릴리스에 걸쳐 점차 구현할 예정입니다. 자세한 내용은 CTO Chris Wright의 메시지에서 참조하십시오.

1장. 3scale 레지스트리 서비스 계정

3scale 2saas가 있는 공유 환경에서 registry.redhat.io 의 컨테이너 이미지를 사용하려면 개별 사용자의 고객 포털 자격 증명 대신 레지스트리 서비스 계정을 사용해야 합니다.

레지스트리 서비스 계정을 생성하고 수정하려면 다음 섹션에 설명된 단계를 수행합니다.

1.1. 레지스트리 서비스 계정 생성

레지스트리 서비스 계정을 생성하려면 아래 절차를 따르십시오.

절차

  1. Registry Service Accounts 페이지로 이동하여 로그인합니다.
  2. New Service Account (새 서비스 계정)를 클릭합니다.
  3. Create a New Registry Service Account (새 레지스트리 서비스 계정 생성) 페이지에서 양식을 작성합니다.

    1. 서비스 계정 의 이름을 추가합니다.

      참고: 양식 필드 앞에 임의로 생성된 고정 길이의 숫자 문자열이 표시됩니다.

    2. 설명을 입력합니다.
    3. 생성을 클릭합니다.
  4. 서비스 계정으로 다시 이동합니다.
  5. 생성한 서비스 계정을 클릭합니다.
  6. example 12345678|username 및 암호를 포함하여 사용자 이름을 기록합니다. 이 사용자 이름과 암호는 registry.redhat.io 에 로그인하는 데 사용됩니다.
참고

토큰 정보 페이지에는 인증 토큰 사용 방법을 보여주는 탭이 있습니다. 예를 들어 Token Information( 토큰 정보 ) 탭에는 사용자 이름이 12345678|username 및 그 아래의 암호 문자열에 표시됩니다.

1.2. 컨테이너 레지스트리 인증 구성

3scale 관리자는 OpenShift에 3scale을 배포하기 전에 registry.redhat.io를 사용하여 인증을 구성합니다.

사전 요구 사항

  • 관리자 인증 정보가 있는 Red Hat OpenShift Container Platform(OCP) 계정.
  • OpenShift oc 클라이언트 툴이 설치되어 있습니다. 자세한 내용은 OpenShift CLI 설명서를 참조하십시오.

절차

  1. 관리자로 OpenShift 클러스터에 로그인합니다.

    $ oc login -u system:admin
  2. 3scale을 배포하려는 프로젝트를 엽니다.

    oc project your-openshift-project
  3. Red Hat Customer Portal 계정을 사용하여 docker-registry 시크릿을 생성하고 3scale-registry-auth를 시크릿으로 교체하여 다음을 생성할 수 있습니다.

    $ oc create secret docker-registry threescale-registry-auth \
      --docker-server=registry.redhat.io \
      --docker-username="customer_portal_username" \
      --docker-password="customer_portal_password" \
      --docker-email="email_address"

    다음 출력이 표시됩니다.

    secret/threescale-registry-auth created
  4. 이미지를 가져오는 데 시크릿을 사용하도록 서비스 계정에 시크릿을 연결합니다. 서비스 계정 이름은 OpenShift pod에서 사용하는 이름과 일치해야 합니다. 이 예에서는 default 서비스 계정을 사용합니다.

    $ oc secrets link default threescale-registry-auth --for=pull
  5. 빌드 이미지를 푸시하고 가져오는 데 보안을 사용하도록 builder 서비스 계정에 보안을 연결합니다.

    $ oc secrets link builder threescale-registry-auth

추가 리소스

컨테이너 이미지용 Red Hat으로 인증하는 방법에 대한 자세한 내용은 다음을 참조하십시오.

1.3. 레지스트리 서비스 계정 수정

표의 각 인증 토큰 오른쪽에 있는 팝업 메뉴를 사용하여 레지스트리 서비스 계정 페이지에서 서비스 계정을 편집하거나 삭제할 수 있습니다.

주의

서비스 계정을 다시 생성하거나 제거하면 토큰을 사용하여 registry.redhat.io 에서 콘텐츠를 인증하고 검색하는 시스템에 영향을 미칩니다.

각 기능에 대한 설명은 다음과 같습니다.

  • 토큰을 다시 생성합니다. 권한이 있는 사용자가 서비스 계정 과 연결된 암호를 재설정할 수 있습니다.

    참고: 서비스 계정 의 사용자 이름을 수정할 수 없습니다.

  • 업데이트 설명: 권한이 있는 사용자가 서비스 계정에 대한 설명을 업데이트할 수 있습니다.
  • 계정 삭제: 권한이 있는 사용자가 서비스 계정을 제거할 수 있도록 합니다.

1.4. 추가 리소스

2장. APIcast 설치

APIcast는 내부 및 외부 API 서비스를 Red Hat 3scale Platform과 통합하는 데 사용되는 NGINX 기반 API 게이트웨이입니다. APIcast는 라운드 로빈을 사용하여 부하 분산을 수행합니다.

이 가이드에서는 배포 옵션, 환경 제공 및 시작 방법에 대해 알아봅니다.

사전 요구 사항

APIcast는 독립 실행형 API 게이트웨이가 아닙니다. 3scale API Manager에 연결해야 합니다.

  • 3scale 호스팅 계정.

APIcast를 설치하려면 다음 섹션에 설명된 단계를 수행합니다.

2.1. APIcast 배포 옵션

호스팅 또는 자체 관리 APIcast를 사용할 수 있습니다. 두 경우 모두 APIcast를 3scale API Management 플랫폼의 나머지 부분에 연결해야 합니다.

  • 호스팅 APIcast: 3scale은 클라우드에서 APIcast를 호스팅합니다. 이 경우 APIcast는 이미 배포되어 있으며 하루에 50,000 건의 호출으로 제한됩니다.
  • 자체 관리 APIcast: 원하는 대로 APIcast를 배포할 수 있습니다. 다음은 APIcast를 배포하는 데 권장되는 몇 가지 옵션입니다.

2.2. APIcast 환경

기본적으로 3scale 계정을 생성하거나 새 API 서비스를 생성할 때 다음 두 가지 환경에서 호스팅되는 APIcast가 제공됩니다.

  • 스테이징: API 통합을 구성하고 테스트하는 동안만 사용해야 합니다. 설정이 예상대로 작동하는지 확인했으면 프로덕션 환경에 배포하도록 선택할 수 있습니다.
  • 프로덕션: 하루에 50,000건의 호출으로 제한되며 다음과 같은 즉시 사용 가능한 인증 옵션을 지원합니다. API 키 및 앱 ID 및 앱 키 쌍, OpenID Connect.

자체 관리 배포를 사용하는 경우 여전히 두 개의 환경이 동일하므로 각각에 대해 APIcast 인스턴스를 배포해야 합니다. 스테이징 또는 프로덕션 값을 사용할 수 있는 환경 변수 THREESCALE_DEPLOYMENT_ENV 를 설정하여 APIcast 인스턴스에서 사용할 구성(Staging 또는 Production)을 지정할 수 있습니다 .

2.3. 통합 설정 구성

3scale 관리자로서 3scale이 실행되는 환경에 대한 통합 설정을 구성합니다.

사전 요구 사항

관리자 권한이 있는 3scale 계정.

절차

  1. [your_API_name] > 통합 > 설정으로 이동합니다.
  2. Deployment 에서 기본 옵션은 다음과 같습니다.

    • 배포 옵션: 호스팅 APIcast
    • 인증 모드: API 키.
  3. 원하는 옵션으로 변경합니다.
  4. 변경 사항을 저장하려면 Update Product(제품 업데이트 )를 클릭합니다.

2.4. 서비스 구성

API 백엔드의 엔드포인트 호스트인 Private Base URL(프라이빗 기본 URL ) 필드에서 API 백엔드를 선언해야 합니다. APIcast는 모든 인증, 권한 부여, 속도 제한 및 통계가 처리된 후에 모든 트래픽을 API 백엔드로 리디렉션합니다.

이 섹션에서는 서비스 구성을 안내합니다.

2.4.1. API 백엔드 선언

일반적으로 API의 개인 기본 URL은 관리하는 도메인(yourdomain.com)에서 https://api-backend.yourdomain.com:443 과 같습니다. 예를 들어 Twitter API와 통합하면 Private Base URL은 https://api.twitter.com/ 입니다.

이 예제에서는 모든 경로를 수락하고 요청에 대한 정보(경로, 요청 매개 변수, 헤더 등)를 반환하는 간단한 API인 3scale에서 호스팅하는 Echo API를 사용합니다. 개인 기본 URL은 https://echo-api.3scale.net:443 입니다.

절차

  • 개인(관리되지 않음) API가 작동하는지 테스트합니다. 예를 들어, Echo API의 경우 curl 명령을 사용하여 다음 호출을 수행할 수 있습니다.

    curl "https://echo-api.3scale.net:443"

    다음과 같은 응답이 표시됩니다.

    {
        "method": "GET",
        "path": "/",
        "args": "",
        "body": "",
        "headers": {
          "HTTP_VERSION": "HTTP/1.1",
          "HTTP_HOST": "echo-api.3scale.net",
          "HTTP_ACCEPT": "*/*",
          "HTTP_USER_AGENT": "curl/7.51.0",
          "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
          "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
          "HTTP_X_FORWARDED_PORT": "443",
          "HTTP_X_FORWARDED_PROTO": "https",
          "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
        },
        "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
      }

2.4.2. 인증 설정 구성

[your_product_name] > Integration > Settings 아래의 AUTHENTICATION 섹션에서 API에 대한 인증 설정을 구성할 수 있습니다.

표 2.1. 선택적 인증 필드

필드설명

인증 사용자 키

자격 증명 위치와 연결된 사용자 키를 설정합니다.

인증 정보 위치

자격 증명이 HTTP 헤더, 쿼리 매개 변수 또는 HTTP 기본 인증으로 전달되는지 여부를 정의합니다.

호스트 헤더

사용자 지정 호스트 요청 헤더를 정의합니다. 이는 API 백엔드가 특정 호스트의 트래픽만 허용하는 경우 필요합니다.

시크릿 토큰

API 백엔드에 대한 직접 개발자 요청을 차단하는 데 사용됩니다. 여기에 헤더 값을 설정하고 백엔드에서 이 secret 헤더를 사용한 호출만 허용하는지 확인합니다.

또한 [your_product_name] > Integration > Settings 아래에서 GATEWAY RESPONSE 오류 코드를 구성할 수 있습니다. 오류에 대한 Response Code,Content-typeResponse Body 를 정의합니다. 인증에 실패했습니다. 인증이 누락되어 일치하지 않습니다.

표 2.2. 응답 코드 및 기본 응답 본문

응답 코드응답 본문

403

인증 실패

403

인증 매개 변수가 누락되어 있습니다

404

일치하는 매핑 규칙이 없습니다

429

사용 제한 초과

2.4.3. API 테스트 호출 구성

API를 구성하려면 제품을 사용하여 백엔드를 테스트하고 APIcast 구성을 스테이징 및 프로덕션 환경으로 승격하여 요청 호출을 기반으로 테스트합니다.

각 제품에 대해 요청이 경로에 따라 해당 백엔드로 리디렉션됩니다. 이 경로는 제품에 백엔드를 추가할 때 구성됩니다. 예를 들어, 제품에 백엔드가 두 개 추가되는 경우 각 백엔드에 고유한 경로가 있습니다.

사전 요구 사항

절차

  1. [your_product_name] > Integration > Configuration 으로 이동하여 APIcast 구성을 스테이징으로 승격합니다.
  2. APIcast Configuration( APIcast 구성)에는 제품에 추가된 각 백엔드에 대한 매핑 규칙이 표시됩니다. Promote v.[n] to Staging APIcast 를 클릭합니다.

    • v.[n] 은 승격할 버전 번호를 나타냅니다.
  3. 스테이징으로 승격되고 나면 프로덕션으로 승격할 수 있습니다. Staging APIcast 에서 Promote v.[n] to Production APIcast 를 클릭합니다.

    • v.[n] 은 승격할 버전 번호를 나타냅니다.
  4. 명령줄에서 API에 대한 요청을 테스트하려면 테스트하기 위해 Example curl 에 제공된 명령을 사용합니다.

    • curl 명령 예제는 제품의 첫 번째 매핑 규칙을 기반으로 합니다.

API에 대한 요청을 테스트할 때 메서드 및 지표를 추가하여 매핑 규칙을 수정할 수 있습니다.

구성을 수정할 때마다 API를 호출하기 전에 스테이징 및 프로덕션 환경으로 승격해야 합니다. 스테이징 환경으로 승격할 보류 중인 변경 사항이 있으면 관리 포털에 Integration (통합) 메뉴 항목 옆에 느낌표가 표시됩니다.

3scale 호스팅 APIcast 게이트웨이는 인증 정보를 검증하고 API의 애플리케이션 계획에 대해 정의한 속도 제한을 적용합니다. 자격 증명 없이 호출하거나 잘못된 자격 증명을 사용하여 호출하면 Authentication failed 라는 오류 메시지가 표시됩니다.

2.5. APIcast Operator 설치

이 가이드에서는 OCI(OpenShift Container Platform) 콘솔을 통해 APIcast Operator를 설치하는 단계를 제공합니다.

절차

  1. 관리자 권한이 있는 계정을 사용하여 OCP 콘솔에 로그인합니다.
  2. Projects > Create Project(프로젝트 만들기) 에서 operator-test 라는 새 프로젝트를 만듭니다.
  3. Operators > 설치된 Operator를 클릭합니다.
  4. Filter by keyword 상자에 apicast 를 입력하여 APIcast Operator를 찾습니다. 커뮤니티 버전을 사용하지 마십시오.
  5. APIcast 운영자를 클릭합니다. APIcast Operator에 대한 정보가 표시됩니다.
  6. 설치를 클릭합니다. Create Operator Subscription (운영 프로그램 서브스크립션 생성) 페이지가 열립니다.
  7. Subscribe(서브스크립션 )를 클릭하여 Create Operator Subscription (운영 프로그램 서브스크립션 생성) 페이지에서 모든 기본 선택을 수락합니다.

    1. 서브스크립션 업그레이드 상태가 Up to date 로 표시됩니다.
  8. Operators > 설치된 Operator 를 클릭하여 operator-test 프로젝트에서 APIcast Operator ClusterServiceVersion (CSV) 상태가 InstallSucceeded 에 표시되는지 확인합니다.

2.6. Operator를 사용하여 APIcast 게이트웨이 자체 관리 솔루션 배포

이 가이드에서는 Openshift Container Platform 콘솔을 통해 APIcast Operator를 사용하여 APIcast 게이트웨이 자체 관리 솔루션을 배포하는 단계를 제공합니다.

사전 요구 사항

절차

  1. 관리자 권한이 있는 계정을 사용하여 OCP 콘솔에 로그인합니다.
  2. Operators > 설치된 Operators 를 클릭합니다.
  3. 설치된 Operator 목록에서 APIcast Operator 를 클릭합니다.
  4. APIcast > APIcast 생성을 클릭합니다.

2.6.1. APIcast 배포 및 구성 옵션

다음 두 가지 방법을 사용하여 APIcast 게이트웨이 자체 관리 솔루션을 배포하고 구성할 수 있습니다.

또한 다음을 참조하십시오.

2.6.1.1. 3scale 시스템 엔드 포인트 제공

절차

  1. 3scale System Admin Portal 끝점 정보가 포함된 OpenShift 시크릿을 생성합니다.

    oc create secret generic ${SOME_SECRET_NAME} --from-literal=AdminPortalURL=${MY_3SCALE_URL}
    • ${SOME_SECRET_NAME} 은 비밀의 이름이며 기존 비밀과 충돌하지 않는 한 원하는 이름이 될 수 있습니다.
    • ${MY_3SCALE_URL} 은 3scale 액세스 토큰과 3scale 시스템 포털 엔드포인트를 포함하는 URI입니다. 자세한 내용은 THREESCALE_PORTAL_ENDPOINT를 참조하십시오.

      예제

      oc create secret generic 3scaleportal --from-literal=AdminPortalURL=https://access-token@account-admin.3scale.net

      시크릿 콘텐츠에 대한 자세한 내용은 관리 포털 구성 시크릿 참조를 살펴보십시오.

  2. APIcast용 OpenShift 오브젝트 생성

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      adminPortalCredentialsRef:
        name: SOME_SECRET_NAME

    spec.adminPortalCredentialsRef.name 은 3scale 시스템 관리 포털 엔드포인트 정보가 포함된 기존 OpenShift 시크릿의 이름이어야 합니다.

  3. APIcast 오브젝트와 연결된 OpenShift Deployment의 readyReplicas 필드가 1 인지 확인하여 APIcast 포드가 실행 중이고 준비되었는지 확인합니다. 또는 다음과 같이 필드가 설정될 때까지 기다립니다.

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
2.6.1.1.1. APIcast 게이트웨이가 실행 중이고 사용 가능한지 확인

절차

  1. OpenShift Service APIcast가 로컬 시스템에 노출되어 있는지 확인하고 테스트 요청을 수행합니다. APIcast OpenShift 서비스를 localhost:8080 으로 포트 전달하여 이를 수행합니다.

    oc port-forward svc/apicast-example-apicast 8080
  2. 구성된 3scale 서비스에 요청하여 성공적인 HTTP 응답을 확인합니다. 서비스의 Staging Public Base URL 또는 Production Public Base URL 에 구성된 도메인 이름을 사용합니다. 예를 들면 다음과 같습니다.

    $ curl 127.0.0.1:8080/test -H "Host: myhost.com"
2.6.1.1.2. Kubernetes 인그레스를 통해 외부에서 APIcast 노출

Kubernetes 인그레스를 통해 APIcast를 외부에 노출하려면 exposedHost 섹션을 설정하고 구성합니다. exposedHost 섹션의 host 필드가 설정되면 Kubernetes 인그레스 오브젝트가 생성됩니다. 그런 다음 Kubernetes Ingress 오브젝트를 이전에 설치한 기존 Kubernetes Ingress 컨트롤러에서 사용하여 APIcast를 외부에서 액세스할 수 있습니다.

외부에서 APIcast에 액세스할 수 있도록 하는 Ingress 컨트롤러에 대한 자세한 내용은 Kubernetes Ingress 컨트롤러 설명서 를 참조하십시오.

호스트 이름 myhostname.com 을 사용하여 APIcast를 공개하는 다음 예제:

apiVersion: apps.3scale.net/v1alpha1
kind: APIcast
metadata:
  name: example-apicast
spec:
  ...
  exposedHost:
    host: "myhostname.com"
  ...

이 예제에서는 HTTP를 사용하여 포트 80에 Kubernetes Ingress 오브젝트를 생성합니다. APIcast 배포가 OpenShift 환경에 있는 경우 OpenShift 기본 Ingress 컨트롤러는 Ingress 개체 APIcast 생성을 사용하여 Route 오브젝트를 생성하여 APIcast 설치에 외부에서 액세스할 수 있습니다.

exposedHost 섹션에 대해 TLS를 구성할 수도 있습니다. 다음 표의 사용 가능한 필드에 대한 세부 정보:

표 2.3. APIcastExposedHost 참조 테이블

JSON/yaml 필드유형필수 항목기본값설명

호스트

string

있음

해당 없음

게이트웨이로 라우팅되는 도메인 이름

tls

[]extensions.IngressTLS

없음

해당 없음

인그레스 TLS 개체의 배열입니다. TLS 에 대해 자세히 알아보기.

2.6.1.2. 구성 시크릿 제공

절차

  1. 구성 파일을 사용하여 보안을 생성합니다.

    $ curl https://raw.githubusercontent.com/3scale/APIcast/master/examples/configuration/echo.json -o $PWD/config.json
    
    oc create secret generic apicast-echo-api-conf-secret --from-file=$PWD/config.json

    구성 파일을 config.json 이라고 합니다. 이는 APIcast CRD 참조 요구 사항입니다.

    시크릿 콘텐츠에 대한 자세한 내용은 관리 포털 구성 시크릿 참조를 살펴보십시오.

  2. APIcast 사용자 정의 리소스를 생성합니다.

    $ cat my-echo-apicast.yaml
    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: my-echo-apicast
    spec:
      exposedHost:
        host: YOUR DOMAIN
      embeddedConfigurationSecretRef:
        name: apicast-echo-api-conf-secret
    
    $ oc apply -f my-echo-apicast.yaml
    1. 다음은 포함된 구성 보안의 예입니다.

      apiVersion: v1
      kind: Secret
      metadata:
        name: SOME_SECRET_NAME
      type: Opaque
      stringData:
        config.json: |
          {
            "services": [
              {
                "proxy": {
                  "policy_chain": [
                    { "name": "apicast.policy.upstream",
                      "configuration": {
                        "rules": [{
                          "regex": "/",
                          "url": "http://echo-api.3scale.net"
                        }]
                      }
                    }
                  ]
                }
              }
            ]
          }
  3. APIcast 오브젝트를 생성할 때 다음 콘텐츠를 설정합니다.

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      embeddedConfigurationSecretRef:
        name: SOME_SECRET_NAME

    spec.embeddedConfigurationSecretRef.name 은 게이트웨이 구성이 포함된 기존 OpenShift 시크릿의 이름이어야 합니다.

  4. APIcast 오브젝트와 연결된 OpenShift Deployment의 readyReplicas 필드가 1 인지 확인하여 APIcast 포드가 실행 중이고 준비되었는지 확인합니다. 또는 다음과 같이 필드가 설정될 때까지 기다립니다.

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
2.6.1.2.1. APIcast 게이트웨이가 실행 중이고 사용 가능한지 확인

절차

  1. OpenShift Service APIcast가 로컬 시스템에 노출되어 있는지 확인하고 테스트 요청을 수행합니다. APIcast OpenShift 서비스를 localhost:8080 으로 포트 전달하여 이를 수행합니다.

    oc port-forward svc/apicast-example-apicast 8080
  2. 구성된 3scale 서비스에 요청하여 성공적인 HTTP 응답을 확인합니다. 서비스의 Staging Public Base URL 또는 Production Public Base URL 에 구성된 도메인 이름을 사용합니다. 예를 들면 다음과 같습니다.

    $  curl 127.0.0.1:8080/test -H "Host: localhost"
    {
      "method": "GET",
      "path": "/test",
      "args": "",
      "body": "",
      "headers": {
        "HTTP_VERSION": "HTTP/1.1",
        "HTTP_HOST": "echo-api.3scale.net",
        "HTTP_ACCEPT": "*/*",
        "HTTP_USER_AGENT": "curl/7.65.3",
        "HTTP_X_REAL_IP": "127.0.0.1",
        "HTTP_X_FORWARDED_FOR": ...
        "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
        "HTTP_X_FORWARDED_PORT": "80",
        "HTTP_X_FORWARDED_PROTO": "http",
        "HTTP_FORWARDED": "for=10.0.101.216;host=echo-api.3scale.net;proto=http"
      },
      "uuid": "603ba118-8f2e-4991-98c0-a9edd061f0f0"

2.6.1.3. APIcast Operator를 사용하여 사용자 정의 환경 삽입

자체 관리 APIcast를 사용하는 3scale 설치에서는 APIcast 연산자를 사용하여 사용자 지정 환경을 삽입할 수 있습니다. 사용자 지정 환경은 게이트웨이가 제공하는 모든 업스트림 API에 APIcast가 적용되는 동작을 정의합니다. 사용자 지정 환경을 만들려면 Lua 코드에서 글로벌 구성을 정의합니다.

APIcast 설치 후 또는 APIcast 설치 후 사용자 지정 환경을 삽입할 수 있습니다. 사용자 지정 환경을 삽입한 후 이를 제거하고 APIcast Operator가 변경 사항을 조정할 수 있습니다.

사전 요구 사항

  • APIcast Operator가 설치되어 있습니다.

절차

  1. 삽입할 사용자 지정 환경을 정의하는 Lua 코드를 작성합니다. 예를 들어 다음 env1.lua 파일은 APIcast 운영자가 모든 서비스에 대해 로드하는 사용자 지정 로깅 정책을 보여줍니다.

    local cjson = require('cjson')
    local PolicyChain = require('apicast.policy_chain')
    local policy_chain = context.policy_chain
    
    local logging_policy_config = cjson.decode([[
    {
      "enable_access_logs": false,
      "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
    }
    ]])
    
    policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)
    
    return {
      policy_chain = policy_chain,
      port = { metrics = 9421 },
    }
  2. 사용자 지정 환경을 정의하는 Lua 파일에서 시크릿을 생성합니다. 예를 들면 다음과 같습니다.

    oc create secret generic custom-env-1 --from-file=./env1.lua

    시크릿에는 여러 사용자 지정 환경이 포함될 수 있습니다. 사용자 지정 환경을 정의하는 각 파일에 대해 -from-file 옵션을 지정합니다. Operator는 각 사용자 지정 환경을 로드합니다.

  3. 방금 생성한 시크릿을 참조하는 APIcast 사용자 정의 리소스를 정의합니다. 다음 예제에서는 사용자 지정 환경을 정의하는 시크릿을 참조하는 상대적 콘텐츠만 보여줍니다.

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      customEnvironments:
        - secretRef:
            name: custom-env-1

    APIcast 사용자 정의 리소스는 사용자 지정 환경을 정의하는 여러 시크릿을 참조할 수 있습니다. Operator는 각 사용자 지정 환경을 로드합니다.

  4. 사용자 지정 환경을 추가하는 APIcast 사용자 정의 리소스를 생성합니다. 예를 들어 APIcast 사용자 정의 리소스를 apicast.yaml 파일에 저장한 경우 다음 명령을 실행합니다.

    oc apply -f apicast.yaml

다음 단계

사용자 정의 환경을 업데이트하는 경우 시크릿에 업데이트가 포함되도록 시크릿을 다시 만들어야 합니다. APIcast Operator는 업데이트를 감시하고 업데이트를 찾을 때 자동으로 재배포됩니다.

2.6.1.4. APIcast Operator를 사용하여 사용자 정의 정책 삽입

자체 관리 APIcast를 사용하는 3scale 설치에서는 APIcast Operator를 사용하여 사용자 지정 정책을 삽입할 수 있습니다. 사용자 지정 정책을 삽입하면 정책 코드가 APIcast에 추가됩니다. 그런 다음 다음 중 하나를 사용하여 API 제품의 정책 체인에 사용자 지정 정책을 추가할 수 있습니다.

  • 3scale API
  • Product 사용자 정의 리소스

3scale 관리 포털을 사용하여 제품의 정책 체인에 사용자 지정 정책을 추가하려면 사용자 지정 정책의 스키마를 CustomPolicyDefinition 사용자 지정 리소스에 등록해야 합니다. 사용자 지정 정책 등록은 관리 포털을 사용하여 제품의 정책 체인을 구성하려는 경우에만 필요합니다.

사용자 지정 정책을 APIcast 설치의 일부로 삽입할 수 있습니다. 사용자 지정 정책을 삽입한 후 제거할 수 있으며 APIcast operator가 변경 사항을 조정합니다.

사전 요구 사항

  • APIcast Operator가 설치되었거나 설치 중입니다.
  • 자체 정책 쓰기에 설명된 대로 사용자 지정 정책을 정의했습니다. 즉, 사용자 지정 정책을 정의하는 my-first-custom-policy.lua, apicast-policy.json, init.lua 파일이 이미 생성되었습니다.

절차

  1. 하나의 사용자 지정 정책을 정의하는 파일에서 시크릿을 생성합니다. 예를 들면 다음과 같습니다.

    oc create secret generic my-first-custom-policy-secret \
     --from-file=./apicast-policy.json \
     --from-file=./init.lua \
     --from-file=./my-first-custom-policy.lua

    사용자 지정 정책이 두 개 이상 있는 경우 각 사용자 지정 정책에 대한 보안을 생성합니다. 보안에는 하나의 사용자 지정 정책만 포함될 수 있습니다.

  2. 방금 생성한 시크릿을 참조하는 APIcast 사용자 정의 리소스를 정의합니다. 다음 예제에서는 사용자 정의 정책을 정의하는 시크릿을 참조하는 것과 관련된 콘텐츠만 보여줍니다.

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      customPolicies:
        - name: my-first-custom-policy
          version: "0.1"
          secretRef:
            name: my-first-custom-policy-secret

    APIcast 사용자 정의 리소스는 사용자 지정 정책을 정의하는 여러 시크릿을 참조할 수 있습니다. Operator는 각 사용자 지정 정책을 로드합니다.

  3. 사용자 지정 정책을 추가하는 APIcast 사용자 정의 리소스를 생성합니다. 예를 들어 APIcast 사용자 정의 리소스를 apicast.yaml 파일에 저장한 경우 다음 명령을 실행합니다.

    oc apply -f apicast.yaml

다음 단계

사용자 정의 정책을 업데이트하는 경우 보안이 업데이트가 포함되도록 보안을 다시 생성해야 합니다. APIcast Operator는 업데이트를 감시하고 업데이트를 찾을 때 자동으로 재배포됩니다.

2.6.1.5. APIcast Operator를 사용하여 OpenTracing 구성

자체 관리 APIcast를 사용하는 3scale 설치에서는 APIcast Operator를 사용하여 OpenTracing을 구성할 수 있습니다. OpenTracing을 활성화하면 APIcast 인스턴스에 대한 더 많은 통찰력과 가시성을 얻을 수 있습니다.

절차

  1. stringData.config 에 OpenTracing 구성 세부 정보가 포함된 시크릿을 정의합니다. 이는 OpenTracing 구성 세부 정보가 포함된 속성에 대해 유일하게 유효한 값입니다. 다른 사양에서는 APIcast가 OpenTracing 구성 세부 정보를 수신하지 못하도록 합니다. 다음 예제에서는 유효한 보안 정의를 보여줍니다.

    apiVersion: v1
    kind: Secret
    metadata:
      name: myjaeger
    stringData:
      config: |-
          {
          "service_name": "apicast",
          "disabled": false,
          "sampler": {
            "type": "const",
            "param": 1
          },
          "reporter": {
            "queueSize": 100,
            "bufferFlushInterval": 10,
            "logSpans": false,
            "localAgentHostPort": "jaeger-all-in-one-inmemory-agent:6831"
          },
          "headers": {
            "jaegerDebugHeader": "debug-id",
            "jaegerBaggageHeader": "baggage",
            "TraceContextHeaderName": "uber-trace-id",
            "traceBaggageHeaderPrefix": "testctx-"
          },
          "baggage_restrictions": {
              "denyBaggageOnInitializationFailure": false,
              "hostPort": "127.0.0.1:5778",
              "refreshInterval": 60
          }
          }
    type: Opaque
  2. 시크릿을 생성합니다. 예를 들어 이전 시크릿 정의를 myjaeger.yaml 파일에 저장한 경우 다음 명령을 실행합니다.

    oc create secret generic myjaeger --from-file myjaeger.yaml
  3. OpenTracing 특성을 지정하는 APIcast 사용자 지정 리소스를 정의합니다. CR 정의에서 spec.tracingConfigSecretRef.name 속성을 OpenTracing 구성 세부 정보가 포함된 보안 이름으로 설정합니다. 다음 예제에서는 OpenTracing 구성을 기준으로 한 콘텐츠만 보여줍니다.

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: apicast1
    spec:
      ...
      openTracing:
        enabled: true
        tracingConfigSecretRef:
          name: myjaeger
        tracingLibrary: jaeger
    ...
  4. OpenTracing을 구성하는 APIcast 사용자 정의 리소스를 만듭니다. 예를 들어 APIcast 사용자 정의 리소스를 apicast1.yaml 파일에 저장한 경우 다음 명령을 실행합니다.

    oc apply -f apicast1.yaml

다음 단계

OpenTracing이 설치된 방법에 따라 Jaeger 서비스 사용자 인터페이스에 추적이 표시되어야 합니다.

2.7. 추가 리소스

최신 릴리스 및 지원되는 APIcast 버전에 대한 자세한 내용은 다음 문서를 참조하십시오.

3장. APIcast 호스팅

이 튜토리얼을 완료하면 클라우드의 보안 게이트웨이로 API를 완전히 보호하게 됩니다.

APIcast는 가능한 한 빨리 API를 시작하거나 최소한의 인프라 변경을 원하는 경우 최상의 배포 옵션입니다.

사전 요구 사항

3.1. 스테이징 환경에서 호스팅되는 APIcast를 사용하여 API 배포

첫 번째 단계는 API를 구성하고 스테이징 환경에서 테스트합니다.

절차

  1. 개인 기본 URL 및 해당 엔드포인트를 정의합니다.
  2. 자격 증명 및 기타 구성 세부 사항의 배치를 선택합니다. 자세한 내용은 APIcast Hosted 문서를 참조하십시오.
  3. Update Product(제품 업데이트 )를 클릭하여 구성 설정을 저장합니다. 이러한 설정은 APIcast 스테이징 인스턴스를 API로 수행합니다.

구성이 완료되면 녹색 확인 메시지가 표시됩니다.

다음 단계로 이동하기 전에 백엔드 서비스의 유효성을 검증하도록 비밀 토큰을 구성했는지 확인합니다. Authentication Settings (인증 설정)에서 보안 토큰의 값을 정의할 수 있습니다. 이렇게 하면 nobody가 APIcast 액세스 제어를 우회할 수 있습니다.

3.2. 프로덕션으로 호스팅되는 APIcast를 사용하여 API 배포

이때 API 구성을 프로덕션 환경으로 전환할 준비가 되었습니다. 3scale 호스팅 APIcast 인스턴스를 배포하려면 다음을 수행합니다.

절차

  1. Integration(통합) 및 Configuration (구성) 페이지로 돌아가서 'Promote to Production to Production' 단추를 클릭합니다.
  2. 이 단계를 반복하여 프로덕션 환경에 대한 스테이징 환경의 추가 변경을 촉진합니다.

구성이 모든 클라우드 APIcast 인스턴스를 배포하고 전파하는 데 5~7분이 걸립니다. 재배포하는 동안 API에 다운타임이 발생하지 않습니다. API 호출은 호출을 제공하는 인스턴스에 따라 다양한 응답을 반환할 수 있습니다. 프로덕션 환경 주변의 상자가 녹색으로 전환되면 배포가 성공적으로 완료되었습니다.

스테이징 및 프로덕션 APIcast 인스턴스 모두 apicast.io 도메인에 기본 URL이 있습니다. 스테이징 환경 URL에 스테이징 하위 도메인이 있으므로 서로 구분할 수 있습니다. 예를 들면 다음과 같습니다.

3.3. 추가 정보

  • 50,000건의 조회/일은 APIcast 프로덕션 클라우드 인스턴스를 통해 API에 허용되는 최대값입니다. 관리 포털의 분석 섹션에서 API 사용량을 확인할 수 있습니다.
  • API 트래픽 급증 시 초당 20개의 하드 제한값이 발생합니다.
  • 스로틀 제한 위에 APIcast는 응답 코드 403 을 반환합니다. 이는 속도 제한을 초과하는 애플리케이션의 기본값과 동일합니다. 오류를 구분하려면 응답 본문을 확인하십시오.

4장. Docker 컨테이너 환경에 APIcast 배포

이 가이드는 Red Hat 3scale API 게이트웨이로 사용할 준비가 된 Docker 컨테이너 엔진 내에 APIcast를 배포하는 단계별 가이드입니다.

참고

Docker 컨테이너 환경에 APIcast를 배포할 때 지원되는 RHEL(Red Hat Enterprise Linux) 및 Docker 버전은 다음과 같습니다.

  • RHEL 7.7
  • Docker 1.13.1

사전 요구 사항

Docker 컨테이너 환경에서 APIcast를 배포하려면 다음 섹션에 설명된 단계를 수행합니다.

4.1. Docker 컨테이너 환경 설치

이 가이드에서는 RHEL 7.x에서 Docker 컨테이너 환경을 설정하는 단계를 설명합니다.

Red Hat에서 제공하는 Docker 컨테이너 엔진은 RHEL에서 Extras 채널의 일부로 출시됩니다. 추가 리포지토리를 활성화하려면 Subscription Manager 또는 yum-config-manager 옵션을 사용할 수 있습니다. 자세한 내용은 RHEL 제품 설명서 를 참조하십시오.

AWS(Amazon Web Services)에 RHEL 7.x를 배포하려면 Amazon EC2(Amazon Elastic Compute Cloud) 인스턴스에 다음 단계를 수행합니다.

절차

  1. 모든 리포지토리 나열: sudo yum repolist all.
  2. *-extras 리포지토리를 찾습니다.
  3. extras 리포지토리를 활성화합니다. sudo yum-config-manager --enable rhui-REGION-rhel-server-extras.
  4. Docker 컨테이너 환경 패키지를 설치합니다. sudo yum install docker.

추가 리소스

다른 운영 체제의 경우 다음 Docker 설명서를 참조하십시오.

4.2. Docker 컨테이너 환경 게이트웨이 실행

중요

3scale 2.11에서는 RHEL 7에서 컨테이너로 실행되는 APIcast 배포에 대한 지원이 더 이상 사용되지 않습니다. 향후 릴리스에서 3scale은 RHEL 8 및 Podman만 지원합니다. APIcast 자체 관리를 컨테이너로 실행하는 경우 지원되는 구성으로 설치를 업그레이드합니다.

Docker 컨테이너 환경 게이트웨이를 실행하려면 다음을 수행합니다.

절차

  1. Docker 데몬을 시작합니다.

    sudo systemctl start docker.service
  2. Docker 데몬이 실행 중인지 확인합니다.

    sudo systemctl status docker.service

Red Hat 레지스트리에서 Docker 컨테이너 엔진 이미지를 사용할 준비가 된 것을 다운로드할 수 있습니다.

+

sudo docker pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel7:3scale2.13
  1. Docker 컨테이너 엔진에서 APIcast를 실행합니다.

    sudo docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.redhat.io/3scale-amp2/apicast-gateway-rhel7:3scale2.13

    여기서 <access_token> 은 3scale 계정 관리 API의 액세스 토큰입니다. 액세스 토큰 대신 공급자 키를 사용할 수 있습니다. <domain>-admin.3scale.net 은 3scale 관리 포털의 URL입니다.

이 명령은 포트 8080 에서 "apicast" 라는 Docker 컨테이너 엔진을 실행하고 3scale 관리 포털에서 JSON 구성 파일을 가져옵니다. 다른 구성 옵션은 APIcast 설치를 참조하십시오.

4.2.1. docker 명령 옵션

docker run 명령과 함께 다음 옵션을 사용할 수 있습니다.

  • --rm: 종료 시 컨테이너를 자동으로 제거합니다.
  • -d 또는 --detach: 컨테이너를 백그라운드에서 실행하고 컨테이너 ID를 인쇄합니다. 지정되지 않은 경우 컨테이너는 포그라운드 모드에서 실행되며 CTRL + c 를 사용하여 중지할 수 있습니다. 분리 모드에서 시작하는 경우 docker attach 명령을 사용하여 컨테이너에 다시 연결할 수 있습니다(예: docker attach apicast ).
  • -p 또는 --publish: 컨테이너의 포트를 호스트에 게시합니다. 값에는 <host port="">:<container port=""> 형식이 있어야 하므로 -p 80:8080 은 컨테이너의 8080 포트를 호스트 시스템의 포트 80 에 바인딩합니다. 예를 들어 관리 API는 포트 8090 을 사용하므로 -p 8090:8090docker run 명령에 추가하여 이 포트를 게시할 수 있습니다.
  • -e 또는 --env: 환경 변수를 설정합니다.
  • -v 또는 --volume: 볼륨을 마운트합니다. 값은 일반적으로 <host path="">:<container path=""[:<options>] 로 표시됩니다. <options&gt;는 선택적 속성입니다. 볼륨을 읽기 전용으로 지정하려면 :ro로 설정할 수 있습니다(기본적으로 읽기-쓰기 모드로 마운트됨). 예: -v /host/path:/container/path:ro.

4.2.2. APIcast 테스트

이전 단계에서는 Docker 컨테이너 엔진이 자체 구성 파일과 3scale 레지스트리의 Docker 컨테이너 이미지를 사용하여 실행 중인지 확인합니다. 포트 8080 에서 APIcast를 통해 호출을 테스트하고 3scale 계정에서 가져올 수 있는 올바른 인증 자격 증명을 제공할 수 있습니다.

테스트 호출은 APIcast가 올바르게 실행되고 있지만 인증 및 보고가 성공적으로 처리되고 있는지 확인합니다.

참고

호출에 사용하는 호스트가 Integration (통합) 페이지의 Public Base URL 필드에 구성된 호스트와 같은지 확인합니다.

추가 리소스

4.3. 추가 리소스

5장. Podman에 APIcast 배포

이 가이드는 Red Hat 3scale API 게이트웨이로 사용할 Pod Manager(Podman) 컨테이너 환경에 APIcast를 배포하는 단계별 가이드입니다.

참고

Podman 컨테이너 환경에 APIcast를 배포할 때 지원되는 RHEL(Red Hat Enterprise Linux) 및 Podman 버전은 다음과 같습니다.

  • RHEL 8.x
  • podman 1.4.2

사전 요구 사항

Podman 컨테이너 환경에 APIcast를 배포하려면 다음 섹션에 설명된 단계를 수행합니다.

5.1. Podman 컨테이너 환경 설치

이 가이드에서는 RHEL 8.x에서 Podman 컨테이너 환경을 설정하는 단계를 설명합니다. Docker는 RHEL 8.x에 포함되지 않으므로 컨테이너 작업을 위해 Podman을 사용합니다.

RHEL 8.x를 사용한 Podman에 대한 자세한 내용은 컨테이너 명령줄 참조를 참조하십시오.

절차

  • Podman 컨테이너 환경 패키지를 설치합니다.

    sudo dnf 설치 podman

추가 리소스

다른 운영 체제의 경우 다음 Podman 설명서를 참조하십시오.

5.2. Podman 환경 실행

Podman 컨테이너 환경을 실행하려면 아래 절차를 따르십시오.

절차

  1. Red Hat 레지스트리에서 Podman 컨테이너 이미지를 사용할 준비를 다운로드합니다.

    podman pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13
  2. Podman에서 APIcast를 실행합니다.

    podman run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13

    여기서 <access_token> 은 3scale 계정 관리 API의 액세스 토큰입니다. 액세스 토큰 대신 공급자 키를 사용할 수 있습니다. <domain>-admin.3scale.net 은 3scale 관리 포털의 URL입니다.

이 명령은 포트 8080 에서 "apicast" 라는 Podman 컨테이너 엔진을 실행하고 3scale 관리 포털에서 JSON 구성 파일을 가져옵니다. 다른 구성 옵션은 APIcast 설치를 참조하십시오.

5.2.1. Podman을 사용하여 APIcast 테스트

이전 단계에서는 Podman 컨테이너 엔진이 3scale 레지스트리의 Podman 컨테이너 이미지와 자체 구성 파일을 사용하여 실행 중인지 확인합니다. 포트 8080 에서 APIcast를 통해 호출을 테스트하고 3scale 계정에서 가져올 수 있는 올바른 인증 자격 증명을 제공할 수 있습니다.

테스트 호출은 APIcast가 올바르게 실행되고 있지만 인증 및 보고가 성공적으로 처리되고 있는지 확인합니다.

참고

호출에 사용하는 호스트가 Integration (통합) 페이지의 Public Base URL 필드에 구성된 호스트와 같은지 확인합니다.

5.3. podman 명령 옵션

podman 명령과 함께 다음 옵션 예제를 사용할 수 있습니다.

  • -d: 분리된 모드로 컨테이너를 실행하고 컨테이너 ID를 인쇄합니다. 지정되지 않은 경우 컨테이너는 포그라운드 모드에서 실행되며 CTRL + c 를 사용하여 중지할 수 있습니다. 분리 모드에서 시작하는 경우 podman attach 명령을 사용하여 컨테이너에 다시 연결할 수 있습니다(예: podman attach apicast ).
  • ps-a: Podman ps 는 컨테이너 생성 및 실행을 나열하는 데 사용됩니다. ps 명령에 -a 를 추가하면 실행 중 및 중지된 모든 컨테이너(예: podman ps -a )가 표시됩니다.
  • 검사-l: 실행 중인 컨테이너를 검사합니다. 예를 들어 inspect 를 사용하여 컨테이너에 할당된 ID를 확인합니다. 최신 컨테이너의 세부 정보를 가져오려면 -l 을 사용합니다(예: podman inspect -l | grep Id\": ).

5.4. 추가 리소스