Remote Development Workspaces 기능 작업을 위해 로컬 개발 환경을 설정하십시오. 개발 요구에 따라 두 가지 설정 모드 중에서 선택할 수 있습니다:

• 에이전트 for workspace(agentw):
  • 더 간단한 설정.
  • 직접 에이전트 통신 사용.
  • 대부분의 개발 시나리오에 권장.
• GitLab Workspaces Proxy:
  • 더 복잡한 설정.
  • 워크스페이스 통신을 위한 프록시 사용.
  • 프록시 관련 기능 테스트에 필요.

Kubernetes 설정#

1. Rancher Desktop 1.20.0을 설치합니다.

2. Rancher Desktop에서 Preferences 아이콘을 선택합니다.

3. 가상 머신을 구성합니다:

   • Virtual Machine > Hardware로 이동하여 최소 4 CPU 및 8 GB RAM 값을 설정합니다.

   • macOS만 해당:

     1. Virtual Machine > Emulation으로 이동합니다.
     2. Virtual Machine Type으로 VZ를 선택합니다.
     3. Enable Rosetta support를 선택합니다.

4. Container Engine으로 이동하여 **containerd**를 선택합니다.

5. Kubernetes로 이동합니다:

   1. Kubernetes 버전 v1.33.4를 선택합니다.
   2. Enable Traefik 체크박스를 해제합니다.

GDK 설정#

1. GDK 설치.

2. GDK_ROOT 환경 변수를 설정합니다:

   echo 'export GDK_ROOT="/path/to/your/gdk"' >> ~/.zshrc
   

   /path/to/your/gdk를 실제 GDK 디렉토리 경로로 바꾸십시오.

3. EE 라이선스 설정.

4. 로컬 네트워크 바인딩 문서를 따라 로컬 사설 IP 주소에서 실행하도록 GDK를 구성합니다.

   이 설정에서는 사설 IP 주소가 172.16.123.1이라고 가정합니다. 다른 IP 주소를 사용하는 경우 이후 단계에서 올바른 값으로 대체하십시오.

5. GDK용 NGINX를 구성합니다:

   1. gdk.yml 파일에 이 구성을 추가합니다:

      hostname: gdk.test
      nginx:
        enabled: true
        http:
            enabled: true
      

   2. NGINX를 설치합니다:

      brew install nginx
      

6. 선택 사항. GitLab에서 원하는 브랜치를 체크아웃합니다:

   cd "${GDK_ROOT}/gitlab"
   git checkout my_branch
   

   gdk update를 실행할 때 변경사항이 손실되지 않도록 하려면 gdk.yml에 다음을 추가하십시오:

   gdk:
     auto_rebase_projects: true
   

7. GDK를 재시작합니다:

   cd "${GDK_ROOT}"
   gdk restart
   

GDK에서 GitLab Relay(KAS) 설정#

1. gdk.yml에 이 구성을 추가하여 GDK에서 Kubernetes용 에이전트를 활성화합니다:

   gitlab_k8s_agent:
    enabled: true
    agent_listen_address: gdk.test:8150
    k8s_api_listen_address: gdk.test:8154
   

2. GDK를 재구성하고 재시작합니다:

    cd "${GDK_ROOT}"
    gdk reconfigure
    gdk restart
   

3. 선택 사항. Kubernetes용 에이전트에서 원하는 브랜치를 체크아웃합니다:

         cd "${GDK_ROOT}/gitlab-k8s-agent"
         git checkout my_branch
   

4. 선택 사항. 예를 들어 다른 클론된 디렉토리에서 실행하거나 IDE에서 디버깅하기 위해 kas를 수동으로 실행하려면:

   • 로컬에서 kas 및 agentk 실행을 참조하십시오.

   • JetBrains GoLand IDE에서 디버깅의 경우:

     1. kas "Run Configuration" "Run Kind: Directory"를 설정합니다.
     2. /path/to/cmd/kas를 가리킵니다.
     3. Run after build를 확인합니다.
     4. Bazel에 전달하는 것과 동일한 ENV 변수 및 옵션을 모두 전달합니다.

Kubernetes용 에이전트 설치 확인#

Kubernetes용 에이전트가 제대로 설치되었는지 확인하려면:

1. Apple App Store에서 Xcode를 설치하고 라이선스에 동의합니다:

    sudo xcodebuild -license accept
   

2. 에이전트 리포지토리를 클론합니다:

    git clone https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent
   

3. 설치를 테스트합니다:

    cd gitlab-agent
    make test
   

