Hugging Face API Key Secret

Create a Kubernetes secret that stores a Hugging Face API token so NeMo microservices can authenticate with the Hugging Face Hub (download, upload, and reference private models).

Important

By default, Kubernetes secrets are not encrypted. To secure your secrets, refer to Kubernetes secret best practices in the Kubernetes documentation.

Secret values aren’t visible through pod specs. Use a secrets management solution such as Vault with the External Secrets Operator to inject secrets into the target Kubernetes project securely.

Prerequisites

• A valid Hugging Face API token with access to your organization’s models and repositories.

• The target Kubernetes project where you deploy NeMo.

Create the Secret

The example below creates a generic secret named hf-secret containing the token under the key HF_TOKEN.

kubectl create secret generic hf-secret \
  --namespace <NAMESPACE> \
  --from-literal=HF_TOKEN=$HUGGINGFACE_HUB_TOKEN

If your token is in a different environment variable (for example, HF_TOKEN), replace $HUGGINGFACE_HUB_TOKEN accordingly.

Reference the Secret in values.yaml

Configure the customization workflow to use the secret and enable Hugging Face downloads by setting these values. The chart reads the secret name and key from .customizer.hfAPISecret and .customizer.hfAPISecretKey.

customizer:
  hfAPISecret: "hf-secret"      # Kubernetes Secret name
  hfAPISecretKey: "HF_TOKEN"   # Key in the Secret that holds the token
  
  customizationTargets:
    hfTargetDownload:
      # Enable model downloads from Hugging Face
      enabled: true
      # List of allowed organizations for model downloads
      # Empty list allows all organizations
      allowedHfOrgs:
        - "nvidia"
        - "meta-llama"
        # Add other organizations as needed

Important

Both the secret reference and hfTargetDownload.enabled: true are required. The secret alone does not enable Hugging Face downloads.

Ensure the secret exists in the same installation project as the chart.

Verify the Secret

Run the following command to confirm the secret and key are present, then decode the value:

kubectl get secret hf-secret -n <NAMESPACE> \
  -o jsonpath='{.data.HF_TOKEN}' | base64 --decode; echo

Rotate or Update the Token

Update the secret without downtime by applying a new value:

kubectl -n <NAMESPACE> create secret generic hf-secret \
  --from-literal=HF_TOKEN=$NEW_HUGGINGFACE_HUB_TOKEN \
  --dry-run=client -o yaml | kubectl apply -f -

Where This Applies

NeMo’s model customization workflows require a Hugging Face token to download models with huggingface-cli and to upload to your organization’s Hugging Face repositories during import. For a full example, refer to the Import a Hugging Face model tutorial.