GitLab 워크스페이스를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

오류: Failed to renew lease#

워크스페이스를 생성할 때 에이전트 로그에서 다음 오류 메시지가 나타날 수 있습니다.

{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX}

이 오류는 GitLab agent for Kubernetes의 알려진 이슈 때문에 발생합니다. 에이전트 인스턴스가 리더십 임대를 갱신하지 못해 remote_development 같은 리더 전용 모듈이 종료될 때 이 오류가 발생합니다.

이 문제를 해결하려면 다음 절차를 따릅니다.

1. 에이전트 인스턴스를 다시 시작합니다.
2. 문제가 계속되면 Kubernetes 클러스터의 상태와 연결을 확인합니다.

오류: Workspace create failed: Expiration date must be before <date>#

워크스페이스를 생성할 때 UI에서 다음 오류가 나타날 수 있습니다.

Workspace create failed: Expiration date must be before <date>

이 오류는 새로 생성한 워크스페이스에 대한 인증용으로 생성된 개인 액세스 토큰의 만료 날짜가 인스턴스의 토큰 만료 설정을 초과할 때 발생합니다.

이 문제를 해결하려면 인스턴스의 액세스 토큰 수명 제한을 비활성화합니다. 이슈 579331에서는 이 제약을 해소하기 위해 워크스페이스 관련 토큰에 설정 가능한 한도를 두는 방안을 제안하고 있습니다.

오류: No agents available to create workspaces#

프로젝트에서 워크스페이스를 생성할 때 다음 오류가 발생할 수 있습니다.

No agents available to create workspaces. Please consult Workspaces documentation for troubleshooting.

이 오류는 여러 원인으로 발생할 수 있습니다. 다음 문제 해결 단계를 차례로 수행합니다.

권한 확인#

1. 워크스페이스 프로젝트와 에이전트 프로젝트 모두에 Developer, Maintainer 또는 Owner 권한이 있는지 확인합니다.
2. 워크스페이스 프로젝트의 상위 그룹에서 에이전트가 허용되어 있는지 확인합니다.

자세한 내용은 에이전트 허용을 참고합니다.

에이전트 구성 확인#

에이전트 구성에서 remote_development 모듈이 활성화되어 있는지 확인합니다.

remote_development:
  enabled: true

GitLab agent for Kubernetes에서 remote_development 모듈이 비활성화되어 있으면 enabled를 true로 설정합니다.

에이전트 이름 불일치 확인#

Kubernetes용 GitLab 에이전트 토큰 생성 단계에서 만든 에이전트 이름이 .gitlab/agents/FOLDER_NAME/의 폴더 이름과 일치하는지 확인합니다.

이름이 다르면 폴더 이름을 에이전트 이름과 정확히 일치하도록 변경합니다.

에이전트 연결 상태 확인#

에이전트가 GitLab에 연결되어 있는지 확인합니다.

1. 그룹으로 이동합니다.

2. Operate > Kubernetes clusters를 선택합니다.

3. Connection status가 Connected 인지 확인합니다. 연결되어 있지 않으면 에이전트 로그를 확인합니다.

   kubectl logs -f -l app=gitlab-agent -n gitlab-workspaces
   

오류: unsupported scheme in kas address#

이 오류는 GitLab Relay(KAS) 주소에 필요한 프로토콜 스킴이 빠져 있을 때 발생합니다.

이 문제를 해결하려면 다음 절차를 따릅니다.

1. TF_VAR_kas_address 변수에 grpcs:// 또는 wss:// 접두사를 추가합니다. 예: grpcs://kas.gitlab.com.
2. 구성을 업데이트하고 에이전트를 다시 배포합니다.

오류: 오프라인 환경에서 워크스페이스 시작 시 ImagePullBackOff#

오프라인 환경에서 워크스페이스를 생성하면 다음 오류가 나타날 수 있습니다.

workspace-example-abc123-def456   0/1   Init:ImagePullBackOff   0

이 오류는 워크스페이스가 registry.gitlab.com에서 init 컨테이너 이미지를 가져오지 못할 때 발생합니다. 오프라인 환경에서는 init 컨테이너 이미지가 하드코딩되어 있어 devfile에서 재정의할 수 없습니다.

해결 방법은 다음과 같습니다.

1. init 컨테이너 이미지 참조를 수정하도록 Kubernetes mutating webhook을 배포합니다.
2. MutatingWebhookConfiguration을 생성, 업데이트 또는 삭제할 수 있는 클러스터 관리자 권한이 있는지 확인합니다.

구현 예시는 A Simple Kubernetes Admission Webhook을 참고합니다.

오류: redirect URI included is not valid#