4. 오류가 발생하면 정리하고 재시도합니다:

    bazel clean --expunge
    make test
   

   [!note] GDK에서 사용하는 /gitlab-k8s-agent에서도 이 작업을 수행해야 할 수 있습니다.

make test가 통과되면 Kubernetes용 에이전트를 사용할 준비가 됩니다.

Workspaces를 위한 Kubernetes용 에이전트(agentk) 설정#

1. 에이전트 구성 파일을 생성합니다:

   1. http://gdk.test:3000/gitlab-org로 이동합니다.
   2. README가 있는 gitlab-agent-configurations라는 이름의 비공개 프로젝트를 생성합니다.
   3. 프로젝트에서 agentk 구성을 포함하는 .gitlab/agents/remotedev/config.yaml 파일을 생성합니다.

   [!note] 이 파일을 생성하거나 변경할 때 4단계에 설명된 agentk를 시작하거나 재시작해야 합니다.

2. GitLab에 agentk를 등록합니다:

   1. gitlab-agent-configurations 프로젝트에서 Operate > Kubernetes clusters로 이동합니다.
   2. Connect a cluster를 선택합니다.
   3. 입력 필드에 remotedev를 입력합니다.
   4. Register를 선택합니다.
   5. 생성된 토큰을 복사하고 저장합니다. AGENT_TOKEN 환경 변수에 필요합니다.

3. 에이전트를 gitlab-org 그룹에 매핑합니다:

   1. http://gdk.test:3000/gitlab-org로 이동합니다.
   2. Settings > Workspaces로 이동합니다.
   3. All agents 탭을 선택합니다.
   4. 목록에서 remotedev를 찾아 Allow를 선택합니다.
   5. 에이전트가 Allowed agents 탭에 나타나는지 확인합니다.

4. 에이전트(agentk)를 시작합니다:

    export AGENT_TOKEN='your_copied_token'
    cd "${GDK_ROOT}/gitlab-k8s-agent"
    echo -n "$AGENT_TOKEN" > "$HOME/.gitlab-agentk-token.txt"
    export POD_NAMESPACE=default
    export POD_NAME=remotedev
    bazel run //cmd/agentk -- --kas-address=grpc://gdk.test:8150 --token-file=$HOME/.gitlab-agentk-token.txt
   

5. 선택 사항. 예를 들어 다른 클론된 디렉토리에서 실행하거나 IDE에서 디버깅하기 위해 agentk를 수동으로 실행하려면:

   • 로컬에서 kas 및 agentk 실행을 참조하십시오.

   • JetBrains GoLand IDE에서 디버깅의 경우:

     1. kas "Run Configuration" "Run Kind: Directory"를 설정합니다.
     2. /path/to/cmd/kas를 가리킵니다.
     3. Run after build를 확인합니다.
     4. Bazel에 전달하는 것과 동일한 ENV 변수 및 옵션을 모두 전달합니다.

Operate > Kubernetes clusters로 이동합니다. 이제 remotedev 에이전트가 Connected로 표시되어야 합니다.

GDK에서 Workspaces 구성#

에이전트 for workspace 모드의 경우#

.gitlab/agents/remotedev/config.yaml 파일에 이 구성을 사용하십시오:

remote_development:
  enabled: true
  network_policy:
    enabled: true
    egress:
    - allow: '0.0.0.0/0'
      except:
      - '10.0.0.0/8'
      - '172.16.0.0/12'
      - '192.168.0.0/16'
    - allow: '172.16.123.1/32'
  gitlab_workspaces_proxy:
    http_enabled: false
    ssh_enabled: false

observability:
  logging:
    level: debug
    grpc_level: warn

GitLab Workspaces Proxy 모드의 경우#

.gitlab/agents/remotedev/config.yaml 파일에 이 구성을 사용하십시오:

remote_development:
  enabled: true
  dns_zone: workspaces.localtest.me
  network_policy:
    enabled: true
    egress:
    - allow: '0.0.0.0/0'
      except:
      - '10.0.0.0/8'
      - '172.16.0.0/12'
      - '192.168.0.0/16'
    - allow: '172.16.123.1/32'

observability:
  logging:
    level: debug
    grpc_level: warn

GitLab Workspaces Proxy 설정(프록시 모드만 해당)#

GitLab Workspaces Proxy 모드를 선택한 경우 다음 추가 단계를 완료하십시오:

