パフォーマンスのスケールアップは、Pod の合計数に応じて行われます。ハードウェアリソースが多いほど、デプロイする Pod 数が増えます。

以下のコマンドを使用して、Pod の数によりパフォーマンスのスケールアップを行います。

oc scale dc dc-name --replicas=X

3scale でスケーリングされる主要なデプロイメント設定項目は以下のとおりです。

この設定により、すべてのログが 1 箇所に集約され、Elasticsearch、Fluentd、および Kibana (EFK) ロギングツールでクエリーすることができます。これらのツールにより、3scale の設定にいつ誰がどのような変更を加えたかについての可視性が向上します。たとえば、これには、請求、アプリケーションプラン、API 設定などへの変更が含まれます。

3scale は、features.yml 設定ファイルを使用して、一部のグローバル機能を有効にします。stdout への監査ログの送付を有効化するには、このファイルを ConfigMap からマウントして、デフォルトのファイルと置き換える必要があります。features.yml に依存する OpenShift Pod は、system-app および system-sidekiq です。

stdout への監査ログの送付を有効にして 3scale アプリケーションログが OpenShift に転送されるようになったら、EFK ロギングツールを使用して 3scale アプリケーションを監視することができます。

OpenShift での EFK ロギングの設定方法については、以下のドキュメントを参照してください。

各コンポーネントのデプロイメント設定には、アクセスと例外のログが含まれます。デプロイメントで問題が発生した場合には、これらのログで詳細を確認してください。

3scale のログにアクセスするには、以下の手順に従います。

ジョブキューには、system-sidekiq Pod から送られる情報のログが含まれます。これらのログを使用して、クラスターがデータを処理しているかどうかを確認します。OpenShift CLI を使用してログを照会することができます。

oc get jobs

oc logs <job>

単調増加を防止するために、3scale はデフォルトで以下のテーブルの自動パージをスケジュールします。

以下の表は例外で、データベース管理者が手動でパージする必要があります。

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL 14 DAY;

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL '14 day';

DELETE FROM alerts WHERE timestamp <= TRUNC(SYSDATE) - 14;

本セクションで説明しない他のテーブルについては、データベース管理者は、システムで自動的にパージされないテーブルを手動でクリーンアップする必要があります。

本セクションでは、toolbox コンテナーイメージをインストールする方法について説明します。

以下のコマンド例により、短縮名 <name> のリモート 3scale インスタンスが <url> に追加されます。

3scale remote add [--config-file <config_file>] <name> <url>

$ podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale remote add instance_a https://123456789@example_a.net

$ podman commit toolbox-container toolbox

上記の例では、リモートインスタンスを作成し、コンテナーをコミットして新しいイメージを作成します。次に、含まれるリモート情報を使用して新しいイメージを実行することができます。たとえば、以下のコマンドでは、新しいイメージを使用して新たに追加されたリモートを表示します。

$ podman run toolbox 3scale remote list
instance_a https://example_a.net 123456789

続いて、他の toolbox コマンドは、新たに作成されたイメージを使用して、追加されたリモートにアクセスすることができます。以下の例では、registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 ではなく toolbox という名前のイメージが使用されています。

以下のコマンド例は、リモートアクセスクレデンシャルを一覧表示する方法を示しています。

3scale remote list [--config-file <config_file>]

このコマンドにより、追加されたリモート 3scale インスタンスのリストが <name> <URL> <authentication-key> のフォーマットで表示されます。

$ podman run <toolbox_image_with_remotes_added> 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321

以下のコマンド例は、リモートアクセスクレデンシャルを削除する方法を示しています。

3scale remote remove [--config-file <config_file>] <name>

このコマンドにより、短縮名 <name> のリモート 3scale インスタンスが削除されます。

$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a

以下のコマンド例は、リモートアクセスクレデンシャルの名前を変更する方法を示しています。

3scale remote rename [--config-file <config_file>] <old_name> <new_name>

このコマンドにより、短縮名 <old_name> のリモート 3scale インスタンスの名前が <new_name> に変更されます。

$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b

新しいアプリケーションプランを作成するには、以下の手順に従います。

以下のコマンドにより、新しいアプリケーションプランが作成されます。

3scale application-plan create [opts] <remote> <service> <plan-name>

アプリケーションプランの作成時に、以下のオプションを使用します。

Options
       --approval-required=<value>    The application requires approval:
                                      true or false
       --cost-per-month=<value>       Cost per month
       --default                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --published                    Publish the application plan
       --setup-fee=<value>            Set-up fee
    -t --system-name=<value>          Set application plan system name
       --trial-period-days=<value>    The trial period in days

Options for application-plan
    -c --config-file=<value>          3scale toolbox configuration file:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode

アプリケーションプランが存在しない場合に新しく作成する、または既存のアプリケーションプランを更新するには、以下の手順に従います。

以下のコマンドにより、アプリケーションプランが更新されます。

3scale application-plan create [opts] <remote> <service> <plan>

アプリケーションプランの更新時に、以下のオプションを使用します。

Options
       --approval-required=<value>    The application requires approval:
                                      true or false
       --cost-per-month=<value>       Cost per month
       --default                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
       --enabled                      Enable the application plan
       --hide                         Hide the application plan
    -n --name=<value>                 Set the plan name
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --publish                      Publish the application plan
       --setup-fee=<value>            Set-up fee
       --trial-period-days=<value>    The trial period in days

