8.6. 3scale OpenAPI 사용자 정의 리소스 배포

OpenAPI CR(사용자 정의 리소스)은 개발자 포털의 ActiveDocs에 사용할 수 있는 OCI(OpenAPI Specification) 문서를 가져오는 한 가지 방법입니다. OAS는 API에 대해 특정 프로그래밍 언어를 사용하는 것과 관련이 없는 표준입니다. 사람과 컴퓨터는 소스 코드 액세스, 문서 또는 네트워크 트래픽 검사 없이 API 제품의 기능을 보다 쉽게 이해할 수 있습니다.

사전 요구 사항

  • 3scale 2.11 On-Premises 인스턴스에 대한 관리자 권한이 있는 사용자 계정.
  • API를 정의하는 OAS 문서입니다.
  • OpenAPI CR이 테넌트에 연결되는 방법에 대한 이해.

8.6.1. 시크릿에서 OAS 문서를 가져오는 3scale OpenAPI 사용자 정의 리소스 배포

3scale 백엔드제품을 생성할 수 있도록 OpenAPI CR(사용자 정의 리소스)을 배포합니다.

참고

Operator는 시크릿의 콘텐츠만 읽습니다. Operator는 시크릿에서 필드 이름을 읽지 않습니다.

절차

  1. OAS 문서가 포함된 시크릿을 정의합니다. 예를 들어 다음 콘텐츠를 사용하여 myoasdoc1.yaml 을 생성할 수 있습니다.

    openapi: "3.0.2"
    info:
      title: "some title"
      description: "some description"
      version: "1.0.0"
    paths:
      /pet:
        get:
          operationId: "getPet"
          responses:
            405:
              description: "invalid input"
  2. 시크릿을 생성합니다. 예를 들면 다음과 같습니다.

    $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml
    
    secret/myoasdoc1 created
  3. OpenAPI CR을 정의합니다. OAS 문서가 포함된 보안에 대한 참조를 지정해야 합니다. 예를 들어 myopenapicr1.yaml 파일을 생성할 수 있습니다.

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: myopenapicr1
    spec:
      openapiRef:
        secretRef:
          name: myoasdoc1
  4. 방금 정의한 리소스를 생성합니다. 예를 들면 다음과 같습니다.

    $ oc create -f myopenapicr1.yaml

    주어진 예에서 출력은 다음과 같습니다.

    openapi.capabilities.3scale.net/myopenapicr1 created

8.6.2. 3scale OpenAPI 사용자 정의 리소스 정의의 기능

CRD(OpenAPI 사용자 정의 리소스 정의) 배포 기능에 대한 정보는 3scale 제품, 백엔드 및 개발자 포털에 대한 ActiveDoc을 구성하는 데 도움이 됩니다.

  • OAS 문서는 다음에서 읽을 수 있습니다.

    • Kubernetes 시크릿
    • http 및 https 형식의 URL
  • OAS 문서에서 info.title 설정은 215자를 초과해서는 안 됩니다. Operator는 이 설정을 사용하여 길이 제한이 있는 OpenShift 오브젝트 이름을 생성합니다.
  • 서버 목록의 첫 번째 서버[0].url 요소만 개인 URL로 구문 분석됩니다. OAS(OpenAPI Specification)는 servers[0].url 요소의 basePath 구성 요소를 사용합니다.
  • OpenAPI CRD는 단일 최상위 보안 요구 사항을 지원하지만 운영 수준 보안은 지원하지 않습니다.
  • OpenAPI CRD는 apiKey 보안 스키마를 지원합니다.

8.6.3. OpenAPI 사용자 정의 리소스 정의 시 규칙 가져오기

가져오기 규칙은 3scale 배포에 대해 OpenAPI 문서를 설정할 때 OCI(OpenAPI Specification)가 3scale로 작동하는 방식을 지정합니다.

제품 이름

기본 제품 시스템 이름은 OpenAPI 문서의 info.title 필드에서 가져온 것입니다. OpenAPI 문서의 제품 이름을 재정의하려면 OpenAPI CR(사용자 정의 리소스)에서 spec.productSystemName 필드를 지정합니다.

프라이빗 기본 URL

개인 기본 URL은 OpenAPI CR servers[0].url 필드에서 읽습니다. OpenAPI CR의 spec.privateBaseURL 필드를 사용하여 이 값을 덮어쓸 수 있습니다.

3scale 방법

가져온 OpenAPI 문서에 정의된 각 작업은 제품 수준에서 하나의 3scale 메서드로 변환됩니다. 메서드 이름은 작업 오브젝트의 operationId 필드에서 읽습니다.

