튜토리얼: GitLab 워크스페이스 프록시 설정

이 튜토리얼에서는 GitLab 워크스페이스 프록시를 설정하여 클러스터 내의 workspaces를 인증하고 권한 부여하는 방법을 알아보겠습니다.

gitlab-workspaces-proxy를 설정하려면 다음 단계를 수행해야 합니다.

  1. TLS 인증서 생성.
  2. GitLab 인스턴스에 앱 등록
  3. SSH 호스트 키 생성
  4. GitLab URL 내보내기
  5. 구성 비밀 생성
  6. 프록시를 위한 Helm 차트 설치
  7. Kubernetes 리소스 확인
  8. DNS 레코드 업데이트

전제 조건

  • 설치된 Ingress 컨트롤러
  • 실행 중인 Kubernetes 클러스터
  • 로컬 머신에 helm 3.11.0 이상 및 kubectl이 있는 경우

TLS 인증서 생성

다음에 대한 TLS 인증서를 생성해야 합니다.

  • gitlab-workspaces-proxy이 수신 대기하는 도메인(GITLAB_WORKSPACES_PROXY_DOMAIN)
  • workspaces가 있는 도메인(GITLAB_WORKSPACES_WILDCARD_DOMAIN)

아무 인증기관에서 인증서를 생성할 수 있습니다.

TLS 인증서를 생성하려면 다음 단계를 수행하세요.

  1. HTTPS를 활성화하려면 Certbot을 설치합니다. 

    brew install certbot

  2. ACME DNS를 사용하여 Let’s Encrypt 인증서를 생성하고 DNS 제공자에 TXT 레코드를 생성합니다. 

    export EMAIL="YOUR_EMAIL@example.dev"
export GITLAB_WORKSPACES_PROXY_DOMAIN="workspaces.example.dev"
export GITLAB_WORKSPACES_WILDCARD_DOMAIN="*.workspaces.example.dev"

certbot -d "${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  -m "${EMAIL}" \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work \
  --manual \
  --preferred-challenges dns certonly

certbot -d "${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  -m "${EMAIL}" \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work \
  --manual \
  --preferred-challenges dns certonly

  3. 다음 환경 변수를 생성 출력의 인증서 디렉토리로 업데이트합니다. 

    export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_WILDCARD_DOMAIN}/fullchain.pem"
export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_WILDCARD_DOMAIN}/privkey.pem"

    certbot 명령은 와일드카드 도메인에 대해 다른 경로를 생성할 수 있습니다. 

    export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/fullchain.pem"
export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/privkey.pem"

이제 인증서를 생성했으니 GitLab 인스턴스에 앱을 등록해야 합니다.

GitLab 인스턴스에 앱 등록

GitLab 인스턴스에 앱을 등록하려면 다음 단계를 수행하세요.

  1. GitLab을 OAuth 2.0 식별 공급자로 구성.
  2. 리디렉션 URI를 https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback로 설정합니다.
  3. Trusted 확인란을 선택합니다.
  4. 스코프를 api, read_user, openid, profile로 설정합니다.

  5. CLIENT_ID, CLIENT_SECRET, 및 REDIRECT_URI를 내보냅니다. 

    export CLIENT_ID="your_application_id"
export CLIENT_SECRET="your_application_secret"
export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
  6. 클라이언트 ID와 생성된 비밀을 안전한 장소(예: 1Password)에 저장합니다.

다음으로 SSH 호스트 키를 생성하고 GitLab URL을 내보냅니다.

SSH 호스트 키 생성

RSA 키를 생성하려면 다음 명령을 실행합니다. 

ssh-keygen -f ssh-host-key -N '' -t rsa
export SSH_HOST_KEY=$(pwd)/ssh-host-key

또는 ECDSA 키를 생성할 수도 있습니다.

GitLab URL 내보내기

GITLAB_URL 환경 변수를 내보내려면 다음 명령을 실행합니다. 

export GITLAB_URL="https://gitlab.com"

그런 다음 프록시를 위한 구성 비밀을 생성합니다.

프록시를 위한 구성 비밀 생성