Options for application-plan
    -c --config-file=<value>          3scale toolbox configuration file:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode

以下のコマンドにより、アプリケーションプランが一覧表示されます。

3scale application-plan list [opts] <remote> <service>

アプリケーションプランの一覧表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、アプリケーションプランが表示されます。

3scale application-plan show [opts] <remote> <service> <plan>

アプリケーションプランの表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、アプリケーションプランが削除されます。

3scale application-plan delete [opts] <remote> <service> <plan>

アプリケーションプランの削除時に、以下のオプションを使用します。

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

単一のアプリケーションプランを yaml コンテンツにエクスポートすることや、コンテンツからインポートすることができます。

次の点に注意してください。

3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>

$ podman run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name

Options
    -f --file=<value>             Write to file instead of stdout

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3scale application-plan import [opts] <remote> <service_system_name>

$ podman run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name

3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name

Options
    -f --file=<value>                  Read from file or URL instead of
                                       stdin
    -p --plan=<value>                  Override application plan reference

Options for application-plan
    -c --config-file=<value>           3scale toolbox configuration file:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode

メトリクスが存在しない場合に新しく作成する、または既存のメトリクスを更新するには、以下の手順に従います。

以下のコマンドにより、メトリクスが更新されます。

3scale metric apply [opts] <remote> <service> <metric>

メトリクスの更新時に、以下のオプションを使用します。

Options
       --description=<value>      Set a metric description
       --disabled                 Disable this metric in all application
                                  plans
       --enabled                  Enable this metric in all application
                                  plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、メトリクスが一覧表示されます。

3scale metric list [opts] <remote> <service>

メトリクスの一覧表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、メトリクスが削除されます。

3scale metric delete [opts] <remote> <service> <metric>

メトリクスの削除時に、以下のオプションを使用します。

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

メソッドを作成するには、以下の手順に従います。

以下のコマンドにより、メソッドが作成されます。

3scale method create [opts] <remote> <service> <method-name>

メソッドの作成時に、以下のオプションを使用します。

Options
       --description=<value>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -t --system-name=<value>      Set the method system name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

メソッドが存在しない場合に新しく作成する、または既存のメソッドを更新するには、以下の手順に従います。

以下のコマンドにより、メソッドが更新されます。

3scale method apply [opts] <remote> <service> <method>

メソッドの更新時に、以下のオプションを使用します。

Options
       --description=<value>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
       --enabled                  Enable this method in all
                                  application plans
    -n --name=<value>             Set the method name
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、メソッドが一覧表示されます。

3scale method list [opts] <remote> <service>

メソッドの一覧表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、メソッドが削除されます。

3scale method delete [opts] <remote> <service> <metric>

メソッドの削除時に、以下のオプションを使用します。

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、新しいサービスが作成されます。

3scale service create [options] <remote> <service-name>

サービスの作成時に、以下のオプションを使用します。

Options
    -a --authentication-mode=<value>     Specify authentication mode of
                                         the service:
                                          - '1' for API key
                                          - '2' for App Id/App Key
                                          - 'oauth' for OAuth mode
                                          - 'oidc' for OpenID Connect
    -d --deployment-mode=<value>         Specify the deployment mode of
                                         the service
       --description=<value>             Specify the description of the
                                         service
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml
    -s --system-name=<value>             Specify the system-name of the
                                         service
       --support-email=<value>           Specify the support email of the
                                         service

Options for service
    -c --config-file=<value>             3scale toolbox configuration file:
                                         defaults to $HOME/.3scalerc.yaml
    -h --help                            Print help for this command
    -k --insecure                        Proceed and operate even for
                                         server connections otherwise
                                         considered insecure
    -v --version                         Print the version of this command
       --verbose                         Verbose mode

サービスが存在しない場合に新しく作成する、または既存のサービスを更新するには、以下の手順に従います。

以下のコマンドにより、サービスが更新されます。

3scale service apply <remote> <service-id_or_system-name>

サービスの更新時に、以下のオプションを使用します。

Options
    -a --authentication-mode=<value>     Specify authentication mode of
                                         the service:
                                           - '1' for API key
                                           - '2' for App Id/App Key
                                           - 'oauth' for OAuth mode
                                           - 'oidc' for OpenID Connect
    -d --deployment-mode=<value>         Specify the deployment mode of
                                         the service
       --description=<value>             Specify the description of the
                                         service
    -n --name=<value>                    Specify the name of the metric
       --support-email=<value>           Specify the support email of the
                                         service
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml

Options for services
    -c --config-file=<value>             3scale toolbox configuration file:
                                         defaults to $HOME/.3scalerc.yaml
    -h --help                            Print help for this command
    -k --insecure                        Proceed and operate even for
                                         server connections otherwise
                                         considered insecure
    -v --version                         Print the version of this command
       --verbose                         Verbose mode

以下のコマンドにより、サービスが一覧表示されます。

3scale service list <remote>

サービスの一覧表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、サービスが表示されます。

3scale service show <remote> <service-id_or_system-name>

サービスの表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、サービスが削除されます。

3scale service delete <remote> <service-id_or_system-name>

サービスの削除時に、以下のオプションを使用します。

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

OpenAPI 使用に準拠した API 定義から新しい ActiveDocs を作成するには、以下の手順を実施します。

ActiveDoc が存在しない場合に新しく作成する、または新しい API 定義で既存の ActiveDocs を更新するには、以下のコマンドを使用します。

