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는 시크릿에서 필드 이름을 읽지 않습니다.
사전 요구 사항
절차
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"
시크릿을 생성합니다. 예를 들면 다음과 같습니다.
$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
OpenAPI
CR을 정의합니다. OAS 문서가 포함된 보안에 대한 참조를 지정해야 합니다. 예를 들어myopenapicr1.yaml
파일을 생성할 수 있습니다.apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: name: myopenapicr1 spec: openapiRef: secretRef: name: myoasdoc1
방금 정의한 리소스를 생성합니다. 예를 들면 다음과 같습니다.
$ 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 Security 는 OpenAPI
CRD의 spec.privateAPIHostHeader
및 spec.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이 연결되는 테넌트를 식별하는 보안이 포함되어 있습니다. 보안 이름은 다음 중 하나입니다.-
threescale-provider-account
- 사용자 정의
이 시크릿에는 3scale 인스턴스의 URL과 해당 3scale 인스턴스의 테넌트 1개에 대한 액세스 자격 증명이 포함된 토큰이 포함됩니다.
-
절차
- OpenShift 계정에서 Operator > 설치된 운영자로 이동합니다.
- 3scale Operator를 클릭합니다.
- YAML 탭을 선택합니다.
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
-
저장을 클릭합니다. 3scale Operator가
OpenAPI
CR을 생성하는 데 몇 초가 걸립니다.
검증
-
OpenShift에서 3scale 제품 개요 페이지에서 동기화 조건이
True
로 표시되는지 확인합니다. - 3scale 계정으로 이동합니다.
-
OAS 문서가 있는지 확인합니다. 위의 예제에서는
openapi1
이라는 새 OAS 문서를 볼 수 있습니다.