Functions CLI로 Compute Module 이미지 게시

Functions CLI는 소스 코드에서 함수 명세를 추론하고, Foundry가 요구하는 metadata label을 포함한 Docker 이미지를 빌드 및 게시하는 도구입니다. 로컬 개발과 CI/CD에서 사용할 수 있습니다.

준비

사용할 운영체제용 Functions CLI 바이너리를 준비합니다. Unix 계열에서는 실행 권한을 부여한 뒤 PATH에 있는 functions-cli로 호출합니다.

chmod +x functions-cli

기본 빌드 엔진은 Docker입니다. 게시할 Artifacts 저장소와 인증 자격 증명도 필요합니다. 빌드와 게시는 실제 레지스트리에 결과를 만들므로 대상 저장소와 이미지 태그를 먼저 정합니다.

Python 함수 명세 추론

--opt functions는 함수 명세 추론을, --plugin python_cm은 Python Compute Module SDK를 사용하는 소스 처리를 선택합니다.

functions-cli infer --opt functions --plugin python_cm --dir ./src

미리 준비한 추론 plan 파일을 사용하는 경로도 있습니다.

functions-cli infer --planfile ./infer_plan.yml --dir ./src

결과는 함수 이름, 입력 이름과 자료형 및 출력 타입을 포함한 JSON 배열입니다. 이 단계의 명세 생성과 이미지 빌드/게시는 구분합니다.

File plugin 자료형

함수 명세를 직접 작성할 때는 file plugin의 JSON 정의를 사용할 수 있습니다. 다음은 가상 Person 타입을 정의하고 함수의 입출력에서 조합하는 명세 예입니다.

{
  "types": {
    "Person": {
      "type": "object",
      "fields": {
        "name": {"dataType": "string"},
        "age": {"dataType": "integer"}
      }
    }
  },
  "functions": [
    {
      "functionName": "example_function",
      "inputs": [
        {"name": "text", "dataType": "string", "required": true},
        {"name": "items", "dataType": "list<Person>", "required": true},
        {"name": "metadata", "dataType": "optional<dict<string, string>>", "required": false}
      ],
      "outputs": [{"dataType": "dict<string, set<Person>>"}]
    }
  ]
}

이 파일은 함수의 타입 계약입니다. 이미지에는 같은 이름과 입출력을 처리하는 실제 함수 구현이 있어야 합니다.

dict<string, set<Person>> 또는 optional<list<integer>>처럼 중첩할 수 있습니다. File plugin의 정의 형식과 런타임으로 POST하는 함수 명세의 형식은 구분합니다.

빌드 plan

plan은 YAML 또는 JSON으로 작성합니다. 아래 호스트, 이미지 이름과 저장소 RID는 가상 값입니다. 레지스트리 주소와 RID는 Artifacts의 Publish > Docker에 표시된 실제 값으로 바꿉니다. CLIENT_ID와 CLIENT_SECRET 및 IMAGE_TAG는 외부 환경에서 제공합니다.

build_plan.yml:

name: my-compute-module-image
tag: $(IMAGE_TAG)
registry:
  url: stack-container-registry.palantirfoundry.com
  username: ri.artifacts.main.repository.example-artifact-repo-rid-abc123
auth:
  client_id: $(CLIENT_ID)
  client_secret: $(CLIENT_SECRET)
  host: stack.palantirfoundry.com
kind: python_cm

plan 안의 $(...)는 CLI가 사용하는 환경 변수 참조입니다. 비밀 값을 plan에 직접 기록하지 않습니다.

: "${IMAGE_TAG:?IMAGE_TAG is required}"
: "${CLIENT_ID:?CLIENT_ID is required}"
: "${CLIENT_SECRET:?CLIENT_SECRET is required}"
functions-cli build -p ./build_plan.yml -d ./src

auth에는 위 OAuth client의 client_id, client_secret, host 조합 대신 Foundry API 토큰을 사용할 수도 있습니다.

auth:
  token: $(FOUNDRY_TOKEN)

토큰 인증 경로에서는 FOUNDRY_TOKEN을 외부 환경으로 제공하고 client credentials 항목과 함께 사용하지 않습니다.

이미지 태그 증가

직접 태그를 지정하는 대신 build의 -t 옵션을 사용할 수 있습니다.

Docker daemon 없는 GoCR 엔진

Docker-in-Docker가 없거나 제한된 CI에서는 GoCR 엔진을 사용할 수 있습니다. 먼저 Python 3.12와 앱의 런타임 의존성이 설치된 기반 이미지를 준비하고 그 게시 주소를 COMPUTE_RUNTIME_IMAGE로 제공합니다. Python SDK 앱에는 foundry-compute-modules도 설치되어 있어야 합니다. 기반 이미지 준비에는 Python 이미지 구성을 사용할 수 있습니다.

name: my-compute-module-image
tag: 0.0.1
registry:
  url: stack-container-registry.palantirfoundry.com
  username: ri.artifacts.main.repository.example-artifact-repo-rid-abc123
auth:
  token: $(FOUNDRY_TOKEN)
engine:
  gocr:
    base_image: $(COMPUTE_RUNTIME_IMAGE)
    copy_paths:
      - source: ./src
        dest: /app/client
    entrypoint: ["python", "/app/client/app.py"]
kind: python_cm

copy_paths는 앱 파일을 이미지에 복사하고 entrypoint는 시작 명령을 지정합니다. 호스트와 RID는 실제 게시 대상으로 바꿉니다. 위 plan에는 런타임 의존성을 설치하는 단계가 없습니다.

CLI 로그

-v는 Info, -vv는 Debug 출력을 사용합니다. 디버그 로그를 공유할 때 인증 정보와 비밀이 포함되지 않았는지 확인합니다.