3scale activedocs apply <remote> <activedocs_id_or_system_name>

ActiveDocs の更新時に、以下のオプションを使用します。

Options
  -d --description=<value>              Specify the description of the
                                        ActiveDocs
       --hide                           Specify to hide the ActiveDocs
                                        on the Developer Portal
 -i --service-id=<value>                Specify the Service ID associated
                                        to the ActiveDocs
 -o --output=<value>                    Output format on stdout:
                                        one of json|yaml
    --openapi-spec=<value>              Specify the Swagger specification.
                                        Can be a file, a URL or '-' to read
                                        from stdin. This is a mandatory
                                        option when applying the ActiveDoc
                                        for the first time.
 -p --publish                           Specify to publish the ActiveDocs
                                        on the Developer Portal. Otherwise
                                        it is hidden
 -s --name=<value>                      Specify the name of the ActiveDocs
    --skip-swagger-validations=<value>  Specify whether to skip validation
                                        of the Swagger specification: true
                                        or false. Defaults to true.

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode

以下の項目を含め、デベロッパーポータルのすべての ActiveDocs に関する情報を取得するには、以下のコマンドを使用します。

以下のコマンドにより、定義済みの ActiveDocs がすべて一覧表示されます。

3scale activedocs list <remote>

ActiveDocs の一覧表示時に、以下のオプションを使用します。

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -s --service-ref=<value>      Filter the ActiveDocs by service
                                  reference
Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、ActiveDocs が削除されます。

3scale activedocs delete <remote> <activedocs-id_or-system-name>

ActiveDocs の削除時に、以下のオプションを使用します。

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、プロキシー設定が表示されます。

3scale proxy-config show <remote> <service> <environment>

プロキシー設定の表示時に、以下のオプションを使用します。

Options
       --config-version=<value>   Specify the proxy configuration version.
                                  If not specified, defaults to latest
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered
                                  insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、最新のステージング環境用プロキシー設定が実稼働環境にプロモートされます。

3scale proxy-config promote <remote> <service>

最新のステージング環境用プロキシー設定を実稼働環境にプロモートする際に、以下のオプションを使用します。

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

Self-managed APIcast ゲートウェイが 3scale インスタンスに接続されていない場合などに、proxy-config export コマンドを使用します。このシナリオでは、3scale 設定を手動で注入するか、APICast デプロイメントおよび設定オプション を使用して注入します。いずれの場合も、3scale の設定を指定する必要があります。

以下のコマンドは、APIcast ゲートウェイに注入することのできる設定をエクスポートします。

3scale proxy-config export <remote>

3scale 設定ファイル として使用されるプロバイダーアカウントのプロキシー設定をエクスポートする際に、以下のオプションを指定することができます。

Options for proxy-config
--environment=<value>      Gateway environment. Must be 'sandbox' or
                           'production' (default: sandbox)
-o --output=<value>        Output format. One of: json|yaml

以下の deploy コマンドは、サービスメッシュを使用している場合に、APIcast 設定を 3scale のステージング環境または実稼働環境にプロモートします。

3scale proxy-config deploy <remote> <service>

deploy コマンドを使用して APIcast 設定をステージング環境にプロモートする時に、以下のオプションを指定できます。

-o --output=<value>        Output format. One of: json|yaml

特定の 3scale アカウントおよびアプリケーションプランにリンクされたアプリケーションを 1 つ作成するには、create コマンドを使用します。

以下のコマンドにより、アプリケーションが作成されます。

3scale application create [opts] <remote> <account> <service> <application-plan> <name>

アプリケーションの作成時に、以下のオプションを使用します。

OPTIONS
       --application-id=<value>     App ID or Client ID (for OAuth and
                                    OpenID Connect authentication modes)
                                    of the application to be created.
       --application-key=<value>    App Key(s) or Client Secret (for OAuth
                                    and OpenID Connect authentication
                                    modes) of the application created.
       --description=<value>        Application description
    -o --output=<value>             Output format on stdout:
                                    one of json|yaml
       --redirect-url=<value>       OpenID Connect redirect url
       --user-key=<value>           User Key (API Key) of the application
                                    to be created.

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

以下のコマンドにより、アプリケーションが表示されます。

3scale application show [opts] <remote> <application>

OPTIONS
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

アプリケーションが存在しない場合に新しく作成する、または既存のアプリケーションを更新するには、以下のコマンドを使用します。

3scale application apply [opts] <remote> <application>

アプリケーションの更新時に、以下のオプションを使用します。

OPTIONS
       --account=<value>           Application's account. Required when
                                   creating
       --application-key=<value>   App Key(s) or Client Secret (for OAuth
                                   and OpenID Connect authentication
                                   modes) of the application to be
                                   created. Only used when application
                                   does not exist.
       --description=<value>       Application description
       --name=<value>              Application name
    -o --output=<value>            Output format on stdout:
                                   one of json|yaml
       --plan=<value>              Application's plan. Required when
                                   creating.
       --redirect-url=<value>      OpenID Connect redirect url
       --resume                    Resume a suspended application
       --service=<value>           Application's service. Required when
                                   creating.
       --suspend                   Suspends an application (changes the
                                   state to suspended)
       --user-key=<value>          User Key (API Key) of the application
                                   to be created.

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode.

以下のコマンドにより、アプリケーションが削除されます。

3scale application delete [opts] <remote> <application>

