함수에 대한 작업

함수는 HTTP 요청에 의해 호출될 때 작업을 수행하는 상태 비저장 코드 스니펫입니다. IBM Code Engine 함수를 사용하면 확장 가능한 서버리스 방식으로 비즈니스 로직을 실행할 수 있습니다. IBM Code Engine 함수는 짧은 지연 시간과 신속한 스케일아웃 시나리오를 지원하기 위해 최적화된 런타임 환경을 제공합니다. 함수 코드는 특정 Node.js 또는 Python 버전이 포함된 관리형 런타임에서 작성할 수 있습니다.

코드 번들은 기능 코드를 나타내는 파일의 콜렉션입니다. 이 코드 번들은 런타임 컨테이너에 삽입됩니다. 코드 번들은 Code Engine 에 의해 작성되며 컨테이너 레지스트리에 저장되거나 함수와 함께 인라인으로 저장됩니다. 코드 번들은 OCI (Open Container Initiative) 표준 컨테이너 이미지가 아닙니다.

시작하기 전에

Code Engine 콘솔을 사용하려면 Code Engine 개요로 이동하세요.
CLI를 사용하려는 경우 Code Engine CLI 환경을 설정하십시오.
코드를 Code Engine 함수 컴포넌트로 실행하기 위한 접근 방식을 계획하고 선택하세요.

작성할 Code Engine 워크로드의 유형을 잘 모르십니까? Code Engine 플랜을 참조하십시오.

기능 제한사항

이벤트 생성자에 등록하는 것은 지원되지 않습니다.
Terraform에 대한 지원이 없습니다.

내 코드를 Code Engine 함수 컴포넌트로 실행하려면 어떻게 해야 하나요?

코드가 로컬 파일이나 Git 리포지토리에 소스로 존재하든, 공개 또는 비공개 레지스트리에 있는 기존 코드 번들이든, Code Engine 을 통해 코드를 함수로 실행할 수 있는 간소화된 방법을 제공합니다.

Git 리포지토리에 있는 소스 코드로 시작하는 경우 소스 위치를 가리키도록 선택할 수 있으며, Code Engine 에서 소스에서 코드 번들을 빌드하고 한 번의 작업으로 함수를 생성하는 작업을 처리합니다. 이 시나리오에서는 Code Engine 이 IBM Cloud® Container Registry 에 코드를 업로드합니다. 자세한 정보는 저장소 소스 코드에서 함수 작성 을 참조하십시오.
로컬 워크스테이션에서 소스 코드로 시작하는 경우 소스 위치를 가리키도록 선택할 수 있으며, Code Engine 에서 소스에서 이미지를 빌드하고 단일 CLI 명령으로 함수를 생성하는 작업을 처리합니다. 이 시나리오에서는 Code Engine 이 IBM Cloud® Container Registry 에 코드를 업로드합니다. 자세한 정보는 CLI를 사용하여 로컬 소스 코드에서 함수 작성 을 참조하십시오.
소스 코드로 시작하는 경우 소스 코드를 인라인으로 실행할 수도 있습니다. 이 시나리오에서는 함수를 작성할 때 소스 코드에 붙여넣습니다. 자세한 정보는 인라인 코드로 함수 작성 을 참조하십시오.

함수를 만들고 실행한 후에는 함수를 만들거나 이전에 함수를 업데이트한 방법과 관계없이 앞의 방법 중 하나를 사용하여 함수를 업데이트할 수도 있습니다.

내 함수를 호출하면 어떤 일이 발생합니까?

함수가 호출 (시작) 되면 해당 함수 인스턴스는 구성된 런타임 컨테이너 및 자원 매개변수를 사용하여 초기화됩니다. 첫 번째 초기화 프로세스를 콜드 스타트라고 합니다.

