잡 스펙의 `parameterized` 블록

파라미터화된 잡은 함수 정의처럼 다양한 입력에 대해 수행할 수 있는 작업 묶음을 캡슐화하는 데 사용해요. parameterized 블록이 잡에 추가되면 그 잡은 클러스터 전체에 함수처럼 동작해요.

출처: 문서

본문

배치	`job -> parameterized`

parameterized 블록은 잡 운영자가 특정 작업을 수행하는 잡을 구성하고, 리소스 요구 사항을 정의하며, 잡 안의 태스크가 입력과 구성을 어떻게 검색할지 구성할 수 있게 해요.

파라미터화된 잡을 호출하려면 nomad job dispatch 또는 동등한 HTTP API를 사용해요. 파라미터화된 잡에 대해 디스패치할 때 불투명한 페이로드와 메타데이터가 잡에 주입될 수 있어요. 파라미터화된 잡에 대한 이러한 입력은 함수에 대한 인자처럼 동작해요. 잡은 호출자에게 구현 세부 사항을 노출하지 않고 동작을 변경하려고 이것들을 사용해요.

그 목적을 위해 잡 안의 태스크는 이 페이로드가 파일시스템의 어디에 쓰여질지 정의하는 dispatch_payload 블록을 추가할 수 있어요. 예시 페이로드는 태스크의 JSON 구성이에요.

또한 잡을 디스패치할 때 특정 메타데이터를 필수로 표시해 보간으로 구성이 태스크의 인자에 직접 주입되도록 할 수 있어요. 예시는 관리 서비스나 데이터베이스에서 잡이 수행해야 할 작업을 조회하는 데 사용할 수 있는 실행 ID 키를 요구하는 것이에요.

잡이 디스패치될 때마다 고유한 잡 ID가 생성돼요. 이렇게 하면 호출자가 어떤 프로그래밍 언어의 future나 promise처럼 잡의 상태를 추적할 수 있어요. 디스패치된 잡은 디스패치 후 업데이트할 수 없어요. 잡 정의를 업데이트하려면 부모 잡을 업데이트해야 해요.

job "docs" {
  parameterized {
    payload       = "required"
    meta_required = ["dispatcher_email"]
    meta_optional = ["pager_email"]
  }
}

파라미터화된 잡을 디스패치할 때의 추가 고려 사항은 multiregion 문서를 참고하세요.

요구 사항 (Requirements)

잡의 스케줄러 타입은 batch 또는 sysbatch여야 해요.

매개변수 (Parameters)

meta_optional (array<string>: nil) - 잡에 대해 디스패치할 때 제공될 수 있는 메타데이터 키 묶음.
meta_required (array<string>: nil) - 잡에 대해 디스패치할 때 반드시 제공되어야 하는 메타데이터 키 묶음.
payload (string: "optional") - 파라미터화된 잡에 대해 디스패치할 때 페이로드를 제공해야 하는 요구 사항. payload의 최대 크기는 16 KiB예요. 이 필드의 옵션:
- "optional" - 잡에 대해 디스패치할 때 페이로드는 선택적.
- "required" - 잡에 대해 디스패치할 때 페이로드를 반드시 제공해야 함.
- "forbidden" - 잡에 대해 디스패치할 때 페이로드가 금지됨.

예시 (Examples)

다음 예시는 실행할 수 없는 예시 파라미터화된 잡을 보여줘요.

필수 입력 (Required inputs)

이 예시는 페이로드와 메타데이터를 모두 요구하는 파라미터화된 잡을 보여줘요:

job "video-encode" {
  # ...

  type = "batch"

  parameterized {
    payload       = "required"
    meta_required = ["dispatcher_email"]
  }

  group "encode" {
    # ...

    task "ffmpeg" {
      driver = "exec"

      config {
        command = "ffmpeg-wrapper"

        # When dispatched, the payload is written to a file that is then read by
        # the created task upon startup
        args = ["-config=${NOMAD_TASK_DIR}/config.json"]
      }

      dispatch_payload {
        file = "config.json"
      }
    }
  }
}

메타데이터 보간 (Metadata interpolation)

