生活記事簿: GitLab CICD - 使用 GitLab Runner

這裡紀錄下使用
GitLab 做 CICD (Continuous Integration/Continuous Deployment, 持續整合、持續佈置)
時的一些佈驟及事項

GitLab 使用了 Job, Gitlab-Runner 及 executor 的設計。

在 Git 專案根目錄上會需要建立一個描述 Job 的 .gitlab-ci.yml 檔案，
其中記載了 CICD 要做的事項流程即要執行的 script 語句。

Gitlab-Runner 會跟 Gitlab repository 連線、檢查有無分派 Job 、並接受 Job ， Gitlab-Runner 可能是被按裝在在 Windows 系統上、或是被按裝在 Linux 上、或甚至是在某台 server 跑起來的 Docker 中都有可能。

在 Gitlab-Runner 中，可以在其設定檔 config.toml 中設定多個 Gitlab-executor，當 Gitlab-Runner 接到需要執行的 Job 時，就會啟動相應 (例如 .gitlab-ci.yml 中擁有 tag1, tag2 的 Job 對應到有 tag1, tag2 的 Gitlab-executor) 的 Gitlab-executor。

因為 Gitlab-executor 本身需要跟 Giblab repository 連線，所以需要指定 Gitlab repository 的 SSL 憑證，例如如果專案位於 Gitlab 的 https://xxx.git/... 上，那就要取得 https://xxx.git 的憑證 (例如可以用 Chrome 瀏覽器去下載憑證)。

Gitlab-executor 是主要執行 .gitlab-ci.yml 中 Job 的 script 語句的環境，有分成幾種不同環境的 executor，
例如官方列出的 shell, docker, ssh 等等，可參考 Executors | GitLab。
當使用 shell 環境的 Gitlab-executor 時，相當於直接在 Git-Runner 安裝環境上直接執行 script，
例如如果 Git-Runner 裝在 Windows 系統上，相當於直接執行 Windows 的 command line 語句。
或是例如如果 Git-Runner 裝在 Linux 系統 (如果裝在 docker 運行的 Linux 上也是一樣) 上，則相當於直接執行 Linux bash 語句。

當使用 docker 環境的 Gitlab-executor 時，Gitlab-Runner 會在所處環境下以指定的 docker image (可在 .gitab-ci.yml 中指定，或是在 config.toml 中指定預設的 image) 啟動一個指定的 docker container (這時 Gitlab-Runner 所被安裝的環境下必須要事先安裝好 docker)，
Job 的 script 會以在這個被啟動的 docker container 下被執行。
例如如果啟動的 docker container 是含有安裝 php 的 container，那就能執行 Job script 的 php 語句。

這裡我以一個例子做示範，
情境是用 docker 啟動兩個 container，
一個運行 Gitlab-Runner，
另一個運行 Linux ubuntu 系統來模擬正式環境程式要佈署到的那台 server，
在這裡 Git project 假設是一個 Maven 專案，我想要利用 GitLab CICD 來對專案進行建構 war 檔 (mvn clean install)，並以 SSH 的方式傳送到佈署 server，並以 SSH 連線佈署 server 執行解包 (jar -xvf xxx.war)

以下開始示範：

首先先安裝 Gitlab-Runner，
詳請可參考官網 Install GitLab Runner | GitLab ，
在這邊我以用 docker 來安裝 Gitlab-Runner 示範，
docker 可以使用 gitlab/gitlab-runner:latest 這個 docker image 來安裝 Gitlab-Runner，

安裝完好後，接下來要來進行 Gitlab-executor 的設定，
詳請請參閱官網 Registering runners | GitLab，
設定主要以/etc/gitlab-runner/config.toml 設定檔來設定，
如果 Gitlab-Runner 不是用 root 身份啟動的話，檔案就會改放在登入 user 的位置，
例如 ~/.gitlab-runner/config.toml，可參考 Advanced configuration | GitLab 。
如果本來就有已設定好的 config.toml 檔的話，放在 Gitlab-Runner container 中的正確位置就可以了，基本上每次對 config.toml 檔的修改 Gitlab-Runner 都會偵測到並再次載入修改的設定，不太需要重開 Gitlab-Runner，