프록시를 위한 구성 비밀을 생성하려면 다음 단계를 수행하세요.

  1. 서명 키를 생성하고 안전한 장소(예: 1Password)에 키를 저장합니다.

  2. SIGNING_KEY를 내보냅니다. 

    export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"

프록시를 위한 Helm 차트 설치

프록시를 위한 Helm 차트를 설치하려면 다음 단계를 수행하세요.

  1. helm 리포지토리를 추가합니다. 

    helm repo add gitlab-workspaces-proxy \
  https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel

  2. 다른 Ingress 클래스를 사용하는 경우 ingress.className 매개변수를 수정합니다. 

    helm repo update

helm upgrade --install gitlab-workspaces-proxy \
  gitlab-workspaces-proxy/gitlab-workspaces-proxy \
  --version 0.1.15 \
  --namespace=gitlab-workspaces \
  --create-namespace \
  --set="auth.client_id=${CLIENT_ID}" \
  --set="auth.client_secret=${CLIENT_SECRET}" \
  --set="auth.host=${GITLAB_URL}" \
  --set="auth.redirect_uri=${REDIRECT_URI}" \
  --set="auth.signing_key=${SIGNING_KEY}" \
  --set="ingress.host.workspaceDomain=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  --set="ingress.host.wildcardDomain=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  --set="ingress.tls.workspaceDomainCert=$(cat ${WORKSPACES_DOMAIN_CERT})" \
  --set="ingress.tls.workspaceDomainKey=$(cat ${WORKSPACES_DOMAIN_KEY})" \
  --set="ingress.tls.wildcardDomainCert=$(cat ${WILDCARD_DOMAIN_CERT})" \
  --set="ingress.tls.wildcardDomainKey=$(cat ${WILDCARD_DOMAIN_KEY})" \
  --set="ssh.host_key=$(cat ${SSH_HOST_KEY})" \
  --set="ingress.className=nginx"

    참고: 인증서를 갱신해야 할 수 있습니다. 예를 들어, Let’s Encrypt 인증서는 기본적으로 세 달 동안 유효합니다. 새로운 인증서를 받으면 이전 helm 명령을 다시 실행하여 인증서를 업데이트해야 합니다.

이제 Kubernetes 리소스를 확인하겠습니다.

Kubernetes 자원 검증

  1. 다음의 Kubernetes 자원을 확인하세요:

    • 구성 시크릿: 

      kubectl -n gitlab-workspaces get secret gitlab-workspaces-proxy  -o=go-template='{{index .data "config.yaml"}}' | base64 -d

    • gitlab-workspaces 네임스페이스의 인그레스 클래스: 

      kubectl -n gitlab-workspaces get ingress

      프록시를 gitlab-workspaces 이외의 다른 네임스페이스에 배포하는 경우, GitLab 에이전트 구성에서 네임스페이스를 업데이트하세요: 

      remote_development:
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

  2. 파드가 실행 중인지 확인하세요: 

    kubectl -n gitlab-workspaces get pods

이제 DNS 레코드를 업데이트할 수 있습니다.

DNS 레코드 업데이트

DNS 레코드를 업데이트하려면 다음을 수행하세요:

  1. ${GITLAB_WORKSPACES_PROXY_DOMAIN} 및 ${GITLAB_WORKSPACES_WILDCARD_DOMAIN}을 인그레스 컨트롤러에 의해 노출된 로드 밸런서로지 지정하세요.

  2. 터미널에서 다음 명령을 실행하여 gitlab-workspaces-proxy에 접근 가능한지 확인하세요: 

    curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}

    이 명령은 GitLab에서 워크스페이스를 생성할 때까지 400 Bad Request 오류가 반환됩니다.

  3. 다른 터미널에서 다음 명령을 실행하세요: 

    kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy

    로그에 could not find upstream workspace upstream not found 오류가 표시됩니다.

준비가 모두 끝났습니다! 이제 클러스터에서 워크스페이스를 인증하고 권한 부여하기 위해 GitLab 워크스페이스 프록시를 사용할 수 있습니다.