アプリのオンボーディング

1. 始める前に

セルフペース型の環境設定

1. Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

• プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列で、いつでも更新できます。
• プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud Console により一意の文字列が自動生成されます（通常は内容を意識する必要はありません）。ほとんどの Codelab では、プロジェクト ID を参照する必要があります（通常、プロジェクト ID は「PROJECT_ID」の形式です）。好みの文字列でない場合は、別のランダムな ID を生成するか、独自の ID を試用して利用可能であるかどうかを確認することができます。プロジェクトの作成後、ID は「フリーズ」されます。
• 3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。

注意: プロジェクト ID はグローバルに一意である必要があります。また、ご自身が選択したプロジェクト ID を他のユーザーが使用することはできません。その ID を使用するのはご自身のみです。プロジェクトが削除された場合も、その ID の再使用はできません。

注: Gmail アカウントを使用している場合は、デフォルトの場所の設定は [組織なし] のままにしてかまいません。Google Workspace アカウントを使用している場合は、組織に適した場所を選択してください。

2. 次に、Cloud のリソースや API を使用するために、Cloud Console で課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルを終了した後に課金が発生しないようにリソースをシャットダウンするには、Codelab の最後にある「クリーンアップ」の手順を行います。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアル プログラムをご利用いただけます。

2. ワークスペースの準備

1. 次の URL にアクセスして Cloud Shell エディタを開きます。

https://ide.cloud.google.com

2. CLI でプロジェクト名が設定されていることを確認する

gcloud config set project {{project-id}}

export PROJECT_ID=$(gcloud config get-value project)

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

3. API を有効にする

gcloud services enable \

cloudbuild.googleapis.com \

secretmanager.googleapis.com

4. CloudDeploy に権限を付与する

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.admin ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/container.developer ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/iam.serviceAccountUser ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.jobRunner ${PROJECT_ID}

5. ターミナル ウィンドウで、次のコマンドを使用してアプリケーション ソースのクローンを作成します。

git clone https://github.com/GoogleCloudPlatform/software-delivery-workshop.git

6. ディレクトリに移動し、IDE ワークスペースをリポジトリのルートに設定します。

cd software-delivery-workshop && rm -rf .git

cd delivery-platform && cloudshell workspace .

3. 事前定義されたカスタム アプリ テンプレートの活用

開発者は、組織内で一般的に使用される一連のテンプレートから選択できる必要があります。オンボーディング プロセスでは、GitHub アカウントに保存されている一元的なテンプレート リポジトリのセットが作成されます。以降の手順で、これらのテンプレート リポジトリがコピーされ、新しいアプリケーションのベースとして使用できるように変更されます。このラボでは、ここに示されているサンプル構造を使用して、テンプレート リポジトリにシードします。サンプルをモデルにしたフォルダを追加することで、独自のテンプレートを追加できます。

このステップでは、提供されたサンプル ファイルから、アプリ テンプレートを保持する独自のリポジトリを作成します。GitHub とのやり取りを簡素化するために、ヘルパースクリプトが用意されています。

これらは、テンプレート リポジトリにデータを入力するために使用される 1 回限りの手順です。以降の手順では、これらのリポジトリを再利用します。

GitHub アクセスを構成する

このチュートリアルの手順では、GitHub API を呼び出してリポジトリを作成し、構成します。以降のさまざまなポイントで、GitHub のユーザー名と個人用アクセス トークンが必要になります。次のスクリプトは、値を取得して後で使用するためにローカル変数として保存するのに役立ちます。

source ./onboard-env.sh

echo Git Username: $GIT_USERNAME

echo Git Base URL: $GIT_BASE_URL

アプリ テンプレート リポジトリを作成する

このラボでは、独自のベース テンプレートを統合する方法の例として、サンプル アプリケーション テンプレートを提供します。このステップでは、GitHub アカウントの mcd-app-templates というリポジトリに、これらのファイルの独自のコピーを作成します。

1. テンプレートを作業ディレクトリにコピーする

cp -R $BASE_DIR/resources/repos/app-templates $WORK_DIR

cd $WORK_DIR/app-templates

2. GitHub アカウントに空のリモート リポジトリを作成する

$BASE_DIR/scripts/git/gh.sh create mcd-app-templates

3. テンプレート リポジトリをリモート リポジトリに push する

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-app-templates

git push origin main

4. 作業ディレクトリをクリーンアップする

cd $BASE_DIR

rm -rf $WORK_DIR/app-templates

共有ベース構成リポジトリを作成する