このアプローチでは、API バックエンド環境ごとに個別の 3scale インスタンスがデプロイされます。このアーキテクチャーの利点は、各環境が互いに分離されるため、共有するデータベースやその他のリソースがないことです。たとえば、ある環境で行われる負荷テストは、他の環境のリソースには影響しません。

この方法では、単一の 3scale インスタンスが使用されますが、マルチテナンシー機能は複数の API バックエンドをサポートするために使用されます。

APIcast 組み込みゲートウェイを使用する場合、3scale と APIcast ゲートウェイの組み合わせ で説明されている上記のアプローチを使用して設定された API バックエンドは自動的に処理されます。3scale マスター管理によりテナントが追加されると、実稼働環境およびステージングの組み込み APIcast ゲートウェイでテナントのルートが作成されます。マルチテナント対応サブドメインについて を参照してください。

したがって、異なるテナントにマッピングされた各 API バックエンド環境は、独自のルートを取得します。以下に例を示します。

追加の APIcast ゲートウェイは、3scale インスタンスが実行されているものとは 異なる OpenShift クラスター にデプロイされたものです。追加の APIcast ゲートウェイを設定して使用する方法は複数あります。APIcast の起動時に使用される環境変数の値 THREESCALE_PORTAL_ENDPOINT は、追加の APIcast ゲートウェイの設定方法によって異なります。

API バックエンド環境ごとに個別の APIcast ゲートウェイを使用することができます。以下に例を示します。

DEV_APICAST -> DEV_TENANT ; DEV_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for DEV_TENANT
QA_APICAST -> QA_TENANT ; QA_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for QA_APICAST
PROD_APICAST -> PROD_TENANT ; PROD_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for PROD_APICAST

THREESCALE_PORTAL_ENDPOINT は、設定をダウンロードするために APIcast によって使用されます。API バックエンド環境にマッピングする各テナントは、個別の APIcast ゲートウェイを使用します。THREESCALE_PORTAL_ENDPOINT は、その API バックエンド環境に固有のすべてのプロダクト設定が含まれるテナントの管理ポータルに設定されます。

単一の APIcast ゲートウェイは、複数の API バックエンド環境と共に使用することができます。この場合、THREESCALE_PORTAL_ENDPOINT は マスター管理ポータル に設定されます。

API プロバイダーサイクルのステージは、API の詳細規定、開発、およびデプロイをベースとしています。以下に、各ステージの目的と成果を説明します。

API 利用者サイクルのステージは、API を利用するためのプロモーション、配布、および調整をベースとしています。以下に、各ステージの目的と成果を説明します。

API ライフサイクルの自動化用に Jenkins パイプラインを作成してデプロイする方法の例として、以下のサンプルが Red Hat Integration リポジトリーで提供されています。

これらのサンプルは、3scale toolbox を呼び出す 3scale Jenkins 共有ライブラリーを使用して、主要な API 管理機能を実証します。本トピックの設定手順を実施したら、各 Red Hat Integration リポジトリーのユースケース例 で提供される OpenShift テンプレートを使用してパイプラインをインストールすることができます。

ホスト型 3scale 環境の設定は、すべてのサンプル Jenkins CI/CD パイプラインで必要です。

オンプレミス型 3scale 環境の設定は、Hybrid - open と Hybrid - OIDC のサンプル Jenkins CI/CD パイプラインでのみ必要です。

Hybrid - OpenID Connect (OIDC) または Semantic versioning のサンプルパイプラインを使用している場合、本セクションの手順を実施して 3scale で Red Hat Single Sign-On (RH-SSO) をデプロイします。これは OIDC 認証に必要であり、両方のサンプルで使用されます。

本セクションでは、toolbox のインストール、リモート 3scale インスタンスの作成、および管理ポータルへのアクセスに使用されるシークレットのプロビジョニングを行う方法について説明します。

本セクションでは、サンプルパイプラインで提供される API バックエンドの例をデプロイする方法について説明します。独自のパイプラインを作成してデプロイする場合、必要に応じて独自の API バックエンドを代わりに使用できます。

本セクションは、ホスト型 3scale 環境で Self-managed APIcast インスタンスで使用するためのものです。本セクションの説明は、SaaS - API key 以外のすべてのサンプルパイプラインに該当します。

必要な環境を設定したら、各 Red Hat Integration リポジトリーのサンプルユースケース 用に提供される OpenShift テンプレートを使用して、サンプルパイプラインをインストールしてデプロイすることができます。本セクションでは、SaaS - API Key のサンプルについてのみ説明します。

本リリースでは、以下の制約が適用されます。

3scale バックエンド および プロダクト を作成できるように、OpenAPI カスタムリソース (CR) をデプロイします。

OpenAPI カスタムリソース定義 (CRD) のデプロイメント機能に関する知識は、3scale プロダクトの設定、バックエンド、およびその後の開発者ポータル用の ActiveDocs の作成に役立ちます。

インポートルールは、3scale デプロイメントの OpenAPI ドキュメントを設定する際に、OpenAPI Specification(OAS) が 3scale とどのように機能するかを指定します。

OpenAPI ドキュメントでは、paths オブジェクトは動詞およびパターンプロパティーのマッピングルールを提供します。3scale メソッドは operationId に応じて関連付けられます。

delta の値は 1 にハードコーディングされます。

デフォルトでは、Strict マッチング ポリシーが設定されます。マッチングポリシーは、OpenAPI CRD の spec.PrefixMatching フィールドを使用して、接頭辞マッチング に切り替えることができます。

