検索

クラスターの設定

download PDF
OpenShift Container Platform 3.11

OpenShift Container Platform 3.11 のインストールおよび設定

概要

OpenShift のインストールと設定のトピックでは、ご使用の環境で OpenShift をインストールし、設定するための基本事項を説明します。扱われるトピックを参照して、OpenShift の稼働に必要な一度だけ実行するタスク (one-time task) を実行してください。

第1章 概要

本書では、OpenShift Container Platform クラスターのインストール後に利用できる追加の設定オプションについて説明します。

第2章 レジストリーのセットアップ

2.1. 内部レジストリーの概要

2.1.1. レジストリーについて

OpenShift Container Platform は、ソースコードから コンテナーイメージ をビルドし、デプロイし、そのライフサイクルを管理することができます。これを可能にするため、 OpenShift Container Platform は内部の 統合コンテナーイメージレジストリー を提供しています。このレジストリーは OpenShift Container Platform 環境にデプロイでき、ここからイメージをローカルで管理できます。

2.1.2. 統合レジストリーまたはスタンドアロンレジストリー

完全な OpenShift Container Platform クラスターの初回インストール時に、レジストリーはインストールプロセスで自動的にデプロイされている可能性があります。自動的にデプロイされていなかった場合やレジストリー設定のカスタマイズが追加で必要になる場合には、既存クラスターへのレジストリーのデプロイ を参照してください。

OpenShift Container Platform のレジストリーは、完全な OpenShift Container Platform クラスターの統合部分として実行されるようにデプロイすることが可能である一方、スタンドアロンのコンテナーイメージレジストリーとして個別にインストールすることも可能です。

スタンドアロンレジストリーをインストールするには、スタンドアロンレジストリーのインストール の手順に従ってください。このインストールパスは、レジストリーと専用の Web コンソールを実行するオールインワンのクラスターをデプロイします。

2.2. 既存クラスターへのレジストリーのデプロイ

2.2.1. 概要

OpenShift Container Platform クラスターの初回インストール時に統合レジストリーが事前に自動的にデプロイされなかった場合や、正常に実行されず、既存のクラスターに再デプロイする必要がある場合は、以下のセクションで新規レジストリーをデプロイするためのオプションを参照してください。

注記

スタンドアロンレジストリー をインストールしていない場合、このトピックは不要になります。

2.2.2. レジストリーホスト名の設定

内部参照と外部参照の両方でレジストリーを認識するために使用するホスト名およびポートを設定できます。これを実行すると、イメージストリームはイメージのホスト名ベースのプッシュおよびプル仕様を提供することができ、これによってイメージのコンシューマーがレジストリーのサービス IP の変更の影響を受けないようにし、イメージストリームとその参照をクラスター間で移植できる可能性があります。

クラスター内からレジストリーを参照するために使用されるホスト名を設定するには、マスター設定ファイルの imagePolicyConfig セクションで internalRegistryHostname を設定します。外部のホスト名は、同じ場所で externalRegistryHostname の値を設定することで管理されます。

イメージポリシーの設定

imagePolicyConfig:
  internalRegistryHostname: docker-registry.default.svc.cluster.local:5000
  externalRegistryHostname: docker-registry.mycompany.com

レジストリー自体は、同じ内部ホスト名の値で設定する必要があります。これは、レジストリーのデプロイメント設定で REGISTRY_OPENSHIFT_SERVER_ADDR 環境変数を設定するか、またはレジストリー設定の OpenShift セクション で値を設定することで実行できます。

注記

レジストリーで TLS を有効にしている場合、サーバー証明書にはレジストリーの参照に使用されるホスト名が含まれている必要があります。ホスト名をサーバー証明書に追加する方法については、レジストリーのセキュリティー保護 を参照してください。

2.2.3. レジストリーのデプロイ

統合コンテナーイメージレジストリーをデプロイするには、クラスター管理者権限を持つユーザーとして oc adm registry コマンドを使用します。以下に例を示します。

$ oc adm registry --config=/etc/origin/master/admin.kubeconfig \1
    --service-account=registry \2
    --images='registry.redhat.io/openshift3/ose-${component}:${version}' 3
1
--config は、クラスター管理者 のための CLI 設定ファイル へのパスです。
2
--service-account は、レジストリーの Pod の実行に使用されるサービスアカウントです。
3
OpenShift Container Platform の適切なイメージをプルするために必要です。${component} および ${version} はインストール時に動的に置き換えられます。

これにより、docker-registry と呼ばれるサービスとデプロイメント設定が作成されます。正常にデプロイされると、Pod が docker-registry-1-cpty9 のような名前で作成されます。

レジストリーの作成時に指定できるオプションの詳細の一覧を表示するには、以下を実行します。

$ oc adm registry --help

--fs-group の値は、レジストリーが使用する SCC (通常は制限付き SCC) によって許可されている必要があります。

2.2.4. レジストリーの DaemonSet としてのデプロイ

レジストリーを --daemonset オプションを使用して DaemonSet としてデプロイするには、 oc adm registry コマンドを使用します。

DeamonSet は、ノードの作成時に、それらに指定された Pod のコピーが含まれていることを確認します。ノードが削除されると、Pod はガベージコレクションされます。

DaemonSet の詳細は、Daemonset の使用 を参照してください。

2.2.5. レジストリーのコンピュートリソース

デフォルトでは、レジストリーは コンピュートリソースの要求や制限 に関する設定がない状態で作成されます。実稼働環境では、レジストリーのデプロイメント設定を更新してレジストリー Pod のリソース要求や制限を設定しておくことが強く推奨されます。設定しない場合、レジストリー Pod は BestEffort Pod と判断されます。

要求や制限の設定に関する詳細は、コンピュートリソース を参照してください。

2.2.6. レジストリーのストレージ

レジストリーには、コンテナーのイメージとメタデータが格納されています。Pod をレジストリーと共に単純にデプロイする場合、Pod の終了時に破棄される一時的なボリュームを使用します。誰かがビルドまたはレジストリーにプッシュしたイメージは消えます。

このセクションでは、サポートされているレジストリーのストレージドライバーの一覧を示します。詳細は、コンテナーイメージレジストリーのドキュメント を参照してください。

以下の一覧には、レジストリーの設定ファイルで設定する必要のあるストレージドライバーが含まれます。

レジストリーの一般的なストレージ設定オプションはサポートされています。詳細は、コンテナーイメージレジストリーのドキュメント を参照してください。

以下のストレージオプションは、ファイルシステムドライバー で設定する必要があります。

注記

サポートされている永続ストレージドライバーの詳細は、永続ストレージの設定 および 永続ストレージの例 を参照してください。

2.2.6.1. 実稼働環境での使用

実稼働環境での使用の場合には、リモートボリュームを割り当てるか、または 各自が選択した永続ストレージ方法を定義して使用します

たとえば、既存の Persistent Volume Claim (永続ボリューム要求) を使用するには、以下を実行します。

$ oc set volume deploymentconfigs/docker-registry --add --name=registry-storage -t pvc \
     --claim-name=<pvc_name> --overwrite
重要

テストにより、RHEL NFS サーバーをコンテナーイメージレジストリーのストレージバックエンドとして使用することに関する問題が検出されています。これには、OpenShift Container レジストリーおよび Quay が含まれます。そのため、コアサービスで使用される PV をサポートするために RHEL NFS サーバーを使用することは推奨されていません。

他の NFS の実装ではこれらの問題が検出されない可能性があります。OpenShift コアコンポーネントに対して実施された可能性のあるテストに関する詳細情報は、個別の NFS 実装ベンダーにお問い合わせください。

2.2.6.1.1. Amazon S3 のストレージのバックエンドとしての使用

Amazon Simple Storage Service のストレージを内部コンテナーイメージレジストリーと共に使用する方法もあります。Amazon Simple Storage Service は AWS マネジメントコンソール で管理できるセキュアなクラウドストレージです。これを使用するには、レジストリーの設定ファイルを手動で編集し、レジストリー Pod にマウントする必要があります。ただし、設定を開始する前に、アップストリームの 推奨される手順 を確認してください。

デフォルトの YAML 設定ファイル をベースとして取得し、storageセクションのfilesystemエントリーを、以下のように s3 エントリーに置き換えます。これにより、ストレージのセクションは以下のようになります。

storage:
  cache:
    layerinfo: inmemory
  delete:
    enabled: true
  s3:
    accesskey: awsaccesskey 1
    secretkey: awssecretkey 2
    region: us-west-1
    regionendpoint: http://myobjects.local
    bucket: bucketname
    encrypt: true
    keyid: mykeyid
    secure: true
    v4auth: false
    chunksize: 5242880
    rootdirectory: /s3/object/name/prefix
1
Amazon のアクセスキーに置き換えてください。
2
Amazon のシークレットキーに置き換えてください。

s3 のすべての設定オプションは、アップストリームの ドライバー参照ドキュメント に記載されています。

レジストリー設定を上書き すると、設定ファイルを Pod にマウントするための追加の手順に進みます。

警告

レジストリーが S3 ストレージのバックエンドで実行されると、問題が報告されます

使用している統合レジストリーでサポートされていない S3 リージョンを使用する必要がある場合は、S3 ドライバー設定 を参照してください。

2.2.6.2. 非実稼働環境での使用

非実稼働環境の場合、--mount-host=<path> オプションを使って、永続ストレージに使用するレジストリーのディレクトリーを指定します。次に、レジストリーのボリュームがホストのマウントとして、指定された <path> に作成されます。

重要

--mount-host オプションは、レジストリーのコンテナーが実行されているノードからディレクトリーをマウントします。docker-registry デプロイメント設定をスケールアップすると、レジストリー Pod とコンテナーが別々のノードで実行されので、それぞれ独自のローカルストレージを使用したレジストリーコンテナーが 2 つ以上作成される可能性があります。これは予期しない動作を生じさせます。 その後に繰り返される同一イメージのプル要求が最終的に到達するコンテナーによっては必ずしも成功しない場合があるためです。

--mount-host オプションは、レジストリーコンテナーを特権モードで実行することを要求します。この要求は、ユーザーが --mount-host を指定すると自動的に有効にされます。ただしデフォルトでは、すべての Pod が 特権付きコンテナー をデフォルトで実行できる訳ではありません。それでもこのオプションを使用する必要がある場合は、レジストリーを作成してから、レジストリーがインストール時に作成された registry サービスアカウントを使用するように指定してください。

$ oc adm registry --service-account=registry \
    --config=/etc/origin/master/admin.kubeconfig \
    --images='registry.redhat.io/openshift3/ose-${component}:${version}' \ 1
    --mount-host=<path>
1
OpenShift Container Platform の適切なイメージをプルするために必要です。${component} および ${version} はインストール時に動的に置き換えられます。
重要

コンテナーイメージレジストリー Pod は、ユーザー 1001 として実行されます。このユーザーは、ホストのディレクトリーへの書き込みができなければなりません。したがって、以下のコマンドでディレクトリーの所有権をユーザー ID 1001 に変更する必要がある場合があります。

$ sudo chown 1001:root <path>

2.2.7. レジストリーコンソールの有効化

OpenShift Container Platform は、統合レジストリーへの Web ベースのインターフェイスを提供します。このレジストリーコンソールは、イメージを参照および管理するためのコンポーネント (任意) です。Pod として実行されているステートレスサービスとしてデプロイされます。

注記

OpenShift Container Platform を スタンドアロンレジストリー としてインストールした場合、レジストリーコンソールはインストール時にすでにデプロイされ、そのセキュリティーが自動的に保護されています。

重要

Cockpit がすでに実行されている場合、レジストリーコンソールとのポート競合 (デフォルトでは 9090) を避けるために、次に進む前にこれをシャットダウンする必要があります。

2.2.7.1. レジストリーコンソールのデプロイ
重要

最初に レジストリーを公開 しておく必要があります。

  1. デフォルトのプロジェクトにパススルールートを作成します。このルートは、以下の手順でレジストリーコンソールのアプリケーションを作成する際に必要になります。

    $ oc create route passthrough --service registry-console \
        --port registry-console \
        -n default
  2. レジストリーコンソールのアプリケーションをデプロイします。<openshift_oauth_url> を OpenShift Container Platform OAuth プロバイダー の URL に置き換えます。 通常これはマスターになります。

    $ oc new-app -n default --template=registry-console \
        -p OPENSHIFT_OAUTH_PROVIDER_URL="https://<openshift_oauth_url>:8443" \
        -p REGISTRY_HOST=$(oc get route docker-registry -n default --template='{{ .spec.host }}') \
        -p COCKPIT_KUBE_URL=$(oc get route registry-console -n default --template='https://{{ .spec.host }}')
    注記

    レジストリーコンソールへのログインの試行時にリダイレクト URL が間違っていた場合は、oc get oauthclients で OAuth クライアントを確認してください。

  3. 最後に、Web ブラウザーでこのルート URI を使用しているコンソールを表示します。
2.2.7.2. レジストリーコンソールのセキュリティー保護

デフォルトでは、レジストリーコンソールは、レジストリーコンソールのデプロイ の手順ごとに手動でデプロイされる場合に自己署名 TLS 証明書を生成します。詳細は、レジストリーコンソールのトラブルシューティング を参照してください。

組織の署名済み証明書をシークレットボリュームとして追加する際には、以下の手順に従ってください。ここでは、証明書が oc クライアントホストで利用可能であることを前提としています。

  1. 証明書とキーを含む .cert ファイルを作成します。以下を使用してファイルをフォーマットします。

    • サーバー証明書と中間証明機関のための 1 つ以上数の BEGIN CERTIFICATE ブロック。
    • キーの BEGIN PRIVATE KEY または同種のものを含むブロック。キーは暗号化することができません。

      以下に例を示します。

      -----BEGIN CERTIFICATE-----
      MIIDUzCCAjugAwIBAgIJAPXW+CuNYS6QMA0GCSqGSIb3DQEBCwUAMD8xKTAnBgNV
      BAoMIGI0OGE2NGNkNmMwNTQ1YThhZTgxOTEzZDE5YmJjMmRjMRIwEAYDVQQDDAls
      ...
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      MIIDUzCCAjugAwIBAgIJAPXW+CuNYS6QMA0GCSqGSIb3DQEBCwUAMD8xKTAnBgNV
      BAoMIGI0OGE2NGNkNmMwNTQ1YThhZTgxOTEzZDE5YmJjMmRjMRIwEAYDVQQDDAls
      ...
      -----END CERTIFICATE-----
      -----BEGIN PRIVATE KEY-----
      MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCyOJ5garOYw0sm
      8TBCDSqQ/H1awGMzDYdB11xuHHsxYS2VepPMzMzryHR137I4dGFLhvdTvJUH8lUS
      ...
      -----END PRIVATE KEY-----
    • セキュリティーの保護されたレジストリーには、以下の SAN (サブジェクトの別名: Subject Alternative Names) 一覧が含まれているはずです。

      • 2 つのサービスのホスト名。

        以下に例を示します。

        docker-registry.default.svc.cluster.local
        docker-registry.default.svc
      • サービス IP アドレス。

        以下に例を示します。

        172.30.124.220

        以下のコマンドを使ってコンテナーイメージレジストリーのサービス IP アドレスを取得します。

        oc get service docker-registry --template='{{.spec.clusterIP}}'
      • パブリックホスト名。

        以下に例を示します。

        docker-registry-default.apps.example.com

        以下のコマンドを使ってコンテナーイメージレジストリーのパブリックホスト名を取得します。

        oc get route docker-registry --template '{{.spec.host}}'

        たとえば、サーバー証明書には以下のような SAN の詳細が記載されるはずです。

        X509v3 Subject Alternative Name:
                       DNS:docker-registry-public.openshift.com, DNS:docker-registry.default.svc, DNS:docker-registry.default.svc.cluster.local, DNS:172.30.2.98, IP Address:172.30.2.98

        レジストリーコンソールは、証明書を /etc/cockpit/ws-certs.d ディレクトリーから読み込みます。また、拡張子 .cert が付いたファイルをアルファベット順で (最後から) 使用します。したがって、.cert ファイルには OpenSSL スタイルでフォーマットされた PEM ブロックが少なくとも 2 つ含まれる必要があります。

        証明書がない場合、自己署名証明書が openssl コマンドで作成され、0-self-signed.cert ファイルに保存されます。

  2. シークレットを作成します。

    $ oc create secret generic console-secret \
        --from-file=/path/to/console.cert
  3. このシークレットを registry-console デプロイメント設定に追加します。

    $ oc set volume dc/registry-console --add --type=secret \
        --secret-name=console-secret -m /etc/cockpit/ws-certs.d

    これにより、レジストリーコンソールの新規デプロイメントがトリガーされ、署名済み証明書が組み込まれます。

2.2.7.3. レジストリーコンソールのトラブルシューティング
2.2.7.3.1. デバッグモード

レジストリーコンソールのデバッグモードは環境変数を使用して有効にされます。以下のコマンドは、レジストリーコンソールをデバッグモードで再デプロイします。

$ oc set env dc registry-console G_MESSAGES_DEBUG=cockpit-ws,cockpit-wrapper

デバッグモードを有効にすると、より詳細なログがレジストリーコンソールの Pod ログに表示されます。

2.2.7.3.2. SSL 証明書パスの表示

レジストリーコンソールが使用している証明書を確認するには、コマンドをコンソール Pod 内から実行できます。

  1. default プロジェクトで Pod を一覧表示し、レジストリーコンソールの Pod 名を検索します。

    $ oc get pods -n default
    NAME                       READY     STATUS    RESTARTS   AGE
    registry-console-1-rssrw   1/1       Running   0          1d
  2. 直前のコマンドで取得した Pod 名を使って、cockpit-ws プロセスが使用している証明書パスを取得します。以下は、自動生成された証明書を使用しているコンソールの例です。

    $ oc exec registry-console-1-rssrw remotectl certificate
    certificate: /etc/cockpit/ws-certs.d/0-self-signed.cert

2.3. レジストリーへのアクセス

2.3.1. ログの表示

コンテナーイメージレジストリーのログを表示するには、デプロイメント設定で oc logs コマンドを使用します。

$ oc logs dc/docker-registry
2015-05-01T19:48:36.300593110Z time="2015-05-01T19:48:36Z" level=info msg="version=v2.0.0+unknown"
2015-05-01T19:48:36.303294724Z time="2015-05-01T19:48:36Z" level=info msg="redis not configured" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002
2015-05-01T19:48:36.303422845Z time="2015-05-01T19:48:36Z" level=info msg="using inmemory layerinfo cache" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002
2015-05-01T19:48:36.303433991Z time="2015-05-01T19:48:36Z" level=info msg="Using OpenShift Auth handler"
2015-05-01T19:48:36.303439084Z time="2015-05-01T19:48:36Z" level=info msg="listening on :5000" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002

2.3.2. ファイルストレージ

タグとイメージメタデータは OpenShift Container Platform に格納されますが、レジストリーは、レイヤーと署名データを /registry にあるレジストリーコンテナーにマウントされているボリュームに格納します。oc exec は特権付きコンテナーでは機能しないため、レジストリーの内容を確認するには、レジストリー Pod のコンテナーを格納しているノードに対して SSH を手動で実行し、コンテナー自体で docker exec を実行します。

  1. 現在の Pod を一覧表示し、コンテナーイメージレジストリーの Pod 名を検索します。

    # oc get pods

    次に、oc describe を使用して、コンテナーを実行しているノードのホスト名を検索します。

    # oc describe pod <pod_name>
  2. 目的のノードにログインします。

    # ssh node.example.com
  3. ノードホストのデフォルトプロジェクトから実行中のコンテナーを一覧表示し、コンテナーイメージレジストリーのコンテナー ID を特定します。

    # docker ps --filter=name=registry_docker-registry.*_default_
  4. oc rsh コマンドを使用してレジストリーの内容を一覧表示します。

    # oc rsh dc/docker-registry find /registry
    /registry/docker
    /registry/docker/registry
    /registry/docker/registry/v2
    /registry/docker/registry/v2/blobs 1
    /registry/docker/registry/v2/blobs/sha256
    /registry/docker/registry/v2/blobs/sha256/ed
    /registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
    /registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/data 2
    /registry/docker/registry/v2/blobs/sha256/a3
    /registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    /registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/data
    /registry/docker/registry/v2/blobs/sha256/f7
    /registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
    /registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/data
    /registry/docker/registry/v2/repositories 3
    /registry/docker/registry/v2/repositories/p1
    /registry/docker/registry/v2/repositories/p1/pause 4
    /registry/docker/registry/v2/repositories/p1/pause/_manifests
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures 5
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
    /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/link 6
    /registry/docker/registry/v2/repositories/p1/pause/_uploads 7
    /registry/docker/registry/v2/repositories/p1/pause/_layers 8
    /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256
    /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/link 9
    /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
    /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/link
    1
    このディレクトリーには、すべてのレイヤーと署名が Blob として格納されます。
    2
    このファイルには、Blob の内容が含まれます。
    3
    このディレクトリーには、すべてのイメージリポジトリーが格納されます。
    4
    このディレクトリーは単一イメージリポジトリーの p1/pause 用です。
    5
    このディレクトリーには、特定のイメージマニフェストリビジョンの署名が含まれます。
    6
    このファイルには、Blob (署名データを含む) への参照が含まれます。
    7
    このディレクトリーには、指定されたリポジトリーに対して現在アップロードされステージングされているすべてのレイヤーが含まれます。
    8
    このディレクトリーには、このリポジトリーが参照するすべてのレイヤーへのリンクが含まれます。
    9
    このファイルには、イメージを介してこのリポジトリーにリンクされている特定のレイヤーへの参照が含まれます。

2.3.3. レジストリーへの直接アクセス

さらに高度な使用方法として、レジストリーに直接アクセスし、docker コマンドを起動することが可能です。これにより、docker pushdocker pull などの操作で直接イメージをプッシュするか、または統合レジストリーからイメージをプルすることができます。これを実行するには、docker login コマンドを使ってレジストリーにログインしている必要があります。実行できる操作は、以下のセクションで説明されているようにユーザーが持つパーミッションによって異なります。

2.3.3.1. ユーザーの前提条件

レジストリーに直接アクセスするには、使用するユーザーが、使用目的に応じて以下の前提条件を満たしている必要があります。

  • 直接アクセスするには、ユーザーは選択する アイデンティティープロバイダー通常ユーザー である必要があります。通常ユーザーは、レジストリーへのログインに必要なアクセストークンを生成できます。system:admin などの システムユーザー はアクセストークンを取得できないため、レジストリーに直接アクセスすることはできません。

    たとえば HTPASSWD 認証を使用している場合は、以下のコマンドを使用してこれを作成することができます。

    # htpasswd /etc/origin/master/htpasswd <user_name>
  • docker pull コマンドを使用する場合などにイメージをプルするには、ユーザーに registry-viewer ロールがなければなりません。このロールを追加するには、以下を実行します。

    $ oc policy add-role-to-user registry-viewer <user_name>
  • イメージの書き出しやプッシュを実行するには (docker push コマンドを使用する場合など)、ユーザーに registry-editor ロールが必要です。このロールを追加するには、以下を実行します。

    $ oc policy add-role-to-user registry-editor <user_name>

ユーザーパーミッションに関する詳細は、ロールバインディングの管理 を参照してください。

2.3.3.2. レジストリーへのログイン
注記

ユーザーが、レジストリーに直接アクセスできるための 前提条件 を満たしていることを確認してください。

レジストリーに直接ログインするには、以下を実行します。

  1. OpenShift Container Platform に通常ユーザーとしてログインしていることを確認します。

    $ oc login
  2. アクセストークンを使用してコンテナーイメージレジストリーにログインします。

    docker login -u openshift -p $(oc whoami -t) <registry_ip>:<port>
注記

ユーザー名の任意の値を渡すことができ、トークンには必要な情報がすべて含まれます。コロンを含むユーザー名を渡すとログインに失敗します。

2.3.3.3. イメージのプッシュとプル

レジストリーにログイン すると、レジストリーに docker pull および docker push 操作を実行できます。

重要

任意のイメージをプルできますが、system:registry ロールを追加している場合は、各自のプロジェクトにあるレジストリーにのみイメージをプッシュすることができます。

次の例では、以下を使用します。

コンポーネント

<registry_ip>

172.30.124.220

<port>

5000

<project>

openshift

<image>

busybox

<tag>

省略 (デフォルトは latest)

  1. 任意のイメージをプルします。

    $ docker pull docker.io/busybox
  2. 新規イメージに <registry_ip>:<port>/<project>/<image> 形式でタグ付けします。プロジェクト名は、イメージを正しくレジストリーに配置し、これに後でアクセスできるようにするために OpenShift Container Platform の プル仕様 に表示される必要があります

    $ docker tag docker.io/busybox 172.30.124.220:5000/openshift/busybox
    注記

    通常ユーザーには、指定されたプロジェクトの system:image-builder ロールが必要です。このロールにより、ユーザーはイメージの書き出しやプッシュを実行できます。そうしないと、次の手順の docker push は失敗します。テストするには、新しいプロジェクトを作成 して、busybox イメージをプッシュします。

  3. 新しくタグ付けされたイメージをレジストリーにプッシュします。

    $ docker push 172.30.124.220:5000/openshift/busybox
    ...
    cf2616975b4a: Image successfully pushed
    Digest: sha256:3662dd821983bc4326bee12caec61367e7fb6f6a3ee547cbaff98f77403cab55

2.3.4. レジストリーメトリクスへのアクセス

OpenShift Container レジストリーは、Prometheus メトリクス のエンドポイントを提供します。Prometheus はスタンドアロンのオープンソースのシステムモニターリングおよびアラートツールキットです。

メトリクスは、レジストリーエンドポイントの /extensions/v2/metrics パスに公開されます。ただし、このルートは最初に有効にされている必要があります。 有効化の方法については レジストリー設定の拡張 を参照してください。

以下は、メトリクスクエリーの簡単な例です。

$ curl -s -u <user>:<secret> \ 1
    http://172.30.30.30:5000/extensions/v2/metrics | grep openshift | head -n 10

# HELP openshift_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which OpenShift was built.
# TYPE openshift_build_info gauge
openshift_build_info{gitCommit="67275e1",gitVersion="v3.6.0-alpha.1+67275e1-803",major="3",minor="6+"} 1
# HELP openshift_registry_request_duration_seconds Request latency summary in microseconds for each operation
# TYPE openshift_registry_request_duration_seconds summary
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.5"} 0
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.9"} 0
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.99"} 0
openshift_registry_request_duration_seconds_sum{name="test/origin-pod",operation="blobstore.create"} 0
openshift_registry_request_duration_seconds_count{name="test/origin-pod",operation="blobstore.create"} 5
1
<user> は任意ですが、<secret>レジストリー設定 で指定された値と一致していなければなりません。

メトリクスにアクセスするための別の方法は、クラスターロールの使用です。エンドポイントはここでも有効にする必要がありますが、<secret> を指定する必要はありません。設定ファイルのメトリクスに対応する部分は以下のようになります。

openshift:
  version: 1.0
  metrics:
    enabled: true
...

メトリクスにアクセスするために必要なクラスターロールがない場合、これを作成する必要があります。

$ cat <<EOF |
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-scraper
rules:
- apiGroups:
  - image.openshift.io
  resources:
  - registry/metrics
  verbs:
  - get
EOF
oc create -f -

このロールをユーザーに追加するには、以下のコマンドを実行します。

$ oc adm policy add-cluster-role-to-user prometheus-scraper <username>

高度なクエリーと推奨されるビジュアライザーについては、アップストリームの Prometheus ドキュメント を参照してください。

2.4. レジストリーのセキュリティー保護および公開

2.4.1. 概要

デフォルトでは、OpenShift Container Platform レジストリーは、TLS 経由でトラフィックを提供できるようクラスターのインストール時にセキュリティー保護されます。サービスを外部に公開するために、パススルールートもデフォルトで作成されます。

何らかの理由でレジストリーが保護されていないか、または公開されていない場合は、これらを手動で実行する方法について以下のセクションを参照してください。

2.4.2. レジストリーを手動でセキュリティー保護する

