Contour Ingress 用 TKG 拡張機能のデプロイと管理

このトピックでは、Contour Ingress 用 TKG 拡張機能 v1.3.1 をデプロイする方法について説明します。Contour は、Envoy リバース プロキシを使用する Kubernetes Ingress コントローラです。Tanzu Kubernetes クラスタで実行されているサービスにルートを公開するには、Contour Ingress 用 TKG 拡張機能をデプロイします。

拡張機能の前提条件

Contour Ingress 用 TKG 拡張機能 v1.3.1 をデプロイするには、次の要件を満たす必要があります。

• クラスタをプロビジョニングします。TKGS v1alpha2 API を使用して Tanzu Kubernetes クラスタをプロビジョニングするためのワークフローを参照してください。
• クラスタに接続します。vCenter Single Sign-On ユーザーとして Tanzu Kubernetes クラスタに接続を参照してください。
• kubectl を実行するクライアント ホストへのTKG 拡張機能 v1.3.1 バンドルのダウンロードを実行します。
• ターゲット クラスタへのTKG 拡張機能の前提条件のインストールを実行します。

Contour 拡張機能のデプロイ

Contour Ingress 用 TKG 拡張機能は、クラスタに Envoy と Contour の 2 つのコンテナをインストールします。詳細については、『 https://projectcontour.io/』を参照してください。

コンテナ	リソースの種類	レプリカ	説明
Envoy	DaemonSet	3	高パフォーマンスのリバース プロキシ
Contour	デプロイ	2	Envoy 用の管理および構成サーバ

この拡張機能は、 https://projects.registry.vmware.com/ にある VMware パブリック レジストリからコンテナをプルするように構成されています。プライベート レジストリを使用する場合は、データ値と拡張機能構成に含まれるエンドポイント URL を、対応するものに変更します。 Contour 拡張機能の構成を参照してください。

1. 拡張機能のすべての前提条件を満たしていることを確認します。拡張機能の前提条件を参照してください。
2. Contour の拡張機能ファイルをダウンロードしたディレクトリに移動します。

   cd /tkg-extensions-v1.3.1+vmware.1/extensions/ingress/contour

3. 次のコマンドを実行して、tanzu-system-ingress 名前空間と、Contour サービスのアカウントおよびロール オブジェクトを作成します。

   kubectl apply -f namespace-role.yaml

4. vSphere 用の Contour データ値ファイルを作成します。

   cp vsphere/contour-data-values-lb.yaml.example vsphere/contour-data-values.yaml

5. ファイル vsphere/contour-data-values.yaml を更新して Contour を構成します。

   サンプル データ値ファイルには、最低限必要な構成が含まれています。すべての構成フィールドとオプションの説明については、Contour 拡張機能の構成を参照してください。

   たとえば、次に示す vSphere 用の Contour 構成には、LoadBalancer タイプのサービスが使用されます。

   infrastructure_provider: "vsphere"
   contour:
     image:
       repository: projects.registry.vmware.com/tkg
   envoy:
     image:
       repository: projects.registry.vmware.com/tkg
       tag: v1.17.3_vmware.1
     service:
       type: "LoadBalancer"

   注： CVE を含む Envoy イメージ バージョン v1.16.2_vmware.1 を使用しないようにするために、Envoy イメージ バージョン v1.17.3_vmware.1 を指定することをお勧めします。詳細については、 リリース ノートを参照してください。
6. データ値を使用してシークレットを作成します。

   kubectl create secret generic contour-data-values --from-file=values.yaml=vsphere/contour-data-values.yaml -n tanzu-system-ingress

   secret/contour-data-values が tanzu-system-ingress 名前空間に作成されます。次のコマンドを使用して確認します。

   kubectl get secrets -n tanzu-system-ingress

7. Contour Ingress コントローラ アプリケーションをデプロイします。

   kubectl apply -f contour-extension.yaml

   成功すると、app.kappctrl.k14s.io/contour created が表示されます。

8. Contour Ingress コントローラ アプリケーションのステータスを確認します。

   kubectl get app contour -n tanzu-system-ingress

   成功すると、ステータスが Reconciling から Reconcile succeeded に変わります。ステータスが Reconcile failed の場合は、Contour Ingress のデプロイのトラブルシューティングを参照してください。
9. Contour Ingress コントローラ アプリケーションの詳細情報を表示します。

   kubectl get app contour -n tanzu-system-ingress -o yaml

10. LoadBalancer タイプの Envoy サービスを表示します。

    kubectl get service envoy -n tanzu-system-ingress -o wide

    成功すると、Envoy LoadBalancer の詳細が表示されます。

    NAME    TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE     SELECTOR
    envoy   LoadBalancer   10.79.65.110   10.178.147.73   80:30437/TCP,443:30589/TCP   2m42s   app=envoy,kapp.k14s.io/app=1629916985840017976

