アプリのパッケージ化の要件

このページでは、Kubernetes アプリをパッケージ化するための要件と、その要件を満たすためのガイドラインについて説明します。

アプリ パッケージは、ユーザーの Kubernetes クラスタにデプロイされるコンテナ イメージと構成ファイルがまとめられたものです。Google Cloud Console から Google Kubernetes Engine にアプリをデプロイできるようにするには、アプリ パッケージに Deployment コンテナが含まれている必要があります。Deployment コンテナは構成ファイルと表示メタデータを Kubernetes API に push します。

Google Cloud ユーザーはアプリ パッケージを使用して次のことができます。

  • Google Cloud Marketplace カタログでアプリを見つける
  • Cloud Console を使用してアプリを GKE または Anthos クラスタにデプロイする
  • Cloud Console を使用して実行中のアプリを操作する

Cloud Console からのデプロイメントのサポートとともに、kubectlHelm などのツールを使用したコマンドライン インターフェース(CLI)からのデプロイの手順もパッケージに含める必要があります。

アプリ パッケージの例については、Google クリック デプロイ ソリューションの GitHub リポジトリをご覧ください。 リポジトリには、WordPress や Elasticsearch など、一般的なオープンソース アプリのパッケージが格納されています。

始める前に

  • Google Cloud 環境の設定が完了していることを確認します。
  • アプリを実行するための構成ファイル、ユーザーガイド、などのリソース用のパブリック Git リポジトリを作成します。GitHub、Cloud Source Repositories などのプロバイダ、または独自のサーバーでリポジトリをホストできます。配布する製品ごとに専用のリポジトリを使用することをおすすめします。

概要

アプリは次の要件を満たす必要があります。

  • Git リポジトリには、リポジトリのオープンソース ライセンスを含む LICENSE ファイルを含める必要があります。

  • Git リポジトリには、アプリをデプロイする構成ファイルが含まれている必要があります。構成ファイルには、Kubernetes YAML マニフェスト、または Helm チャートを使用できます。

    構成には、アプリを説明するアプリケーション カスタム リソースを含める必要があります。

    構成の要件をご覧ください。

  • 必要に応じて、アプリを VMware 上の Anthos クラスタに対応させるには、互換性のためにアプリのイメージを変更します。

    VMware 上の Anthos クラスタをサポートするための要件をご覧ください。

    VMware 上の Anthos クラスタの詳細については、VMware 上の Anthos クラスタの概要をご覧ください。

  • 必要に応じて、Istio との互換性を保つ必要がある場合は、Istio を実行するクラスタの制限を確認してください。

  • アプリが商用の場合は、お客様に料金が正しく請求されるようにするために、アプリからその使用状況を Google に報告する必要があります。利用状況レポートを Google に送信する使用量ベースの料金請求エージェントにアプリを統合することをおすすめします。

    料金請求エージェントを統合するための要件をご覧ください。

  • アプリのすべてのコンテナ イメージを Container Registry のレジストリにアップロードする必要があります。レジストリには、ユーザーが Cloud Console からアプリをデプロイするときにアプリの構成を Google Kubernetes Engine API に push する deployer のイメージも含める必要があります

    アプリイメージを作成するための要件をご覧ください。

  • アプリの統合テストを含める必要があります。

    検証プロセスの要件をご覧ください。

  • コマンドラインからアプリをデプロイする手順、アプリを構成する手順、アプリを使用する手順を記載したユーザーガイドを含める必要があります。

    ユーザーガイドの要件をご覧ください。

構成の要件

構成は、Kubernetes マニフェストまたは Helm チャートとして指定できます。

