4.8. Pipelines as Code の使用

重要

Pipelines as Code は、テクノロジープレビュー機能としてのみご利用いただけます。テクノロジープレビュー機能は、Red Hat の実稼働環境におけるサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。

Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲を参照してください。

Pipelines as Code を使用すると、クラスター管理者と必要な権限を持つユーザーは、パイプラインテンプレートをソースコード Git リポジトリーの一部として定義できます。設定された Git リポジトリーのソースコードプッシュまたはプルリクエストによってトリガーされると、この機能はパイプラインを実行し、ステータスを報告します。

4.8.1. 主な特長

Pipelines as Code は、次の機能をサポートしています。

プルリクエストのステータスおよび Git リポジトリーをホストするプラットフォームの制御。
GitHub は API を確認し、パイプライン実行のステータスを設定します (再チェックを含む)。
GitHub のプルリクエストとコミットイベント。
/retest などのコメントでリクエストアクションをプルします。
Git イベントのフィルターリング、およびイベントごとの個別のパイプライン。
ローカルタスク、Tekton Hub、およびリモート URL を含むパイプラインの自動タスク解決。
GitHub blob およびオブジェクト API を使用した設定の取得。
GitHub 組織を介して、または Prow スタイルの OWNER ファイルを使用したアクセス制御リスト (ACL)。
ブートストラップおよび Pipelines as Code のリポジトリーを管理するための tkn-pac CLI プラグイン。
GitHub App、GitHub Webhook、Bitbucket Server、および Bitbucket Cloud のサポート。

4.8.2. OpenShift Container Platform への Pipelines as Code のインストール

Pipelines as Code は、Red Hat OpenShift Pipelines Operator のインストール時にデフォルトでインストールされます。Pipelines 1.7 以降のバージョンを使用している場合は、Pipelines as Code を手動でインストールする手順を省略します。

ただし、Red Hat OpenShift Pipelines Operator による Pipelines as Code のデフォルトのインストールを無効にする必要がある場合には、TektonConfig カスタムリソースの enablePipelinesAsCode フィールドの値を false に設定します。

...
spec:
    addon:
      enablePipelinesAsCode: false
...

Operator を使用して Pipelines as Code をインストールするには、enablePipelinesAsCode フィールドの値を true に設定します。

手順

Red Hat OpenShift Pipelines Operator を使用したデフォルトのインストールではなく、OpenShift Container Platform クラスターに Pipelines as Code を 手動で インストールするには、以下のコマンドを実行します。
```
$ VERSION=0.5.4
$ oc apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/release-$VERSION/release-$VERSION.yaml
```
注記
最新の安定版については、リリースページを参照してください。さらに、Red Hat OpenShift Pipelines のリリースノートを確認し、Pipelines as Code のバージョンが Red Hat OpenShift Pipelines のバージョンと互換性を持つようにします。
このコマンドは、Pipelines as Code を pipelines-as-code namespace にインストールし、ユーザーロールと Pipelines as Code イベントリスナーのルート URL を作成します。
クラスターで作成された Pipelines as Code コントローラーのルート URL を書き留めます。
```
$ echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}')
```
この URL は、後でサービスプロバイダーをホストする Git リポジトリーを設定する際に必要になります。
(オプション) 管理者以外のユーザーが各 namespace にリポジトリーのカスタムリソース定義 (CRD) を作成するのを許可するには、namespace に openshift-pipeline-as-code-clusterrole という名前の RoleBinding オブジェクトを作成します。たとえば、ユーザーが user-ci namespace にリポジトリー CRD を作成するのを許可するには、以下のコマンドを実行します。
```
$ oc adm policy add-role-to-user openshift-pipeline-as-code-clusterrole user -n user-ci
```
あるいは、oc apply -f <RoleBinding.yaml> コマンドを使用して、以下の YAML ファイルを適用します。
```
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: openshift-pipeline-as-code-clusterrole
  namespace: user-ci
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: openshift-pipeline-as-code-clusterrole
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: user
```

4.8.3. Pipelines as Code CLI のインストール

クラスター管理者は、ローカルマシンで、またはテスト用のコンテナーとして tkn-pac CLI ツールを使用できます。tkn-pac CLI ツールは、Red Hat OpenShift Pipelines の tkn CLI をインストールする際に自動的にインストールされます。

サポートされるプラットフォームに tkn-pac tkn-pac バージョン 0.23.1 バイナリーをインストールすることもできます。

Linux (x86_64, amd64)
Linux on IBM Z and LinuxONE (s390x)
Linux on IBM Power Systems (ppc64le)
Mac
Windows
注記
バイナリーは tkn バージョン 0.23.1 と互換性があります。

4.8.4. サービスプロバイダーをホストする Git リポジトリーの Pipelines as Code の設定