11. Envoy DaemonSet を確認します。

    kubectl get daemonsets -n tanzu-system-ingress

    成功すると、3 ポッドの Envoy DaemonSet が表示されます。

    NAME    DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
    envoy   3         3         3       3            3           <none>          6m10s

12. Contour のデプロイを確認します。

    kubectl get deployments -n tanzu-system-ingress

    成功すると、2 ポッドの Contour のデプロイが表示されます。

    NAME      READY   UP-TO-DATE   AVAILABLE   AGE
    contour   2/2     2            2           8m7s

13. Contour Ingress コントローラが正しくインストールされ、使用可能な状態であることを確認します。

    kubectl get pod,svc -n tanzu-system-ingress

    Contour ポッドと Envoy ポッドのステータスは Running である必要があり、Envoy サービスの LoadBalancer には EXTERNAL-IP が割り当てられます。

    NAME                           READY   STATUS    RESTARTS   AGE
    pod/contour-84bb5475cf-7h4cx   1/1     Running   0          9m52s
    pod/contour-84bb5475cf-v8k9r   1/1     Running   0          9m52s
    pod/envoy-4828j                2/2     Running   0          9m52s
    pod/envoy-c54dw                2/2     Running   0          9m52s
    pod/envoy-qpjqp                2/2     Running   0          9m52s
    
    NAME              TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
    service/contour   ClusterIP      10.105.6.207   <none>          8001/TCP                     9m52s
    service/envoy     LoadBalancer   10.79.65.110   10.178.147.73   80:30437/TCP,443:30589/TCP   9m52s

Contour Ingress のデプロイのトラブルシューティング

デプロイまたは調整が失敗した場合は、kubectl get pods -n tanzu-system-ingress を実行してポッドのステータスを確認します。contour および envoy ポッドは、Running である必要があります。ポッドのステータスが ImagePullBackOff または ImageCrashLoopBackOff の場合は、コンテナ イメージをプルできていません。データ値と拡張機能 YAML ファイルに記述されているリポジトリ URL を確認し、これらが正確であることを確認します。

コンテナログを確認します。 name-XXXX は、 kubectl get pods -A を実行したときの一意のポッド名です。

kubectl logs pod/envoy-XXXXX -c envoy -n tanzu-system-ingress

 kubectl logs pod/contour-XXXXX -c contour -n tanzu-system-ingress

Contour ポッドが ContainerCreating 状態で停止し、上記のいずれかのイメージ エラーでは失敗しておらず、処理が進行していない（「contour-xxxxx has timed out progressing」）場合は、IP アドレスの競合が発生している可能性があります。ワークロード ネットワークを構成したときに指定したノード CIDR 範囲が、クラスタ仕様のポッド CIDR 範囲（デフォルトでは 192.168.0.0/16）と競合していないことを確認します。競合がある場合は、別のポッド サブネットを使用してクラスタを更新するか、ノード ネットワークを変更します。

Contour 拡張機能の更新

Tanzu Kubernetes クラスタにデプロイされている Contour 拡張機能を更新します。

1. シークレットから Contour データ値を取得します。

   kubectl get secret contour-data-values -n tanzu-system-ingress -o 'go-template={{ index .data "values.yaml" }}' | base64 -d > contour-data-values.yaml
   

2. ingress/contour/values.yaml 内の Contour Ingress データ値を更新します。Contour 拡張機能の構成を参照してください。
   たとえば、次に示す vSphere 用の Contour 構成には、LoadBalancer タイプのサービスが使用されます。

   infrastructure_provider: "vsphere"
   contour:
     image:
       repository: projects.registry.vmware.com/tkg
   envoy:
     image:
       repository: projects.registry.vmware.com/tkg
       tag: v1.17.3_vmware.1
     service:
       type: "LoadBalancer"

   注： CVE を含む Envoy イメージ バージョン v1.16.2_vmware.1 を使用しないようにするために、Envoy イメージ バージョン v1.17.3_vmware.1 を指定することをお勧めします。詳細については、 リリース ノートを参照してください。
3. Contour データ値のシークレットを更新します。

   kubectl create secret generic contour-data-values --from-file=values.yaml=contour-data-values.yaml -n tanzu-system-ingress -o yaml --dry-run | kubectl replace -f-

   Contour 拡張機能が新しいデータ値で調整されます。

   注： デフォルトでは、kapp-controller によってアプリケーションが 5 分ごとに同期されます。更新は 5 分以内に有効になります。更新をすぐに有効にするには、 contour-extension.yaml 内の syncPeriod の値を小さくし、 kubectl apply -f contour-extension.yaml を使用して Grafana 拡張機能を再デプロイします。