レジストリーを手動でセキュリティー保護して TLS 経由でトラフィックを処理するには、以下を実行します。

  1. レジストリーをデプロイします
  2. レジストリーのサービス IP とポートを取得します。

    $ oc get svc/docker-registry
    NAME              TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
    docker-registry   ClusterIP   172.30.82.152   <none>        5000/TCP   1d
  3. 既存のサーバー証明書を使用するか、またはキーと、指定された CA で署名された指定 IP およびホスト名に有効なサーバー証明書を作成します。レジストリーのサービス IP と docker-registry.default.svc.cluster.local ホスト名のサーバー証明書を作成するには、Ansible ホストインベントリーファイル (デフォルトでは /etc/ansible/hosts) に一覧表示されている最初のマスターから以下のコマンドを実行します。

    $ oc adm ca create-server-cert \
        --signer-cert=/etc/origin/master/ca.crt \
        --signer-key=/etc/origin/master/ca.key \
        --signer-serial=/etc/origin/master/ca.serial.txt \
        --hostnames='docker-registry.default.svc.cluster.local,docker-registry.default.svc,172.30.124.220' \
        --cert=/etc/secrets/registry.crt \
        --key=/etc/secrets/registry.key

    ルーターを 外部に公開する 場合、公開ルートのホスト名を --hostnames フラグに追加します。

    --hostnames='mydocker-registry.example.com,docker-registry.default.svc.cluster.local,172.30.124.220 \

    ルートを外部にアクセス可能にするためにデフォルトの証明書を更新する際のその他詳細については、レジストリーとルーター証明書の再デプロイ を参照してください。

    注記

    oc adm ca create-server-cert コマンドは、2 年間有効な証明書を生成します。この期間は --expire-days オプションを使って変更することができますが、セキュリティー上の理由から、値をこれより大きくすることは推奨されません。

  4. レジストリー証明書のシークレットを作成します。

    $ oc create secret generic registry-certificates \
        --from-file=/etc/secrets/registry.crt \
        --from-file=/etc/secrets/registry.key
  5. シークレットをレジストリー Pod のサービスアカウント (デフォルトのサービスアカウントなど) に追加します。

    $ oc secrets link registry registry-certificates
    $ oc secrets link default  registry-certificates
    注記

    シークレットを参照しているサービスアカウントにのみにシークレットを制限することはデフォルトで無効にされています。つまり、マスターの設定ファイルで serviceAccountConfig.limitSecretReferences がマスター設定の false (デフォルトの設定) に設定されている場合は、サービスにシークレットをリンクする必要はありません。

  6. docker-registry サービスを一時停止します。

    $ oc rollout pause dc/docker-registry
  7. シークレットボリュームをレジストリーのデプロイメント設定に追加します。

    $ oc set volume dc/docker-registry --add --type=secret \
        --secret-name=registry-certificates -m /etc/secrets
  8. 以下の環境変数をレジストリーのデプロイメント設定に追加して TLS を有効にします。

    $ oc set env dc/docker-registry \
        REGISTRY_HTTP_TLS_CERTIFICATE=/etc/secrets/registry.crt \
        REGISTRY_HTTP_TLS_KEY=/etc/secrets/registry.key

    詳細は、Docker ドキュメントのレジストリーの設定 のセクションを参照してください。

  9. レジストリーの liveness probe に使用されているスキームを HTTP から HTTPS に更新します。

    $ oc patch dc/docker-registry -p '{"spec": {"template": {"spec": {"containers":[{
        "name":"registry",
        "livenessProbe":  {"httpGet": {"scheme":"HTTPS"}}
      }]}}}}'
  10. レジストリーを OpenShift Container Platform 3.2 以降に初めてデプロイした場合は、レジストリーの readiness probe として使用されているスキームを HTTP から HTTPS に更新します。

    $ oc patch dc/docker-registry -p '{"spec": {"template": {"spec": {"containers":[{
        "name":"registry",
        "readinessProbe":  {"httpGet": {"scheme":"HTTPS"}}
      }]}}}}'
  11. docker-registry サービスを再開します。

    $ oc rollout resume dc/docker-registry
  12. レジストリーが TLS モードで実行されていることを検証します。最後の docker-registry のデプロイメントが完了するまで待機し、Docker ログでレジストリーコンテナーを確認します。listening on :5000, tls のエントリーが見つかるはずです。

    $ oc logs dc/docker-registry | grep tls
    time="2015-05-27T05:05:53Z" level=info msg="listening on :5000, tls" instance.id=deeba528-c478-41f5-b751-dc48e4935fc2
  13. CA 証明書を Docker 証明書ディレクトリーにコピーします。これはクラスター内のすべてのノードで実行する必要があります。

    $ dcertsdir=/etc/docker/certs.d
    $ destdir_addr=$dcertsdir/172.30.124.220:5000
    $ destdir_name=$dcertsdir/docker-registry.default.svc.cluster.local:5000
    
    $ sudo mkdir -p $destdir_addr $destdir_name
    $ sudo cp ca.crt $destdir_addr    1
    $ sudo cp ca.crt $destdir_name
    1
    ca.crt ファイルは、マスター上の /etc/origin/master/ca.crt のコピーです。
  14. 認証を使用している場合、docker のバージョンによっては、OS レベルで証明書を信頼するようにクラスターを設定することも必要になります。

    1. 証明書をコピーします。

      $ cp /etc/origin/master/ca.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
    2. 以下を実行します。

      $ update-ca-trust enable
  15. /etc/sysconfig/docker ファイルのこの特定のレジストリーに対してのみ、--insecure-registry オプションを削除します。次にデーモンを再度読み込み、 docker サービスを再起動して設定の変更を反映させます。

    $ sudo systemctl daemon-reload
    $ sudo systemctl restart docker
  16. docker クライアント接続を検証します。レジストリーに対する docker push、またはレジストリーからの docker pull が正常に実行されるはずです。必ず このレジストリーにログインしていること を確認してください。

    $ docker tag|push <registry/image> <internal_registry/project/image>

    以下に例を示します。

    $ docker pull busybox
    $ docker tag docker.io/busybox 172.30.124.220:5000/openshift/busybox
    $ docker push 172.30.124.220:5000/openshift/busybox
    ...
    cf2616975b4a: Image successfully pushed
    Digest: sha256:3662dd821983bc4326bee12caec61367e7fb6f6a3ee547cbaff98f77403cab55

2.4.3. セキュアなレジストリーの手動による公開

OpenShift Container Platform クラスター内から、OpenShift Container Platform レジストリーにログインするのではなく、外部からレジストリーにアクセスできるようにするには、先にレジストリーのセキュリティーを確保してから、このレジストリーをルートに公開します。この方法を使うと、ルートアドレスを使ってクラスターの外部からレジストリーにログインし、ルートのホストを使ってイメージにタグ付けしたり、イメージをプッシュしたりできます。

  1. 以下の前提条件に関するそれぞれの手順は、標準的なクラスターのインストール時にデフォルトで実行されます。これが実行されていない場合は、手動で実行してください。

  2. パススルールート は、クラスターの初回のインストール時にレジストリーについてデフォルトで作成されている必要があります。

    1. ルートが存在するかどうかを確認します。

      $ oc get route/docker-registry -o yaml
      apiVersion: v1
      kind: Route
      metadata:
        name: docker-registry
      spec:
        host: <host> 1
        to:
          kind: Service
          name: docker-registry 2
        tls:
          termination: passthrough 3
      1
      ルートのホスト。この名前は、外部から DNS 経由でルーターの IP アドレスに解決できる必要があります。
      2
      レジストリーのサービス名。
      3
      このルートをパススルールートとして指定します。
      注記

      Re-encrypt ルートはセキュアなレジストリーを公開するためにもサポートされています。

    2. ルートが存在していない場合、oc create route passthrough コマンドで、レジストリーをルートのサービスとして指定してルートを作成します。デフォルトでは、作成したルートの名前はサービス名と同じです。

      1. docker-registry サービスの詳細を取得します。

        $ oc get svc
        NAME              CLUSTER_IP       EXTERNAL_IP   PORT(S)                 SELECTOR                  AGE
        docker-registry   172.30.69.167    <none>        5000/TCP                docker-registry=default   4h
        kubernetes        172.30.0.1       <none>        443/TCP,53/UDP,53/TCP   <none>                    4h
        router            172.30.172.132   <none>        80/TCP                  router=router             4h
      2. ルートを作成します。

        $ oc create route passthrough    \
            --service=docker-registry    \1
            --hostname=<host>
        route "docker-registry" created     2
        1
        レジストリーをルートのサービスとして指定します。
        2
        ルート名はサービス名と同じです。
  3. 次に、ホストシステム上のレジストリーに使用されている証明書を信頼し、ホストによるイメージのプッシュおよびプルを許可する必要があります。参照される証明書は、レジストリーのセキュリティー保護を実行したときに作成されたものです。

    $ sudo mkdir -p /etc/docker/certs.d/<host>
    $ sudo cp <ca_certificate_file> /etc/docker/certs.d/<host>
    $ sudo systemctl restart docker
  4. レジストリーのセキュリティー保護の実行時に得られた情報を使って レジストリーにログイン します。ただし、ここではサービス IP ではなくルートで使用されているホスト名を指定します。セキュリティーが保護され、公開されているレジストリーにログインする際は、必ず docker login コマンドのレジストリーを指定してください。

    # docker login -e user@company.com \
        -u f83j5h6 \
        -p Ju1PeM47R0B92Lk3AZp-bWJSck2F7aGCiZ66aFGZrs2 \
        <host>
  5. これでルートのホストを使ってイメージのタグ付けとプッシュを実行できます。たとえば、test という名前のプロジェクトにある busybox イメージをタグ付けし、プッシュするには、以下を実行します。

    $ oc get imagestreams -n test
    NAME      DOCKER REPO   TAGS      UPDATED
    
    $ docker pull busybox
    $ docker tag busybox <host>/test/busybox
    $ docker push <host>/test/busybox
    The push refers to a repository [<host>/test/busybox] (len: 1)
    8c2e06607696: Image already exists
    6ce2e90b0bc7: Image successfully pushed
    cf2616975b4a: Image successfully pushed
    Digest: sha256:6c7e676d76921031532d7d9c0394d0da7c2906f4cb4c049904c4031147d8ca31
    
    $ docker pull <host>/test/busybox
    latest: Pulling from <host>/test/busybox
    cf2616975b4a: Already exists
    6ce2e90b0bc7: Already exists
    8c2e06607696: Already exists
    Digest: sha256:6c7e676d76921031532d7d9c0394d0da7c2906f4cb4c049904c4031147d8ca31
    Status: Image is up to date for <host>/test/busybox:latest
    
    $ oc get imagestreams -n test
    NAME      DOCKER REPO                       TAGS      UPDATED
    busybox   172.30.11.215:5000/test/busybox   latest    2 seconds ago
    注記

    イメージストリームにはルート名とポートではなく、レジストリーサービスの IP アドレスとポートが設定されます。詳細は oc get imagestreams を参照してください。

2.4.4. 非セキュアなレジストリーを手動で公開する

レジストリーを公開するためにレジストリーのセキュリティーを保護する代わりに、OpenShift Container Platform の非実稼働環境で、非セキュアなレジストリーを簡単に公開できます。これにより、SSL 証明書を使用せずにレジストリーへの外部ルートを作成することができます。

警告

非実稼働環境以外では、非セキュアなレジストリーを外部アクセスに公開すべきではありません。

非セキュアなレジストリーを公開するには、以下を実行します。

  1. レジストリーを公開します。

    # oc expose service docker-registry --hostname=<hostname> -n default

    以下の JSON ファイルが作成されます。

    apiVersion: v1
    kind: Route
    metadata:
      creationTimestamp: null
      labels:
        docker-registry: default
      name: docker-registry
    spec:
      host: registry.example.com
      port:
        targetPort: "5000"
      to:
        kind: Service
        name: docker-registry
    status: {}
  2. ルートが正常に作成されたことを確認します。

    # oc get route
    NAME              HOST/PORT                    PATH      SERVICE           LABELS                    INSECURE POLICY   TLS TERMINATION
    docker-registry   registry.example.com            docker-registry   docker-registry=default
  3. レジストリーの健全性を確認します。

    $ curl -v http://registry.example.com/healthz

    HTTP 200 / OK メッセージが表示されるはずです。

    レジストリーを公開したら、ポート番号を OPTIONS エントリーに追加して /etc/sysconfig/docker ファイルを更新します。以下に例を示します。

    OPTIONS='--selinux-enabled --insecure-registry=172.30.0.0/16 --insecure-registry registry.example.com:80'
    重要

    上記のオプションは、ログインしようとしているクライアントに追加してください。

    また、Docker がクライアント上で実行されていることも確認してください。

公開されている非セキュアなレジストリーに ログイン する際に、docker login コマンドでレジストリーを指定していることを確認します。以下に例を示します。

# docker login -e user@company.com \
    -u f83j5h6 \
    -p Ju1PeM47R0B92Lk3AZp-bWJSck2F7aGCiZ66aFGZrs2 \
    <host>

2.5. レジストリー設定の拡張

2.5.1. レジストリー IP アドレスの維持

OpenShift Container Platform はサービス IP アドレスによって統合レジストリーを参照します。したがって docker-registry サービスを削除し、再作成しようとする場合、古い IP アドレスを新しいサービスで再利用するように調整すると、完全に透過的な移行が可能になります。新規 IP アドレスを取得することが避けられない場合は、マスターのみを再起動してクラスターの中断を最小限に抑えられます。

アドレスの再利用
IP アドレスを再利用するには、古い docker-registry サービスの IP アドレスを削除する前に保存し、新たに割り当てられた IP アドレスを、新しい docker-registry サービスに保存されているアドレスに置き換えるように調整します。
  1. サービスの clusterIP を書き留めておきます。

    $ oc get svc/docker-registry -o yaml | grep clusterIP:
  2. サービスを削除します。

    $ oc delete svc/docker-registry dc/docker-registry
  3. レジストリーの定義を registry.yaml に作成し、<options> を、たとえば 非実稼働環境での使用 のセクションの手順 3 で使用されているものなどに置き換えます。

    $ oc adm registry <options> -o yaml > registry.yaml
  4. registry.yaml を編集し、そこで Service を検索して、clusterIP を手順 1 で書き留めたアドレスに変更します。
  5. 変更した registry.yaml を使ってレジストリーを作成します。

    $ oc create -f registry.yaml
マスターの再起動
IP アドレスを再利用できない場合、古い IP アドレスを含む プル仕様 を使った操作は失敗します。クラスターの中断を最小限に抑えるには、マスターを再起動する必要があります。
# master-restart api
# master-restart controllers

これで、古い IP アドレスを含む古いレジストリー URL がキャッシュからクリアされます。

注記

クラスター全体を再起動すると、Pod に不要なダウンタイムが発生し、実質、キャッシュのクリアが行われないので、これは推奨していません。

2.5.2. 外部レジストリーの検索一覧の設定

/etc/containers/registries.confファイルを使用して、コンテナーイメージを検索するための Docker レジストリーの一覧を作成できます。

/etc/containers/registries.conf ファイルは、レジストリーサーバーの一覧で、ユーザーが myimage:latest などのイメージの短い名前を使用してイメージをプルするときに OpenShift ContainerPlatform はこの一覧を検索する必要があります。検索の順序をカスタマイズしたり、安全なレジストリーと安全でないレジストリーを指定したり、ブロックするレジストリーリストを定義したりできます。OpenShift Container Platform は、ブロックするリストのレジストリーからプルを検索したり、許可したりしません。

たとえば、ユーザーが myimage:latest イメージをプルする必要がある場合、OpenShift Container Platform は myimage:latest が見つかるまで一覧に表示される順序でレジストリーを検索します。

レジストリー検索の一覧を指定すると、OpenShift Container Platform ユーザーがダウンロードできるイメージとテンプレートのセットをキュレートできます。これらのイメージを 1 つ以上の Docker レジストリーに配置し、レジストリーを一覧に追加して、それらのイメージをクラスター内にプルできます。

注記

レジストリーの検索一覧を使用する場合、OpenShift Container Platform は検索一覧にないレジストリーからイメージをプルしません。

レジストリーの検索一覧を設定するには、以下を実行します。

  1. /etc/containers/registries.conf ファイルを編集し、必要に応じて以下のパラメーターを追加または編集します。

    [registries.search] 1
    registries = ["reg1.example.com", "reg2.example.com"]
    
    [registries.insecure] 2
    registries = ["reg3.example.com"]
    
    [registries.block] 3
    registries = ['docker.io']
    1
    ユーザーが SSL/TLS を使用してイメージをダウンロードできるセキュアなレジストリーを指定します。
    2
    ユーザーが TLS を使用せずにイメージをダウンロードできる、セキュアではないレジストリーを指定します。
    3
    ユーザーがイメージをダウンロードできないレジストリーを指定します。

2.5.3. レジストリーホスト名の設定

内部参照と外部参照の両方でレジストリーを認識するために使用するホスト名およびポートを設定できます。これを実行すると、イメージストリームはイメージのホスト名ベースのプッシュおよびプル仕様を提供することができ、これによってイメージのコンシューマーがレジストリーのサービス IP の変更の影響を受けないようにし、イメージストリームとその参照をクラスター間で移植できる可能性があります。

クラスター内からレジストリーを参照するために使用されるホスト名を設定するには、マスター設定ファイルの imagePolicyConfig セクションで internalRegistryHostname を設定します。外部のホスト名は、同じ場所で externalRegistryHostname の値を設定することで管理されます。

イメージポリシーの設定

imagePolicyConfig:
  internalRegistryHostname: docker-registry.default.svc.cluster.local:5000
  externalRegistryHostname: docker-registry.mycompany.com

レジストリー自体は、同じ内部ホスト名の値で設定する必要があります。これは、レジストリーのデプロイメント設定で REGISTRY_OPENSHIFT_SERVER_ADDR 環境変数を設定するか、またはレジストリー設定の OpenShift セクション で値を設定することで実行できます。

注記

レジストリーで TLS を有効にしている場合、サーバー証明書にはレジストリーの参照に使用されるホスト名が含まれている必要があります。ホスト名をサーバー証明書に追加する方法については、レジストリーのセキュリティー保護 を参照してください。

2.5.4. レジストリー設定の上書き

統合レジストリーのデフォルトの設定 (デフォルトでは実行中のレジストリーコンテナーの /config.yml にあります) は、独自の カスタム設定 で上書きできます。

注記

このファイルのアップストリームの設定オプションも環境変数を使って上書きできます。ミドルウェアのセクション は、環境変数を使って上書きできるオプションがごく少数であるため例外とします。特定の設定オプションを上書きする方法についてこちら を参照してください。

レジストリー設定ファイルの直接管理を有効にし、ConfigMap を使用して更新された設定をデプロイするには、以下を実行します。

  1. レジストリーをデプロイします
  2. 必要に応じて、レジストリー設定ファイルをローカルで編集します。以下は、レジストリーにデプロイされている初期 YAML ファイルです。サポートされているオプション を確認してください。

    レジストリー設定ファイル

    version: 0.1
    log:
      level: debug
    http:
      addr: :5000
    storage:
      cache:
        blobdescriptor: inmemory
      filesystem:
        rootdirectory: /registry
      delete:
        enabled: true
    auth:
      openshift:
        realm: openshift
    middleware:
      registry:
        - name: openshift
      repository:
        - name: openshift
          options:
            acceptschema2: true
            pullthrough: true
            enforcequota: false
            projectcachettl: 1m
            blobrepositorycachettl: 10m
      storage:
        - name: openshift
    openshift:
      version: 1.0
      metrics:
        enabled: false
        secret: <secret>

  3. 各ファイルの内容を保持する ConfigMap をこのディレクトリーに作成します。

    $ oc create configmap registry-config \
        --from-file=</path/to/custom/registry/config.yml>/
  4. registry-config ConfigMap をボリュームとしてレジストリーのデプロイメント設定に追加し、カスタム設定ファイルを /etc/docker/registry/ にマウントします。

    $ oc set volume dc/docker-registry --add --type=configmap \
        --configmap-name=registry-config -m /etc/docker/registry/
  5. 以下の環境変数をレジストリーのデプロイメント設定に追加して、直前の手順の設定パスを参照するようにレジストリーを更新します。

    $ oc set env dc/docker-registry \
        REGISTRY_CONFIGURATION_PATH=/etc/docker/registry/config.yml

上記の手順は、必要な設定を行えるように繰り返し実行される場合があります。たとえば、トラブルシューティング時に、デバッグ モードに切り換えるよう設定が一時的に更新される場合があります。

既存の設定を更新するには、以下を実行します。

警告

この手順を実行すると、現在デプロイされているレジストリー設定が上書きされます。

  1. ローカルのレジストリー設定ファイル config.yml を編集します。
  2. registry-config configmap を削除します。

    $ oc delete configmap registry-config
  3. 更新された設定ファイルを参照するよう configmap を再作成します。

    $ oc create configmap registry-config\
        --from-file=</path/to/custom/registry/config.yml>/
  4. 更新された設定を読み取るためにレジストリーを再デプロイします。

    $ oc rollout latest docker-registry
ヒント

設定ファイルをソース管理リポジトリーに保持します。

2.5.5. レジストリー設定の参照

アップストリームの docker ディストリビューション ライブラリーでは、多数の設定オプションを利用できます。ただし、すべての 設定オプション がサポートされているか、または有効にされているわけではありません。このセクションは、レジストリー設定を上書きする 際の参考としてご利用ください。

注記

このファイルのアップストリームの設定オプションも環境変数を使って上書きできます。ただし、ミドルウェアのセクション は、環境変数を使って上書きすることはできません特定の設定オプションを上書きする方法についてこちら を参照してください。

2.5.5.1. Log

アップストリームのオプション はサポートされています。

以下に例を示します。

log:
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging
2.5.5.2. フック

メールフックはサポートされていません。

2.5.5.3. ストレージ

このセクションでは、サポートされているレジストリーのストレージドライバーの一覧を示します。詳細は、コンテナーイメージレジストリーのドキュメント を参照してください。

以下の一覧には、レジストリーの設定ファイルで設定する必要のあるストレージドライバーが含まれます。

レジストリーの一般的なストレージ設定オプションはサポートされています。詳細は、コンテナーイメージレジストリーのドキュメント を参照してください。

以下のストレージオプションは、ファイルシステムドライバー で設定する必要があります。

注記

サポートされている永続ストレージドライバーの詳細は、永続ストレージの設定 および 永続ストレージの例 を参照してください。

一般的なストレージ設定オプション

storage:
  delete:
    enabled: true 1
  redirect:
    disable: false
  cache:
    blobdescriptor: inmemory
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false
    readonly:
      enabled: false

1
このエントリーは、イメージのプルーニングが正常に機能するために必須です。
2.5.5.4. 認証

認証オプションは変更することができません。openshift の拡張がサポートされている唯一のオプションです。

auth:
  openshift:
    realm: openshift
2.5.5.5. ミドルウェア

リポジトリーのミドルウェアの拡張を使用して、OpenShift Container Platform やイメージプロキシーとの対話を行う OpenShift Container Platform ミドルウェアの設定を行うことができます。

middleware:
  registry:
    - name: openshift 1
  repository:
    - name: openshift 2
      options:
        acceptschema2: true 3
        pullthrough: true 4
        mirrorpullthrough: true 5
        enforcequota: false 6
        projectcachettl: 1m 7
        blobrepositorycachettl: 10m 8
  storage:
    - name: openshift 9
1 2 9
これらの入力は必須です。これらの入力によって必要なコンポーネントが読み込まれていることを確認できます。これらの値は変更しないでください。
3
レジストリーへのプッシュ時に manifest schema v2 を格納できます。詳細は、 こちら を参照してください。
4
レジストリーがリモート Blob のプロキシーとして機能できるようにします。詳細は、 こちら を参照してください。
5
レジストリーキャッシュの Blob がリモートレジストリーから提供されるようにし、その後の迅速なアクセスを可能にします。Blob の初回アクセス時にミラーリングが開始されます。このオプションは、プルスルー が無効にされている場合は機能しません。
6
ターゲットに設定されているプロジェクトで定義されているサイズ制限を超える Blob のアップロードを防止します。
7
レジストリーにキャッシュされている制限の有効期限のタイムアウト。値が小さいほど、制限の変更がレジストリーに伝播するまでの時間が短くなります。ただし、レジストリーは制限をサーバーからより頻繁に照会するため、結果としてプッシュは遅くなります。
8
Blob とリポジトリー間の記憶されている関連付けの有効期限のタイムアウト。値が高いほどルックアップが高速になり、レジストリー操作がより効率的になる可能性が高くなります。一方、アクセスできなくなったユーザーにイメージレイヤーを提供するリスクと同様にメモリー使用量も上昇します。
2.5.5.5.1. S3 ドライバー設定

使用している統合レジストリーでサポートされていない S3 リージョンを使用する必要がある場合は、regionendpoint を指定して region 検証エラーを防ぐことができます。

Amazon Simple Storage Service ストレージの使用についての詳細は、ストレージバックエンドとしての Amazon S3 を参照してください。

以下に例を示します。

version: 0.1
log:
  level: debug
http:
  addr: :5000
storage:
  cache:
    blobdescriptor: inmemory
  delete:
    enabled: true
  s3:
    accesskey: BJKMSZBRESWJQXRWMAEQ
    secretkey: 5ah5I91SNXbeoUXXDasFtadRqOdy62JzlnOW1goS
    bucket: docker.myregistry.com
    region: eu-west-3
    regionendpoint: https://s3.eu-west-3.amazonaws.com
 auth:
  openshift:
    realm: openshift
middleware:
  registry:
    - name: openshift
  repository:
    - name: openshift
  storage:
    - name: openshift
注記

region および regionendpoint フィールドの間に整合性があることを確認します。そうでない場合、統合レジストリーは開始されますが、S3 ストレージに対する読み取りまたは書き込みを行うことはできません。

また、Amazon S3 とは異なる S3 ストレージを使用する場合に、regionendpoint が役に立ちます。

2.5.5.5.2. CloudFront ミドルウェア

CloudFront ミドルウェア拡張は、CloudFront CDN ストレージプロバイダーである AWS をサポートするために追加することができます。CloudFront ミドルウェアは、イメージコンテンツの海外への配信を高速化します。Blob は世界中の複数のエッジロケーションに配信されます。クライアントは常に最小の待機時間でエッジにアクセスできます。

注記

CloudFront ミドルウェア拡張を使用できるストレージは S3 ストレージのみです。また、使用できるのは Blob が提供されている間のみです。したがって、高速化できるのは Blob のダウンロードのみで、アップロードは高速化しません。

以下は、CloudFront ミドルウェアを含む S3 ストレージドライバーの最小限の設定例です。

version: 0.1
log:
  level: debug
http:
  addr: :5000
storage:
  cache:
    blobdescriptor: inmemory
  delete:
    enabled: true
  s3: 1
    accesskey: BJKMSZBRESWJQXRWMAEQ
    secretkey: 5ah5I91SNXbeoUXXDasFtadRqOdy62JzlnOW1goS
    region: us-east-1
    bucket: docker.myregistry.com
auth:
  openshift:
    realm: openshift
middleware:
  registry:
    - name: openshift
  repository:
    - name: openshift
  storage:
    - name: cloudfront 2
      options:
        baseurl: https://jrpbyn0k5k88bi.cloudfront.net/ 3
        privatekey: /etc/docker/cloudfront-ABCEDFGHIJKLMNOPQRST.pem 4
        keypairid: ABCEDFGHIJKLMNOPQRST 5
    - name: openshift
1
S3 ストレージは、CloudFront ミドルウェアに関係なく同じ方法で設定する必要があります。
2
CloudFront ストレージミドルウェアは、OpenShift ミドルウェアより前に一覧表示される必要があります。
3
CloudFront ベースの URL。AWS マネジメントコンソールでは、これは CloudFront ディストリビューションの Domain Name として一覧表示されます。
4
AWS のプライベートキーが格納されているファイルシステムの場所。Amazon EC2 のキーペアと混同しないよう注意してください。信頼される署名者の CloudFront キーペアの作成については、AWS ドキュメント を参照してください。このファイルは、レジストリー Pod に シークレット としてマウントする必要があります。
5
Cloudfront キーペアの ID。
2.5.5.5.3. ミドルウェア設定オプションの上書き

middleware セクションは、環境変数を使って上書きできません。ただし例外がいくつかあります。以下に例を示します。

middleware:
  repository:
    - name: openshift
      options:
        acceptschema2: true 1
        pullthrough: true 2
        mirrorpullthrough: true 3
        enforcequota: false 4
        projectcachettl: 1m 5
        blobrepositorycachettl: 10m 6
1
ブール環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_ACCEPTSCHEMA2 で上書きできる設定オプション。manifest schema v2 をマニフェストの Put 要求で 受け入れる機能を有効にします。認識される値は truefalse (以下の他のすべてのブール変数に適用されます) になります。
2
ブール環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_PULLTHROUGH で上書きできる設定オプション。 リモートレジストリーのプロキシーモードを有効にします。
3
ブール環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_MIRRORPULLTHROUGH で上書きできる設定オプション。 リモート Blob が提供されている場合、レジストリーに対して Blob をローカルにミラーリングするように指示します。
4
ブール環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_ENFORCEQUOTA で上書きできる設定オプション。クォータ実施をオンまたはオフにする機能を有効にします。 デフォルトでは、クォータの実施はオフになっています。
5
環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_PROJECTCACHETTL で上書きできる設定オプション。有効な時間文字列 (例: 2m) を取ります。空白の場合は、デフォルトのタイムアウトが取得されます。ゼロ (0m) の場合、キャッシングは無効にされます。
6
環境変数 REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_BLOBREPOSITORYCACHETTL で上書きできる設定オプション。Blob と含まれているレポジトリーの関連付けについてのエビクションタイムアウトを指定します。 値のフォーマットは projectcachettl のケースと同じです。
2.5.5.5.4. イメージのプルスルー

この機能を有効にすると、Blob がローカルに存在しない限り、レジストリーは要求された Blob をリモートレジストリーから取得しようと試みます。リモートの候補は、クライアントがプルする イメージストリームの状態で保存された DockerImage エントリーから算出されます。このエントリーのすべての固有のリモートレジストリーの参照は Blob が見つかるまで繰り返し試行されます。