콜드 스타트 대기 시간을 줄이기 위해 Code Engine 는 특정 CPU및 메모리 구성으로 특정 런타임을 사전에 준비하여 호출을 최적화합니다. 함수에 대한 사전 예열된 조합에는 Node.js 및 Python 런타임과 함수에 대한 기본 CPU 및 메모리 조합( 0.25 vCPU x 1GB 메모리)이 있습니다. 또한 시스템은 이미 초기화된 기능 인스턴스의 재사용을 개선하도록 설계되었습니다. 따라서 호출이 완료된 후에도 함수 인스턴스는 동일한 인스턴스를 다시 사용하고 마지막 호출이 완료되었을 때 인스턴스의 상태를 다시 사용하여 후속 호출을 허용하도록 유지됩니다. 함수 인스턴스의 재사용은 보장되지 않습니다.

기능 인스턴스를 더 오래 유지할 수 있습니까?

Code Engine를 사용하면 기능이 워크로드에 따라 자동으로 확장 및 축소됩니다. 기본 CPU및 메모리 조합을 사용하여 함수를 작성하는 경우, 함수는 사용을 위해 최적화된 "사전 준비된" 컨테이너에 삽입됩니다. 기본 조합이 아닌 CPU및 메모리 조합을 사용하여 함수를 작성하면 함수가 새 컨테이너에 삽입됩니다. 기본적으로 이 컨테이너는 기능이 완료된 후 짧은 시간 동안만 활성 상태로 유지됩니다. 자세한 정보는 함수에 대해 지원되는 CPU및 메모리 조합 을 참조하십시오.

CLI의 --scale-down-delay 옵션 또는 콘솔의 용량 축소 지연 옵션을 사용하여 컨테이너가 활성 상태로 유지되는 시간을 변경할 수 있습니다. 컨테이너를 활성 상태로 유지하면 함수의 후속 실행에 대한 콜드 스타트 시간이 줄어들지만 사용자 정의 함수 컨테이너가 존재하는 시간에 대해서도 비용이 청구됩니다.

요청 및 응답

함수는 HTTP 프로토콜로 호출됩니다. 함수를 호출할 때 사용자 정의 요청 매개변수, 사용자 정의 요청 본문 및 헤더, HTTP 메서드를 지정할 수 있습니다. 요청 매개변수는 함수 코드에서 입력 매개변수로 사용할 수 있습니다. 함수 코드는 함수 엔드포인트에서 호출자에게 리턴되는 응답 본문, 응답 헤더 및 응답 코드를 설정할 수 있습니다.

예 1: 함수에서 HTML 응답 생성

다음 예제는 함수에서 HTML 응답을 생성하는 방법을 보여줍니다.

  function main(params) {
      var msg = 'You did not tell me who you are.';
      if (params.name) {
          msg = `Hello, ${params.name}!`
       } else {
          msg = `Hello, FaaS on CodeEngine!`
      }
      return {
          headers: { 'Content-Type': 'text/html; charset=utf-8' },
          body: `<html><body><h3>${msg}</h3></body></html>`
       }
  }

  module.exports.main = main;

예 2: 응답 코드 및 응답 헤더 설정

함수는 특정 응답 코드 및 헤더 플래그를 설정할 수 있습니다. 다음 예는 응답 코드와 응답 헤더를 설정하여 다른 URL 으로 리디렉션을 추가하는 방법을 설명합니다.

function main(params) {
    return {
        headers: { location: 'https://cloud.ibm.com/docs/codeengine' },
        statusCode: 302
    }
}

예 3: 함수에서 일반 텍스트 응답 생성

다음 예제는 함수에서 일반 텍스트 응답을 생성하는 방법을 보여줍니다.

function main(params) {
    var msg = 'You did not tell me who you are.';
    if (params.name !== "") {
        msg = `Hello, ${params.name}!`
    }
    return {
        headers: { 'Content-Type': 'text/plain;charset=utf-8' },
        body: `${msg}`
    }
}

오류 처리 및 디버깅

