%%{init: {  "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Hierarchy structure for GitLab workspaces
    accDescr: Workspace projects inherit agent access through the group hierarchy with agents connected to separate agent projects.
topGroup[Top-level group]
subGroup[Subgroup]
workspaceProject[Workspace project]
agentProject[Agent project]
workspaceAgent[Workspace agent]

topGroup --> subGroup

subGroup --> workspaceProject
subGroup --> agentProject
agentProject -.- workspaceAgent

class workspaceProject active;</code></pre></details></div>

Ingress 컨트롤러 설치#
외부 트래픽을 워크스페이스로 라우팅하려면 Kubernetes 클러스터에 원하는 Ingress 컨트롤러를 설치합니다. Ingress 컨트롤러는 WebSocket을 지원해야 합니다. 다음 예시에서는 Ingress NGINX 컨트롤러를 사용합니다.


Kubernetes 클러스터에 Ingress 컨트롤러를 설치합니다.
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace gitlab-ingress-controller \
  --create-namespace



로드 밸런서의 외부 IP 주소를 확인합니다. 이 주소는
DNS 레코드를 업데이트할 때 필요합니다.
kubectl get svc -n gitlab-ingress-controller ingress-nginx-controller



Kubernetes용 GitLab 에이전트 설치#
클러스터를 GitLab에 연결하려면 Kubernetes 클러스터에 Kubernetes용 GitLab 에이전트를
설치합니다.

Kubernetes용 에이전트 설치의 설치 방법 중 하나를 완료합니다.
구성한 agentName을 기록해 둡니다. 워크스페이스용 에이전트를 구성할 때 필요합니다.

GitLab Relay (KAS) 설치#
GitLab Relay(KAS)는 클러스터의 에이전트와 통신하는 컴포넌트입니다.

GitLab.com에서는 GitLab Relay(KAS)를 기본적으로 grpcs://kas.gitlab.com에서 사용할 수 있습니다.
GitLab Self-Managed에서는 관리자가
GitLab Relay(KAS)를 설정해야 합니다.
설정하면 grpcs://gitlab.example.com에서 사용할 수 있으며, HTTPS가 없거나 상대 URL 루트를 사용하는 인스턴스에서는 wss://gitlab.example.com/-/kubernetes-agent/에서 사용할 수 있습니다.

Kubernetes용 GitLab 에이전트 구성#
에이전트 프로젝트에서 remote_development 모듈을 구성하려면 다음을 수행합니다.


상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.


프로젝트에 .gitlab/agents/<agentName>/config.yaml 파일을 만듭니다.
agentName은 워크스페이스 인프라를 설정할 때 구성한 에이전트의 이름입니다.


config.yaml에서 워크스페이스 설정에 다음 구성을 사용합니다.
remote_development:
  enabled: true
  dns_zone: "<workspaces.example.dev>" # DNS zone of the URL where workspaces are available



전체 구성 옵션 목록은 워크스페이스 구성 참조를 참고합니다.
Note
Kubernetes용 GitLab 에이전트는 한 프로젝트에서 구성하지만 다른 프로젝트의 워크스페이스에서도 사용할 수 있습니다.
프로젝트마다 별도의 에이전트를 둘 필요는 없습니다.
구성한 에이전트는
그룹에서 에이전트를 허용하기 전까지 표시되지 않습니다.

그룹에서 Kubernetes용 GitLab 에이전트 허용#
그룹에서 에이전트를 허용하면 해당 그룹과 하위 그룹, 그리고 그 그룹들에 속한 모든 프로젝트에서
그 에이전트를 사용할 수 있습니다.
Note
에이전트는 하나만 있으면 됩니다. 같은 에이전트로 그룹의 모든 프로젝트에서 워크스페이스를 만들 수 있습니다.

그룹에서 Kubernetes용 GitLab 에이전트를 허용해 그룹의 모든 프로젝트에서 사용하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
왼쪽 사이드바에서 Settings > Workspaces를 선택합니다.
Group agents 섹션에서 All agents 탭을 선택합니다.
Kubernetes용 GitLab 에이전트에 대해 Allow를 선택합니다.
확인 대화 상자에서 Allow agent를 선택합니다.

워크스페이스 권한 부여#
워크스페이스 프로젝트와 에이전트 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있는
사용자에게 워크스페이스를 만들고 관리하는 데 필요한 권한을 부여합니다. 다음 방법을 사용할 수 있습니다.

프로젝트에 사용자 추가
그룹에 사용자 추가

TLS 인증서 생성#
워크스페이스마다 자체 하위 도메인을 사용하므로 워크스페이스 접근에는 와일드카드 도메인이 필요합니다.
다음 대상에 대해 TLS 인증서를 생성해야 합니다.

gitlab-workspaces-proxy가 수신 대기하는 도메인(GITLAB_WORKSPACES_PROXY_DOMAIN)
워크스페이스를 사용할 수 있는 와일드카드 도메인(GITLAB_WORKSPACES_WILDCARD_DOMAIN)

예를 들어 기본 도메인이 workspaces.example.dev 라면 다음과 같습니다.

GITLAB_WORKSPACES_PROXY_DOMAIN은 workspaces.example.dev 입니다.
GITLAB_WORKSPACES_WILDCARD_DOMAIN은 *.workspaces.example.dev 입니다.
개별 워크스페이스는 workspace-1.workspaces.example.dev와 같은 URL에서 사용할 수 있습니다.

인증서는 어떤 인증 기관에서든 생성할 수 있습니다.
Kubernetes 클러스터에 cert-manager가 구성되어 있으면
이를 사용해 TLS 인증서를 자동으로 만들고 갱신할 수 있습니다.
인증서를 직접 생성하려면 다음을 수행합니다.


HTTPS를 사용할 수 있도록 Certbot을 설치합니다.
brew install certbot



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



출력에 표시된 인증서 디렉터리로 다음 환경 변수를 설정합니다.
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"

환경에 따라 certbot 명령이 인증서와 키를 다른 경로에 저장할 수 있습니다.
정확한 경로를 확인하려면 다음 명령을 실행합니다.
certbot certificates \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work



Note
인증서가 만료되면 갱신해야 합니다.
예를 들어 Let's Encrypt 인증서는 3개월 뒤에 만료됩니다.
인증서를 자동으로 갱신하려면 cert-manager를 참고합니다.

GitLab OAuth 애플리케이션 등록#
GitLab 인스턴스에 OAuth 애플리케이션을 등록하려면 다음을 수행합니다.


GitLab에서 OAuth 애플리케이션을 만듭니다. 다음 중 하나를 만들 수 있습니다.

사용자 소유 애플리케이션
그룹 소유 애플리케이션
Admin 영역에서 만드는 인스턴스 전체 애플리케이션



리디렉션 URI를 https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback으로 설정합니다.


Confidential 체크박스가 선택되어 있는지 확인합니다. 기본적으로 선택되어 있습니다.


인스턴스 전체 애플리케이션을 만드는 경우 Trusted 체크박스도 선택합니다.


스코프를 api, read_user, openid, profile로 설정합니다.


구성 값을 내보냅니다.
export GITLAB_URL="https://gitlab.com"
export CLIENT_ID="your_application_id"
export CLIENT_SECRET="your_application_secret"
export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"



클라이언트 ID와 생성된 시크릿을 1Password 등 안전한 곳에 보관합니다.


SSH 호스트 키 생성#
RSA 키를 생성하려면 다음 명령을 실행합니다.
ssh-keygen -f ssh-host-key -N '' -t rsa
export SSH_HOST_KEY=$(pwd)/ssh-host-key

대신 ECDSA 키를 생성할 수도 있습니다.
Kubernetes 시크릿 생성#
Kubernetes 시크릿을 생성하려면 다음 명령을 실행합니다.
kubectl create namespace gitlab-workspaces

kubectl create secret generic gitlab-workspaces-proxy-config \
  --namespace="gitlab-workspaces" \
  --from-literal="auth.client_id=${CLIENT_ID}" \
  --from-literal="auth.client_secret=${CLIENT_SECRET}" \
  --from-literal="auth.host=${GITLAB_URL}" \
  --from-literal="auth.redirect_uri=${REDIRECT_URI}" \
  --from-literal="auth.signing_key=${SIGNING_KEY}" \
  --from-literal="ssh.host_key=$(cat ${SSH_HOST_KEY})"

kubectl create secret tls gitlab-workspace-proxy-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WORKSPACES_DOMAIN_CERT}" \
  --key="${WORKSPACES_DOMAIN_KEY}"

kubectl create secret tls gitlab-workspace-proxy-wildcard-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WILDCARD_DOMAIN_CERT}" \
  --key="${WILDCARD_DOMAIN_KEY}"