プルスルーは、プルされているイメージのイメージストリームタグが存在する場合にのみ発生します。たとえば、プルされているイメージが docker-registry.default.svc:5000/yourproject/yourimage:prod である場合、レジストリーは、プロジェクト yourprojectyourimage:prod という名前のイメージストリームタグを検索します。タグが見つかると、レジストリーはそのイメージストリームタグに関連付けられた dockerImageReference を使ってイメージのプルを試行します。

プルスルーを実行すると、レジストリーは、参照されているイメージストリームタグに関連付けられたプロジェクトにあるプル認証情報を使用します。また、この機能を使用すると、ユーザーは、イメージを参照しているイメージストリームタグにアクセスできる限り、アクセスに必要な認証情報を持たないレジストリーのイメージをプルすることができます。

使用しているレジストリーに、プルスルーの実行対象である外部レジストリーを信頼するのに必要な証明書があることを確認してください。証明書は Pod の /etc/pki/tls/certs ディレクトリーに配置する必要があります。証明書は 設定マップ または シークレット を使ってマウントできます。ここで、/etc/pki/tls/certs ディレクトリー全体を置き換える必要があることに注意してください。新しい証明書を組み込み、マウントするシークレットまたは設定マップのシステム証明書を置き換えます。

デフォルトでは、イメージストリームタグは Source の参照ポリシータイプを使用することに注意してください。これは、イメージストリームの参照がイメージのプル仕様に対して解決される場合、使用される仕様はイメージのソースを参照することを意味します。外部レジストリーでホストされているイメージであれば、外部レジストリーが参照され、この結果としてリソースは外部レジストリーでイメージを参照し、プルします。たとえば、この場合、registry.redhat.io/openshift3/jenkins-2-rhel7 とプルスルーは適用されません。イメージストリームを参照しているリソースが内部レジストリーを参照しているプル仕様を使用するようにするには、イメージストリームタグは Local の参照ポリシータイプを使用する必要があります。詳細は、参照ポリシー を参照してください。

この機能はデフォルトでオンになっています。ただし、設定オプション を使って無効にすることができます。

デフォルトでは、この方法で提供されるすべてのリモート Blob は、mirrorpullthrough が無効にされていない限りローカルに格納され、その後のアクセスが高速になります。ミラーリング機能の欠点はストレージの使用量が増えることにあります。

注記

ミラーリングは、クライアントが Blob を 1 バイト以上取得しようとする際に開始されます。実際に必要になる前に、特定イメージを統合レジストリーに事前にフェッチするには、以下のコマンドを実行します。

$ oc get imagestreamtag/${IS}:${TAG} -o jsonpath='{ .image.dockerImageLayers[*].name }' | \
  xargs -n1 -I {} curl -H "Range: bytes=0-1" -u user:${TOKEN} \
  http://${REGISTRY_IP}:${PORT}/v2/default/mysql/blobs/{}
注記

OpenShift Container Platform のミラーリング機能をアップストリームの レジストリーのプルスルーキャッシュ機能 と混同しないようにしてください。 これらは似ていますが、全く異なる機能です。

2.5.5.5.5. Manifest Schema v2 サポート

各イメージには、Blob を記述するマニフェスト、それを実行するための命令、および追加のメタデータがあります。マニフェストはバージョン管理されており、バージョンごとに構造やフィールドが異なります。同一イメージが複数のマニフェストバージョンで表現されます。それぞれのバージョンはそれぞれ異なるダイジェストがあります。

現在サポートされているレジストリーは manifest v2 schema 1 (schema1) と manifest v2 schema 2 (schema2) です。前者は古くなっていますが、今後もしばらくはサポートされます。

デフォルト設定は schema2 で保持されます。

各種の Docker クライアントとの互換性の問題に注意する必要があります。

  • Docker クライアントのバージョン 1.9 以前は、schema1 のみをサポートしています。このクライアントがプルまたはプッシュするマニフェストはレガシースキーマになります。
  • Docker クライアントのバージョン 1.10 は、schema1schema2 の両方をサポートしています。デフォルトでは、新しい方のスキーマをサポートする場合はこちらをレジストリーにプッシュします。

イメージを schema1 で格納するレジストリーは、常にイメージを変更せずにクライアントに返します。Schema2 は新規の Docker クライアントにのみ変更しない状態で移動します。古いクライアントの場合は、オンザフライで schema1 に変換されます。

これにより、大きな影響が想定されます。たとえば、新規 Docker クライアントでレジストリーにプッシュされたイメージは、古い Docker のダイジェストでプルすることはできません。格納されたイメージのマニフェストは schema2 であり、そのダイジェストはこのバージョンのマニフェストをプルする場合にのみ使用できるためです。

すべてのレジストリークライアントが schema2 をサポートしていることを確認できたら、そのサポートをレジストリーで有効にすることができます。特定のオプションについては、上記の ミドルウェア設定の参照 を参照してください。

2.5.5.6. OpenShift

このセクションでは、OpenShift Container Platform に特有の機能のグローバル設定について説明します。今後のリリースでは、 Middleware セクションにある openshift 関連の設定は非推奨になる予定です。

現在、このセクションではレジストリーメトリクスの収集を設定できます。

openshift:
  version: 1.0 1
  server:
    addr: docker-registry.default.svc 2
  metrics:
    enabled: false 3
    secret: <secret> 4
  requests:
    read:
      maxrunning: 10 5
      maxinqueue: 10 6
      maxwaitinqueue 2m 7
    write:
      maxrunning: 10 8
      maxinqueue: 10 9
      maxwaitinqueue 2m 10
1
このセクションの設定バージョンを指定する必須エントリー。サポートされている値は 1.0 のみです。
2
レジストリーのホスト名。マスターで設定されている値と同じ値に設定される必要があります。これは環境変数 REGISTRY_OPENSHIFT_SERVER_ADDR で上書きされる可能性があります。
3
メトリクスの収集を有効にするには true に設定します。これはブール環境変数 REGISTRY_OPENSHIFT_METRICS_ENABLED で上書きされる可能性があります。
4
クライアント要求の承認に使用されるシークレット。メトリクスのクライアントは これを Authorization ヘッダーでベアラートークンとして使用します。環境変数 REGISTRY_OPENSHIFT_METRICS_SECRET で上書きできます。
5
同時に行えるプル要求の最大数。環境変数 REGISTRY_OPENSHIFT_REQUESTS_READ_MAXRUNNING で上書きできます。ゼロは無制限を意味します。
6
キューに入れられるプル要求の最大数。環境変数 REGISTRY_OPENSHIFT_REQUESTS_READ_MAXINQUEUE で上書きできます。ゼロは無制限を意味します。
7
拒否されるまでのキューにあるプル要求の最大待機時間。環境変数 REGISTRY_OPENSHIFT_REQUESTS_READ_MAXWAITINQUEUE で上書きできます。ゼロは無制限を意味します。
8
同時に行えるプッシュ要求の最大数。環境変数 REGISTRY_OPENSHIFT_REQUESTS_WRITE_MAXRUNNING で上書きできます。ゼロは無制限を意味します。
9
キューにあるプッシュ要求の最大数。環境変数 REGISTRY_OPENSHIFT_REQUESTS_WRITE_MAXINQUEUE で上書きできます。ゼロは無制限を意味します。
10
拒否されるまでのキューにあるプッシュ要求の最大待機時間。環境変数 REGISTRY_OPENSHIFT_REQUESTS_WRITE_MAXWAITINQUEUE で上書きできます。ゼロは無制限を意味します。

使用状況の情報については レジストリーメトリクスへのアクセス を参照してください。

2.5.5.7. レポート

レポート (Reporting) はサポートされていません。

2.5.5.8. HTTP

アップストリームのオプション はサポートされています。環境変数を使って設定を変更する方法についてはこちら を参照してください。変更の必要があるのは tls セクションのみです。以下に例を示します。

http:
  addr: :5000
  tls:
    certificate: /etc/secrets/registry.crt
    key: /etc/secrets/registry.key
2.5.5.9. 通知

アップストリームのオプション はサポートされています。REST API リファレンス はより包括的な統合オプションを提供します。

以下に例を示します。

notifications:
  endpoints:
    - name: registry
      disabled: false
      url: https://url:port/path
      headers:
        Accept:
          - text/plain
      timeout: 500
      threshold: 5
      backoff: 1000
2.5.5.10. Redis

Redis はサポートされていません。

2.5.5.11. Health

アップストリームのオプション はサポートされています。レジストリーのデプロイメント設定は、 /healthz で統合されたヘルスチェックを提供します。

2.5.5.12. Proxy

プロキシー設定は有効にできません。この機能は OpenShift Container Platform リポジトリーのミドルウェア拡張pullthrough: true で提供されます。

2.5.5.13. Cache

統合レジストリーは、データをアクティブにキャッシュして、速度の遅い外部リソースに対する呼び出しの回数を減らします。キャッシュには 2 種類あります。

  1. Blob のメタデータのキャッシュに使用されるストレージキャッシュ。このキャッシュには有効期限がなく、データは明示的に削除されるまで残り続けます。
  2. アプリケーションキャッシュには、Blob とリポジトリーの関連付けが含まれます。このキャッシュ内のデータには有効期限があります。

キャッシュを完全にオフににするには設定を変更する必要があります。

version: 0.1
log:
  level: debug
http:
  addr: :5000
storage:
  cache:
    blobdescriptor: "" 1
openshift:
  version: 1.0
  cache:
    disabled: true 2
    blobrepositoryttl: 10m
1
ストレージのバックエンドでアクセスしたメタデータのキャッシュを無効にします。このキャッシュがない場合、レジストリーサーバーはメタデータのバックエンドに絶えずアクセスします。
2
Blob とリポジトリーの関連付けを含むキャッシュを無効にします。このキャッシュがない場合、レジストリーサーバーは継続的にマスター API のデータを照会し、関連付けを再計算します。

2.6. 既知の問題

2.6.1. 概要

以下は、統合レジストリーのデプロイまたは使用時の既知の問題です。

2.6.2. レジストリーのプルスルーに伴う同時ビルド

ローカルの docker-registry デプロイメントは追加の負荷を受けます。デフォルトで、ここでは registry.redhat.io からのコンテンツをキャッシュするようになりました。STI ビルドの registry.redhat.io のイメージはローカルレジストリーに保存されます。それらをプルしようとすると、ローカル docker-registry からのプルが試行され。その結果として、過剰な数の同時ビルドがプルでタイムアウトになり、ビルドが失敗する可能性のある状況になります。この問題を軽減するには、docker-registry デプロイメントを複数のレプリカにスケーリングします。Pod のログでタイムアウトの有無をチェックします。

2.6.3. 共有 NFS ボリュームとスケーリングされたレジストリーの使用時のイメージのプッシュエラー

スケーリングされたレジストリーを共有 NFS ボリュームで使用すると、イメージのプッシュ時に以下のいずれかのエラーが発生することがあります。

  • digest invalid: provided digest did not match uploaded content
  • blob upload unknown
  • blob upload invalid

これらのエラーは、Docker のイメージのプッシュの試行時に内部レジストリーサービスによって返されます。その原因は、ノード間のファイル属性の同期に起因します。NFS クライアント側のキャッシング、ネットワーク待機時間およびレイヤーサイズなどはすべて、デフォルトのラウンドロビンロードバランシング設定を使用してイメージをプッシュする際に発生するエラーの要因になる可能性があります。

このような障害の可能性を最小限に抑えるには、以下の手順を実行します。

  1. docker-registry サービスの sessionAffinityClientIP に設定されていることを確認します。

    $ oc get svc/docker-registry --template='{{.spec.sessionAffinity}}'

    これにより ClientIP が返されるはずです。ClientIP は OpenShift Container Platform の最近のバージョンのデフォルトです。 これが返されない場合は、以下のように変更してください。

    $ oc patch svc/docker-registry -p '{"spec":{"sessionAffinity": "ClientIP"}}'
  2. NFS サーバー上のレジストリーボリュームの NFS エクスポート行に no_wdelay オプションが一覧表示されていることを確認します。no_wdelay オプションは、サーバーによる書き込みの遅延を防ぎ、このレジストリーの要件である、書き込み直後の読み取りの整合性を大幅に改善します。
重要

テストにより、RHEL NFS サーバーをコンテナーイメージレジストリーのストレージバックエンドとして使用することに関する問題が検出されています。これには、OpenShift Container レジストリーおよび Quay が含まれます。そのため、コアサービスで使用される PV をサポートするために RHEL NFS サーバーを使用することは推奨されていません。

他の NFS の実装ではこれらの問題が検出されない可能性があります。OpenShift コアコンポーネントに対して実施された可能性のあるテストに関する詳細情報は、個別の NFS 実装ベンダーにお問い合わせください。

2.6.4. 内部で管理されたイメージのプルに失敗し見つかりません (not found) のエラーが表示される

このエラーは、プルされたイメージがプルしたイメージストリームとは異なるイメージストリームにプッシュされた場合に発生します。これは、ビルドされたイメージを任意のイメージストリームに再タグ付けすることによって発生します。

$ oc tag srcimagestream:latest anyproject/pullimagestream:latest

その後、以下のようなイメージ参照を使用してプルします。

internal.registry.url:5000/anyproject/pullimagestream:latest

Docker を手動でプルするときにも同様のエラーが発生します。

Error: image anyproject/pullimagestream:latest not found

このエラーを防ぐには、内部で管理されたイメージのタグ付けを完全に避けるか、またはビルドしたイメージを必要な namespace に 手動で 再プッシュします。

2.6.5. S3 ストレージでのイメージのプッシュが失敗し 500 内部サーバーエラー (500 Internal Server Error) と表示される

レジストリーが S3 ストレージのバックエンドで実行されると、問題が報告されます。コンテナーイメージレジストリーへのプッシュは、以下のエラーを出して失敗することがあります。

Received unexpected HTTP status: 500 Internal Server Error

これをデバッグするには、レジストリーのログを表示 する必要があります。ログで、プッシュの失敗時に発生した同様のエラーメッセージを探します。

time="2016-03-30T15:01:21.22287816-04:00" level=error msg="unknown error completing upload: driver.Error{DriverName:\"s3\", Enclosed:(*url.Error)(0xc20901cea0)}" http.request.method=PUT
...
time="2016-03-30T15:01:21.493067808-04:00" level=error msg="response completed with error" err.code=UNKNOWN err.detail="s3: Put https://s3.amazonaws.com/oso-tsi-docker/registry/docker/registry/v2/blobs/sha256/ab/abe5af443833d60cf672e2ac57589410dddec060ed725d3e676f1865af63d2e2/data: EOF" err.message="unknown error" http.request.method=PUT
...
time="2016-04-02T07:01:46.056520049-04:00" level=error msg="error putting into main store: s3: The request signature we calculated does not match the signature you provided. Check your key and signing method." http.request.method=PUT
atest

このようなエラーを確認した場合には、Amazon S3 サポートにお問い合わせください。お住まいの地域や特定のバケットに関連した問題がある可能性があります。

2.6.6. イメージのプルーニングの失敗

イメージのプルーニング時に以下のエラーが発生した場合:

BLOB sha256:49638d540b2b62f3b01c388e9d8134c55493b1fa659ed84e97cb59b87a6b8e6c error deleting blob

さらに、レジストリーのログ に以下の情報が含まれている場合。

error deleting blob \"sha256:49638d540b2b62f3b01c388e9d8134c55493b1fa659ed84e97cb59b87a6b8e6c\": operation unsupported

上記に該当する場合、お使いの カスタム設定ファイル には ストレージセクション に必須のエントリー、つまり true に設定された storage:delete:enabled が含まれていないことを意味します。これらを追加し、レジストリーを再デプロイして、再度イメージプルーニングの操作を行ってください。

第3章 ルーターのセットアップ

3.1. ルーターの概要

3.1.1. ルーターについて

トラフィックをクラスターに送る 方法は多数あります。最も一般的な方法として、 OpenShift Container Platform インストールで OpenShift Container Platform ルーター を、サービス 向けの外部トラフィックの ingress ポイントとして使用できます。

OpenShift Container Platform は以下のルータープラグインを提供し、サポートしています。

3.1.2. ルーターのサービスアカウント

OpenShift Container Platform クラスターをデプロイする前に、ルーターの サービスアカウント を用意しておく必要があります。これには、クラスターのインストール時に自動的に作成されます。このサービスアカウントには、ホストのポートの指定に使用できる SCC (security context constraints) へのパーミッションがあります。

3.1.2.1. ラベルにアクセスするためのパーミッション

namespace ラベルが使用されている場合 (ルーターシャードを作成している場合など)、ルーターのサービスアカウントには cluster-reader のパーミッションが必要になります。

$ oc adm policy add-cluster-role-to-user \
    cluster-reader \
    system:serviceaccount:default:router

サービスアカウントを準備したら、デフォルト HAProxy ルーターカスタマイズ HAProxy ルーター のインストールに進むことができます。

3.2. デフォルト HAProxy ルーターの使用

3.2.1. 概要

oc adm router コマンドには、新規インストールでのルーターのセットアップタスクを単純化する管理者 CLI が提供されます。oc adm router コマンドは、サービスとデプロイメント設定オブジェクトを作成します。--service-account オプションを使用して、ルーターがマスターとの通信で使用するサービスアカウントを指定します。

ルーターサービスアカウント は事前に作成するか、oc adm router --service-account コマンドで作成することができます。

OpenShift Container Platform コンポーネント間のあらゆる形式の通信は TLS によって保護され、各種の証明書や認証方法を使用します。--default-certificate .pem フォーマットファイルは提供されるか、または oc adm router コマンドで作成されます。ルート が作成されると、ユーザーはルートの処理時にルーターが使用するルート証明書を提供できるようになります。

重要

ルーターを削除する際に、デプロイ設定やサービス、およびシークレットも削除されていることを確認します。

ルーターは特定のノードにデプロイされます。これにより、クラスター管理者と外部ネットワークマネージャーはどの IP アドレスがルーターを実行し、ルーターがどのトラフィックを処理するかについて調整しやすくなります。ノードセレクター を使用してルーターを特定のノードにデプロイします。

重要

ルーターはデフォルトでホストネットワークを使用し、ホストのすべてのインターフェイスのポート 80 と 443 に直接割り当てられます。ポート 80/443 が利用できるホストにルーターを制限し、他のサービスに使用されないようにします。これは ノードセレクタースケジューラー設定 を使用して設定します。たとえば、これはルートなどのサービスの実行用として専用のインフラストラクチャーノードを設定することで実行できます。

重要

お使いのルーターで個別の openshift-router サービスアカウントを使用することをお勧めします。--service-account フラグを oc adm router コマンドで使用してこれを指定できます。

$ oc adm router --dry-run --service-account=router 1
1
--service-account は、openshift-routerサービスアカウント の名前です。
重要

oc adm router を使用して作成されるルーター Pod には、ルーター Pod がデプロイされるためにノードが満たさなければならないデフォルトのリソース要求が設定されます。デフォルトのリソース要求は、インフラストラクチャーコンポーネントの信頼性を向上させる取り組みとして、ルーター Pod の QoS 層をリソース要求を持たない Pod よりも高く設定するために使用されます。デフォルト値は、基本的なルーターがデプロイされるのに必要な最小限のリソースを表しており、ルーターデプロイメント設定で編集できます。 また、ルーターの負荷に基づいてそれらの値を引き上げることもできます。

3.2.2. ルーターの作成

ルーターが存在しない場合は、以下を実行してルーターを作成します。

$ oc adm router <router_name> --replicas=<number> --service-account=router --extended-logging=true

高可用性 の設定が作成されない限り、high availability は通常 1 になります。

--extended-logging=true は、ルーターを、 HAProxy で生成されるログを syslog コンテナーに転送するように設定します。

ルーターのホスト IP アドレスを見つけるには、以下を実行します。

$ oc get po <router-pod>  --template={{.status.hostIP}}

また、ルーターシャードを使用 して、ルーターを特定の namespace またはルートに絞り込むか、ルーターの作成後に 環境変数を設定 できます。この場合には、シャードごとにルーターを作成します。

3.2.3. その他の基本ルーターコマンド

デフォルトルーターの確認
router という名前のデフォルトのルーターサービスアカウントは、クラスターのインストール時に自動的に作成されます。このアカウントがすでに存在することを確認するには、以下を実行します。
$ oc adm router --dry-run --service-account=router
デフォルトルーターの表示
デフォルトルーターが作成されている場合でそれを確認するには、以下を実行します。
$ oc adm router --dry-run -o yaml --service-account=router
HAProxy ログを転送するためのルーター設定
HAProxy で生成されるログを syslog サイドカーコンテナーに転送するようにルーターを設定します。--extended-logging=true パラメーターは、syslog コンテナーを追加して、HAProxy ログを標準出力に転送します。
$ oc adm router --extended-logging=true

以下の例は、--extended-logging=true を使用するルーターの設定です。

$ oc get pod router-1-xhdb9 -o yaml
apiVersion: v1
kind: Pod
spec:
  containers:
  - env:

    ....

    - name: ROUTER_SYSLOG_ADDRESS 1
      value: /var/lib/rsyslog/rsyslog.sock

    ....

 - command: 2
   - /sbin/rsyslogd
   - -n
   - -i
   - /tmp/rsyslog.pid
   - -f
   - /etc/rsyslog/rsyslog.conf
   image: registry.redhat.io/openshift3/ose-haproxy-router:v3.11.188
   imagePullPolicy: IfNotPresent
   name: syslog
1
--extended-logging=true パラメーターは、ログのソケットファイルを作成します。
2
--extended-logging=true パラメーターはコンテナーをルーターに追加します。コンテナーでは、rsyslog プロセスが /sbin/rsyslogd -n -i /tmp/rsyslog.pid -f /etc/rsyslog/rsyslog.conf として実行します。

以下のコマンドを使用して HAProxy ログを表示します。

$ oc set env dc/test-router ROUTER_LOG_LEVEL=info 1
$ oc logs -f <pod-name> -c syslog 2
1
ログレベルを info または debug に設定します。デフォルトは warning です。
2
ログを表示するルーター Pod の名前を指定します。

HAProxy ログは以下の形式を使用します。

2020-04-14T03:05:36.629527+00:00 test-311-node-1 haproxy[43]: 10.0.151.166:59594 [14/Apr/2020:03:05:36.627] fe_no_sni~ be_secure:openshift-console:console/pod:console-b475748cb-t6qkq:console:10.128.0.5:8443 0/0/1/1/2 200 393 - - --NI 2/1/0/1/0 0/0 "HEAD / HTTP/1.1"
2020-04-14T03:05:36.633024+00:00 test-311-node-1 haproxy[43]: 10.0.151.166:59594 [14/Apr/2020:03:05:36.528] public_ssl be_no_sni/fe_no_sni 95/1/104 2793 -- 1/1/0/0/0 0/0
ラベル付けされたノードへのルーターのデプロイ
指定された ノードラベル に一致するノードにルーターをデプロイするには、以下を実行します。
$ oc adm router <router_name> --replicas=<number> --selector=<label> \
    --service-account=router

たとえば、router という名前のルーターを作成し、それを node-role.kubernetes.io/infra=true とラベルが付けられたノードに配置するには、以下を実行します。

$ oc adm router router --replicas=1 --selector='node-role.kubernetes.io/infra=true' \
  --service-account=router

クラスターのインストール時に、openshift_router_selector および openshift_registry_selector の Ansible 設定はデフォルトで node-role.kubernetes.io/infra=true に設定されます。デフォルトのルーターおよびレジストリーは、node-role.kubernetes.io/infra=true ラベルに一致するノードがある場合にのみ自動的にデプロイされます。

ラベルの更新に関する情報については、ノードのラベルの更新 を参照してください。

複数のインスタンスが スケジューラーポリシー に従って複数の異なるホストに作成されます。

複数の異なるルーターイメージの使用
複数の異なるルーターイメージを使用し、使用されるルーター設定を表示するには、以下を実行します。
$ oc adm router <router_name> -o <format> --images=<image> \
    --service-account=router

以下に例を示します。

$ oc adm router region-west -o yaml --images=myrepo/somerouter:mytag \
    --service-account=router

3.2.4. ルートを特定のルーターに絞り込む

ROUTE_LABELS 環境変数を使用してルートを絞り込むことで、特定のルーターによってのみ使用されるようできます。

たとえば、複数のルーターと 100 のルートがある場合、ラベルをルートに割り当てることで、それらの一部を 1 つのルーターで処理し、残りを別のルーターで処理するようにできます。

  1. ルーターの作成 後に、ROUTE_LABELS 環境変数を使用してルーターにタグ付けします。

    $ oc set env dc/<router=name>  ROUTE_LABELS="key=value"
  2. ラベルを必要なルートに追加します。

    oc label route <route=name> key=value
  3. ラベルがルートに割り当てられていることを確認するには、ルートの設定をチェックします。

    $ oc describe route/<route_name>
同時接続の最大数の設定
ルーターはデフォルトで最大 20000 の接続を処理できるようになっています。この上限は必要に応じて変更できます。接続が少なすぎると、ヘルスチェックが機能せず、不必要な再起動が実行されます。システムをこの接続の最大数に対応するように設定する必要があります。'sysctl fs.nr_open''sysctl fs.file-max' に示される上限は十分に大きな値である必要があります。そうでない場合には HAproxy は起動しません。

ルーターを作成したら、--max-connections= オプションで必要な上限を設定します。

$ oc adm router --max-connections=10000   ....

ルーターのデプロイメント設定で ROUTER_MAX_CONNECTIONS 環境変数を編集し、値を変更します。ルーター Pod は新しい値で再起動されます。ROUTER_MAX_CONNECTIONS が存在しない場合は、デフォルト値の 20000 が使用されます。

注記

接続にはフロントエンドおよび内部バックエンドが含まれます。これは 2 つの接続としてカウントされます。必ず ROUTER_MAX_CONNECTIONS の値を作成しようとしている接続数の 2 倍以上になるように設定してください。

3.2.5. HAProxy Strict SNI

HAProxy strict-sni は、ルーターのデプロイメント設定の ROUTER_STRICT_SNI 環境変数によって管理できます。また、これは --strict-sni コマンドラインオプションを使用してルーターを作成する時にも設定できます。

$ oc adm router --strict-sni

3.2.6. TLS 暗号化スイート

ルーターの作成時に --ciphers オプションを使用して、ルーターの 暗号化スイート を設定します。

$ oc adm router --ciphers=modern   ....

値は modernintermediate、または old で、デフォルトは intermediate です。または、":" 区切りで暗号化を指定することも可能です。暗号化は、以下のコマンドで表示されたセットの中から選択する必要があります。

$ openssl ciphers

また、既存のルーターには ROUTER_CIPHERS 環境変数を使用します。

3.2.7. 相互 TLS 認証

ルーターおよびバックエンドサービスへのクライアントアクセスは、手動の TLS 認証を使用して制限できます。ルーターは、その authenticated セットではなくクライアントからの要求を拒否します。相互 TLS 認証はクライアント証明書で実装でき、証明書を発行する認証局 (CA)、証明書失効一覧および/または証明書件名フィルターに基づいて制御できます。ルーターの作成時に相互 TLS 設定オプションの --mutual-tls-auth--mutual-tls-auth-ca--mutual-tls-auth-crl および --mutual-tls-auth-filter を使用します。

$ oc adm router --mutual-tls-auth=required  \
                --mutual-tls-auth-ca=/local/path/to/cacerts.pem   ....

--mutual-tls-auth の値は requiredoptional、または none であり、none はデフォルトになります。--mutual-tls-auth-ca 値は 1 つ以上の CA 証明書を含むファイルを指定します。これらの CA 証明書はクライアントの証明書を検証するためにルーターによって使用されます。

--mutual-tls-auth-crl は、(有効な認証局が発行する) 証明書が取り消されているケースを処理するために証明書失効一覧を指定するために使用できます。

$ oc adm router --mutual-tls-auth=required  \
     --mutual-tls-auth-ca=/local/path/to/cacerts.pem  \
     --mutual-tls-auth-filter='^/CN=my.org/ST=CA/C=US/O=Security/OU=OSE$'  \
     ....

--mutual-tls-auth-filter 値は、証明書件名に基づくきめ細やかなアクセス制御に使用できます。この値は、証明書の件名に一致させるために使用される正規表現です。

注記

上記の相互 TLS 認証フィルターの例では、^ および $  のアンカーが使用された制限的な正規表現 (regex) を示しており、これは証明書件名に 完全に 一致します。制限的な正規表現を使用することにした場合、有効とみなされるすべての CA によって発行された証明書に一致する可能性があることに留意してください。発行された証明書に対してよりきめ細やかな制御を行えるように --mutual-tls-auth-ca オプションを使用することも推奨されています。

--mutual-tls-auth=required を使用することにより、バックエンドリソースへのアクセスを認証されたクライアント のみ に許可することができます。これは、クライアントが常に認証情報 (またはクライアント証明書) を提供するために 必要である ことを意味します。相互 TLS 認証を Optional (オプション) にするには、--mutual-tls-auth=optional を使用 (または、デフォルトの none を使用) してこれを無効にします。ここで、optional とは、クライアントに認証情報の提示を要求する必要が ない ことを意味し、クライアントが認証情報を提供する場合は、その情報は X-SSL* HTTP ヘッダーでバックエンドに渡されることを意味します。

$ oc adm router --mutual-tls-auth=optional  \
     --mutual-tls-auth-ca=/local/path/to/cacerts.pem  \
     ....

