3.5. Operator를 사용하여 APIcast 게이트웨이 자체 관리 솔루션 배포
이 가이드에서는 Openshift Container Platform 콘솔을 통해 APIcast Operator를 사용하여 APIcast 게이트웨이 자체 관리 솔루션을 배포하는 단계를 제공합니다.
기본 설정은 APIcast를 배포할 때 프로덕션 환경에 대한 것입니다. 스테이징 환경을 배포하기 위해 항상 이러한 설정을 조정할 수 있습니다. 예를 들어 다음 oc
명령을 사용합니다.
$ oc patch apicast/{apicast_name} --type=merge -p '{"spec":{"deploymentEnvironment":"staging","configurationLoadMode":"lazy"}}'
자세한 내용은 APIcast 사용자 정의 리소스 참조를 참조하십시오.
사전 요구 사항
- 관리자 권한이 있는 OCP(OpenShift Container Platform) 4.x 이상.
- OpenShift에 APIcast Operator 설치 단계를 수행했습니다.
절차
- 관리자 권한이 있는 계정을 사용하여 OCP 콘솔에 로그인합니다.
- Operators > 설치된 Operators를 클릭합니다.
- Installed Operators 목록에서 APIcast Operator를 클릭합니다.
- APIcast > Create APIcast를 클릭합니다.
3.5.1. APIcast 배포 및 구성 옵션
다음 두 가지 방법을 사용하여 APIcast 게이트웨이 자체 관리 솔루션을 배포하고 구성할 수 있습니다.
또한 다음을 참조하십시오.
3.5.1.1. 3scale 시스템 엔드 포인트 제공
절차
3scale System 관리 포털 엔드포인트 정보가 포함된 OpenShift 시크릿을 생성합니다.
$ oc create secret generic ${SOME_SECRET_NAME} --from-literal=AdminPortalURL=${MY_3SCALE_URL}
-
${SOME_SECRET_NAME}
은 시크릿의 이름이며 기존 보안과 충돌하지 않는 한 원하는 이름이 될 수 있습니다. ${MY_3SCALE_URL}
은 3scale 액세스 토큰 및 3scale System 포털 끝점을 포함하는 URI입니다. 자세한 내용은THREESCALE_PORTAL_ENDPOINT
를 참조하십시오.예제
$ oc create secret generic 3scaleportal --from-literal=AdminPortalURL=https://access-token@account-admin.3scale.net
시크릿 콘텐츠에 대한 자세한 내용은 관리 포털 구성 시크릿 참조를 살펴보십시오.
-
APIcast용 OpenShift 오브젝트 생성
apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: example-apicast spec: adminPortalCredentialsRef: name: SOME_SECRET_NAME
spec.adminPortalCredentialsRef.name
은 3scale 시스템 관리 포털 끝점 정보가 포함된 기존 OpenShift 시크릿의 이름이어야 합니다.APIcast 오브젝트와 연결된 OpenShift 배포의
readyReplicas
필드가 1 인지 확인하여 APIcast Pod가 실행 중이고 준비되었는지 확인합니다. 또는 다음을 사용하여 필드가 설정될 때까지 기다립니다.$ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}') 1
3.5.1.1.1. APIcast 게이트웨이가 실행 중이고 사용 가능한지 확인
절차
OpenShift Service APIcast가 로컬 머신에 노출되었는지 확인하고 테스트 요청을 수행합니다. 이렇게 하려면 포트-캐스트 OpenShift 서비스를
localhost:8080
으로 전달합니다.$ oc port-forward svc/apicast-example-apicast 8080
구성된 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"
3.5.1.1.2. Kubernetes 인그레스를 통해 외부에서 APIcast 노출
쿠버네티스 인그레스를 통해 APIcast를 외부에 노출하려면 exposedHost
섹션을 설정하고 구성하십시오. exposedHost
섹션의 host
필드가 설정되면 Kubernetes Ingress 오브젝트가 생성됩니다. 그런 다음 Kubernetes Ingress 오브젝트는 이전에 설치한 및 기존 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 컨트롤러는 APIcast 설치에 대한 외부 액세스를 허용하는 Ingress 오브젝트 APIcast를 사용하여 Route 오브젝트를 생성합니다.
exposedHost
섹션에 대해 TLS를 구성할 수도 있습니다. 다음 표에서 사용 가능한 필드에 대한 세부 정보:
json/yaml 필드 | 유형 | 필수 항목 | 기본값 | 설명 |
---|---|---|---|---|
| string | 있음 | 해당 없음 | 게이트웨이로 라우팅되는 도메인 이름 |
| []networkv1.IngressTLS | 없음 | 해당 없음 | ingress TLS 오브젝트의 배열입니다. TLS에서 자세한 내용을 참조하십시오. |
3.5.1.2. 구성 시크릿 제공
절차
구성 파일을 사용하여 시크릿을 생성합니다.
$ 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 참조 요구 사항입니다.시크릿 콘텐츠에 대한 자세한 내용은 관리 포털 구성 시크릿 참조를 살펴보십시오.
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
다음은 포함된 구성 시크릿의 예입니다.
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" }] } } ] } } ] }
APIcast 오브젝트를 생성할 때 다음 콘텐츠를 설정합니다.
apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: example-apicast spec: embeddedConfigurationSecretRef: name: SOME_SECRET_NAME
spec.embeddedConfigurationSecretRef.name
은 게이트웨이 구성이 포함된 기존 OpenShift 시크릿의 이름이어야 합니다.APIcast 오브젝트와 연결된 OpenShift 배포의
readyReplicas
필드가 1 인지 확인하여 APIcast Pod가 실행 중이고 준비되었는지 확인합니다. 또는 다음을 사용하여 필드가 설정될 때까지 기다립니다.$ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}') 1
3.5.1.2.1. APIcast 게이트웨이가 실행 중이고 사용 가능한지 확인
절차
OpenShift Service APIcast가 로컬 머신에 노출되었는지 확인하고 테스트 요청을 수행합니다. 이렇게 하려면 포트-캐스트 OpenShift 서비스를
localhost:8080
으로 전달합니다.$ oc port-forward svc/apicast-example-apicast 8080
3.5.1.3. APIcast Operator를 사용하여 사용자 정의 환경 삽입
자체 관리 APIcast를 사용하는 3scale 설치에서는 APIcast
연산자를 사용하여 사용자 지정 환경을 삽입할 수 있습니다. 사용자 지정 환경은 게이트웨이가 제공하는 모든 업스트림 API에 APIcast가 적용되는 동작을 정의합니다. 사용자 지정 환경을 만들려면 Lua 코드에서 글로벌 구성을 정의합니다.
APIcast 설치 후 또는 APIcast 설치 후 사용자 지정 환경을 삽입할 수 있습니다. 사용자 지정 환경을 삽입한 후 이를 제거하고 APIcast
Operator가 변경 사항을 조정할 수 있습니다.
사전 요구 사항
- APIcast Operator가 설치되어 있습니다.
절차
삽입할 사용자 지정 환경을 정의하는 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 }, }
사용자 지정 환경을 정의하는 Lua 파일에서 시크릿을 생성합니다. 예를 들어 다음과 같습니다.
$ oc create secret generic custom-env-1 --from-file=./env1.lua
시크릿에는 여러 사용자 지정 환경이 포함될 수 있습니다. 사용자 지정 환경을 정의하는 각 파일에 대해
-from-file
옵션을 지정합니다. Operator는 각 사용자 지정 환경을 로드합니다.방금 생성한 시크릿을 참조하는
APIcast
사용자 정의 리소스를 정의합니다. 다음 예제에서는 사용자 지정 환경을 정의하는 시크릿을 참조하는 상대적 콘텐츠만 보여줍니다.apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: customEnvironments: - secretRef: name: custom-env-1
APIcast
사용자 정의 리소스는 사용자 지정 환경을 정의하는 여러 시크릿을 참조할 수 있습니다. Operator는 각 사용자 지정 환경을 로드합니다.사용자 지정 환경을 추가하는
APIcast
사용자 정의 리소스를 생성합니다. 예를 들어APIcast
사용자 정의 리소스를apicast.yaml
파일에 저장한 경우 다음 명령을 실행합니다.$ oc apply -f apicast.yaml
다음 단계
사용자 정의 환경을 업데이트하는 경우 시크릿에 업데이트가 포함되도록 시크릿을 다시 만들어야 합니다. APIcast
Operator는 업데이트를 감시하고 업데이트를 찾을 때 자동으로 재배포됩니다.
3.5.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
파일이 이미 생성되었습니다.
절차
하나의 사용자 지정 정책을 정의하는 파일에서 시크릿을 생성합니다. 예를 들어 다음과 같습니다.
$ 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
사용자 지정 정책이 두 개 이상 있는 경우 각 사용자 지정 정책에 대한 보안을 생성합니다. 보안에는 하나의 사용자 지정 정책만 포함될 수 있습니다.
방금 생성한 시크릿을 참조하는
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는 각 사용자 지정 정책을 로드합니다.사용자 지정 정책을 추가하는
APIcast
사용자 정의 리소스를 생성합니다. 예를 들어APIcast
사용자 정의 리소스를apicast.yaml
파일에 저장한 경우 다음 명령을 실행합니다.$ oc apply -f apicast.yaml
다음 단계
사용자 정의 정책을 업데이트하는 경우 보안이 업데이트가 포함되도록 보안을 다시 생성해야 합니다. APIcast
Operator는 업데이트를 감시하고 업데이트를 찾을 때 자동으로 재배포됩니다.
추가 리소스
3.5.1.5. APIcast Operator를 사용하여 OpenTracing 구성
자체 관리 APIcast
를 사용하는 3scale 설치에서는 APIcast Operator를 사용하여 OpenTracing을 구성할 수 있습니다. OpenTracing을 활성화하면 APIcast 인스턴스에 대한 더 많은 통찰력과 가시성을 얻을 수 있습니다.
사전 요구 사항
-
APIcast
Operator가 설치되었거나 설치 중입니다. - OpenTracing을 사용하도록 APIcast 구성에 나열된 사전 요구 사항입니다.
- Jaeger가 설치되어 있어야 합니다.
절차
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
시크릿을 생성합니다. 예를 들어 이전 시크릿 정의를
myjaeger.yaml
파일에 저장한 경우 다음 명령을 실행합니다.$ oc create -f myjaeger.yaml
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 ...
OpenTracing을 구성하는
APIcast
사용자 정의 리소스를 만듭니다. 예를 들어APIcast
사용자 정의 리소스를apicast1.yaml
파일에 저장한 경우 다음 명령을 실행합니다.$ oc apply -f apicast1.yaml
다음 단계
OpenTracing이 설치된 방법에 따라 Jaeger 서비스 사용자 인터페이스에 추적이 표시되어야 합니다.
추가 리소스