Kubernetes Runner 구성 가이드

이번 kubernetes Runner 설정 가이드를 보기 전에 Runner 구성과 GitLab Runner 로컬 설치 구성 가이드를 읽어 보시기 바랍니다.

사전조건

• 클러스터로부터 GitLab 서버의 API 호출이 가능해야 합니다.
• Beta API 가능한 1.4 버전 이상의 Kubernetes를 사용해야 합니다.
• kubectl CLI가 로컬에 설치되어 있고 클러스터에 인증되어 있어야 합니다.
• Helm CLI가 PC에 설치되어 있어야 합니다.

사전준비 - (번외) Kubernetes 설정

특정 Namespace에 Runner를 사용하기 위해서는 몇 가지 설정이 필요합니다.

1. CSP(Cloud Solution Provider) 환경에 로그인

특정 Kubernetes의 Namespace 및 Service Account 생성 권한이 있는 계정으로 로그인해야 합니다

• Azure (참고)

az login
az aks get-credentials --resource-group myResourceGroup --name myAKSCluster

• AWS

aws configure (참고)

aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

eks에 연결(참고)

aws eks --region <region> update-kubeconfig --name <cluster_name>

• GCloud (참고)

gcloud auth login
gcloud config set compute/zone <compute-zone>
gcloud container clusters get-credentials <cluster-name>

2. Namespace 생성

• Namespace의 경우 그룹이나 팀, 혹은 파트별로 구성
  • 예시: group-a, group-b, team-a, team-b, part-a, part-b, dep-a, dep-b
• 아래 명령어를 실행하여 hello-world라는 Namespace를 생성

kubectl create namespace hello-world

• 생성된 Namespace 확인

kubectl get namespaces

• 생성된 Namespace로 이동(kubens가 설치되지 않았을 때 get 명령어에 -n 옵션으로 네임스페이스를 지정하면 됩니다)

kubens hello-world

3. Service Account 생성

• Namespace를 관리할 Service Account 생성하여 관리
  • 예시: sa-group-a, sa-group-b, sa-team-a, sa-team-b
• 아래 명령어를 실행하여 hello-sa라는 이름의 Service Account 생성
  • namespace를 지정(예시는 hello-world namespace를 연결)

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: hello-sa
  namespace: hello-world
EOF

• Service Account 정보 확인

kubectl get serviceaccounts hello-sa -o yaml

4. Role 생성

• hello-role이라는 이름의 Role을 생성

cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: hello-world
  name: hello-role
