CircleCI の設定を絵に書いて頭の中を整理

circleci

2021-12-14 更新 =======

  • Resource Class
    • Pricing のページの情報が正しいと確認がとれました。Free プランでも、例えば Docker Executor の Medium+, Large が利用できるようになっているとのことです
  • Docker Layer Caching (DLC)
    • Free プランでも DLC が利用できるようになったと確認が取れました
    • なので、このブログの絵の DLC は黄色の箱から白の箱に更新しました
    • 英語版のドキュメントで該当部分の文言を削除しました（日本語版はしばらくお待ちください）
  • この記事に書かれている情報は 2021-12-14 時点でのものになります！

更新内容ここまで =====

どーも。こんにちは。こんばんは。しーばです。

この記事は Calendar for CircleCI Advent Calendar 2021 | Advent Calendar 2021 - Qiita の10日目の記事ですー。間に合ってないけど、まだ日が昇ってないからセーフってことで、よろしくお願いします！

9日目は、ふなっきーの 2021年のChangelogから振り返るCircleCI - その3(最終回) - Qiita でした。僕が入社してからの2ヶ月間でも色々リリースされてどんどん良くなっていってて面白いなぁっていうのと、新しい機能がリリースされて便利になるとそれが直接開発者のみなさんの役に立つのってとても嬉しいなぁっていうのと、僕もはやく役に立てるようにがんばるぞーっていうのと。そんな気持ちです。

CircleCI 勉強中

さて、そんなこんなでまだ CircleCI 自体を勉強中なんですけど、今日は、公式ドキュメントを読んで頭の整理をしてみたので、それを紹介します。僕は、ドキュメントを読むのが結構苦手で、すぐ頭の中が散らかってしまうので、絵を描いて自分に分かるようにしたりします。これが誰かの役に立つと嬉しい。

全体像

まずは全体像から。こんなイメージ。

https://cdn-ak.f.st-hatena.com/images/fotolife/b/bufferings/20211211/20211211011025_original.png

  • ひとつのプロジェクトに対して複数の Workflow が定義できて
  • それぞれの Workflow の中では複数の Job が依存関係をもって実行される
  • 各 Job には Steps があって
  • Executor 上で実行される

最初にドキュメントを読んだときにはいまいちピンときてなかった「Pipeline」。しばらくして分かってきたのが

  • Pipeline は config.yml のことだと思って良さそう

ということ。ここまでは特に問題ないかなぁ

config.yml

さて、そんな Pipeline を定義する config.yml 。

公式ドキュメントのこのページ CircleCI を設定する - CircleCI を「ふむふむ」とか「なるほど？」とか言いつつ読んでいって「わかったぞー！」ってなるんだけど、2,3日後には「あれ？ここには environment が定義できるんだったっけ？どうだっけ？」みたいにすぐに記憶喪失になってしまう。

ということで、全体の関係性をふんいきで描いてみました。これで、忘れても大丈夫だー。

注意点

  • クラウド版とオンプレ版があるけどクラウド版についてだけ描いてます
  • 対象バージョンは2.1。Deprecated なのはスルーしてます
  • それぞれの要素の関係を中心に整理したので、全部の項目を書いてるわけじゃないです
  • たくさんの部分を項目の正式名称じゃなくて、自分の頭の中で理解した名前で書いてます
  • 会社としての正式なものではなくて、僕個人の理解です

全体像2

それぞれの説明は後でするとして、全体の画像を載せておきます。フォーマットは特に考えずに書いてるので、ふんいきで感じてもらえると嬉しいです。

https://cdn-ak.f.st-hatena.com/images/fotolife/b/bufferings/20211214/20211214181644_original.png

うえからざっくり説明していきます

Pipeline

f:id:bufferings:20211211015113p:plain:w400

Workflow

f:id:bufferings:20211214173345p:plain

  • Workflow Scheduler
    • これが Pipeline Scheduler に置き換わっていくみたい
    • Pipeline 単位で起動されることになるので、その場合は When/Unless と Pipeline Parameter を使って制御することになる
  • Workflow Job
    • これは僕が頭の中で区別するためにつけた名前
    • Workflow には複数の Workflow Job がひもづく
    • Workflow Job は、Job への参照か、または Approval Job
      • Workflow の部分に直接 Job の Steps を書くことはない
    • Branch/Tag フィルターが指定できる
    • Pre Steps/Post Steps が定義できるので、Job の内容に手を入れずに前後に処理を入れることができる
    • Steps はここで描くと収まりきらないので、別途描いた。文字の色を青色にしておいた

