このページでは、Application Delivery を使用して NGINX のデプロイを構成する方法について説明します。デプロイは staging
と prod
の 2 つの環境で実行されます。prod
環境では通常の構成が使用され、staging
では若干変更された構成が使用されます。
要件
このチュートリアルを実行するには、次の準備が必要です。
- Git 2.19.2 以降がローカルにインストールされている。
- プライベート リポジトリの作成権限を持つ GitHub または GitLab アカウント。Application Delivery は、GitHub リポジトリと GitLab リポジトリのみをサポートしています。
- GKE バージョン 1.15 以降が動作しているクラスタ。
- clusterAdmin 権限を持つユーザー。
- Kustomize がローカルにインストールされている必要があります。インストール ガイドに沿ってください。
- デプロイ リポジトリ内の Kubernetes 構成ファイルを検証する場合は、Docker をインストールする必要があります。
始める前に
作業を始める前に、次のことを確認してください。
- Google Kubernetes Engine API が有効になっていることを確認します。 Google Kubernetes Engine API の有効化
- Google Cloud CLI がインストールされていることを確認します。
- 次のいずれかの方法で、プロジェクトにデフォルトの Google Cloud CLI 設定をセットアップします。
- プロジェクトのデフォルトの設定全般を確認する場合は、
gcloud init
を使用します。 gcloud config
を使用して、プロジェクト ID、ゾーン、リージョンを個別に設定します。-
gcloud init
を実行して、次の操作を行います。gcloud init
リモート サーバーで SSH を使用している場合は、
--console-only
フラグを指定して、コマンドがブラウザを起動しないようにします。gcloud init --console-only
- Google Cloud アカウントを使用できるように、gcloud CLI の承認手順を行います。
- 新しい構成を作成するか、既存の構成を選択します。
- Google Cloud プロジェクトを選択します。
- デフォルトの Compute Engine ゾーンを選択します。
- デフォルトの Compute Engine リージョンを選択します。
- デフォルトのプロジェクト ID を設定します。
gcloud config set project PROJECT_ID
- デフォルトの Compute Engine リージョン(例:
us-central1
)を設定します。gcloud config set compute/region COMPUTE_REGION
- デフォルトの Compute Engine ゾーン(例:
us-central1-c
)を設定します。gcloud config set compute/zone COMPUTE_ZONE
gcloud
を最新バージョンに更新します。gcloud components update
gcloud init
gcloud config
デフォルトの場所を設定することで、gcloud CLI のエラー(One of [--zone, --region] must be supplied: Please specify location
など)を防止できます。
- GitHub または GitLab アカウントに SSH 認証鍵を追加します。
ssh
を使用して鍵をテストします。GitHub
sh ssh -T git@github.com
GitLab
sh ssh -T git@gitlab.com
接続の詳細や鍵のパスフレーズの確認を求められる場合があります。接続に成功すると、ターミナルにメッセージが出力されます。
Application Delivery の設定
Application Delivery を使用するには、次の操作を行う必要があります。
- Application Delivery を有効にして新しいクラスタを作成するか、バージョン 1.15 以降を実行している既存の GKE クラスタで Application Delivery を有効にします。
- Application Delivery のコマンドライン ツールである
appctl
をインストールします。
Application Delivery で新しいクラスタを作成する
Application Delivery を有効にして新しいクラスタを作成するには、gcloud CLI またはコンソールを使用します。
gcloud
クラスタを作成します。
gcloud beta container clusters create CLUSTER_NAME \
--cluster-version CLUSTER_VERSION\
--addons ApplicationManager
以下を置き換えます。
CLUSTER_NAME
: 新しいクラスタの名前。CLUSTER_VERSION
: 新しいクラスタのバージョン。GKE 1.15 以降である必要があります。
Console
コンソールで Google Kubernetes Engine ページに移動します。
[add_box 作成] をクリックします。
[Standard] セクションで [構成] をクリックします。
クラスタの名前を指定します。
[コントロール プレーンのバージョン] で 1.15.x 以降を選択します。
必要に応じてクラスタを構成します。
ナビゲーション パネルの [クラスタ] の下の [機能] をクリックします。
[アプリケーション マネージャーを有効にする] のチェックボックスをオンにします。
[作成] をクリックします。
既存のクラスタで Application Delivery を有効にする
既存のクラスタで Application Delivery を有効にするには、gcloud CLI またはコンソールを使用します。
gcloud
既存のクラスタで Application Delivery を有効にするには、次のコマンドを実行します。
gcloud beta container clusters update CLUSTER_NAME \
--update-addons ApplicationManager=ENABLED
CLUSTER_NAME
は、既存のクラスタの名前に置き換えます。
Console
コンソールで Google Kubernetes Engine のページに移動します。
クラスタのリストで、変更するクラスタの名前をクリックします。
[機能] の [アプリケーション マネージャー] フィールドの横にある [edit アプリケーション マネージャーを編集] をクリックします。
[アプリケーション マネージャーを有効にする] のチェックボックスをオンにします。
[変更を保存] をクリックします。
インストールの確認
Application Delivery のインストールのステータスを確認するには、次のコマンドを実行します。
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 を使用できます。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
をインストールするには、gcloud CLI を使用して pkg
をインストールします。
gcloud components install pkg
クラスタで Application Delivery を有効にして、pkg
をインストールすると、最初のアプリケーションをデプロイする準備が整います。
アプリケーションのデプロイ
アプリケーションをデプロイするには、次の手順を行います。
- 新しい Git リポジトリを作成するか、既存のリポジトリを初期化する。
- 基本構成を作成する。
- デプロイ用に 1 つ以上の環境を作成する。
- 必要に応じて、アプリケーション リポジトリ内の環境に構成オーバーレイを適用する。
- pull リクエストまたは merge リクエストの形式でリリース候補版を作成する。
- リリース版をデプロイする。
新しいリポジトリを作成する
appctl
を使用して、GitHub または GitLab に Application Delivery 用のリポジトリを作成します。
- アプリケーション ディレクトリを作成するディレクトリに移動します。
appctl
で Application Delivery のリポジトリを作成します。GitHub
次のコマンドを実行します。
appctl init APP_NAME \ --app-config-repo=github.com/USERNAME/APP_NAME
以下を置き換えます。
APP_NAME
: アプリケーションの名前。USERNAME
: GitHub のユーザー名。
たとえば、GitHub のユーザー名が
octocat
であり、myapp
という名前のアプリケーションを作成する場合は、次のコマンドを実行します。appctl init myapp \ --app-config-repo=github.com/octocat/myapp
GitLab
次のコマンドを実行します。
appctl init APP_NAME \ --app-config-repo=gitlab.com/USERNAME/APP_NAME
以下を置き換えます。
APP_NAME
: アプリケーションの名前。USERNAME
: GitLab のユーザー名。
たとえば、GitLab のユーザー名が
alice
であり、myapp
という名前のアプリケーションを作成する場合は、次のコマンドを実行します。appctl init myapp \ --app-config-repo=gitlab.com/alice/myapp
appctl
によって、新しいプライベート リポジトリの確認を求めるプロンプトが表示されます。
appctl
により、リモートのプライベート Git リポジトリが 2 つ作成されます。
- アプリケーション リポジトリ
github.com/USERNAME/APP_NAME
。このリポジトリは現在のディレクトリにクローンされます。 - デプロイ リポジトリ
github.com/USERNAME/APP_NAME-deployment
。ローカル デプロイ リポジトリは./APP_NAME/.deployment
に保存されます。
これらのリポジトリの内容と構造の詳細については、Application Delivery のコンセプト ガイドをご覧ください。
既存のリポジトリを初期化する
既存のリポジトリがある場合は、GitHub または GitLab で appctl
を使用して、Application Delivery 用のリポジトリを初期化します。
アプリケーション ディレクトリを作成するディレクトリに移動します。
appctl init
コマンドを実行します。これにより、APP_NAME
というディレクトリが作成され、そこにリポジトリのクローンが作成されます。appctl init
コマンドは、リポジトリの./config
ディレクトリに格納されている構成ファイルの Kustomize ベースレイヤを初期化します。--config-path
フラグを使用すると、別の構成パスを指定できます。デフォルトでは、
appctl init
はデプロイ リポジトリの URL としてgithub.com/USERNAME/APP_NAME-deployment
を使用します。--deployment-repo
フラグを使用すると別の URL を指定できます。デプロイ リポジトリが存在しない場合は、appctl
コマンドによって作成されます。GitHub
appctl init APP_NAME \ --app-config-repo=github.com/USERNAME/APP_NAME \ [--config-path=CONFIG_PATH]
以下を置き換えます。
APP_NAME
: アプリケーションの名前。USERNAME
: GitHub のユーザー名。CONFIG_PATH
: リポジトリの構成ディレクトリへのパス(省略可)。省略した場合、デフォルトは./config
です。
たとえば、既存のアプリケーション構成リポジトリが
https://github.com/octocat/myapp
であり、想定するデプロイ リポジトリがhttps://github.com/octocat/myapp-deploy
の場合は、次のコマンドを実行します。appctl init myapp \ --app-config-repo=github.com/octocat/myapp
GitLab
appctl init APP_NAME \ --app-config-repo=gitlab.com/USERNAME/APP_NAME \ [--config-path=CONFIG_PATH]
以下を置き換えます。
APP_NAME
: アプリケーションの名前。USERNAME
: GitLab のユーザー名。CONFIG_PATH
: リポジトリの構成ディレクトリへのパス(省略可)。省略した場合、デフォルトは./config
です。
たとえば、既存のアプリケーション構成リポジトリが
gitlab.com/alice/myapp
の場合は、次のコマンドを実行します。appctl init myapp --app-config-repo=gitlab.com/alice/myapp
基本構成の作成
作業ディレクトリをアプリケーション リポジトリに変更します。
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
これを基本構成とするように、Application Delivery を構成します。次の内容を
config/base/kustomization.yaml
に貼り付けます。#config/base/kustomization.yaml resources: - myapp.yaml
構成のテストと push
アプリケーション リポジトリ ディレクトリから、
kustomize build
を使用して構成をテストします。kustomize build config/base/
構成が有効な場合は、
kustomize
により、適用時にクラスタにデプロイされる YAML が出力されます。YAML を確認後、アプリケーション リポジトリで commit 版を作成し、push します。
git add . git commit -m "Creating APP_NAME" git push origin master
リリース環境の追加
Application Delivery により、アプリケーションが環境にデプロイされます。appctl
を使用してリリースの環境を追加します。
アプリケーション リポジトリのルート ディレクトリに移動します。
appctl
を使用して環境を作成します。appctl env add ENVIRONMENT_NAME \ --cluster=CLUSTER_NAME
以下を置き換えます。
ENVIRONMENT_NAME
: 新しい環境の名前。CLUSTER_NAME
: クラスタの名前。
appctl
により、スキャフォールドされた Kustomize 構成を含む git commit が作成されます。--namespace
を使用して、このアプリケーションのリリース環境の名前空間名を指定できます。指定しない場合、デフォルトの名前空間はAPP_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
必要に応じて、
git log
を使用して Application Delivery による Git リポジトリでの変更を表示します。git log -p *
構成をアプリケーション リポジトリに push します。
git push origin master
省略可: デプロイ リポジトリの確認
デプロイ リポジトリの GitHub または GitLab ページを開きます。たとえば、GitHub ユーザー名が octocat
で、作成したアプリケーション名が myapp
の場合、URL は https://github.com/octocat/myapp-deployment
です。このページから、各環境用に作成されたブランチを確認できます。
環境のデプロイ
Application Delivery を使用して環境をデプロイするには、次の手順を行います。
git tag
を使用してバージョンを作成し、そのタグを push します。git tag VERSION git push origin VERSION
VERSION
は、アプリケーションのバージョン番号に置き換えます。たとえば、バージョン
v0.1.0
を push するには、次のコマンドを実行します。git tag v0.1.0 git push origin v0.1.0 ```
appctl prepare
を使用して、現在タグ付けされているバージョンを指定し、確認のためにデプロイ リポジトリで pull リクエストを生成します。appctl prepare ENVIRONMENT_NAME
たとえば、
staging
環境を使用する場合は、次のコマンドを実行します。appctl prepare staging \ --validate=true
これにより、kpt 検証関数
gcr.io/kustomize-functions/example-validator
がトリガーされ、デプロイ リポジトリに push される変更が検証されます。kpt は
gcloud components install pkg
によってインストールされます。この検証関数では、内部で kubeval を実行します。これは、Kubernetes OpenAPI 仕様のスキーマを使用して Kubernetes 構成ファイルを検証します。kpt prepare staging --validate
を実行するには、マシンに Docker をインストールする必要があります。デフォルトでは、
--validate
フラグは無効になっています。appctl
がデプロイ リポジトリへの commit を完了すると、次のような pull リクエストの URL が出力されます。Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"
pull リクエストが承認された後、
appctl apply
を使用してデプロイを完了します。appctl apply ENVIRONMENT_NAME
ENVIRONMENT_NAME
は、環境の名前に置き換えます。たとえば、
staging
環境に変更をデプロイするには、次のコマンドを実行します。appctl apply staging
kubectl
を使用するか、コンソールからアプリケーションが実行されていることを確認します。kubectl
kubectl describe
を使用してアプリケーションのステータスを表示します。kubectl get releasetracks.app.gke.io APP_NAME \ --n NAMESPACE \ -w
以下を置き換えます。
APP_NAME
: アプリケーション リポジトリの名前。NAMESPACE
: 環境の作成時に指定した名前空間名。名前空間名を指定しなかった場合、デフォルトはAPP_NAME-ENVIRONMENT_NAME
です。
たとえば、
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 でデプロイされたアプリケーションのステータスとバージョン情報を確認するには、コンソールの GKE [アプリケーション] ページをご覧ください。
リリース版をプロモートする
環境間でリリース候補版をプロモートするには、次のコマンドを実行します。
appctl prepare TARGET_ENVIRONMENT \ --from-env=SOURCE_ENVIRONMENT
以下を置き換えます。
TARGET_ENVIRONMENT
: リリース候補をデプロイする環境の名前。SOURCE_ENVIRONMENT
: 現在の環境の名前。
たとえば、
staging
からprod
へプロモートするには、次のコマンドを実行します。appctl prepare prod --from-env=staging
GitHub または GitLab を使用して、pull リクエストを確認して承認します。
リリース候補版をターゲット環境にデプロイするには、次のコマンドを実行します。
appctl apply TARGET_ENVIRONMENT
たとえば、
prod
環境にデプロイするには、次のコマンドを実行します。appctl apply prod
コンソールでの環境の表示
環境のアプリケーションがデプロイされると、GKE アプリケーションのページに表示されます。このページには、アプリケーションのリストが表示されます。アプリケーションの環境はかっこ内に示されます。次のスクリーンショットでは、staging
と prod
の 2 つの環境を持つアプリケーション myapp
が表示されています。このページには、各環境の名前空間、クラスタ、バージョンも表示されます。
git タグ、コンポーネント、環境リストなど、アプリケーションの詳細を表示するには、アプリケーション名をクリックします。次のスクリーンショットでは、myapp
の詳細が表示されています。
環境の構成を変更する
このセクションでは、staging
環境が前の手順のように構成されていることを前提としています。前の手順は、使用環境に合わせて変更可能です。
このセクションでは、kustomize オーバーレイを使用して staging
環境のパラメータを変更します。変更後、git で変更を push してタグ付けします。Application Delivery により、クラスタが更新されます。
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
config/envs/staging/kustomization.yaml
ファイルを編集し、patch-replicas.yaml
をpatchesStrategicMerge
という新しいコレクションに追加します。#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
kustomize build
を使用して、構成をテストします。kustomize build config/envs/staging/
変更を追加して commit します。
git add . git commit -m "<var>COMMIT_MESSAGE</var>" git push origin master
COMMIT_MESSAGE
は、変更内容を説明するメッセージに置き換えます。git tag
を使用してバージョンを作成し、作成したバージョンを push します。git tag VERSION git push origin VERSION
VERSION
は、必要なバージョン番号に置き換えます。確認のため、デプロイ リポジトリで
appctl prepare
を使用して pull リクエストを生成します。appctl prepare ENVIRONMENT_NAME
リンク先で GitHub または GitLab の pull リクエストを作成します。
pull リクエストの内容を確認します。Application Delivery により、
replicas
を1
とする変更が 1 行加えられています。GitHub または GitLab を使用して pull リクエストを承認します。
appctl apply
を使用して変更を適用します。appctl apply staging
構成変更のロールバック
以前のリリースにロールバックするには、次のコマンドを実行します。
appctl apply TARGET_ENVIRONMENT \
--from-tag GIT_TAG
以下を置き換えます。
TARGET_ENVIRONMENT
: リリースをデプロイする環境の名前。GIT_TAG
: リリースのタグの名前。
スクリプトでの appctl
の使用
appctl
ツールはインタラクティブ形式であり、デフォルトではユーザーからの入力を想定しています。appctl
をスクリプト、コンテナ、パイプラインで実行する場合は、環境変数 APPCTL_INTERACTIVE
を false
に設定します。
たとえば、bash シェルで次のコマンドを実行します。
export APPCTL_INTERACTIVE=false
appctl
コマンドの個別の説明は、appctl help command
により確認できます。たとえば、appctl prepare
のヘルプを表示するには、appctl help prepare
を実行します。
アプリケーション マネージャーのアンインストール
クラスタで実行中のアプリケーションを削除するには、新しい環境に作成された名前空間をすべて削除します。
すべての環境とクラスタに対して、次のコマンドを繰り返し実行します。
指定の環境のクラスタに切り替えます。
kubectl config use-context ENVIRONMENT_CLUSTER_NAME
ENVIRONMENT_CLUSTER_NAME
は、選択した環境のクラスタの名前に置き換えます。この環境のアプリケーションが動作している名前空間を削除します。
kubectl delete ns NAMESPACE
NAMESPACE
は、削除する名前空間の名前に置き換えます。デフォルトはAPP_NAME-ENVIRONMENT_NAME
です。GitHub または GitLab から、
appctl
によって作成された 2 つの Git リポジトリを削除します。ローカルのアプリケーション ディレクトリを削除します。
rm -rf myapp/
gcloud
またはコンソールから、クラスタの Application Delivery を無効にできます。gcloud
gcloud beta container clusters update CLUSTER_NAME \ --update-addons ApplicationManager=DISABLED
コンソール
コンソールで Google Kubernetes Engine のページに移動します。
クラスタのリストで、変更するクラスタの名前をクリックします。
[機能] の [アプリケーション マネージャー] フィールドの横にある [edit アプリケーション マネージャーを編集] をクリックします。
[アプリケーション マネージャーを有効にする] チェックボックスをオフにします。
[変更を保存] をクリックします。
次のステップ
Kustomize の詳細を見る。