Application Delivery によるアプリケーションの管理


このページでは、Application Delivery を使用して NGINX のデプロイを構成する方法について説明します。デプロイは stagingprod の 2 つの環境で実行されます。prod 環境では通常の構成が使用され、staging では若干変更された構成が使用されます。

要件

このチュートリアルを実行するには、次の準備が必要です。

  • Git 2.19.2 以降がローカルにインストールされている。
  • プライベート リポジトリの作成権限を持つ GitHub または GitLab アカウント。Application Delivery は、GitHub リポジトリと GitLab リポジトリのみをサポートしています。
  • GKE 1.15 以降が動作しているクラスタ。
  • clusterAdmin 権限を持つユーザー。
  • Kustomize がローカルにインストールされている必要があります。インストール ガイドに沿ってください。
  • デプロイ リポジトリ内の Kubernetes 構成ファイルを検証する場合は、Docker をインストールする必要があります。

始める前に

作業を始める前に、次のことを確認してください。

次のいずれかの方法で gcloud のデフォルトの設定を指定します。

  • gcloud init。デフォルトの設定全般を確認する場合に使用します。
  • gcloud config。プロジェクト ID、ゾーン、リージョンを個別に設定する場合に使用します。

gcloud init の使用

エラー One of [--zone, --region] must be supplied: Please specify location を受信した場合は、このセクションの内容を実施します。

  1. gcloud init を実行して、次の操作を行います。

    gcloud init

    リモート サーバーで SSH を使用している場合は、--console-only フラグを指定して、コマンドがブラウザを起動しないようにします。

    gcloud init --console-only
  2. 手順に従って gcloud を承認し、Google Cloud アカウントを使用します。
  3. 新しい構成を作成するか、既存の構成を選択します。
  4. Google Cloud プロジェクトを選択します。
  5. ゾーンクラスタの場合はデフォルトの Compute Engine ゾーン、リージョン クラスタまたは Autopilot クラスタの場合はデフォルトの Compute Engine リージョンを選択します。

gcloud config の使用

  • デフォルトのプロジェクト ID を設定します。
    gcloud config set project PROJECT_ID
  • ゾーンクラスタを使用する場合は、デフォルトのコンピューティング ゾーンを設定します。
    gcloud config set compute/zone COMPUTE_ZONE
  • Autopilot クラスタまたはリージョン クラスタを使用する場合は、デフォルトのコンピューティング リージョンを設定します。
    gcloud config set compute/region COMPUTE_REGION
  • gcloud を最新バージョンに更新します。
    gcloud components update
  • GitHub または GitLab アカウントに SSH 認証鍵を追加します。
  • ssh を使用して鍵をテストします。

    GitHub

    ssh -T git@github.com

    GitLab

    ssh -T git@gitlab.com

    接続の詳細や鍵のパスフレーズの確認を求められる場合があります。接続に成功すると、ターミナルにメッセージが出力されます。

Application Delivery の設定

Application Delivery を使用するには:

  1. 新しいクラスタを作成して有効にするか、バージョン 1.15 以降を実行している既存の GKE クラスタで有効にします。
  2. Application Delivery のコマンドライン ツールである appctl をインストールします。

Application Delivery で新しいクラスタを作成する

Application Delivery を有効にして新しいクラスタを作成するには、gcloud または Cloud Console を使用します。

gcloud

1.15.x 以降のクラスタ バージョンを指定します。

gcloud beta container clusters create cluster-name \
    --cluster-version cluster-version --addons ApplicationManager

Console

  1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

    Google Kubernetes Engine のメニューに移動

  2. [ 作成] をクリックします。

  3. クラスタの名前を指定します。

  4. [マスターのバージョン] で 1.15.x 以降のバージョンを選択します。

  5. 必要に応じてクラスタを構成します。

  6. ナビゲーション パネルの [クラスタ] の下の [機能] をクリックします。

  7. [アプリケーション マネージャーを有効にする] のチェックボックスをオンにします。

  8. [作成] をクリックします。

既存のクラスタで Application Delivery を有効にする

既存のクラスタで Application Delivery を有効にするには、gcloud または Cloud Console を使用します。

gcloud

gcloud beta container clusters update cluster-name \
    --update-addons ApplicationManager=ENABLED

