Cloud 스케줄러 문제 해결

이 페이지에서는 Cloud Scheduler 문제를 해결하는 방법을 보여줍니다.

Cloud Scheduler는 각 작업 실행 시작 시와 종료 시 로그를 게시합니다. Cloud Scheduler에서 사용할 수 있는 감사 로그를 비롯해 특정 작업의 로그를 검색, 확인, 분석할 수 있습니다. 자세한 내용은 로그 보기를 참고하세요.

기본적으로 Cloud Scheduler 작업이 타겟 서비스(작업 요청 핸들러)로부터 확인을 수신하지 않으면 작업이 실패한 것으로 간주됩니다. Cloud Scheduler는 구성한 지수 백오프에 따라 작업을 재시도합니다.

Google Cloud 서비스에 영향을 미치는 사고에 대한 자세한 내용은 Google Cloud Service Health 대시보드 및 Cloud Scheduler에 대해 보고된 모든 사고를 참고하세요.

다운스트림 서비스 문제로 인해 작업이 실패함

작업 실패는 Cloud Scheduler 자체가 아닌 Cloud Scheduler가 타겟팅하는 다운스트림 서비스(예: Cloud Run)의 문제로 인해 발생할 수 있습니다. 다음 조건이 적용되는 경우 다운스트림 서비스 문제를 의심할 수 있습니다.

  • Cloud Scheduler 권한이 올바르게 설정되어 있습니다.
  • Cloud Scheduler가 타겟 서비스에 도달할 수 있습니다.
  • Cloud Scheduler 실행 로그의 오류 메시지는 다운스트림 서비스에서 발생합니다.

이 문제를 해결하려면 다음 단계를 완료하시기 바랍니다.

  1. 다운스트림 서비스를 직접 호출: Cloud Scheduler 없이 다운스트림 서비스를 성공적으로 호출할 수 있는지 확인합니다. 호출이 성공하면 Cloud Scheduler가 문제를 일으키는 것일 수 있습니다. 호출이 실패하면 다운스트림 서비스의 추가 디버깅이 필요합니다.
  2. 대상 서비스 로그 검사: 대상 서비스의 로그를 검사하고 출력되는 오류를 확인한 후 그에 따라 분류합니다.
  3. 장기 실행 작업 확인: Cloud Scheduler가 장기 실행 작업 (30분 초과)에 대해 HTTP 504 오류를 반환하는 경우 대상 서비스에 더 긴 요청 타임아웃이 있을 수 있으므로 대상 서비스 로그에서 실행이 성공했는지 실패했는지 확인합니다. 이러한 시나리오에서는 Cloud Scheduler가 시간 초과되지만 대상 서비스는 시간 초과되지 않습니다.

권한 오류로 인해 작업이 실패함

권한은 리소스에 액세스할 수 있는 주 구성원과 허용되는 작업을 제어합니다. 잘못 구성된 권한은 작업 실행을 방해하고 권한 거부 오류를 발생시킬 수 있습니다. 감사 로그는 모든 권한 변경사항에 대한 자세한 기록을 제공하므로 이러한 문제의 소스를 식별할 수 있습니다.

권한 오류로 인해 Cloud Scheduler 작업이 실패하면 실행 로그에 "debugInfo":"URL_ERROR-ERROR_OTHER. Original HTTP response code number = 403"와 같은 메시지가 표시될 수 있습니다.

