GitLab Function 생성

요약

GitLab Function은 함수의 인터페이스와 구현을 정의하는 func.yml 파일이 포함된 디렉터리입니다. CI/CD job에서 함수를 사용하는 방법에 대한 자세한 내용은 GitLab Functions를 참조하세요.

Status: Experiment

GitLab Function은 함수의 인터페이스와 구현을 정의하는 func.yml 파일이 포함된 디렉터리입니다. 함수는 로컬에서 실행하거나 job과 프로젝트 전반에 걸쳐 재사용할 수 있도록 OCI 레지스트리에 게시할 수 있습니다.

CI/CD job에서 함수를 사용하는 방법에 대한 자세한 내용은 GitLab Functions를 참조하세요. 함수 예시는 GitLab Functions 예시를 참조하세요.

함수 구조#

함수는 최소한 func.yml 파일과 구현에 필요한 지원 파일들을 포함하는 디렉터리입니다:

my-function/
├── func.yml
└── my-script.sh

func.yml 파일에는 ---로 구분된 두 개의 YAML 문서가 포함됩니다: 함수의 입력과 출력을 정의하는 spec, 그리고 함수가 수행하는 작업을 설명하는 definition입니다.

# Document 1: spec
spec:
  inputs:
    message:
      type: string
  outputs:
    result:
      type: string
---
# Document 2: definition
exec:
  command: ["${{ func_dir }}/my-script.sh", "${{ inputs.message }}"]

Spec: 입력과 출력 선언#

spec은 함수의 인터페이스를 설명합니다.

입력#

각 입력에는 type이 필요합니다. default 값이 있는 입력은 선택 사항입니다. 기본값이 없는 입력은 호출자가 반드시 제공해야 합니다.

입력 이름은 영숫자와 밑줄만 사용할 수 있으며 숫자로 시작할 수 없습니다.

입력은 다음 타입 중 하나여야 합니다:

타입	예시	설명
array	["a","b"]	타입이 지정되지 않은 항목의 목록
boolean	true	참 또는 거짓
number	56.77	64비트 부동소수점
string	"brown cow"	텍스트
struct	{"k1":"v1","k2":"v2"}	구조화된 콘텐츠

예시:

spec:
  inputs:
    # Required string input
    message:
      type: string

    # Optional input with a default
    count:
      type: number
      default: 1

    # Struct input for passing structured data
    config:
      type: struct
      default: {}

출력#

출력은 함수가 이후 단계로 반환하는 값을 정의합니다. 각 출력에는 type이 필요합니다. default 값이 있는 출력은 선택 사항입니다. 함수가 출력 값을 작성하지 않으면 기본값이 사용됩니다.

출력은 입력과 동일한 타입과 명명 규칙을 사용합니다.

예시:

spec:
  outputs:
    # Required string output
    artifact_path:
      type: string

    # Optional output with a default
    compressed:
      type: boolean
      default: false

런타임에 함수는 ${{ output_file }}에서 지정한 경로에 출력 값을 작성합니다. 각 줄은 name과 value 필드가 있는 JSON 객체여야 합니다:

echo '{"name":"artifact_path","value":"/dist/app.tar.gz"}' >> "${{ output_file }}"
echo '{"name":"compressed","value":true}' >> "${{ output_file }}"

출력 위임#

함수에 여러 단계가 있고 특정 단계에서 함수의 출력을 가져오려면, spec에 outputs: delegate를 사용하고 definition에 delegate: <step_name>을 사용합니다:

spec:
  outputs: delegate
---
run:
  - name: build
    func: ./build
  - name: package
    func: ./package
delegate: package  # use the package step outputs as this function outputs

Definition: 함수 구현#

func.yml의 두 번째 문서는 구현을 설명합니다. 함수는 두 가지 방법으로 구현할 수 있습니다.

exec#

exec를 사용하여 단일 명령 또는 스크립트를 실행합니다. 명령은 셸 없이 OS에 직접 전달되므로 문자열 배열이어야 합니다.

spec:
  inputs:
    message:
      type: string
---
exec:
  command: ["./greet", "${{ inputs.message }}"]

