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

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

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

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

  • Cloud Marketplace カタログでアプリを見つける
  • Google Cloud コンソールを使用して、アプリを GKE または GKE Enterprise クラスタにデプロイする
  • Google Cloud コンソールを使用して、実行中のアプリを操作する。

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

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

始める前に

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

概要

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

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

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

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

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

  • アプリは x86 プロセッサを使用するノードで実行する必要があります。

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

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

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

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

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

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

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

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

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

構成の要件

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)への認証とレポート送信を処理します。 料金モデルを送信すると、Cloud Marketplace チームにより、アプリがレポートを作成するためのサービスと、使用状況を測定するための課金指標が作成されます。

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

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

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

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

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

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

ベスト プラクティスに従って、使用状況を報告し、Google が使用状況データを受信せず、顧客に課金が発生しないケースを処理します。

課金エージェントの統合

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

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

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

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

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

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

料金請求エージェントには、使用状況レポートを Google に送信できるようにするための認証情報が必要です。Cloud Marketplace では、ユーザーが 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 コンポーネントも提供する場合、オプションとして Cloud Marketplace Procurement サービスを使用して、その SaaS コンポーネントで定期的に資格情報 ID の有効性をチェックできます。Procurement サービスへのアクセスについては、パートナー エンジニアにお問い合わせください。

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

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

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

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

アプリイメージが Debian などのベースイメージや、Python、OpenJDK などの言語ランタイム イメージに依存する場合は、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)は、お客様が 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 スキーマをご覧ください。

GPU クラスタのリクエスト

アプリで特定の GPU が必要な場合、または GPU が多用される場合は、deployer スキーマを使用して、クラスタ内の GPU のタイプと数を指定できます。GPU のニーズを指定すると、支援されるクラスタの作成が無効になります。

アプリで汎用 Nvidia GPU または特定の Nvidia プラットフォームをリクエストできます。

認証プロセスの要件

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

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

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

これらの機能テストのパッケージ化、実行、検証を行う方法の詳細については、検証の統合に関するドキュメントをご覧ください。

ユーザーガイドの要件

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

概要

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

1 回限りの設定

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

インストール

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

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

基本的な使用法

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

バックアップと復元

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

イメージの更新

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

スケーリング

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

削除

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