サポートされるセキュリティースキームは apiKey です。

apiKey セキュリティースキームタイプ:

以下は、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 ドキュメントがセキュリティー要件を指定しない場合、以下が適用されます。

3scale 認証セキュリティー は、OpenAPI CRD の spec.privateAPIHostHeader フィールドおよび spec.privateAPISecretToken フィールドを使用して設定できます。

カスタム公開ベース 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"

指定した URL から OAS ドキュメントをインポートする OpenAPI カスタムリソースをデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。

3scale バックエンド および プロダクト を作成できるように、ActiveDoc カスタムリソース (CR) をデプロイします。

ActiveDoc カスタムリソース定義 (CRD) は、開発者の OpenAPI ドキュメント形式の製品ドキュメントを考慮します。ActiveDoc CRD デプロイメント機能に関する知識は、デベロッパーポータルの ActiveDocs の作成に役立ちます。

指定した URL から OAS(OpenAPI Specification) ドキュメントをインポートする ActiveDoc カスタムリソース (CR) をデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。

新しく作成したテナントで Openshift Container Platform を使用し、新規バックエンドを設定します。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、バックエンドのカスタムリソースに必要なバックエンドメトリクスを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、バックエンドのカスタムリソースに必要なバックエンドメソッドを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、バックエンドのカスタムリソースに必要なバックエンドマッピングルールを定義します。

以下の点について考慮してください。

status フィールドには、エンドユーザーに役立つリソース情報が表示されます。手動で更新することは意図されず、リソースの変更ごとに同期されます。

status フィールドの属性は以下のとおりです。

同期されたリソースの例:

status:
    backendId: 59978
    conditions:
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Failed
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Invalid
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "True"
      type: Synced
    observedGeneration: 2

3scale operator が新しい 3scale リソースを見つけると、LookupProviderAccount プロセスは、リソースを所有するテナントを識別するために開始されます。

プロセスは、テナントのクレデンシャルソースを確認します。何も見つからない場合は、エラーが発生します。

以下の手順では、プロセスがテナントのクレデンシャルソースを検証する方法を説明します。

新しく作成したテナントで Openshift Container Platform を使用し、新規プロダクトを設定します。

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastHosted: {}

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastSelfManaged:
      stagingPublicBaseURL: "https://staging.api.example.com"
      productionPublicBaseURL: "https://production.api.example.com"

新しく作成した 3scale テナントで Openshift Container Platform を使用し、applicationPlans オブジェクトを使用してプロダクトカスタムリソースに必要なアプリケーションプランを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、applicationPlans.limits リストを使用してプロダクトアプリケーションプランに必要な制限を定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、applicationPlans.pricingRules リストを使用してプロダクトアプリケーションプランに必要な課金ルールを定義します。

以下の点について考慮してください。

任意の OAuth 2.0 フローの認証に OpenID Connect (OIDC) を使用する 3scale プロダクトの Product カスタムリソースをデプロイできます。3scale は、OpenID Connect などのサードパーティーアイデンティティープロバイダー (IdP) と統合して、API リクエストの認証を行います。OpenID Connect についての詳しい情報は、OpenID Connect integration を参照してください。サードパーティーの IdP との統合後、プロダクトカスタムリソースに 2 種類のデータを含めます。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、metrics オブジェクトを使用してプロダクトカスタムリソースに必要なメトリクスを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、methods オブジェクトを使用してプロダクトカスタムリソースに必要なメソッドを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、mappingRules オブジェクトを使用してプロダクトカスタムリソースに必要なマッピングルールを定義します。

以下の点について考慮してください。

新しく作成した 3scale テナントで Openshift Container Platform を使用し、backendUsages オブジェクトを適用して宣言的にプロダクトに追加される必要なバックエンドを定義します。

以下の点について考慮してください。

3scale 管理者は、Product カスタムリソースを設定して、その API プロダクトの公開された API へのリクエストに対するゲートウェイレスポンスを指定できます。CR のデプロイ後に、3scale は指定した応答およびエラーメッセージをゲートウェイが返すようにします。

Product CR の gatewayResponse オブジェクトには、ゲートウェイが返すレスポンスが含まれます。

3scale の管理者は、Product カスタムリソースを設定して、その API プロダクトに適用するポリシーチェーンを指定できます。CR のデプロイ後に、3scale は設定済みのポリシーをプロダクトのアップストリームの公開された API へのリクエストに適用します。

status フィールドには、エンドユーザーに役立つリソース情報が表示されます。手動で更新することは意図されず、リソースの変更ごとに同期されます。

status フィールドの属性は以下のとおりです。

同期されたリソースの例:

status:
  conditions:
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Failed
  - lastTransitionTime: "2020-10-21T18:06:54Z"
    status: "False"
    type: Invalid
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Orphan
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "True"
    type: Synced
  observedGeneration: 1
  productId: 2555417872138
  providerAccountHost: https://3scale-admin.example.com
  state: incomplete

3scale operator が新しい 3scale リソースを見つけると、LookupProviderAccount プロセスは、リソースを所有するテナントを識別するために開始されます。

プロセスは、テナントのクレデンシャルソースを確認します。何も見つからない場合は、エラーが発生します。

以下の手順では、プロセスがテナントのクレデンシャルソースを検証する方法を説明します。

3scale operator を使用して 3scale をインストールする場合は、DeveloperAccount および DeveloperUser カスタムリソース (CR) をデプロイできます。これらの CR により、開発者ポータルで 3scale が管理する API に開発者がアクセスするためのアカウントを作成および更新できます。