함수 호출은 시스템 또는 애플리케이션 오류를 리턴할 수 있습니다. 예를 들어, 시스템 오류는 기능 코드가 성공적으로 실행되지 않았음을 표시하는 반면, 애플리케이션 오류는 기능 코드 자체의 문제점을 표시합니다.

시스템 오류가 발생하면 다음 코드와 유사한 HTTP 응답 코드가 반환됩니다.

HTTP 응답 코드
코드	설명
409	기능에 필요한 자원이 충족되지 않았습니다.
413	요청 페이로드가 정의된 최대값을 초과합니다.
414	호출 URI가 너무 깁니다.
416	함수가 정의된 최대값을 초과하는 응답을 생성했습니다.
422	함수 코드가 유효하지 않아서 처리할 수 없습니다. 자세한 내용은 플랫폼 로그를 참조하십시오.
424	함수 코드를 실행할 수 없습니다. 나중에 다시 시도하십시오.
429	리소스 할당량을 초과했으므로 기능을 스케줄할 수 없습니다.
431	요청 헤더가 정의된 최대값을 초과합니다.
500	내부 서버 오류입니다.
502	잘못된 게이트웨이입니다.
503	현재 기능을 사용할 수 없습니다. 나중에 다시 시도하세요.
507	스토리지가 부족하여 함수를 로드할 수 없습니다.

Code Engine 가 함수 코드를 실행할 수 있는 경우 다음 상태 코드 중 하나로 호출에 응답합니다.

상태 코드
코드	설명
200	함수 호출이 승인되었습니다. 함수가 지연되어 실행됩니다.
202	함수 호출이 승인되었습니다. 함수가 비동기식으로 실행됩니다.
299	함수가 지정된 또는 최대 런타임 한계를 초과하여 중단되었습니다.

함수 개발자는 앞서 나열된 코드를 포함하여 임의의 HTTP 상태 코드를 생성할 수 있습니다. 따라서 응답 헤더는 상태 코드가 기능 코드에 의해 생성되었음을 표시합니다.

Code Engine 함수는 함수 호출 응답에 다음 응답 헤더를 추가합니다.

상태 코드
코드	설명
`x-faas-actionstatus`	함수 프로그램 로직에 의해 설정된 HTTP 상태 코드입니다.
`x-faas-activation-id`	함수 호출을 식별하기 위한 고유 ID입니다.
`x-faas-result`	런타임 컨테이너에서 리턴하는 `success` 메시지 또는 짧은 오류 메시지입니다.
`x-faas-errormessage`	추가 세부사항이 있는 긴 오류 메시지입니다.
`x-faas-prewarmed`	호출이 콜드인지 또는 함수가 기존 (사전 가온된 컨테이너) 에서 실행되었는지 여부를 표시하는 메시지입니다. 가능한 값은 `false` 또는 `true` 입니다.

함수 데이터 입출력 (I/O) 특성

Code Engine에서 함수를 실행하려면 코드가 다음 특성으로 런타임 계약을 구현해야 합니다.