작업 디렉터리의 기본값은 CI_PROJECT_DIR입니다. 재정의하려면 work_dir을 사용합니다. work_dir 키워드는 exec definition에만 유효하며, run: definition에는 사용할 수 없습니다.

명령이 func.yml과 동일한 디렉터리의 파일을 참조해야 할 때는 work_dir을 ${{ func_dir }}로 설정합니다:

exec:
  command: ["./build.sh"]
  work_dir: "${{ func_dir }}"

명령이 0이 아닌 종료 코드로 종료되면 함수가 실패합니다.

run#

run을 사용하면 다른 함수를 순서대로 호출하는 함수를 만들 수 있습니다.

시퀀스의 어떤 단계가 실패하면 함수가 실패합니다. 실패 후에는 시퀀스의 이후 단계가 실행되지 않습니다.

spec:
  inputs:
    environment:
      type: string
  outputs:
    url:
      type: string
---
run:
  - name: build
    func: ./build
  - name: push
    func: registry.example.com/my-org/push:1.0.0
    inputs:
      artifact: ${{ steps.build.outputs.artifact_path }}
  - name: deploy
    func: ./deploy
    inputs:
      env: ${{ inputs.environment }}
      image: ${{ steps.push.outputs.image_ref }}
outputs:
  url: ${{ steps.deploy.outputs.url }}

환경 변수 설정#

definition에서 env를 사용하여 exec 명령 또는 run: 시퀀스의 모든 단계에 환경 변수를 설정합니다. 값에는 표현식을 사용할 수 있습니다:

spec:
---
run:
  - name: test
    func: ./run-tests
env:
  GOFLAGS: "-race"
  TARGET_ENV: "${{ inputs.environment }}"

환경 변수 내보내기#

함수 실행 후 job의 나머지 단계에서 환경 변수를 사용할 수 있도록 하려면, ${{ export_file }}에 작성합니다. 각 줄은 name과 value 필드가 있는 JSON 객체여야 합니다:

echo '{"name":"INSTALL_PATH","value":"/opt/myapp"}' >> "${{ export_file }}"

string, number, boolean 값만 환경 변수로 내보낼 수 있습니다.

내보낸 변수가 env:와 더 넓은 환경과 상호 작용하는 방법에 대한 자세한 내용은 환경 변수를 참조하세요.

표현식#

표현식은 ${{ }} 구문을 사용하며 함수가 실행되기 직전에 평가됩니다. 표현식은 inputs 값, env 값, exec 명령 인수, work_dir에 사용할 수 있습니다.

expressions에 설명된 것 외에도, 함수 definition 내부에서 다음 컨텍스트 변수를 사용할 수 있습니다:

변수	설명
inputs.	이 함수에 전달된 명명된 입력의 값.
func_dir	이 func.yml을 포함하는 디렉터리의 절대 경로. 번들된 파일을 참조할 때 사용.
output_file	출력을 작성하기 위한 파일 경로.
export_file	환경 변수를 내보내기 위한 파일 경로.
steps.<step_name>.outputs.<output_name>	명명된 단계의 출력 (run: definition에서만 사용 가능).

완전한 예시#

다음 함수는 파일 경로를 받아 gzip으로 압축하고 압축된 파일의 경로를 반환합니다.

함수 생성#

디렉터리 레이아웃:

compress/
├── func.yml
└── compress.sh

func.yml:

spec:
  inputs:
    input_path:
      type: string
  outputs:
    output_path:
      type: string
---
exec:
  command: ["${{ func_dir }}/compress.sh", "${{ inputs.input_path }}", "${{ output_file }}"]

compress.sh (실행 가능해야 함):

#!/usr/bin/env sh
set -e

INPUT_PATH="$1"
OUTPUT_FILE="$2"

gzip --keep "$INPUT_PATH"

echo "{\"name\":\"output_path\",\"value\":\"${INPUT_PATH}.gz\"}" >> "$OUTPUT_FILE"

job에서 함수 사용#

이 함수는 job 환경에서 gzip이 필요합니다. 이 예시에서는 job이 실행되는 인스턴스에 gzip이 이미 설치되어 있다고 가정합니다. 설치되어 있지 않은 경우, script: 단계로 먼저 설치하거나, compress를 호출하기 전에 설치를 처리하는 함수를 호출할 수 있습니다.