相互 TLS 認証サポートが有効にされる場合 (--mutual-tls-auth フラグに required または optional 値のいずれかを使用)、クライアント認証情報は X-SSL* HTTP ヘッダーの形式でバックエンドに渡されます。

X-SSL* HTTP ヘッダー X-SSL-Client-DN の例: 証明書の件名の完全な識別名 (DN)。X-SSL-Client-NotBefore: YYMMDDhhmmss[Z] 形式のクライアント証明書の開始日。X-SSL-Client-NotAfter: YYMMDDhhmmss[Z] 形式のクライアント証明書の開始日。X-SSL-Client-SHA1: クライアント証明書の SHA-1 フィンガープリント。X-SSL-Client-DER: クライアント証明書への完全なアクセスを提供します。base-64 形式でエンコードされた DER フォーマットのクライアント証明書が含まれます。

3.2.8. 高可用性ルーター

IP フェイルオーバーを使用して OpenShift Container Platform クラスターで 高可用性ルーターをセットアップ できます。このセットアップには複数の異なるノードの複数のレプリカが含まれるため、フェイルオーバーソフトウェアは現在のレプリカが失敗したら別のレプリカに切り替えることができます。

3.2.9. ルーターサービスポートのカスタマイズ

環境変数の ROUTER_SERVICE_HTTP_PORTROUTER_SERVICE_HTTPS_PORT を設定することで、テンプレートルーターがバインドするサービスポートをカスタマイズできます。これは、テンプレートルーターを作成し、そのデプロイメント設定を編集することで実行できます。

以下の例では、0 レプリカのルーターデプロイメントを作成し、ルーターサービス HTTP と HTTPS ポートをカスタマイズし、これを適切に (1 レプリカに) スケーリングしています。

$ oc adm router --replicas=0 --ports='10080:10080,10443:10443' 1
$ oc set env dc/router ROUTER_SERVICE_HTTP_PORT=10080  \
                   ROUTER_SERVICE_HTTPS_PORT=10443
$ oc scale dc/router --replicas=1
1
公開されるポートがコンテナーネットワークモード --host-network=false を使用するルーターに対して適切に設定されていることを確認します。
重要

テンプレートルーターサービスポートをカスタマイズする場合は、ルーター Pod が実行されるノードのファイアウォールでカスタムポートが開いているようにする必要があります (Ansible または iptables のいずれか、または firewall-cmd で使用するその他のカスタム方法を使用します)。

以下は、カスタムルーターサービスポートを開くために iptables を使用した例です。

$ iptables -A OS_FIREWALL_ALLOW -p tcp --dport 10080 -j ACCEPT
$ iptables -A OS_FIREWALL_ALLOW -p tcp --dport 10443 -j ACCEPT

3.2.10. 複数ルーターの使用

管理者は同じ定義を使用して複数のルーターを作成し、同じルートのセットを提供することができます。各ルーターは複数の異なる ノード に置かれ、異なる IP アドレスを持ちます。ネットワーク管理者は、各ノードに必要なトラフィックを送る必要があります。

複数のルーターをグループ化して、クラスター内や複数テナントでのルーティングの負荷を別のルーターまたは シャード に分散することができます。グループの各ルーターまたはシャードは、ルーターのセレクターに基づいてルートを許可します。管理者は ROUTE_LABELS を使用してクラスター全体でシャードを作成できます。ユーザーは NAMESPACE_LABELS を使用して namespace (プロジェクト) でシャードを作成できます。

3.2.11. デプロイメント設定へのノードセレクターの追加

特定のルーターを特定のノードにデプロイするには、2 つの手順を実行する必要があります。

  1. ラベル を必要なノードに追加します。

    $ oc label node 10.254.254.28 "router=first"
  2. ノードセレクターをルーターのデプロイメント設定に追加します。

    $ oc edit dc <deploymentConfigName>

    template.spec.nodeSelector フィールドに、ラベルに対応するキーと値を追加します。

    ...
      template:
        metadata:
          creationTimestamp: null
          labels:
            router: router1
        spec:
          nodeSelector:      1
            router: "first"
    ...
    1
    router=first ラベルに対応するキーと値はそれぞれ routerfirst になります。

3.2.12. ルーターシャードの使用

ルーターのシャード化 により、NAMESPACE_LABELSROUTE_LABELS を使用してルーターの namespace とルートの絞り込みが実行されます。これにより、複数のルーターデプロイメントでルートのサブセットを分散させることができます。重複しないサブセットを使用することにより、ルートセットのパーティション設定を効果的に行うことができます。または、重複するルートのサブセットを設定する複数のシャードを定義することもできます。

デフォルトで、ルーターはすべての プロジェクト (namespace) からすべてのルートを選択します。シャード化によってラベルがルートまたはルーターの namespace およびラベルセレクターに追加されます。各ルーターシャードは特定のラベルのセットで選択されるルーターを設定するか、または特定のラベルセレクターで選択される namespace に属します。

注記

ルーターサービスアカウントには [cluster reader] パーミッションセットを設定し、他の namespace のラベルにアクセスできるようにする必要があります。

ルーターのシャード化および DNS

外部 DNS サーバーは要求を必要なシャードにルートするために必要となるので、管理者はプロジェクトの各ルーターに個別の DNS エントリーを作成する必要があります。ルーターは不明なルートを別のルーターに転送することはありません。

以下の例を考慮してください。

  • Router A はホスト 192.168.0.5 にあり、*.foo.com のルートを持つ。
  • Router B はホスト 192.168.1.9 にあり、*.example.com のルートを持つ。

各 DNS エントリーは *.foo.com を Router A をホストするノードに解決し、*.example.com を Router B をホストするノードに解決する必要があります。

  • *.foo.com A IN 192.168.0.5
  • *.example.com A IN 192.168.1.9

ルーターのシャード化の例

このセクションでは、namespace およびルートラベルを使用するルーターのシャード化について説明します。

図3.1 namespace ラベルに基づくルーターのシャード化

Router Sharding Based on Namespace Labels
  1. namespace ラベルセレクターでルーターを設定します。

    $ oc set env dc/router NAMESPACE_LABELS="router=r1"
  2. ルーターには namespace にセレクターがあるため、ルーターは一致する namespace のルートのみを処理します。このセレクターが namespace に一致させるようにするには、namespace に適宜ラベルを付けます。

    $ oc label namespace default "router=r1"
  3. ルートをデフォルトの namespace に作成すると、ルートはデフォルトのルーターで利用できるようになります。

    $ oc create -f route1.yaml
  4. 新規プロジェクト (namespace) を作成し、route2 というルートを作成します。

    $ oc new-project p1
    $ oc create -f route2.yaml

    ルートがルーターで利用できないことを確認します。

  5. namespace p1router=r1 のラベルを付けます。

    $ oc label namespace p1 "router=r1"

このラベルを追加すると、ルートはルーターで利用できるようになります。

ルーターのデプロイメント finops-router はルートセレクター NAMESPACE_LABELS="name in (finance, ops)" を使用して実行され、ルーターのデプロイメント dev-router はラベルセレクター NAMESPACE_LABELS="name=dev" を使用して設定されます。

すべてのルートが name=financename=ops、および name=dev というラベルの付けられた namespace にない場合、この設定により、2 つのルーターのデプロイメント間でルートが効果的に分散されます。

上記のシナリオでは、シャード化は重複するセットを持たないパーティション設定の特別なケースとなります。ルートは複数のルーターシャード間で分割されます。

ルート選択の基準によって、ルートの分散方法が決まります。複数のルーターデプロイメントに重複するルートのサブセットを設定することも可能です。

上記の例では finops-routerdev-router のほかに devops-router があり、これはラベルセレクター NAMESPACE_LABELS="name in (dev, ops)" を使用して設定されます。

name=dev または name=ops というラベルが付けられた namespace のルートは 2 つの異なるルーターデプロイメントによって提供されるようになりました。これは、namespace ラベルに基づくルーターのシャード化 の手順で説明されているように、ルートの重複するサブセットを定義するケースです。

また、これによりさらに複雑なルーティングルールを作成し、優先度の高いトラフィックを専用の finops-router に転送し、優先度の低いトラフィックは devops-router に送信できます。

ルートラベルに基づくルーターのシャード化

NAMESPACE_LABELS によって、提供するプロジェクトをフィルターでき、それらのプロジェクトからすべてのルートを選択できますが、ルートはルート自体に関連する他の基準に基づいてパーティション設定する必要がある場合があります。ROUTE_LABELS セレクターを使用すると、ルート自体を細かくフィルターできます。

ルーターデプロイメント prod-router はルートセレクター ROUTE_LABELS="mydeployment=prod" を使用して設定され、ルーターデプロイメント devtest-router はラベルセレクター ROUTE_LABELS="mydeployment in (dev, test)" を使用して設定されます。

この設定は、namespace の種類を問わず、ルートのラベルに基づいて 2 つのルーターデプロイメント間のルートのパーティション設定を行います。

この例では、提供されるルートすべてがラベル "mydeployment=<tag>" でタグ付けされていることを想定しています。

3.2.12.1. ルーターシャードの作成

このセクションでは、ルーターシャードのさらに詳細な例を示します。さまざまなラベルを持つ a — z という 26 のルートがあることを想定してください。

ルートで使用可能なラベル

sla=high       geo=east     hw=modest     dept=finance
sla=medium     geo=west     hw=strong     dept=dev
sla=low                                   dept=ops

これらのラベルは、サービスレベルアグリーメント、地理的な場所、ハードウェア要件、部門などの概念を表しています。ルートは各列のラベルを最大 1 つ持つことができます。ルートによっては他のラベルを持つことことも、ラベルをまったく持たないこともあります。

名前SLAGeo (地理的な場所)HWDept (部門)その他のラベル

a

high

east

modest

finance

type=static

b

 

west

strong

 

type=dynamic

c, d, e

low

 

modest

 

type=static

g — k

medium

 

strong

dev

 

l — s

high

 

modest

ops

 

t — z

 

west

  

type=dynamic

これは oc adm routeroc set env および oc scale がどのように連携してルーターシャードを作成するかを表している便利なスクリプト mkshard です。

#!/bin/bash
# Usage: mkshard ID SELECTION-EXPRESSION
id=$1
sel="$2"
router=router-shard-$id           1
oc adm router $router --replicas=0  2
dc=dc/router-shard-$id            3
oc set env   $dc ROUTE_LABELS="$sel"  4
oc scale $dc --replicas=3         5
1
作成されたルーターは router-shard-<id> という名前を持ちます。
2
ここではスケーリングを指定しません。
3
ルーターのデプロイメント設定。
4
oc set env を使用して選択式を設定します。選択式は環境変数 ROUTE_LABELS の値です。
5
拡張します。

mkshard を複数回実行して、複数のルーターを作成します。

ルーター選択式ルート

router-shard-1

sla=high

a, l — s

router-shard-2

geo=west

b, t — z

router-shard-3

dept=dev

g — k

3.2.12.2. ルーターシャードの変更

ルーターシャードは ラベルに基づいた 設定なので、(oc label を使用して) ラベルまたは (oc set env を使用して) 選択式のいずれかを変更できます。

このセクションでは ルーターシャードの作成 セクションで扱った例をさらに詳細に取り上げ、選択式の変更方法を示します。

これは、新規の選択式を使用できるよう既存のルーターを変更する便利なスクリプト modshard です。

#!/bin/bash
# Usage: modshard ID SELECTION-EXPRESSION...
id=$1
shift
router=router-shard-$id       1
dc=dc/$router                 2
oc scale $dc --replicas=0     3
oc set env   $dc "$@"             4
oc scale $dc --replicas=3     5
1
変更後のルーターの名前は router-shard-<id> になります。
2
変更が発生するデプロイメント設定です。
3
縮小します。
4
oc set env を使用して新しい選択式を設定します。ルーターシャードの作成 セクションの mkshard とは異なり、modshardID 以外の引数として指定される選択式には環境変数名とその値が含まれている必要があります。
5
拡大して元に戻します。
注記

modshard では、 router-shard-<id>デプロイメントストラテジーRolling の場合、oc scale コマンドは不要です。

たとえば router-shard-3 の部門を拡張して opsdev を含めるには、以下を実行します。

$ modshard 3 ROUTE_LABELS='dept in (dev, ops)'

結果として、router-shard-3 はルート g — s (g — kl — s の組み合わせ) を選択します。

この例ではシャードから除外する 1 つの部門を指定します。 このシナリオ例では 3 つの部門しかないため、これによって前述の例と同じ結果が得られます。

$ modshard 3 ROUTE_LABELS='dept != finance'

この例は 3 つのコンマで区切られた属性を指定しており、結果としてルート b のみが選択されます。

$ modshard 3 ROUTE_LABELS='hw=strong,type=dynamic,geo=west'

ルートのラベルを使用する ROUTE_LABELS と同様に、NAMESPACE_LABELS 環境変数を使用して、ルートはルートの namespace ラベルのラベルに基づいて選択できます。この例では、ラベル frequency=weekly を持つルートの namespace を提供するように router-shard-3 を変更します。

$ modshard 3 NAMESPACE_LABELS='frequency=weekly'

最後の例は ROUTE_LABELSNAMESPACE_LABELS を組み合わせて、ラベル sla=low を持ち、ラベル frequency=weekly を持つ namespace のルート選択します。

$ modshard 3 \
    NAMESPACE_LABELS='frequency=weekly' \
    ROUTE_LABELS='sla=low'

3.2.13. ルーターのホスト名の検索

サービスを公開する際に、ユーザーは外部ユーザーがアプリケーションにアクセスするために使用する DNS 名からの同じルートを使用できます。外部ネットワークのネットワーク管理者は、ホスト名がルートを許可したルーター名に解決することを確認する必要があります。ユーザーはこのホスト名を指す CNAME を使用して DNS をセットアップできます。ただし、ルーターのホスト名が不明な場合があります。不明な場合は、クラスター管理者は指定できます。

クラスター管理者は、--router-canonical-hostname オプションをルーター作成時のルーターの正規ホスト名で使用できます。以下に例を示します。

# oc adm router myrouter --router-canonical-hostname="rtr.example.com"

これは、ルーターのホスト名を含む ROUTER_CANONICAL_HOSTNAME 環境変数をルーターのデプロイメント設定に作成します。

すでに存在しているルーターの場合、クラスター管理者はルーターのデプロイメント設定を編集し、ROUTER_CANONICAL_HOSTNAME 環境変数を追加します。

spec:
  template:
    spec:
      containers:
        - env:
          - name: ROUTER_CANONICAL_HOSTNAME
            value: rtr.example.com

ROUTER_CANONICAL_HOSTNAME 値は、ルートを許可したすべてのルーターのルートステータスに表示されます。ルートステータスはルーターがリロードされるたびに更新されます。

ユーザーがルートを作成すると、すべてのアクティブなルーターはそのルートを評価し、条件を満たしていればそのルートを許可します。ROUTER_CANONICAL_HOSTNAME 環境変数を定義するルーターがルートを許可すると、ルーターはルートステータスの routerCanonicalHostname フィールドに値を入力します。ユーザーはルートステータスを検証して、どのルーターがルートを許可したかを確認でき、ルーターを一覧から選択し、ネットワーク管理者に渡すルーターのホスト名を見つけることができます (該当する場合)。

status:
  ingress:
    conditions:
      lastTransitionTime: 2016-12-07T15:20:57Z
      status: "True"
      type: Admitted
      host: hello.in.mycloud.com
      routerCanonicalHostname: rtr.example.com
      routerName: myrouter
      wildcardPolicy: None

oc describe にはホスト名が含まれます (利用可能な場合)。

$ oc describe route/hello-route3
...
Requested Host: hello.in.mycloud.com exposed on router myroute (host rtr.example.com) 12 minutes ago

上記の情報を使用して、ユーザーは DNS 管理者に対し、ルートのホスト hello.in.mycloud.com から CNAME をルーターの正規ホスト名 rtr.example.com に応じてセットアップするよう依頼できます。この結果として、hello.in.mycloud.com へのトラフィックがユーザーのアプリケーションに到達するようになります。

3.2.14. デフォルトのルーティングサブドメインのカスタマイズ

マスター設定ファイル (デフォルトでは /etc/origin/master/master-config.yaml ファイル) を変更することで、お使いの環境のデフォルトルーティングサブドメインとして使用される接尾辞をカスタマイズできます。ホスト名を指定しないルートの場合、このデフォルトのルーティングサブドメインを使用してホスト名が生成されます。

以下の例は、設定された接尾辞を v3.openshift.test に設定する方法を示しています。

routingConfig:
  subdomain: v3.openshift.test
注記

この変更には、マスターを実行している場合は再起動が必要となります。

OpenShift Container Platform マスターが上記の設定を実行している場合、 namespace の mynamespace に追加されるホスト名を持たない no-route-hostname というルートの例では、生成されるホスト名は以下のようになります。

no-route-hostname-mynamespace.v3.openshift.test

3.2.15. カスタムルーティングサブドメインへのルートホスト名の強制

管理者がすべてのルートを特定のルーティングサブドメインに限定する場合、--force-subdomain オプションを oc adm router コマンドに渡すことができます。これはルートで指定されたホスト名を上書きし、--force-subdomain オプションに提供されるテンプレートに基づいてホスト名を生成するようルーターに強制します。

以下の例ではルーターを実行し、カスタムサブドメインテンプレート ${name}-${namespace}.apps.example.com を使用してルートホスト名を上書きしています。

$ oc adm router --force-subdomain='${name}-${namespace}.apps.example.com'

3.2.16. ワイルドカード証明書の使用

証明書を含まない TLS 対応のルートはルーターのデフォルト証明書を代わりに使用します。ほとんどの場合、この証明書は信頼された認証局から提供されますが、利便性を考慮して OpenShift Container Platform CA を使用して証明書を作成することができます。以下に例を示します。

$ CA=/etc/origin/master
$ oc adm ca create-server-cert --signer-cert=$CA/ca.crt \
      --signer-key=$CA/ca.key --signer-serial=$CA/ca.serial.txt \
      --hostnames='*.cloudapps.example.com' \
      --cert=cloudapps.crt --key=cloudapps.key
注記

oc adm ca create-server-cert コマンドは、2 年間有効な証明書を生成します。この期間は --expire-days オプションを使って変更することができますが、セキュリティー上の理由から、値をこれより大きくすることは推奨されません。

Ansible ホストインベントリーファイル (デフォルトで /etc/ansible/hosts) に最初に一覧表示されているマスターから oc adm コマンドを実行します。

ルーターは、証明書とキーが単一ファイルに PEM 形式で入力されていると予想します。

$ cat cloudapps.crt cloudapps.key $CA/ca.crt > cloudapps.router.pem

ここで --default-cert フラグを使用できます。

$ oc adm router --default-cert=cloudapps.router.pem --service-account=router
注記

ブラウザーは、ワイルドカードを 1 つ深いレベルのサブドメインに有効であると見なします。この例では、証明書は a.cloudapps.example.com に対して有効ですが、a.b.cloudapps.example.com には有効ではありません。

3.2.17. 証明書を手動で再デプロイする

ルーター証明書を手動で再デプロイするには、以下を実行します。

  1. デフォルトのルーター証明書を含むシークレットがルーターに追加されているかどうかを確認します。

    $ oc set volume dc/router
    
    deploymentconfigs/router
      secret/router-certs as server-certificate
        mounted at /etc/pki/tls/private

    証明書が追加されている場合は、以下の手順を省略してシークレットを上書きします。

  2. デフォルト証明書ディレクトリーが以下の変数 DEFAULT_CERTIFICATE_DIR に設定されていることを確認します。

    $ oc set env dc/router --list
    
    DEFAULT_CERTIFICATE_DIR=/etc/pki/tls/private

    設定されていない場合は、以下のコマンドを使用してディレクトリーを作成します。

    $ oc set env dc/router DEFAULT_CERTIFICATE_DIR=/etc/pki/tls/private
  3. 証明書を PEM 形式にエクスポートします。

    $ cat custom-router.key custom-router.crt custom-ca.crt > custom-router.crt
  4. ルーター証明書シークレットを上書きするか、またはこれを作成します。

    証明書シークレットがルーターに追加されている場合は、シークレットを上書きします。追加されていなければ、新規シークレットを作成します。

    シークレットを上書きするには、以下のコマンドを実行します。

    $ oc create secret generic router-certs --from-file=tls.crt=custom-router.crt --from-file=tls.key=custom-router.key --type=kubernetes.io/tls -o json --dry-run | oc replace -f -

    新規シークレットを作成するには、以下のコマンドを実行します。

    $ oc create secret generic router-certs --from-file=tls.crt=custom-router.crt --from-file=tls.key=custom-router.key --type=kubernetes.io/tls
    
    $ oc set volume dc/router --add --mount-path=/etc/pki/tls/private --secret-name='router-certs' --name router-certs
  5. ルーターをデプロイします。

    $ oc rollout latest dc/router

3.2.18. セキュリティー保護されたルートの使用

現時点で、パスワードで保護されたキーファイルはサポートされていません。HAProxy は開始時にパスワードを求めるプロンプトを出しますが、このプロセスを自動化する方法はありません。キーファイルからパスフレーズを削除するために、以下を実行できます。

# openssl rsa -in <passwordProtectedKey.key> -out <new.key>

以下の例は、トラフィックが宛先にプロキシー処理される前に TLS 終端がルーターで生じる場合にセキュアな edge termination ルートを使用する方法を示しています。セキュアな edge termination ルートは TLS 証明書とキー情報を指定します。TLS 証明書は、ルーターのフロントエンドで提供されます。

最初にルーターインスタンスを起動します。

# oc adm router --replicas=1 --service-account=router

次に、セキュアな edge ルートのプライベートキー、CSR、証明書を作成します。この手順はお使いの認証局やプロバイダーによって異なります。www.example.test というドメインの単純な自己署名証明書の場合は、以下の例を参照してください。

# sudo openssl genrsa -out example-test.key 2048
#
# sudo openssl req -new -key example-test.key -out example-test.csr  \
  -subj "/C=US/ST=CA/L=Mountain View/O=OS3/OU=Eng/CN=www.example.test"
#
# sudo openssl x509 -req -days 366 -in example-test.csr  \
      -signkey example-test.key -out example-test.crt

上記の証明書とキーを使用してルートを生成します。

$ oc create route edge --service=my-service \
    --hostname=www.example.test \
    --key=example-test.key --cert=example-test.crt
route "my-service" created

その定義を確認します。

$ oc get route/my-service -o yaml
apiVersion: v1
kind: Route
metadata:
  name:  my-service
spec:
  host: www.example.test
  to:
    kind: Service
    name: my-service
  tls:
    termination: edge
    key: |
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

www.example.test の DNS エントリーがルーターインスタンスを指し、ドメインへのルートが利用できることを確認します。以下の例では、Curl をローカルリゾルバーと共に使用して DNS ルックアップのシミュレーションを行っています。

# routerip="4.1.1.1"  #  replace with IP address of one of your router instances.
# curl -k --resolve www.example.test:443:$routerip https://www.example.test/

3.2.19. (サブドメインの) ワイルドカードルートの使用

HAProxy ルーターはワイルドカードルートをサポートしており、ROUTER_ALLOW_WILDCARD_ROUTES 環境変数を true に設定することでこれを有効にできます。ルーター許可のチェックをパスする Subdomain のワイルドカードポリシーを持つすべてのルートは HAProxy ルーターによって提供されます。次に、HAProxy ルーターはルートのワイルドカードポリシーに基づいて (ルートの) 関連サービスを公開します。

重要

ルートのワイルドカードポリシーを変更するには、ルートを削除してから更新されたワイルドカードポリシーでこれを再作成する必要があります。ルートの .yaml ファイルでルートのワイルドカードポリシーのみを編集しても機能しません。

$ oc adm router --replicas=0 ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true
$ oc scale dc/router --replicas=1

Web コンソールでワイルドカードルートを設定する方法についてはこちら を参照してください。

セキュアなワイルドカード edge termination ルートの使用

以下の例では、トラフィックが宛先にプロキシー処理される前にルーターで生じる TLS 終端を反映しています。サブドメイン example.org (*.example.org) のホストに送られるトラフィックは公開されるサービスにプロキシーされます。

セキュアな edge termination ルートは TLS 証明書とキー情報を指定します。TLS 証明書は、サブドメイン (*.example.org) に一致するすべてのホストのルーターのフロントエンドによって提供されます。

  1. ルーターインスタンスを起動します。

    $ oc adm router --replicas=0 --service-account=router
    $ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true
    $ oc scale dc/router --replicas=1
  2. セキュリティー保護された edge ルートについてのプライベートキー、証明書署名要求 (CSR) および証明書を作成します。

    この手順はお使いの認証局やプロバイダーによって異なります。*.example.test というドメインの単純な自己署名証明書の場合は、以下の例を参照してください。

    # sudo openssl genrsa -out example-test.key 2048
    #
    # sudo openssl req -new -key example-test.key -out example-test.csr  \
      -subj "/C=US/ST=CA/L=Mountain View/O=OS3/OU=Eng/CN=*.example.test"
    #
    # sudo openssl x509 -req -days 366 -in example-test.csr  \
          -signkey example-test.key -out example-test.crt
  3. 上記の証明書とキーを使用してワイルドカードのルートを生成します。

    $ cat > route.yaml  <<REOF
    apiVersion: v1
    kind: Route
    metadata:
      name:  my-service
    spec:
      host: www.example.test
      wildcardPolicy: Subdomain
      to:
        kind: Service
        name: my-service
      tls:
        termination: edge
        key: "$(perl -pe 's/\n/\\n/' example-test.key)"
        certificate: "$(perl -pe 's/\n/\\n/' example-test.cert)"
    REOF
    $ oc create -f route.yaml

    *.example.test の DNS エントリーがお使いのルーターインスタンスを指し、ドメインへのルートが利用できることを確認します。

    この例では curl をローカルリゾルバーと共に使用し、DNS ルックアップのシミュレーションを行います。

    # routerip="4.1.1.1"  #  replace with IP address of one of your router instances.
    # curl -k --resolve www.example.test:443:$routerip https://www.example.test/
    # curl -k --resolve abc.example.test:443:$routerip https://abc.example.test/
    # curl -k --resolve anyname.example.test:443:$routerip https://anyname.example.test/

ワイルドカードルートを許可しているルーター (ROUTER_ALLOW_WILDCARD_ROUTEStrue に設定する) の場合、ワイルドカードルートに関連付けられたサブドメインの所有権についてのいくつかの注意点があります。

ワイルドカードルートの設定前に、所有権は、最も古いルートを持つ namespace のホスト名についての要求に基づいて設定されました (これはその他の要求を行うルートよりも優先されました)。たとえば、ルート r1 がルート r2 より古い場合、one.example.test の要求を持つ namespace ns1 のルート r1 は同じホスト名 one.example.test について namespace ns2 のルート ns2 よりも優先されます。

さらに、他の namespace のルートは重複しないホスト名を要求することを許可されていました。たとえば、namespace ns1 のルート ronewww.example.test を要求でき、namespace d2 の別のルート rtwoc3po.example.test を要求できました。

これは、同じサブドメイン (上記の例では example.test) を要求するワイルドカードルートがない場合には同様になります。

ただし、ワイルドカードルートはサブドメイン内のホスト名 ( \*.example.test 形式のホスト名) をすべて要求する必要があります。ワイルドカードルートの要求は、そのサブドメイン (example.test) の最も古いルートがワイルドカードルートと同じ namespace 内にあるかどうかによって許可または拒否されます。最も古いルートは通常のルートまたはワイルドカードルートのいずれかになります。

たとえば、ホスト owner.example.test を要求する 最も古い ルートが namespace ns1 にすでに存在し、後からそのサブドメイン (example.test) のルートを要求する新規のワイルドカードルート wildthing が追加される場合、そのワイルドカードルートによる要求は、そのルートが所有ルートと同じ namespace (ns1) にある場合にのみ許可されます。

以下の例では、ワイルドカードルートの要求が成功する場合と失敗する場合のさまざまなシナリオを示しています。

以下の例では、ワイルドカードルートを許可するルーターは、ワイルドカードルートがサブドメインを要求していない限り、サブドメイン example.test のホストに対する重複しない要求を許可します。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=owner.example.test
$ oc expose service myservice --hostname=aname.example.test
$ oc expose service myservice --hostname=bname.example.test

$ oc project ns2
$ oc expose service anotherservice --hostname=second.example.test
$ oc expose service anotherservice --hostname=cname.example.test

$ oc project otherns
$ oc expose service thirdservice --hostname=emmy.example.test
$ oc expose service thirdservice --hostname=webby.example.test

以下の例では、ワイルドカードルートを許可するルーターは、所有している namespace が ns1 なので、owner.example.test または aname.example.test の要求を許可しません。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=owner.example.test
$ oc expose service myservice --hostname=aname.example.test

$ oc project ns2
$ oc expose service secondservice --hostname=bname.example.test
$ oc expose service secondservice --hostname=cname.example.test

$ # Router will not allow this claim with a different path name `/p1` as
$ # namespace `ns1` has an older route claiming host `aname.example.test`.
$ oc expose service secondservice --hostname=aname.example.test --path="/p1"

$ # Router will not allow this claim as namespace `ns1` has an older route
$ # claiming host name `owner.example.test`.
$ oc expose service secondservice --hostname=owner.example.test