如果第一次沒有 config.toml 檔存在，想要一個範本的話，可以使用交互模示來進行 register Gitlab-executor，啟動 Gitlab-Runner 後，執行 container 的 gitlab-runner register 指令：
(假設 container 名稱取叫 my-gitlab-runner-container)
docker exec -it my-gitlab-runner-container gitlab-runner register

如果 Gitlab repository 是 https 的話，如之前所述需要設定憑證位置，指令要改成：
docker exec -it my-gitlab-runner-container gitlab-runner register --tls-ca-file=/path/to/tlsCaFile
請把 /path/to/tlsCaFile 改成憑證在 container 中的位置，

設定好以後就會多出 /etc/gitlab-runner/config.toml，
裡面的內容之後可以依自己需求需改
(保持可例如用 docker cp 取出後設定到 docker-compose volume 裡面做持久化之類)，
而註冊好的 Gitlab-Executor 也會在 GibLab 網站上各 Project (如果是 Project runner 的話) 的
CICD --> Runner 設定裡面，
需要注意的是，在 GitLab 網站介面中，有時也會把 Gitlab-executor 稱呼成 Runner，
其實可以把 Gitlab-executor 當成是 Gitlab-Runner 在不同環境下的 Job script 執行就可以比較好理解了。

我的模擬目錄如下：

/docker-compose.yml

/gitlab-runner/Dockerfile
/gitlab-runner/config/config.toml
/gitlab-runner/ssh/id_rsa
/gitlab-runner/ssh/id_rsa.pub
/gitlab-runner/ssl/gitLabCA.cer

/online-server/Dockerfile
/online-server/ssh/authorized_keys
/online-server/project/

這邊我就直接貼上 docker-compose 的設定：

docker-compose.yml:

version: '2'
services:
    docker-runner:
        build: ./gitlab-runner
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - ./gitlab-runner/ssl:/data/ssl/
            - ./gitlab-runner/config:/etc/gitlab-runner
    online-server:
        build: ./online-server
        volumes:
            - ./online-server/ssh:/root/.ssh
            - ./online-server/project:/data/project
        ports:
            - "2222:22"

先看 volumes 中的設定，

/var/run/docker.sock:/var/run/docker.sock 設定了 docker socket 的用法，
來讓 Gitlab-Runner 可以像宿主機 (host) 那樣使用 docker 去啟動一個 Gitlab-executor。

./gitlab-runner/ssl:/data/ssl/ 則是把 Gitlab repository 的 SSL 憑證放到 Gitlab-Runner container 中。

而 ./gitlab-runner/config:/etc/gitlab-runner 的設定則是讓 Gitlab-Runner 的設定檔 config.toml 持久化，不要 container 關閉了以後修改就不見了。

在 /gitlab-runner/ssh 中的 id_rsa 和 id_rsa.pub 是用 ssh-keygen 指令產生出來的 SSH 私鑰 (private key) 和公鑰 (public key)，可以用來設定 Gitlab-Executor 在使用 SSH 連線時，不用密碼登入 (這邊其實公鑰用不到，公鑰主要是要放在被 SSH 連線的對方 server 上)，

詳細可參考：

[教學] 產生SSH Key並且透過KEY進行免密碼登入 | 辛比誌

在這裡我們沒有對 /gitlab-runner/ssh 設定 volumes 的原因是，

因為 Gitlab-Executor 在執行時會以 "gitlab-runner" 這樣的 user 身份做登入 (不是 root)，

所以 id_rsa 必須放在 /home/gitlab-runner/.ssh 資料夾之下，

並且 id_rsa 及它所在的資料夾都必須能為 "gitlab-runner" user 來存取，

所以之後我們會用 Dockerfile 的 ADD 指令把 id_rsa 加進 Gitlab-Runner container 中並設定擁有者和權限。

注意的是，把 id_rsa 放到 Gitlab-Runner container 中這件事只需對 shell 的 executor 做，

因為如果是 docker 的 executor，官方有說可以在 Gitlab 中設定變數 (Variables) 並在 Job 中完成 container 的 SSH private key 設定，可參考 SSH keys when using the Docker executor

現在讓我們來看 /gitlab-runner/Dockerfile 的內容：

/gitlab-runner/Dockerfile ：

FROM gitlab/gitlab-runner:latest

