はじめに
はじめまして。Sreake事業部インターン生の荒木です。2023年10月から長期インターン生としてKubernetes関連技術の習得とSRE技術の調査・検証を行っています。
前回の記事では、KubernetesクラスタのCDツールであるPipeCDの概要と特徴についてまとめましたが、具体的なインストール方法やカスタマイズについては触れていませんでした。そこで、本記事ではこの不足を補完し、PipeCDの具体的な導入手順やカスタマイズ方法に焦点を当てています。
クイックスタートインストール
PipeCDのコマンドラインツールであるpipectlを用いることで、クイックスタート用の構成でPipeCDとPipedをインストールすることができます。クイックスタート用のパラメータでHelmChartを使用しているに過ぎないので同一の環境は容易に再現することができます。なお、このpipectlはwindows非対応です。
# pipectlのインストール
# OS="darwin" or "linux"
$ export OS=linux
$ curl -Lo ./pipectl https://github.com/pipe-cd/pipecd/releases/download/v0.45.3/pipectl_v0.45.3_${OS}_amd64
$ chmod +x ./pipectl
$ sudo mv ./pipectl /usr/local/bin/pipectlクイックスタートインストールは以下のコマンドを実行した後、CLIに従ってパラメータを入力することで実施できます。
$ pipectl quickstart --version v0.45.2
⚠️ gitのリポジトリを登録する際、クイックスタートの設定では監視対象のブランチがbranch: masterと設定されていました。デフォルトブランチがmainで設定された昨今のリポジトリを登録すると、Pipedの起動が上手くいきません。そのためkubectl patch等による手動変更が必要です。
以降の手順については次の項の[3. PipeCDのフロントサーバーにログイン] から共通です。
HelmChartによるインストール
HelmChartを用いてPipecd Control PlaneとPipedをデプロイし、GKE Ingressを使用してServerを外部公開する構成を示します。それにあたり、
name:pipecd,domain:yourdomain.example.comで設定したmanaged certificateの作成- GCP上であらかじめ予約してあるIPアドレス名：
pipecd-allocated-ipの使用
をインストールの過程で行っています。
WebUIのサーバーを公開する際に利用するグローバルIPアドレスの予約は以下のコードで行いました。
resource "google_compute_global_address" "pipecd_ip" {
name = "pipecd-allocated-ip"
address_type = "EXTERNAL"
}その後、保有しているドメインのAレコードを更新し予約したIPアドレスを名前解決可能に設定しておく必要があります。
Google マネージド SSL 証明書の使用 | Google Kubernetes Engine（GKE） | Google Cloud
手順フロー
- PipeCD Control Planeのインストール
- Ownerページでプロジェクトを作成
- PipeCDのフロントサーバーにログイン
- Piped登録用ID, PWを発行
- Pipedのインストール
- フロントサーバーからアプリケーションを登録
1. PipeCD Control Planeのインストール
以降、Helm Chartによるインストールの手順を示していますが、secrets.yamlには非常にセンシティブなクレデンシャル情報が含まれています。
当該開発環境では、この secrets.yaml を Helm Secret プラグインを使用して暗号化しており、実際に実行したコマンドとは異なる例示を行っています。また、yamlファイル内に直接シークレットを記述していますので、-set-fileオプションを用いて、ファイルを参照する形で値を注入することが推奨されます。注意ください。
$ helm upgrade --install pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version v0.45.3 -n pipecd --create-namespace \
--values values.yaml --values secrets.yamlvalues.yaml
quickstart:
enabled: true
service:
port: 443
internalPort: 80
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: "gce"
kubernetes.io/ingress.global-static-ip-name: pipecd-allocated-ip
networking.gke.io/managed-certificates: pipecd
managedCertificate:
enabled: true
domains: [yourdomain.example.com]
server:
args:
secureCookie: falsesecrets.yaml
config:
data: |
apiVersion: pipecd.dev/v1beta1
kind: ControlPlane
spec:
datastore:
type: MYSQL
config:
url: root:<データベースのパスワード>@tcp(pipecd-mysql:3306)
database: pipecd-database
filestore:
type: MINIO
config:
endpoint: http://pipecd-minio:9000
bucket: sample-bucket
accessKeyFile: /etc/pipecd-secret/minio-access-key
secretKeyFile: /etc/pipecd-secret/minio-secret-key
autoCreateBucket: true
mysql:
database: pipecd-database
rootPassword: <データベースのパスワード>
secret:
encryptionKey:
data: <encryptionKey>
minioAccessKey:
data: <minioのアクセスキー>
minioSecretKey:
data: <minioのシークレットキー>当該構成ではdatastore:MYSQL, FileStore:Minioとして設定しており、ArgoCDと同様にストレージを同一クラスタ内に保持している形になります。しかし、PipeCDではそれぞれのストレージをクラウド上で管理することができます。
quickstart.enabled=trueの設定がある場合、mysqlとminioのpodがデプロイされるChartの設計のため、クラウドストレージを用いるときはquickstart.enabled=falseとしてください。
なお、yourdomain.example.comでのhttpsでの公開が完了するまで30分以上必要です。
httpsでの公開が確立したらserver.args.secureCookie:trueへの変更が推奨されます。
なお、公式リファレンスに記述されていたapi.args.secureCookieはHelmChartのテンプレートを確認しましたが存在しませんでした。
2. Ownerページでプロジェクトを作成
Ownerページはデフォルトの設定であれば
kubectl port-forward service/pipecd-ops 9082 -n pipecd
でポートフォワードすることによりアクセスできます。
このページでプロジェクト新規作成や確認を行うことができます。
Add Project にてプロジェクトを登録すると以下の通りです。
3. PipeCDのフロントサーバーにログイン
Ingressを用いず、Serverを公開しない構成の際は同様にポートフォワードして
kubectl port-forward svc/pipecd 8080 -n {NAMESPACE}
としてアクセスできます。
4. Pipedの登録ID, PWを発行
Settings > (Piped) + ADDでpipedを登録できます。
この時点ではpipedをインストールしていないので、ステータスはofflineです。
5. Pipedのインストール
Pipecdのインストールと同様にHelmChartを使用します。その際、
- 先ほど発行した
Piped Id,Piped Key - gitのリポジトリのURL
- プライベートリポジトリならばssh-key
等のパラメータをChartに渡す必要があります。
$ helm upgrade --install piped oci://ghcr.io/pipe-cd/chart/pipecd --version v0.45.3 -n [namespace] --create-namespace \
--values values.yaml --values secrets.yamlこれはGitlabのプライベートリポジトリを登録する際の例です。
config:
data: |
apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
projectID: sample-proj
pipedID: 045e02a5-5f16-480f-b87a-417935241510
pipedKeyFile: /etc/piped-secret/piped-key
# Write in a format like "host:443" because the communication is done via gRPC.
apiAddress: pipecd:443
repositories:
- repoId: sample-repo
remote: git@gitlab.com:****/*******/*********/*******.git
branch: main
syncInterval: 1m
git:
sshKeyFile: /etc/piped-secret/ssh-key
host: gitlab.comsecret:
create: true
name: ""
mountPath: /etc/piped-secret
data:
piped-key: ***********************************
ssh-key: |
-----BEGIN OPENSSH PRIVATE KEY-----
***********************************
***********************************
***********************************
***********************************
***********************************
-----END OPENSSH PRIVATE KEY-----
kubeConfigs: []
args:
insecure: truepipedのインストールが完了し、アクセス可能になるとステータスがonlineになります。
6. フロントサーバーからアプリケーションを登録
- 設定したリポジトリの中にあるアプリのみ登録可能
- リポジトリ内の
app.pipecd.yamlによって認識される app.pipecd.yamlの数=アプリの数
正常にアプリケーションが登録されるとその後デプロイが行われます。
各種カスタマイズと機能
デプロイの設定
PipeCDには2種類のデプロイパターンが存在します。
- Quick Sync
Git コミットで指定された状態にアプリケーションを同期。pipelineフィールドが設定されていなければこれが実行される。 - Pipeline Sync
app.pipecd.yamlのpipelineフィールドにユーザーが記述して設定した同期。
以下はカナリアアップデートでのデプロイ設定の例です。
$ tree app
app
├── app.pipecd.yaml
├── deployment.yaml
└── service.yaml
0 directories, 3 files
apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
name: canary
labels:
env: example
team: product
planner:
alwaysUsePipeline: true
pipeline:
stages:
# Deploy the workloads of CANARY variant. In this case, the number of
# workload replicas of CANARY variant is 10% of the replicas number of PRIMARY variant.
- name: K8S_CANARY_ROLLOUT
with:
replicas: 10%
- name: WAIT_APPROVAL
with:
timeout: 6h
# Update the workload of PRIMARY variant to the new version.
- name: K8S_PRIMARY_ROLLOUT
# Destroy all workloads of CANARY variant.
- name: K8S_CANARY_CLEAN
description: |
This app demonstrates how to deploy a Kubernetes app by Canary strategy without requering any mesh.\
References: [adding a new app](https://pipecd.dev/docs/user-guide/managing-application/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)
https://github.com/pipe-cd/examples/blob/master/kubernetes/canary/app.pipecd.yaml
サンプルアプリケーションのapp.pipecd.yamlにspec.planner.alwaysUsePipelineフィールドを追加しています。この設定を行わないと、gitの更新を検知した際の同期の過程でPipeline Syncが行われず、Quick Syncとして実行されるので注意が必要です。
pipecdのパイプラインの設定に関して、重要な要素が2つあります。
variants: primary, baseline, canary
- パイプラインの過程において、デプロイ構成それ自体を変数として扱える形にしたもの。
- カナリアアップデートなどを実施する時に一時的なデプロイ構成として扱うことができる。
- パイプライン終了時点で
primaryただ一つが残るように設定する。
stages: K8S_PRIMARY_ROLLOUT, K8S_CANARY_ROLLOUT, K8S_CANARY_CLEAN, K8S_BASELINE_ROLLOUT, K8S_BASELINE_CLEAN, K8S_TRAFFIC_ROUTING, WAIT, WAIT_APPROVAL, ANALYSIS(kubernetesアプリケーションの場合)
- 事前にpipecd側で定義されているアクション
K8S_*_ROLLOUT：特定のvariantsの状態をターゲットのコミットで定義された状態に更新するK8S_*_CLEAN：特定のvariantsの状態を削除するK8S_TRAFFIC_ROUTING：variantsにトラフィックを分配する- name: K8S_TRAFFIC_ROUTING with: canary: 10 # canaryにトラフィックの10%を流入 primary: 90 # primaryにトラフィックの90%を流入WAIT：指定した秒数待機WAIT_APPROVAL：指名したユーザーの許可を受ける必要のあるステージを追加ANALYSIS：variantsを分析することで自動承認を行う。- PrometheusもしくはDatadogを構成する必要がある。
これはアプリケーションを登録した後のUI上のアプリケーションの詳細画面です。右上の[Sync]タブから、手動で同期することができます。
画面右上に表示されている[Sync]ですが、公式リファレンスの記述から確認することができませんでした。しかし、選択時の挙動を確認したところ、このSyncはデフォルトとして設定されているデプロイパターンでの同期が行われているようです。
つまり、上記のサンプルコードの場合はspec.planner.alwaysUsePipelineをTrueに設定していますのでPipeline Syncが実行されました。
手動承認ステージの追加
WAIT_APPROVALを使用することで特定ユーザーの許可を要するステージが作成できます。
アップデート/ロールバックの選択を容易に行うことができます。
Slack通知
pipedのインストール時にSlackAppの構成を記述することで、WAIT_APPROVALステージが発生した時にSlackで通知を送ることができます。
#(中略)
notifications:
receivers:
slack:
hookURL: *********
# The path to the oautoken file
oauthTokenFile: /etc/piped-secret/slack-oauth-token
channelID: *********
# The accounts to which slack api referes. This field supports both @username and username writing styles.
mentionedAccounts: @username#(中略)
secret:
mountPath: /etc/piped-secret
data:
#(中略)
slack-oauth-token: |
********************その際app.pipecd.yamlのnotificationフィールドを使用します。
#(中略)
notification:
mentions:
- event: DEPLOYMENT_WAIT_APPROVAL
slack:
- slack-userGithub OAth Appsを用いたSSO設定
１．Github上でOAth Appsを作成
Githubの[Settings] / [Developer Settings] からOAth Appsを作成します。この際、Authorization callback URLをPipeCDのServerを公開しているhttps://yourdomain.example.com/auth/callbackで登録します。
作成完了後、Generate a new client secret からClient secretsを作成します。これはClient IDと共に次のステップで利用することになります。
２．PipeCD Control PlaneのHelmChartに各種設定を追加
前述した、Control Planeのインストール時に使用したsecrets.yamlに以下のように追加しました。
config:
data: |
apiVersion: pipecd.dev/v1beta1
kind: ControlPlane
spec:
stateKey: pipecd-state-key
address: https://yourdomain.example.com
sharedSSOConfigs:
- name: sample-github-sso
provider: GITHUB
github:
clientId: <Client ID>
clientSecret: <Client secrets>
# (中略)３．プロジェクトの作成
kubectl port-forward service/pipecd-ops 9082 -n pipecd
再び、Ownerページにアクセスして、SSOを有効にしたプロジェクトを作成します。
この時、Shared SSOのフォームに先ほど設定した、SSOの設定名(上記の例ならsample-github-sso)を記入します。
４．ロールの設定
PipeCDに一度Adminユーザーでログインして、User Groupの設定を施す必要があります。
Settings > (Progect) >(User Group) + ADDにおいて、該当するgithubアカウントとチームの権限を設定します。
例えば、Githubのアカウントが、
| Organization | Sample-Org |
|---|---|
| Team | Sample-Team-A |
上記の所属関係にあり、同じチームでPipeCDにサインインできるようにするためには、Team/Group: Sample-Org/sample-team-aとして設定します。
In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named
ORG/ABC-TEAM, the PipeCD user group would be set asORG/abc-team. (It’s follow the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME}) https://pipecd.dev/docs-v0.45.x/user-guide/managing-controlplane/auth/#configuring-the-pipecds-user-groups
設定したいチーム名は全てlowercaseにする必要があります。
以上で再度、PipeCDにログインする際、Sample-Org/Sample-Team-A に所属する者であればだれでも、LOGIN WITH GITHUB からログインすることができるようになります。
おわりに
本記事では、PipeCDのインストール手順について解説しました。
私の検証用環境としてはTerraformのHelm ProviderとMakefileでPipeCDのインストールを可能な限り自動化したため比較的スムーズに検証することができました。
ただし、今回の検証ではPipeCDの売りであるマルチクラウド構成に関する機能を詳細に検証することはできませんでした。そのため、Controle PlaneとAgentが分離していることのメリットが最大限効果を発揮する場面での検証が不十分といえます。今後の課題として、この機能に焦点を当てた検証を行っていく予定です。