Console

  1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

    Google Kubernetes Engine のメニューに移動

  2. クラスタのリストで、変更するクラスタの名前をクリックします。

  3. [機能] の [アプリケーション マネージャー] フィールドの横にある [ アプリケーション マネージャーを編集] をクリックします。

  4. [アプリケーション マネージャーを有効にする] のチェックボックスをオンにします。

  5. [変更を保存] をクリックします。

インストールの確認

Application Delivery のインストールのステータスを確認するには、次のコマンドを実行します。

  1. Deployment のステータスを確認します。

    kubectl get deployment application-controller-manager -n application-system
    

    出力は次のようになります。

    NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
    application-controller-manager   2/2     2            2           1h
    

    この application-controller-manager Deployment では 2 つの Pod を使用できます。

  2. StatefulSet のステータスを確認します。

    kubectl get statefulset kalm-controller-manager -n kalm-system
    

    出力は次のようになります。

    NAME                      READY   AGE
    kalm-controller-manager   1/1     1h
    

    この kalm-controller-manager StatefulSet には 1 つの Pod があります。

appctl のインストール

Application Delivery コマンドライン ツール appctl を含む pkggcloud でインストールします。

gcloud components install pkg

クラスタで Application Delivery を有効にして、pkg をインストールすると、最初のアプリケーションをデプロイする準備が整います。

アプリケーションのデプロイ

アプリケーションをデプロイするには、次のタスクを行います。

  1. 新しい git リポジトリを作成するか、既存のリポジトリを初期化する。
  2. 基本構成を作成する。
  3. デプロイ用に 1 つ以上の環境を作成する。
  4. 必要に応じて、アプリケーション リポジトリ内の環境に構成オーバーレイを適用する。
  5. pull リクエストまたは merge リクエストの形式でリリース候補版を作成する。
  6. リリース版をデプロイする。

新しいリポジトリを作成する

appctl を使用して、GitHub または GitLab に Application Delivery 用のリポジトリを作成します。

  1. アプリケーション ディレクトリを作成するディレクトリに移動します。
  2. appctl で Application Delivery のリポジトリを作成します。

    GitHub

    appctl init application-name \
      --app-config-repo=github.com/user-name/application-name

    たとえば、GitHub のユーザー名が octocat で、myapp という名前のアプリケーションを作成する場合は、次のコマンドを実行します。

    appctl init myapp --app-config-repo=github.com/octocat/myapp

    GitLab

    appctl init application-name \
      --app-config-repo=gitlab.com/user-name/application-name

    たとえば、GitLab のユーザー名が alice で、myapp という名前のアプリケーションを作成する場合は、次のコマンドを実行します。

    appctl init myapp --app-config-repo=gitlab.com/alice/myapp

  3. appctl から、新しいプライベート リポジトリの確認を求められます。

appctl により、リモートのプライベート git リポジトリが 2 つ作成されます。

  • アプリケーション リポジトリ github.com/user-name/application-name。このリポジトリは現在のディレクトリにクローンされます。
  • デプロイ リポジトリ github.com/user-name/application-name-deployment。ローカル デプロイ リポジトリは ./application-name/.deployment に保存されます。

これらのリポジトリの内容と構造の詳細については、Application Delivery のコンセプト ガイドをご覧ください。

既存のリポジトリを初期化する

既存のリポジトリがある場合は、GitHub または GitLab で appctl を使用して、Application Delivery 用のリポジトリを初期化します。

  1. アプリケーション ディレクトリを作成するディレクトリに移動します。

  2. appctl init コマンドを実行します。これにより、application-name というディレクトリが作成され、そこにリポジトリのクローンが作成されます。

    appctl init コマンドは、リポジトリの ./config ディレクトリに格納されている構成ファイルの Kustomize ベースレイヤを初期化します。--config-path フラグを使用すると、別の構成パスを指定できます。

    デフォルトでは、appctl init はデプロイ リポジトリの URL として github.com/user-name/application-name-deployment を使用します。--deployment-repo フラグを使用すると別の URL を指定できます。デプロイ リポジトリが存在しない場合、appctl コマンドによって作成されます。

    GitHub

    appctl init application-name \
        --app-config-repo=github.com/user-name/application-name \
        [--config-path=config-path]

    たとえば、既存のアプリケーション構成リポジトリが https://github.com/octocat/myapp で、デプロイ リポジトリが https://github.com/octocat/myapp-deploy の場合、次のコマンドを実行します。

    appctl init myapp --app-config-repo=github.com/octocat/myapp

    GitLab

    appctl init application-name \
      --app-config-repo=gitlab.com/user-name/application-name \
      [--config-path=config-path]

    たとえば、既存のアプリケーション構成リポジトリが gitlab.com/alice/myapp の場合、次のコマンドを実行します。

    appctl init myapp --app-config-repo=gitlab.com/alice/myapp