このチュートリアルでは、複数のチームで共有されるベース構成ファイルを使用し、その上にアプリケーション固有の構成をオーバーレイする Kustomize というツールを使用します。これにより、プラットフォーム チームは多くのチームと環境にわたってスケーリングできます。

このステップでは、提供されたサンプルから mcd-shared_kustomize という共有構成リポジトリを作成します。

1. テンプレートを作業ディレクトリにコピーする

cp -R $BASE_DIR/resources/repos/shared-kustomize $WORK_DIR

cd $WORK_DIR/shared-kustomize

2. GitHub アカウントに空のリモート リポジトリを作成する

$BASE_DIR/scripts/git/gh.sh create mcd-shared_kustomize

3. テンプレート リポジトリをリモート リポジトリに push する

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-shared_kustomize

git push origin main

4. 作業ディレクトリをクリーンアップする

cd $BASE_DIR

rm -rf $WORK_DIR/shared-kustomize

テンプレート リポジトリを作成したら、それらを使用してアプリ インスタンスを作成できます。

4. アプリケーションの新しいインスタンスを作成する

テンプレートから新しいアプリケーションを作成する場合、テンプレート構造内の複数のファイルでプレースホルダ変数を実際の値に置き換えることが必要になることがよくあります。置換が完了すると、新しいアプリ インスタンス用に新しいリポジトリが作成されます。開発者は、このアプリ インスタンス リポジトリをクローンして、日々の開発作業を行います。

このステップでは、アプリ テンプレートの値を置き換え、結果のファイルを新しいリポジトリに投稿します。

新しいアプリケーションの名前を定義する

export APP_NAME=my-app

Golang テンプレート リポジトリを取得する

cd $WORK_DIR/

git clone -b main $GIT_BASE_URL/mcd-app-templates app-templates

rm -rf app-templates/.git

cd app-templates/golang

プレースホルダの値を置き換える

オンボーディングで最も一般的なニーズの 1 つは、テンプレート内の変数をアプリケーションで使用される実際のインスタンスに置き換えることです。たとえば、アプリケーション名を提供します。次のコマンドは、環境変数に保存されている値を使用して、すべての .tmpl ファイルのインスタンスを作成します。

for template in $(find . -name '*.tmpl'); do envsubst < ${template} > ${template%.*}; done

新しいリポジトリを作成して更新されたファイルを保存する

1. GitHub アカウントに空のリモート リポジトリを作成する

$BASE_DIR/scripts/git/gh.sh create ${APP_NAME}

2. テンプレート リポジトリをリモート リポジトリに push する

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/${APP_NAME}

git push origin main

アプリ インスタンスが作成されたので、継続的ビルドを実装します。

5. 自動パイプライン実行の構成

継続的インテグレーション システムの中核となるのは、ソース管理システムで発生したイベントに基づいてパイプライン ロジックを実行する機能です。デベロッパーがリポジトリでコードを commit すると、他のシステムでプロセスをトリガーするように構成できるイベントが起動されます。

このステップでは、ユーザーがリポジトリでコードを commit またはタグ付けするたびに Google Cloud Build を呼び出してパイプラインを実行するように GitHub を構成します。

セキュア アクセスを有効にする

アプリケーション パイプラインへの安全なアクセスを構成するには、2 つの要素が必要です。パイプラインに固有の API キーとシークレット。

API キー

API キーは、特定の API を呼び出すクライアントを識別するために使用されます。この場合、クライアントは GitHub になります。ここで説明していないベスト プラクティスとして、API キーのスコープをクライアントがアクセスする特定の API のみに制限することがあります。鍵は前の手順で作成しました。

1. こちらのリンクをクリックして、キーを確認できます。
2. 次のコマンドを実行して、値が設定されていることを確認できます。

echo $API_KEY_VALUE

パイプライン シークレット

シークレットは、呼び出し元を承認し、特定のクラウドビルド ターゲット ジョブに対する権限があることを確認するために使用されます。GitHub に 2 つのリポジトリがあり、それぞれが独自のパイプラインにのみアクセスできるようにする必要があります。API_KEY は github で使用できる API を制限しますが（この場合は Cloud Build API が呼び出されます）、シークレットは Cloud Build API でクライアントが実行できるジョブを制限します。

1. シークレットの名前、ロケーション、値を定義する

SECRET_NAME=${APP_NAME}-webhook-trigger-cd-secret

SECRET_PATH=projects/${PROJECT_NUMBER}/secrets/${SECRET_NAME}/versions/1