4. アプリケーションのステータスを確認します。

   kubectl get app contour -n tanzu-system-ingress

   Contour が更新されると、ステータスが Reconcile Succeeded に変更されます。

5. 詳細なステータスを確認します。

   kubectl get app contour -n tanzu-system-ingress -o yaml

6. 必要に応じてトラブルシューティングを実行します。Contour Ingress のデプロイのトラブルシューティングを参照してください。

Contour 拡張機能の削除

Tanzu Kubernetes クラスタから Contour 拡張機能を削除します。

注： 手順を順番に実行します。Contour Ingress コントローラ アプリケーションが完全に削除される前に、名前空間、サービス アカウント、ロール オブジェクトを削除しないでください。これを行うと、システム エラーが発生する可能性があります。

1. Contour 拡張機能のディレクトリに移動します。

   cd extensions/ingress/contour/

2. Contour Ingress コントローラ アプリケーションを削除します。

   kubectl delete app contour -n tanzu-system-ingress

   予期される結果：app.kappctrl.k14s.io "contour" deleted。

3. Contour Ingress アプリケーションが削除されていることを確認します。

   kubectl get app contour -n tanzu-system-ingress

   予期される結果：apps.kappctrl.k14s.io "contour" not found。

4. tanzu-system-ingress 名前空間と、Contour 拡張機能サービスのアカウントおよびロール オブジェクトを削除します。

   kubectl delete -f namespace-role.yaml

Contour 拡張機能のアップグレード

既存の Contour 拡張機能がデプロイされている場合は、最新バージョンにアップグレードできます。

1. Contour の構成マップをエクスポートし、バックアップとして保存します。

   kubectl get configmap contour -n tanzu-system-ingress -o 'go-template={{ index .data "contour.yaml" }}' > contour-configmap.yaml

2. 既存の Contour 環境を削除します。Contour 拡張機能の削除を参照してください。
3. 最新の Contour 拡張機能をデプロイします。Contour 拡張機能のデプロイを参照してください。

Contour 拡張機能の構成

Contour Ingress コントローラの構成値は、 /extensions/ingress/contour/vsphere/contour-data-values.yaml で設定されます。

表 1. Contour Ingress の構成パラメータ