構成は次の要件を満たしている必要があります。

  • 不安定な API からユーザーを保護するために、ベータ版または一般利用可能な Kubernetes リソースのみを使用します。

  • 構成では、アプリケーション カスタム リソースをデプロイする必要があります。アプリケーション リソースには、ユーザーが Google Cloud Marketplace UI を使用してアプリをデプロイするときに表示される情報を含めます。

    アプリケーション リソースは、アプリに関連付けられている Kubernetes コンポーネントを統合するカスタム リソースです。これにより、ユーザーはそれらのリソースをグループとして管理できます。

    アプリケーション リソースの作成と例については、アプリケーションの GitHub リポジトリをご覧ください。

  • 構成では、envsubst を使用して、またはフラグとして、置換できるパラメータを使用する必要があります。

    以下のパラメータは、置換できる必要があります。

    • 名前空間: 構成のすべてのリソースは単一の名前空間に属している必要があります。Google Cloud Marketplace ユーザーは、アプリをデプロイするときにこの名前空間を構成します。マニフェストで名前空間をハードコーディングしないでください。これにより、指定したリソースがユーザーが選択した名前空間に作成されるようになります。名前空間は、RoleBinding 内の ServiceAccount を参照する場合など、リソース定義の内部で表示されることもあります。このような参照はすべてパラメータ化する必要があります。

    • アプリ名: アプリケーション リソースのインスタンス名。アプリの複数のインスタンスが 1 つの名前空間にデプロイされている場合に名前の競合を避けるために、アプリの各リソースの名前にこの文字列を含める必要があります。

    • コンテナ イメージ: PodSpec 内などでは、イメージの参照はすべて置き換え可能である必要があります。これにより、Google Cloud Marketplace でこれらの参照をオーバーライドして、コンテナ レジストリで公開されているイメージを指すようにできます。また、顧客は変更されたイメージを簡単に置換できます。

    • ライセンス シークレット: アプリが商用メータリングを実行している場合は、シークレット リソースの名前をパラメータとして受け入れる必要があります。シークレットには、使用状況レポートの認証情報が含まれており、アプリはこの認証情報を使用して Google に使用状況データを送信します。

      構成パラメータの詳細については、GitHub をご覧ください。

  • アプリは、クライアント側のツールを使用してデプロイできる必要があります。たとえば、Helm を使用する場合、デプロイは --client-only コマンドライン フラグで機能する必要があります。

VMware 上の Anthos クラスタをサポートするための要件

VMware クラスタ上のお客様の Anthos クラスタは、標準の GKE クラスタとは構成が異なる場合があります。この構成が変動する可能性があるため、VMware 上の Anthos クラスタでアプリを実行する場合は、次のリソースを手動で構成する必要があります。

  • ストレージ クラス

    Google Cloud Marketplace では、VMware クラスタ上のお客様の Anthos クラスタに存在するストレージ クラスを予測できないため、アプリに次の変更を加えることをおすすめします。

    • Persistent Volume Claims(PVC)を作成する際には、ストレージクラスを明示的に参照せずにそのクレームをプロビジョニングさせる。

    • アプリが x-google-marketplace STORAGE_CLASS プロパティを使用している場合、お客様は Cloud Console からアプリをデプロイする際に、自分でストレージ クラスを選択する必要があります。適切なストレージ クラスを選択するようにユーザーをガイドするためのドキュメントを追加することをおすすめします。

  • サービスと Ingress

    Google Cloud Marketplace では、VMware クラスタ上のお客様の Anthos クラスタのネットワーク トポロジとネットワーク コントローラを予測できないため、お客様独自の構成で機能するネットワークをお客様が設定する必要があります。

    基盤となるネットワーク トポロジが Ingress リソースをサポートしていない場合、deployer で Ingress リソースを作成しないでください。アプリがデプロイメントに使用するクライアントに応じて、次の方法でアプリを変更する必要があります。

    • アプリの構成に kubectl と環境変数を使用している場合、デプロイメント環境の違いに合わせてマニフェストの拡張を変更できないため、マニフェストからすべての Ingress リソースを削除することをおすすめします。

    • Helm を使用して構成している場合は、デプロイメント イメージのスキーマで x-google-marketplace INGRESS_AVAILABLE プロパティを使用します。このプロパティが false である場合、deployer で Ingress リソースを作成しないようにします。この値を設定するのは UI デプロイメントのみであることに注意してください。デフォルト値は CLI デプロイメントに使用されます。

      INGRESS_AVAILABLE プロパティ値に基づいて分岐する方法の例については、クリック デプロイ nginx テンプレートをご覧ください。

    デプロイメント コンテナの概要については、デプロイメント コンテナの要件をご覧ください。 deployer のスキーマに関する情報を含む、デプロイメント コンテナを構築する手順の詳細については、Google Cloud Marketplace ツールの GitHub リポジトリをご覧ください。

    ドキュメントのデプロイ後のセクションで、アプリをデプロイした後にお客様がネットワークを設定する手順を追加してください。

  • Kubernetes サービス アカウント

    お客様の Anthos clusters on VMware が Container Registry リポジトリ内のアプリイメージにアクセスできるようにするには、明示的に宣言された Kubernetes サービス アカウントをアプリで使用する必要があります。サービス アカウントは、deployer イメージのスキーマ内に、x-google-marketplace SERVICE_ACCOUNT プロパティを使用して定義する必要があります。

    アプリでは、名前空間のデフォルトのサービス アカウントに利用したり、新しいサービス アカウントを作成したりしてはいけません。すべてのポッド仕様に serviceAccountName プロパティを設定するなどして、サービス アカウントをすべてのワークロードに明示的に指定して、名前空間のデフォルトのサービス アカウントを利用させないようにします。

    明示的なサービス アカウントを使用するアプリについては、Google Click to Deploy の GitHub リポジトリにある Prometheus アプリの次の例を参照してください。

    サービス アカウントの構成については、サービス アカウントに関する Kubernetes のドキュメントをご覧ください。