$ oc project otherns

$ # Router will not allow this claim as namespace `ns1` has an older route
$ # claiming host name `aname.example.test`.
$ oc expose service thirdservice --hostname=aname.example.test

以下の例では、ワイルドカードルートを許可するルーターは、所有している namespace が ns1 で、そのワイルドカードルートが同じ namespace に属しているので、`\*.example.test の要求を許可します。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=owner.example.test

$ # Reusing the route.yaml from the previous example.
$ # spec:
$ #   host: www.example.test
$ #   wildcardPolicy: Subdomain

$ oc create -f route.yaml   #  router will allow this claim.

以下の例では、ワイルドカードルートを許可するルーターは、所有している namespace が ns1 で、ワイルドカードルートが別の namespace cyclone に属するため、`\*.example.test の要求を許可しません。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=owner.example.test

$ # Switch to a different namespace/project.
$ oc project cyclone

$ # Reusing the route.yaml from a prior example.
$ # spec:
$ #   host: www.example.test
$ #   wildcardPolicy: Subdomain

$ oc create -f route.yaml   #  router will deny (_NOT_ allow) this claim.

同様に、ワイルドカードルートを持つ namespace がサブドメインを要求すると、その namespace 内のルートのみがその同じサブドメインでホストを要求できます。

以下の例では、ワイルドカードルートを持つ namespace ns1 のルートがサブドメイン example.test を要求すると、namespace ns1 内のルートのみがその同じサブドメインのホストを要求することを許可されます。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=owner.example.test

$ oc project otherns

$ # namespace `otherns` is allowed to claim for other.example.test
$ oc expose service otherservice --hostname=other.example.test

$ oc project ns1

$ # Reusing the route.yaml from the previous example.
$ # spec:
$ #   host: www.example.test
$ #   wildcardPolicy: Subdomain

$ oc create -f route.yaml   #  Router will allow this claim.

$ #  In addition, route in namespace otherns will lose its claim to host
$ #  `other.example.test` due to the wildcard route claiming the subdomain.

$ # namespace `ns1` is allowed to claim for deux.example.test
$ oc expose service mysecondservice --hostname=deux.example.test

$ # namespace `ns1` is allowed to claim for deux.example.test with path /p1
$ oc expose service mythirdservice --hostname=deux.example.test --path="/p1"

$ oc project otherns

$ # namespace `otherns` is not allowed to claim for deux.example.test
$ # with a different path '/otherpath'
$ oc expose service otherservice --hostname=deux.example.test --path="/otherpath"

$ # namespace `otherns` is not allowed to claim for owner.example.test
$ oc expose service yetanotherservice --hostname=owner.example.test

$ # namespace `otherns` is not allowed to claim for unclaimed.example.test
$ oc expose service yetanotherservice --hostname=unclaimed.example.test

以下の例では、所有権のあるルートが削除され、所有権が namespace 内または namespace 間で渡されるさまざまなシナリオが示されています。namespace ns1 のホスト eldest.example.test を要求するルートが存在する場合、その namespace 内のワイルドカードルートはサブドメイン example.test を要求できます。ホスト eldest.example.test のルートが削除されると、次に古いルート senior.example.test が最も古いルートになりますが、これは他のルートに影響を与えません。ホスト senior.example.test のルートが削除されると、次に古いルート junior.example.test が最も古いルートになり、ワイルドカードルートの要求をブロックします。

$ oc adm router ...
$ oc set env dc/router ROUTER_ALLOW_WILDCARD_ROUTES=true

$ oc project ns1
$ oc expose service myservice --hostname=eldest.example.test
$ oc expose service seniorservice --hostname=senior.example.test

$ oc project otherns

$ # namespace `otherns` is allowed to claim for other.example.test
$ oc expose service juniorservice --hostname=junior.example.test

$ oc project ns1

$ # Reusing the route.yaml from the previous example.
$ # spec:
$ #   host: www.example.test
$ #   wildcardPolicy: Subdomain

$ oc create -f route.yaml   #  Router will allow this claim.

$ #  In addition, route in namespace otherns will lose its claim to host
$ #  `junior.example.test` due to the wildcard route claiming the subdomain.

$ # namespace `ns1` is allowed to claim for dos.example.test
$ oc expose service mysecondservice --hostname=dos.example.test

$ # Delete route for host `eldest.example.test`, the next oldest route is
$ # the one claiming `senior.example.test`, so route claims are unaffacted.
$ oc delete route myservice

$ # Delete route for host `senior.example.test`, the next oldest route is
$ # the one claiming `junior.example.test` in another namespace, so claims
$ # for a wildcard route would be affected. The route for the host
$ # `dos.example.test` would be unaffected as there are no other wildcard
$ # claimants blocking it.
$ oc delete route seniorservice

3.2.20. コンテナーネットワークスタックの使用

OpenShift Container Platform ルーターはコンテナー内で実行され、デフォルトの動作として、ホスト (例: ルーターコンテナーが実行されるノードなど) のネットワークスタックを使用します。このデフォルトの動作には、リモートクライアントからのネットワークトラフィックがターゲットサービスとコンテナーに到達するためにユーザー空間で複数のホップを使用する必要がないので、パフォーマンス上のメリットがあります。

さらに、このデフォルト動作によってルーターはノードの IP アドレスではなくリモート接続の実際のソース IP アドレスを取得できます。これは、発信元の IP に基づいて ingress ルールを定義し、スティッキーセッションをサポートし、他に使用されているものの中でトラフィックを監視するのに役立ちます。

このホストネットワークの動作は --host-network ルーターコマンドラインオプションによって制御でき、デフォルトの動作は --host-network=true を使用した場合と等しくなります。コンテナーネットワークスタックを使用してルーターを実行する場合は、ルーターを作成する際に --host-network=false オプションを使用します。以下に例を示します。

$ oc adm router --service-account=router --host-network=false

内部的には、これは外部ネットワークがルーターと通信するために、ルーターコンテナーが 80 と 443 ポートを公開する必要があることを意味します。

注記

コンテナーネットワークスタックを使用して実行することで、ルーターは接続のソース IP アドレスを実際のリモート IP アドレスではなくノードの NAT された IP アドレスとして扱うことを意味します。

注記

マルチテナントネットワークの分離 を使用する OpenShift Container Platform クラスターでは、--host-network=false オプションを指定したデフォルト以外の namespace のルーターはクラスターのすべてのルートを読み込みますが、ネットワークの分離により複数の namespace にあるルートには到達できません。--host-network=true オプションを指定すると、ルートはコンテナーネットワークをバイパスし、クラスターの任意の Pod にアクセスできます。この場合、分離が必要な場合は、複数の namespace のルートを追加しないでください。

3.2.21. Dynamic Configuration Manager の使用

HAProxy ルーターを Dynamic Configuration Manager を使用するように設定できます。

Dynamic Configuration Manager は、HAProxy リロードのダウンタイムなしに特定のタイプのルートをオンラインにします。これは、ルートおよびエンドポイントの addition|deletion|update など、ルートおよびエンドポイントのすべてのライフサイクルイベントを処理します。

ROUTER_HAPROXY_CONFIG_MANAGER 環境変数を true に設定して Dynamic Configuration Manager を有効にします。

$ oc set env dc/<router_name> ROUTER_HAPROXY_CONFIG_MANAGER='true'

Dynamic Configuration Manager が HAProxy を動的に設定できない場合、これは設定を再作成し、HAProxy プロセスをリロードします。これには、新規ルートにカスタムタイムアウトなどのカスタムアノテーションが含まれる場合や、ルートにカスタム TLS 設定が必要な場合などが含まれます。

動的な設定は、事前に割り当てられたルートおよびバックエンドサーバーのプールと共に HAProxy ソケットおよび設定 API を内部で使用します。ルートの事前に割り当てられたプールは、ルートのブループリントを使用して作成されます。ブループリントのデフォルトセットはセキュリティー保護のないルート、カスタム TLS 設定のないセキュリティー保護された edge ルート、および passthrough ルートをサポートします。

重要

re-encrypt ルートにはカスタム TLS 設定情報が必要であるため、Dynamic Configuration Manager でそれらを使用するには追加の設定が必要になります。

ROUTER_BLUEPRINT_ROUTE_NAMESPACE を設定し、オプションで ROUTER_BLUEPRINT_ROUTE_LABELS 環境変数を設定することで Dynamic Configuration Manager が使用できるブループリントを拡張します。

ブループリントルート namespace のすべてのルート、またはルートラベルに一致するルートは、ブループリントのデフォルトセットに似たカスタムブループリントとして処理されます。これには、re-encrypt ルートやカスタムアノテーションを使用するルート、またはカスタム TLS 設定のあるルートが含まれます。

以下の手順では、reencrypt-blueprintannotated-edge-blueprint、および annotated-unsecured-blueprint の 3 つのルートオブジェクトがあることを前提としています。各種のルートタイプオブジェクトについては、ルートタイプ を参照してください。

手順

  1. 新しいプロジェクトを作成します。

    $ oc new-project namespace_name
  2. 新規ルートを作成します。この方法では既存サービスを公開します。

    $ oc create route edge edge_route_name --key=/path/to/key.pem \
          --cert=/path/to/cert.pem --service=<service> --port=8443
  3. ルートにラベルを付けます。

    $ oc label route edge_route_name type=route_label_1
  4. ルートオブジェクト定義から 3 つの異なるルートを作成します。すべてにラベル type=route_label_1 が付けられます。

    $ oc create -f reencrypt-blueprint.yaml
    $ oc create -f annotated-edge-blueprint.yaml
    $ oc create -f annotated-unsecured-blueprint.json

    また、ブループリントルートとしての使用を防ぐラベルをルートから削除することもできます。たとえば、annotated-unsecured-blueprint をブループリントルートとして使用されることを防ぐには、以下を実行します。

    $ oc label route annotated-unsecured-blueprint type-
  5. ブループリントプールに用される新規のルーターを作成します。

    $ oc adm router
  6. 新規ルーターの環境変数を設定します。

    $ oc set env dc/router ROUTER_HAPROXY_CONFIG_MANAGER=true      \
                           ROUTER_BLUEPRINT_ROUTE_NAMESPACE=namespace_name  \
                           ROUTER_BLUEPRINT_ROUTE_LABELS="type=route_label_1"

    ラベル type=route_label_1 が設定された namespace またはプロジェクト namespace_name のすべてのルートはカスタムブループリントとして処理でき、使用できます。

    ブループリントは、namespace namespace_name で通常実行するようにルートを管理することによって、追加し、更新し、削除できることに注意してください。Dynamic Configuration Manager は、ルーターが routes および services の有無を監視するのと同様の方法で namespace namespace_name のルートへの変更の有無を監視します。

  7. 事前に割り当てられたルートおよびバックエンドサーバーのプールサイズは、ROUTER_BLUEPRINT_ROUTE_POOL_SIZE (デフォルトは 10)、および ROUTER_MAX_DYNAMIC_SERVERS (デフォルトは 5) 環境変数で制御できます。また、Dynamic Configuration Manager が加える変更をディスクにコミットする頻度、つまり HAProxy 設定が再作成され、HAProxy プロセスがリロードされるタイミングを制御することもできます。デフォルトは 1 時間 (3600 秒) または Dynamic Configuration Manager のプールスペースが不足するタイミングになります。COMMIT_INTERVAL 環境変数がこの設定を制御します。

    $ oc set env dc/router -c router ROUTER_BLUEPRINT_ROUTE_POOL_SIZE=20  \
          ROUTER_MAX_DYNAMIC_SERVERS=3 COMMIT_INTERVAL=6h

    この例では、各ブループリントルートのプールサイズを 20 に増やし、動的サーバーの数を 3 に減らし、またコミット期間を 6 時間に増やしています。

3.2.22. ルーターメトリクスの公開

HAProxy ルーターメトリクス は、外部メトリクス収集および集約システム (例: Prometheus、statsd) で使用されるようにデフォルトで Prometheus 形式 で公開されます。メトリクスは独自の HTML 形式でブラウザーで閲覧したり CSV ダウンロードを実行するために HAProxy ルーター から直接利用することもできます。これらのメトリクスには、HAProxy ネイティブメトリクスおよび一部のコントローラーメトリクスが含まれます。

以下のコマンドを使用してルーターを作成する場合、OpenShift Container Platform は Prometheus 形式のメトリクスをデフォルトが 1936 の統計ポートで利用可能にします。

$ oc adm router --service-account=router
  • Prometheus 形式で未加工統計を抽出するには、以下を実行します。

    curl <user>:<password>@<router_IP>:<STATS_PORT>

    以下に例を示します。

    $ curl admin:sLzdR6SgDJ@10.254.254.35:1936/metrics

    メトリクスにアクセスするために必要な情報は、ルーターサービスのアノテーションで確認できます。

    $ oc edit service <router-name>
    
    apiVersion: v1
    kind: Service
    metadata:
      annotations:
        prometheus.io/port: "1936"
        prometheus.io/scrape: "true"
        prometheus.openshift.io/password: IImoDqON02
        prometheus.openshift.io/username: admin

    prometheus.io/port はデフォルトが 1936 の統計ポートです。アクセスを許可するようファイウォールを設定する必要がある場合があります。直前のユーザー名およびパスワードを使用してメトリクスにアクセスします。パスは /metrics です。

    $ curl <user>:<password>@<router_IP>:<STATS_PORT>
    for example:
    $ curl admin:sLzdR6SgDJ@10.254.254.35:1936/metrics
    ...
    # HELP haproxy_backend_connections_total Total number of connections.
    # TYPE haproxy_backend_connections_total gauge
    haproxy_backend_connections_total{backend="http",namespace="default",route="hello-route"} 0
    haproxy_backend_connections_total{backend="http",namespace="default",route="hello-route-alt"} 0
    haproxy_backend_connections_total{backend="http",namespace="default",route="hello-route01"} 0
    ...
    # HELP haproxy_exporter_server_threshold Number of servers tracked and the current threshold value.
    # TYPE haproxy_exporter_server_threshold gauge
    haproxy_exporter_server_threshold{type="current"} 11
    haproxy_exporter_server_threshold{type="limit"} 500
    ...
    # HELP haproxy_frontend_bytes_in_total Current total of incoming bytes.
    # TYPE haproxy_frontend_bytes_in_total gauge
    haproxy_frontend_bytes_in_total{frontend="fe_no_sni"} 0
    haproxy_frontend_bytes_in_total{frontend="fe_sni"} 0
    haproxy_frontend_bytes_in_total{frontend="public"} 119070
    ...
    # HELP haproxy_server_bytes_in_total Current total of incoming bytes.
    # TYPE haproxy_server_bytes_in_total gauge
    haproxy_server_bytes_in_total{namespace="",pod="",route="",server="fe_no_sni",service=""} 0
    haproxy_server_bytes_in_total{namespace="",pod="",route="",server="fe_sni",service=""} 0
    haproxy_server_bytes_in_total{namespace="default",pod="docker-registry-5-nk5fz",route="docker-registry",server="10.130.0.89:5000",service="docker-registry"} 0
    haproxy_server_bytes_in_total{namespace="default",pod="hello-rc-vkjqx",route="hello-route",server="10.130.0.90:8080",service="hello-svc-1"} 0
    ...
  • ブラウザーでメトリクスを取得するには、以下を実行します。

    1. 以下の 環境変数 をルーターデプロイメント設定ファイルから削除します。

      $ oc edit dc router
      
      - name: ROUTER_LISTEN_ADDR
        value: 0.0.0.0:1936
      - name: ROUTER_METRICS_TYPE
        value: haproxy
    2. HAProxy ルーターによって提供されるため、ルーターの readiness probe にパッチを適用し、これが liveness probe と同じパスを使用するようにします。

      $ oc patch dc router -p '"spec": {"template": {"spec": {"containers": [{"name": "router","readinessProbe": {"httpGet": {"path": "/healthz"}}}]}}}'
    3. ブラウザーで以下の URL を使用して統計ウィンドウを起動します。 ここでは、STATS_PORT 値はデフォルトで 1936 になります。

      http://admin:<Password>@<router_IP>:<STATS_PORT>

      ;csv を URL に追加して CVS 形式の統計を取得できます。

      以下に例を示します。

      http://admin:<Password>@<router_IP>:1936;csv

      ルーター IP、管理者名、およびパスワードを取得するには、以下を実行します。

      oc describe pod <router_pod>
  • メトリクスのコレクションを表示しないようにするには、以下を実行します。

    $ oc adm router --service-account=router --stats-port=0

3.2.23. 大規模クラスターの ARP キャッシュのチューニング

(net.ipv4.neigh.default.gc_thresh3 の値 (デフォルトで 65536) を上回る) 多数のルート を持つ OpenShift Container Platform クラスターでは、ARP キャッシュでより多くのエントリーを許可するためにルーター Pod を実行するクラスターの各ノードで sysctl 変数のデフォルト値を増やす必要があります。

問題が発生している場合、以下のようなカーネルメッセージが表示されます。

[ 1738.811139] net_ratelimit: 1045 callbacks suppressed
[ 1743.823136] net_ratelimit: 293 callbacks suppressed

この問題が発生すると、oc コマンドは以下のエラーを出して失敗することがあります。

Unable to connect to the server: dial tcp: lookup <hostname> on <ip>:<port>: write udp <ip>:<port>-><ip>:<port>: write: invalid argument

IPv4 の ARP エントリーの実際の量を確認するには、以下を実行します。

# ip -4 neigh show nud all | wc -l

数字が net.ipv4.neigh.default.gc_thresh3 しきい値に近づき始めたら、値を増やします。以下を実行して現在値を取得します。

# sysctl net.ipv4.neigh.default.gc_thresh1
net.ipv4.neigh.default.gc_thresh1 = 128
# sysctl net.ipv4.neigh.default.gc_thresh2
net.ipv4.neigh.default.gc_thresh2 = 512
# sysctl net.ipv4.neigh.default.gc_thresh3
net.ipv4.neigh.default.gc_thresh3 = 1024

以下の sysctl は変数を OpenShift Container Platform の現在のデフォルト値に設定します。

# sysctl net.ipv4.neigh.default.gc_thresh1=8192
# sysctl net.ipv4.neigh.default.gc_thresh2=32768
# sysctl net.ipv4.neigh.default.gc_thresh3=65536

これらの設定を永続化するには、このドキュメント を参照してください。

3.2.24. DDoS 攻撃からの保護

timeout http-request をデフォルトの HAProxy ルーターイメージに追加して、分散型の denial-of-service (DDoS) 攻撃 (slowloris など) からデプロイメントを保護します。

# and the haproxy stats socket is available at /var/run/haproxy.stats
global
  stats socket ./haproxy.stats level admin

defaults
  option http-server-close
  mode http
  timeout http-request 5s
  timeout connect 5s 1
  timeout server 10s
  timeout client 30s
1
timeout http-request は最大 5 秒に設定されます。HAProxy は HTTP 要求全体の送信のための 5 秒をクライアントに対して指定します。この指定がないと、HAProxy はエラーを出して接続を切断します。

また、環境変数 ROUTER_SLOWLORIS_TIMEOUT が設定されている場合、クライアントが HTTP 要求全体を送信するためにかかる合計時間が制限されます。これが設定されていない場合、HAProxy は接続を切断します。

環境変数を設定することで、情報をルーターのデプロイメント設定の一部として取得でき、テンプレートを手動で変更することが不要になります。 一方、HAProxy 設定を手動で追加すると、ルーター Pod の再ビルドとルーターテンプレートファイルの保守が必要になります。

アノテーションを使用して、以下を制限する機能を含む基本的な DDoS 保護を HAProxy テンプレートルーターに実装します。

  • 同時 TCP 接続の数
  • クライアントが TCP 接続を要求できるレート
  • HTTP 要求を実行できるレート

アプリケーションによってはトラフィックのパターンが完全に異なる場合があるため、これらはルートごとに有効にされます。

表3.1 HAProxy テンプレートルーター設定
設定説明

haproxy.router.openshift.io/rate-limit-connections

設定した内容を有効にします (true に設定した場合など)。

haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp

このルートの同じ IP アドレスで接続できる同時 TCP 接続の数。

haproxy.router.openshift.io/rate-limit-connections.rate-tcp

クライアント IP で開くことができる TCP 接続の数。

haproxy.router.openshift.io/rate-limit-connections.rate-http

クライアント IP が 3 秒間で実行できる HTTP 要求の数。

3.2.25. HAProxy スレッドの有効化

--threads フラグを使用してスレッドを有効にします。このフラグは、HAProxy ルーターが使用するスレッド数を指定します。

3.3. カスタマイズされた HAProxy ルーターのデプロイ

3.3.1. 概要

デフォルトの HAProxy ルーターは多数のユーザーのニーズを対応することを目的としています。ただし、このルーターは HAProxy のすべての機能を公開している訳ではありません。そのため、ユーザーはそれぞれのニーズに合わせてルーターを変更する必要があります。

新機能をアプリケーションバックエンド内で実装したり、現在の操作を変更する必要がある場合があります。ルータープラグインはこのカスタマイズを行うために必要なすべての機能を提供します。

ルーター Pod はテンプレートファイルを使用して必要な HAProxy 設定ファイルを作成します。テンプレートファイルは golang テンプレート です。テンプレートを処理する際に、ルーターはルーターのデプロイメント設定、許可されたルートのセット、一部のヘルパー機能などの OpenShift Container Platform 情報にアクセスします。

ルーター Pod が起動し、リロードされるたびに、HAProxy 設定ファイルが作成され、HAProxy が起動します。HAProxy 設定マニュアル には HAProxy のすべての機能と有効な設定ファイルの作成方法が記載されています。

configMap を使用して新規テンプレートをルーター Pod に追加することができます。この方法により、ルーターデプロイメント設定を変更して、configMap をルーター Pod のボリュームとしてマウントできます。TEMPLATE_FILE 環境変数はルーター Pod のテンプレートファイルのフルパス名に設定されます。

重要

OpenShift Container Platform のアップグレード後に、ルーターテンプレートのカスタマイズが引き続き機能する訳ではありません。

また、ルーターテンプレートのカスタマイズは、実行中のルーターのテンプレートバージョンに適用する必要があります。

または、カスタムルーターイメージをビルドし、ルーターの一部またはすべてをデプロイする際にこれを使用することができます。すべてのルーターが同じイメージを実行する必要はありません。これを実行するには、 haproxy-template.config ファイルを変更し、ルーターイメージを 再ビルド します。新しいイメージはクラスターの Docker リポジトリーにプッシュされ、ルーターのデプロイメント設定の image: フィールドが新しい名前で更新されます。クラスターが更新されたら、イメージを再ビルドし、プッシュする必要があります。

いずれの場合でも、ルーター Pod はテンプレートファイルを使用して起動します。

3.3.2. ルーター設定テンプレートの取得

HAProxy テンプレートファイルはかなり大きく複雑です。一部を変更するのであれば、すべてを書き換えるよりも既存のテンプレートを変更する方が簡単です。マスターでルーターを実行し、ルーター Pod を参照することで実行中のルーターから haproxy-config.templateファイルを取得できます。

# oc get po
NAME                       READY     STATUS    RESTARTS   AGE
router-2-40fc3             1/1       Running   0          11d
# oc exec router-2-40fc3 cat haproxy-config.template > haproxy-config.template
# oc exec router-2-40fc3 cat haproxy.config > haproxy.config

または、ルーターを実行しているノードにログオンします。

# docker run --rm --interactive=true --tty --entrypoint=cat \
    registry.redhat.io/openshift3/ose-haproxy-router:v{product-version} haproxy-config.template

イメージ名は コンテナーイメージ から取られます。

この内容をカスタマイズされたテンプレートのベースとして使用するためにファイルに保存します。保存された haproxy.config は実際に実行されているものを示します。

3.3.3. ルーター設定テンプレートの変更

3.3.3.1. 背景情報

このテンプレートは golang テンプレート に基づいています。これは、ルーターのデプロイメント設定の環境変数や、以下に示す設定情報およびルーターが提供するヘルパー機能を参照することができます。

テンプレートファイルの構造は作成される HAProxy 設定ファイルを反映します。テンプレートの処理時に、{{" something "}} によって囲まれていないものはすべて設定ファイルに直接コピーされます。{{" something "}} で囲まれている部分は評価されます。生成されるテキスト (ある場合) は設定ファイルにコピーされます。

3.3.3.2. Go テンプレートアクション

define アクションは、処理されるテンプレートを含むファイルに名前を付けます。

{{define "/var/lib/haproxy/conf/haproxy.config"}}pipeline{{end}}
表3.2 テンプレートルーター関数
関数意味

processEndpointsForAlias(alias ServiceAliasConfig, svc ServiceUnit, action string) []Endpoint

有効なエンドポイントの一覧を返します。アクションが Shuffle の場合、エンドポイントの順序はランダム化されます。

env(variable, default …​string)string

Pod からの名前付き環境変数の取得を試行します。これが定義されていないか、または空の場合、オプションの 2 つ目の引数が返されます。それ以外の場合には空の文字列を返します。

matchPattern(pattern, s string) bool

1 つ目の引数は正規表現を含む文字列で、2 つ目の引数はテストに使用できる変数です。1 つ目の引数として提供される正規表現が 2 つ目の引数として提供される文字列と一致するかどうかを示すブール値を返します。

isInteger(s string) bool

指定された変数が整数かどうかを判別します。

firstMatch(s string, allowedValues …​string) bool

所定の文字列を許可された文字列の一覧と比較します。左から右にスキャンし、最初の一致を返します。

matchValues(s string, allowedValues …​string) bool

所定の文字列を許可された文字列の一覧と比較します。文字列が許可される値の場合は true を返します。 それ以外の場合は、false を返します。

generateRouteRegexp(hostname, path string, wildcard bool) string

ルートホスト (とパス) に一致する正規表現を生成します。最初の引数はホスト名であり、2 つ目はパス、3 つ目はワイルドカードブール値です。

genCertificateHostName(hostname string, wildcard bool) string

証明書の提供/証明書のマッチングに使用するホスト名を生成します。1 つ目の引数はホスト名で、2 つ目はワイルドカードブール値です。

isTrue(s string) bool

所定の変数に true が含まれるかどうかを判別します。

これらの関数は、HAProxy テンプレートルータープラグインによって提供されます。

3.3.3.3. ルーターが提供する情報

このセクションでは、ルーターがテンプレートで利用可能にする OpenShift Container Platform の情報について説明しますす。ルーター設定パラメーターは HAProxy ルータープラグインに与えられるデータセットです。フィールドには (dot) .Fieldname を使用してアクセスします。

以下のルーター設定パラメーター表は各種フィールドの定義を詳しく取り上げています。とくに .State には許可されたルートセットが設定されます。

表3.3 ルーター設定パラメーター
フィールドタイプ説明

WorkingDir

string

ファイルが書き込まれるディレクトリー。 デフォルトは /var/lib/containers/router に設定されます。

State

map[string](ServiceAliasConfig)

ルート。

ServiceUnits

map[string]ServiceUnit

サービスのルックアップ。

DefaultCertificate

string

pem 形式のデフォルト証明書へのフルパス名。

PeerEndpoints

[]Endpoint

ピア。

StatsUser

string

統計の公開に使用するユーザー名 (テンプレートがサポートしている場合)。

StatsPassword

string

統計の公開に使用するパスワード (テンプレートがサポートしている場合)。

StatsPort

int

統計の公開に使用するポート (テンプレートがサポートしている場合)。

BindPorts

bool

ルーターがデフォルトポートをバインドすべきかどうか。

表3.4 ルーター ServiceAliasConfig (Route)
フィールドタイプ説明

Name

string

ルートのユーザー固有の名前。

Namespace

string

ルートの namespace。

Host

string

ホスト名です。例: www.example.com

Path

string

オプションのパス。例: www.example.com/myservice (ここでは、myservice がパスになります)。

TLSTermination

routeapi.TLSTerminationType

このバックエンドの終了ポリシー。 マッピングファイルとルーター設定を利用します。

Certificates

map[string]Certificate

このバックエンドをセキュリティー保護するために使用する証明書。証明書 ID で指定します。

Status

ServiceAliasConfigStatus

永続化する必要がある設定のステータスを示します。

PreferPort

string

ユーザーが公開したいポートを示します。空の場合、サービスのポートが選択されます。

InsecureEdgeTerminationPolicy

routeapi.InsecureEdgeTerminationPolicyType

edge termination ルートへの非セキュアな接続の必要な動作を示します。 none (または disable)、allow、または redirect

RoutingKeyName

string

Cookie ID を隠すために使用するルート + namespace 名のハッシュ。

IsWildcard

bool

このサービスユニットがワイルドカードサポートを必要とすることを示します。

Annotations

map[string]string

このルートに割り当てられるアノテーション。

ServiceUnitNames

map[string]int32

このルートをサポートするサービスコレクション。マップの他のエントリーに関連してサービス名で指定され、これに割り当てられた重みで評価されます。

ActiveServiceUnits

int

ゼロ以外の重みを持つ ServiceUnitNames の数。

ServiceAliasConfig はサービスのルートです。ホスト + パスによって特定されます。デフォルトのテンプレートは {{range $cfgIdx, $cfg := .State }} を使用してルートを繰り返し処理します。その {{range}} ブロック内で、テンプレートは $cfg.Field を使用して現在の ServiceAliasConfig のフィールドを参照できます。