3scale 매핑 규칙

가져온 OpenAPI 문서에 정의된 각 작업은 제품 수준에서 하나의 3scale 매핑 규칙으로 변환됩니다. 이전 버전에서는 기존 매핑 규칙이 OpenAPI CR로 가져온 규칙으로 교체되었습니다.

OpenAPI 문서에서 paths 오브젝트는 동사 및 패턴 속성에 대한 매핑 규칙을 제공합니다. 3scale 방법은 operationsId 에 따라 연결됩니다.

delta 값은 1 로 하드 코딩됩니다.

기본적으로 Strict 일치 정책이 구성됩니다. 일치하는 정책은 OpenAPI CRD의 spec.PrefixMatching 필드를 사용하여 Prefix matching 로 전환할 수 있습니다.

인증

하나의 최상위 보안 요구 사항만 지원됩니다. 작업 수준 보안 요구 사항은 지원되지 않습니다.

지원되는 보안 스키마는 apiKey 입니다.

apiKey 보안 스키마 유형:

  • 자격 증명 위치는 보안 스키마 오브젝트의 OpenAPI 문서에서 읽습니다.
  • 인증 사용자 키는 보안 스키마 오브젝트의 OpenAPI 문서 이름 필드에서 읽습니다.

다음은 apiKey 보안 요구 사항이 있는 OAS 3.0.2의 일부입니다.

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

OpenAPI 문서에서 보안 요구 사항을 지정하지 않으면 다음이 적용됩니다.

  • 제품 인증은 apiKey 에 대해 구성됩니다.
  • 인증 정보 위치는 기본적으로 3scale 값 인 쿼리 매개변수(GET) 또는 본문 매개변수(GET/PUT/DELETE) 로 설정됩니다.
  • Auth 사용자 키의 기본값은 3scale 값 user_key 입니다.

3scale Authentication SecurityOpenAPI CRD의 spec.privateAPIHostHeaderspec.privateAPISecretToken 필드를 사용하여 설정할 수 있습니다.

ActiveDocs

3scale ActiveDoc이 생성되지 않습니다.

3scale 제품 정책 체인

3scale 정책 체인은 기본 1개 3scale 생성입니다.

3scale 배포 모드

기본적으로 구성된 3scale 배포 모드는 APIcast 3scale managed입니다. 그러나 spec.productionPublicBaseURL 또는 spec.stagingPublicBaseURL. 또는 두 필드가 OpenAPI CR에 있는 경우 제품의 배포 모드는 APIcast 자체 관리입니다.

사용자 정의 공용 기본 URL이 있는 OpenAPI CR의 예:

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

8.6.4. URL에서 OAS 문서를 가져오는 3scale OpenAPI 사용자 정의 리소스 배포

지정하는 URL에서 OAS 문서를 가져오는 OpenAPI 사용자 정의 리소스를 배포할 수 있습니다. 그런 다음 이 OAS 문서를 개발자 포털에서 API의 ActiveDocs 기반으로 사용할 수 있습니다.

사전 요구 사항

  • 동일한 네임스페이스에 있는 3scale 인스턴스에서 기본 테넌트에 연결되지 않는 OpenAPI 사용자 정의 리소스를 생성하는 경우 OpenAPI CR을 포함할 네임스페이스에는 OpenAPI CR이 연결되는 테넌트를 식별하는 보안이 포함되어 있습니다. 보안 이름은 다음 중 하나입니다.

    • threescale-provider-account
    • 사용자 정의

    이 시크릿에는 3scale 인스턴스의 URL과 해당 3scale 인스턴스의 테넌트 1개에 대한 액세스 자격 증명이 포함된 토큰이 포함됩니다.

절차

  1. OpenShift 계정에서 Operator > 설치된 운영자로 이동합니다.
  2. 3scale Operator를 클릭합니다.
  3. YAML 탭을 선택합니다.
  4. OpenAPI 사용자 정의 리소스를 생성합니다. 예를 들면 다음과 같습니다.

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: openapi1
    spec:
      openapiRef:
        url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
      providerAccountRef:
        name: mytenant
  5. 저장을 클릭합니다. 3scale Operator가 OpenAPI CR을 생성하는 데 몇 초가 걸립니다.

검증

  1. OpenShift에서 3scale 제품 개요 페이지에서 동기화 조건이 True 로 표시되는지 확인합니다.
  2. 3scale 계정으로 이동합니다.
  3. OAS 문서가 있는지 확인합니다. 위의 예제에서는 openapi1 이라는 새 OAS 문서를 볼 수 있습니다.

8.6.5. 추가 리소스