워크스페이스에 접근할 때 유효하지 않은 리디렉션 URI에 관한 OAuth 오류가 발생할 수 있습니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

• OAuth 애플리케이션이 올바르게 구성되지 않았습니다. 이 문제를 해결하려면 다음 절차를 따릅니다.
  1. GitLab의 OAuth 애플리케이션 리디렉션 URI가 사용 중인 도메인과 일치하는지 확인합니다.
  2. OAuth 애플리케이션 리디렉션 URI를 업데이트합니다. 예: https://YOUR_DOMAIN/auth/callback.
• 워크스페이스 프록시가 오래된 OAuth 자격 증명을 사용하고 있습니다. 이 문제를 해결하려면 다음 절차를 따릅니다.

  1. 프록시가 최신 OAuth 자격 증명을 사용하는지 확인합니다.

  2. 워크스페이스 프록시를 다시 시작합니다.

     kubectl rollout restart deployment -n gitlab-workspaces gitlab-workspaces-proxy
     

오류: Workspace does not exist#

VS Code에서 다음과 같은 오류가 나타날 수 있습니다.

Workspace does not exist

Please select another workspace to open.

이 문제는 워크스페이스는 정상적으로 시작됐지만 Git clone 작업이 실패해 예상한 프로젝트 디렉터리가 없을 때 발생합니다. Git clone 작업은 네트워크 문제, 인프라 문제 또는 회수된 리포지터리 권한 때문에 실패합니다.

이 문제를 해결하려면 다음 절차를 따릅니다.

1. 오류 대화 상자에서 다른 워크스페이스를 선택하라는 안내가 나오면 Cancel을 선택합니다.

2. VS Code 메뉴에서 File > Open Folder를 선택합니다.

3. /projects 디렉터리로 이동한 뒤 OK를 선택합니다.

4. EXPLORER 패널에서 프로젝트와 이름이 같은 디렉터리가 있는지 확인합니다.

   • 디렉터리가 없으면 Git clone 작업이 완전히 실패한 것입니다.
   • 디렉터리가 있지만 비어 있으면 clone 작업이 시작됐으나 완료되지 않은 것입니다.

5. 터미널을 엽니다. 메뉴에서 Terminal > New Terminal을 선택합니다.

6. 워크스페이스 로그 디렉터리로 이동합니다.

   cd /tmp/workspace-logs/
   

7. Git clone이 실패한 원인을 알려 줄 수 있는 오류 출력이 있는지 로그에서 확인합니다.

   less poststart-stderr.log
   

8. 확인된 문제를 해결한 뒤 워크스페이스를 다시 시작합니다.

문제가 계속되면 Git이 포함된 정상 동작 컨테이너 이미지로 새 워크스페이스를 생성합니다.

postStart 이벤트 디버그#

사용자 지정 postStart 이벤트가 실패하거나 예상대로 동작하지 않으면 워크스페이스 로그 디렉터리를 사용해 문제를 디버그할 수 있습니다.

일반적인 postStart 디버그 시나리오와 해결 방법은 다음과 같습니다.

• Command not found: 컨테이너 이미지에 의존성이 빠져 있음을 나타내는 오류가 있는지 poststart-stderr.log에서 확인합니다.
• Permission denied: 파일 권한이나 사용자 구성 조정이 필요할 수 있는 권한 오류가 있는지 poststart-stderr.log에서 확인합니다.
• Network issues: postStart 이벤트가 의존성을 내려받거나 외부 리소스에 접근할 때 연결 시간 초과나 DNS 확인 실패가 있는지 확인합니다.
• Long-running commands: postStart 이벤트가 멈춘 것으로 보이면 poststart-stdout.log에서 명령이 아직 실행 중인지 또는 정상적으로 완료됐는지 확인합니다.

postStart 명령 실행 로그를 확인하려면 다음 절차를 따릅니다.

1. 워크스페이스에서 터미널을 엽니다.

2. 워크스페이스 로그 디렉터리로 이동합니다.

   cd /tmp/workspace-logs/
   

3. 로그 파일을 확인합니다.

   # Monitor postStart execution output in real-time
   tail -f poststart-stdout.log
   
   # Check postStart errors
   cat poststart-stderr.log
   
   # Check VS Code server startup
   cat start-vscode.log
   

4. 오류가 있는지 확인합니다.

   # Search for error messages across all logs
   grep -i error *.log
   
   # Search for specific command output
   grep "your-command-name" poststart-stdout.log
   

5. 확인된 문제를 해결한 뒤 워크스페이스를 다시 시작합니다.

자세한 내용은 워크스페이스 로그 디렉터리와 사용 가능한 로그 파일을 참고합니다.