문제해결

이 페이지에서는 Workflows를 사용할 때 발생할 수 있는 문제를 해결하는 방법을 보여줍니다.

자세한 내용은 Workflows 모니터링 및 디버깅을 참조하세요.

배포 오류

워크플로가 배포될 때 Workflows는 소스 코드에 오류가 없고 언어 구문과 일치하는지 확인합니다. 문제가 있으면 Workflows가 오류를 반환합니다. 배포 오류의 가장 일반적인 유형은 다음과 같습니다.

정의되지 않은 변수, 단계 또는 하위 워크플로 참조
잘못된 구문
- 잘못된 들여쓰기
- 누락되었거나 불필요한 {, }, ", -, :

예를 들어 다음 소스 코드는 반환 구문이 정의되지 않은 변수 varC를 참조하기 때문에 배포 오류를 발생시킵니다.

- step1:
    assign:
    - varA: "Hello"
    - varB: "World"
- step2:
    return: ${varC + varB}

이 잘못된 소스 코드는 다음 Google Cloud Console 및 gcloud CLI 예시에서 사용됩니다.

콘솔

배포 오류가 발생하면 Workflows가 워크플로 수정 페이지의 배너에 오류 메시지를 표시합니다. 이 오류 메시지는 소스 코드의 문제를 플래그로 표시하고, 가능한 경우 오류 원점을 지정합니다.

Could not deploy workflow: failed to build: error in step step2: error
evaluating return value: symbol 'varC' is neither a variable nor a
sub-workflow name (Code: 3)

gcloud

gcloud workflows deploy 명령어를 실행할 때 배포가 실패하면 Workflows가 명령줄에 오류 메시지를 반환합니다. 이 오류 메시지는 소스 코드의 문제를 나타내며, 가능한 경우 오류의 출처를 지정합니다.

ERROR: (gcloud.workflows.deploy) [INVALID_ARGUMENT] failed to build:
error in step step2: error evaluating return value: symbol 'varC' is neither
a variable nor a sub-workflow name

문제를 해결하려면 워크플로의 소스 코드를 수정합니다. 이 경우 varC 대신 varA를 참조하세요.

HTTP `403` 서비스 계정 권한 오류

HTTP 서버가 403 오류 코드로 응답하면 워크플로 실행이 실패합니다. 예를 들면 다음과 같습니다.

Permission 'iam.serviceaccounts.actAs' denied on service
account PROJECT_NUMBER-compute@developer.gserviceaccount.com (or it may not exist).

또는

SERVICE_ACCOUNT does not have storage.objects.create access to the Google Cloud
Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist).

모든 워크플로는 워크플로가 생성될 때 IAM 서비스 계정과 연결됩니다. 이 문제를 해결하려면 워크플로 관리에 필요한 최소 권한이 포함된 하나 이상의 IAM 역할을 서비스 계정에 부여해야 합니다. 예를 들어 워크플로에서 Cloud Logging으로 로그를 전송하도록 하려면 워크플로를 실행하는 서비스 계정에 logging.logEntries.create 권한이 포함된 역할이 부여되었는지 확인합니다. 자세한 내용은 워크플로에 Google Cloud 리소스에 대한 액세스 권한 부여를 참조하세요.

HTTP `404 No such object` 또는 `Not found` 오류

Cloud Storage 커넥터를 사용할 때 HTTP 서버가 404 오류 코드로 응답하면 워크플로 실행이 실패합니다. 예를 들면 다음과 같습니다.

HTTP server responded with error code 404
in step "read_input_file", routine "main", line: 13
{
  "body": "Not Found",
  "code": 404,
  ...
}

경로의 안전성을 위해 객체 이름을 URL로 인코딩해야 합니다. url_encode 및 url_encode_plus 함수를 사용하여 요청 URL의 객체 이름 또는 쿼리 문자열에 해당 문자가 표시될 때 이를 인코딩할 수 있습니다. 예를 들면 다음과 같습니다.

- init:
    assign:
        - source_bucket: "my-bucket"
        - file_name: "my-folder/my-file.json"
- list_objects:
    call: googleapis.storage.v1.objects.get
    args:
        bucket: ${source_bucket}
        object: ${text.url_encode(file_name)}
        alt: media
    result: r
- returnStep:
    return: ${r}

