copied!

PipeCDのインストールとカスタマイズ

Sreake事業部

2024.1.9

copied!

はじめに

はじめまして。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.yaml

values.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: false

secrets.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ではそれぞれのストレージをクラウド上で管理することができます。

Install Control Plane

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.com

secret:
    create: true
    name: ""
    mountPath: /etc/piped-secret
    data:
        piped-key: ***********************************
        ssh-key: |
          -----BEGIN OPENSSH PRIVATE KEY-----
					***********************************
					***********************************
					***********************************
					***********************************
					***********************************
          -----END OPENSSH PRIVATE KEY-----
    kubeConfigs: []
args:
    insecure: true

pipedのインストールが完了し、アクセス可能になるとステータスが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-user

Github 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 as ORG/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が分離していることのメリットが最大限効果を発揮する場面での検証が不十分といえます。今後の課題として、この機能に焦点を当てた検証を行っていく予定です。

スリーシェイク、「AWS アドバンストティアサービスパートナー」に昇格

PipeCDの概要