1. Homepage
  2. Runtime Fabric (2.3)

  3. イングレスの設定

Runtime Fabric のイングレスの設定

このコンテンツでは、バージョン 1.10 以降の Runtime Fabric でのイングレスの設定について説明します。以前のイングレスの設定手順については、バージョン 1.8 または 1.9 のドキュメントを参照してください。

Anypoint Runtime Fabric では、イングレスリソーステンプレートを使用してカスタムイングレス設定を指定できます。テンプレートでは、 Kubernetes イングレス仕様​と同様、アノテーション、イングレスクラス名、および HTTP および HTTPS ルールを指定できます。

アプリケーションのイングレスリソーステンプレートを適用しない場合、デプロイしたときにイングレスエンドポイントを追加できません。

デフォルトでは、Google Kubernetes Engine (GKE) と一緒に含まれているイングレスコントローラーによってアプリケーションごとに個別の HTTP ロードバランサーがプロビジョニングされます。詳細は、 「Default Ingress Controller Behavior with Runtime Fabric on GKE (GKE での Runtime Fabric を使用したデフォルトのイングレスコントローラーの動作)」​を参照してください。

AWS アプリケーションのロードバランサーでは、​group.name​ アノテーションを使用しない限り同様の動作になります。詳細は、 「Application load balancing on Amazon EKS (Amazon EKS でのアプリケーションの負荷分散)」​を参照してください。

カスタムイングレスリソーステンプレートの利点

Runtime Fabric でカスタムイングレスリソーステンプレートを使用すれば、以下に対するサポートを含めてネイティブ Kubernetes イングレス設定機能を活用できます。

  • アプリケーションごとに複数のイングレス設定

  • 同じ Runtime Fabric インスタンス内の複数のイングレスコントローラー

  • TLS および HTTPS 設定

  • カスタム URL 名前付け

  • URL パラメーターのプレースホルダー

Runtime Fabric でのイングレスリソーステンプレートの動作

次の図では、Runtime Fabric でイングレスリソーステンプレートを使用する方法の概要を示しています。

Runtime Fabric でのイングレステンプレートワークフローを示す図

  1. IT 管理者がイングレスコントローラーを設定します。

  2. IT 管理者が必須パラメーターを使用してイングレスリソーステンプレートを作成または変更します。イングレスコントローラーの動作はそれぞれ異なります。イングレスコントローラーのドキュメントを確認して、アノテーションを調整してください。

  3. IT 管理者が ​kubectl apply​ コマンドを使用してテンプレートを適用します。

  4. 適用されたテンプレートから、Runtime Fabric によってプレースホルダーの URI ドメインが作成され、すべてのアプリケーションデプロイメントのテンプレートとして Anypoint Runtime Manager でイングレス設定が伝播されます。

  5. Mule アプリケーション開発者が Runtime Manager を使用して、イングレステンプレートで指定されているように、使用可能なホスト、省略可能なサブドメイン、およびパスの組み合わせを選択することでデプロイメントのアプリケーションを設定します。

  6. Runtime Fabric によってアプリケーションデプロイメント要求が受信され、テンプレートのイングレス設定を使用してクラスターで対応するイングレスオブジェクトが作成されます。

イングレスリソーステンプレートの例

次の例では、Runtime Fabric イングレスリソーステンプレートを作成するために Kubernetes イングレス仕様を変更する方法を示しています。

お使いの Kubernetes バージョンに適した API バージョンを使用してください。

  • Kubernetes v1.19 以降:

    • networking.k8s.io/v1

    • networking.k8s.io/v1beta1

      Kubernetes v1.22 以降では、​extensions/v1beta1​ および ​networking.k8s.io/v1beta1​ API バージョンのイングレスは使用できません。

  • Kubernetes v1.18 以前:

    • networking.k8s.io/v1beta1 のみ

networking.k8s.io/v1

このテンプレートは設定の簡略化バージョンです。テンプレートの最終的な設定は、使用しているコントローラーおよびイングレスのルーティングルールに応じて異なる場合があります。お使いのイングレスコントローラーのドキュメントを慎重にお読みください。

 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-rtf-ingress
  namespace: rtf (1)
  labels:
spec:
  ingressClassName: rtf-nginx (2)
  tls: (3)
  - hosts:
      - app-name.example.com
    secretName: example-tls
  rules:
  - host: app-name.example.com (4)
    http:
      paths: (5)
      - pathType: Prefix
        path: / (6)
        backend: (7)
          service:
            name: service-name
            port:
              name: service-port

この例について、次の点に注意してください。