基本構成の作成

  1. 作業ディレクトリをアプリケーション リポジトリに変更します。たとえば、アプリケーション名として myapp を使用した場合は、次のコマンドを実行します。

    cd myapp
  2. Kubernetes ワークロードの構成を作成します。有効な Kubernetes Deployment を指定できます。

    次の構成では、nginx コンテナの 3 つのレプリカをデプロイする nginx という名前のアプリケーションを定義します。構成をファイル config/base/myapp.yaml にコピーします。LoadBalancer を有効にする場合は、行 type: LoadBalancer のコメントを解除します。

    #myapp/config/base/myapp.yaml
    
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
    spec:
      # if your cluster supports it, uncomment the following to automatically create
      # an external load-balanced IP for the frontend service.
      # type: LoadBalancer
      ports:
        - port: 80
      selector:
        app: nginx
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: nginx
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: nginx:1.7.9
            ports:
            - containerPort: 80
    
  3. これを基本構成とするように、Application Delivery を構成します。次の内容を config/base/kustomization.yaml に貼り付けます。

    #config/base/kustomization.yaml
    
    resources:
      - myapp.yaml
    

構成のテストと push

  1. アプリケーション リポジトリ ディレクトリから、kustomize build を使用して構成をテストします。

    kustomize build config/base/

    構成が有効な場合は、kustomize により、適用時にクラスタにデプロイされる YAML が出力されます。

  2. YAML を確認後、アプリケーション リポジトリで commit 版を作成し、push します。

    git add .
    git commit -m "Creating application-name"
    git push origin master

リリース環境の追加

Application Delivery により、アプリケーションが環境にデプロイされます。appctl を使用してリリースの環境を追加します。

  1. アプリケーション リポジトリのルート ディレクトリに移動(cd myapp など)します。
  2. appctl を使用して環境を作成します。

    appctl env add environment-name --cluster=cluster-name

    appctl により、スキャフォールドされた Kustomize 構成を含む git commit が作成されます。

    --namespace を使用して、このアプリケーションのリリース環境の名前空間名を指定できます。そうでない場合、デフォルトの名前空間名は application-name-environment-name になります。たとえば、デフォルトの名前空間名を使用して staging 環境と prod 環境をクラスタ application-cluster に追加するには、次のコマンドを実行します。

    appctl env add staging --cluster=application-cluster
    appctl env add prod --cluster=application-cluster

    test 名前空間の test 環境をクラスタ application-cluster に追加するには、次のコマンドを実行します。

    appctl env add test --cluster=application-cluster --namespace=test

    環境を追加する場合は、この環境のデプロイ リポジトリで pull リクエストとコードレビューが必要かどうか検討する必要があります。デフォルトでは、pull リクエストが作成されます。環境が本番環境の条件に該当せず、コードレビューが不要な場合は、--review-required=false を使用して pull リクエストを作成する必要はありません。たとえば、pull リクエストを作成する必要のない test 環境を追加します。

    appctl env add test --cluster=application-cluster --review-required=false

  3. 必要に応じて、git log を使い、Application Delivery による Git リポジトリでの変更を確認できます。

    git log -p *
  4. 構成をアプリケーション リポジトリに push します。

    git push origin master

省略可: デプロイ リポジトリの確認

デプロイ リポジトリの GitHub または GitLab ページを開きます。たとえば、GitHub ユーザー名が octocat で、作成したアプリケーション名が myapp の場合、URL は https://github.com/octocat/myapp-deployment です。このページから、各環境用に作成されたブランチを確認できます。

環境のデプロイ