表3.5 ルーター ServiceUnit
フィールドタイプ説明

Name

string

名前はサービス名 + namespace に対応します。ServiceUnit を特定します。

EndpointTable

[]Endpoint

サービスをサポートするエンドポイント。これはルーターの最終のバックエンド実装に変換されます。

ServiceUnit はサービスをカプセル化したものであり、そのサービスをサポートするエンドポイントであり、またサービスを参照するルートです。これは、ルーター設定ファイルの作成の基になるデータです。

表3.6 ルーターエンドポイント
フィールド

ID

string

IP

string

Port

string

TargetName

string

PortName

string

IdHash

string

NoHealthCheck

bool

Endpoint は、Kubernetes エンドポイントの内部表現です。

表3.7 ルーター証明書、ServiceAliasConfigStatus
フィールドタイプ説明

Certificate

string

パブリック/プライベートキーのペアを表します。これは ID で識別され、ファイル名になります。CA 証明書には PrivateKey が設定されません。

ServiceAliasConfigStatus

string

この設定に必要なファイルがディスクに永続化されていることを示します。有効な値の例: "saved" または "" (ブランク)。

表3.8 ルーター証明書タイプ
フィールドタイプ説明

ID

string

 

内容

string

証明書。

PrivateKey

string

プライベートキー。

表3.9 ルーター TLSTerminationType
フィールドタイプ説明

TLSTerminationType

string

セキュアな通信が停止する場合について指示します。

InsecureEdgeTerminationPolicyType

string

ルートへの非セキュアな接続の必要な動作を示します。各ルーターは公開するポートを独自に決定することがありますが、通常はポート 80 になります。

TLSTerminationTypeInsecureEdgeTerminationPolicyType はセキュアな通信が停止する場合について指示します。

表3.10 ルーター TLSTerminationType 値
Constant意味

TLSTerminationEdge

edge

edge ルーターでの暗号化を終了します。

TLSTerminationPassthrough

パススルー

宛先での暗号化を終了し、宛先でトラフィックを復号化します。

TLSTerminationReencrypt

reencrypt

edge ルーターで暗号化を終了し、宛先で提供される新規の証明書を使用して再暗号化します。

表3.11 ルーター InsecureEdgeTerminationPolicyType 値
意味

Allow

トラフィックは非セキュアなポートのサーバーに送信されます (デフォルト)。

Disable

トラフィックは非セキュアなポートでは許可されません。

Redirect

クライアントはセキュアなポートにリダイレクトされます。

なし ("") は Disable と同じです。

3.3.3.4. アノテーション

各ルートにはアノテーションを割り当てることができます。各アノテーションは名前と値のみで設定されます。

apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/timeout: 5500ms
[...]

名前は既存のアノテーションと競合しないものにできます。値は文字列です。文字列では複数のトークンをスペースで区切ることができます (例: aa bb cc)。このテンプレートは {{index}} を使用してアノテーションの値を抽出します。以下に例を示します。

{{$balanceAlgo := index $cfg.Annotations "haproxy.router.openshift.io/balance"}}

この例は、これをどのようにクライアントの相互認証に使用できるかを示しています。

{{ with $cnList := index $cfg.Annotations "whiteListCertCommonName" }}
  {{   if ne $cnList "" }}
    acl test ssl_c_s_dn(CN) -m str {{ $cnList }}
    http-request deny if !test
  {{   end }}
{{ end }}

このコマンドを使用してホワイトリストの CN を処理できます。

$ oc annotate route <route-name> --overwrite whiteListCertCommonName="CN1 CN2 CN3"

詳細は、ルート固有のアノテーション を参照してください。

3.3.3.5. 環境変数

テンプレートはルーター Pod に存在する任意の環境変数を使用できます。環境変数はデプロイメント設定に設定できます。また、新規の環境変数を追加できます。

これらは env 関数で参照されます。

{{env "ROUTER_MAX_CONNECTIONS" "20000"}}

1 つ目の文字列は変数であり、変数がないか、または nil の場合には 2 つ目の文字列がデフォルトになります。ROUTER_MAX_CONNECTIONS が設定されていないか、または nil の場合、20000 が使用されます。環境変数はマップと言えます。 ここでキーは環境変数名で、内容は変数の値になります。

詳細は、ルート固有の環境変数 を参照してください。

3.3.3.6. 使用例

以下で HAProxy テンプレートファイルに基づく単純なテンプレートを示します。

以下のコメントで開始します。

{{/*
  Here is a small example of how to work with templates
  taken from the HAProxy template file.
*/}}

テンプレートは任意の数の出力ファイルを作成できます。define コンストラクトを使用して出力ファイルを作成します。ファイル名は定義する引数として指定され、define ブロック内の一致する終了部分までのすべての情報がそのファイルの内容として書き込まれます。

{{ define "/var/lib/haproxy/conf/haproxy.config" }}
global
{{ end }}

上記は global/var/lib/haproxy/conf/haproxy.config ファイルにコピーし、ファイルを閉じます。

ロギングを環境変数に基づいてセットアップします。

{{ with (env "ROUTER_SYSLOG_ADDRESS" "") }}
  log {{.}} {{env "ROUTER_LOG_FACILITY" "local1"}} {{env "ROUTER_LOG_LEVEL" "warning"}}
{{ end }}

env 関数は、環境変数の値を抽出します。環境変数が定義されていないか、または nil の場合、2 つ目の引数が返されます。

with コンストラクトは with ブロック内の "." (ドット) の値を with に引数として提供される値に設定します。with アクションは Dot で nil をテストします。nil ではない場合、その句は end (終了部分) まで処理されます。上記では、ROUTER_SYSLOG_ADDRESS/var/log/msg が含まれ、ROUTER_LOG_FACILITY が定義されておらず、ROUTER_LOG_LEVELinfo が含まれていると想定しています。以下が出力ファイルにコピーされます。

  log /var/log/msg local1 info

許可された各ルートは設定ファイルの行を生成します。range を使用して、許可されたルートを確認します。

{{ range $cfgIdx, $cfg := .State }}
  backend be_http_{{$cfgIdx}}
{{end}}

.StateServiceAliasConfig のマップです。ここでは、キーはルート名です。range はマップを通じて、パスするたびに key を使用して $cfgIdx を設定し、 $cfg がルートを記述する ServiceAliasConfig をポイントするよう設定します。myroutehisroute という 2 つのルートがある場合、上記により以下が出力ファイルにコピーされます。

  backend be_http_myroute
  backend be_http_hisroute

ルートアノテーション $cfg.Annotations もマップであり、アノテーション名がキーとなり、コンテンツの文字列が値になっています。ルートは必要な数だけアノテーションを持つことができ、テンプレートの作成者が使用方法を定義します。ユーザーはアノテーションをルートにコード化し、テンプレート作成者は HAProxy テンプレートをカスタマイズしてそのアノテーションを処理できるようにします。

通常はアノテーションをインデックス化して値を取得します。

{{$balanceAlgo := index $cfg.Annotations "haproxy.router.openshift.io/balance"}}

インデックスは指定されたアノテーションの値を抽出します。そのため、$balanceAlgo はアノテーションまたは nil に関連付けられた文字列が含まれます。上記のように、nil 以外の文字列についてテストし、with コンストラクトを使用して影響を確認することができます。

{{ with $balanceAlgo }}
  balance $balanceAlgo
{{ end }}

$balanceAlgonil でない場合、balance $balanceAlgo は出力ファイルにコピーされます。

2 つ目の例では、アノテーションのタイムアウト値の設定に基づいてサーバータイムアウトを設定します。

$value := index $cfg.Annotations "haproxy.router.openshift.io/timeout"

$value を評価して、適切に作成された文字列が含まれていることを確認できます。matchPattern 関数は正規表現を受け入れ、引数が表現を満たしていれば true を返します。

matchPattern "[1-9][0-9]*(us\|ms\|s\|m\|h\|d)?" $value

これにより 5000ms を受け入れますが、7y は受け取りません。この結果はテストで使用できます。

{{if (matchPattern "[1-9][0-9]*(us\|ms\|s\|m\|h\|d)?" $value) }}
  timeout server  {{$value}}
{{ end }}

これを使用してトークンに一致させることもできます。

matchPattern "roundrobin|leastconn|source" $balanceAlgo

または、matchValues を使用してトークンと一致させることもできます。

matchValues $balanceAlgo "roundrobin" "leastconn" "source"

3.3.4. ConfigMap を使用してルーター設定テンプレートを置き換える

ConfigMap を使用して、ルーターイメージを再ビルドせずにルーターインスタンスをカスタマイズできます。ルーター環境変数の作成し、変更することができるだけでなく、haproxy-config.templatereload-haproxy その他のスクリプトを変更することもできます。

  1. 上記のように 変更する haproxy-config.template をコピーします。必要に応じて変更します。
  2. ConfigMap を作成します。

    $ oc create configmap customrouter --from-file=haproxy-config.template

    customrouter ConfigMap には変更された haproxy-config.template ファイルのコピーが含まれています。

  3. ルーターデプロイメント設定を変更し、ConfigMap をファイルとしてマウントし、TEMPLATE_FILE 環境変数がこれをポイントするようにします。これは、 oc set envoc set volume コマンドを使用するか、またはルーターデプロイメント設定を編集して実行できます。

    oc コマンドの使用
    $ oc set volume dc/router --add --overwrite \
        --name=config-volume \
        --mount-path=/var/lib/haproxy/conf/custom \
        --source='{"configMap": { "name": "customrouter"}}'
    $ oc set env dc/router \
        TEMPLATE_FILE=/var/lib/haproxy/conf/custom/haproxy-config.template
    ルーターデプロイメント設定の編集

    oc edit dc router を使用して、テキストエディターでルーターデプロイメント設定を編集します。

    ...
            - name: STATS_USERNAME
              value: admin
            - name: TEMPLATE_FILE  1
              value: /var/lib/haproxy/conf/custom/haproxy-config.template
            image: openshift/origin-haproxy-routerp
    ...
            terminationMessagePath: /dev/termination-log
            volumeMounts: 2
            - mountPath: /var/lib/haproxy/conf/custom
              name: config-volume
          dnsPolicy: ClusterFirst
    ...
          terminationGracePeriodSeconds: 30
          volumes: 3
          - configMap:
              name: customrouter
            name: config-volume
    ...
    1
    spec.container.env フィールドに TEMPLATE_FILE 環境変数を追加して、マウントされた haproxy-config.template ファイルをポイントするようにします。
    2
    spec.container.volumeMounts フィールドを追加して、マウントポイントを作成します。
    3
    新しい spec.volumes フィールドを追加し、ConfigMap を示唆します。

    変更を保存し、エディターを終了します。ルーターが再起動します。

3.3.5. Stick Table の使用

以下のカスタマイズの例を 高可用なルーティングセットアップ で使用することで、ピア間の同期を行う stick-table を使用できます。

ピアセクションの追加

ピア間で stick-table を同期するには、HAProxy 設定でピアセクションを定義する必要があります。このセクションによって、HAProxy がどのようにピアを識別し、接続するかが決まります。プラグインはデータを .PeerEndpoints 変数にあるテンプレートに提供するので、ルーターサービスのメンバーを簡単に識別できます。以下を追加することで、ピアセクションをルーターイメージ内の haproxy-config.template ファイルに追加することができます。

{{ if (len .PeerEndpoints) gt 0 }}
peers openshift_peers
  {{ range $endpointID, $endpoint := .PeerEndpoints }}
    peer {{$endpoint.TargetName}} {{$endpoint.IP}}:1937
  {{ end }}
{{ end }}

リロードスクリプトの変更

stick-table を使用する場合、HAProxy にピアセクションでローカルホスト名として見なすものをオプションで指示することができます。エンドポイントの作成時に、プラグインは TargetName をエンドポイントの TargetRef.Name の値に設定するよう試みます。TargetRef が設定されていない場合、TargetName は IP アドレスに設定されます。TargetRef.Name は Kubernetes ホスト名に対応しているので、-L オプションを reload-haproxy スクリプトに追加してローカルホストをピアセクションで識別できます。

peer_name=$HOSTNAME 1

if [ -n "$old_pid" ]; then
  /usr/sbin/haproxy -f $config_file -p $pid_file -L $peer_name -sf $old_pid
else
  /usr/sbin/haproxy -f $config_file -p $pid_file -L $peer_name
fi
1
ピアセクションで使用されるエンドポイントターゲット名と一致している必要があります。

バックエンドの変更

最後に、stick-table をバックエンド内で使用するために、HAProxy 設定を変更して stick-table およびピアセットを使用することができます。以下は、stick-table を使用するように TCP 接続の既存のバックエンドを変更している例です。

            {{ if eq $cfg.TLSTermination "passthrough" }}
backend be_tcp_{{$cfgIdx}}
  balance leastconn
  timeout check 5000ms
  stick-table type ip size 1m expire 5m{{ if (len $.PeerEndpoints) gt 0 }} peers openshift_peers {{ end }}
  stick on src
                {{ range $endpointID, $endpoint := $serviceUnit.EndpointTable }}
  server {{$endpointID}} {{$endpoint.IP}}:{{$endpoint.Port}} check inter 5000ms
                {{ end }}
            {{ end }}

この変更を行った後に、ルーターを再ビルド できます。

3.3.6. ルーターの再ビルド

ルーターを再ビルドするには、実行中のルーターにある複数のファイルのコピーが必要になります。作業ディレクトリーを作成し、ルーターからファイルをコピーします。

# mkdir - myrouter/conf
# cd myrouter
# oc get po
NAME                       READY     STATUS    RESTARTS   AGE
router-2-40fc3             1/1       Running   0          11d
# oc exec router-2-40fc3 cat haproxy-config.template > conf/haproxy-config.template
# oc exec router-2-40fc3 cat error-page-503.http > conf/error-page-503.http
# oc exec router-2-40fc3 cat default_pub_keys.pem > conf/default_pub_keys.pem
# oc exec router-2-40fc3 cat ../Dockerfile > Dockerfile
# oc exec router-2-40fc3 cat ../reload-haproxy > reload-haproxy

これらのファイルのいずれも編集するか、または置き換えることができます。ただし、conf/haproxy-config.templatereload-haproxy が変更される可能性が高くなります。

ファイルの更新後:

# docker build -t openshift/origin-haproxy-router-myversion .
# docker tag openshift/origin-haproxy-router-myversion 172.30.243.98:5000/openshift/haproxy-router-myversion 1
# docker push 172.30.243.98:5000/openshift/origin-haproxy-router-pc:latest 2
1
このバージョンをリポジトリーでタグ付けします。この場合、リポジトリーは 172.30.243.98:5000 になります。
2
タグ付けバージョンをリポジトリーにプッシュします。まずリポジトリーに docker ログイン する必要がある場合があります。

新規ルーターを使用するには、image: 文字列を変更するか、または --images=<repo>/<image>:<tag> フラグを oc adm router コマンドに追加してルーターデプロイ設定を編集します。

変更のデバッグ時に、デプロイメント設定で imagePullPolicy: Always を設定して各 Pod の作成時にイメージプルを強制的に実行すると便利です。デバッグが完了したら、これを imagePullPolicy: IfNotPresent に戻して各 Pod の起動時のプルを回避します。

3.4. PROXY プロトコルを使用するように HAProxy ルーターを設定する

3.4.1. 概要

デフォルトで HAProxy ルーターは、非セキュアな edge および re-encrypt ルートへの受信接続に HTTP を使用することを想定しています。ただし、PROXY プロトコル を使用することで、ルーターが受信要求を予想するよう設定することができます。このトピックでは、HAProxy ルーターと外部ロードバランサーを PROXY プロトコルを使用するように設定する方法を説明しています。

3.4.2. PROXY プロトコルを使用する理由

プロキシーサーバーやロードバランサーなどの中間サービスが HTTP 要求を転送する際に、これは接続のソースアドレスを要求の Forwarded ヘッダーに追加して、この情報を後続の中間サービスと、要求が最終的に転送されるバックエンドサービスに提供できます。ただし、接続が暗号化されている場合、中間サービスは Forwarded ヘッダーを変更できません。この場合、要求が転送されても HTTP ヘッダーは元のソースアドレスを正確に通信することができません。

この問題を解決するために、一部のロードバランサーは、単純に HTTP を転送する代替手段として PROXY プロトコルを使用して HTTP 要求をカプセル化します。カプセル化によって、ロードバランサーは転送される要求自体を変更することなく、情報を要求に追加することができます。これにより、ロードバランサーは、暗号化された接続を転送する場合でもソースアドレスを通信できます。

HAProxy ルーターが PROXY プロトコルを受け入れ、HTTP 要求のカプセル化を解除するように設定できます。ルーターは edge および re-encrypt ルートの暗号化を終了するので、ルーターは要求の ForwardedHTTP ヘッダー (および関連する HTTP ヘッダー) を更新でき、PROXY プロトコルを使用して通信されるソースアドレスを追加できます。

警告

PROXY プロトコルと HTTP は互換性がなく、組み合わせることはできません。ルーターの前にロードバランサーを使用する場合、これらがどちらも PROXY プロトコルまたは HTTP のいずれかを使用する必要があります。一方を PROXY プロトコルを使用するように設定し、他方を HTTP を使用するように設定すると、ルーティングが失敗します。

3.4.3. PROXY プロトコルの使用

デフォルトで、HAProxy ルーターは PROXY プロトコルを使用しません。ROUTER_USE_PROXY_PROTOCOL 環境変数を使用することで、ルーターが受信接続に PROXY プロコトルの使用を予想するように設定できます。

PROXY プロコトルの有効化

$ oc set env dc/router ROUTER_USE_PROXY_PROTOCOL=true

変数を true または TRUE 以外の値に設定し、PROXY プロコトルを無効にします。

PROXY プロトコルの無効化

$ oc set env dc/router ROUTER_USE_PROXY_PROTOCOL=false

ルーターで PROXY プロトコルを有効にする場合、ルーターの前のロードバランサーが PROXY プロコトルを使用するように設定する必要があります。以下は、Amazon の Elastic Load Balancer (ELB) サービスを PROXY プロトコルを使用するように設定した例です。この例では、ELB がポート 80 (HTTP)、443 (HTTPS)、5000 (イメージレジストリーの場合) を 1 つ以上の EC2 インスタンスで実行されるルーターに転送することを想定しています。

Amazon ELB を設定して PROXY プロコトルを使用する

  1. 後続の手順を単純化するために、最初に一部の Shell 変数を設定します。

    $ lb='infra-lb' 1
    $ instances=( 'i-079b4096c654f563c' ) 2
    $ secgroups=( 'sg-e1760186' ) 3
    $ subnets=( 'subnet-cf57c596' ) 4
    1
    ELB の名前。
    2
    ルーターが実行されているインスタンス。
    3
    この ELB のセキュリティーグループ。
    4
    この ELB のサブネット。
  2. 次に、適切なリスナーやセキュリティーグループおよびサブネットを使用して ELB を作成します。

    注記

    すべてのリスナーが HTTP プロトコルではなく TCP プロトコルを使用するよう設定する必要があります。

    $ aws elb create-load-balancer --load-balancer-name "$lb" \
       --listeners \
        'Protocol=TCP,LoadBalancerPort=80,InstanceProtocol=TCP,InstancePort=80' \
        'Protocol=TCP,LoadBalancerPort=443,InstanceProtocol=TCP,InstancePort=443' \
        'Protocol=TCP,LoadBalancerPort=5000,InstanceProtocol=TCP,InstancePort=5000' \
       --security-groups $secgroups \
       --subnets $subnets
    {
        "DNSName": "infra-lb-2006263232.us-east-1.elb.amazonaws.com"
    }
  3. ルーターインスタンスを ELB に登録します。

    $ aws elb register-instances-with-load-balancer --load-balancer-name "$lb" \
       --instances $instances
    {
        "Instances": [
            {
                "InstanceId": "i-079b4096c654f563c"
            }
        ]
    }
  4. ELB のヘルスチェックを設定します。

    $ aws elb configure-health-check --load-balancer-name "$lb" \
       --health-check 'Target=HTTP:1936/healthz,Interval=30,UnhealthyThreshold=2,HealthyThreshold=2,Timeout=5'
    {
        "HealthCheck": {
            "HealthyThreshold": 2,
            "Interval": 30,
            "Target": "HTTP:1936/healthz",
            "Timeout": 5,
            "UnhealthyThreshold": 2
        }
    }
  5. 最後に、ProxyProtocol 属性を有効にしたロードバランサーのポリシーを作成し、ELB の TCP ポート 80 および 443 でポリシーを設定します。

    $ aws elb create-load-balancer-policy --load-balancer-name "$lb" \
       --policy-name "${lb}-ProxyProtocol-policy" \
       --policy-type-name 'ProxyProtocolPolicyType' \
       --policy-attributes 'AttributeName=ProxyProtocol,AttributeValue=true'
    $ for port in 80 443
      do
        aws elb set-load-balancer-policies-for-backend-server \
         --load-balancer-name "$lb" \
         --instance-port "$port" \
         --policy-names "${lb}-ProxyProtocol-policy"
      done

設定の確認

ロードバランサーを以下のように検証して、設定が正しいことを確認します。

$ aws elb describe-load-balancers --load-balancer-name "$lb" |
    jq '.LoadBalancerDescriptions| [.[]|.ListenerDescriptions]'
