%%{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)는 기본적으로 wss://kas.gitlab.com에서 사용할 수 있습니다.
GitLab Self-Managed에서 관리자는 GitLab Relay (KAS) 설정을 해야 합니다.
그 후 wss://gitlab.example.com/-/kubernetes-agent/에서 사용할 수 있습니다.

Kubernetes용 GitLab 에이전트 구성#
에이전트 프로젝트에서 remote_development 모듈을 구성하려면:


상단 메뉴에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.


프로젝트에서 .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 에이전트를 허용하고 해당 그룹의 모든 프로젝트에서 사용 가능하게 하려면:

상단 메뉴에서 검색 또는 이동을 선택하여 그룹을 찾습니다.
설정 > 워크스페이스를 선택합니다.
그룹 에이전트 섹션에서 모든 에이전트 탭을 선택합니다.
Kubernetes용 GitLab 에이전트에 대해 허용을 선택합니다.
확인 대화 상자에서 에이전트 허용을 선택합니다.

워크스페이스 권한 부여#
워크스페이스 및 에이전트 프로젝트에 대해 개발자, 유지 관리자 또는 소유자 역할을 가진 사용자에게 워크스페이스를 생성하고 관리하는 데 필요한 권한을 부여합니다. 다음을 할 수 있습니다:

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

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 애플리케이션을 생성합니다. 다음을 만들 수 있습니다:

사용자 소유 애플리케이션
그룹 소유 애플리케이션
관리자 영역의 인스턴스 전체 애플리케이션



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


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


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


범위를 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



파드가 실행 중인지 확인합니다:
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 에이전트 구성 업데이트#
gitlab-workspaces가 아닌 다른 네임스페이스에 프록시용 Helm 차트를 배포하는 경우 Kubernetes용 GitLab 에이전트 구성을 업데이트합니다:
remote_development:
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

관련 주제#

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