1. OAuth 애플리케이션을 생성합니다:

   1. http://gdk.test:3000/admin으로 이동합니다.

   2. Applications으로 이동하여 Add new application을 선택합니다.

   3. 이름을 GitLab Workspaces Proxy로 설정합니다.

   4. 리디렉션 URI를 https://workspaces.localtest.me/auth/callback으로 설정합니다.

   5. 범위를 api, read_user, openid 및 profile로 설정합니다.

   6. 클라이언트 자격 증명을 내보냅니다:

      export CLIENT_ID="your_client_id"
      export CLIENT_SECRET="your_client_secret"
      

2. GDK를 가리키도록 GITLAB_URL을 내보냅니다:

    export GITLAB_URL="http://gdk.test:3000"
   

3. Ingress Controller 및 GitLab Workspaces Proxy를 설정합니다:

    brew install mkcert
    cd "${GDK_ROOT}/gitlab"
    ./scripts/remote_development/workspaces_kubernetes_setup.sh
   

워크스페이스 생성#

1. 선택 사항. 테스트용 devfile을 정의합니다:

   1. 특정 구성을 테스트할 필요가 없는 경우 다음 단계에서 기본 Devfile을 사용하기 위해 이 단계를 건너뛰십시오.

   2. http://gdk.test:3000/gitlab-org/gitlab-shell의 gitlab-org/gitlab-shell 프로젝트로 이동합니다.

   3. .devfile.yaml 파일을 생성합니다:

        schemaVersion: 2.2.0
        components:
          - name: tooling-container
            attributes:
              gl/inject-editor: true
            container:
                image: "registry.gitlab.com/gitlab-org/workspaces/gitlab-workspaces-docs/ubuntu:04@sha256:07590ca30ebde8a5339c3479404953e43ee70e7e9e0c2ede2770684010ddf7fe"
      

      [!note] SHA256은 가져온 컨테이너가 AMD64 아키텍처 컨테이너인지 확인하기 위해 필요합니다. Workspaces를 위한 GitLab VS Code 포크는 아직 다른 아키텍처를 지원하지 않습니다. 이를 추적하려면 이슈 392693을 참조하십시오.

2. 새 워크스페이스를 생성합니다:

   1. http://gdk.test:3000/-/remote_development/workspaces에서 Your Work > Workspaces로 이동합니다.

   2. New Workspace를 선택합니다.

   3. devfile이 있는 프로젝트를 선택합니다(또는 shell을 검색하여 GitLab Shell을 찾습니다).

      [!note] 에이전트 구성이 없다는 오류가 발생하면 agentk 디버그 로그를 확인하여 agentk가 성공적으로 연결되고 에이전트 구성 파일을 읽는지 확인하십시오.

   4. 클러스터 에이전트를 선택합니다.

   5. devfile 단계를 건너뛴 경우 Use GitLab default devfile을 선택합니다.

   6. Create Workspace를 선택합니다.

   7. 워크스페이스가 Running 상태가 될 때까지 기다립니다.

   8. Open Workspace를 선택합니다.

3. 워크스페이스에서 Web IDE를 위한 Extensions Marketplace를 활성화하려면 확장 관리를 참조하십시오.

   [!note] 기본적으로 Workspaces를 위한 GitLab VS Code 포크 서버는 Open VSX Extensions Marketplace를 사용합니다. 이 설정은 워크스페이스 시작 시 product.json 파일에 구성됩니다. 이 파일은 ${GL_EDITOR_VOLUME_DIR}/code-server 디렉토리에 있습니다.

   Extensions Marketplace 구성을 사용자 지정하려면 product.json 파일의 관련 속성은 다음과 같습니다:

   {
       "extensionsGallery": {
           "serviceUrl": "",
           "itemUrl": "",
           "resourceUrlTemplate": ""
       }
   }
   

선택 사항. AI 기능 설정#

워크스페이스에서 AI 기능을 활성화하려면:

1. GDK에 GitLab 팀원 라이선스 설정의 지침을 따르십시오.

   이 페이지에는 로컬 개발을 위한 다른 AI 기능 설정 옵션도 나열되어 있습니다. GitLab Duo Pro 애드온 라이선스가 있는 GitLab Self-Managed Ultimate 구독을 직접 프로비저닝하려면 CustomersDot 접근 방식의 클라우드 라이선스를 따르십시오.

