Tasks Quickstart#

This guide provides an end-to-end workflow for creating and launching a container-based Task on NVIDIA Cloud Functions (NVCF), using the tasks_sample container. This sample Task generates dummy output files and demonstrates how to report progress and results to NVCF. Unlike Functions, Tasks are one-and-done workloads that run to completion on a GPU-powered worker, ideal for tasks like model fine-tuning or TensorRT engine building.

Before beginning, ensure that you have created an NGC Personal API Key and authenticated with the NGC Docker Registry.

Clone, Build, and Push the Docker Image to NGC Private Registry#

Clone the sample repository and navigate to the tasks_sample directory.

git clone https://github.com/NVIDIA/nv-cloud-function-helpers.git

cd nv-cloud-function-helpers/examples/tasks_sample

ls

Verify the directoy output is correct:

Dockerfile  README.md  main.py  requirements.txt

Build the Docker image using the provided Dockerfile. Note that this will build the image for an amd64 architecture. For arm, platform should be linux/arm64.

docker buildx build . -t tasks_sample --platform linux/amd64

Tag and push the Docker image to your NGC Private Registry. Replace $ORG_NAME with your NGC organization name (e.g., qdrlnbkss123), which you can find in the NGC Organization Profile Page.

docker tag tasks_sample:latest nvcr.io/$ORG_NAME/tasks_sample:latest

docker push nvcr.io/$ORG_NAME/tasks_sample:latest

After pushing, verify the container appears in the NGC Private Registry Containers Page. It is now ready for use in Task creation.

Create & Launch the Task Using the Cloud Functions UI#

Navigate to the Cloud Functions UI, select “Create Task”, and choose “Custom Container”. Enter the Task details for tasks_sample:
- Name: my-sample-task
- Container Image: nvcr.io/$ORG_NAME/tasks_sample:latest
- GPU Specification: Select a GPU (e.g., L40S) and backend (e.g., GFN).
- Result Handling Strategy: Upload tasks to NGC Private Registry
- Results Location (Model Name): sample-task-results
- Personal API Key: Add your Personal API Key (with PRIVATE_REGISTRY scope) to upload results to NGC.
- Max Runtime Duration: 1 hour
- Max Queued Duration: 1 hour
- Termination Grace Period: 10 minutes
Leave other fields as default or adjust as needed.

After creation, the Task appears in the Tasks List with a QUEUED status. It will transition to LAUNCHED and RUNNING as it schedules and executes.

Monitor the Task’s progress in the UI. Once completed (COMPLETED status), verify the results in your NGC Private Registry at nvcr.io/$ORG_NAME/sample-task-results.

Create & Launch the Task Using the NGC CLI#

Ensure you have an API key (see Generate an NGC Personal API Key) and the NGC CLI configured.
You can list the avaible GPUs for the –gpu-specification option using the following command:

ngc cloud-function gpu list

Create the Task with the following command, replacing $ORG_NAME and $NGC_API_KEY:

ngc cloud-function task create \
--org $ORG_NAME \
--name my-sample-task \
--container-image nvcr.io/$ORG_NAME/tasks_sample:latest \
--gpu-specification L40S:gl40s_1.br25_2xlarge:GFN \
--result-handling-strategy UPLOAD \
--result-location $ORG_NAME/sample-task-results \
--secret NGC_API_KEY:$NGC_API_KEY \
--max-runtime-duration 1H \
--max-queued-duration 1H \
--termination-grace-period-duration 5M

This returns a taskId (e.g., 579ad430-34b9-4a6e-9537-a060db4a9e6c).

List Tasks to monitor its status:

ngc cloud-function task list

Retrieve Task details:

ngc cloud-function task info 579ad430-34b9-4a6e-9537-a060db4a9e6c

Once completed, verify results in your NGC Private Registry at nvcr.io/$ORG_NAME/sample-task-results. Additional CLI commands include:
- View events: ngc cloud-function task events 579ad430-34b9-4a6e-9537-a060db4a9e6c
- List results: ngc cloud-function task results 579ad430-34b9-4a6e-9537-a060db4a9e6c
- Cancel Task: ngc cloud-function task cancel 579ad430-34b9-4a6e-9537-a060db4a9e6c
See the NGC CLI Task Documentation for further details.

Understanding the Tasks Sample#

The tasks_sample container demonstrates key Task features:

Progress Reporting: It updates the progress file (NVCT_PROGRESS_FILE_PATH) with percentComplete, name, and optional metadata as it generates results. See progress File Format for details.
Result Generation: It creates dummy files in subfolders under NVCT_RESULTS_DIR (e.g., output_result_0/sample_file_0.txt), matching the name in the progress file.
Heartbeat: A background thread updates lastUpdatedAt every ~60 seconds to signal the Task is alive.
Customization: Environment variables like NUM_OF_RESULTS (default: 1), FILE_SIZE_BYTES (default: 1MB), and DELAY_BETWEEN_RESULTS_IN_MINUTES (default: 1) control behavior.

To test locally:

docker run -it -v ${PWD}:/tmp/output -e NVCT_RESULTS_DIR="/tmp/output" tasks_sample

Inspect the generated progress file and output files in the mounted directory.

Verifying Task Results#

After the Task completes (COMPLETED status), navigate to your NGC Private Registry at nvcr.io/$ORG_NAME/sample-task-results.
Expect subfolders like output_result_0 containing files (e.g., sample_file_0.txt) uploaded by the Task.
Use the CLI to list results:

ngc cloud-function task results 579ad430-34b9-4a6e-9537-a060db4a9e6c

Sample response:

{
    "taskId": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
    "ncaId": "test-nca-id",
    "taskName": "my-sample-task",
    "results": [
        {
            "id": "679ad430-44b9-5a6e-0537-b060db4a9e6c",
            "createdAt": "2025-03-04T10:00:00.000Z",
            "name": "output_result_0",
            "uri": "nvcr.io/$ORG_NAME/sample-task-results/output_result_0"
        }
    ]
}

Next Steps#

Explore Task Management and Execution for lifecycle details and API endpoints.
Customize the tasks_sample container by modifying main.py for your workload (e.g., fine-tuning or engine building).
Learn about Helm Chart Based Tasks for advanced use cases.