공개 웹 애플리케이션 엔드포인트에서 호출할 수 있어야 웹 페이지에 임베드된 다음 Code Engine 이벤트 소스, 웹 브라우저 또는 기타 HTTPS 지원 클라이언트에서 호출할 수 있습니다.
main 프로시저를 시작점으로 구현해야 합니다. main 프로시저는 JSON 형식 데이터 구조의 양식으로 입력 매개변수를 수신할 수 있으며 JSON 형식 데이터 구조의 양식으로도 출력 매개변수를 리턴할 수 있습니다.
함수가 지정된 경로를 기반으로 다른 특색을 구현할 수 있도록 선택적 하위 경로를 수신할 수 있습니다. 함수의 main 프로시저는 __ce_path 입력 매개변수로 경로를 수신합니다.
런타임 시 함수를 구성하는 데 사용할 수 있는 선택적 조회 매개변수를 수신할 수 있습니다. 함수의 main 프로시저는 JSON 형식 입력 데이터 구조 내에서 키-값 쌍으로 매개변수를 수신합니다.
클라이언트 코드가 허용된 인코딩을 지정할 수 있도록 요청 헤더를 수신할 수 있습니다.
선택적 컨텐츠 유형 요청 헤더를 수신할 수 있습니다.
함수가 런타임 시 처리하는 선택적 요청 페이로드 (본문) 를 수신할 수 있습니다. 선택한 요청 컨텐츠 유형에 따라 데이터 페이로드가 기본 64인코딩 양식 또는 JSON 입력 데이터 구조의 일부로 "펼쳐지지 않은" 형식으로 함수의 기본 시작점으로 전달됩니다. application/x-www-form-urlencoded 입력의 키 값 쌍에 있는 특수 문자는 percent-encoded 값입니다.
호출하는 클라이언트에 반환되는 임의의 HTTP 상태 코드(선택 사항)를 정의할 수 있습니다.
경로 재지정 위치, 응답 인코딩 또는 쿠키 값과 같은 임의의 응답 헤더를 설정할 수 있습니다.
선택된 2진또는 2진이 아닌 인코딩을 사용하여 임의의 응답 본문을 리턴할 수 있습니다 (예: application/octet-stream, application/json, text/*, image/* 또는 audio/*). content-type 응답 헤더가 설정되지 않은 경우 기본값은 text/plain 입니다.
다음 요청 컨텐츠 유형을 지원합니다. application/x-www-form-urlencoded (기본값), text/plain, application/json, application/octet-stream, image/*, audio/*
multipart/form-data 요청 헤더를 지원하지 않습니다.

Code Engine 함수에 대한 가시성 옵션

Code Engine 을 사용하면 요청을 수신하는 데 사용할 수 있는 엔드포인트 또는 시스템 도메인 매핑을 정의하여 기능에 적합한 가시성 수준을 결정할 수 있습니다.

모든 함수에는 동일한 Code Engine 프로젝트 내의 모든 컴포넌트에서 볼 수 있지만 프로젝트 외부에서는 볼 수 없는 내부 시스템 도메인 매핑이 있습니다. 내부 시스템 도메인 맵핑 외에도 공용 인터넷 또는 IBM Cloud 사설 네트워크에 기능을 표시하도록 선택합니다.

공개 또는 비공개 가시성을 위해 이 기능은 HTTPS 엔드포인트에 노출됩니다. 사용되는 TLS 인증서에 대한 자세한 내용은 Code Engine 프로젝트용 TLS 인증서를 참조하세요.

다음 가시성 레벨을 사용하여 함수를 배치할 수 있습니다.

기능에 대한 가시성
설정	설명
내부(프로젝트)	이 설정을 사용하는 기능은 동일한 Code Engine 프로젝트의 컴포넌트에서 요청을 수신할 수 있습니다. 내부(프로젝트) 엔드포인트를 설정하면 공용 인터넷에서는 함수에 액세스할 수 없으며 동일한 Code Engine 프로젝트 내에서 실행 중인 다른 Code Engine 컴포넌트에서만 네트워크 액세스가 가능합니다. 이 엔드포인트는 항상 사용 가능합니다. 중요한: 함수는 내부 경로를 사용하여 다른 작업이나 애플리케이션을 호출할 수 없습니다.
public	이 설정이 있는 함수는 인터넷과 Code Engine 프로젝트에 노출됩니다. 공용 엔드포인트를 설정하면 함수가 공용 인터넷이나 Code Engine 프로젝트 내의 컴포넌트로부터 요청을 받을 수 있습니다. 이 설정은 기본값입니다.
개인용	이 설정이 있는 함수는 IBM Cloud 비공개 네트워크와 Code Engine 프로젝트에 노출됩니다. 비공개 엔드포인트를 설정하면 공용 인터넷에서는 기능에 액세스할 수 없으며, 동일한 프로젝트에서 실행 중인 가상 사설 엔드포인트(VPE) 또는 Code Engine 구성 요소를 사용하여 다른 IBM Cloud 서비스에서만 네트워크에 액세스할 수 있습니다.

함수를 생성 및 배포하거나 업데이트할 때 콘솔 또는 CLI에서 함수의 표시 여부에 대한 엔드포인트 설정을 설정할 수 있습니다.

내부 엔드포인트를 사용하여 함수 배치

내부 (프로젝트) 엔드포인트를 사용하여 배치할 함수에 대한 엔드포인트 가시성을 설정할 수 있습니다. 내부 (프로젝트) 엔드포인트를 설정하면 공용 인터넷에서 기능에 액세스할 수 없으며 동일한 Code Engine 프로젝트 내에서 실행 중인 다른 Code Engine 컴포넌트에서만 네트워크 액세스가 가능합니다. 이 엔드포인트는 항상 사용 가능합니다. 함수는 여전히 공유 컴포넌트를 통해 액세스할 수 있으므로 보안이 필요합니다.

예를 들어 솔루션이 프로젝트 내에서 여러 기능으로 구성된 경우, 인터넷에서 해당 기능 중 하나만 표시되도록 솔루션을 설정하여 들어오는 트래픽을 처리할 수 있습니다. 이 공개 기능은 솔루션의 다른 기능에 작업을 위임하여 인터넷에 표시되지 않도록 할 수 있습니다.

CLI를 사용하여 function create 또는 function update 명령에서 --visibility=project 옵션을 사용하여 프로젝트 엔드포인트와 함께 배치되도록 기능에 대한 엔드포인트 가시성을 설정하십시오. function get 명령을 사용하여 엔드포인트 정의를 반영하는 기능에 사용 가능한 URL을 확보할 수 있습니다.

콘솔에서 함수를 작성할 때 엔드포인트 설정을 사용하여 함수에 대한 엔드포인트의 가시성을 설정하십시오. 기능이 배치된 후 기능 페이지의 도메인 맵핑 탭에서 이러한 시스템 도메인 맵핑 설정을 보고 수정할 수 있습니다.

이 설정을 사용하는 기능은 동일한 Code Engine 프로젝트의 컴포넌트에서 요청을 수신할 수 있습니다. 그러나 함수는 내부 경로를 사용하여 다른 작업이나 애플리케이션을 호출할 수 없습니다.

공용 엔드포인트로 함수 배포하기

기능을 배치할 때 기본적으로 기능은 공용 인터넷 또는 동일한 Code Engine 프로젝트 내의 컴포넌트에서 요청을 수신할 수 있습니다. 이 경우 이 기능은 공용 엔드포인트와 함께 배포됩니다.

비공개 엔드포인트로 함수 배포하기

개인용 엔드포인트를 사용하여 배치할 기능에 대한 엔드포인트 가시성을 설정할 수 있습니다. 함수에 대해 비공개 엔드포인트를 설정하면 공용 인터넷에서는 액세스할 수 없으며 동일한 프로젝트(클러스터-로컬)에서 실행 중인 다른 IBM Cloud 서비스(가상 사설 엔드포인트) 또는 Code Engine 구성 요소(클러스터-로컬)에서만 네트워크에 액세스할 수 있습니다.

예를 들어 솔루션이 자체 가상 사설 엔드포인트 내의 IBM Cloud Kubernetes Service Kubernetes 클러스터에서 실행되는 구성 요소로 구성되어 있고 IBM Cloud 사설 네트워크에서 Code Engine 기능에 액세스하려는 경우 해당 기능의 가시성을 비공개로 설정할 수 있습니다. 기능의 공개 여부가 비공개로 설정되어 있으면 공용 인터넷을 통해 해당 기능에 액세스할 수 없습니다. 이 함수는 프로젝트 내의 다른 함수에서 계속 액세스할 수 있습니다.

IBM Cloud 사설 네트워크를 통해서만 기능이 노출되고 외부 인터넷에는 노출되지 않도록 사설 엔드포인트를 사용하여 기능을 작성 할 수 있습니다. 이 기능은 여전히 내부 네트워크 내에서 공유 구성 요소를 통해 액세스할 수 있으며 해당 기능의 엔드포인트를 보호해야 합니다.

CLI를 사용하여 function create 또는 function update 명령에서 --visibility=private 옵션을 사용하여 개인용 엔드포인트와 함께 배치되도록 기능에 대한 엔드포인트 가시성을 설정하십시오. function get 명령을 사용하여 엔드포인트 정의를 반영하는 기능에 사용 가능한 URL을 확보할 수 있습니다.

사설 네트워크를 통한 연결에 대한 자세한 정보는 Code Engine에서 가상 사설 엔드포인트 사용을 참조하십시오.

함수 작성 옵션

함수를 만들 때 지정할 수 있는 옵션에 대해 알아보세요. 옵션은 콘솔 또는 CLI를 사용하는지에 따라 다를 수 있습니다.

메모리 및 CPU

함수를 배포할 때 함수가 사용할 수 있는 메모리와 CPU의 양을 지정할 수 있습니다. 이러한 양은 함수가 컴퓨팅 집약적인지, 메모리 집약적인지 또는 균형 잡힌지에 따라 달라질 수 있습니다.

기본적으로 함수에는 4G의 메모리와 1.0 vCPU. 기타 지원되는 메모리 및 CPU 조합에 대한 자세한 정보는 기능에 대해 지원되는 메모리 및 CPU 조합 을 참조하십시오.

환경 변수를 사용하여 함수 생성 및 실행하기

런타임에 함수에서 사용할 수 있는 키-값 쌍으로 환경 변수를 정의하고 설정할 수 있습니다.

함수를 만들 때 또는 CLI로 기존 함수를 업데이트할 때 환경 변수를 정의할 수 있습니다.

환경 변수 정의에 대한 자세한 정보는 환경 변수 작업을 참조하십시오.

Code Engine 는 특정 환경 변수를 함수에 자동으로 삽입합니다. 자동으로 삽입된 환경 변수에 대한 자세한 정보는 자동으로 삽입된 환경 변수를 참조하십시오.

시크릿 및 컨피그맵을 사용할 때 함수 생성 및 실행하기

Code Engine 에서 환경 변수를 사용하여 함수에서 시크릿과 컨피그맵을 사용할 수 있습니다.

시크릿과 configmap 모두는 키-값 쌍입니다. 환경 변수로 맵핑되면, 환경 변수 이름이 해당 맵에 있는 각 항목의 "키"에 해당하고, 환경 변수 값은 해당 키의 "값"인 것과 같이 NAME=VALUE 관계가 설정됩니다.

함수는 환경 변수를 사용하여 컨피그맵(또는 시크릿)을 완전히 참조하거나 컨피그맵(또는 시크릿)의 개별 키를 참조할 수 있습니다.

자세한 정보는 환경 변수를 사용하여 시크릿 참조 및 환경 변수를 사용하여 configmap 참조를 참조하십시오.

함수 할당량에 대한 고려사항

애플리케이션, 기능 및 일괄처리 작업에 대해 작업할 때 이러한 자원은 Code Engine 프로젝트의 컨텍스트 내에서 실행됩니다. 자원 할당량은 프로젝트별로 정의되며 애플리케이션, 기능 및 일괄처리 작업에 대한 제한이 적용됩니다.

Code Engine 한계에 대한 자세한 정보는 Code Engine의 한계 및 할당량을 참조하십시오.

다음 단계

이제 Code Engine 기능에 대한 작업의 주요 개념에 익숙하게 되었으므로 기능을 작성하고 이에 대해 작업할 준비가 되었습니까? 다음 주제를 참조하십시오.

함수 작업에 대한 자세한 내용은 다음 주제를 참조하세요.