RUN mkdir /home/gitlab-runner/.ssh
ADD ["ssh", "/home/gitlab-runner/.ssh"]
RUN chown -R gitlab-runner:gitlab-runner /home/gitlab-runner/.ssh
RUN chmod -R 700 /home/gitlab-runner/.ssh

可以看到在 /gitlab-runner-Dockerfile 中，設定了要啟動的 docker image 為 gitlab/gitlab-runner，
建立了 gitlab-runner 身份的 .ssh 資料夾，
用 ADD 指定放進了 id_rsa，並且用 chown 更改了檔案擁有者、
用了 chmod 改變了檔案權限，700 代表只允設檔案擁有者有 read (讀), write (寫), execute (執行) 的權限，須注意的是不能把 id_rsa 權限設定的太大，例如 777，太大的權限在 SSH 連線時也有可能會被禁止。

在我們看 /gitlab-runner/config/config.toml 之前，
先來看一下 onlin-server 的設定，online-server 是用來模擬一個有開放 SSH 連接並已有安裝好 jdk 的線上佈署環境。

/online-server/Dockerfile ：

FROM ubuntu:latest

RUN apt-get update
RUN apt-get install ssh -y
RUN apt-get install openjdk-11-jdk -y

# RUN echo "root:12345"|chpasswd # we don't need to set password for root because we want to use ssh-key-only-login

RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/g' /etc/ssh/sshd_config # let root user can login
#RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin without-password/g' /etc/ssh/sshd_config # let root user can login but only use way without password, like ssh key

RUN sed -i 's/#AuthorizedKeysFile/AuthorizedKeysFile/g' /etc/ssh/sshd_config # let "authorized_keys" file can be used for ssh login
RUN mkdir ~/.ssh
RUN chmod -R 700 ~/.ssh

RUN service ssh start

EXPOSE 22

CMD ["/usr/sbin/sshd","-D"]

在 online-server 的 dockerfile 中，使用了 ubuntu 的 docker image，

並用 apt-get 安裝了 ssh 及 openjdk-11-jdk，

在這邊為了方便是先假設 Gitlab-Executor 會用 root 身份來登入 SSH，

不過在實際上為了安全，通常應會再設定一個非 root 的身份來讓其登入，

因為在這裡不用 root 用密碼登入 (會用 SSH key 登入)，所以沒設定密碼，如果要設定 root 的密碼的話，可以用以下指令，請把 12345 換成要的密碼，如果是要其他身份請把 root 換掉：

RUN echo "root:12345"|chpasswd

接著要修改 /etc/ssh/sshd_config 檔的內容，

因為這裡需要讓 root 身份登入，所以需要把內容裡的
#PermitRootLogin prohibit-password 換成
PermitRootLogin yes 或
PermitRootLogin without-password (可以登入，但不能用密碼登入)，

可以看到我們使用
sed -i
的指令來做修改。

然後
#AuthorizedKeysFile 也要把註解拿掉，換成

AuthorizedKeysFile

接著建立 .ssh 資料夾並設定權限，要注意的是

RUN mkdir ~/.ssh

RUN chmod -R 700 ~/.ssh

只適用於讓 root 身份登入的情況，如果需要讓其他身份登入，請照類似
/gitlab-runner/Dockerfile 中的方式，為非 root 身份建立正確位置的 .ssh 資料夾、設定擁有者和權限。

最後用以下命令啟動 SSH service，往外打開 22 port，
並把 container 的生命週期綁在 "/usr/sbin/sshd" 上：

RUN service ssh start

EXPOSE 22

CMD ["/usr/sbin/sshd","-D"]

在來我們來看下 Gitlab-Executor 的設定，即 /gitlab-runner/config/config.toml，

/gitlab-runner/config/config.toml ：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "xxx description"
  url = "https://xxx-git"
  token = "xxxxxxxxxxxxxxxxxxxx"
  tls-ca-file = "/data/ssl/gitLabCA.cer"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "ubuntu:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    network_mode = "gitlab-cicd-test_default"
    volumes = ["/c/Users/xxx/.m2/repository:/.m2/repository"]
    shm_size = 0

[[runners]]
  name = "yyy description"
  url = "https://xxx-git/"
  token = "yyyyyyyyyyyyyyyyyyyy"
  tls-ca-file = "/data/ssl/gitLabCA.cer"
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

在此例 config.toml 中，