1 このテンプレートは ​rtf​ 名前空間に配置する必要があります。
2 ingressClassName には ​rtf-​ のプレフィックスを付ける必要があります (たとえば、​rtf-nginx​)。

Runtime Fabric では ​rtf-​ プレフィックスを使用してオブジェクトをテンプレートとして認識します。 spec.ingressClassName​ 項目または ​kubernetes.io/ingress.class​ アノテーションの ​rtf-​ プレフィックスが付いたテンプレートは、Runtime Fabric エージェントのみにコンシュームされ、実際のイングレスコントローラーにはコンシュームされません。 イングレスコントローラーでは、ベンダー固有の名前 (たとえば、​nginx​ や ​haproxy​) を使用する ​spec.ingressClassName​ 値が含まれるリソースのみを検出します。
3 TLS は省略可能です。

secretName​ 属性が含まれる TLS セクションを追加する場合、必ず ​rtf​ 名前空間で参照される TLS シークレットを作成する必要もあります。
4 アプリケーションをデプロイすると、​app-name​ プレースホルダーのパラメーターは実際のアプリケーション名に置き換えられます。これにより、サブドメインにワイルドカードが含まれない場合に各エンドポイント名を一意にすることができます。
5 テンプレートにはホストの複数のパスを含めることができますが、Runtime Manager にはホストの最初のパスルールのみが表示されます。
6 path​ パラメーター値は、​Mule アプリケーションのイングレスを設定​するときに ​[Path (パス)]​ 項目に追加した値で置き換えられます。​path​ はプレースホルダーではありません。
7 これらのプレースホルダー値は Kubernetes 検証に必須ですが、実際の値は Runtime Fabric によって使用されません。

パスベースのルーティングイングレステンプレートの場合、イングレスコントローラーのドキュメントを参照してから設定してください。Nginx の使用例については、 「Path-based Nginx Ingress Routing Example for Runtime Fabric on Self-Managed Kubernetes (自己管理型 Kubernetes の Runtime Fabric のパスベースの Nginx イングレスルーティングの例)」​を参照してください。

networking.k8s.io/v1beta1

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example-rtf-ingress
  namespace: rtf (1)
  labels:
spec:
  ingressClassName: rtf-nginx (2)
  tls: (3)
  - hosts:
      - app-name.example.com
    secretName: example-tls
  rules:
    - host: app-name.example.com (4)
      http:
        paths: (5)
        - path: / (6)
          pathType:
          backend: (7)
            serviceName: service-name
            servicePort: 80

この例について、次の点に注意してください。

1 このテンプレートは ​rtf​ 名前空間に配置する必要があります。
2 ingressClassName には ​rtf-​ のプレフィックスを付ける必要があります (たとえば、​rtf-nginx​)。

Runtime Fabric では ​rtf-​ プレフィックスを使用してオブジェクトをテンプレートとして認識します。 spec.ingressClassName​ 項目または ​kubernetes.io/ingress.class​ アノテーションの ​rtf-​ プレフィックスが付いたテンプレートは、Runtime Fabric エージェントのみにコンシュームされ、実際のイングレスコントローラーにはコンシュームされません。 イングレスコントローラーでは、ベンダー固有の名前 (たとえば、​nginx​ や ​haproxy​) を使用する ​spec.ingressClassName​ 値が含まれるリソースのみを検出します。
3 TLS は省略可能です。

secretName​ 属性が含まれる TLS セクションを追加する場合、必ず ​rtf​ 名前空間で参照される TLS シークレットを作成する必要もあります。
4 アプリケーションをデプロイすると、​app-name​ プレースホルダーのパラメーターは実際のアプリケーション名に置き換えられます。これにより、サブドメインにワイルドカードが含まれない場合に各エンドポイント名を一意にすることができます。
5 テンプレートにはホストの複数のパスを含めることができますが、Runtime Manager にはホストの最初のパスルールのみが表示されます。
6 path​ パラメーター値は、​Mule アプリケーションのイングレスを設定​するときに ​[Path (パス)]​ 項目に追加した値で置き換えられます。​path​ はプレースホルダーではありません。
7 これらのプレースホルダー値は Kubernetes 検証に必須ですが、実際の値は Runtime Fabric によって使用されません。

パスベースのルーティングイングレステンプレートの場合、イングレスコントローラーのドキュメントを参照してから設定してください。 Nginx の使用例については、 「Path-based Nginx Ingress Routing Example for Runtime Fabric on Self-Managed Kubernetes (自己管理型 Kubernetes の Runtime Fabric のパスベースの Nginx イングレスルーティングの例)」​を参照してください。

テンプレートのプレースホルダー