이 문제를 해결하려면 다음 확인 중 하나 이상을 완료하세요.

  • 서비스 에이전트에 부여된 IAM 역할 확인: Cloud Scheduler 서비스 에이전트에는 Cloud Scheduler 서비스 에이전트(roles/cloudscheduler.serviceAgent) 역할이 필요합니다. 이 역할이 없으면 Cloud Scheduler 작업이 실패합니다. Cloud Scheduler 서비스 에이전트에 역할을 수동으로 부여할 수 있습니다. 수동 부여는 2019년 3월 19일 이전에 Cloud Scheduler API를 사용 설정한 경우 또는 Cloud Scheduler 서비스 에이전트 역할을 삭제한 경우에만 필요합니다. 자세한 내용은 Cloud Scheduler 서비스 에이전트 역할 부여를 참고하세요.

  • 서비스 계정 권한 확인: 작업에 연결된 서비스 계정에 대상 서비스를 호출할 수 있는 올바른 권한과 범위가 있는지 확인합니다. 여기에는 타겟이 다른 프로젝트에 있거나 중개 서비스의 최종 타겟인 시나리오가 포함됩니다. 타겟이 Google Cloud내에 있는 경우 서비스 계정에 필요한 역할을 부여했는지 확인합니다. Google Cloud 내 각 서비스에는 특정 역할이 필요하며 수신 서비스는 생성된 토큰을 자동으로 확인합니다. 예를 들어 Cloud Run 및 Cloud Run 함수의 경우 Cloud Run Invoker 역할을 부여해야 합니다. Google Cloud외부에 대상이 있는 경우 수신 서비스가 수동으로 토큰을 확인해야 합니다. 자세한 내용은 Cloud Scheduler에 인증 및 HTTP 대상에 인증 사용을 참고하세요.

  • VPC 서비스 제어 위반사항 확인: VPC 서비스 제어는 데이터 무단 반출을 방지하기 위해 보안 경계를 설정할 수 있는 Google Cloud기능입니다. 오류가 VPC 서비스 제어와 관련되었는지 파악하려면 VPC 서비스 제어를 사용 설정한 후 사용하려는 프로젝트 및 서비스에 적용했는지 확인하세요. 프로젝트 및 서비스가 VPC 서비스 제어로 보호되는지 확인하려면 해당 리소스 계층 구조 수준에서 VPC 서비스 제어 정책을 확인합니다.

    문제의 범위를 파악하려면 감사 로그에서 VPC 서비스 제어 오류를 검색하세요.

    1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

      로그 탐색기로 이동

      검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

    2. 다음 기준에 따라 감사 로그를 쿼리합니다.

      severity="ERROR" AND protoPayload.status.details.violations.type="VPC_SERVICE_CONTROLS"

      구체적으로 오류 메시지에는 다음 텍스트가 포함될 수 있습니다.

      • Request is prohibited by organization's policy
      • Request violates VPC Service Controls

    VPC 서비스 제어를 구성할 때 발생할 수 있는 문제에 대한 자세한 내용은 일반적인 문제 해결을 참고하세요.

  • 비공개 엔드포인트 확인: Cloud Scheduler는 VPC 서비스 제어 경계 내에서 Cloud Run, Cloud Run Functions, Google Cloud API와 같은 특정 비공개 엔드포인트만 호출할 수 있습니다. 대상 서비스의 인그레스 설정(예: Cloud Run의 네트워크 인그레스 제한 참고)과 연결된 서비스 계정의 권한을 확인합니다. URL_ERROR-ERROR_DNS 오류 메시지가 표시될 수 있습니다. 자세한 내용은 이 문서의 연결할 수 없는 대상 타겟으로 인해 작업이 실패함을 참고하세요.

연결할 수 없는 대상 타겟으로 인해 작업이 실패함

이 문제는 대상 타겟에 연결할 수 없어 Cloud Scheduler 작업이 실패할 때 발생합니다. 실행 로그에 URL_ERROR 또는 URL_UNREACHABLE로 시작하는 오류가 표시됩니다.