객체 이름을 URL 인코딩하지 않고 스토리지 버킷에 폴더가 있으면 요청이 실패합니다. 자세한 내용은 URL 경로 부분 인코딩 및 Cloud Storage 이름 지정 고려사항을 참조하세요.

HTTP `429 Too many requests` 오류

활성 워크플로 실행이 동시에 발생할 수 있는 최대 개수가 존재합니다. 이 할당량이 소진되고 실행 백로그가 사용 중지되었거나 백로그된 실행의 할당량에 도달하면 새 실행은 HTTP 429 Too many requests 상태 코드와 함께 실패합니다.

실행 백로그를 사용하면 동시 실행 할당량에 도달한 후 워크플로 실행을 대기열에 추가할 수 있습니다. 기본적으로 실행 백로깅은 다음 예외를 제외하고 모든 요청(Cloud Tasks에서 트리거된 요청 포함)에 대해 사용 설정됩니다.

워크플로에서 executions.run 또는 executions.create 커넥터를 사용하여 실행을 만들 때 실행 백로그는 기본적으로 사용 중지됩니다. 실행의 disableConcurrencyQuotaOverflowBuffering 필드를 false로 명시적으로 설정하여 구성할 수 있습니다.
Pub/Sub에서 트리거된 실행의 경우 실행 백로그가 사용 중지되며 구성할 수 없습니다.

자세한 내용은 실행 백로그 관리를 참조하세요.

사용자가 정의한 속도로 Cloud Tasks 큐에서 하위 워크플로를 실행하도록 사용 설정하고 실행 속도를 개선할 수도 있습니다. 이 경우 명시적으로 실행 백로그를 사용 중지할 수 있습니다.

프로젝트 간 서비스 계정 권한 오류

프로젝트 간 서비스 계정을 사용하여 워크플로를 배포하려고 할 때 PERMISSION_DENIED 오류가 발생하면 프로젝트에 iam.disableCrossProjectServiceAccountUsage 부울 제약조건이 적용되지 않았는지 그리고 서비스 계정을 올바르게 설정했는지 확인합니다. 자세한 내용은 프로젝트 간 서비스 계정으로 워크플로 배포를 참조하세요.

리소스 이름은 RFC 1123을 준수해야 합니다.

HTTP 서버가 400 오류 코드로 응답하면 워크플로 실행이 실패합니다. 예를 들면 다음과 같습니다.

"description": "must conform to RFC 1123: only lowercase, digits, hyphens,
and periods are allowed, must begin and end with letter or digit, and less
than 64 characters."

이 문제를 해결하려면 리소스 이름이 RFC 1123에 정의된 대로 DNS 라벨 표준을 따르고 변수를 할당할 때 문자열 및 표현식이 올바르게 연결되는지 확인합니다.

예를 들어 - string: hello-${world}와 같이 변수를 할당할 수 없습니다. 대신 다음 단계를 따릅니다.

YAML

  - assign_vars:
      assign:
          - string: "hello"
          - string: ${string+" "+"world"}

JSON

  [
    {
      "assign_vars": {
        "assign": [
          {
            "string": "hello"
          },
          {
            "string": "${string+" "+"world"}"
          },
        ]
      }
    }
  ]

콜론이 포함된 표현식

YAML에서 콜론이 포함된 표현식의 경우 콜론이 맵 정의로 해석되면 예기치 않은 동작이 발생할 수 있습니다. 워크플로를 배포 및 실행할 수 있지만 출력이 예상한 대로 표시되지 않습니다.

Google Cloud 콘솔을 사용하여 워크플로를 만드는 경우 Google Cloud 콘솔에서 워크플로를 시각적으로 렌더링할 수 없으며 다음과 비슷한 경고가 표시될 수 있습니다.

워크플로 생성 경고

YAML 표현식을 작은따옴표로 묶으면 이 문제를 해결할 수 있습니다.

권장: '${"a: " +string(a)}'

권장하지 않음: ${"a: " +string(a)}

영숫자가 아닌 문자를 사용하여 키 매핑

영숫자가 아닌 문자(예: "special!key": value의 느낌표)로 맵 키에 액세스할 때는 키 이름을 따옴표로 묶어야 합니다. 키 이름을 따옴표로 묶지 않으면 워크플로를 배포할 수 없습니다. 예를 들어 다음 소스 코드를 배포하려고 하면 token recognition error가 발생합니다.

- init:
    assign:
    - var:
        key:
            "special!key": bar
- returnOutput:
    return: '${"foo" + var.key[special!key]}'

