Menu Close

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

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

사전 요구 사항

절차

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

3.6.1. APIcast 배포 및 구성 옵션

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

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

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

절차

  1. 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

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

  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 배포의 readyReplicas 필드가 1 인지 확인하여 APIcast Pod가 실행 중이고 준비되었는지 확인합니다. 또는 다음을 사용하여 필드가 설정될 때까지 기다립니다.

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

절차

  1. OpenShift Service 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"
3.6.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를 구성할 수도 있습니다. 다음 표에서 사용 가능한 필드에 대한 세부 정보:

표 3.3. APIcastExposedHost 참조 테이블

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

host

string

있음

해당 없음

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

tls

[]extensions.IngressTLS

없음

해당 없음

ingress TLS 오브젝트의 배열입니다. TLS에서 자세한 내용을 참조하십시오.

3.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 배포의 readyReplicas 필드가 1 인지 확인하여 APIcast Pod가 실행 중이고 준비되었는지 확인합니다. 또는 다음을 사용하여 필드가 설정될 때까지 기다립니다.

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

절차

  1. OpenShift Service 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"

3.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

다음 단계

사용자 지정 환경을 정의하는 보안의 콘텐츠를 업데이트할 수 없습니다. 사용자 지정 환경을 업데이트해야 하는 경우 사용자 지정 환경을 정의하는 Lua 파일을 업데이트한 다음 다음 중 하나를 수행합니다.

  • 권장되는 옵션은 다른 이름으로 시크릿을 생성한 다음 업데이트된 사용자 지정 환경에 대해 APIcast 사용자 정의 리소스 필드인 spec.customEnvironments[].secretRef.name 을 업데이트하는 것입니다. Operator는 롤링 업데이트를 트리거하고 업데이트된 사용자 지정 환경을 로드합니다.
  • 또는 spec.replicas 를 0으로 설정한 다음 spec.replicas 를 이전 값으로 다시 설정하여 기존 보안을 업데이트하여 APIcast를 재배포할 수 있습니다.

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

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

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

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

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

사전 요구 사항

절차

  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 사용자 정의 리소스 필드인 spec.customPolicies[].secretRef.name 을 업데이트하는 것입니다. Operator는 롤링 업데이트를 트리거하고 업데이트된 사용자 지정 정책을 로드합니다.
  • 또는 spec.replicas 를 0으로 설정한 다음 spec.replicas 를 이전 값으로 다시 설정하여 기존 보안을 업데이트하여 APIcast를 재배포할 수 있습니다.

3.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 서비스 사용자 인터페이스에 추적이 표시되어야 합니다.