InfoGrab Docs

워크스페이스 트러블슈팅

요약

GitLab 워크스페이스를 사용할 때 다음 문제가 발생할 수 있습니다. 워크스페이스를 생성할 때 에이전트 로그에서 다음 오류 메시지가 발생할 수 있습니다: 이 오류는 Kubernetes용 GitLab 에이전트의 알려진 문제입니다.

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}

이 오류는 Kubernetes용 GitLab 에이전트의 알려진 문제입니다. 이 오류는 에이전트 인스턴스가 리더십 리스를 갱신할 수 없어 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

Kubernetes용 GitLab 에이전트에 대해 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 GitLab Kubernetes Agent Server address#

이 오류는 Kubernetes Agent Server (KAS) 주소에 필수 프로토콜 스킴이 없을 때 발생합니다.

이 문제를 해결하려면:

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

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

오프라인 환경에서 워크스페이스를 생성할 때 이 오류가 발생할 수 있습니다:

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

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

Warning

다음 해결 방법은 지원되지 않으며 임시입니다. 지원되는 솔루션이 제공될 때까지 이슈 509983 위험을 감수하고 사용하세요.

해결 방법:

  1. init 컨테이너 이미지 참조를 수정하기 위해 Kubernetes 변이 웹훅을 배포합니다.
  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. 로그 파일을 봅니다:

    # 실시간으로 postStart 실행 출력 모니터링
tail -f poststart-stdout.log

# postStart 오류 확인
cat poststart-stderr.log

# VS Code 서버 시작 확인
cat start-vscode.log

  4. 오류를 확인합니다:

    # 모든 로그에서 오류 메시지 검색
grep -i error *.log

# 특정 명령 출력 검색
grep "your-command-name" poststart-stdout.log

  5. 식별된 문제를 해결하고 워크스페이스를 재시작합니다.

자세한 내용은 워크스페이스 로그 디렉토리 및 사용 가능한 로그 파일을 참조하세요.

워크스페이스 트러블슈팅

원문 보기
요약

GitLab 워크스페이스를 사용할 때 다음 문제가 발생할 수 있습니다. 워크스페이스를 생성할 때 에이전트 로그에서 다음 오류 메시지가 발생할 수 있습니다: 이 오류는 Kubernetes용 GitLab 에이전트의 알려진 문제입니다.

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}

이 오류는 Kubernetes용 GitLab 에이전트의 알려진 문제입니다. 이 오류는 에이전트 인스턴스가 리더십 리스를 갱신할 수 없어 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

Kubernetes용 GitLab 에이전트에 대해 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 GitLab Kubernetes Agent Server address#

이 오류는 Kubernetes Agent Server (KAS) 주소에 필수 프로토콜 스킴이 없을 때 발생합니다.

이 문제를 해결하려면:

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

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

오프라인 환경에서 워크스페이스를 생성할 때 이 오류가 발생할 수 있습니다:

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

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

Warning

다음 해결 방법은 지원되지 않으며 임시입니다. 지원되는 솔루션이 제공될 때까지 이슈 509983 위험을 감수하고 사용하세요.

해결 방법:

  1. init 컨테이너 이미지 참조를 수정하기 위해 Kubernetes 변이 웹훅을 배포합니다.
  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. 로그 파일을 봅니다:

    # 실시간으로 postStart 실행 출력 모니터링
tail -f poststart-stdout.log

# postStart 오류 확인
cat poststart-stderr.log

# VS Code 서버 시작 확인
cat start-vscode.log

  4. 오류를 확인합니다:

    # 모든 로그에서 오류 메시지 검색
grep -i error *.log

# 특정 명령 출력 검색
grep "your-command-name" poststart-stdout.log

  5. 식별된 문제를 해결하고 워크스페이스를 재시작합니다.

자세한 내용은 워크스페이스 로그 디렉토리 및 사용 가능한 로그 파일을 참조하세요.