次のプレースホルダーは省略可能です。プレースホルダーを使用する場合、テンプレートの適切な場所で置き換えてください。プレースホルダーは小文字にしてください。

プレースホルダーの名前 場所 値の例

business-group-id

path​、​host​、​annotation、labels

 
labels:
  business:
  business-group-id

environment-id

path​、​host​、​annotation、labels

 
labels:
  environment:
  environment-id

unique-id

path​、​annotation、labels

 
path: /app-name-unique-id.com

unique-id​ プレースホルダーを使用して一意のアプリケーション URL を作成します。この方法は、異なるビジネスグループから同じ名前を持つ 2 つのアプリケーションをデプロイする場合に便利です。たとえば、イングレステンプレートの ​path​ セクションで ​app-name-unique-id.com​ を使用する場合、生成されるエンドポイントは ​app-name-7jkbic.com​ のようになります。

unique-id​ プレースホルダーは Runtime Fabric バージョン 1.12.28 以降で使用できます。

イングレステンプレートでの TLS の使用

イングレステンプレートで TLS を使用するには、TLS シークレットを作成する必要があります。詳細は、 Kubernetes TLS のドキュメント​を参照してください。

rtf.mulesoft.com/synchronized=true​ 表示ラベルを使用して、たとえば次のように、TLS シークレットの更新をすべてのアプリケーション名前空間に同期するように Runtime Fabric を設定できます。

apiVersion: v1
kind: Secret
metadata:
  name: testsecret-tls
  namespace: <agent-namespace>
  labels:
    rtf.mulesoft.com/synchronized=true
data:
  tls.crt: base64 encoded cert
  tls.key: base64 encoded key
type: kubernetes.io/tls

この表示ラベルをシークレットに適用すると、イングレスコントローラーで更新済みの TLS 素材をアプリケーション名前空間にすぐに適用できるようになります。この表示ラベルを追加しない場合は、各名前空間でシークレットを手動で更新する必要があります。

同期メカニズムを使用して、デプロイ時に Runtime Fabric エージェントの名前空間のシークレットをアプリケーションの名前空間に複製できます。

既存のイングレステンプレートを変更する

既存のイングレステンプレートは、すでにアプリケーションのデプロイで使用されている場合でも修正できます。 テンプレートを変更しても、このテンプレートに基づいてすでに作成されているイングレスオブジェクトは更新されません。

テンプレートの変更を反映して既存のイングレスを更新するには、Mule アプリケーションを再デプロイする必要があります。 たとえば、ベースドメインを更新してイングレステンプレートのエンドポイントの変更が必要になった場合は、古いエンドポイントを削除して、アプリケーションの再デプロイ時に新しいエンドポイントを追加します。

Runtime Fabric で Mule アプリケーションデプロイメント用のイングレスを設定する

イングレスを設定するには、次のタスクを実行します。

  1. イングレスリソーステンプレートを作成してクラスターで適用します。

  2. Mule アプリケーションのイングレスを設定します。

始める前に

Runtime Fabric でイングレスをセットアップする前に、イングレスコントローラーを設定する必要があります。イングレスコントローラーのリストについては、 Kubernetes のドキュメント​を参照してください。

イングレスリソーステンプレートを作成してクラスターで適用する

テンプレート例​のいずれかを使用してイングレスリソースを作成します。

  1. テンプレート例を新しいファイルにコピーして、コメントに変更します。

  2. ファイル名に ​.yaml​ 拡張子を含めます。

  3. イングレステンプレートを適用するには、次のコマンドを実行します。

    kubectl apply -f <TEMPLATE_FILENAME.yaml>

テンプレートに問題がある場合、Kubernetes ​api-server​ によってエラーが返され、コマンドは失敗します。

テンプレートを正常に適用したら、次のコマンドを使用して表示できます。

kubectl describe ingress [Ingress Name] -n rtf

Mule アプリケーションのイングレスを設定する

Runtime Manager を使用して Runtime Fabric にデプロイするときに、アプリケーションのイングレスを設定します。アプリケーションに使用可能なホストおよびパスは、Runtime Fabric システム管理者が設定したイングレスリソーステンプレートから取得されます。

この手順を使用してテストアプリケーションをデプロイし、イングレスリソーステンプレートを検証することもできます。

