3.7. operator を使用した Self-managed APIcast ゲートウェイソリューションのデプロイ


本セクションでは、Openshift Container Platform コンソールから APIcast operator を使用して Self-managed APIcast ゲートウェイソリューションをデプロイする手順について説明します。

前提条件

手順

  1. 管理者権限を持つアカウントを使用して OCP コンソールにログインします。
  2. Operators > Installed Operators の順にクリックします。
  3. Installed Operators のリストで APIcast Operator をクリックします。
  4. APIcast > Create APIcast の順にクリックします。

3.7.1. APIcast のデプロイメントおよび設定オプション

Self-managed APIcast ゲートウェイソリューションは、以下に示す 2 とおりの方法を使用してデプロイおよび設定することができます。

以下も参照してください。

3.7.1.1. 3scale システムエンドポイントの指定

手順

  1. 3scale システム管理ポータルのエンドポイント情報が含まれる 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

      シークレットの内容についての詳細は、APIcast Custom Resource reference のEmbeddedConfSecret を参照してください。

  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.7.1.1.1. APIcast ゲートウェイが動作中で利用可能であることの確認

手順

  1. ローカルマシンから OpenShift Service APIcast にアクセス可能であることを確認し、テストリクエストを実行します。そのために、APIcast OpenShift Service を 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.7.1.1.2. Kubernetes Ingress 経由での APIcast の外部公開

Kubernetes Ingress 経由で APIcast を外部に公開するには、exposedHost セクションを設定します。ExposedHost セクションの host フィールドを設定すると、Kubernetes Ingress オブジェクトが作成されます。事前にインストールした既存の Kubernetes Ingress Controller はこの Kubernetes Ingress オブジェクトを使用し、APIcast を外部からアクセス可能にします。

APIcast を外部からアクセス可能にするのに使用できる Ingress Controllers およびその設定方法について詳しく知るには、Kubernetes Ingress Controllers のドキュメント を参照してください。

ホスト名 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 Controller は APIcast が作成する Ingress オブジェクト使用して Route オブジェクトを作成し、APIcast インストールへの外部アクセスが可能になります。

exposedHost セクションに TLS を設定することもできます。利用可能なフィールドの詳細を以下の表に示します。

表3.3 APIcastExposedHost の参照テーブル
json/yaml フィールドタイプ必須/任意デフォルト値説明

host

string

はい

該当なし

ゲートウェイにルーティングされているドメイン名

tls

[]extensions.IngressTLS

いいえ

該当なし

受信 TLS オブジェクトの配列。詳細は、TLS を参照してください。

3.7.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 の要件です。

    シークレットの内容についての詳細は、APIcast Custom Resource reference のEmbeddedConfSecret を参照してください。

  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.7.1.2.1. APIcast ゲートウェイが動作中で利用可能であることの確認

手順

  1. ローカルマシンから OpenShift Service APIcast にアクセス可能であることを確認し、テストリクエストを実行します。そのために、APIcast OpenShift Service を 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.7.1.3. APIcast Operator を使用したカスタム環境の注入

Self-managed APIcast を使用する 3scale インストールでは、3scale Operator を使用してカスタム環境を注入できます。カスタム環境は、ゲートウェイが提供するすべてのアップストリーム API に APIcast が適用する動作を定義します。カスタム環境を作成するには、Lua コードでグローバル設定を定義します。

APIcast のインストールの一部として、またはインストール後にカスタム環境を注入できます。カスタム環境を注入した後、その環境を削除すると、APIcast Operator が変更を調整します。

前提条件

  • APIcast Operator がインストールされている。

手順

  1. 注入するカスタム環境を定義する Lua コードを記述します。たとえば、次の env1.lua ファイルは、APIcast Operator がすべてのサービスに対してロードするカスタムログポリシーを示しています。

    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 に設定して APIcast を再デプロイしてから、spec.replicas を以前の値に戻して APIcast を再デプロイすることもできます。

3.7.1.4. APIcast オペレーターを使用したカスタムポリシーの注入

Self-managed APIcast を使用する 3scale インストールでは、APIcast operator を使用してカスタムポリシーを注入できます。カスタムポリシーを注入すると、ポリシーコードが APIcast に追加されます。次に、以下のいずれかを使用して、カスタムポリシーを API 製品のポリシーチェーンに追加できます。

  • 3scale API
  • Product カスタムリソース

3scale 管理ポータルを使用してカスタムポリシーを製品のポリシーチェーンに追加するには、カスタムポリシーのスキーマを CustomPolicyDefinition カスタムリソースに登録する必要もあります。カスタムポリシー登録は、管理ポータルを使用して製品のポリシーチェーンを設定する場合にのみ必要です。

APIcast のインストールの一部として、またはインストール後にカスタムポリシーを注入できます。カスタムポリシーを注入した後、それを削除すると、APIcast operator が変更を調整します。

前提条件

  • APIcast operator がインストールされているか、インストール中である。
  • Write your own policy で説明されているように、カスタムポリシーを定義している。つまり、たとえば、カスタムポリシーを定義するmy-first-custom-policy.luaapicast-policy.json、およびinit.luaファイルをすでに作成している。

手順

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

    複数のカスタムポリシーがある場合は、カスタムポリシーごとにシークレットを作成します。シークレットには、カスタムポリシーを 1 つだけ含めることができます。

  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 に設定して APIcast を再デプロイしてから、spec.replicas を以前の値に戻して APIcast を再デプロイすることもできます。

3.7.1.5. APIcast operator を使用した OpenTracing の設定

Self-managed 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 サービスユーザーインターフェイスでトレースが表示されるはずです。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.