이 문제를 해결하려면 수신된 오류 메시지에 따라 다음 검사 중 하나를 완료하세요.

  • URL_ERROR-ERROR_AUTHENTICATION: HTTP 401 (Unauthorized) 또는 HTTP 407 (Proxy Authentication Required) 오류가 반환됩니다. 대상 타겟에 인증이 필요하지만 Cloud Scheduler 요청에 유효한 인증 토큰이 포함되어 있지 않습니다. 예를 들어 요청에 승인 헤더가 누락되었거나 사용자 인증 정보가 유효하지 않습니다. 작업의 인증 설정을 확인합니다. 자세한 내용은 Cloud Scheduler에 인증 및 HTTP 대상에 인증 사용을 참고하세요.

  • URL_ERROR-ERROR_DNS: 도메인 이름 시스템 (DNS)을 사용하여 호스트 이름을 확인할 수 없기 때문에 URL 가져오기에 실패했음을 나타냅니다. 예를 들어 호스트 이름이 존재하지 않거나 연결된 IP 주소가 없습니다. 오류 메시지에 Original HTTP response code number = 0 텍스트가 포함될 수 있습니다. 호스트 이름의 유효성을 확인하고 비공개 엔드포인트를 호출할 때는 Cloud Scheduler에서 지원되는지 확인하고 수신 설정을 확인합니다.

  • URL_ERROR-ERROR_NOT_FOUND: 웹 서버가 HTTP 404 Not Found 오류를 반환합니다. 타겟 URL이 올바르고 리소스가 존재하는지 확인합니다.

  • URL_ERROR-ERROR_OTHER: 이 오류는 이전에 자세히 설명되지 않은 일반 HTTP 4xx 오류를 나타냅니다. 로그를 확인하여 원래 HTTP 응답 코드를 가져옵니다. HTTP 403 오류가 표시되면 이 문서에서 권한 오류로 인해 작업이 실패함을 참고하세요.

  • URL_UNREACHABLE-UNREACHABLE_5xx: 대상 타겟이 HTTP 5xx 또는 429 오류를 반환합니다. 일시적인 상태(예: 서버 과부하)일 수 있습니다. 대상 타겟의 로그를 확인하여 문제를 디버그합니다.

  • URL_UNREACHABLE-UNREACHABLE_CONNECTION_RESET: 피어에 의해 연결이 재설정되었습니다. 외부 서버 측에 문제가 있는지 확인합니다.

  • URL_UNREACHABLE-UNREACHABLE_ERROR: 네트워크 오류를 나타냅니다. 타겟 URL이 올바른지, 액세스를 차단하는 방화벽 규칙이 있는지 확인합니다.

작업 실행 문제

Cloud 스케줄러 작업은 정의된 시간 또는 일정한 간격으로 실행됩니다. 작업이 실행되는 동안 다음 문제가 발생할 수 있습니다.

이전에 작동하던 작업이 실행을 중지함

이 문제는 이전에 성공적으로 실행된 Cloud Scheduler 작업이 Cloud Scheduler API가 사용 중지되어 실행이 중지될 때 발생합니다. 다음 기준에 따라 감사 로그를 쿼리하여 API가 사용 중지된 시간을 확인할 수 있습니다.

resource.type="audited_resource" AND
protoPayload.serviceName="cloudscheduler.googleapis.com" AND
operation.producer="serviceusage.googleapis.com" AND
protoPayload.authorizationInfo.permission="serviceusage.services.disable"

이 문제를 해결하려면 Cloud Scheduler API를 사용 설정합니다.

일광 절약 시간으로 인해 작업 실행이 불규칙해짐

Google Cloud 콘솔을 사용하여 Cloud Scheduler 작업을 만들 때는 시간대를 지정해야 합니다. Google Cloud CLI를 사용하는 경우 --time-zone 플래그를 사용하여 시간대를 선택적으로 지정할 수 있습니다. 그렇지 않으면 사용되는 기본 시간대는 협정 세계시(UTC) 또는 UTC입니다.

이 문제는 작업이 UTC가 아닌 시간대로 구성되어 있고 일광 절약 시간제 (DST) 변경으로 인해 실행이 불규칙해질 때 발생합니다. 이는 정상적인 동작이므로,

작업에 매우 정확한 주기가 필요한 경우 일광 절약 시간을 시행하지 않는 시간대를 선택해야 합니다. 특히 이 문제를 완전히 방지하려면 UTC 시간대를 사용하도록 작업 일정을 구성하세요.

자세한 내용은 크론 작업 형식 및 시간대를 참조하세요.

다음 단계

Cloud Scheduler 문서에서 문제 해결 방법을 찾을 수 없는 경우 다음 옵션을 고려하세요.

자세한 내용은 Cloud Scheduler 지원을 참고하세요.