サポート対象バージョンの OpenShift にインストールされた初期設定済みのオンプレミス型 AMP インスタンス

本書は、ノートパソコンやこれに類するエンドユーザー機器上のローカルインストールを対象としていません。

APIcast デプロイメントの規模が大きくなると、利用可能なストレージの量を増やす必要が生じる可能性があります。ストレージをスケールアップする方法は、永続ストレージに使用しているファイルシステムのタイプによって異なります。

ネットワークファイルシステム (NFS) を使用している場合は、oc edit pv コマンドを使用して永続ボリュームをスケールアップできます。

oc edit pv <pv_name>

他のストレージ手段を使用している場合は、以降のセクションに挙げる方法のいずれかを使用して、永続ボリュームを手動でスケールアップする必要があります。

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

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

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

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

oc get jobs

oc logs <job>

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

alerts テーブルは例外で、データベース管理者が手動でパージする必要があります。

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;

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

yum または rpm を使用して、ツールボックスを Red Hat Enterprise Linux にインストールできます。

以下に例を示します。

$ sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2.6-rpms --enable rhel-server-rhscl-7-rpms

ただし、Fedora Linux、Ubuntu Linux、Windows、または macOS に、サポートされないバージョンを使用できます。そのためには、最新の .rpm、.deb、.msi、または .pkg ファイルを GitHub から ダウンロードしてインストールします。

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

既存のリモートのリスト (名前、URL、および認証キー) を表示します。

$ 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321

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

短縮名 <name> のリモートを <url> に追加します。

3scale remote add instance_a https://123456789@example_a.net

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

短縮名 <name> のリモートを削除します。

3scale remote remove instance_a

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

リモートの短縮名を <old_name> から <new_name> に変更します。

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
    -d --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --end-user-required=<value>      End user required: true or false
    -p --published                      This will publish the application plan
       --setup-fee=<value>              Set-up fee
    -t --system-name=<value>            This will 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
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

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

次の例では、アプリケーションプランを更新します。

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

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

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
       --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --enabled                        This will enable the application plan
       --end-user-required=<value>      End user required: true or false
       --hide                           This will hide the application plan
    -n --name=<value>                   This will set the plan name
    -p --publish                        This will 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
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered
                                        insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

次の例は、アプリケーションプランを一覧表示します。

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

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

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

次の例は、アプリケーションプランを示しています。

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

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

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will 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
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

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

次の点に注意してください。アプリケーションプランで定義される制限が含まれます。アプリケーションプランで定義される課金ルールが含まれます。制限および課金ルールで参照されるメトリクス/メソッドが含まれます。アプリケーションプランで定義される機能が含まれます。サービスは id または system_name で参照できます。アプリケーションプランは id または system_name で参照できます。

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

3scale application-plan export -f 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
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

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

3scale application-plan import -f 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
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode

メトリクスを作成するには、以下の手順に従います。

次の例では、メトリックを作成します。

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

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

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
    -t --system-name=<value>      This will set the application plan system name
       --unit=<value>             Metric unit: default hit

Option for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

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

次の例では、メトリックを更新します。

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

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

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
       --enabled                  This will enable this metric in all application plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit

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

次の例は、メトリックを一覧表示します。

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

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

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will 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
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

次の例では、メソッドを作成します。

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

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

Option
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
    -t --system-name=<value>      This will set the method system name

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

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

次の例では、メソッドを更新します。

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

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

Options
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
       --enabled                  This will enable this method in all
                                  application plans
    -n --name=<value>             This will set the method name

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

次の例は、メソッドを一覧表示します。

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

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

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will 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
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will 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
    -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
                                          (default:
                                          $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints 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

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

次の例は、サービスを一覧表示します。

3scale service list <remote>

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

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

次の例は、サービスを示しています。

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

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

Options for services
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints 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 (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

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

Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
    -p --published                     Specify it to publish the ActiveDoc on
                                       the Developer Portal. Otherwise it
                                       will be hidden
    -s --system-name=<value>           Specify the system-name of the
                                       ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

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

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 it to hide the ActiveDocs on
                                       the Developer Portal
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
       --openapi-spec=<value>          Specify the swagger spec. Can be a
                                       file, an URL or '-' to read from
                                       stdin. This option is mandatory when
                                       applying the ActiveDoc for the first
                                       time
    -p --publish                       Specify it to publish the ActiveDocs
                                       on the Developer Portal. Otherwise it
                                       will be hidden
    -s --name=<value>                  Specify the name of the ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

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

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

次の例では、定義されたすべての ActiveDocs を一覧表示します。

3scale activedocs list <remote>

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

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints 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
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

次の例は、プロキシー設定を一覧表示します。

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

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

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

次の例は、プロキシー設定を示しています。

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

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

Options for proxy-config
    -c --config-file=<value>         3scale toolbox configuration file
                                     (default: /home/msoriano/.3scalerc.yaml)
    -h --help                        show help for this command
    -k --insecure                    Proceed and operate even for server
                                     connections otherwise considered
                                     insecure
    -v --version                     Prints 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 (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

次の例は、アプリケーションを一覧表示します。

3scale application list [opts] <remote>

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

OPTIONS
       --account=<value>          Filter by account
       --plan=<value>             Filter by application plan.
                                  Service option required.
       --service=<value>          Filter by service

特定の 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 to be
                                      created.
       --description=<value>          Application description
       --redirect-url=<value>         OpenID Connect redirect url
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.

次の例は、アプリケーションを示しています。

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

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

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

次の例では、アプリケーションを削除します。

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

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 のサンプルについてのみ説明します。

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

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

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

APIcast 組み込みゲートウェイを使用する場合には、「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: api01 というラベルの API を作成します。

以下の手順により、api: api01 というラベルのプランを追加します。

以下の手順により、metric01 というメトリクスを追加します。

以下の手順により、メトリクスに 1 日あたり 10 ヒットという制限を設定します。

以下の手順により、metric01 のカウントを増加させる MappingRule を追加します。

バインディングオブジェクトを使用してバインドするには、以下の手順に従います。

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

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

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

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

zync-database はリレーショナルデータベースで、3scale とアイデンティティープロバイダー (IdP) 間におけるアイデンティティーの同期に関連する情報を保存します。この情報は他のコンポーネントには複製されず、唯一の 信頼できるソース です。

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

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

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

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

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.rb ファイルをバックアップします。

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

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

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

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

以降のセクションで、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 から始めてクライアントまで遡って作業します。

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"

コマンドラインから API を呼び出す場合には機能するが、ActiveDocs を経由する場合には失敗することがあります。

ActiveDocs 呼び出しを機能させるために、これらの呼び出しを 3scale 側のプロキシー経由で送信します。このプロキシーが追加する特定のヘッダーが API にとって想定外だった場合に、問題を引き起こす可能性があります。これを確認するには、以下の手順を試みます。

これについての包括的なガイドは、NGINX のロギングとモニターリング に関するドキュメントを参照してください。

3scale Service Management API エンドポイントによって返されるエラーコードを確認するには、以下の手順に従って 3scale API Documentation のページを参照します。

以下は、3scale によって返される HTTP レスポンスコードと、そのコードが返される条件の一覧です。

これらのエラーレスポンスのほとんどには、マシンリーダブルなエラーカテゴリーと人が判読できる説明が含まれる XML ボディーも含まれています。

標準の API ゲートウェイ設定を使用する場合、3scale から 200 以外のコードが返されると、クライアントには以下のどちらかのコードと共にレスポンスが返されます。