GitLab 워크스페이스 프록시 Helm 차트 설치#
GitLab 워크스페이스 프록시용 Helm 차트를 설치하려면 다음을 수행합니다.


helm 리포지터리를 추가합니다.
helm repo add gitlab-workspaces-proxy \
  https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel

Helm 차트 0.1.13 이하에서는 다음 명령을 사용합니다.
helm repo add gitlab-workspaces-proxy \
  https://gitlab.com/api/v4/projects/gitlab-org%2fremote-development%2fgitlab-workspaces-proxy/packages/helm/devel



차트를 설치하고 업그레이드합니다.

[!warning]
차트 버전 0.1.22 이하에는 명령줄 인수를 통해 민감한 정보가 노출되는 보안
취약점이 있습니다. 자세한 내용은
해당 취약점을 참고합니다.
차트 버전 0.1.20 이하에는 와일드카드 도메인에 쿠키를 설정하는 보안 취약점도
있습니다. 자세한 내용은
취약점 수정 내역을 참고합니다.
두 취약점을 모두 해결하려면 차트 버전 0.1.23 이상으로 업그레이드해야 합니다.
차트 버전 0.1.16 이전에는 Helm 차트를 설치할 때 시크릿이 자동으로 생성되었습니다.
0.1.16 이전 버전에서 업그레이드하는 경우에는 업그레이드 명령을 실행하기 전에
필요한 Kubernetes 시크릿을 생성합니다.