新規の DeveloperAccount CR をデプロイするには、admin ロールを持つユーザーの DeveloperUser CR もデプロイする必要があります。ここで提供される手順は、新規 DeveloperAccount CR をデプロイするためのものです。DeveloperAccount CR のデプロイ後、更新または削除する手順は他の CR と同じです。

CR は 3scale Operator が含まれる namespace にのみデプロイできます。

oc wait --for=condition=Ready --timeout=30s developeraccount/developeraccount1

失敗した場合、カスタムリソースの status フィールドは、エラーが一時的または永続的であるかどうかを示し、問題の修正に役立つエラーメッセージを提供します。

新しい開発者ユーザーに、開発者ポータルにログインできることを通知します。また、ログインクレデンシャルを伝える必要がある場合もあります。

他のカスタムリソースを更新または削除するのと同じ様に、デプロイされた DeveloperAccount カスタムリソースを更新または削除することができます。ただし、DeveloperAccount CR を削除すると、3scale operator は実際には削除しません。削除した DeveloperAccount CR と同じ名前の新しい DeveloperAccount CR をデプロイしようとすると、その名前の DeveloperAccount CR がすでに存在することを示すメッセージを受信します。新規の DeveloperAccount CR に異なる名前を指定する必要があります。

3scale operator を使用して 3scale をインストールする場合、Developer Portal で 3scale 管理の API への開発者アクセスを管理するために、DeveloperUser カスタムリソース (CR) をデプロイできます。ここで提供される手順は、新規 DeveloperUser CR をデプロイするためのものです。DeveloperUser CR のデプロイ後、更新または削除する手順は他の CR と同じです。

CR は 3scale Operator が含まれる namespace にのみデプロイできます。

oc wait --for=condition=Ready --timeout=30s developeruser/developeruser02

失敗した場合、カスタムリソースの status フィールドは、エラーが一時的または永続的であるかどうかを示し、問題の修正に役立つエラーメッセージを提供します。

新しい開発者ユーザーに、開発者ポータルにログインできることを通知します。また、ログインクレデンシャルを伝える必要がある場合もあります。

他のカスタムリソースを更新または削除するのと同じ様に、デプロイされた DeveloperUser カスタムリソースを更新または削除することができます。ただし、DeveloperUser CR を削除すると、3scale operator は実際には削除しません。削除した DeveloperUser CR と同じアカウント名、ユーザー名、または電子メールの新しい DeveloperUser CR をデプロイしようとすると、DeveloperUser CR がすでに存在することを示すメッセージを受信します。新規の DeveloperUser CR には、別の開発者ユーザーアカウント名、ユーザー名、または電子メールを指定する必要があります。

system-mysql はリレーショナルデータベースで、3scale 管理コンソールのユーザー、アカウント、API、プランなどについての情報を保存します。

サービスに関連するこの情報のサブセットは、Backend コンポーネントと同期され、backend-redis に保存されます。system-mysql は、この情報の 信頼できるソース です。

system-storage は、システム コンポーネントにより読み取り/書き込みされるファイルを保存します。

これは 2 つのカテゴリーに分類されます。

backend-redis には、バックエンド コンポーネントにより使用される複数のデータセットが含まれます。

system-redis には、バックグラウンドで処理されるジョブのキューが含まれます。これらは一時的なものであり、処理後に削除されます。

MySQL バックアップコマンドを実行します。

oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'export MYSQL_PWD=${MYSQL_ROOT_PASSWORD}; mysqldump --single-transaction -hsystem-mysql -uroot system' | gzip > system-mysql-backup.gz

system-storage ファイルを別のストレージにアーカイブします。

oc rsync $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system ./local/dir

redis からの dump.rdb ファイルをバックアップします。

oc cp $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./backend-redis-dump.rdb

redis からの dump.rdb ファイルをバックアップします。

oc cp $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./system-redis-dump.rdb

zync_production データベースをバックアップします。

oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'pg_dump zync_production' | gzip > zync-database-backup.gz

OpenShift シークレットおよび ConfigMap のコマンドリストを以下に示します。

oc get secrets system-smtp -o json > system-smtp.json
oc get secrets system-seed -o json > system-seed.json
oc get secrets system-database -o json > system-database.json
oc get secrets backend-internal-api -o json > backend-internal-api.json
oc get secrets system-events-hook -o json > system-events-hook.json
oc get secrets system-app -o json > system-app.json
oc get secrets system-recaptcha -o json > system-recaptcha.json
oc get secrets system-redis -o json > system-redis.json
oc get secrets zync -o json > zync.json
oc get secrets system-master-apicast -o json > system-master-apicast.json

oc get configmaps system-environment -o json > system-environment.json
oc get configmaps apicast-environment -o json > apicast-environment.json

テンプレートベースのデプロイメントを復元するには、以下の手順に従います。

oc apply -f system-smtp.json

operator ベースのデプロイメントを復元するには、以下の手順に従います。

バックアップファイルを system-storage に復元します。

oc rsync ./local/dir/system/ $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system

zync-database を復元する手順は、3scale に適用したデプロイメントタイプによって異なります。

backend-redis の復元後、System からの設定情報と同期させ、Backend の情報と信頼できるソース である System の情報の一貫性を確保する必要があります。

最新バージョンの backend-worker に復元します。