Istio を使用したクラスタに関する制限

アプリの Istio との互換性を保つには、このセクションで説明されている制限を確認してください。Istio の概要については、What is Istio? をご覧ください。

お客様のクラスタで Istio が実行されている場合、アプリのポッド間のネットワーク トラフィックは、デフォルトでは Istio によって制御されます。このため、次の状況ではネットワーク通信がブロックされる可能性があります。

  • クラスタの IP アドレスを使用している場合、ポッドで kubectl コマンドを実行すると、コマンドが失敗する可能性があります。

  • アプリがポッド間通信または IP ベースの通信を使用している場合、クラスタ形成の手順が失敗する可能性があります。

  • OS パッケージのリポジトリなどのサードパーティ サービスへの外部接続はブロックされる可能性があります。顧客は、外部サービスへのアクセスを可能にするために、Istio の出力トラフィックを構成する必要があります。

LoadBalancer や Ingress のリソースではなく、Istio Gateway を使用して着信接続を構成することをおすすめします。

Helm を使用して構成している場合は、デプロイメント イメージのスキーマで x-google-marketplace ISTIO_ENABLED プロパティを使用します。このプロパティが true である場合、Istio サイドカーの準備ができるまで待つなど、deployer においてデプロイメントを変更する必要があります。

ドキュメントのデプロイ後についてのセクションに、お客様がアプリポッド間通信を設定するための手順を追加することをおすすめします。

課金エージェントを統合するための要件

商用アプリを販売する場合は、従量制課金(UBB)エージェントをアプリに統合することをおすすめします。

このエージェントは、Google の使用状況レポート エンドポイント(Google Service Control)への認証とレポート送信を処理します。 料金モデルを送信すると、Google Cloud Marketplace チームにより、アプリがレポートを作成するためのサービスと、使用状況を測定するための課金指標が作成されます。

ローカルでの集計、障害復旧、再試行もこのエージェントによって管理されます。使用時間指標では、ハートビートを自動的にレポートするようにエージェントを構成できます。

また、このエージェントによってレポート ステータスが公開されます。これにより、使用状況データが正常にレポートされているかをアプリから検出できます。

お客様は Google Cloud Marketplace でアプリを購入してライセンスを取得します。このライセンスは、デプロイ時にアプリに添付されます。

課金エージェントと統合する場合は、使用状況レポートが失敗したときのアプリの動作を考慮してください。レポートが失敗した場合、次のいずれかを示している可能性があります。

  • 顧客がサブスクリプションをキャンセルした。

  • 顧客が誤ってレポート チャネルを無効にした可能性がある。たとえば、顧客が誤ってエージェントを削除したり、間違って構成したりする場合があります。またネットワークが原因でエージェントが Google のレポート エンドポイントにアクセスできなくなる場合もあります。

このような場合、Google は利用状況データを受信しないので、顧客には課金されなくなります

これらの状況では、アプリが自動的に停止するか、機能を無効にできます。アプリの起動中に使用状況レポートが失敗した場合は、顧客がフィードバックをすぐに受信して問題を解決できるように、アプリを自動的に停止させることをおすすめします。

課金エージェントの統合

エージェントは、サイドカー コンテナとして統合できます。このコンテナは、アプリと同じポッドで、または SDK を使用して実行されます。

サイドカー方式では、エージェントはアプリコンテナと同じ Kubernetes Pod 内の独自のコンテナで実行されます。アプリは、エージェントのローカル REST インターフェースと通信します。

SDK 方式では、エージェントをコンパイルするか、アプリのバイナリにリンクする必要があります。SDK は、Python のバインディングを使用して、Go 用にネイティブに実装されています。

一般に、サイドカー方式の方が簡単に統合できます。一方、SDK を使用する場合は、エージェントが誤って無効にされる可能性が小さくなります。