Pipelines as Code をインストールした後に、クラスター管理者はサービスプロバイダーをホストする Git リポジトリーを設定できます。現在、以下のサービスがサポートされています。

Github アプリケーション
GitHub Webhook
Bitbucket Server
Bitbucket Cloud

注記

GitHub アプリケーションが、Pipelines as Code を使用するために推奨されるサービスです。

4.8.4.1. GitHub アプリケーションの Pipelines as Code の設定

GitHub アプリケーションは Red Hat OpenShift Pipeline とのインテグレーションポイントとして機能し、Git ベースのワークフローのメリットを OpenShift Pipelines にもたらします。クラスター管理者は、すべてのクラスターユーザーに単一の GitHub アプリケーションを設定できます。GitHub アプリケーションが Pipelines as Code と連携するには、GitHub アプリケーションの Webhook が GitHub イベントをリッスンする Pipelines as Code イベントリスナールート (または受信エンドポイント) をポイントするようにします。

4.8.4.1.1. GitHub アプリケーションの設定

クラスター管理者は、以下のコマンドを実行して GitHub アプリケーションを作成できます。

$ tkn pac bootstrap github-app

tkn pac CLI プラグインがインストールされていない場合は、GitHub アプリケーションを手動で作成できます。

手順

Pipelines as Code 用に GitHub アプリケーションを手動で作成および設定するには、以下の手順を実行します。

GitHub アカウントにサインインします。
Settings -→ Developer settings -→ GitHub Apps の順に移動し、New GitHub App をクリックします。
GitHub App フォームに以下の情報を入力します。
- GitHub Application Name: OpenShift Pipelines
- Homepage URL: OpenShift Console の URL
- Webhook URL: Pipelines as Code ルートまたは受信 URLこの情報は、コマンド echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}') を実行して取得することができます。
  注記
  Red Hat OpenShift Pipelines Operator を使用してデフォルトでインストールされる Pipelines as Code の場合、pipelines-as-code の代わりに openshift-pipelines namespace を使用します。
- Webhook secret: 任意のシークレット。コマンド openssl rand -hex 20 を実行してシークレットを生成することができます。
以下の リポジトリーのパーミッション を選択します。
- チェック: 読み取り/書き込み
- コンテンツ: 読み取り/書き込み
- 問題: 読み取り/書き込み
- メタデータ: 読み取り専用
- プルリクエスト: 読み取り/書き込み
以下の 組織のパーミッション を選択します。
- メンバー: 読み取り専用
- プラン: 読み取り専用
以下の ユーザーパーミッション を選択します。
- コミットコメント
- 問題のコメント
- プルリクエスト
- プルリクエストのレビュー
- プルリクエストのレビューコメント
- プッシュ
Create GitHub App をクリックします。
新たに作成された GitHub App の Details ページで、上部に表示される App ID を書き留めます。
Private keys セクションで、Generate Private key をクリックして GitHub アプリケーションの秘密鍵を自動的に生成およびダウンロードします。今後の参照や使用のために秘密鍵を安全に保管します。

4.8.4.1.2. GitHub アプリケーションにアクセスするための Pipelines as Code の設定

新たに作成された GitHub アプリケーションにアクセスするために Pipelines as Code を設定するには、以下のコマンドを実行します。

$ oc -n <pipelines-as-code> create secret generic pipelines-as-code-secret \ 1
        --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ 2
        --from-literal github-application-id="<APP_ID>" \ 3
        --from-literal webhook.secret="<WEBHOOK_SECRET>" 4

1: Red Hat OpenShift Pipelines Operator を使用してデフォルトでインストールされる Pipelines as Code の場合、pipelines-as-code の代わりに openshift-pipelines namespace を使用します。
2: GitHub アプリケーションの設定時にダウンロードした秘密鍵へのパス。
3: GitHub アプリケーションの App ID。
4: GitHub アプリケーションの作成時に提供された Webhook シークレット。

注記

GitHub Enterprise から設定されたヘッダーを検出し、それを GitHub Enterprise API 承認 URL に使用することで、Pipelines as Code は自動的に GitHub Enterprise と連携します。

4.8.5. Pipelines as Code のコマンドリファレンス

tkn-pac CLI ツールは、以下の機能を提供します。

ブートストラップ Pipelines as Code のインストールおよび設定。
新規 Pipelines as Code リポジトリーの作成。
すべての Pipeline as Code リポジトリーを一覧表示。
Pipeline as Code リポジトリーおよび関連付けられた実行の記述。
使用を開始するための単純なパイプライン実行の生成。
Pipelines as Code によって実行されたかのようにパイプラインの実行を解決。

ヒント

アプリケーションのソースコードが含まれる Git リポジトリーに変更を加える必要がないように、テストおよび実験用に機能に対応するコマンドを使用することができます。

4.8.5.1. 基本的な構文