有兩個 Gitlab-Executor 被設定，分別是環境為 docker 的 docker executor 和環境為 shell 的 shell executor，環境是用 executor 這個參數來設定，例如 executor = "docker"。

可以看到兩個 executor 都設定了 Gitlab reposotiry SSL 憑證的位置，即 "tls-ca-file" 這個參數設定。

在 docker executor 中，[runners.docker] 裡可以設定一些關於會被啟動的 executor 的 container 的設定，其中例如：

image 參數可設定預設 docker image，如果 GitLab CICD Job 設定檔 .gitlab-ci.yml 的 Job 沒有指定 docker image 的話，就會拿預設 docker image 來用。

volumes 可以設定 Gitlab-executor 的 volumes，在此例中因為我的宿主機是 Windows (我使用了 Windows 系充可以安裝的 Docker Desktop)，並且如剛才所說我們是使用了 Docker socket 而非 dind (Docker in Docker) 的方式，Gitlab-Executor 和 Gitlab-Runner 是平行的關係 (即不是在 Gitlab-Runner container 裡又開了一個 Gitlab-Executor container)，

所以 volumes 設定的宿主機是 Windows，

在這裡我設定了 Maven repository 的位置做 volumes 給 Docker-executor 用以避免每次執行 CICD 時，mvn clean install 都要再上網抓一次 library ，因為每次 CICD Job 執行完後，啟動起來的 Docker Gitlab-Executor 都會被銷毀掉，裡面的資料沒做特別設定的話也都會消失掉。

要注意的是，Windows 系統的路徑，例如 D:\\xxx 要寫成 /d/xxx，且路徑上不可有空白符號。

network_mode 可以設定 Docker Gitlab-Executor container 使用的 network_mode，
效果等同於 docker run 指令的 --network_mode 參數及 docker-compose.yml 裡的 network_mode 參數。
因為我的 docker-compose.yml 建立起來的 gitlab-runner 和 online-server 這兩個 container 所處的網路名稱為 gitlab-cicd-test_default，

為了讓不是被 docker-compose.yml 建立起來的 Gitlab-Executor container 能夠與 online-server 這個 container 溝通 (之後要用 SSH 去連)，所以我用了

network_mode = "gitlab-cicd-test_default"

把 executor container 加進 "gitlab-cicd-test_default" 網路中。

最後來看看 .gitlab-ci.yml 裡面寫了什麼，

.gitlab-ci.yml：

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=/.m2/repository"

cache:
  paths:
    - .m2/repository/

stages:
  - build
  # - test
  - deploy