[
  [
    {
      "Listener": {
        "InstancePort": 80,
        "LoadBalancerPort": 80,
        "Protocol": "TCP",
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": ["infra-lb-ProxyProtocol-policy"] 1
    },
    {
      "Listener": {
        "InstancePort": 443,
        "LoadBalancerPort": 443,
        "Protocol": "TCP",
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": ["infra-lb-ProxyProtocol-policy"] 2
    },
    {
      "Listener": {
        "InstancePort": 5000,
        "LoadBalancerPort": 5000,
        "Protocol": "TCP",
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": [] 3
    }
  ]
]
1
TCP ポート 80 のリスナーには PROXY プロトコルを使用するポリシーが設定されている必要があります。
2
TCP ポート 443 のリスナーには同じポリシーが設定されている必要があります。
3
TCP ポート 5000 のリスナーにはこのポリシーを設定できません

または、ELB をすでに設定していても、PROXY プロトコルを使用するよう設定されていない場合は、 TCP ポート 80 の既存リスナーを、HTTP ではなく TCP プロコトルを使用するように変更する必要があります (TCP ポート 443 はすでに TCP プロトコルを使用しているはずです)。

$ aws elb delete-load-balancer-listeners --load-balancer-name "$lb" \
   --load-balancer-ports 80
$ aws elb create-load-balancer-listeners --load-balancer-name "$lb" \
   --listeners 'Protocol=TCP,LoadBalancerPort=80,InstanceProtocol=TCP,InstancePort=80'

プロコトル更新の確認

プロコトルが以下のように更新されていることを確認します。

$ aws elb describe-load-balancers --load-balancer-name "$lb" |
   jq '[.LoadBalancerDescriptions[]|.ListenerDescriptions]'
[
  [
    {
      "Listener": {
        "InstancePort": 443,
        "LoadBalancerPort": 443,
        "Protocol": "TCP",
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": []
    },
    {
      "Listener": {
        "InstancePort": 5000,
        "LoadBalancerPort": 5000,
        "Protocol": "TCP",
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": []
    },
    {
      "Listener": {
        "InstancePort": 80,
        "LoadBalancerPort": 80,
        "Protocol": "TCP", 1
        "InstanceProtocol": "TCP"
      },
      "PolicyNames": []
    }
  ]
]
1
TCP ポート 80 のリスナーなど、すべてのリスナーが TCP プロコトルを使用している必要があります。

次にロードバランサーポリシーを作成し、上記の手順 5 に説明されているようにこれを ELB に追加します。

第4章 Red Hat CloudForms のデプロイ

4.1. Red Hat CloudForms の OpenShift Container Platform へのデプロイ

4.1.1. はじめに

OpenShift Container Platform インストーラーには、Red Hat CloudForms 4.6 (CloudForms Management Engine 5.9 または CFME) を OpenShift Container Platform にデプロイするための Ansible ロールの openshift-management と Playbook が含まれています。

警告

現在の実装には、OpenShift Container Platform 3.6 ドキュメント で説明されているように、Red Hat CloudForms 4.5 のテクノロジープレビューのデプロイメントプロセスとの互換性はありません。

Red Hat CloudForms を OpenShift Container Platform にデプロイする際には、以下の 2 つ点について決定する必要があります。

  1. 外部またはコンテナー化された (Pod 化された とも言う) PostgreSQL データベースを使用するかどうか。
  2. 永続ボリューム (PV) をどのストレージクラスでサポートするか。

最初の点については、Red Hat CloudForms で使用する PostgreSQL データベースが置かれている場所によって Red Hat CloudForms を以下のいずれかの方法でデプロイできます。

デプロイのバリアント説明

完全コンテナー化

すべてのアプリケーションサービスと PostgreSQL データベースは、OpenShift Container Platform で Pod として実行されます。

外部データベース

アプリケーションは外部でホストされた PostgreSQL データベースサーバーを使用し、その他すべてのサービスは OpenShift Container Platform で Pod として実行されます。

2 つ目の点については、openshift-management ロールが、多くのデフォルトのデプロイメントパラメーターの上書き用にカスタマイズオプションを提供します。これには、 PV をサポートするための以下のストレージクラスのオプションが含まれています。

Storage Class説明

NFS (デフォルト)

ローカル、クラスター上

NFS (外部)

NFS の他の場所 、ストレージアプライアンスなど

クラウドプロバイダー

クラウドプロバイダー (Google Cloud Engine、Amazon Web Services、または Microsoft Azure) の自動ストレージプロビジョニングを使用

事前設定 (詳細)

ユーザーが事前にすべてを作成済みであることを前提とする

本書では、Red Hat CloudForms を OpenShift Container Platform で実行するための要件、利用可能な設定変数の説明、および OpenShift Container Platform の初回インストール時かクラスターのプロビジョニング後のいずれかでインストーラーを実行する方法などについてのトピックを扱います。

4.2. Red Hat CloudForms を OpenShift Container Platform で使用するための要件

 
デフォルトの要件は以下の表に記載されています。これらは テンプレートパラメーターをカスタマイズ して上書きできます。

重要

以下の要件を満たしていないと、アプリケーションのパフォーマンスが低下するか、またはデプロイに失敗する可能性があります。

表4.1 デフォルトの要件
項目要件説明カスタマイズパラメーター

アプリケーションメモリー

≥ 4.0 Gi

アプリケーションのメモリー最小要件

APPLICATION_MEM_REQ

アプリケーションストレージ

≥ 5.0 Gi

アプリケーションの PV サイズ最小要件

APPLICATION_VOLUME_CAPACITY

PostgreSQL メモリー

≥ 6.0 Gi

データベースのメモリー最小要件

POSTGRESQL_MEM_REQ

PostgreSQL ストレージ

≥ 15.0 Gi

データベースの PV サイズ最小要件

DATABASE_VOLUME_CAPACITY

クラスターホスト

≥ 3

クラスター内のホスト数

該当なし

以上の要件をまとめると以下のようになります。

  • ユーザーにはいくつかのクラスターノードが必要である。
  • クラスターノードには多くの利用可能なメモリーが必要である。
  • ユーザーは、ローカルまたはクラウドプロバイダーに数 GiB の利用可能なストレージを持っている必要がある。
  • PV サイズはテンプレートパラメーターの値を上書きして変更できる。

4.3. ロール変数の設定

4.3.1. 概要

以下のセクションでは、Ansible インベントリーファイル で使用されるロール変数について説明します。 ロール変数は、インストーラーを実行 する際に Red Hat CloudForms インストールの動作を制御するために使用されます。

4.3.2. 一般的な変数

変数必須デフォルト説明

openshift_management_install_management

いいえ

false

ブール値。 アプリケーションをインストールするには true に設定します。

openshift_management_app_template

はい

cfme-template

インストールする Red Hat CloudForms のデプロイメントのバリアントです。コンテナー化されたデータベースの cfme-template を設定するか、または外部データベースの cfme-template-ext-db を設定します。

openshift_management_project

いいえ

openshift-management

Red Hat CloudForms インストールの namespace (プロジェクト)。

openshift_management_project_description

いいえ

CloudForms Management Engine

namespace (プロジェクト) の説明。

openshift_management_username

いいえ

admin

デフォルトの管理ユーザー名。この値を変更してもユーザー名は変更されません。 名前をすでに変更しており、統合スクリプト (コンテナープロバイダーを追加する ためのスクリプトなど) を実行している場合にのみこの値を変更してください。

openshift_management_password

いいえ

smartvm

デフォルトの管理パスワード。この値を変更してもパスワードは変更されません。 このパスワードをすでに変更しており、統合スクリプト (コンテナープロバイダーを追加する ためのスクリプトなど) を実行している場合にのみこの値を変更してください。

4.3.3. テンプレートパラメーターのカスタマイズ

openshift_management_template_parameters Ansible ロール変数は、アプリケーションまたは PV テンプレートで上書きする必要のあるテンプレートを指定するために使用します。

たとえば、PostgreSQL Pod のメモリー要件を減らしたい場合には、以下を設定します。

openshift_management_template_parameters={'POSTGRESQL_MEM_REQ': '1Gi'}

Red Hat CloudForms テンプレートが処理される際に、1GiPOSTGRESQL_MEM_REQ テンプレートパラメーターの値に使用されます。

すべてのテンプレートパラメーターが (コンテナー化されたデータベースと外部データベースの) 両方 のテンプレートバリアントにある訳ではありません。たとえば、Pod 化されたデータベースのテンプレートには POSTGRESQL_MEM_REQ パラメーターがありますが、このパラメーターは外部のデータベーステンプレートにはありません。 そこには Pod を必要とするデータベースが存在せず、この情報は必要とされないためです。

したがって、テンプレートパラメーターを上書きする場合には十分注意する必要があります。テンプレートで定義されていないパラメーターを追加するとエラーの原因になります。管理アプリケーションの作成を確認する タスクの実行時にエラーを受信した場合は、インストーラーを再度実行する前にアンインストールのスクリプトを実行してください。

4.3.4. データベース変数

4.3.4.1. コンテナー化された (Pod 化された) データベース

cfme-template.yaml ファイルにある POSTGRES_* または DATABASE_* テンプレートパラメーターは、インベントリーファイルの openshift_management_template_parameters ハッシュを使用してカスタマイズすることができます。

4.3.4.2. 外部データベース

cfme-template-ext-db.yaml ファイルにある POSTGRES_* または DATABASE_* テンプレートパラメーターは、インベントリーファイルの openshift_management_template_parameters ハッシュを使用してカスタマイズすることができます。

外部 PostgreSQL データベースは、ユーザーにデータベース接続パラメーターを指定するように要求します。必要な接続キーはインベントリーの openshift_management_template_parameters パラメーターに設定する必要があります。必要なキー以下の通りです。

  • DATABASE_USER
  • DATABASE_PASSWORD
  • DATABASE_IP
  • DATABASE_PORT (ほとんどの PostgreSQL サーバーはポート 5432 で実行されます)
  • DATABASE_NAME
注記

外部データベースで PostgreSQL 9.5 が実行されていることを確認します。 実行されていないと、CloudForms アプリケーションを正常にデプロイできない場合があります。

インベントリーに、以下のような行が含まれているはずです。

[OSEv3:vars]
openshift_management_app_template=cfme-template-ext-db 1
openshift_management_template_parameters={'DATABASE_USER': 'root', 'DATABASE_PASSWORD': 'mypassword', 'DATABASE_IP': '10.10.10.10', 'DATABASE_PORT': '5432', 'DATABASE_NAME': 'cfme'}
1
openshift_management_app_template パラメーターを cfme-template-ext-db に設定します。

4.3.5. ストレージクラス変数

変数必須デフォルト説明

openshift_management_storage_class

いいえ

nfs

使用されるストレージのタイプ。オプションには nfsnfs_externalpreconfiguredcloudprovider があります。

openshift_management_storage_nfs_external_hostname

いいえ

false

NetApp アプライアンスなどの外部 NFS サーバーを使用している場合、ここにホスト名を設定する必要があります。外部 NFS を使用していない場合は値を false のままにしておきます。さらに外部 NFS では、ユーザーがアプリケーション PV とオプションでデータベース PV をサポートする NFS エクスポートを作成する必要があります。

openshift_management_storage_nfs_base_dir

いいえ

/exports/

外部 NFS を使用している場合、ベースパスをこのエクスポートの位置に設定できます。ローカルの NFS の場合、ローカルの NFS エクスポートに使用されているデフォルトのパスを変更する必要がある場合にも、この値を変更します。

openshift_management_storage_nfs_local_hostname

いいえ

false

[nfs] グループがインベントリーにない場合や、ローカルの NFS ホストをクラスターに手動で定義する必要がある場合は、このパラメーターを必要な NFS サーバーのホスト名に設定します。サーバーは OpenShift Container Platform クラスターの一部である必要があります。

4.3.5.1. NFS (デフォルト)

NFS ストレージクラスは、概念実証およびテストデプロイメントに最も適しています。このクラスは、デプロイメント用のデフォルトのステージクラスにもなります。これを選択した場合、追加の設定は不要です。

このストレージクラスは、必要な PV をサポートするように NFS をクラスターホスト (デフォルトではインベントリーファイルの最初のマスター) に設定します。アプリケーションは PV を必要とし、データベース (外部でホストされている可能性がある) は 2 番目の PV が必要となる場合があります。PV サイズの最小要件は、Red Hat CloudForms アプリケーションは 5GiB、PostgreSQL データベースは 15GiB です (NFS 専用で使用する場合は、ボリュームまたはパーティション上の使用可能な最小領域は 20GiB です)。

カスタマイズは、以下のロール変数を使って行われます。

  • openshift_management_storage_nfs_base_dir
  • openshift_management_storage_nfs_local_hostname
4.3.5.2. NFS (外部)

外部 NFS は、必要な PV にエクスポートを提供するために事前設定された NFS サーバーを使用します。外部 NFS の場合、ユーザーは cfme-app とオプションで cfme-db (コンテナー化されたデータベース用) のエクスポートが必要です。

設定は、以下のロール変数を使って提供されます。

  • openshift_management_storage_nfs_external_hostname
  • openshift_management_storage_nfs_base_dir

openshift_management_storage_nfs_external_hostname パラメーターは、外部 NFS サーバーのホスト名または IP に設定する必要があります。

/exports がエクスポートの親ディレクトリーではない場合、ベースディレクトリーを openshift_management_storage_nfs_base_dir パラメーターで設定する必要があります。

たとえば、サーバーエクスポートが /exports/hosted/prod/cfme-app の場合は、openshift_management_storage_nfs_base_dir=/exports/hosted/prod を設定する必要があります。

4.3.5.3. クラウドプロバイダー

ストレージクラスに OpenShift Container Platform のクラウドプロバイダー統合を使用している場合、Red Hat CloudForms は必要な PV をサポートするためにこのクラウドプロバイダーを使用することができます。これを正常に実行するには、openshift_cloudprovider_kind 変数 (AWS または GCE 用) と、ユーザーが選択したクラウドプロバイダーに固有のすべての関連パラメーターを設定している必要があります。

アプリケーションがこのストレージクラスを使って作成されている場合、必要な PV は、設定済みのクラウドプロバイダーのストレージ統合を使って自動的にプロビジョニングされます。

このストレージクラスの動作を設定するために使用される追加の変数はありません。

4.3.5.4. 事前設定 (詳細)

preconfigured (事前設定されている) ストレージクラスの場合、ユーザーは各自の操作を正確に把握しており、すべてのストレージ要件が事前に配慮されていることを意味します。つまり、一般的には正しいサイズの PV を作成されています。インストーラーは、ストレージ設定を変更する必要がありません。

このストレージクラスの動作を設定するために使用される追加の変数はありません。

4.4. インストーラーの実行

4.4.1. OpenShift Container Platform のインストール時またはインストール後の Red Hat CloudForms のデプロイ

Red Hat CloudForms のデプロイを、OpenShift Container Platform の初回インストール時か、またはクラスターのプロビジョニング後のいずれかに実行することを選択できます。

  1. openshift_management_install_management がインベントリーファイルの [OSEv3:vars] セクションの下で true に設定されていることを確認します。

    [OSEv3:vars]
    openshift_management_install_management=true
  2. インベントリーファイルにある Red Hat CloudForms のその他のロール変数を、ロール変数の設定 で説明されているように設定します。これを支援するリソースは、インベントリーファイルの例 を参照してください。
  3. OpenShift Container Platform がすでにプロビジョニングされているかどうかに応じて、実行する Playbook を選択します。

    1. Red Hat CloudForms を、OpenShift Container Platform クラスターのインストールと同時にインストールする必要がある場合には、インストール Playbook の実行 で説明されているように標準の config.yml Playbook を呼び出して、OpenShift Container Platform クラスターと Red Hat CloudForms のインストールを開始します。
    2. Red Hat CloudForms を、すでにプロビジョニングされている OpenShift Container Platform クラスターにインストールする必要がある場合には、Playbook ディレクトリーに切り替えてから Red Hat CloudForms Playbook を直接呼び出してインストールを開始します。

      $ cd /usr/share/ansible/openshift-ansible
      $ ansible-playbook -v [-i /path/to/inventory] \
          playbooks/openshift-management/config.yml

4.4.2. インベントリーファイルの例

このセクションでは、インベントリーファイルのスニペットの例について説明し、使い始めに役立つ OpenShift Container Platform での Red Hat CloudForms の各種の設定について説明します。

注記

変数の詳しい説明については、ロール変数の設定 を参照してください。

4.4.2.1. すべてのデフォルト

以下は、すべてのデフォルト値と選択肢を使用した最も単純な例です。これで、Red Hat CloudForms のインストールが完全にコンテナー化 (Pod 化) されます。すべてのアプリケーションコンポーネントと PostgreSQL データベースが OpenShift Container Platform に Pod として作成されます。

[OSEv3:vars]
openshift_management_app_template=cfme-template
4.4.2.2. 外部 NFS ストレージ

以下は、前述の例と同様に (ただしローカルの NFS サービスをクラスターで使用する代わりに)、既存の外部 NFS サーバー (ストレージアプライアンスなど) を使用しています。新しいパラメーターが 2 つある点に注意してください。

[OSEv3:vars]
openshift_management_app_template=cfme-template
openshift_management_storage_class=nfs_external 1
openshift_management_storage_nfs_external_hostname=nfs.example.com 2
1
nfs_external に設定します。
2
NFS サーバーのホスト名に設定します。

外部 NFS ホストが /exports/hosted/prod などの異なる親ディレクトリーの下でエクスポートディレクトリーをホストしている場合は、以下の変数を追加します。

openshift_management_storage_nfs_base_dir=/exports/hosted/prod
4.4.2.3. PV サイズの上書き

以下の例では、永続ボリューム (PV) のサイズを上書きします。PV サイズは openshift_management_template_parameters で設定する必要があります。 これにより、アプリケーションとデータベースは相互に干渉しあうことなく作成済みの PV で要求を実行できます。

[OSEv3:vars]
openshift_management_app_template=cfme-template
openshift_management_template_parameters={'APPLICATION_VOLUME_CAPACITY': '10Gi', 'DATABASE_VOLUME_CAPACITY': '25Gi'}
4.4.2.4. メモリー要件の上書き

テストまたは概念実証のインストールでは、アプリケーションとデータベースのメモリー要件を設定している容量内に収めるようにする必要がある場合があります。メモリーの上限を下げると、パフォーマンスが低下するか、またはアプリケーションの初期化に完全に失敗したりする可能性があることに注意してください。

[OSEv3:vars]
openshift_management_app_template=cfme-template
openshift_management_template_parameters={'APPLICATION_MEM_REQ': '3000Mi', 'POSTGRESQL_MEM_REQ': '1Gi', 'ANSIBLE_MEM_REQ': '512Mi'}

この例では、インストーラーに対し、パラメーター APPLICATION_MEM_REQ3000Mi に、POSTGRESQL_MEM_REQ1Gi に、さらに ANSIBLE_MEM_REQ512Mi に設定してアプリケーションテンプレートを処理するように指示します。

これらのパラメーターは、前述の例 PV サイズの上書き に示されているパラメーターと組み合せることができます。

4.4.2.5. 外部 PostgreSQL データベース

外部データベースを使用するには、openshift_management_app_template パラメーターの値を cfme-template-ext-db に変更する必要があります。

さらに、データベース接続情報を openshift_management_template_parameters 変数を使って入力する必要があります。詳細は、ロール変数の設定 を参照してください。

[OSEv3:vars]
openshift_management_app_template=cfme-template-ext-db
openshift_management_template_parameters={'DATABASE_USER': 'root', 'DATABASE_PASSWORD': 'mypassword', 'DATABASE_IP': '10.10.10.10', 'DATABASE_PORT': '5432', 'DATABASE_NAME': 'cfme'}
重要

PostgreSQL 9.5 が実行中であることを確認してください。 実行されていないと、アプリケーションを正常にデプロイできない場合があります。

4.5. コンテナープロバイダー統合の有効化

4.5.1. 単一コンテナープロバイダーの追加

インストーラーの実行 で説明されているように Red Hat CloudForms を OpenShift Container Platform にデプロイした後に、コンテナープロバイダーの統合を有効にする方法は 2 つあります。OpenShift Container Platform をコンテナープロバイダーとして手動で追加するか、このロールに含まれる Playbook を試してみてください。

4.5.1.1. 手動の追加

OpenShift Container Platform クラスターをコンテナープロバイダーとして手動で追加する手順については、以下の Red Hat CloudForms ドキュメントを参照してください。

4.5.1.2. 自動の追加

コンテナープロバイダーの自動的な統合は、このロールに含まれている Playbook を使用して実行できます。

この Playbook は以下を実行します。

  1. 必要な認証シークレットを収集します。
  2. Red Hat CloudForms アプリケーションとクラスター API への公開ルートを検索します。
  3. REST の呼び出しを実行し、OpenShift Container Platform クラスターをコンテナープロバイダーとして追加します。

Playbook ディレクトリーに切り替え、コンテナープロバイダーの Playbook を実行します。

$ cd /usr/share/ansible/openshift-ansible
$ ansible-playbook -v [-i /path/to/inventory] \
    openshift-management/add_container_provider.yml

4.5.2. 複数のコンテナープロバイダー

このロールには、最新の OpenShift Container Platform クラスターを Red Hat CloudForms デプロイメントに統合するための Playbook に加え、複数のコンテナープラットフォームを任意の Red Hat CloudForms サーバーに コンテナープロバイダーとして追加することを可能にするスクリプトが含まれています。コンテナープラットフォームは、OpenShift Container Platform または OpenShift Origin です。

複数のプロバイダースクリプトを使用する場合、Playbook の実行時に EXTRA_VARS パラメーターを CLI に手動で設定することが必要になります。

4.5.2.1. スクリプトの作成

複数のプロバイダースクリプトを作成するには、以下の手動の設定を実行します。

  1. /usr/share/ansible/openshift-ansible/roles/openshift_management/files/examples/container_providers.yml のサンプルを、/tmp/cp.yml など別の場所にコピーします。このファイルは後で変更します。
  2. Red Hat CloudForms の名前またはパスワードを変更している場合は、コピーしたcontainer_providers.yml ファイルの management_server キーにある hostnameuser および password の各パラメーターを更新します。
  3. コンテナープロバイダーとして追加する必要のある各 Container Platform クラスターについて、container_providers キーの下にエントリーを入力します。

    1. 以下のパラメーターを設定する必要があります。

      • auth_key - cluster-admin 権限を持つサービスアカウントのトークンです。
      • hostname - クラスター API をポイントしているホスト名です。各コンテナープロバイダーは固有のホスト名を持っている必要があります。
      • name - Red Hat CloudForms サーバーのコンテナープロバイダーの概要ページに表示されるクラスター名です。この名前は固有でなければなりません。
      ヒント

      auth_key ベアラートークンをクラスターから取得するには、以下を実行します。

      $ oc serviceaccounts get-token -n management-infra management-admin
    2. 以下のパラメーターは任意で設定することができます。

      • port - Container Platform クラスターが API を 8443 以外のポートで実行している場合は、このキーを更新します。
      • endpoint - SSL 検証を有効にする (verify_ssl) か、または検証設定を ssl-with-validation に変更することができます。現時点では、カスタムの信頼される CA 証明書のサポートは利用できません。
4.5.2.1.1. 例

例として以下のシナリオを見てみましょう。

  • container_providers.yml ファイルを /tmp/cp.yml にコピーしている。
  • 2 つの OpenShift Container Platform クラスターを追加する必要がある。
  • Red Hat CloudForms サーバーが mgmt.example.com で実行されている。

このシナリオでは、/tmp/cp.yml を以下のようにカスタマイズします。

container_providers:
  - connection_configurations:
      - authentication: {auth_key: "<token>", authtype: bearer, type: AuthToken} 1
        endpoint: {role: default, security_protocol: ssl-without-validation, verify_ssl: 0}
    hostname: "<provider_hostname1>"
    name: <display_name1>
    port: 8443
    type: "ManageIQ::Providers::Openshift::ContainerManager"
  - connection_configurations:
      - authentication: {auth_key: "<token>", authtype: bearer, type: AuthToken} 2
        endpoint: {role: default, security_protocol: ssl-without-validation, verify_ssl: 0}
    hostname: "<provider_hostname2>"
    name: <display_name2>
    port: 8443
    type: "ManageIQ::Providers::Openshift::ContainerManager"
management_server:
  hostname: "<hostname>"
  user: <user_name>
  password: <password>
1 2
<token> をこのクラスターの管理トークンに置き換えます。
4.5.2.2. Playbook の実行

複数プロバイダー統合スクリプトを実行するには、コンテナープロバイダーの設定ファイルへのパスを EXTRA_VARS パラメーターとして ansible-playbook コマンドに指定する必要があります。container_providers_config を設定ファイルパスに設定するには、-e (または --extra-vars) パラメーターを使用します。Playbook ディレクトリーに切り替えて Playbook を実行します。

$ cd /usr/share/ansible/openshift-ansible
$ ansible-playbook -v [-i /path/to/inventory] \
    -e container_providers_config=/tmp/cp.yml \
    playbooks/openshift-management/add_many_container_providers.yml

Playbook が完成すると、Red Hat CloudForms サービスに 2 つの新しいコンテナープロバイダーが見つかるはずです。コンピュート → コンテナー → プロバイダー の順にページを進んで概要を確認してください。

4.5.3. プロバイダーの更新

単一または複数のコンテナープロバイダーを追加したら、新規プロバイダーを Red Hat CloudForms で更新し、コンテナープロバイダーと管理されているコンテナーに関する最新データをすべて取得する必要があります。そのためには、Red Hat CloudForms Web コンソールの各プロバイダーに進み、それぞれについて更新ボタンをクリックします。

手順については、以下の Red Hat CloudForms ドキュメントを参照してください。

4.6. Red Hat CloudForms のアンインストール

4.6.1. アンインストール Playbook の実行

デプロイした Red Hat CloudForms インストールを OpenShift Container Platform からアンインストールして削除するには、Playbook ディレクトリーに切り替え、uninstall.yml Playbook を実行します。

$ cd /usr/share/ansible/openshift-ansible
$ ansible-playbook -v [-i /path/to/inventory] \
    playbooks/openshift-management/uninstall.yml
重要

NFS エクスポートの定義と NFS エクスポートに格納されているデータは自動的に削除されません。新規デプロイメントの初期化を試行する前に、古いアプリケーションまたはデータベースデプロイメントのデータを手動で消去することが推奨されます。

4.6.2. トラブルシューティング

古い PostgreSQL データの消去に失敗すると連鎖的なエラーが発生し、postgresql Pod が crashloopbackoff の状態になる可能性があります。この状態になると cfme Pod の起動が阻止されます。crashloopbackoff は、以前のデプロイ時に作成されたデータベース NFS エクスポートの不正なファイル権限に起因します。

次に進むには、PostgreSQL エクスポートからすべてのデータを削除し、Pod (デプロイヤー Pod ではない) を削除します。以下の Pod がある場合の例を示します。

$ oc get pods
NAME                 READY     STATUS             RESTARTS   AGE
httpd-1-cx7fk        1/1       Running            1          21h
cfme-0               0/1       Running            1          21h
memcached-1-vkc7p    1/1       Running            1          21h
postgresql-1-deploy  1/1       Running            1          21h
postgresql-1-6w2t4   0/1       CrashLoopBackOff   1          21h

この場合、以下を実行します。

  1. データベース NFS エクスポートのデータを消去します。
  2. 以下を実行します。

    $ oc delete postgresql-1-6w2t4

PostgreSQL デプロイヤー Pod は、削除した Pod を置き換えるために新規の postgresql Pod の拡張を試みます。postgresql Pod が実行された後に、cfme Pod は阻止する操作を停止し、アプリケーションの初期化を開始します。

第5章 Prometheus クラスターモニタリング

5.1. 概要

OpenShift Container Platform には、Prometheus オープンソースプロジェクトおよびその幅広いエコシステムをベースとする事前に設定された、自己更新型のモニターリングスタックが同梱されます。これは、クラスターコンポーネントのモニターリング機能を提供し、一連のアラートと共に提供されるためにクラスター管理者に対して問題の発生について即時に通知し、一連の Grafana ダッシュボードを提供します。

monitoring diagram

上図でハイライトされているように、OpenShift Container Platform Cluster Monitoring Operator (CMO) はモニターリングスタックの中心に位置します。 これは、デプロイされたモニターリングコンポーネントおよびリソースを監視し、それらが最新の状態にあることを確認します。

Prometheus Operator (PO) は、Prometheus および Alertmanager インスタンスを作成し、設定し、管理します。また、Kubernetes ラベルのクエリーに基づいてモニタリングターゲットの設定を自動生成します。

Prometheus および Alertmanager に加えて、OpenShift Container Platform Monitoring には node-exporter および kube-state-metrics も含まれます。Node-exporter は、ノードについてのメトリクスを収集するために各ノードにデプロイされるエージェントです。kube-state-metrics exporter エージェントは、Kubernetes オブジェクトを Prometheus で消費できるメトリクスに変換します。

クラスターモニターリングの一部としてモニターされるターゲットには、以下が含まれます。

  • Prometheus 自体
  • Prometheus-Operator
  • cluster-monitoring-operator
  • Alertmanager クラスターインスタンス
  • Kubernetes apiserver
  • kubelet (コンテナーメトリクス用に kubelet で組み込まれる cAdvisor)
  • kube-controllers
  • kube-state-metrics
  • node-exporter
  • etcd (etcd モニターリングが有効にされる場合)

これらのコンポーネントはすべて自動的に更新されます。

OpenShift Container Platform Cluster Monitoring Operator についての詳細は、Cluster Monitoring Operator GitHub プロジェクトを参照してください。

注記

互換性が保証された更新を提供できるようにするため、OpenShift Container Platform Monitoring スタックの設定は明示的に利用可能なオプションのみに制限されます。

5.2. OpenShift Container Platform クラスターモニターリングの設定

OpenShift Container Platform の Ansible openshift_cluster_monitoring_operator ロールは、インベントリーファイル の変数を使用して Cluster Monitoring Operator を設定し、デプロイします。

表5.1 Ansible 変数
変数説明

openshift_cluster_monitoring_operator_install

true の場合に Cluster Monitoring Operator をデプロイします。そうでない場合はデプロイ解除します。この変数は、デフォルトで true に設定されます。

openshift_cluster_monitoring_operator_prometheus_storage_capacity

各 Prometheus インスタンスの Persistent Volume Claim (永続ボリューム要求、PVC) のサイズです。変数は、openshift_cluster_monitoring_operator_prometheus_storage_enabledtrue に設定される場合にのみ適用されます。デフォルトは 50Gi に設定されます。

openshift_cluster_monitoring_operator_alertmanager_storage_capacity

各 Alertmanager インスタンスの Persistent Volume Claim (永続ボリューム要求、PVC) のサイズです。変数は、openshift_cluster_monitoring_operator_alertmanager_storage_enabledtrue に設定されている場合にのみ適用されます。デフォルトは 2Gi に設定されます。

openshift_cluster_monitoring_operator_node_selector

必要な既存の ノードセレクター を設定して、Pod が特定のラベルを持つノードに配置されるようにします。デフォルトは node-role.kubernetes.io/infra=true になります。

openshift_cluster_monitoring_operator_alertmanager_config

Alertmanager を設定します。

openshift_cluster_monitoring_operator_prometheus_storage_enabled

Prometheus の時系列データの永続ストレージを有効にします。この変数は、デフォルトで false に設定されます。

openshift_cluster_monitoring_operator_alertmanager_storage_enabled

Alertmanager の通知および非通知 (silences) の永続ストレージを有効にします。この変数は、デフォルトで false に設定されます。

openshift_cluster_monitoring_operator_prometheus_storage_class_name

openshift_cluster_monitoring_operator_prometheus_storage_enabled オプションを有効にしている場合、特定の StorageClass を設定して、Pod がその storageclassPVC を使用するように設定されていることを確認します。デフォルトは none に設定され、これによりデフォルトのストレージクラス名が適用されます。

openshift_cluster_monitoring_operator_alertmanager_storage_class_name

openshift_cluster_monitoring_operator_alertmanager_storage_enabled オプションを有効にしている場合、特定の StorageClass を設定し、Pod がその storageclassPVC を使用するように設定されていることを確認します。デフォルトは none に設定され、これによりデフォルトのストレージクラス名が適用されます。

5.2.1. モニターリングの前提条件

モニタリングスタックには、追加のリソース要件があります。詳細は、コンピューティングリソースについての推奨事項 を参照してください。

5.2.2. モニターリングスタックのインストール

モニターリングスタックは、デフォルトで OpenShift Container Platform と共にインストールされます。これがインストールされないようにすることもできます。これを実行するには、Ansible インベントリーファイルでこの変数を false に設定します。

openshift_cluster_monitoring_operator_install

以下でこれを実行できます。

$ ansible-playbook [-i </path/to/inventory>] <OPENSHIFT_ANSIBLE_DIR>/playbooks/openshift-monitoring/config.yml \
   -e openshift_cluster_monitoring_operator_install=False

Ansible ディレクトリーの共通パスは /usr/share/ansible/openshift-ansible/ です。この場合、設定ファイルへのパスは /usr/share/ansible/openshift-ansible/playbooks/openshift-monitoring/config.yml になります。

5.2.3. 永続ストレージ

クラスターモニターリングを永続ストレージと共に実行すると、メトリクスは 永続ボリューム に保存され、再起動または再作成される Pod を維持できます。これは、メトリクスデータまたはアラートデータをデータ損失から保護する必要がある場合に適しています。実稼働環境では、ブロックストレージテクノロジー を使用して永続ストレージを設定することを強く推奨します。

5.2.3.1. 永続ストレージの有効化

デフォルトで、永続ストレージは Prometheus の時系列データおよび Alertmanager の通知および非通知 (silences) の両方に対して無効にされます。クラスターを、それらのいずれかまたは両方を永続的に保存するように設定することができます。

  • Prometheus 時系列データの永続ストレージを有効にするには、Ansible インベントリーファイルでこの変数を true に設定します。

    openshift_cluster_monitoring_operator_prometheus_storage_enabled

  • Alertmanager 通知および非通知 (silences) の永続ストレージを有効にするには、Ansible インベントリーファイルでこの変数を true に設定します。

    openshift_cluster_monitoring_operator_alertmanager_storage_enabled

5.2.3.2. 必要なストレージサイズの判別

必要な永続ストレージは Pod 数によって異なります。ディスクが一杯にならないように十分なストレージを確保することは管理者の責任です。永続ストレージのシステム要件については、Capacity Planning for Cluster Monitoring Operator を参照してください。

5.2.3.3. 永続ストレージサイズの設定

Prometheus および Alertmanager の Persistent Volume Claim (永続ボリューム要求、PVC) のサイズを指定するには、以下の Ansible 変数を変更します。

  • openshift_cluster_monitoring_operator_prometheus_storage_capacity (デフォルト: 50Gi)
  • openshift_cluster_monitoring_operator_alertmanager_storage_capacity (デフォルト: 2Gi)

上記の変数のそれぞれは、対応する storage_enabled 変数が true に設定されている場合にのみ適用されます。

5.2.3.4. 十分な永続ボリュームの割り当て

動的にプロビジョニングされるストレージを使用しない限り、PVC で要求される永続ボリューム (PV) が利用できる状態にあることを確認する必要があります。各レプリカに 1 つの PV が必要です。 Prometheus には 2 つのレプリカがあり、Alertmanager には 3 つのレプリカがあるため、合計で 5 つの PV が必要になります。

5.2.3.5. 動的にプロビジョニングされたストレージの有効化

静的にプロビジョニングされたストレージの代わりに、動的にプロビジョニングされたストレージを使用できます。詳細は、Dynamic Volume Provisioning を参照してください。

Prometheus および Alertmanager の動的ストレージを有効にするには、Ansible インベントリーファイルで以下のパラメーターを true に設定します。

  • openshift_cluster_monitoring_operator_prometheus_storage_enabled (Default: false)
  • openshift_cluster_monitoring_operator_alertmanager_storage_enabled (Default: false)

動的ストレージを有効にした後に、Ansible インベントリーファイルの以下のパラメーターで、各コンポーネントの Persistent Volume Claim (永続ボリューム要求、PVC) に storageclass を設定することもできます。

  • openshift_cluster_monitoring_operator_prometheus_storage_class_name (デフォルト: "")
  • openshift_cluster_monitoring_operator_alertmanager_storage_class_name (デフォルト: "")

上記の変数のそれぞれは、対応する storage_enabled 変数が true に設定されている場合にのみ適用されます。

5.2.4. サポートされる設定

OpenShift Container Platform モニターリングの設定は、本書で説明されているオプションを使用して行う方法がサポートされている方法です。このような明示的な設定オプション以外に、追加の設定をスタックに挿入できます。ただし、設定のパラダイムが Prometheus リリース間で変更される可能性があるので、これはサポートされていません。このような変更には、設定のすべての可能性が制御されている場合のみ適切に対応できます。

明示的にサポート対象外とされているケースには、以下が含まれます。

  • 追加の ServiceMonitor オブジェクトを openshift-monitoring namespace に作成する。これにより、クラスターをモニターリングする Prometheus インスタンスの収集ターゲットが拡張されます。 これは、認識不可能な競合および負荷の差異を生じさせるため、Prometheus のセットアップは不安定になる可能性があります。
  • 追加の ConfigMap オブジェクトを作成する。これにより、クラスターをモニターリングする Prometheus インスタンスに追加のアラートおよび記録ルールが組み込まれます。 Prometheus 2.0 は新規のルールファイル構文と共に提供されるため、この動作は互換性を失わせる可能性のある動作を引き起すものとして知られている点に注意してください。

5.3. Alertmanager の設定

Alertmanager は受信アラートを管理し、これには、非通知 (silencing)、抑制 (inhibition)、集計 (aggregation)、およびメール、PagerDuty、および HipChat などの方法での通知の送信が含まれます。

OpenShift Container Platform Monitoring Alertmanager クラスターのデフォルト設定:

  global:
    resolve_timeout: 5m
  route:
    group_wait: 30s
    group_interval: 5m
    repeat_interval: 12h
    receiver: default
    routes:
    - match:
        alertname: DeadMansSwitch
      repeat_interval: 5m
      receiver: deadmansswitch
  receivers:
  - name: default
  - name: deadmansswitch

この設定は、openshift_cluster_monitoring_operator ロールで Ansible 変数 openshift_cluster_monitoring_operator_alertmanager_config を使用して上書きできます。

以下の例では、PagerDuty で通知を設定しています。service_key を取得する方法については、PagerDuty ドキュメントの Alertmanager についての記述を参照してください。

openshift_cluster_monitoring_operator_alertmanager_config: |+
  global:
    resolve_timeout: 5m
  route:
    group_wait: 30s
    group_interval: 5m
    repeat_interval: 12h
    receiver: default
    routes:
    - match:
        alertname: DeadMansSwitch
      repeat_interval: 5m
      receiver: deadmansswitch
    - match:
        service: example-app
      routes:
      - match:
          severity: critical
        receiver: team-frontend-page
  receivers:
  - name: default
  - name: deadmansswitch
  - name: team-frontend-page
    pagerduty_configs:
    - service_key: "<key>"

サブルートは重大度 (severity) が critical のアラートに対してのみ一致し、それらを team-frontend-page という receiver 経由で送信します。この名前が示すように、critical アラートについては、その送信先を設定する必要があります。各種のアラートレシーバー経由でアラートを設定する方法については、Alertmanager configuration を参照してください。

5.3.1. Dead man's switch

OpenShift Container Platform Monitoring には、モニターする側のインフラストラクチャーの可用性が確保するためのDead man's switchという機能が同梱されています。

Dead man's switch は、常にトリガーする単純な Prometheus アラートルールです。Alertmanager は、Dead man's switch の通知を、この機能をサポートする通知プロバイダーに絶えず送信します。また、これは Alertmanager と通知プロバイダー間の通信が機能していることを確認します。

この仕組みは、モニターリングシステム自体が停止した場合にアラートを発行するために PagerDuty によってサポートされています。詳細は、後続の Dead man's switch PagerDuty を参照してください。

5.3.2. アラートのグループ化

アラートが Alertmanager に対して発行される際に、Alertmanager はそれらを論理的にグループ化するよう設定される必要があります。

この例では、新規ルートが frontend チームのアラートルートを反映するように追加されます。

手順

  1. 新規ルートを追加します。複数のルートが元のルートの下に追加される場合がありますが、通常ルートは通知の receiver を定義するために追加されます。以下の例では、Matcher を使用してサービス example-app から送られるアラートのみが使用されるようにします。

    global:
      resolve_timeout: 5m
    route:
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 12h
      receiver: default
      routes:
      - match:
          alertname: DeadMansSwitch
        repeat_interval: 5m
        receiver: deadmansswitch
      - match:
          service: example-app
        routes:
        - match:
            severity: critical
          receiver: team-frontend-page
    receivers:
    - name: default
    - name: deadmansswitch

    サブルートは重大度 (severity) が critical のアラートに対してのみ一致し、それらを team-frontend-page という receiver 経由で送信します。この名前が示すように、critical アラートについては、その送信先を設定する必要があります。

5.3.3. Dead man's switch PagerDuty

PagerDuty は、Dead Man's Snitch という統合によりこの仕組みをサポートしています。単純に PagerDuty 設定をデフォルトの deadmansswitch receiver に追加します。上記のプロセスを使用してこの設定を追加します。

Dead Man's Snitch を、Dad Man's Switch アラートが 15 分間サイレントな場合に Operator を呼び出すように設定します。デフォルトの Alertmanager 設定では、Dead Man's Switch アラートは 5 分ごとに繰り返されます。Dead Man's Snitch が 15 分後にトリガーされる場合、これは通知が少なくとも 2 回失敗したことを示します。

configure Dead Man's Snitch を PagerDuty に設定する方法 について参照してください。

5.3.4. アラートルール

OpenShift Container Platform Cluster Monitoring には、デフォルトで設定される以下のアラートルールが同梱されます。現時点で、カスタムアラートルールを追加することはできません。

一部のアラートルールには同じ名前が付けられています。これは意図的な理由によるものです。これらのルールは、それぞれのしきい値、それぞれの重大度 (severity) またはそれらの両方を使って同じイベントについてのアラートを送ります。抑制ルールを使用すると、高い重大度のアラートが発生する場合に重大度の低いアラートが抑制されます。

アラートルールについての詳細は、configuration file を参照してください。

アラート重要度説明

ClusterMonitoringOperatorErrors

critical

Cluster Monitoring Operator で X% エラーが発生している。

AlertmanagerDown

critical

Alertmanager が Prometheus のターゲット検出に表示されない。

ClusterMonitoringOperatorDown

critical

ClusterMonitoringOperator が Prometheus のターゲット検出に表示されない。

KubeAPIDown

critical

KubeAPI が Prometheus のターゲット検出に表示されない。

KubeControllerManagerDown

critical

KubeControllerManager が Prometheus のターゲット検出に表示されない。

KubeSchedulerDown

critical

KubeScheduler が Prometheus のターゲット検出に表示されない。

KubeStateMetricsDown

critical

KubeStateMetrics が Prometheus のターゲット検出に表示されない。

KubeletDown

critical

Kubelet が Prometheus のターゲット検出に表示されない。

NodeExporterDown

critical

NodeExporter が Prometheus のターゲット検出に表示されない。

PrometheusDown

critical

Prometheus が Prometheus のターゲット検出に表示されない。

PrometheusOperatorDown

critical

PrometheusOperator が Prometheus のターゲット検出に表示されない。

KubePodCrashLooping

critical

Namespace/Pod (コンテナー) が再起動している (回数 / 秒)。

KubePodNotReady

critical

Namespace/Pod の準備ができていない。

KubeDeploymentGenerationMismatch

critical

デプロイメント Namespace/Deployment 生成の不一致。

KubeDeploymentReplicasMismatch

critical

デプロイメント Namespace/Deployment レプリカの不一致。

KubeStatefulSetReplicasMismatch

critical

StatefulSet Namespace/StatefulSet レプリカの不一致。

KubeStatefulSetGenerationMismatch

critical

StatefulSet Namespace/StatefulSet 生成の不一致。

KubeDaemonSetRolloutStuck

critical

必要な Pod の X% のみがスケジュールされており、daemon set Namespace/DaemonSet に対して準備ができている。

KubeDaemonSetNotScheduled

warning

daemonset Namespace/DaemonSet の多数の Pod がスケジュールされていない。

KubeDaemonSetMisScheduled

warning

daemonset Namespace/DaemonSet の多数の Pod が実行される場所ではない場所で実行されている。

KubeCronJobRunning

warning

CronJob Namespace/CronJob の完了に 1 時間を超える時間がかかる。

KubeJobCompletion

warning

ジョブ Namespaces/Job の完了に 1 時間を超える時間がかかる。

KubeJobFailed

warning

ジョブ Namespaces/Job を完了できない。

KubeCPUOvercommit

warning

Pod でのオーバーコミットされた CPU リソース要求がノードの失敗を許容できない。

KubeMemOvercommit

warning

Pod でのオーバーコミットされたメモリーリソース要求がノードの失敗を許容できない。

KubeCPUOvercommit

warning

Namespace でのオーバーコミットされた CPU リソース要求のクォータ。

KubeMemOvercommit

warning

Namespace でのオーバーコミットされたメモリーリソース要求のクォータ。

alerKubeQuotaExceeded

warning

namespace Namespace での ResourceX% 使用されている。

KubePersistentVolumeUsageCritical

critical

namespace NamespacePersistentVolumeClaim で要求される永続ボリュームに X% の空きがある。

KubePersistentVolumeFullInFourDays

critical

直近のサンプリングにより、namespace NamespacePersistentVolumeClaim で要求される永続ボリュームが 4 日以内で一杯になることが予想される。現時点で X バイトが利用可能。

KubeNodeNotReady

warning

Node が 1 時間を経過しても準備状態にならない。

KubeVersionMismatch

warning

Kubernetes コンポーネントの X 種類のバージョンが実行中である。

KubeClientErrors

warning

Kubernetes API サーバークライアントの 'Job/Instance' で X% エラーが発生している。

KubeClientErrors

warning

Kubernetes API サーバークライアントの 'Job/Instance' で毎秒 X エラーが発生している。

KubeletTooManyPods

warning

Kubelet Instance が上限の 110 に近い X Pod を実行している。

KubeAPILatencyHigh

warning

API サーバーに Verb Resource について 99 番目のパーセンタイルのレイテンシー X 秒がある。

KubeAPILatencyHigh

critical

API サーバーに Verb Resource について 99 番目のパーセンタイルのレイテンシー X 秒がある。

KubeAPIErrorsHigh

critical

API サーバーで X% の要求についてエラーが生じている。

KubeAPIErrorsHigh

warning

API サーバーで X% の要求についてエラーが生じている。

KubeClientCertificateExpiration

warning

Kubernetes API 証明書の有効期限が 7 日以内に切れる。

KubeClientCertificateExpiration

critical

Kubernetes API 証明書の有効期限が 1 日以内に切れる。

AlertmanagerConfigInconsistent

critical

要約: 設定の同期が取れていない。説明: Alertmanager クラスター Service のインスタンスの設定の同期が取れていない。

AlertmanagerFailedReload

warning

要約: Alertmanager の設定のリロードが失敗。説明: Alertmanager の設定のリロードが Namespace/Pod に対して失敗する。

TargetDown

warning

要約: ターゲットがダウンしている。説明: X% の Job ターゲットがダウンしている。

DeadMansSwitch

none

要約: DeadMansSwitch のアラート。説明: アラートパイプライン全体が機能することを確認するための DeadMansSwitch。

NodeDiskRunningFull

warning

node-exporter Namespace/Pod のデバイス Device が 24 時間以内に一杯の状態で実行される。

NodeDiskRunningFull

critical

node-exporter Namespace/Pod のデバイス Device が 2 時間以内に一杯の状態で実行される。

PrometheusConfigReloadFailed

warning

要約: Prometheus の設定のリロードに失敗。説明: Prometheus の設定が Namespace/Pod に対して失敗した。

PrometheusNotificationQueueRunningFull

warning

要約: Prometheus のアラート通知キューが一杯の状態で実行されている。説明: Prometheus のアラート通知キューが Namespace/Pod に対して一杯の状態で実行されている。

PrometheusErrorSendingAlerts

warning

要約: Prometheus からのアラートの送信時のエラー。説明: アラートの Prometheus Namespace/Pod から Alertmanager Alertmanager への送信時のエラー。

PrometheusErrorSendingAlerts

critical

要約: Prometheus からのアラートの送信時のエラー。説明: アラートの Prometheus Namespace/Pod から Alertmanager Alertmanager への送信時のエラー。

PrometheusNotConnectedToAlertmanagers

warning

要約: Prometheus が Alertmanager に接続されていない。説明: Prometheus Namespace/Pod が Alertmanager に接続されていない。

PrometheusTSDBReloadsFailing

warning

要約: Prometheus にディスクからのデータブロックのリロードの問題がある。説明: InstanceJob で、4 時間以内に X のリロードの問題が発生。

PrometheusTSDBCompactionsFailing

warning

要約: Prometheus でサンプルブロックのコンパクト化の問題がある。説明: InstanceJob で、4 時間以内に X のコンパクト化の問題が発生。

PrometheusTSDBWALCorruptions

warning

要約: Prometheus ログ先行書き込みが破損している。説明: InstanceJob に破損したログ先行書き込み (WAL) がある。

PrometheusNotIngestingSamples

warning

要約: Prometheus がサンプルを取り入れていない。説明: Prometheus Namespace/Pod がサンプルを取り入れていない。

PrometheusTargetScrapesDuplicate

warning

要約: Prometheus の多くのサンプルが拒否されている。説明: Namespace/Pod には、重複したタイムスタンプ (ただし異なる値を含む) により多くのサンプルが拒否されている。

EtcdInsufficientMembers

critical

Etcd クラスター "Job": メンバーが不十分 (X)。

EtcdNoLeader

critical

Etcd クラスター "Job": メンバー Instance にリーダーがない。

EtcdHighNumberOfLeaderChanges

warning

Etcd クラスター "Job": インスタンス Instance で 1 時間以内に X leader 変更が生じる。

EtcdHighNumberOfFailedGRPCRequests

warning

Etcd クラスター "Job": GRPC_Method についての X% の要求が etcd インスタンス Instance で失敗。

EtcdHighNumberOfFailedGRPCRequests

critical

Etcd クラスター "Job": GRPC_Method についての X% の要求が etcd インスタンス Instance で失敗。

EtcdGRPCRequestsSlow

critical

Etcd クラスター "Job": GRPC_Method の gRPC 要求に X_s on etcd instance _Instance がかかっている。

EtcdMemberCommunicationSlow

warning

Etcd クラスター "Job": To とのメンバー通信に X_s on etcd instance _Instance がかかっている。

EtcdHighNumberOfFailedProposals

warning

Etcd クラスター "Job": etcd インスタンス Instance での 1 時間以内の X proposal の失敗。

EtcdHighFsyncDurations

warning

Etcd クラスター "Job": 99 番目のパーセンタイルの fync 期間は X_s on etcd instance _Instance

EtcdHighCommitDurations

warning

Etcd クラスター "Job": 99 番目のパーセンタイルのコミット期間 X_s on etcd instance _Instance.

FdExhaustionClose

warning

Job インスタンス Instance がそのファイル記述子をすぐに使い切る。

FdExhaustionClose

critical

Job インスタンス Instance がそのファイル記述子をすぐに使い切る。

5.4. etcd モニターリングの設定

etcd サービスが正常に実行されない場合、OpenShift Container Platform クラスター全体の運用に支障が及ぶ可能性があります。そのため、etcd のモニターリングを設定することができます。

以下の手順に従って etcd モニターリングを設定します。

手順

  1. モニターリングスタックが実行中であることを確認します。

    $ oc -n openshift-monitoring get pods
    NAME                                           READY     STATUS              RESTARTS   AGE
    alertmanager-main-0                            3/3       Running             0          34m
    alertmanager-main-1                            3/3       Running             0          33m
    alertmanager-main-2                            3/3       Running             0          33m
    cluster-monitoring-operator-67b8797d79-sphxj   1/1       Running             0          36m
    grafana-c66997f-pxrf7                          2/2       Running             0          37s
    kube-state-metrics-7449d589bc-rt4mq            3/3       Running             0          33m
    node-exporter-5tt4f                            2/2       Running             0          33m
    node-exporter-b2mrp                            2/2       Running             0          33m
    node-exporter-fd52p                            2/2       Running             0          33m
    node-exporter-hfqgv                            2/2       Running             0          33m
    prometheus-k8s-0                               4/4       Running             1          35m
    prometheus-k8s-1                               0/4       ContainerCreating   0          21s
    prometheus-operator-6c9fddd47f-9jfgk           1/1       Running             0          36m
  2. クラスターモニターリングスタックの設定ファイルを開きます。

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  3. config.yaml: |+ の下に、etcd セクションを追加します。

    1. マスターノードの静的 Pod で etcd を実行する場合、セレクターを使用して etcd ノードを指定できます。

      ...
      data:
        config.yaml: |+
          ...
          etcd:
            targets:
              selector:
                openshift.io/component: etcd
                openshift.io/control-plane: "true"
    2. 別のホストで etcd を実行する場合、IP アドレスを使用してノードを指定する必要があります。

      ...
      data:
        config.yaml: |+
          ...
          etcd:
            targets:
             ips:
             - "127.0.0.1"
             - "127.0.0.2"
             - "127.0.0.3"

      etcd ノードの IP アドレスが変更される場合は、この一覧を更新する必要があります。

  4. etcd サービスモニターが実行されていることを確認します。

    $ oc -n openshift-monitoring get servicemonitor
    NAME                  AGE
    alertmanager          35m
    etcd                  1m 1
    kube-apiserver        36m
    kube-controllers      36m
    kube-state-metrics    34m
    kubelet               36m
    node-exporter         34m
    prometheus            36m
    prometheus-operator   37m
    1
    etcd サービスモニター。

    etcd サービスモニターが起動するには 1 分程度の時間がかかる場合があります。

  5. これで、Web インターフェイスに移動して etcd モニターリングのステータスについての詳細を確認できます。

    1. URL を取得するには、以下を実行します。

      $ oc -n openshift-monitoring get routes
      NAME                HOST/PORT                                                                           PATH      SERVICES            PORT      TERMINATION   WILDCARD
      ...
      prometheus-k8s      prometheus-k8s-openshift-monitoring.apps.msvistun.origin-gce.dev.openshift.com                prometheus-k8s      web       reencrypt     None
    2. https を使用して、prometheus-k8s について一覧表示されている URL に移動します。ログインします。
  6. ユーザーが cluster-monitoring-view ロールに属することを確認します。このロールは、クラスターモニターリング UI を表示するためのアクセスを提供します。

    たとえば、ユーザー developercluster-monitoring-view ロールに追加するには、以下を実行します。

    $ oc adm policy add-cluster-role-to-user cluster-monitoring-view developer
  7. Web インターフェイスで、cluster-monitoring-view ロールに属するユーザーとしてログインします。
  8. Status をクリックしてから Targets をクリックします。etcd エントリーが表示される場合、etcd はモニターされています。

    etcd no certificate
  9. etcd がモニターされていても、Prometheus はまだ etcd に対して認証できないため、メトリックスを収集できません。

    Prometheus 認証を etcd に対して設定するには、以下を実行します。

    1. /etc/etcd/ca/ca.crt および /etc/etcd/ca/ca.key 認証情報ファイルをマスターノードからローカルマシンにコピーします。

      $ ssh -i gcp-dev/ssh-privatekey cloud-user@35.237.54.213
    2. 以下の内容を含む openssl.cnf ファイルを作成します。

      [ req ]
      req_extensions = v3_req
      distinguished_name = req_distinguished_name
      [ req_distinguished_name ]
      [ v3_req ]
      basicConstraints = CA:FALSE
      keyUsage = nonRepudiation, keyEncipherment, digitalSignature
      extendedKeyUsage=serverAuth, clientAuth
    3. etcd.key プライベートキーファイルを生成します。

      $ openssl genrsa -out etcd.key 2048
    4. etcd.csr 証明書署名要求ファイルを生成します。

      $ openssl req -new -key etcd.key -out etcd.csr -subj "/CN=etcd" -config openssl.cnf
    5. etcd.crt 証明書ファイルを生成します。

      $ openssl x509 -req -in etcd.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out etcd.crt -days 365 -extensions v3_req -extfile openssl.cnf
    6. 認証情報を OpenShift Container Platform で使用される形式で配置します。

      $ cat <<-EOF > etcd-cert-secret.yaml
      apiVersion: v1
      data:
        etcd-client-ca.crt: "$(cat ca.crt | base64 --wrap=0)"
        etcd-client.crt: "$(cat etcd.crt | base64 --wrap=0)"
        etcd-client.key: "$(cat etcd.key | base64 --wrap=0)"
      kind: Secret
      metadata:
        name: kube-etcd-client-certs
        namespace: openshift-monitoring
      type: Opaque
      EOF

      これにより、etcd-cert-secret.yaml ファイルが作成されます。

    7. 認証情報ファイルをクラスターに適用します。

      $ oc apply -f etcd-cert-secret.yaml
  10. 認証を設定してから、Web インターフェイスの Targets ページに再度アクセスします。etcd が正常にモニターされていることを確認します。変更が有効になるまでに数分の時間がかかる場合があります。

    etcd monitoring working
  11. OpenShift Container Platform の更新時に etcd モニターリングを自動的に更新する必要がある場合、Ansible インベントリーファイルのこの変数を true に設定します。

    openshift_cluster_monitoring_operator_etcd_enabled=true

    別のホストで etcd を実行する場合、この Ansible 変数を使用して IP アドレスでノードを指定します。

    openshift_cluster_monitoring_operator_etcd_hosts=[<address1>, <address2>, ...]

    etcd ノードの IP アドレスが変更される場合は、この一覧を更新する必要があります。

5.5. Prometheus、Alertmanager、および Grafana へのアクセス

OpenShift Container Platform Monitoring には、クラスターモニターリング用の Prometheus インスタンスおよび中心的な Alertmanager クラスターが同梱されます。Prometheus および Alertmanager に加えて、OpenShift Container Platform Monitoring には Grafana インスタンスおよびクラスターモニターリングのトラブルシューティング向けの事前にビルドされたダッシュボードが含まれます。モニタリングスタックおよびダッシュボードと共に提供される Grafana インスタンスは読み取り専用です。

Prometheus、Alertmanager、および Grafana Web UI にアクセスするためのアドレスを取得するには、以下を実行します。

手順

  1. 次のコマンドを実行します。

    $ oc -n openshift-monitoring get routes
    NAME                HOST/PORT
    alertmanager-main   alertmanager-main-openshift-monitoring.apps._url_.openshift.com
    grafana             grafana-openshift-monitoring.apps._url_.openshift.com
    prometheus-k8s      prometheus-k8s-openshift-monitoring.apps._url_.openshift.com

    https:// をこれらのアドレスに追加します。暗号化されていない接続を使用して UI にアクセスすることはできません。

  2. 認証は、OpenShift Container Platform アイデンティティーに対して行われ、OpenShift Container Platform の他の場所で使用されるのと同じ認証情報および認証方法が使用されます。cluster-monitoring-view クラスターロールなどの、すべての namespace への読み取りアクセスを持つロールを使用する必要があります。

第6章 Red Hat レジストリーへのアクセスおよびその設定

6.1. 認証が有効にされている Red Hat レジストリー

Red Hat Container Catalog で利用可能なすべてのコンテナーイメージはイメージレジストリーの registry.access.redhat.com でホストされます。OpenShift Container Platform 3.11 では、Red Hat Container Catalog は registry.access.redhat.com から registry.redhat.io に移行しました。

新規レジストリーの registry.redhat.io ではイメージおよび OpenShift Container Platform でホストされるコンテンツへのアクセスに認証が必要になります。新規レジストリーへの移行後も、既存レジストリーはしばらく利用可能になります。

注記

OpenShift Container Platform はイメージを registry.redhat.io からプルするため、これを使用できるようにクラスターを設定する必要があります。

新規レジストリーは、以下の方法を使用して認証に標準の OAuth メカニズムを使用します。

  • 認証トークン管理者によって生成される これらのトークンは、システムにコンテナーイメージレジストリーに対する認証機能を付与するサービスアカウントです。サービスアカウントはユーザーアカウントの変更による影響を受けないので、トークンの認証方法は信頼性があり、回復性があります。これは、実稼働クラスター用にサポートされている唯一の認証オプションです。
  • Web ユーザー名およびパスワード。これは、access.redhat.com などのリソースへのログインに使用する標準的な認証情報のセットです。OpenShift Container Platform でこの認証方法を使用することはできますが、これは実稼働デプロイメントではサポートされません。この認証方法の使用は、OpenShift Container Platform 外のスタンドアロンのプロジェクトに制限されます。

ユーザー名またはパスワード、または認証トークンのいずれかの認証情報を使用して docker login を使用し、新規レジストリーのコンテンツにアクセスします。

すべてのイメージストリームは新規レジストリーを参照します。新規レジストリーにはアクセスに認証が必要となるため、OpenShift namespace には imagestreamsecret という新規シークレットがあります。

認証情報は 2 つの場所に配置する必要があります。

  • OpenShift namespaceOpenShift namespace のイメージストリームがインポートできるように、認証情報は OpenShift namespace に存在している必要があります。
  • ホスト。Kubernetes でイメージをプルする際にホストの認証情報を使用するため、認証情報はホスト上になければなりません。

新規レジストリーにアクセスするには、以下を実行します。

  • イメージインポートシークレット imagestreamsecret が OpenShift namespace にあることを確認します。そのシークレットには、新規レジストリーへのアクセスを許可する認証情報があります。
  • クラスターノードのすべてに、マスターからコピーされた /var/lib/origin/.docker/config.json が含まれていることを確認します。 これは、Red Hat レジストリーへのアクセスを許可します。

6.1.1. ユーザーアカウントの作成

Red Hat 製品のエンタイトルメントを持たれる Red Hat のお客様は、ユーザー認証情報を持つアカウントをお持ちです。これは、お客様が Red Hat カスタマーポータルにログインされる際に使用されるユーザー名およびパスワードです。

アカウントをお持ちでない場合は、以下のオプションのいずれかに登録してアカウントを無料で取得することができます。

  • Red Hat Developer Program。このアカウントを使用すると、開発者の各種ツールおよびプログラムにアクセスできます。
  • 30 日間のトライアルサブスクリプション。このアカウントを使用すると、一部の Red Hat ソフトウェア製品にアクセスできる 30 日間のトライアルサブスクリプションを利用できます。

6.1.2. Red Hat レジストリー

お客様の企業が共有アカウントを管理されている場合には、トークンを作成する必要があります。管理者は、組織に関連付けられたすべてのトークンを作成し、表示し、削除することができます。

前提条件

  • ユーザー認証情報

手順

トークンを順番に作成するには、docker login を実行します。

  1. registry.redhat.io に移動します。
  2. Red Hat Network (RHN) のユーザー名とパスワードでログインします。
  3. プロンプトが出されたら、同意書を読んでこれに同意します。

    • 同意書の同意を求めるプロンプトがすぐに出されない場合、以下の手順に進むとプロンプトが出されます。
  4. Registry Service Accounts ページから、Create Service Account をクリックします。

    1. サービスアカウントの名前を指定します。これには、ランダムの文字列が追加されます。
    2. 説明を入力します。
    3. Create をクリックしまう。
  5. サービスアカウントに戻ります。
  6. 作成したサービスアカウントをクリックします。
  7. 追加された文字列を含むユーザー名をコピーします。
  8. トークンをコピーします。

6.1.3. インストールおよびアップグレード時のレジストリー認証情報の管理

レジストリー認証情報は、Ansible インストーラーを使用してインストールまたはアップグレード時に管理することもできます。

これにより、以下がセットアップされます。

  • OpenShift namespace の imagestreamsecret
  • すべてのノードの認証情報。

Ansible インストーラーでは、openshift_examples_registryurl または oreg_url のいずれかのデフォルト値の registry.redhat.io を使用している場合に認証情報が必要になります。

前提条件

  • ユーザー認証情報
  • サービスアカウント
  • サービスアカウントトークン

手順

Ansible インストーラーを使用してインストールまたはアップグレード時にレジストリー認証情報を管理するには、以下を実行します。

  • インストールまたはアップグレード時に、インストーラーインベントリーに oreg_auth_user および oreg_auth_password 変数を指定します。
注記

トークンを作成した場合、oreg_auth_password をトークンの値に設定します。

追加の認証されたレジストリーへのアクセスを必要とするクラスターは、openshift_additional_registry_credentials を設定してレジストリーの一覧を設定できます。各レジストリーには、ホストおよびパスワードの値が必要であり、ユーザー名はユーザーを設定して指定できます。デフォルトで、指定された認証情報は、指定されたレジストリーでイメージ openshift3/ose-pod の検査を試行することによって検証されます。

代替イメージを指定するには、以下のいずれかを実行します。

  • test_image を設定します。
  • test_login を False に設定して認証情報の検証を無効にします。

レジストリーがセキュアでない場合、tls_verify を False に設定します。

この一覧のすべての認証情報には、OpenShift namespace で作成された imagestreamsecret およびすべてのノードにデプロイされた認証情報が含まれます。

以下に例を示します。

openshift_additional_registry_credentials=[{'host':'registry.example.com','user':'name','password':'pass1','test_login':'False'},{'host':'registry2.example.com','password':'token12345','tls_verify':'False','test_image':'mongodb/mongodb'}]

6.1.4. Red Hat レジストリーでのサービスアカウントの使用

Red Hat レジストリーのサービスアカウントを作成し、トークンを生成した後に、追加のタスクを実行できます。

注記

このセクションでは、インストールおよびアップグレード時のレジストリー認証情報の管理セクションで説明されているインベントリー変数を指定することによってインストール時に自動的に実行できる手動の手順について説明します。

前提条件

  • ユーザー認証情報
  • サービスアカウント
  • サービスアカウントトークン

手順

Registry Service Accounts ページから、アカウント名をクリックします。このページから以下のタスクを実行できます。

  • Token Informationタブで、ユーザー名 (指定したランダムの文字列が追加された名前) およびパスワード (トー