helm repo update

helm upgrade --install gitlab-workspaces-proxy \
  gitlab-workspaces-proxy/gitlab-workspaces-proxy \
  --version=0.1.25 \
  --namespace="gitlab-workspaces" \
  --set="ingress.enabled=true" \
  --set="ingress.hosts[0].host=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  --set="ingress.hosts[0].paths[0].path=/" \
  --set="ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
  --set="ingress.hosts[1].host=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  --set="ingress.hosts[1].paths[0].path=/" \
  --set="ingress.hosts[1].paths[0].pathType=ImplementationSpecific" \
  --set="ingress.tls[0].hosts[0]=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
  --set="ingress.tls[0].secretName=gitlab-workspace-proxy-tls" \
  --set="ingress.tls[1].hosts[0]=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
  --set="ingress.tls[1].secretName=gitlab-workspace-proxy-wildcard-tls" \
  --set="ingress.className=nginx"

다른 Ingress 클래스를 사용한다면 ingress.className 파라미터를 수정합니다.


설정 확인#


gitlab-workspaces 네임스페이스의 Ingress 구성을 확인합니다.
kubectl -n gitlab-workspaces get ingress



Pod가 실행 중인지 확인합니다.
kubectl -n gitlab-workspaces get pods



DNS 레코드 업데이트#
DNS 레코드를 업데이트하려면 다음을 수행합니다.


${GITLAB_WORKSPACES_PROXY_DOMAIN}과 ${GITLAB_WORKSPACES_WILDCARD_DOMAIN} 이
Ingress 컨트롤러가 노출한 로드 밸런서 외부 IP 주소를 가리키도록 설정합니다.


gitlab-workspaces-proxy에 접근할 수 있는지 확인합니다.
curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}

이 명령은 워크스페이스를 만들기 전까지 400 Bad Request 오류를 반환합니다.


다른 터미널에서 프록시 로그를 확인합니다.
kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy

이 명령은 워크스페이스를 만들기 전까지 could not find upstream workspace upstream not found 오류를 반환합니다.


Kubernetes용 GitLab 에이전트 구성 업데이트#
프록시용 Helm 차트를 gitlab-workspaces가 아닌 다른 네임스페이스에 배포한다면
Kubernetes용 GitLab 에이전트 구성을 업데이트합니다.
remote_development:
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

관련 주제#

워크스페이스 구성
Kubernetes용 GitLab 에이전트 구성