Variables de entorno
Las variables de entorno son la forma en que una plantilla configura la carga de trabajo que hay dentro: un token de Hugging Face, el nombre de un modelo, un nivel de log. Agréguelas en la sección Entorno del formulario de la plantilla, una clave y un valor por fila, con un interruptor Secreto a la derecha.
Cómo definirlas
| Parte | Reglas |
|---|---|
| Clave | Hasta 256 caracteres. Las filas con la clave en blanco se descartan al guardar. |
| Valor | Cualquier cadena. Dejarlo vacío guarda la entrada como no definida. |
| Secreto | Enmascara el valor para cualquiera fuera de la organización propietaria. |
Una entrada sin valor no se inyecta en el contenedor en absoluto. Eso la convierte en un buen marcador de posición: declare HF_TOKEN como secreta y sin valor, y la plantilla documenta lo que debe aportar el arrendatario sin entregarle un token a todo el que la lea.
A través de la API, env es una lista de objetos en POST /v1/templates y PATCH /v1/templates/{id}:
{
"env": [
{ "key": "MODEL_ID", "value": "meta-llama/Llama-3-8B", "secret": false },
{ "key": "HF_TOKEN", "value": null, "secret": true }
]
}
Enviar env en un PATCH reemplaza la lista completa. No hay actualización por clave.
Enmascaramiento de secretos
Un valor secreto solo se devuelve a la organización propietaria de la plantilla. Todos los demás — incluido quien navegue por su plantilla pública, e incluidos los lectores de una plantilla de sistema seleccionada — reciben value: null con la marca secret intacta. La consola muestra la clave con un marcador de posición oculto en lugar del valor.
El enmascaramiento sigue a los datos, no al endpoint: GET /v1/templates, GET /v1/templates/{id} y GET /v1/templates/by-hash/{hash_id} lo aplican todos.
Dos consecuencias que conviene conocer:
- Duplicar una plantilla que no pertenece a su organización deja en blanco todos los valores secretos de la copia. Usted nunca tuvo acceso de lectura a ellos, y convertirse en propietario de la copia no debe cambiar eso. Duplicar su propia plantilla los conserva.
- Marcar como secreto un valor existente lo oculta de ahí en adelante, pero no lo deja de compartir con quien ya lo haya leído. Rote la credencial en su lugar.
Sustituciones del arrendatario en el despliegue
Un despliegue puede agregar o reemplazar entradas de entorno con env_overrides en POST /v1/instances:
{
"offer_id": "…",
"template_id": "…",
"disk_gb": 100,
"env_overrides": [{ "key": "HF_TOKEN", "value": "hf_…", "secret": true }]
}
Primero se aplica el env de la plantilla y después las sustituciones, emparejadas por clave — la sustitución gana. Las entradas con valor null en cualquiera de los dos lados se descartan en lugar de inyectarse como cadena vacía. Así es como rellena un marcador de posición secreto sin editar la plantilla, y así mantiene su token fuera de una receta compartida.
La capa de la plataforma siempre prevalece
Después de fusionar el env de la plantilla y las sustituciones del arrendatario, Superheat aplica una capa de la plataforma, y esa capa se aplica al final. Una clave de la capa no puede quedar eclipsada por un valor de la plantilla ni por una entrada de env_overrides — lo que usted defina se reemplaza sin aviso.
| Variable | Se define cuando | Contiene |
|---|---|---|
CONTAINER_ID | siempre | el identificador de la carga de trabajo |
GPU_COUNT | siempre | cuántas GPU se asignan a esta instancia |
SUPERHEAT_TCP_PORT_<n> | por cada puerto TCP publicado | el puerto del host al que se asigna el puerto de contenedor <n> |
PUBLIC_KEY | ssh, jupyter, cuando adjunta una clave SSH al desplegar | su clave pública SSH |
SUPERHEAT_SSH_PUBLIC_KEYS | ssh, jupyter, cuando adjunta una clave SSH al desplegar | el mismo material de clave, en la forma separada por saltos de línea |
SUPERHEAT_ONSTART | ssh, jupyter, cuando está definido | el cuerpo del script de inicio |
OPEN_BUTTON_PORT | ssh, jupyter, cuando un puerto lleva la etiqueta open | el puerto destino del botón Abrir |
JUPYTER_TOKEN | jupyter | el token de acceso generado por la plataforma |
JUPYTER_PORT | jupyter | 8080 |
JUPYTER_DIR | jupyter | el directorio de trabajo de Jupyter de la plantilla |
JUPYTER_LAB | jupyter | true para JupyterLab, false para el notebook clásico |
Así que definir JUPYTER_TOKEN en una plantilla no hace nada: la plataforma genera el token para poder construir la URL del botón Abrir, y el token nunca vuelve por el cable. Definir GPU_COUNT tampoco hace nada — refleja el bloque que alquiló realmente, y a un programa que confíe en él se le estaría mintiendo si el arrendatario pudiera editarlo.
La sobrescritura es silenciosa. Si su código lee GPU_COUNT esperando su propio valor, obtendrá el de la plataforma, sin ningún error en ninguna parte.
Qué ve dentro del contenedor
En una imagen derivada de la base, sshd y Jupyter inician shells de login que no heredan el entorno del proceso del contenedor, así que el entrypoint escribe el entorno en /etc/environment y /etc/profile.d/superheat-env.sh. Sus variables, más CONTAINER_ID, GPU_COUNT y las entradas SUPERHEAT_TCP_PORT_*, están todas ahí cuando entra por SSH.
Los secretos de aprovisionamiento se excluyen deliberadamente de ambos archivos: SUPERHEAT_ONSTART, JUPYTER_TOKEN, PUBLIC_KEY y SUPERHEAT_SSH_PUBLIC_KEYS los consume el entrypoint y nunca se vuelven a exportar. Imprimir $JUPYTER_TOKEN en una sesión SSH no devuelve nada, y así es como está diseñado.