$ tkn pac [command or options] [arguments]

4.8.5.2. グローバルオプション

$ tkn pac --help

4.8.5.3. ユーティリティーコマンド

4.8.5.3.1. bootstrap

表4.7 ブートストラップ Pipelines as Code のインストールおよび設定
コマンド	説明
`tkn pac bootstrap`	GitHub および GitHub Enterprise などのサービスプロバイダーをホストする Git リポジトリーの Pipelines as Code をインストールおよび設定します。
`tkn pac bootstrap --nightly`	Pipelines as Code のナイトリービルドをインストールします。
`tkn pac bootstrap --route-url <public_url_to_ingress_spec>`	OpenShift ルートの URL をオーバーライドします。デフォルトでは、`tkn pac bootstrap` は OpenShift ルートを検出します。これは、Pipelines as Code コントローラーサービスに自動的に関連付けられます。 OpenShift Container Platform クラスターがない場合、受信エンドポイントをポイントするパブリック URL の入力を要求します。
`tkn pac bootstrap github-app`	`pipelines-as-code` namespace に GitHub アプリケーションとシークレットを作成します。

4.8.5.3.2. repository

表4.8 Pipelines as Code リポジトリーの管理
コマンド	説明
`tkn pac repo create`	パイプライン実行テンプレートに基づいて、新規 Pipelines as Code リポジトリーおよび namespace を作成します。
`tkn pac repo list`	すべての v リポジトリーとして一覧表示し、関連する実行の最後のステータスを表示します。
`tkn pac repo describe`	Pipelines as Code リポジトリーおよび関連する実行を記述します。

4.8.5.3.3. generate

表4.9 Pipelines as Code を使用したパイプライン実行の生成
コマンド	説明
`tkn pac generate`	単純なパイプライン実行を生成します。ソースコードが含まれるディレクトリーから実行すると、現在の Git 情報を自動的に検出します。さらに、基本的な言語検出機能を使用して、言語に応じてさらにタスクを追加します。たとえば、リポジトリーのルートで `setup.py` ファイルを検出すると、pylint タスクが自動的に生成されたパイプライン実行に追加されます。

4.8.5.3.4. resolve

表4.10 Pipelines as Code を使用したパイプライン実行の解決および実行
コマンド	説明
`tkn pac resolve`	サービスで Pipelines as Code により所有されているかのようにパイプライン実行を実行します。
`tkn pac resolve -f .tekton/pull-request.yaml \| oc apply -f -`	`.tekton/pull-request.yaml` のテンプレートを使用するライブのパイプライン実行のステータスを表示します。ローカルマシンで実行中の Kubernetes インストールと組み合わせて、新しいコミットを生成せずにパイプライン実行を確認できます。ソースコードリポジトリーからコマンドを実行すると、現在の Git 情報を検出し、現在のリビジョンやブランチなどのパラメーターを自動的に解決しようとします。
`tkn pac resolve -f .tekton/pr.yaml -p revision=main -p repo_name=<repository_name>`	Git リポジトリーからのデフォルトのパラメーター値をオーバーライドして、パイプライン実行を実行します。 `-f` オプションはディレクトリーパスを受け入れ、そのディレクトリー内のすべての `.yaml` または `.yml` ファイルに `tkn pac resolve` コマンドを適用することもできます。1 つのコマンドで `-f` フラグを複数回使用することもできます。 `-p` オプションを使用してパラメーター値を指定することで、Git リポジトリーから収集したデフォルト情報をオーバーライドできます。たとえば、Git ブランチをリビジョンおよび異なるリポジトリー名として使用できます。

4.8.6. Pipelines as Code 設定のカスタマイズ

クラスター管理者は pipelines-as-code namespace の pipelines-as-code 設定マップを使用して以下のパラメーターを設定し、Pipelines as Code をカスタマイズすることができます。

表4.11 Pipelines as Code 設定のカスタマイズ
パラメーター	説明	デフォルト
`application-name`	アプリケーションの名前。たとえば、GitHub Checks ラベルに表示される名前です。	`"Pipelines as Code CI"`
`max-keep-days`	実行されたパイプライン実行が `pipelines-as-code namespace` に保持される日数。この configmap の設定は、ユーザーのパイプライン実行のクリーンアップには影響しません。これは、ユーザーの GitHub リポジトリーのパイプライン実行定義のアノテーションによって制御されます。
`secret-auto-create`	GitHub アプリケーションで生成されたトークンを使用してシークレットを自動的に作成するかどうかを示します。このシークレットは、プライベートリポジトリーで使用できます。	`enabled`
`remote-tasks`	有効にすると、パイプライン実行アノテーションからのリモートタスクを許可します。	`enabled`
`hub-url`	Tekton Hub API のベース URL。	`https://hub.tekton.dev/`