oc rollout latest dc/backend-worker

最新バージョンの system-app に復元します。

oc rollout latest dc/system-app

バックアップが可能な 3scale インストール設定については、以下のセクションを参照してください。

バックアップ機能は、以下のデータベースが外部で設定されている場合に利用できます。

以下の表は、バックアップされるデータの一覧を示しています。

既存の APIManager を使用してデプロイされた 3scale インストールのバックアップを作成するには、以下の手順に従います。

バックアップの内容の詳細は、バックアップされるデータ を参照してください。

APIManagerBackup のステータスセクションのその他のフィールドは、設定されたバックアップ先が PVC の場合にデータがバックアップされている PVC の名前など、バックアップの詳細が表示されます。

後で参照するために、status.backupPersistentVolumeClaimName フィールドの値を書き留めておきます。APIManagerRestore で APIManager インストールを復元する場合、必要なフィールドの 1 つは PersistentVolumeClaimName バックアップソースです。

復元が可能な 3scale インストール設定については、以下のセクションを参照してください。

3scale operator の復元機能は、APIManagerBackup カスタムリソースから生成されたバックアップを使用して利用できます。

バックアップ可能な 3scale ソリューションのシナリオのリストは、バックアップされるデータ を参照してください。

以下は、operator の復元機能のスコープではありません。

以下の表は、復元されるデータの一覧を示しています。

APIManager によってデプロイされ APIManagerBackup カスタムリソースによりバックアップを行っている 3scale インストールを復元するには、以下の手順に従います。

以降のセクションで、3scale とのインテグレーションにおける初期段階 (Hosted APIcast 使用の初期段階および実稼働環境への移行前、ならびに Self-managed APIcast の稼働中) で、APIcast エラーログでよく見られる問題のいくつかについて概要を説明します。

セットアップを完全にテストし、しばらくの間実際に API を運用した後に、API ゲートウェイに関連して問題が発生することはほとんどありません。ただし、実際の実稼働環境で発生しうる問題の一部をここに挙げます。

upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"

新しいエンドポイントを追加するなど、API に変更を加える場合、API ゲートウェイの新しい設定ファイルのセットをダウンロードする前に、必ず新しいメソッドおよび URL マッピングを追加する必要があります。

3scale からダウンロードした設定を変更した場合の最も典型的な問題は、Lua のコードエラーです。これにより、以下のような 500 - Internal server error が発生します。