SECRET_VALUE=$(sed "s/[^a-zA-Z0-9]//g" <<< $(openssl rand -base64 15))

2. シークレットを作成する

printf ${SECRET_VALUE} | gcloud secrets create ${SECRET_NAME} --data-file=-

3. Cloud Build にシークレットの読み取りを許可する

gcloud secrets add-iam-policy-binding ${SECRET_NAME} \

--member=serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com \

--role='roles/secretmanager.secretAccessor'

Cloud Build トリガーを作成する

Cloud Build トリガーは、CICD プロセスを実際に実行する構成です。

トリガーを適切に構成するには、ジョブの作成時にいくつかのキー値を指定する必要があります。

4. トリガーの名前と構成ファイルの場所を定義する

export TRIGGER_NAME=${APP_NAME}-clouddeploy-webhook-trigger

export BUILD_YAML_PATH=$WORK_DIR/app-templates/golang/build/cloudbuild-cd.yaml

5. 共有ベース構成リポジトリの場所を定義します。

export KUSTOMIZE_REPO=${GIT_BASE_URL}/mcd-shared_kustomize

6. onboard-env.sh スクリプトで、プロジェクトのコンテナ レジストリを定義する変数が設定されました。次のコマンドを使用して値を確認します。

echo $IMAGE_REPO

7. 前に作成した変数を使用して、CloudBuild Webhook トリガーを作成します。アプリケーション リポジトリの場所は、GitHub からのリクエストの本文から取得されます。以下の値は、リクエスト本文内のパスを参照します。gcloud alpha builds triggers create webhook \

    `--name=${TRIGGER_NAME} \`
   
    `--substitutions='_APP_NAME='${APP_NAME}',_APP_REPO=$(body.repository.git_url),_CONFIG_REPO='${GIT_BASE_URL}'/'${CLUSTER_CONFIG_REPO}',_DEFAULT_IMAGE_REPO='${IMAGE_REPO}',_KUSTOMIZE_REPO='${GIT_BASE_URL}'/'${SHARED_KUSTOMIZE_REPO}',_REF=$(body.ref)' \`
   
    `--inline-config=$BUILD_YAML_PATH \`
   
    `--secret=${SECRET_PATH}`
   

8. このリンクにアクセスして、コンソールで新しく作成された Cloud Build トリガーを確認します。
9. 次のステップで GitHub が使用するエンドポイント URL の変数を定義します。

WEBHOOK_URL="https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY_VALUE}&secret=${SECRET_VALUE}"

GitHub Webhook を構成する

1. GitHub で Webhook を構成する

$BASE_DIR/scripts/git/gh.sh create_webhook ${APP_NAME} $WEBHOOK_URL

2. アプリケーション リポジトリに移動し、新しく構成された Webhook を確認します。

REPO_URL=${GIT_BASE_URL}/${APP_NAME}/settings/hooks

echo $REPO_URL

新しいアプリケーションの作成に必要なすべての手順を手動で実行したので、次はスクリプトで自動化します。

6. オンボーディングのすべての手順を自動化する

実際には、新しいアプリケーションごとに上記の手順を実行することは現実的ではありません。代わりに、ロジックをスクリプトに組み込んで、簡単に実行できるようにする必要があります。上記の手順は、使用可能なスクリプトにすでに含まれています。

このステップでは、提供されたスクリプトを使用して新しいアプリケーションを作成します。

新しいアプリケーションを作成する

1. 正しいディレクトリにいることを確認する

cd $BASE_DIR

2. 新しいアプリケーションを作成する

export APP_NAME=demo-app

./app.sh create ${APP_NAME}

すべてのステップが自動的に実行されます。

GitHub リポジトリを確認する

この時点で、GitHub で新しいリポジトリを確認できるようになります。

1. 次のコマンドを実行して、GitHub リポジトリの URL を取得します。

echo ${GIT_BASE_URL}/demo-app

2. ウェブブラウザで URL を開いて、新しいアプリケーションを確認します。
3. テンプレート変数がインスタンス値に置き換えられた例については、下記の URL をご覧ください。

echo ${GIT_BASE_URL}/demo-app/blob/main/k8s/prod/deployment.yaml#L24

4. 以下の URL で構成された Webhook を確認します。

echo ${GIT_BASE_URL}/demo-app/settings/hooks

CloudBuild トリガーを確認する

トリガーはスクリプトによって自動的に設定されました

1. このリンクにアクセスして、コンソールで Cloud Build トリガーを確認します。
2. このページでビルド履歴を確認する