次に、アプリケーションのイングレスを設定する方法の概要を示します。 完全なデプロイメント手順については、​「Runtime Fabric に Mule アプリケーションをデプロイする」​を参照してください。 Mule Maven プラグインを使用してアプリケーションを Runtime Fabric にデプロイする場合、ブロック ​http​ のデプロイメント設定パラメーター ​publicUrl​ で複数のエンドポイントのカンマ区切り文字列を受け入れることができます。 詳細は、​「deploymentSettings パラメーターリファレンス」​を参照してください。

  1. [Runtime Manager] に移動し、ドキュメントに従ってアプリケーションを Runtime Fabric にデプロイします。

  2. [Ingress (イングレス)]​ を選択します。

  3. [Host (ホスト)]​ ドロップダウンリストからアプリケーションのホストを選択します。

  4. ホスト名にワイルドカードが使用されている場合、​[Subdomain (サブドメイン)]​ 項目でサブドメインを追加します。

    [Subdomain (サブドメイン)]​ 項目はホスト名にワイルドカードが使用されている場合のみ使用できます。

  5. [Path (パス)]​ 項目で、アプリケーションのエンドポイントに URL パスを追加します。

    エンドポイントのホスト項目とパス項目が入力されます

  6. エンドポイントをプレビューするには、生成されたプレビューリンクをクリックします。

  7. 別のエンドポイントを追加するには、​[+ Add Endpoint (+ エンドポイントを追加)]​ をクリックします。

  8. 準備ができたら、​[Deploy application (アプリケーションをデプロイ)]​ をクリックします。

既存のイングレス設定のアップグレード後の変換

Runtime Fabric バージョン 1.10 にアップグレードする場合、アップグレードプロセスでアノテーション、パス、名前空間、ホストパラメーターを含む既存のイングレスの ConfigMaps が自動的にイングレスリソーステンプレート形式に変換されます。次の表を確認して、アップグレード後にアクションが必要かどうかを判断してください。

アップグレード前の Runtime Fabric アップグレード後の Runtime Fabric 必要なアクション TLS サポート

ドメインは設定されず、ingress-ConfigMap は適用されない

アップグレード後にテンプレートが自動的に生成されない

テンプレートを作成する。​イングレスリソーステンプレートを作成してクラスターで適用する​を参照してください。

-

ドメインは設定されないが、有効な ingress-ConfigMap が適用される

生成されたテンプレートにホストの ​*​ が含まれ、以前の ingress-ConfigMap のパスおよびアノテーションが含まれる

生成されたテンプレートで ​host​ 項目を編集し、Runtime Manager でアプリケーションをデプロイするための有効なホスト/ドメインを指定する

デフォルトでは TLS セクションは追加されない

有効なドメインが設定されるが、ingress-ConfigMap は適用されない

生成されたテンプレートにテンプレートあたり 1 つのドメインにつき 1 つのホストが含まれ、各テンプレートのパスに ​/app-name​ が含まれる

ドメインで ​https://​ が使用されていない限り、直ちにアクションは必要ない。使用されている場合は、HTTPS ドメインに対応するテンプレートで TLS シークレットを設定します

https://​ があるドメインでは、そのドメインに対応するテンプレートにシークレット属性のない TLS セクションが含まれる

有効なドメインが設定され、有効な ingress-ConfigMap が適用される

生成されたテンプレートにテンプレートあたり 1 つのドメインにつき 1 つのホストが含まれ、以前の ingress-ConfigMap のパスおよびアノテーションがすべて含まれる

ドメインで ​https://​ が使用されていない限り、直ちにアクションは必要ない。使用されている場合は、HTTPS ドメインに対応するテンプレートで TLS シークレットを設定します

https://​ があるドメインでは、そのドメインに対応するテンプレートにシークレット属性のない TLS セクションが含まれる

イングレスの問題のトラブルシューティング

Runtime Fabric にイングレスを使用しようとしたときにエラーが発生した場合、次のようにトラブルシューティングしてください。

Mule アプリケーションをデプロイしたがそのエンドポイントにアクセスできない

シナリオ: Runtime Manager で Mule アプリケーションを正常にデプロイしましたが、アプリケーションのエンドポイントにアクセスできません。

この問題をトラブルシューティングする手順は、次のとおりです。

  1. アプリケーションがポート 8081 でリスンしていることを確認します。

    kubectl port-forward -n [NAMESPACE] svc/<APP_NAME> 8081:8081

  2. アプリケーションが実行されていて HTTP 要求に応答していることを確認します。

    curl -v \http://127.0.0.1:8081/

    これにより、API アクセスの問題が Mule アプリケーション自体にあるかどうかを判断できます。

  3. そのアプリケーションサービスのイングレスリソースが存在することを検証します。

    kubectl get ingress -n [NAMESPACE]

  4. サービスが作成されたことを検証します。

    kubectl get svc -n [NAMESPACE]

作成されなかった場合は、Runtime Fabric エージェントのログを確認します。

+

kubectl logs -n rtf [AGENT_POD_NAME] -f

