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

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

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

オンボーディングで最も一般的なニーズの一つは、テンプレートの変数を、アプリケーションで使用される実際のインスタンスに置き換えることです。たとえば、アプリケーション名を指定します。次のコマンドは、環境変数に格納された値を使用して、すべての .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

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

シークレットは、呼び出し元を認証し、特定の Cloud Build ターゲット ジョブに対する権限があることを確認するために使用されます。独自のパイプラインにのみアクセスできる 2 つの異なるリポジトリを GitHub にできます。API_KEY は、GitHub で使用できる API（この場合は Cloud Build API が呼び出されます）を制限しますが、シークレットは、クライアントが Cloud Build API のどの Job を実行できるかを制限します。

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 プロセスを実行する構成です。

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

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 スクリプトで、プロジェクトの Container Registry を定義する変数が設定されています。次のコマンドを使用して値を確認します。

echo $IMAGE_REPO

7. 前に作成した変数を使用して、CloudBuild Webhook トリガーを作成します。アプリケーション リポジトリの場所は、GitHub からのリクエストの本文から pull されます。以下の値は、リクエスト本文内のパスを参照しています。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. このページでビルド履歴を確認する