job "email-blast" {
  # ...

  type = "batch"

  parameterized {
    payload       = "forbidden"
    meta_required = ["CAMPAIGN_ID"]
  }

  group "emails" {
    # ...

    task "emailer" {
      driver = "exec"

      config {
        command = "emailer"

        # The campaign ID is interpolated and injected into the task's
        # arguments
        args = ["-campaign=${NOMAD_META_CAMPAIGN_ID}"]
      }
    }
  }
}

periodic과 parameterized 함께 사용 (Use periodic with parameterized)

Nomad는 parameterized와 periodic 둘 다인 잡을 스케줄링할 때 내부 계층 구조를 사용해요.

parameterized => periodic => batch

Nomad는 periodic + parameterized 잡을 다음 순서로 처리해요:

Nomad는 주기적 구성에 널 매개변수가 있는 periodic 잡을 디스패치하지 않아요. 이렇게 해서 파라미터화된 잡이 periodic 잡보다 우선하도록 강제해요.
Nomad가 파라미터화된 잡을 디스패치하고 매개변수를 부여한 후, Nomad는 주기적 구성을 사용해요.
Nomad는 트리거하는 파라미터화된 잡의 매개변수를 사용하는 주기적 구성에 따라 새 잡을 디스패치해요.

이 예시에서 운영자가 파라미터화된 잡을 적어도 한 번 디스패치할 때까지 periodic 잡은 새 잡을 트리거하지 않아요. 그 후 디스패치된 자식 잡은 주어진 매개변수로 더 많은 자식을 주기적으로 트리거해요.

  periodic {
    crons = [
      "*/40 * * * * * *"
    ]
  }
  parameterized {
    payload       = "required"
    meta_required = ["dispatcher_email"]
    meta_optional = ["pager_email"]
  }

이 예시 출력에는 세 개의 열과 주석이 있는데, 이것은 위의 periodic, parameterized 예시 잡에 대한 것이에요. 마지막 열로 스크롤해 주석을 확인하세요.

$ nomad job status
ID                                                     Type                            Submit Date
sync                                                   batch/periodic/parameterized    2024-11-07T10:43:30+01:00 // Original submitted job
sync/dispatch-1730972650-247c6e97                      batch/periodic                  2024-11-07T10:44:10+01:00 // First dispatched job with parameters A
sync/dispatch-1730972650-247c6e97/periodic-1730972680  batch                           2024-11-07T10:44:40+01:00 // Cron job with parameters A
sync/dispatch-1730972650-247c6e97/periodic-1730972860  batch                           2024-11-07T10:47:40+01:00 // Cron job with parameters A
sync/dispatch-1730972760-f79a96e1                      batch/periodic                  2024-11-07T10:46:00+01:00 // Second dispatched job with parameters B
sync/dispatch-1730972760-f79a96e1/periodic-1730972800  batch                           2024-11-07T10:46:40+01:00 // Cron job with parameters B
sync/dispatch-1730972760-f79a96e1/periodic-1730972860  batch                           2024-11-07T10:47:40+01:00 // Cron job with parameters B

출력은 다음을 보여줘요:

sync 잡은 parameterized와 periodic 잡이에요. 하지만 Nomad는 필수 매개변수로 제출할 때까지 periodic 잡을 실행하지 않아요.
sync/dispatch-1730972650-247c6e97 잡은 매개변수를 포함하고 sync/dispatch-1730972650-247c6e97/periodic-1730972680과 sync/dispatch-1730972650-247c6e97/periodic-1730972860이라는 이름의 batch 잡을 트리거해요.
sync/dispatch-1730972760-f79a96e1 잡은 새 매개변수를 할당하고 그 매개변수를 사용하는 새 batch 잡을 트리거해요.

periodic 잡을 강제 실행해야 한다면 해당하는 파라미터화된 잡을 강제 실행하면 돼요.

이 예시는 위 예시의 매개변수 A를 가진 첫 번째 디스패치된 잡을 강제 실행해요.

$ nomad job periodic force sync/dispatch-1730972650-247c6e97

잡 스펙의 `parameterized` 블록