Copy page

Unidades

Nombres privados

Los servicios del mismo proyecto pueden hablar entre sí por una red privada, usando nombres en lugar de direcciones. Nada de esto sale de la región y nada de esto se factura. Esta página es la referencia de esos nombres; la guía de la red de Minecraft los usa de principio a fin.

Dos tipos de nombre

Para un Workload (un Worker, una Web App, cualquier cosa que ejecute unidades) con el slug lobby:

nombre	llega a
lobby	todas las unidades listas. El DNS responde con todas sus direcciones, así que un cliente que elija una se reparte entre ellas. Úsalo para las peticiones normales.
<clave>.lobby	una unidad concreta, por su clave: u1.lobby, u2.lobby, ... para las unidades que crea la política de escalado, o un nombre que elijas tú, como duel-77.lobby, para las unidades que crea tu código.

La key de una unidad y su private_name completo son campos de la unidad en la API de Units, así que un programa nunca tiene que construir un nombre a mano:

Code
{ "key": "u2", "private_name": "u2.lobby", "state": "running" }

La clave es estable mientras viva la unidad. Cuando una unidad se retira, su nombre deja de resolverse, y una unidad posterior puede ocupar la misma clave.

Las reglas

1. Solo dentro del mismo proyecto. Cada proyecto es su propia red aislada. Una unidad llega a cualquier otra unidad de su proyecto, en cualquier puerto, y a nada de otro proyecto. Un nombre nunca se resuelve fuera del proyecto que lo posee, y no existen nombres entre proyectos.
2. El slug debe empezar por una letra. El nombre es una etiqueta DNS, y el DNS exige que el nombre de un servicio empiece por una letra (una etiqueta DNS-1035). Un Workload cuyo slug empieza por un dígito, por ejemplo 1api, simplemente no recibe nombre privado: sus unidades tienen private_name: null. Renómbralo a api1 o lobby y el nombre aparece. Renombrar mueve el nombre, lo que sustituye las unidades mediante el despliegue progresivo normal.
3. Solo responden las unidades listas. Una unidad que está arrancando, fallando o parada queda fuera de lobby, y <clave>.lobby no se resuelve hasta que esa unidad esté lista.
4. Un nombre por slug. El slug es único dentro de un proyecto, así que el nombre también. Si la plantilla de un producto ya usa el slug como nombre de un servicio de red, el Workload conserva ese y no recibe nombre privado.

Un nombre no publica un puerto

Un nombre privado es solo un nombre. No abre, reenvía ni reparte ningún puerto: te conectas al nombre en el puerto en el que escucha tu programa, por ejemplo u1.lobby:25565, igual que con un nombre de host en una LAN. Dos consecuencias:

• Nunca declaras un puerto para que funcione un nombre privado. Cualquier puerto en el que escuche la unidad es accesible desde el mismo proyecto.
• No es una dirección pública. Para dejar entrar a internet usa un endpoint, que es un objeto aparte y facturado.

Cuándo usar cada uno

• Otro servicio llamando a tu API: usa api. Cuando las unidades van y vienen, el nombre siempre apunta a las que están listas.
• Algo que debe hablar con una copia concreta, por ejemplo un coordinador que le dice a la unidad 3 que se vacíe, o un proxy de juego que envía jugadores a un servidor conocido: usa u3.lobby.
• Un nombre no mantiene una petición en la misma unidad: dos conexiones a lobby pueden llegar a dos unidades distintas, así que no cuentes con que una unidad recuerde la petición anterior.

Ejemplos

Code
# desde una shell en cualquier unidad del mismo proyecto
getent hosts lobby          # una línea por unidad lista
getent hosts u2.lobby       # la dirección de esa unidad
nc -vz u2.lobby 25565       # accesible en cualquier puerto en el que escuche la unidad

Code
// Node: conectar con un backend concreto por su nombre privado
import net from "node:net";
const socket = net.connect({ host: "u2.lobby", port: 25565 });

Code
import socket
# cualquier unidad lista del Workload `lobby`
sock = socket.create_connection(("lobby", 25565), timeout=3)

En el modo código, las unidades que crees desde código tienen las claves que elijas tú, como duel-77.lobby.