이 문제를 해결하려면 다음 코드를 사용하여 출력을 반환합니다.

'${"foo" + var.key["special!key"]}'

목록에서 여러 표현식

다음 반복 범위 예시와 같이 목록 내에서 여러 표현식을 사용하는 것은 유효한 YAML이 아닙니다.

[${rangeStart}, ${rangeEnd}])

다음 중 하나를 수행하여 이 문제를 해결할 수 있습니다.

목록을 표현식 내에 배치합니다.

${[rangeStart, rangeEnd]}
각 표현식을 작은따옴표로 묶습니다.

['${rangeStart}', '${rangeEnd}']

그러면 결과는 예상대로 두 값 목록이 됩니다.

고객 관리 암호화 키(CMEK)

Workflows에서 Cloud KMS를 사용할 때 오류가 발생할 수 있습니다. 다음 표는 다양한 문제와 해결 방법을 설명합니다.

문제	설명
`cloudkms.cryptoKeyVersions.useToEncrypt` 권한이 거부됨	제공된 Cloud KMS 키가 없거나 권한이 올바르게 구성되지 않았습니다. 솔루션: Cloud KMS 키가 있는지 확인합니다. 지정된 키링의 키를 나열하고 사용량을 확인합니다. Workflows 서비스 에이전트에 키에 대한 액세스 권한이 있고 `cloudkms.cryptoKeyEncrypterDecrypter` 역할이 부여되었는지 확인합니다.
키 버전이 사용 설정되지 않음	제공된 Cloud KMS 키가 사용 중지되었습니다. 솔루션: Cloud KMS 키 버전을 다시 사용 설정합니다.
키링 리전이 보호할 리소스와 일치하지 않음	제공된 KMS 키링 리전은 워크플로의 리전과 다릅니다. 솔루션 동일한 리전에서 Cloud KMS 키링과 보호된 워크플로를 사용합니다. (다른 프로젝트에 있을 수 있습니다.) 자세한 내용은 Cloud KMS 위치 및 Workflows 위치를 참조하세요.
Cloud KMS 할당량 한도를 초과함	Cloud KMS 요청의 할당량 한도에 도달했습니다. 솔루션: Cloud KMS 호출 수를 제한하거나 할당량 한도를 늘립니다. 자세한 내용은 Cloud KMS 할당량을 참조하세요.

Cloud Run 커넥터를 사용할 때 요청된 항목을 찾을 수 없음

googleapis.run.v1.namespaces.jobs.create 커넥터 메서드를 사용하려고 시도할 때 HTTP 서버가 404 오류 코드로 응답하면 워크플로 실행이 실패합니다.

이 방법을 사용하려면 HTTP 엔드포인트의 위치를 지정해야 합니다. 예를 들면 us-central1 또는 asia-southeast1입니다. 위치를 지정하지 않으면 전역 엔드포인트 https://run.googleapis.com이 사용되지만 이 위치는 list 메서드만 지원합니다.

이 문제를 해결하려면 커넥터를 호출할 때 location 인수를 지정해야 합니다. Cloud Run Admin API 위치 옵션은 서비스 엔드포인트를 참조하세요.

리소스 한도

리소스 제한 또는 ResourceLimitError, MemoryLimitExceededError, ResultSizeLimitExceededError와 같은 오류가 발생하면 변수를 삭제하여 메모리를 비울 수 있습니다. 예를 들어 후속 단계에 필요한 메모리를 확보할 수 있습니다. 또는 관심 없는 결과가 포함된 호출이 있을 수 있으며 해당 결과를 모두 생략할 수 있습니다.

YAML 들여쓰기

YAML 들여쓰기는 의미가 있으며 들여쓰기 수준당 최소 2개 이상의 공백이어야 합니다. 들여쓰기가 부족하면 오류가 발생할 수 있으며 새 수준은 이전 줄의 텍스트 시작부터 최소 2개 이상의 공백이어야 합니다.

예를 들어 다음은 stepName 및 call 항목이 있는 맵이 포함된 목록 항목을 잘못 지정합니다.

- stepName:
  call: sys.log

대신 후속 줄을 공백 2개로 들여써 stepName 내에서 call을 중첩해야 합니다.

- stepName:
    call: sys.log

탭 문자가 아닌 공백을 사용하여 줄을 들여써야 합니다.

다음 단계

Workflows의 알려진 문제