Resource Downloader

Currently, we provide two resource downloader init containers for NGC and for manual uploading. These containers allow you to download the resource files (e.g an avatar USD scene) onto the persistent volume of the microservice pod. Alternatively, you have the option to create your own init container to download the resources from any remote storage.

NGC Resource Downloader

NGC is an NVIDIA file storage system. The ngc-resource-downloader init container will download resources from NGC. For that, a NGC resource path and a secret with the NGC API key need to be provided in the params section of the microservice using the resource downloader.

resourceDownload:
  remoteResourcePath: nvidia/ucs-ms/default-avatar-scene:1.0.0
  secretName: ngc-api-key-secret
  image: nvcr.io/eevaigoeixww/animation/ngc-resource-downloader:1.0.1

Before deploying the UCS app, you must create a Kubernetes secret. The secret.yaml configuration should look like the following snippet.

apiVersion: v1
data:
  NGC_CLI_API_KEY: "******"
kind: Secret
metadata:
  name: ngc-api-key-secret
  namespace: animation-pipeline
type: Opaque

Prerequisites

Before you upload assets to NGC space, you have to download & install NGC CLI.

Also, make sure that you have access to NGC and you know your <ORG> and <TEAM> you would like to upload your asset to. If you don’t have access to NGC, reach out to your NVIDIA contact or to the NVIDIA support or use an alternative download method.

Create a Resource in NGC for the Asset

Use the following command to create a new resource with the name <RESOURCE_NAME> for your asset:

ngc registry resource create <ORG>/<TEAM>/<RESOURCE_NAME> --application OTHER --framework Other --format usda --precision Other --short-desc "Scene asset files for ACE"

For example, to create a resource in <ORG> (lypzw7yma4rr), <TEAM> (your-ngc-team), <RESOURCE_NAME> (avatar_scene), use:

ngc registry resource create lypzw7yma4rr/your-ngc-team/avatar_scene --application OTHER --framework Other --format usda --precision Other --short-desc "Scene asset files for ACE"

Uploading a Version to the NGC Resource

To upload a version (e.g. 1) to the resource, make sure that the asset files are inside a single local folder, e.g. the /exported directory created by the Avatar Configurator including the scene file Avatar_Scene.usd and all the dependencies like textures.

To upload the resource files, provide the local <folder>’s path as an argument to the following command:

ngc registry resource upload-version lypzw7yma4rr/your-ngc-team/avatar_scene:1 --source <folder>

To download a resource, use:

ngc registry resource download-version "lypzw7yma4rr/your-ngc-team/avatar_scene:1"

To remove a version, use:

ngc registry resource remove lypzw7yma4rr/your-ngc-team/avatar_scene:1

Warning

Currently there is a known issue with NGC client 3.22.0 (and potentially earlier versions) on Windows that does not upload folders with nested sub-folders correctly. Until this is fixed, you will need to use a Linux/Ubuntu system to upload scenes to NGC.

Manual Resource Downloader

This manual-resource-downloader init container waits until the resources have been manually uploaded to the persistent volume. The resources need to be uploaded to the path that is passed in the environment variable DESTINATION_RESOURCE_PATH=<persistent-volume-mount-path>. After the resources have been uploaded, confirm this by adding a file called manual_resource_uploaded.txt.

In the params of the UCS app, no resource path need to be provided, as the upload is completely manual. A secret needs to be provided, even if it is not used. In that case, just create an empty dummy-secret.

resourceDownload:
  remoteResourcePath: ""
  secretName: dummy-secret
  image: nvcr.io/eevaigoeixww/animation/manual-resource-downloader:1.0.1

Here is an example with kubectl how resources could be uploaded:

  1. Get the DESTINATION_RESOURCE_PATH environment variable to your local computer.

DESTINATION_RESOURCE_PATH=$(kubectl get pod -n <your-namespace> <your-pod-name> -o jsonpath="{.spec.initContainers[?(@.name=='init')].env[?(@.name=='DESTINATION_RESOURCE_PATH')].value}")

  1. Copy the files from your local computer to the pod to the DESTINATION_RESOURCE_PATH.

cd <your-local-directory>
kubectl cp . -c init -n <your-namespace> <your-pod-name>:$DESTINATION_RESOURCE_PATH

  1. Verify the files are there.

kubectl exec -n <your-namespace> -c init <your-pod-name> -- ls -alh $DESTINATION_RESOURCE_PATH

  1. Create a file called manual_resource_uploaded.txt in the DESTINATION_RESOURCE_PATH to confirm the upload succeeded.

kubectl exec -n <your-namespace> -c init <your-pod-name> -- touch $DESTINATION_RESOURCE_PATH/manual_resource_uploaded.txt

  1. The init container will then complete and the microservice will start.

Create Your Own Resource Downloader

To create your own init container to download the resources from anywhere you want, you just need to provide a download_resource.sh in the working directory.

The UCS app will then use your init container to download the resources.

  • The remoteResourcePath is available as REMOTE_RESOURCE_PATH environment variable.

  • The mount path of the persistent volume is available as DESTINATION_RESOURCE_PATH environment variable.

  • The values in the secret are available as environment variables, exactly as they are stated in the secret.

Here is an extract of the UCS manifest.yaml of an microservice using the resource downloader for illustration purposes.

image: "(($params.resourceDownload.image))"
imagePullPolicy: IfNotPresent
env:
  - name: REMOTE_RESOURCE_PATH
    value: "(($params.resourceDownload.remoteResourcePath))"
  - name: DESTINATION_RESOURCE_PATH
    value: "{{ .persistentVolume.mountPath }}"
envFrom:
  - secretRef:
      name: "(($params.resourceDownload.secretName))"
command: ["/bin/bash", "download_resource.sh"]

Your dockerfile could look something like this. In the download_resource.sh you can freely script the download of the resources.

FROM ubuntu:22.04
WORKDIR /home/my-user
COPY download_resource.sh .
ENTRYPOINT ["/bin/bash", "download_resource.sh"]

Here is an example, how you would add your own init container as params to the UCS app.

resourceDownload:
  remoteResourcePath: my-resource-path
  secretName: my-secret
  image: my-resource-downloader:1.2.3