統合の手順について詳しくは、従量制課金エージェントの GitHub リポジトリの README をご覧ください。実装例を確認するには、アプリのリポジトリとツールのリポジトリのサンプルをご覧ください。

使用状況をレポートするための認証情報

料金請求エージェントには、使用状況レポートを Google に送信できるようにするための認証情報が必要です。Google Cloud Marketplace では、ユーザーが Google Cloud Marketplace からアプリをデプロイするときにこれらの認証情報が生成され、アプリがデプロイされる前に生成された認証情報が目的の Kubernetes 名前空間に Secret として存在することを確認します。この際、シークレットの名前が REPORTING_SECRET スキーマ プロパティとしてアプリに渡されます。

報告用のシークレットを使用するマニフェストの例については、GitHub の WordPress アプリの例をご覧ください。

シークレットには次のフィールドがあります。

entitlement-id

ソフトウェアを購入して使用するためのお客様の契約を表す ID。

consumer-id

使用状況レポートとともに Google Service Control に渡される資格情報に関連付けられた ID。

reporting-key

Google Service Control に対する認証のために使用される Google Cloud サービス アカウントの JSON キー。

プロダクトがアプリに加えて SaaS コンポーネントも提供する場合、オプションで Google Cloud Marketplace Procurement サービスを使用して、その SaaS コンポーネントで資格情報 ID の有効性を定期的にチェックできます。Procurement サービスへのアクセスについては、パートナー エンジニアにお問い合わせください。

アプリに渡される追加パラメータの詳細については、このセクションで後述するアプリに渡されるパラメータをご覧ください。

コンテナ イメージをビルドするための要件

アプリは 1 つ以上のアプリコンテナ イメージで構成されます。さらに、リポジトリには Deployment コンテナが含まれている必要があります。Deployment コンテナは、お客様が Google Cloud Marketplace UI からアプリをデプロイするときに使用されます。

コンテナ イメージは通常、Dockerfiledocker build コマンドライン ツールを使用してビルドされます。Dockerfile とコンテナのビルド手順をアプリの公開リポジトリで公開することをおすすめします。それらを公開すると、お客様はイメージを変更したり再ビルドしたりできます。企業の本番環境用にイメージを認定するために、変更や再ビルドが必要になることがあります。

アプリイメージが Debian などのベースイメージや、Python、OpenJDK などの言語ランタイム イメージに依存する場合は、Google Cloud Marketplace の認定コンテナ イメージのいずれかを使用することを強くおすすめします。これらを使用することで、特にセキュリティ パッチのためにベースイメージをタイムリーに更新できます。また、この方法では、ベースイメージに存在するパッケージを考慮する必要がないため、オープンソース ライセンスのレビューが簡素化されます。

アプリイメージをビルドしたら、環境を設定するときに Container Registry で作成したステージング レジストリにそれらのイメージを push します。

Container Registry の構造は、次のとおりにする必要があります。

  • アプリのメインイメージをリポジトリのルートにする必要があります。たとえば、Container Registry リポジトリが gcr.io/exampleproject/exampleapp である場合、アプリのイメージを gcr.io/exampleproject/exampleapp に置く必要があります。

  • デプロイ コンテナのイメージは、deployer というフォルダに置く必要があります。上記の例では、デプロイメント イメージを gcr.io/exampleproject/exampleapp/deployer に置く必要があります。

  • アプリで追加のコンテナ イメージを使用する場合、追加の各イメージをメインイメージの下の独自のフォルダーに置く必要があります。たとえば、アプリで proxy イメージが必要な場合は、そのイメージを gcr.io/exampleproject/exampleapp/proxy に追加します。

  • アプリのイメージはすべて、リリース トラックと現在のバージョンでタグ付けする必要があります。たとえば、2.0 リリース トラックでバージョン 2.0.5 をリリースする場合、すべてのイメージに 2.02.0.5 のタグ付けをする必要があります。リリースの体系化について学ぶ

たとえば、次の画像は、Grafana Cluster Kubernetes アプリの Container Registry リポジトリを示しています。リリース トラックは 5.3 で、アプリにはメインアプリ イメージ、独自のフォルダー内の deployer イメージ、および debian9 内の Debian 9 イメージが含まれています。リポジトリ内のすべてのイメージに、同じトラック(5.3)とそのトラックのバージョン(5.3.4)が付けられています。これは、deployer で宣言されているアプリケーション リソースのカスタム リソース定義(CRD)の「バージョン」フィールドとも一致する必要があります。

Grafana Container Registry のリポジトリ構造の例

