【2022鐵人賽】再一次認識Build Pipeline的YAML結構

作者:

去年有一篇文章內容提到在YAML中設計多個Agent Job，裡面就提到了Build Pipeline的YAML結構，只不過那篇文章主要是談到如何在Pipeline YAML中加入多個Agent Job，並且設定不同的Job是執行在不同OS的vmImage，這一篇文章就來再次回顧一下YAML的結構，讓我們來認識更多的設定吧！

在Pipeline的YAML結構應該是下面的這個樣子：

  • YAML
    • name
    • resources
    • trigger
    • pool
    • variables
    • stages
      • jobs
        • steps
          • script/bash/pwsh/task …

扣除掉前面幾個只會設定一個的項目，範例結構會像這樣：

  • stages
    • 階段A(stage)
      • jobs
        • 作業1(job)
          • steps
            • 步驟1(task)
            • 步驟2(script)
            • 步驟3(pwsh)
        • 作業2(job)
    • 階段B(stage)
    • 階段C(stage)

在官方的文件頁面上有提到，如果只有單一階段(stage)，可以省略關鍵字stages並且直接使用jobs開始。如果只有單一階段(stage)和單一作業(job)，可以省略stages和jobs關鍵字，直接使用steps開始。

去年的文章內容主要著重在下半段，也就是在stages下面的jobs，這邊我們要來看看stages上面的那幾個，分別是name、resources、trigger、pool與variables。

name

這個是設定Pipeline執行後，在結果清單上所顯示的識別名稱，預設是「$(Date:yyyyMMdd).$(Rev:r)」，也就是西元的年月日與流水編號，下圖分別以紅框netapp_ci_$(Date:yyyyMMdd)$(Rev:.r)與藍框(預設值)顯示差異，從圖中也可以直接知道這個設定是顯示在哪裡：

YAML的name格式顯示

name必須設定在YAML檔案的第一行，它可以使用變數(Variable)的方式取得一些相關的資訊，可以參考官方的文件：預先定義的變數，像是觸發的Branch，或是日期時間的相關變數。

resources

resources底下有幾種類型的資源定義，其中我們後面會經常使用到的部份就是repositories，它是用來定義我們Pipeline中會使用到哪些Git Repository，因為我們後續的Pipeline設計將會把Pipeline的YAML檔和程式存放的Repository分開存放，所以需要在repository裡面設定來源和觸發條件。

resources:
  builds: [ build ]
  containers: [ container ]
  pipelines: [ pipeline ]
  repositories: [ repository ]
  webhooks: [ webhook ]
  packages: [ package ]

trigger

這裡的trigger指的是root層級，也就是YAML檔案存放的repository有異動的時候是否觸發這個YAML Pipeline。

依照我們的設計，在root層級的trigger通常會停用它(設為none)，因為我們會在resources底下的repository那一層再去個別設定trigger，不過設定的格式都是相同的。

trigger底下可以設定幾種不同的條件，像是包含哪些branch、path、tag要觸發，排除哪些branch、path、tag不要觸發，設定方式並不困難，有興趣也可以直接點標題連結看看官方的文件說明。

pool

pool的設定主要是用來設定Pipeline要執行的時候是使用Cloud的Agent跑在哪個OS的vmImage或是使用自架的Agent，對於需要設定使用特定環境的篩選條件demands也是在pool底下。

如果是使用Cloud Agent的話，pool底下使用的關鍵字就是vmImage。反之，使用自架的Agent時，則是設定name，也就是pool的名稱(pool是可以新增多個的)，需要篩選條件的話才會再加上demands關鍵字。

variables

variables是設定Pipeline變數的地方，有另一個跟它很像的名稱叫parameters(參數)，兩者如果搞混的話會有點麻煩，不過parameter在後面進入YAML範本化設計的時候才會經常看到它，到時候會再更清楚的說明和比較兩者的差異。

再往下的stages、jobs、steps這幾項在去年的文章內容已經有介紹過了，不過這些同樣會在後面的文章進入YAML範本化設計的時候頻繁出現，多寫幾次就會很熟了。

以上這些關鍵字已經是針對時常會用到的項目提出來介紹，不然若是直接看官方文件庫的話，我相信100個裡面應該會有101個會覺得看得頭很昏，等到用熟了之後再回頭去看官方的文件就又是另外一個不同的感覺了。

對了，之後文章在學習YAML範本化設計的時候會使用到template這個關鍵字，也就是設計好的YAML檔案可以被其它的YAML檔案當作範本引用，使用的就是template關鍵字，也就是參考檔案的關鍵字。

那什麼樣的YAML結構可以被設計為範本呢？

  • variables
  • stages
  • jobs
  • steps

答案就是上面的這四種。先有個印象就好，後面文章再慢慢學。

發佈留言