rules:
- apiGroups: ["extensions", "apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["pods","services","secrets","pods/exec", "serviceaccounts"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
EOF

• Role 정보 확인

kubectl get roles hello-role -o yaml

5. Role Binding 생성

hello-rb라는 이름의 Role Binding을 생성하여 hello-sa Service Account와 hello-role Role을 바인딩.

cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: hello-world
  name: hello-rb
subjects:
- kind: ServiceAccount
  name: hello-sa
  namespace: hello-world
roleRef:
  kind: Role
  name: hello-role
  apiGroup: rbac.authorization.k8s.io
EOF

• Role Binding 정보를 확인

kubectl get rolebindings hello-rb -o yaml

Helm Chart를 사용하여 GitLab Runner 설치하기

GitLab Helm 리포지터리를 추가합니다.

helm repo add gitlab https://charts.gitlab.io

만약 Helm 2를 사용한다면, 먼저 Helm을 초기화해야 합니다.

helm init

한 번이라도 values.yaml 파일을 사용하여 GitLab 러너를 설정해 봤다면, 아래의 명령어를 실행하세요.

helm install --namespace <NAMESPACE> gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

• <NAMESPACE>는 GitLab 러너를 설치하기 원하는 Kubernetes 네임스페이스
• <CONFIG_VALUES_FILE>은 커스텀 설정이 포함된 파일의 경로. Helm Chart를 사용하여 GitLab Runner 설정하기를 참고하세요.

예시

• values.yaml 파일 예시

gitlabUrl: https://gitlab.com # gitlab url 입력
runnerRegistrationToken: a-trnA24KR77Mh***** # registration token 생성(CI/CD > Runner > New Project Runner)

• helm 설치하기(values.yaml 파일이 있는 폴더에서 아래 명령어를 수행)

helm install --namespace hello-world gitlab-runner -f values.yaml gitlab/gitlab-runner

Helm Chart를 사용하여 GitLab Runner 업그레이드하기

GitLab 러너를 업그레이드하기 전에, GitLab에 러너를 중지시키고 모든 Job이 끝났는지 확인하세요. 러너를 중지시키는 것은 완료 시 권한부여 오류같이 Job에서 발생하는 문제를 방지할 수 있습니다.

GitLab Runner Chart가 설치되면 helm upgrade를 사용하여 구성 변경 및 차트 업데이트를 수행해야 합니다.

helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner

• <NAMESPACE>는 GitLab 러너를 설치하고 싶은 Kubernetes 네임스페이스
• <CONFIG_VALUES_FILE>은 커스텀 설정이 포함된 파일의 경로. Helm Chart를 사용하여 GitLab Runner 설정하기를 참고하세요.
• <RELEASE-NMAE>은 차트를 설치할 때 지어주는 이름입니다. Helm Chart를 사용하여 GitLab Runner 설치하기에서는 gitlab-runner라고 했습니다.

만약 GitLab Runner Helm Chart를 최신 버전이 아닌 특정 버전으로 업데이트하길 원하신다면, helm upgrade 명령어에 --version <RUNNER_HELM_CHART_VERSION>을 추가하세요.

사용가능한 GitLab Runner Helm Chart 버전 확인하기

Helm Chart 및 GitLab Runner 버전은 동일한 버전 관리를 따르지 않습니다. 아래 명령을 사용하여 Helm Chart와 GitLab Runner 간의 버전 매핑을 가져옵니다.

helm search repo -l gitlab/gitlab-runner

출력의 예는 다음과 같습니다.

NAME                    CHART VERSION   APP VERSION DESCRIPTION
...
gitlab/gitlab-runner    0.14.0          12.8.0      GitLab Runner
gitlab/gitlab-runner    0.13.1          12.7.1      GitLab Runner
gitlab/gitlab-runner    0.13.0          12.7.0      GitLab Runner
gitlab/gitlab-runner    0.12.0          12.6.0      GitLab Runner
gitlab/gitlab-runner    0.11.0          12.5.0      GitLab Runner
gitlab/gitlab-runner    0.10.1          12.4.1      GitLab Runner
gitlab/gitlab-runner    0.10.0          12.4.0      GitLab Runner
...

Helm Chart를 사용하여 GitLab Runner 설정하기

GitLab Runner 구성을 위한 values.yaml 파일을 만듭니다. values 파일의 기본값을 재정의하는 방법에 대한 정보는 Helm 문서를 참조하십시오.

기본 구성은 항상 values.yaml 차트 저장소에서 찾을 수 있습니다.

필수 구성

GitLab Runner가 작동하려면 구성 파일에 다음 내용이 명시되어야 합니다.

• gitlabUrl - 러너를 등록할 GitLab 서버 전체 URL (예: https://gitlab.example.com)
• runnerRegistrationToken - GitLab에 새 러너를 추가하기 위한 등록 토큰입니다. 이것은 CICD - Runner - New Project Runner 에서 생성되어야 합니다.

더 이상 추가 구성할 필요가 없으면 GitLab Runner를 설치할 준비가 되었습니다.

추가 구성

구성 템플릿 파일을 사용하여 러너를 구성할 수 있습니다. Helm 차트가 특정 러너 구성 옵션을 인식하지 않고도 구성 템플릿을 사용하여 러너의 모든 필드를 구성할 수 있습니다.

다음은 차트 저장소의 values.yaml 파일에 있는 기본 설정의 일부입니다. values.yaml의 conifg.toml을 포함할 때, config: 섹션에서 toml(<parameter> = <value> 대신에 <parameter>: <value>) 형식이어야 한다는 것을 꼭 주의해주세요.

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"

나머지 설정의 values.yaml에 대한 문서를 확인하세요.

구성 템플릿으로 Cache 사용하기

구성 템플릿을 이용하여 캐시를 사용하려면 values.yaml의 다음 변수를 설정하세요.

• runners.cache.secretName 개체 스토리지 공급자에 대한 secret name(s3access, gcsaccess,google-application-credentials 또는 azureaccess)
• runners.config와 캐시에 대한 추가 설정을 합니다. toml 서식을 사용하세요.

이번 가이드에서는 aws S3에 대해서만 설명합니다. Kubernetes Runner 설정에 대한 깃랩 공식 가이드 문서를 참조하세요.

여기에 S3 static credentials를 활용한 구성 예제가 있습니다.

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        [runners.cache]
          Type = "s3"
          Path = "runner"
          Shared = true
          [runners.cache.s3]
            ServerAddress = "s3.amazonaws.com"
            BucketName = "my_bucket_name"
            BucketLocation = "eu-west-1"
            Insecure = false

  cache:
    secretName: s3access

다음으로 accesskey와 secretkey를 포함한 Kubernetes secret s3access를 만듭니다.

kubectl create secret generic s3access \
    --from-literal=accesskey="YourAccessKey" \
    --from-literal=secretkey="YourSecretKey"

RBAC 지원 활성화하기

만약 클러스터가 RBAC를 사용하도록 설정한 경우, 차트가 자신의 서비스 계정을 만들거나 이미 만들어진 것을 사용하는 것을 선택할 수 있습니다.

차트에서 서비스 계정을 만들려면 rbac.create를 true로 설정합니다.

rbac:
  create: true

이미 존재하는 서비스 계정을 사용하려면 아래의 명령어를 사용하세요.

rbac:
  create: false
  serviceAccountName: your-service-account

ERROR: Job failed (system failure): secrets is forbidden

만약 다음 에러가 발생한다면 RBAC 기능을 활성화해야 합니다.

Using Kubernetes executor with image alpine ...
ERROR: Job failed (system failure): secrets is forbidden: User "system:serviceaccount:gitlab:default" cannot create resource "secrets" in API group "" in the namespace "gitlab"