build-job-docker:
  stage: build
  image: maven:3.6.3-jdk-11
  script:
    - mvn clean install
  tags:
    - docker
  artifacts:
    paths:
      - target/*.war
    expire_in: 1 day
  when: manual

build-job-shell:
  stage: build
  script:
    - mvn clean install
  tags:
    - shell
  artifacts:
    paths:
      - target/*.war
    expire_in: 1 day 
  when: manual

deploy-job-docker-executor:
  stage: deploy
  before_script:
    ##
    ## Install ssh-agent if not already installed, it is required by Docker.
    ## (change apt-get to yum if you use an RPM-based image)
    ##
    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

    ##
    ## Run ssh-agent (inside the build environment)
    ##
    - eval $(ssh-agent -s)

    ##
    ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
    ## We're using tr to fix line endings which makes ed25519 keys work
    ## without extra base64 encoding.
    ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
    ##
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -

    ##
    ## Create the SSH directory and give it the right permissions
    ##
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh

    ##
    ## Optionally, if you will be using any Git commands, set the user name and
    ## and email.
    ##
    # - git config --global user.email "user@example.com"
    # - git config --global user.name "User name"
  script:
    - cd target
    - apt-get update && apt-get install ssh -y
    - scp -o StrictHostKeyChecking=no xxx.war root@online-server:/data/project
    - ssh -o StrictHostKeyChecking=no root@online-server "cd /data/project && jar -xvf /data/project/xxx.war"
  tags:
    - docker  
  when: manual

deploy-job-ssh-shell-executor:
  stage: deploy
  script:
    - cd target
    - scp xxx.war root@online-server:/data/project
    - ssh -o StrictHostKeyChecking=no root@online-server "cd /data/project && jar -xvf /data/project/xxx.war"
  tags:
    - shell  
  when: manual

說明：

在這裡，我已經為注冊好的兩個 Gitlab executor 分別設定了 "docker" 和 "shell" 的 tag。
MAVEN_OPTS: "-Dmaven.repo.local=/.m2/repository" 是設定給 Maven 的環境變量，指定 Maven local repository 的存放位置，並利用 cache paths 的設定將期設成 cache，:
```
cache:
  paths:
    - .m2/repository/
```
這樣在一個 Gitlab CICD Pipeline中的 Job 可以共享 Maven 下載的 Library，不用每個 Job 都再下載一次，雖然效果跟 artifacts 很像，不過用途不太一樣，如果要在 Job 之間共享檔案並且希望能在 Gitlab 網頁界面上存取，例如被 CICD 建立 (build) or 佈署 (deploy) 的檔案，通常會使用 artifacts 而非 cache，詳情可參考 How cache is different from artifacts。
需注意的是，以上的 Maven repository 設定只對 Docker Gitlab Executor 有效，代表的是被啟動的 Docker Gitlab Executor Container 的 Maven local repository 位置，
如果是 Shell Gitlab Executor 的話， Gitlab Runner 本身所處的環境應該會已經先設定好 Maven 的相關配置才對。
在這裡我只用到了 build, deploy 兩個 stage，所以 test stage 被注解掉了。
artifacts 設定了要和其他 Job 共享的檔案位置，是對 project 根目錄的相對位置，在這裡 target/*.war 即是 Maven 的 clean install 命令產出的 war 檔位置，expire_in 可設置 artifact 檔留存在 Gitlab 上的時間，在留存期間我們都可以到 Gitlab 上下載。
```
  artifacts:
    paths:
      - target/*.war
    expire_in: 1 day
```
deploy-job-docker-executor 是一個 Docker Gitlab Executor，before_script 裡設定的語句可以在 script 語句執行之前被執行，在這邊執行的語句是參考了官方的範例：SSH keys when using the Docker executor ，把我們在 Gitlab 中設定 SSH_PRIVATE_KEY 參數設定到了 Docker Gitlab Executor Container 中的 SSH Private Key 應存放位置 (SSH_PRIVATE_KEY 的值即為 id_rsa 裡的 private key 內容)。
deploy-job-docker-executor 的 script 內容為，安裝 SSH 連線用軟體，
進到 target 資料夾 (裡面有之前設定到 artifact 的 war 檔)，
使用 scp 指令將 war 檔傳到要被布署的 server 上，
再使用 ssh 指令登入布署 server，用 jar -xvf 指令去解開 war 檔完成佈署。
deploy-job-ssh-shell-executor 是一個 Shell Gitlab Executor，因為已經事先在其所在環境上 (即 Gitlab Runner 所安裝處的環境，此例為 Linux 環境) 設置好配置，所以只要直接執行 script 指令就好，script 指令基本跟 deploy-job-docker-executor 一樣，只差在不用再安裝 SSH 連線軟體。
需要注意的是，如果 Gitllab Runner 是裝在 Windows 系統上的話，script 裡的語句就會是 Windows cmd 的語法，可能會與 Linux bash 語法稍有不同。
scp 及 ssh 指令的 -o StrictHostKeyChecking=no 參數是告訴 scp, ssh 指令使用"非交互方式" 執行，因為例如在第一次使用 scp, ssh 連線時，會有提示訊息詢問，例如：
```
The authenticity of host 'xxx (xxx)' can't be established.
RSA key fingerprint is yyyyyyy.
Are you sure you want to continue connecting (yes/no)?
```
但因為我們沒有辦法在 script 模式下用 yes 或 no 的交互模式，所以這時就可以用
-o StrictHostKeyChecking=no
來取消交互方式。
因為我們的 Gitlab Executor 都是設定手動執行 (when: manual)，所以需要到 Gitlab 上自行啟動 CICD Pipeline ，如果一切都順利的話，應就可在被佈署 server 上 (即 online-server) 看到被解包的專案了。

參考資料：

生活記事簿

2022年2月28日星期一

GitLab CICD - 使用 GitLab Runner

沒有留言 :

張貼留言

2022年2月28日 星期一

GitLab CICD - 使用 GitLab Runner

沒有留言 :

張貼留言

2022年2月28日星期一