my-job:
  run:
    - name: compress_artifact
      func: ./compress
      inputs:
        input_path: "dist/app.tar"
    - name: list_compressed
      script: ls -lh ${{ steps.compress_artifact.outputs.output_path }}

더 많은 함수 예시는 GitLab Functions 예시를 참조하세요.

함수 빌드 및 릴리스#

함수는 OCI 이미지로 배포됩니다. step runner는 함수 이미지를 빌드하고 게시하기 위한 두 가지 내장 함수를 제공합니다.

빌드#

builtin://function/oci/build 함수는 프로젝트 디렉터리의 파일로부터 멀티 아키텍처 함수 OCI 이미지를 빌드하고 CI_PROJECT_DIR에 function-image.tar로 아카이브합니다.

common.files는 모든 플랫폼에서 공유되는 파일을 복사합니다. platforms.<os/arch>.files는 해당 플랫폼에 특정한 파일을 복사합니다. 두 경우 모두 맵의 키는 이미지 내의 대상 경로이고 값은 CI_PROJECT_DIR을 기준으로 한 소스 경로입니다.

다음 예시에서 function-image.tar는 두 플랫폼을 지원하는 함수 OCI 이미지입니다: linux/amd64와 linux/arm64. 각 플랫폼 이미지에는 func.yml, my-script.sh, bin/my-binary 세 파일이 있습니다. 플랫폼 바이너리에 동일한 파일 이름을 사용하면 func.yml이 플랫폼에 독립적으로 유지됩니다.

build_function:
  artifacts:
    paths:
      - function-image.tar
  run:
    - name: build
      func: builtin://function/oci/build
      inputs:
        version: "1.2.3"
        common:
          files:
            func.yml: func.yml
            my-script.sh: my-script.sh
        platforms:
          linux/amd64:
            files:
              bin/my-binary: bin/linux-amd64/my-binary
          linux/arm64:
            files:
              bin/my-binary: bin/linux-arm64/my-binary

릴리스#

builtin://function/oci/publish 함수는 function/oci/build의 아카이브를 OCI 레지스트리에 게시합니다.

publish 함수는 함수 이미지 태그에 시맨틱 버저닝을 사용합니다: 1.0.0, 1.1.0, 2.0.0. 함수는 function-image.tar 파일에서 버전을 추출합니다. Publish는 필요에 따라 major, major.minor, major.minor.patch 및 latest 태그를 업데이트합니다.

릴리스 후보는 1.2.0-rc1과 같은 사전 릴리스 접미사를 사용합니다. 릴리스 후보를 게시하면 정확한 major.minor.patch-prerelease 태그만 생성됩니다. major, major.minor, latest 태그는 업데이트하지 않습니다.

publish_function:
  needs: [build_function]
  run:
    - name: publish
      func: builtin://function/oci/publish
      inputs:
        archive: function-image.tar  # version is baked into the tar file
        to_repository: registry.example.com/my-org/my-function

레지스트리 인증#

비공개 레지스트리에 게시하려면 function/oci/publish를 실행하기 전에 인증합니다. Docker Auth 함수를 사용하여 게시 전 단계에서 DOCKER_AUTH_CONFIG를 생성하고 내보냅니다:

publish_function:
  needs: [build_function]
  run:
    - name: auth
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/docker-auth:1
      inputs:
        registry: ${{ vars.CI_REGISTRY }}
        username: ${{ vars.CI_REGISTRY_USER }}
        password: ${{ vars.CI_REGISTRY_PASSWORD }}
    - name: publish
      func: builtin://function/oci/publish
      inputs:
        archive: function-image.tar
        to_repository: ${{ vars.CI_REGISTRY_IMAGE }}

docker-auth는 이후의 모든 단계에 DOCKER_AUTH_CONFIG를 내보내므로, function/oci/publish가 자동으로 이를 사용합니다.

게시 후, 호출자는 레지스트리 URL과 태그를 사용하여 함수를 참조합니다:

run:
  - name: run_my_function
    func: registry.example.com/my-org/my-function:1.2.3