サービスおよびイングレスオブジェクトに問題がないように思われる場合は、その他のトラブルシューティングタスクを確認してください。

イングレスリソースがクラスターで作成されたがそのエンドポイントにアクセスできない

シナリオ: Runtime Manager ではクラスターでイングレスリソースが正常に作成されましたが、404 エラーのためにアプリケーションのエンドポイントにアクセスできません。

この問題をトラブルシューティングする手順は、次のとおりです。

  1. イングレスとサービスのリソースを確認します。

    kubectl get ingress -n<APP-NAMESPACE>
kubectl get svc -n<APP-NAMESPACE>

    次のような結果が返されます。

    # kubectl get ingress -n<APP-NAMESPACE>
NAME                           CLASS       HOSTS               ADDRESS       PORTS     AGE
<INGRESS_RESOURCE>            <INGRESS>    <HOSTNAME>.com      <HOST IP>     80, 443   7m3s

# kubectl get svc -n<APP-NAMESPACE>
NAME             TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                      AGE
<SERVICE-NAME>       ClusterIP   <CLUSTER IP>   <none>        8081/TCP,8082/TCP,5701/TCP   8m5s

  2. アプリケーションのイングレスリソースを確認して、リソース、アノテーション、ホストの HTTP パスが正常に表示されることを確認します。

    kubectl get ing -n<APP-NAMESPACE> <INGRESS-RESOURCE-NAME> -oyaml

    次のような結果が返されます。

    # kubectl get ing -n<APP-NAMESPACE> <INGRESS-RESOURCE-NAME> -oyaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  labels:
    ingress.rtf.mulesoft.com/svcName: <APP_NAME>
    ingress.rtf.mulesoft.com/svcVersion: <UUID>
…
…
spec:
  ingressClassName: <INGRESS-CLASS>
  rules:
  - host: myapp.example.com
    http:
      paths:
      - backend:
          serviceName: myapp
          servicePort: 8081
        path: /
        pathType: Prefix
  tls:
  - hosts: myapp.example.com
    secretName: example-tls
status:
  loadBalancer:
    ingress:
    - hostname: <hostname>

  3. アプリケーションポッドログを確認して、適切なリスニングポートを設定していることを確認します。

    kubectl logs -f -n<APP-NAMESPACE> <APP-POD-NAME> -c app

    次のような結果が返されます。

    # kubectl logs -f -n<<APP-NAMESPACE> <APP-POD> -c app
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Starting app '<APP_NAME>'                                                     +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
[2021-07-29 21:22:37.842] INFO  QueueXaResourceManager [ArtifactDeployer.start.01] [event: ]: Starting ResourceManager
[2021-07-29 21:22:37.842] INFO  QueueXaResourceManager [ArtifactDeployer.start.01] [event: ]: Started ResourceManager
[2021-07-29 21:22:37.846] INFO  AbstractLifecycleManager [ArtifactDeployer.start.01] [event: ]: Starting Bean: org.mule.runtime.module.extension.internal.runtime.config.ConfigurationProviderToolingAdapter-HTTP_Listener_config
[2021-07-29 21:22:37.859] INFO  GrizzlyHttpServer [ArtifactDeployer.start.01] [event: ]: Listening for connections on 'http://0.0.0.0:8081'
[2021-07-29 21:22:37.874] INFO  FlowConstructLifecycleManager [ArtifactDeployer.start.01] [event: ]: Starting flow: sample-json-backendFlow
[2021-07-29 21:22:38.171] INFO  AbstractLifecycleManager [ArtifactDeployer.start.01] [event: ]: Starting Bean: listener
[2021-07-29 21:22:38.178] INFO  LogUtil [ArtifactDeployer.start.01]:

  4. ログで、リスナーポートがステップ 1 で検出されたサービスポートに一致することを確認します。

  5. ポートが正しい場合、アプリケーションログを確認してアプリケーションがイングレスコントローラーからの要求を受信していることを確認します。

イングレスリソースが AWS アプリケーションのロードバランサーによって認識されない

シナリオ: AWS ALB を使用している場合、アプリケーションおよびエンドポイントを正常にデプロイした場合でもアプリケーションのエンドポイントにアクセスできません。

イングレスに AWS ロードバランサーコントローラーを使用している場合、​ingressClassName: rtf-alb ​ではなく​テンプレートで ​kubernetes.io/ingress.class: rtf-alb​ アノテーションを指定する必要があります。AWS ロードバランサーコントローラーがこれらのアノテーションのためにデプロイされたイングレスリソース用の L7 ロードバランサーを検出して作成するには、​ingress.class​ アノテーションが必要です。