2. 스테이징 AI Gateway(https://cloud.staging.gitlab.com/ai)를 사용하도록 인스턴스를 구성합니다.

워크스페이스의 경우 GitLab Duo Chat 기능을 활성화해야 합니다. GitLab Duo Enterprise 라이선스가 있어야만 사용할 수 있습니다. 스테이징 Customers Portal을 통해 이 라이선스를 직접 프로비저닝할 수 없습니다. GitLab Duo Pro에서 GitLab Duo Enterprise로 구독을 업그레이드하려면 #g_provision Slack 채널에서 요청을 제출하십시오.

올바르게 구성된 경우 Admin > GitLab Duo Pro 설정에서 No health problems detected. 메시지가 표시됩니다.

IDE 설정#

RubyMine#

범위#

다음 범위를 사용합니다:

• 범위에서 코드를 검색합니다.
• Inspect Code(cmd-shift-A -> Inspect Code)를 사용하여 범위에서 정적 분석을 실행합니다.

remote_dev#

file[gitlab]:ee/lib/remote_development//*||file[gitlab]:ee/spec/factories/remote_development//*||file[gitlab]:ee/app/services/remote_development//*||file[gitlab]:app/models/remote_development//*||file[gitlab]:ee/app/graphql/mutations/remote_development//*||file[gitlab]:ee/app/graphql/resolvers/remote_development//*||file[gitlab]:ee/app/graphql/types/remote_development//*||file[gitlab]:ee/app/models/remote_development//*||file[gitlab]:ee/spec/graphql/types/remote_development//*||file[gitlab]:ee/spec/models/remote_development//*||file[gitlab]:ee/spec/services/remote_development//*||file[gitlab]:ee/app/finders/remote_development//*||file[gitlab]:ee/spec/features/remote_development//*||file[gitlab]:ee/spec/support/shared_contexts/remote_development//*||file[gitlab]:ee/app/graphql/ee/types/user_interface.rb||file[gitlab]:ee/app/graphql/resolvers/concerns/remote_development//*||file[gitlab]:ee/app/graphql/resolvers/projects/workspaces_resolver.rb||file[gitlab]:ee/app/graphql/resolvers/users/workspaces_resolver.rb||file[gitlab]:ee/spec/requests/api/graphql/mutations/remote_development//*||file[gitlab]:ee/spec/requests/api/graphql/remote_development//*||file[gitlab]:ee/spec/finders/remote_development//*||file[gitlab]:ee/app/assets/javascripts/remote_development//*||file[gitlab]:ee/spec/frontend/remote_development//*||file[gitlab]:ee/spec/graphql/api/workspace_spec.rb||file[gitlab]:ee/spec/fixtures/remote_development//*||file[gitlab]:ee/spec/lib/remote_development//*

remote_dev services & lib#

이 범위를 다음에 대한 제한된 YARD 검사를 설정하고 안전 경고를 위해 사용하십시오:

• Editor -> Inspections -> YARD -> Missing @param tag in method signature, 범위를 Warning으로 추가
• Editor -> Inspections -> YARD -> Missing @return tag in method, 범위를 Warning으로 추가

file[gitlab]:ee/app/services/remote_development//*||file[gitlab]:ee/lib/remote_development//*

테스트#

테스트 스위트 실행#

커밋 전 "Smoke Test"를 위해 Workspaces 기능과 관련된 사양 하위 집합을 실행하려면 다음 스크립트를 사용하십시오:

scripts/remote_development/run-smoke-test-suite.sh

로컬에서 E2E 사양 실행#

• 새로운 실행 중인 워크스페이스의 생성을 확인하는 엔드투엔드 테스트가 있습니다.
• 테스트는 GDK, KAS 및 agentk를 사용하여 실행 중인 테스트 GitLab 인스턴스에서 UI 작업을 실행하여 작동합니다.

테스트를 실행하려면:

1. 기본 KAS 또는 agentk가 중지된 상태에서 테스트 GitLab 인스턴스가 실행 중인지 확인합니다.

2. Remote Development 코드가 있는 KAS가 실행 중인지 확인합니다.

3. 기본적으로 E2E 테스트는 GDK GitLab 인스턴스의 gitlab-org 그룹 아래에 test-agent 이름의 에이전트가 있다고 가정합니다:

   1. 기본값으로 작업하려면 gitlab-org 그룹의 프로젝트에 test-agent 이름의 에이전트를 생성합니다. gitlab-org 그룹의 gitlab-shell 프로젝트가 이 에이전트를 생성할 위치로 적합합니다.
   2. 또는 사용자 지정 그룹/에이전트를 사용하려면 환경 변수 AGENTK_GROUP 및 AGENTK_NAME으로 그룹 및 에이전트 이름을 재정의합니다.

4. 현재 작업 디렉토리를 {GDK_ROOT}/gitlab로 변경합니다.

5. scripts/remote_development/run-e2e-spec.sh로 테스트를 실행합니다.

   • 기본값을 재정의하려면 AGENTK_GROUP=some-org GITLAB_PASSWORD=example scripts/remote_development/run-e2e-spec.sh를 사용합니다.

   완전한 환경 변수 목록은 scripts/remote_development/run-e2e-spec.sh에 있습니다.

예시 프로젝트로 동작 확인#

GitLab Workspaces를 테스트하려면 예시 프로젝트를 사용하십시오. 이 프로젝트에는 devfile이 포함되어 있으며 즉시 사용할 수 있습니다.

1. 예시 프로젝트를 개발 머신에 클론하고 gitlab-org 그룹 아래의 로컬 GitLab 설치에 공개 프로젝트로 푸시합니다.
2. 프로젝트는 워크스페이스를 생성할 때 프로젝트 목록에 나타납니다.
3. 특정 사용 지침은 각 프로젝트의 README 파일을 따르십시오.

리포지토리#

다음 리포지토리들은 Workspaces 개발에 사용됩니다:

다음 종속성들은 Workspaces가 의존하는 외부 리포지토리입니다:

디버깅#

디버깅을 위한 IDE 설정#

Ruby Mine에서 디버깅 팁은 GDK에서 실행 중인 GitLab에 RubyMine 디버거 사용을 참조하십시오.

KAS 및 agentk 디버깅도 GoLand에서 작동합니다. Run Configurations를 설정하는 데 도움이 필요하면 개발자 또는 엔지니어 중 한 명에게 문의하십시오.

Rails#

log/remote_development.log#

log/remote_development.log에는 JSON 형식의 특정 원격 개발 로그가 포함됩니다. jq를 설치해야 할 수 있습니다.

tail -f log/remote_development.log | jq

log/development.log#

log/remote_development.log에 없는 다른 세부 정보 또는 예외의 경우 표준 Rails log/development.log를 참조하십시오:

tail -f log/development.log

Rails에서 고아 워크스페이스 삭제#

Rails에서 고아 워크스페이스 레코드가 있거나 완전히 초기화하고 싶을 수 있습니다. 이를 위해:

1. GDK의 gitlab 리포지토리로 이동합니다.

2. Rails 콘솔을 엽니다:

   bin/rails c
   

3. 모든 워크스페이스 레코드를 삭제합니다:

   RemoteDevelopment::Workspace.delete_all
   

Kubernetes#

컨텍스트 및 네임스페이스 관리#

리소스 검사#

로그 및 디버깅#

파드에서 로그 가져오기:

kubectl -n NAMESPACE logs -f POD_NAME

특정 컨테이너에서 로그 가져오기:

kubectl -n NAMESPACE logs -f POD_NAME -c CONTAINER_NAME

워크스페이스 관련 명령#

모든 워크스페이스 개체 가져오기:

kubectl get serviceaccount,pvc,networkpolicy,resourcequota,deployment,service,secret,configmap -l "agent.gitlab.com/id"

gitlab-workspaces-proxy-config 시크릿 가져오기:

kubectl -n gitlab-workspaces get secret gitlab-workspaces-proxy-config -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}'

