Using Cloud Functions

API

View as Markdown

This page provides a brief overview of the NVCF API. All API endpoints are served through your gateway. See gateway-routing for details on configuring your gateway domain and DNS.

OpenAPI Specification

This page does not cover all endpoints.

Please refer to the OpenAPI Spec for the latest API information.

The OpenAPI spec linked above documents the full NVCF API surface. Replace the hosted domain with your own gateway domain when making requests. See gateway-routing for your deployment’s base URL.

The NVCF API is divided into the following sets of APIs:

APIsUsage
Function InvocationExecution of a function that runs on a worker node. Usually an inference call.
Cluster Groups & GPUsDefines endpoints to list Cluster Groups and GPUs as targets for function deployment.
Function ManagementThe creation, modification and deletion of functions
Function DeploymentEndpoints for creating and managing function deployments.

API Versioning

All API endpoints include versioning in the path prefix.

$/v2/nvcf

Authorization

The NVCF API supports API key-based authorization. API keys can be generated using the CLI or directly via the API Keys service endpoint.

Generate an API Key

API keys can be generated using the CLI or directly via the API Keys service. There are two types of API keys:

Using the CLI

The simplest way to generate an API key is via the CLI:

$nvcf-cli api-key create

Refer to the CLI documentation for full usage and additional token generation options.

Admin Token

An admin token provides full access to all NVCF API endpoints. This is useful for initial setup, managing functions, and administrative tasks.

$export GATEWAY_ADDR=<your-gateway-address>
$
$export NVCF_TOKEN=$(curl -s -X POST "http://${GATEWAY_ADDR}/v1/admin/keys" \
>  -H "Host: api-keys.${GATEWAY_ADDR}" \
>  | grep -o '"value":"[^"]*"' | cut -d'"' -f4)
$
$echo "Token generated: ${NVCF_TOKEN:0:20}..."

Scoped API Key

A scoped API key restricts access to specific operations and resources. This is recommended for application use, such as invoking functions.

$EXPIRES_AT=$(date -u -v+1d '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u -d '+1 day' '+%Y-%m-%dT%H:%M:%SZ')
$SERVICE_ID="nvidia-cloud-functions-ncp-service-id-aketm"
$
$export API_KEY=$(curl -s -X POST "http://${GATEWAY_ADDR}/v1/keys" \
>  -H "Host: api-keys.${GATEWAY_ADDR}" \
>  -H "Content-Type: application/json" \
>  -H "Key-Issuer-Service: nvcf-api" \
>  -H "Key-Issuer-Id: ${SERVICE_ID}" \
>  -H "Key-Owner-Id: test@nvcf-api.local" \
>  -d '{
>    "description": "invocation key",
>    "expires_at": "'"${EXPIRES_AT}"'",
>    "authorizations": {
>      "policies": [{
>        "aud": "'"${SERVICE_ID}"'",
>        "auds": ["'"${SERVICE_ID}"'"],
>        "product": "nv-cloud-functions",
>        "resources": [
>          {"id": "*", "type": "account-functions"},
>          {"id": "*", "type": "authorized-functions"}
>        ],
>        "scopes": ["invoke_function", "list_functions", "list_functions_details"]
>      }]
>    },
>    "audience_service_ids": ["'"${SERVICE_ID}"'"]
>  }' | jq -r '.value')
$
$echo "API Key: ${API_KEY:0:20}..."

The scopes array controls which API operations the key can perform. See self-hosted-scopes for the full list. The expires_at field is required for scoped API keys.

API Key Usage

Both key types are passed in the Authorization header.

$Authorization: Bearer $API_KEY

API Key Scopes

The OpenAPI Spec describes the scopes required for each endpoint.

Scope NameAPI Category
update_functionFunction Management
register_functionFunction Management
list_functionsFunction Management
list_cluster_groupsCluster Groups and GPUs
invoke_functionFunction Invocation
deploy_functionFunction Deployment
delete_functionFunction Management