작업 명세의 artifact 블록

작업 명세의 artifact 블록 (artifact block in the job specification)

배치	`job -> group -> task -> artifact`

artifact 블록은 Nomad가 파일, 압축 파일(tarball), 바이너리 같은 원격 리소스를 가져와 풀도록 지시해요. Nomad는 URL을 입력 소스로 사용해 다양한 위치에서 아티팩트를 다운로드할 수 있게 해주는 널리 쓰이는 go-getter 라이브러리로 아티팩트를 다운로드해요.

job "docs" {
  group "example" {
    task "server" {
      artifact {
        source      = "https://example.com/file.tar.gz"
        destination = "local/some-directory"
        options {
          checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
        }
      }
    }
  }
}

Nomad는 http, https, git, hg, S3 아티팩트 다운로드를 지원해요. 이러한 아티팩트가 압축되어 있으면(zip, tgz, bz2, xz) 태스크를 시작하기 전에 자동으로 압축을 풀어요.

출처: 문서

본문

매개변수 (Parameters)

destination (string: "local/") — 태스크 작업 디렉토리의 루트를 기준으로 아티팩트를 다운로드할 디렉토리 경로를 지정해요. 생략하면 기본값이 아티팩트를 local/에 배치해요. mode가 file로 설정되지 않는 한 destination은 디렉토리로 취급돼요. 소스 파일은 그 디렉토리 경로로 다운로드돼요. destination이 태스크 드라이버와 상호작용하는 방법에 대한 자세한 내용은 파일시스템 내부 문서를 참조하세요.
mode (string: "any") — any, file, dir 중 하나. file로 설정하면 destination은 디렉토리가 아닌 파일이어야 해요. 기본적으로 destination은 local/<filename>이 돼요.
options (map<string|string>: nil) — 아티팩트를 가져오기 위한 구성 매개변수를 지정해요. 키-값 쌍은 제공된 source URL에 추가되는 매개변수에 직접 매핑돼요. 옵션과 예제의 전체 목록은 go-getter 문서를 참조하세요.
headers (map<string|string>: nil) — http 또는 https 프로토콜로 아티팩트를 가져올 때 설정할 HTTP 헤더를 지정해요. 자세한 내용은 go-getter 헤더 문서를 참조하세요.
source (string: <required>) — 다운로드할 아티팩트의 URL을 지정해요. 자세한 내용은 go-getter를 참조하세요.
chown (bool: false) — Nomad가 다운로드한 아티팩트를 task.user의 uid와 gid가 소유하도록 재귀적으로 chown해야 하는지 지정해요.

환경 (Environment)

artifact 다운로더는 사용된 소스 프로토콜에 따라 환경 변수를 찾을 수 있어요. 기본적으로 Nomad는 다운로더가 Nomad 클라이언트에 대해 설정된 어떤 환경 변수에도 접근하는 것을 허용하지 않아요. artifact.set_environment_variables 클라이언트 구성으로 환경 변수의 상속을 관리해요. Nomad 변수와 시크릿은 여전히 artifact 블록의 매개변수를 해석하는 데 사용될 수 있어요.

민감한 데이터를 포함하는 매개변수를 채우려면 Nomad Secret 블록을 사용할 것을 권장해요.

작업 한도 (Operation limits)

클라이언트 artifact 구성은 과도한 데이터 다운로드나 작업 시간을 방지하기 위해 특정 artifact 작업에 대한 한도를 설정할 수 있어요.

태스크의 artifact 검색이 그러한 한도 중 하나를 초과하면 태스크는 중단되고 시작에 실패해요. 자세한 내용은 태스크 이벤트를 참조하세요.

예제 (Examples)

다음 예제는 artifact 블록만 보여줘요. artifact 블록은 위에 나열된 배치에서만 유효하다는 것을 기억하세요.

파일 다운로드 (Download file)

이 예제는 제공된 URL에서 아티팩트를 다운로드해 local/file.txt에 배치해요. local/ 경로는 태스크 작업 디렉토리를 기준으로 해요.

artifact {
  source = "https://example.com/file.txt"
}

소스에 대한 요청에서 HTTP 헤더를 설정하려면 선택적 headers 필드를 구성할 수 있어요.

artifact {
  source = "https://example.com/file.txt"

  headers {
    User-Agent    = "nomad-[${NOMAD_JOB_ID}]-[${NOMAD_GROUP_NAME}]-[${NOMAD_TASK_NAME}]"
    X-Nomad-Alloc = "${NOMAD_ALLOC_ID}"
  }
}

HTTP 기본 인증을 사용하려면 URL의 호스트 이름 앞에 사용자 이름과 비밀번호를 붙여요. 사용자 이름과 비밀번호를 포함한 모든 특수 문자는 URL 인코딩되어야 해요. 예를 들어 사용자 이름 exampleUser와 비밀번호 pass/word!에 대해:

artifact {
  source = "https://exampleUser:pass%2Fword%[email protected]/file.txt"
}

git으로 다운로드 (Download using git)

이 예제는 제공된 GitHub URL에서 아티팩트를 다운로드하고 선택적 destination 매개변수로 지정된 local/repo에 배치해요.

artifact {
  source      = "git::https://github.com/hashicorp/nomad-guides"
  destination = "local/repo"
}

프라이빗 저장소에서 다운로드하려면 sshkey를 설정해야 해요. 키는 base64로 인코딩된 문자열이어야 해요. Linux에서 base64 -w0 <file>을 실행해 파일을 인코딩할 수 있어요. 또는 HCL2 표현식을 사용해 머신의 파일에서 키를 읽고 인코딩할 수 있어요:

artifact {
  # The git:: prefix forces go-getter's protocol detection to use the git ssh
  # protocol. It can also automatically detect the protocol from the domain of
  # some git hosting providers (such as GitHub) without the prefix.
  source      = "git::[email protected]:example/nomad-examples"
  destination = "local/repo"
  options {
    # Make sure that the system known hosts file is populated:
    # ssh-keyscan github.com | sudo tee -a /etc/ssh/ssh_known_hosts
    # https://github.com/hashicorp/go-getter/issues/55
    sshkey = "${base64encode(file("/path/to/private-key"))}"
  }
}

특정 ref를 복제하거나 특정 깊이로 복제하려면 ref와 depth 옵션을 사용해요:

artifact {
  source      = "git::https://github.com/hashicorp/nomad-guides"
  destination = "local/repo"
  options {
    ref = "main"
    depth = 1
  }
}

다운로드 및 압축 해제 (Download and unarchive)

이 예제는 결과를 local/file에서 다운로드하고 압축을 풀어요. 소스 URL이 압축 확장자이므로 Nomad가 자동으로 압축을 풀어요:

artifact {
  source = "https://example.com/file.tar.gz"
}

자동 압축 해제를 비활성화하려면 archive 옵션을 false로 설정해요:

artifact {
  source = "https://example.com/file.tar.gz"
  options {
    archive = false
  }
}

다운로드 및 체크섬 검증 (Download and verify checksums)

이 예제는 아티팩트를 다운로드하고 진행 전에 결과 아티팩트의 체크섬을 검증해요. 체크섬이 유효하지 않으면 오류가 반환돼요.

artifact {
  source = "https://example.com/file.zip"

  options {
    checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
  }
}

S3 호환 버킷에서 다운로드 (Download from an S3-compatible bucket)

이 예제들은 Amazon S3에서 아티팩트를 다운로드해요. S3 버킷 주소 지정과 S3 리전별 엔드포인트에는 여러 유형이 있어요. Minio 같은 비-Amazon S3 호환 엔드포인트도 지원되지만, "s3::" 접두사를 명시적으로 설정해야 해요.

이 예제는 공개적으로 접근 가능한 버킷에 경로 기반 표기법을 사용해요:

artifact {
  source = "s3://my-bucket-example.s3-us-west-2.amazonaws.com/my_app.tar.gz"
}

버킷에 인증이 필요하면 EC2 IAM 인스턴스 프로파일을 사용해 자격 증명 사용을 피할 수 있어요. 불가능하다면 options 매개변수로 자격 증명을 제공할 수 있어요:

artifact {
  options {
    // Using the values from a Nomad Secret block
    aws_access_key_id     = "${secret.aws.key_id}"
    aws_access_key_secret = "${secret.aws.key_secret}"
    aws_access_token      = "${secret.aws.token}"
  }
}

S3 특정 구문을 강제하려면 s3:: 접두사를 사용해요:

artifact {
  source = "s3::https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
}

또는 가상 호스팅 스타일을 사용할 수 있어요:

artifact {
  source = "s3://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
}

DigitalOcean Spaces는 S3 호환 객체 저장소를 제공하며 artifact 블록과 함께 사용할 수 있어요. sfo3 리전에 my-bucket-example이라는 버킷과 my_app.tar.gz이라는 파일이 주어지면, 버킷과 파일이 공개되어 있다면 다음 artifact 블록이 작동해요. 이는 Digital Ocean에서 직접 설명한 origin 엔드포인트를 사용해요.

artifact {
  source = "https://my-bucket-example.sfo3.digitaloceanspaces.com/my_app.tar.gz"
}

버킷이나 파일이 프라이빗이라면 artifact 소스 문자열에 s3:: 접두사를 추가하도록 수정해야 해요. 버킷 이름도 URL 경로 구성 요소의 일부가 되도록 이동돼요.

artifact {
  source = "s3::https://sfo3.digitaloceanspaces.com/my-bucket-example/my_app.tar.gz"
}

작업 명세의 artifact 블록