curl -v -X GET "http://localhost/"
* About to connect() to localhost port 80 (#0)
*   Trying 127.0.0.1... connected
> GET / HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: localhost
> Accept: */*
>
< HTTP/1.1 500 Internal Server Error
< Server: openresty/1.5.12.1
< Date: Thu, 04 Feb 2016 10:22:25 GMT
< Content-Type: text/html
< Content-Length: 199
< Connection: close
<

<head><title>500 Internal Server Error</title></head>

<center><h1>500 Internal Server Error</h1></center>
<hr><center>openresty/1.5.12.1</center>


* Closing connection #0

nginx error.log を見て、原因を確認することができます。以下に例を示します。

2016/02/04 11:22:25 [error] 8980#0: *1 lua entry thread aborted: runtime error: /home/pili/NGINX/troubleshooting/nginx.lua:66: bad argument #3 to '_newindex' (number expected, got nil)
stack traceback:
coroutine 0:
  [C]: in function '_newindex'
  /home/pili/NGINX/troubleshooting/nginx.lua:66: in function 'error_authorization_failed'
  /home/pili/NGINX/troubleshooting/nginx.lua:330: in function 'authrep'
  /home/pili/NGINX/troubleshooting/nginx.lua:283: in function 'authorize'
  /home/pili/NGINX/troubleshooting/nginx.lua:392: in function  while sending to client, client: 127.0.0.1, server: api-2445581381726.staging.apicast.io, request: "GET / HTTP/1.1", host: "localhost"

access.log では、以下のようになります。

127.0.0.1 - - [04/Feb/2016:11:22:25 +0100] "GET / HTTP/1.1" 500 199 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"

上記のセクションでは、3scale 運用のいずれかのステージで発生する可能性のある最も典型的でよく知られた問題の概要を示します。

これらをすべて確認してもなお問題の原因と解決策が見つからない場合は、API へのリクエストに関する問題の特定 で説明する、より詳細なトラブルシューティングに進む必要があります。問題のある箇所の特定を試みるため、API から始めてクライアントまで遡って作業します。

telnet を使用して、基本的な TCP/IP 接続 (telnet api.example.com 443) を確認します。

telnet echo-api.3scale.net 80
Trying 52.21.167.109...
Connected to tf-lb-i2t5pgt2cfdnbdfh2c6qqoartm-829217110.us-east-1.elb.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.

telnet su1.3scale.net 443
Trying 174.129.235.69...
telnet: Unable to connect to remote host: Connection timed out

さまざまなネットワークの場所、デバイス、および宛先から、同じサーバーへの接続を試みます。たとえば、クライアントが API に到達できない場合は、API ゲートウェイなど、アクセスできるはずのマシンから API への接続を試みます。

接続試行のいずれかが成功した場合、実際のサーバーに関する問題を除外して、両者間のネットワークのトラブルシューティングに集中できます。問題がここにある可能性が最も高いからです。

ホスト名の代わりに IP アドレスを使ってサーバーへの接続を試みます。たとえば、telnet apis.io 80 の代わりに telnet 94.125.104.17 80 を使用します。

これにより、DNS に関する問題はすべて排除されます。

3scale の例では、dig su1.3scale.net または dig any su1.3scale.net (ホストが解決する IP が複数あると思われる場合) のように、dig を使用してサーバーの IP アドレスを取得することができます。

注記: 一部のホストは dig any をブロックします

OpenSSL を使用して、以下の項目をテストすることができます。

CONNECTED(00000003)
140735196860496:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:s3_pkt.c:1456:SSL alert number 40
140735196860496:error:1409E0E5:SSL routines:ssl3_write_bytes:ssl handshake failure:s3_pkt.c:644:
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 0 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : SSLv3
    Cipher    : 0000
    Session-ID:
    Session-ID-ctx:
    Master-Key:
    Key-Arg   : None
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    Start Time: 1454932872
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
---

詳細は、OpenSSL の man ページ を参照してください。

API が動作状態にあり、リクエストに応答していることを確認するため、同じリクエストを API に対し直接、API ゲートウェイを経由せずに実行します。API ゲートウェイを経由する場合のリクエストと同じパラメーターおよびヘッダーを送信していることを確認する必要があります。失敗したリクエストが正確にわからない場合は、API ゲートウェイと API 間のトラフィックを取得します。

呼び出しに成功する場合、API に関する問題を除外できますが、失敗した場合には、さらに API のトラブルシューティングを行う必要があります。

API ゲートウェイと API 間のネットワークの問題を除外するには、前と同じ呼び出しを、API に直接、ゲートウェイサーバーから実行します。

呼び出しに成功する場合、API ゲートウェイ自体のトラブルシューティングに進むことができます。

API ゲートウェイが正常に機能していることを確認するためには、多くのステップを順に実施します。

API ゲートウェイが正常に動作していることを確認したら、次のステップは API ゲートウェイと 3scale 間の接続についてのトラブルシューティングです。

2015/11/20 11:33:51 [error] 3578#0: *1 upstream timed out (110: Connection timed out) while connecting to upstream, client: 127.0.0.1, server: , request: "GET /api/activities.json?user_key=USER_KEY HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.186:443/transactions/authrep.xml?provider_key=YOUR_PROVIDER_KEY&service_id=SERVICE_ID&usage[hits]=1&user_key=USER_KEY&log%5Bcode%5D=", host: "localhost"

http {
  lua_shared_dict api_keys 10m;
  server_names_hash_bucket_size 128;
  lua_package_path ";;$prefix/?.lua;";
  init_by_lua 'math.randomseed(ngx.time()) ; cjson = require("cjson")';

  resolver 8.8.8.8 8.8.4.4;

nslookup su1.3scale.net 8.8.8.8
;; connection timed out; no servers could be reached

2016/05/09 14:15:15 [alert] 9391#0: send() failed (1: Operation not permitted) while resolving, resolver: 8.8.8.8:53

body_filter_by_lua_block{
  if ngx.req.get_headers()["X-3scale-debug"] == ngx.var.provider_key then
    local resp = ""
    ngx.ctx.buffered = (ngx.ctx.buffered or "") .. string.sub(ngx.arg[1], 1, 1000)
    if ngx.arg[2] then
      resp = ngx.ctx.buffered
    end

    ngx.log(0, ngx.req.raw_header())
    ngx.log(0, resp)
  end
}

2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:7: GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1
Host: 726e3b99.ngrok.io
User-Agent: curl/7.43.0
Accept: */*
X-Forwarded-Proto: https
X-Forwarded-For: 2.139.235.79

 while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io"
2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:8: <?xml version="1.0" encoding="UTF-8"?><error code="access_token_invalid">access_token "7c6f24f5" is invalid: expired or never defined</error> while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io"

Swagger では、petstore.swagger.io にホスト型の swagger-ui が用意されています。これを使用して、最新バージョンの swagger-ui により Swagger 仕様と API をテストすることができます。swagger-ui と ActiveDocs の両方が同じように失敗する場合、ActiveDocs や ActiveDocs プロキシーの問題は除外して、ご自分の仕様のトラブルシューティングに集中できます。あるいは、swagger-ui GitHub リポジトリーで、現在の swagger-ui のバージョンに関する既知の問題を確認できます。

API を使用するクライアントの IP アドレスをホワイトリスト化しないよう推奨しています。ActiveDocs プロキシーは、高可用性を実現するためにフローティング IP アドレスを使用していますが、現在これらの IP の変更を通知する仕組みはありません。

ActiveDocs プロキシーが正しく機能しているかどうかを確認する方法の 1 つは、無効なクレデンシャルを使用して API を呼び出すことです。これにより、ActiveDocs プロキシーと API ゲートウェイの両方について、問題の有無を確認することができます。

API 呼び出しから 403 コード (または不正なクレデンシャルに対してゲートウェイで設定しているコード) が返される場合、呼び出しはゲートウェイに到達しているので、問題は API にあります。

ActiveDocs から行った呼び出しと ActiveDocs 外からの呼び出し間でヘッダーおよびパラメーターの相違点を特定するには、オンプレミスの APItools や Runscope などのサービスを介して呼び出しを行います。これにより、API に送信する前に HTTP 呼び出しを検査し、比較することができます。この操作により、問題を引き起こす可能性のあるリクエスト内のヘッダーやパラメーターを特定することができます。

デバッグログの有効化の詳細については、NGINX のデバッグログに関するドキュメント を参照してください。