Application Delivery を使用して環境をデプロイするには、次の手順を行います。

  1. git tag を使用してバージョンを作成し、そのタグを push します。

    git tag version
    git push origin version

    たとえば、バージョン v0.1.0 を push するには、次のコマンドを実行します。

    git tag v0.1.0
    git push origin  v0.1.0

  2. appctl prepare を使用して、現在タグ付けされているバージョンを指定し、確認のためにデプロイ リポジトリで pull リクエストを生成します。

    appctl prepare environment-name

    たとえば、staging 環境を使用する場合は、次のコマンドを実行します。

    appctl prepare staging --validate=true

    これにより、kpt 検証関数 gcr.io/kustomize-functions/example-validator がトリガーされ、デプロイ リポジトリに push される変更が検証されます。

    kptgcloud components install pkg によってインストールされます。この検証関数では、内部で kubeval を実行します。これは、Kubernetes OpenAPI 仕様からのスキーマを使用して Kubernetes 構成ファイルを検証します。

    kpt prepare staging --validate を実行するには、マシンに [Docker をインストール]](https://docs.docker.com/engine/install/){:external}する必要があります。

    デフォルトでは「--validate」フラグは無効になっています。

    appctl がデプロイ リポジトリへの commit を完了すると、次のような pull リクエストの URL が出力されます。

    Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"
    
  3. GitHub または GitLab を使用して、pull リクエストを確認して承認します。

  4. pull リクエストが承認された後、appctl apply を使用してデプロイを完了します。

    appctl apply environment-name

    たとえば、staging 環境に変更をデプロイするには、次のコマンドを実行します。

    appctl apply staging
  5. kubectl を使用するか、Cloud Console からアプリケーションが実行されていることを確認します。

    kubectl

    kubectl describe を使用してアプリケーションのステータスを表示します。

     kubectl get releasetracks.app.gke.io application-name -n \
         [application-name-environment-name or customized_namespace`] -w

    以下を置き換えます。

    • application-name: アプリケーション リポジトリの名前。
    • environment-name: 環境の名前。
    • customized_namespace: env add で前に指定した名前空間名。

    たとえば、myapp というアプリケーション名の staging 環境のステータスを確認するには、次のコマンドを実行します。

    kubectl get releasetracks.app.gke.io myapp -n myapp-staging

    env add --namespace test によって追加された test 環境のステータスを確認するには、次のコマンドを実行します。

    kubectl get releasetracks.app.gke.io myapp -n test

    Console

    Application Delivery でデプロイされたアプリケーションのステータスとバージョン情報を確認するには、Cloud Console の GKE [アプリケーション] ページをご覧ください。

リリース版をプロモートする

  1. 環境間でリリース候補版をプロモートするには、次のコマンドを実行します。

    appctl prepare target-environment-name \
        --from-env source-environment-name

    以下を置き換えます。

    • target-environment-name: リリース候補をデプロイする環境の名前。
    • source-environment-name: 現在の環境の名前。

    たとえば、staging から prod へプロモートするには、次のコマンドを実行します。

    appctl prepare prod --from-env staging

  2. GitHub または GitLab を使用して、pull リクエストを確認して承認します。

  3. リリース候補版をターゲット環境にデプロイするには、次のコマンドを実行します。

    appctl apply target-environment-name

    たとえば、prod 環境にデプロイするには、次のコマンドを実行します。

    appctl apply prod

Cloud Console での環境の表示

環境のアプリケーションがデプロイされると、GKE アプリケーションのページに表示されます。このページには、アプリケーションのリストが表示されます。アプリケーションの環境はかっこ内に示されます。次のスクリーンショットでは、stagingprod の 2 つの環境を持つアプリケーション myapp が表示されています。このページには、各環境の名前空間、クラスタ、バージョンも表示されます。

アプリケーション ページのスクリーンショット

git タグ、コンポーネント、環境リストなど、アプリケーションの詳細を表示するには、アプリケーション名をクリックします。次のスクリーンショットでは、myapp の詳細が表示されています。

アプリケーションの詳細ページのスクリーンショット。

環境の構成を変更する

このセクションでは、staging 環境が前の手順のように構成されていることを前提としています。前の手順は、使用環境に合わせて変更可能です。

このセクションでは、kustomize オーバーレイを使用して staging 環境のパラメータを変更します。変更後、git で変更を push してタグ付けします。Application Delivery により、クラスタが更新されます。

  1. config/envs/staging/patch-replicas.yaml という名前のファイルを作成し、次のテキストをコピーします。これにより、staging 環境の構成が更新され、3 つのレプリカではなく 1 つのレプリカが実行されるようになります。

    #config/envs/staging/patch-replicas.yaml
    
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 1
    
  2. config/envs/staging/kustomization.yaml ファイルを編集し、patch-replicas.yamlpatchesStrategicMerge という新しいコレクションに追加します。

    #config/envs/staging/kustomization.yaml
    namespace: myapp-staging
    bases:
       - ../../base
    patchesStrategicMerge:
       - patch-replicas.yaml
    

    このオーバーレイには、環境固有のアノテーションも追加できます。次の例では、名前が oncall-team のアノテーションを追加することで、この環境下のすべてのリソース版にそれを追加します。詳細については、Kustomize ファイルのフィールドをご覧ください。

    #config/envs/staging/kustomization.yaml
    
    #Don't change the namespace field
    namespace: myapp-staging
    bases:
       - ../../base
    patchesStrategicMerge:
       - patch-replicas.yaml
    commonAnnotations:
      oncall-team: staging-oncall@foo.bar
    
  3. kustomize build を使用して、構成をテストします。

    kustomize build config/envs/staging/

  4. 変更を追加して commit します。

    git add .
    git commit -m "commit-message"
    git push origin master

    commit-message は、変更内容を説明するメッセージに置き換えます。

  5. git tag を使用してバージョンを作成し、それを push します。

    git tag version
    git push origin  version
  6. 確認のため、デプロイ リポジトリで appctl prepare を使用して pull リクエストを生成します。

    appctl prepare environment-name
  7. リンク先で GitHub または GitLab の pull リクエストを作成します。

  8. pull リクエストの内容を確認します。Application Delivery により、replicas1 とする変更が 1 行加えられています。

  9. GitHub か GitLab を使用して pull リクエストを承認します。

  10. appctl apply を使用して変更を適用します。

    appctl apply staging

構成変更のロールバック

以前のリリースにロールバックするには、次のコマンドを実行します。

appctl apply target-environment-name --from-tag git-tag

以下を置き換えます。

  • target-environment-name: リリースをデプロイする環境の名前。
  • git-tag: リリースのタグの名前。

スクリプトでの appctl の使用

appctl ツールは対話型で、デフォルトでは、ユーザーからの入力を想定しています。appctl をスクリプト、コンテナ、パイプラインで実行する場合は、環境変数 APPCTL_INTERACTIVEfalse に設定します。

たとえば、bash シェルで次のコマンドを実行します。

export APPCTL_INTERACTIVE=false

appctl コマンドの個別の説明は、appctl help command により確認できます。たとえば、appctl prepare のヘルプを表示するには、appctl help prepare を実行します。

アプリケーション マネージャーのアンインストール

クラスタで実行中のアプリケーションを削除するには、新しい環境に作成された名前空間をすべて削除します。

すべての環境とクラスタに対して、次のコマンドを繰り返し実行します。

  1. 指定の環境のクラスタに切り替えます。

    kubectl config use-context ${CONTEXT_OF_ENV_CLUSTER}
  2. この環境のアプリケーションが動作している名前空間を削除します。

     kubectl delete ns [application-name-environment-name or customized_namespace`]

    以下を置き換えます。

    • application-name: アプリケーション リポジトリの名前。
    • environment-name: 環境の名前。
    • customized_namespace: env add で前に指定した名前空間名。
  3. GitHub か GitLab から、appctl によって作成された 2 つの git リポジトリを削除します。

  4. ローカルのアプリケーション ディレクトリを削除します。

    rm -rf myapp/
  5. gcloud または Cloud Console から、クラスタの Application Delivery を無効にできます。

    gcloud

    gcloud beta container clusters update cluster-name \
    --update-addons ApplicationManager=DISABLED

    Console

    1. Cloud Console で Google Kubernetes Engine のメニューに移動します。

      Google Kubernetes Engine のメニューに移動

    2. クラスタのリストで、変更するクラスタの名前をクリックします。

    3. [機能] の [アプリケーション マネージャー] フィールドの横にある [ アプリケーション マネージャーを編集] をクリックします。

    4. [アプリケーション マネージャーを有効にする] チェックボックスをオフにします。

    5. [変更を保存] をクリックします。

次のステップ

Kustomize の詳細を見る。