パラメータ	説明	タイプ	デフォルト
infrastructure_provider	インフラストラクチャ プロバイダ。サポートされている値：vsphere、aws、azure	文字列	必須パラメータ
contour.namespace	contour がデプロイされる名前空間	文字列	tanzu-system-ingress
contour.config.requestTimeout	Envoy に渡されるクライアント要求タイムアウト	time.Duration	0s ファイル ダウンロードのルート タイムアウトを参照してください。
contour.config.server.xdsServerType	使用する XDS サーバ タイプ：サポートされている値：contour または envoy	文字列	Null
contour.config.tls.minimumProtocolVersion	Contour がネゴシエートする最小 TLS バージョン	文字列	1.1
contour.config.tls.fallbackCertificate.name	vhost に定義されている SNI と一致しない要求に対するフォールバック証明書が含まれているシークレットの名前	文字列	Null
contour.config.tls.fallbackCertificate.namespace	フォールバック証明書が含まれているシークレットの名前空間	文字列	Null
contour.config.tls.envoyClientCertificate.name	クライアント証明書として使用するシークレットの名前、バックエンド サービスへの TLS 接続用プライベート キー	文字列	Null
contour.config.tls.envoyClientCertificate.namespace	クライアント証明書として使用するシークレットの名前空間、バックエンド サービスへの TLS 接続用プライベート キー	文字列	Null
contour.config.leaderelection.configmapName	contour leaderelection に使用される configmap の名前	文字列	leader-elect
contour.config.leaderelection.configmapNamespace	contour leaderelection configmap の名前空間	文字列	tanzu-system-ingress
contour.config.disablePermitInsecure	ingressroute permitInsecure フィールドを無効にします	boolean	false
contour.config.accesslogFormat	アクセス ログ形式	文字列	envoy
contour.config.jsonFields	ログに記録されるフィールド	文字列の配列	https://godoc.org/github.com/projectcontour/contour/internal/envoy#JSONFields
contour.config.useProxyProtocol	https://projectcontour.io/guides/proxy-proto/	boolean	false
contour.config.defaultHTTPVersions	Envoy がサービスを提供するためにプログラムする必要がある HTTP バージョン	文字列の配列	"HTTP/1.1 HTTP2"
contour.config.timeouts.requestTimeout	要求全体のタイムアウト	time.Duration	Null（タイムアウトが無効）
contour.config.timeouts.connectionIdleTimeout	アイドル接続を終了するまでの待機時間	time.Duration	60s
contour.config.timeouts.streamIdleTimeout	アクティビティがない要求またはストリームを終了するまでの待機時間	time.Duration	5m
contour.config.timeouts.maxConnectionDuration	アクティビティに関係なく接続を終了するまでの待機時間	time.Duration	Null（タイムアウトが無効）
contour.config.timeouts.ConnectionShutdownGracePeriod	最初と最後の GOAWAY を送信するまでの待機時間	time.Duration	5s
contour.config.cluster.dnsLookupFamily	HTTPProxy ルートから externalName タイプ サービスへのアップストリーム要求に使用する dns-lookup-family	文字列	Null（サポートされている値：auto、v4、v6）
contour.config.debug	デバッグ機能をオンにします	boolean	false
contour.config.ingressStatusAddress	すべての Ingress リソースのステータスで設定するアドレス	文字列	Null
contour.certificate.duration	contour 証明書の有効期間	time.Duration	8760h
contour.certificate.renewBefore	contour 証明書の更新が必要になるまでの期間	time.Duration	360h
contour.deployment.replicas	contour レプリカの数	整数型	2
contour.image.repository	Contour イメージを含むリポジトリの場所。デフォルトは、パブリック VMware レジストリです。プライベート リポジトリを使用している場合は（エアギャップ環境など）、この値を変更します。	文字列	projects.registry.vmware.com/tkg
contour.image.name	contour イメージの名前	文字列	contour
contour.image.tag	Contour イメージ タグ。Contour バージョンをアップグレードしている場合は、この値の更新が必要になることがあります。	文字列	v1.11.0_vmware.1
contour.image.pullPolicy	Contour イメージ プル ポリシー	文字列	IfNotPresent
envoy.image.repository	Envoy イメージを含むリポジトリの場所。デフォルトは、パブリック VMware レジストリです。プライベート リポジトリを使用している場合は（エアギャップ環境など）、この値を変更します。	文字列	projects.registry.vmware.com/tkg
envoy.image.name	envoy イメージの名前	文字列	envoy
envoy.image.tag	イメージ タグを使用します。Envoy バージョンをアップグレードしている場合は、この値の更新が必要になることがあります。	文字列	v1.17.3_vmware.1 注： CVE が含まれているため、Envoy イメージ v1.16.2_vmware.1 を使用しないでください。詳細については、 リリース ノートを参照してください。
envoy.image.pullPolicy	Envoy イメージ プル ポリシー	文字列	IfNotPresent
envoy.hostPort.enable	ホスト上の envoy ポートを公開するフラグ	boolean	true
envoy.hostPort.http	Envoy HTTP ホスト ポート	整数型	80
envoy.hostPort.https	Envoy HTTPS ホスト ポート	整数型	443
envoy.service.type	envoy を公開するサービスのタイプ。サポートされている値：ClusterIP、NodePort、LoadBalancer	文字列	vSphere の必須パラメータ：NodePort または LoadBalancer、AWS：LoadBalancer、Azure：LoadBalancer
envoy.service.annotations	Envoy サービスの注釈	マップ（キー値）	空のマップ
envoy.service.externalTrafficPolicy	envoy サービスの外部トラフィック ポリシー。サポートされている値：Local、Cluster	文字列	Cluster
envoy.service.nodePort.http	http 要求に使用されるタイプ NodePort のサービスに必要な nodePort	整数型	Null - Kubernetes は動的ノード ポートを割り当てます
envoy.service.nodePort.https	HTTPS 要求に使用されるタイプ NodePort のサービスに必要な nodePort	整数型	Null - Kubernetes は動的ノード ポートを割り当てます
envoy.deployment.hostNetwork	hostNetwork で envoy を実行します	boolean	false
envoy.service.aws.LBType	envoy サービスの公開に使用される AWS LB タイプ。サポートされている値：classic、nlb	文字列	classic
envoy.loglevel	envoy に使用するログ レベル	文字列	info

ファイル ダウンロードのルート タイムアウト

パラメータ contour.config.requestTimeout は、Contour ルート タイムアウト期間を定義します。デフォルト値は 0s です。Contour をファイル転送に使用している場合は、この値の調整が必要になる場合があります。

Contour のドキュメントによると、タイムアウト値が 0s の場合、Contour は Envoy タイムアウトを使用するように設定されます。Envoy のドキュメントによると、Envoy のデフォルトのタイムアウトは 15 秒です。また、Envoy では、要求から応答までの操作全体がタイムアウト間隔内で完了することが想定されます。

つまり、デフォルトの Contour タイムアウト設定が 0s の場合、ファイル転送は 15 秒以内に完了する必要があります。これは、サイズが大きいファイルの転送では時間が足りない可能性があります。デフォルトの Envoy のタイムアウトを無効にするには、contour.config.requestTimeout の値を 0 に設定します。