Job

f:id:bufferings:20211214173440p:plain

  • Enable IP Ranges
    • Job で使用する IP アドレスを特定のレンジに限定する機能 ( IP アドレスの範囲 - CircleCI )
    • Free プランでは使えない機能は黄色い箱にしておいた
  • Job には Parameter と Environment (環境変数) が設定できる
  • Executor は Job のところに直接書くこともできるし、別途 Executor として定義したものを参照することもできる
    • 個人的には、参照の方が読みやすそうだなって思う
  • Job のメインは Steps

Executor

Executor は、ここまでとはちょっと違う書き方をしてる

f:id:bufferings:20211214173515p:plain

  • Executor には環境変数を定義することができる
  • 大きくわけて二種類ある：CircleCI Executor と Runner Executor
    • CircleCI Executor は、CircleCI が用意してる Executor
    • Runner Executor は自分で用意して CircleCI から利用する Executor
  • CircleCI Executor には Resource Class が指定できる
    • Free Plan では制限があるみたいなので黄色の箱にしておいた
  • CircleCI Executor には、Docker、macOS、Machine があって、Machine の中に Windows と Ubuntu がある
  • Machine Executor には DLC が指定できる

ちょっと話が変わるけど

Free プラン

について、僕がイマイチよく分かってない部分が2つあるから、中の人に聞いてみようと思う（確認とれたら更新しておきます）

2021-12-14 追記

確認がとれたので更新しました！

追記ここまで

弊社 CI ツールの料金プラン - CircleCI (アクセス日 2021-12-11)

Resource Class

f:id:bufferings:20211211022329p:plain:w400

Resource Class のところに○がついてるってことは、Free プランでも Large までは選べるってことなのかな？Medium までしか使えないと思ってたから気になる。

2021-12-14 追記

Pricing のページの情報が正しいと確認がとれました。Free プランでも、例えば Docker Executor の Medium+, Large が利用できるようになっているとのことです

追記ここまで

Docker Layer Cache

f:id:bufferings:20211211022649p:plain:w400

DLC にも○がついてる。CircleCI を設定する - CircleCI には

お使いのアカウントでこの有料の機能を有効化するには、サポート チケットをオープンしてください。 CircleCI 営業担当者から連絡を差し上げます。

ってあるから、有料なのかなと思ってるんだけど、どうなんだろう？

2021-12-14 追記

  • Free プランでも DLC が利用できるようになったと確認が取れました
  • なので、このブログの絵の DLC は黄色の箱から白の箱に更新しました
  • 英語版のドキュメントで該当部分の文言を削除しました（日本語版はしばらくお待ちください）

追記ここまで

ということで、話を戻そう

Steps

f:id:bufferings:20211214173632p:plain

  • Steps には複数の Step を定義できる
  • Run Step と Predefined Step が基本かな。When と Command 参照は 2.1 からなので後発
  • Run Step
    • 環境変数を定義できる
    • ここにも When があるけど、他の部分の When と違って、ここでは on_success on_fail always のどれかを指定する
    • ちなみに他の部分の When は ロジックステートメント を指定する
    • 実行するコマンドを1つ指定する（複数行可能）
  • Predefined Step
    • CircleCI から提供されている Step
  • When/Unless Step
    • 条件を満たすときだけ実行される
    • この Step の中には Steps を持つので、複数の Step を実行することができる
  • Ref<Command> Step
    • Command の参照

Command

f:id:bufferings:20211214181826p:plain:w400

ひとかたまりの Steps に名前をつけて Command として定義することで、Step の中で再利用することができる

Orbs

この図の中の、Executor、Job、Command が再利用可能なので、それらをひとかたまりにして Orb として登録することができる。

そうすると、Ref<Executor>、Ref<Job>、Ref<Command> と書いている部分で参照することができる。

おわりー

頭の中が整理できた！これで、Environment ってどこで指定できたっけ？ってときもこの絵を見たら分かるし、細かい設定を見たいときはこの絵を見たあとに、公式ドキュメントを見たら頭の中が迷子にならなさそう！よかった！

アドベントカレンダー11日目は。。。

あー！すでにあがってたｗ。ようへいさんのお話です。面白そうー！起きたら読むー！

inokara.hateblo.jp