Nuclio es una plataforma serverless de código abierto pensada para procesar eventos y datos con baja latencia. Cada función se empaqueta como una imagen de contenedor y se ejecuta con un procesador que puede atender varias peticiones en paralelo. En este tutorial instalarás Nuclio en modo Docker (la plataforma local) sobre Ubuntu 24.04, accederás al dashboard web de forma segura y desplegarás una función Python con disparadores HTTP y cron usando la CLI nuctl.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS de 64 bits (x86_64), por ejemplo un VPS de CubePath.
  • Un usuario no root con privilegios sudo.
  • Al menos 2 vCPU y 4 GB de RAM: cada despliegue construye una imagen de contenedor.
  • Docker Engine instalado desde el repositorio oficial, con tu usuario en el grupo docker.
  • jq y curl instalados (sudo apt install jq curl).

Paso 1: Comprobar Docker

Nuclio usa el socket de Docker para construir las imágenes de las funciones y lanzar sus contenedores, así que Docker debe estar activo y tu usuario debe poder usarlo sin sudo:

docker version --format '{{.Server.Version}}'
docker run --rm hello-world

28.4.0
...
Hello from Docker!
This message shows that your installation appears to be working correctly.

Si recibes permission denied while trying to connect to the Docker daemon socket, añade tu usuario al grupo docker y vuelve a iniciar sesión:

sudo usermod -aG docker "$USER"

Paso 2: Elegir la versión de Nuclio

El dashboard y la CLI nuctl deben tener la misma versión. Consulta la última versión publicada en GitHub y guárdala en una variable para los pasos siguientes:

NUCLIO_VERSION=$(curl -s https://api.github.com/repos/nuclio/nuclio/releases/latest | jq -r .tag_name)
echo "$NUCLIO_VERSION"

1.15.4

Tu número será distinto; lo importante es que no aparezca null. Si ves null, has alcanzado el límite de peticiones anónimas de la API de GitHub: consulta la versión en https://github.com/nuclio/nuclio/releases y asígnala a mano con NUCLIO_VERSION=x.y.z.

Paso 3: Arrancar el dashboard de Nuclio

El dashboard es el componente central en modo Docker: sirve la interfaz web, expone la API y orquesta las construcciones y despliegues. Lánzalo como contenedor con el socket de Docker montado, usando la imagen de la versión elegida:

docker run -d \
  --name nuclio-dashboard \
  --restart unless-stopped \
  -p 127.0.0.1:8070:8070 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  "quay.io/nuclio/dashboard:${NUCLIO_VERSION}-amd64"

El puerto se publica solo en 127.0.0.1 a propósito: el dashboard no tiene autenticación y, con acceso al socket de Docker, cualquiera que llegue a él podría ejecutar contenedores en tu servidor. Además, Docker inserta sus propias reglas de iptables, por lo que un puerto publicado en todas las interfaces quedaría accesible aunque UFW lo bloquee.

Comprueba que el contenedor está en marcha y que responde por HTTP:

docker ps --filter name=nuclio-dashboard
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8070/

CONTAINER ID   IMAGE                                  STATUS         PORTS                      NAMES
3f2a9c1d7b44   quay.io/nuclio/dashboard:1.15.4-amd64  Up 2 minutes   127.0.0.1:8070->8070/tcp   nuclio-dashboard
200

Si el contenedor se reinicia en bucle, revisa docker logs --tail 50 nuclio-dashboard.

Paso 4: Acceder al dashboard mediante un túnel SSH

Como el dashboard solo escucha en localhost, accede a él desde tu equipo con un túnel SSH. Ejecuta este comando en tu máquina local, sustituyendo your_user y your_server_ip:

ssh -N -L 8070:127.0.0.1:8070 your_user@your_server_ip

Mientras el túnel esté abierto, abre http://localhost:8070 en el navegador. Verás la pantalla de proyectos de Nuclio con el proyecto default. Desde aquí puedes crear funciones a partir de plantillas, editarlas en línea y consultar sus logs, pero en este tutorial usarás la CLI para que el proceso sea reproducible.

Paso 5: Instalar la CLI nuctl

Descarga el binario de nuctl de la misma versión, instálalo en /usr/local/bin y comprueba que funciona:

curl -fLo nuctl "https://github.com/nuclio/nuclio/releases/download/${NUCLIO_VERSION}/nuctl-${NUCLIO_VERSION}-linux-amd64"
sudo install -m 0755 nuctl /usr/local/bin/nuctl
rm nuctl
nuctl version

La salida muestra la versión del cliente, que debe coincidir con $NUCLIO_VERSION.

Paso 6: Escribir una función Python

Crea un directorio para la función. Nuclio trata el nombre del archivo como un módulo de Python, así que usa un nombre sin guiones, como main.py:

mkdir -p ~/nuclio/saludo
nano ~/nuclio/saludo/main.py

Añade este código. El manejador recibe el context (logger y utilidades) y el event (cuerpo, cabeceras, método y tipo de disparador):

import json


def handler(context, event):
    trigger = event.trigger.kind
    context.logger.info_with("Evento recibido", trigger=trigger)

    if trigger == "cron":
        return "tick"

    try:
        data = json.loads(event.body) if event.body else {}
    except ValueError:
        return context.Response(body="JSON no válido", status_code=400)

    nombre = data.get("nombre", "mundo")
    return context.Response(
        body=json.dumps({"mensaje": f"Hola, {nombre}", "trigger": trigger}),
        headers={},
        content_type="application/json",
        status_code=200,
    )

Ahora describe la función en function.yaml, en el mismo directorio. Este archivo define el runtime, el manejador, las variables de entorno y los disparadores:

nano ~/nuclio/saludo/function.yaml

apiVersion: "nuclio.io/v1"
kind: "NuclioFunction"
metadata:
  name: saludo
spec:
  runtime: "python:3.11"
  handler: "main:handler"
  env:
    - name: LOG_LEVEL
      value: "info"
  triggers:
    http:
      kind: http
      maxWorkers: 4
    cada-minuto:
      kind: cron
      attributes:
        interval: "1m"
  • handler: "main:handler" indica el módulo (main.py) y la función a invocar.
  • maxWorkers: 4 permite que la función atienda hasta cuatro peticiones HTTP en paralelo.
  • El disparador cron invoca la función cada minuto, útil para tareas periódicas.

Si tu función necesita paquetes de pip, añádelos en spec.build.commands, por ejemplo - "pip install requests". Se ejecutan al construir la imagen, no en cada invocación.

Paso 7: Desplegar la función

Despliega la función en la plataforma local (Docker). nuctl lee function.yaml del directorio indicado en --path, construye la imagen y arranca el contenedor:

nuctl deploy saludo --path ~/nuclio/saludo --platform local

El primer despliegue tarda algo más porque descarga las imágenes base de Python. Al terminar verás una línea similar a:

Function deploy complete {"functionName": "saludo", "httpPort": 32768, ...}

Lista las funciones para ver su estado y el puerto HTTP asignado en el host:

nuctl get function --platform local

  NAMESPACE | NAME   | PROJECT | STATE | REPLICAS | NODE PORT
  nuclio    | saludo | default | ready | 1/1      |     32768

La función también aparece en el dashboard, dentro del proyecto default.

Paso 8: Invocar y probar la función

Invoca la función con nuctl, que resuelve el puerto por ti:

nuctl invoke saludo \
  --platform local \
  --method POST \
  --content-type application/json \
  --body '{"nombre": "CubePath"}'

> Response headers:
Content-Type = application/json
...
> Response body:
{
    "mensaje": "Hola, CubePath",
    "trigger": "http"
}

También puedes llamarla directamente con curl usando el NODE PORT del paso anterior:

curl -s -X POST http://127.0.0.1:32768 \
  -H 'Content-Type: application/json' \
  -d '{"nombre": "curl"}'

{"mensaje": "Hola, curl", "trigger": "http"}

Para confirmar que el disparador cron funciona, localiza el contenedor de la función y revisa sus logs pasado al menos un minuto:

FN_CONTAINER=$(docker ps --filter name=saludo --format '{{.Names}}' | head -n 1)
docker logs --tail 5 "$FN_CONTAINER"

{"level":"info","time":"...","name":"saludo.cada-minuto","message":"Evento recibido","trigger":"cron"}

Paso 9: Actualizar y eliminar funciones

Para publicar una nueva versión, edita main.py o function.yaml y vuelve a ejecutar el mismo nuctl deploy. Nuclio reconstruye la imagen y sustituye el contenedor:

nuctl deploy saludo --path ~/nuclio/saludo --platform local

Para ver la configuración completa que Nuclio tiene guardada de una función:

nuctl get function saludo --platform local --output yaml

Y para eliminarla, junto con su contenedor:

nuctl delete function saludo --platform local

Exponer una función al exterior

El puerto que Docker asigna a cada función puede cambiar al redesplegar, por lo que no conviene publicarlo directamente. La opción recomendada es un proxy inverso como Nginx o Caddy en el mismo servidor, con TLS, que reenvíe una ruta o subdominio al puerto de la función. Mantén el dashboard (puerto 8070) siempre fuera de ese proxy o protégelo con autenticación.

Solución de problemas

nuctl deploy falla con Cannot connect to the Docker daemon. Tu usuario no pertenece al grupo docker o no has vuelto a iniciar sesión tras añadirlo. Comprueba con groups que aparece docker.

La función queda en estado error o el build falla. Revisa la salida completa del despliegue con más detalle:

nuctl deploy saludo --path ~/nuclio/saludo --platform local --verbose

Los errores más habituales son un handler que no coincide con el nombre del archivo o de la función, o un paquete de build.commands que no existe.

El runtime no está soportado. Si ves un error sobre python:3.11, consulta los runtimes disponibles para tu versión de Nuclio en el dashboard (al crear una función) y ajusta spec.runtime.

El dashboard no arranca tras reiniciar el servidor. Comprueba que el servicio Docker está habilitado con sudo systemctl is-enabled docker y revisa docker logs nuclio-dashboard.

Conclusión

Tienes Nuclio funcionando en modo Docker en Ubuntu 24.04, con el dashboard protegido tras un túnel SSH y una función Python desplegada con disparadores HTTP y cron. Como siguientes pasos, puedes añadir disparadores de colas como Kafka o NATS en function.yaml, publicar tus funciones detrás de Nginx con HTTPS o, si necesitas varios nodos y autoescalado, migrar a Nuclio sobre Kubernetes con su chart de Helm.