リポジトリは gcr.io/cloud-marketplace/google/grafana にあります。

プロダクト ID を選択するときに、以前に選択したコンテナ イメージ ID を使用します。

Container Registry にイメージをアップロードするには、そのイメージにレジストリ名のタグを付け、gcloud を使用してイメージを push します。たとえば、example-pro のイメージを push するには、次のコマンドを使用します。

docker build -t gcr.io/my-project/example-pro:4.0   # release track 4.0
docker tag gcr.io/my-project/example-pro:4.0 gcr.io/my-project/example-pro:4.0.3  # release version 4.0.3
docker push gcr.io/my-project/example-pro:4.0
docker push gcr.io/my-project/example-pro:4.0.3

イメージにタグを付けてレジストリに push する手順について詳しくは、Container Registry のドキュメントをご覧ください。

Deployment コンテナの要件

Deployment コンテナ(deployer)は、お客様が Google Cloud Marketplace からプロダクトをデプロイするときに使用されます。deployer イメージは、アプリの Kubernetes 構成と、構成を Kubernetes API に push する kubectl や Helm などのクライアント ツールをパッケージ化します。deployer では通常、ユーザーがアプリをデプロイするために実行するのと同じ一連のコマンドライン コマンドを使用する必要があります。

deployer を作成するには、ツールのリポジトリの marketplace ディレクトリにあるデプロイメント コンテナのベースイメージの 1 つを使用します。

ベースイメージには、オーナー参照の割り当て、パスワードの生成、デプロイ後のクリーンアップなどのタスク用の組み込みユーティリティが含まれます。

deployer イメージを構築する手順については、Application Deployer の構築をご覧ください。

アプリに渡されるパラメータ

Deployment コンテナでは、お客様がアプリを選択するときに収集する必要があるパラメータを宣言しなければなりません。これらのパラメータは、ユーザーがアプリをデプロイするときにDeployment コンテナに渡されます。

これらのパラメータを構成するには、Deployment コンテナ イメージに YAML 形式の JSON スキーマを含める必要があります(パス; /data/schema.yaml)。

schema.yaml の作成方法については、Deployer スキーマをご覧ください。

認証プロセスの要件

アプリは Google の認証システム内で実行され、次の点が確認されます。

  • インストールの成功: すべてのリソースが適用され、正常になるまで待機します。
  • 機能テストに合格: deployer により テスターポッドが起動され、終了ステータスを監視します。ゼロは成功、ゼロ以外は失敗を意味します。
  • アンインストールの成功: アプリとそのすべてのリソースがクラスタから正常に削除されました。

アプリを Google Cloud Marketplace に公開するには、結果が成功である必要があります。

これらの機能テストをパッケージ化、実行、検証する方法の詳細については、verification-integration.md の手順をご覧ください。

ユーザーガイドの要件

ユーザーガイドには、次の情報を含める必要があります。

概要

  • 基本機能と構成オプションを含む一般的なアプリの概要。このセクションは、Google Cloud Marketplace で公開されているプロダクトにリンクする必要もあります。

1 回限りの設定

  • kubectl や Helm などのクライアント ツールを構成する方法(該当する場合)。
  • アプリケーションの CustomResourceDefinition(CRD)をインストールする方法。これは、クラスタでアプリケーション リソースを管理できるようにするためです。
  • Google Cloud Marketplace からライセンス シークレットを取得してデプロイする手順(商用アプリを販売する場合)。

インストール

  • アプリをデプロイするためのコマンド。
  • UI 構成で使用できるパラメータを渡す方法。
  • 不変ダイジェストにイメージ参照を固定する方法。
  • deployer スキーマにカスタム入力フィールドを追加する場合は、必要に応じて期待値に関する情報を追加します。

    deployer に入力フィールドを追加する方法を学ぶ

基本的な使用法

  • 管理コンソールに接続する方法(該当する場合)。
  • クライアント ツールに接続し、サンプル コマンドを実行する方法(該当する場合)。
  • ユーザー名とパスワードを変更する方法。
  • Ingress を有効にし、TLS 証明書をインストールする方法(該当する場合)。

バックアップと復元

  • アプリの状態をバックアップする方法。
  • バックアップからアプリの状態を復元する方法。

イメージの更新

  • パッチまたはマイナー アップデート用のアプリイメージを更新する方法。

スケーリング

  • アプリをスケーリングする方法(該当する場合)。

削除

  • アプリを削除する方法。
  • PersistentVolumeClaims など、意図的に孤立している可能性のあるリソースをクリーンアップする方法。