워크스페이스 기본 컨테이너 셸 진입:

PODNAME=$(kubectl get po -o name | cut -d/ -f2) && CONTAINER_NAME=$(kubectl get pod $PODNAME -o jsonpath='{range .spec.containers[*]}{"\t"}{range .env[*]}{","}{end}{"\n"}{end}' | grep GL_TOOLS_DIR | cut -f 1) && kubectl exec $PODNAME -c $CONTAINER_NAME -it -- /bin/bash

워크스페이스 컨테이너에서 명령 실행(로그 추적 예시):

PODNAME=$(kubectl get po -o name | cut -d/ -f2) && CONTAINER_NAME=$(kubectl get pod $PODNAME -o jsonpath='{range .spec.containers[*]}{"\t"}{range .env[*]}{","}{end}{"\n"}{end}' | grep GL_TOOLS_DIR | cut -f 1) && kubectl exec $PODNAME -c $CONTAINER_NAME -it -- /bin/bash -c "tail -n 100 -f /tmp/*.log"

정리 작업#

네임스페이스 삭제:

kubectl delete namespace NAMESPACE

파드 삭제:

kubectl -n NAMESPACE delete pods POD_NAME

모든 워크스페이스 네임스페이스 삭제:

kubectl get namespace | grep gl- | cut -f1 -d" " | xargs -I {} kubectl delete namespace {}

추가 리소스#

GitLab Workspaces Proxy를 사용할 때 localhost 트래픽이 Kubernetes에 도달하는 방법에 대한 정보는 이 댓글을 참조하십시오.