Introducción
Un indicador de funcionalidades es una configuración que activa o desactiva una funcionalidad sin cambiar el código de la aplicación. Imagine que prepara un nuevo banner de anuncio: quiere probarlo en su entorno de práctica mientras mantiene desactivada la versión pública. Workers KV almacena valores pequeños bajo nombres llamados claves. Un Worker puede leer una clave como banner:new cuando necesita decidir qué respuesta enviar. Esto resulta útil para configuraciones que se leen con frecuencia y se modifican ocasionalmente.
Antes de comenzar este curso, complete Conectar LabEx a su cuenta de Cloudflare. Allí se explican el terminal de la máquina virtual de LabEx, la autorización del dispositivo, la confirmación de la cuenta y account_id. Si accedió directamente a este curso, realice primero ese laboratorio. También debe saber escribir un Worker pequeño en JavaScript e implementarlo con Wrangler, como se explica en el curso de introducción a Workers. Un Worker ejecuta su código para gestionar solicitudes en Cloudflare sin que tenga que mantener un servidor.
Aquí creará un espacio de nombres, un contenedor con nombre que mantiene separada una colección de claves de las demás. Lo conectará a un Worker mediante una vinculación, que es el nombre configurado que utiliza el código para acceder a ese recurso. Practicará operaciones locales y en la nube, publicará un endpoint de solo lectura para el banner y eliminará los recursos temporales.
Utilice su propia cuenta de aprendizaje. Esta máquina virtual nueva necesita su propio inicio de sesión con permisos para Workers y KV. El ejercicio utiliza un Worker, un espacio de nombres y algunos valores sintéticos dentro de las asignaciones gratuitas de KV; no se necesita un dominio comprado ni una actualización de pago para este ejercicio pequeño. El uso existente de la cuenta sigue contando para sus asignaciones. El endpoint público no contiene información privada.
La configuración instala Node.js 22.22.0 y Wrangler 4.131.1, localizado en el proyecto, en /home/labex/project/feature-flags. Fija las versiones de las dependencias directas y ejecuta npm install; no necesita volver a instalar las herramientas. Mantenga la máquina virtual abierta hasta comprobar la eliminación en la nube y el cierre de sesión.
Conectar un espacio de nombres dedicado para los indicadores
En este paso, asignará a este laboratorio sus propios nombres de recursos y conectará un espacio de nombres de la nube al proyecto. Mantener un espacio de nombres separado evita que las claves de práctica se mezclen con las de una aplicación existente.
Entre en el proyecto preparado:
cd /home/labex/project/feature-flags
Genere un nombre único una sola vez. openssl rand -hex 6 imprime un sufijo aleatorio; $(...) lo inserta en el nombre. La variable de shell mantiene disponible ese nombre para los comandos siguientes de este terminal.
WORKER_NAME="labex-flags-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorice esta máquina virtual. Además de leer la identidad de su cuenta, Workers Scripts Write permite implementar y eliminar recursos, y Workers KV Write permite administrar el espacio de nombres y las claves de este laboratorio.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Abra en su navegador el enlace del dispositivo que se muestra, introduzca el código actual, revise los permisos solicitados y la cuenta de aprendizaje, y autorice Wrangler. En la página de consentimiento también puede aparecer el acceso en segundo plano. Vuelva al terminal y espere a que termine el inicio de sesión.
En la página de consentimiento, despliegue Developer Platform y compare los permisos solicitados con este ejemplo. Este laboratorio necesita ambos permisos de escritura; abarcan la administración de recursos, no solo la lectura de un indicador.
npx wrangler whoami --json
Confirme loggedIn: true y el name de la cuenta de aprendizaje, aunque solo aparezca una cuenta. Copie el id de esa cuenta. Guárdelo en la configuración siguiente: sustituya YOUR_ACCOUNT_ID antes de ejecutar el comando. El documento here-document de cat escribe en un archivo todo lo que se encuentra entre las dos líneas JSON; > reemplaza el archivo. Como el delimitador no está entre comillas, el shell puede insertar $WORKER_NAME.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
Cree un espacio de nombres en esa cuenta. Su título comparte el nombre único del Worker para que pueda reconocer ambos recursos más adelante. --update-config=false deja visible para usted la edición de la vinculación en lugar de modificar el archivo automáticamente.
npx wrangler kv namespace create "$WORKER_NAME-flags" --update-config=false
La salida incluye el ID del nuevo espacio de nombres. Cópielo y, en esta configuración completa, sustituya YOUR_ACCOUNT_ID y YOUR_NAMESPACE_ID. El nombre de la vinculación FLAGS se elige para que lo utilice el código; el ID identifica el recurso real de Cloudflare.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "FLAGS", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Busque el título del espacio de nombres de este laboratorio y compare su ID con el del archivo. Puede haber otros espacios de nombres; no los modifique. Esta configuración registra qué cuenta y qué recurso deben utilizar los comandos posteriores. Una vinculación es una referencia a un espacio de nombres, no una copia de sus datos.
Mantener separados los indicadores locales y remotos
En este paso, almacenará valores distintos bajo la misma clave y demostrará que las modificaciones locales no afectan a los datos de la nube. Local significa el almacenamiento dentro de esta máquina virtual de LabEx. Remoto significa el espacio de nombres de su cuenta de Cloudflare. Wrangler utiliza la vinculación para identificar el almacén; la opción explícita --local o --remote selecciona dónde se realiza la operación.
Primero, mantenga desactivada la funcionalidad pública:
npx wrangler kv key put banner:new disabled --binding FLAGS --remote
Active la misma funcionalidad en el almacén local de la máquina virtual:
npx wrangler kv key put banner:new enabled --binding FLAGS --local
Lea ambos valores. put escribe una clave y get recupera su valor. Los dos puntos de banner:new son una convención de nombres que agrupa claves relacionadas; no crean un directorio.
Use --text para decodificar el valor almacenado como UTF-8 y mostrarlo en su propia línea.
npx wrangler kv key get banner:new --binding FLAGS --local --text
Debe obtener enabled.
npx wrangler kv key get banner:new --binding FLAGS --remote --text
Debe obtener disabled. Si modificó accidentalmente el valor remoto, repita su comando put con disabled y vuelva a leerlo. No deduzca el destino únicamente a partir de la carpeta del proyecto.
Ahora practique la eliminación de un indicador retirado. Estos comandos solo afectan al espacio de nombres remoto temporal vinculado como FLAGS.
npx wrangler kv key put banner:old retired --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
La lista contiene nombres como banner:new y banner:old, no los valores almacenados. Utilice get cuando necesite un valor.
npx wrangler kv key delete banner:old --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --local
Ahora ambas listas deberían contener únicamente banner:new. Si necesita confirmar que los valores siguen siendo diferentes, vuelva a leerlos. Eliminar una clave quita una entrada; eliminar posteriormente un espacio de nombres quitará todo el contenedor.
KV es eventualmente consistente: un cambio puede tardar en ser visible para las lecturas realizadas desde otras ubicaciones. Un Worker puede ver temporalmente un valor anterior, incluso una clave que antes no existía. No sobrescriba repetidamente un valor para forzar su aparición. Estos indicadores de visualización sin consecuencias toleran ese retraso; no serían adecuados para una decisión inmediata de revocación de acceso. Explorará este comportamiento en un laboratorio posterior. Consulte cómo funciona KV para conocer el modelo de almacenamiento.
Leer un indicador desde un Worker local
En este paso, hará que el comportamiento de la aplicación dependa de la configuración almacenada. El Worker lee env.FLAGS, donde env contiene las vinculaciones de recursos configuradas. get() es asíncrono, por lo que await espera su valor antes de decidir qué devolver.
Escriba el manejador. El delimitador JS, entre comillas, conserva exactamente el código JavaScript y evita la expansión de variables del shell.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/banner") {
return new Response("Not found", { status: 404 });
}
const value = await env.FLAGS.get("banner:new");
return Response.json({
feature: "new-banner",
enabled: value === "enabled"
});
}
};
JS
Una clave inexistente devuelve null. Comparar específicamente con "enabled" garantiza que un valor inexistente o inesperado mantenga desactivado este banner opcional. Es un pequeño valor predeterminado seguro: la aplicación sigue siendo utilizable cuando no se ha proporcionado la configuración. Esto no oculta los fallos de conexión, que son distintos de una clave inexistente.
Inicie el desarrollo local. --local ejecuta el Worker en esta máquina virtual con vinculaciones locales. > local.log 2>&1 envía la salida y los errores al registro; & permite que el terminal acepte más comandos. $! es el ID del proceso en segundo plano, que se guarda aquí para poder detenerlo más adelante.
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Espere el mensaje que indica que el servicio está listo en el puerto 8080. Si el inicio aún está en curso, vuelva a leer el registro antes de continuar.
curl -i http://127.0.0.1:8080/banner
curl -i muestra los encabezados y el cuerpo de la respuesta. Debe obtener HTTP 200, un tipo de contenido JSON y:
{"feature":"new-banner","enabled":true}
El valor true procede del almacén KV local. Al ejecutar el servidor de desarrollo, no copió el valor remoto disabled en la máquina virtual. Mantenga el servidor en ejecución para realizar la siguiente comparación.
Implementar y comparar la respuesta pública
En este paso, publicará el mismo código y comprobará que lee el espacio de nombres de la nube. La implementación carga el Worker y su configuración de vinculaciones; no carga las entradas KV locales.
npx wrangler deploy
Lea la salida de la implementación. Confirme el nombre del Worker, la vinculación FLAGS y la dirección pública de workers.dev. Guarde la dirección real a continuación y sustituya el ejemplo antes de ejecutar el comando. Una variable de shell evita que tenga que volver a escribir una URL larga.
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/banner"
Debe obtener HTTP 200 y:
{"feature":"new-banner","enabled":false}
La configuración de la nube es disabled, por lo que la respuesta pública es false. Si el nuevo nombre de host todavía no responde, espere unos instantes y vuelva a intentarlo. Si la respuesta refleja un valor anterior, compruebe una vez la clave remota y espere a que KV haga visible el cambio en lugar de reescribirla rápidamente. Un error de red no es una prueba correcta.
curl -i http://127.0.0.1:8080/banner
La respuesta local sigue siendo true. Tiene un manejador y dos almacenes de datos separados: el desarrollo local lee los datos de la máquina virtual, mientras que el Worker implementado lee el espacio de nombres identificado por la vinculación.
En el Dashboard de Cloudflare, seleccione la misma cuenta de aprendizaje y abra Storage & databases → Workers KV. Busque el espacio de nombres cuyo nombre coincide con el de este laboratorio e inspeccione sus claves. Confirme que solo queda banner:new, con el valor remoto disabled. Después, abra Workers & Pages, seleccione el Worker de este laboratorio e inspeccione su vista Bindings. Compare la vinculación FLAGS con el espacio de nombres que acaba de inspeccionar. Estos son puntos de comprobación de solo lectura: el terminal sigue siendo el lugar donde realiza los cambios.
El espacio de nombres se abre en Metrics. Seleccione KV Pairs para consultar las entradas reales; los contadores de uso pueden actualizarse después de las escrituras. Si el nuevo Worker no aparece en Workers & Pages, pulse Refresh. En Bindings, desplácese hasta la tabla para comparar el nombre de la vinculación con su espacio de nombres.
El nombre generado, el ID del espacio de nombres y el subdominio público serán distintos de los ejemplos. Ver un espacio de nombres en el Dashboard confirma dónde se encuentra; una respuesta HTTP correcta confirma que la aplicación puede utilizarlo.
Eliminar los recursos temporales de la nube
En este paso, eliminará ambos recursos mientras Wrangler todavía está autorizado. Un espacio de nombres puede sobrevivir a su Worker, por lo que eliminar únicamente la aplicación no limpia sus datos.
Detenga el proceso de desarrollo local iniciado en este terminal:
kill "$DEV_PID"
Inspeccione las referencias de recursos guardadas antes de eliminar nada:
cat wrangler.jsonc
Confirme el nombre del Worker labex-flags-... y el ID del espacio de nombres FLAGS. Elimine el Worker seleccionado mediante esta configuración:
npx wrangler delete
Si se le solicita confirmación, compruebe que el nombre mostrado corresponde a este laboratorio y confirme con y. Después, elimine únicamente el espacio de nombres referenciado por FLAGS:
npx wrangler kv namespace delete --binding FLAGS
Revise el espacio de nombres en cualquier solicitud de confirmación antes de aceptarla. Mantenga intacto wrangler.jsonc para que la comprobación independiente pueda identificar los recursos que deberían haber desaparecido.
npx wrangler kv namespace list
El espacio de nombres de este laboratorio no debería aparecer; los espacios de nombres que no están relacionados deben permanecer. Actualice las listas del Dashboard para confirmar que el Worker y el espacio de nombres del laboratorio han desaparecido. Una solicitud fallida o una sesión iniciada que haya caducado no demuestra que se haya eliminado el recurso. Ejecute la comprobación de este paso antes de cerrar sesión para que pueda inspeccionar un inventario autorizado.
Finalizar la autorización de la máquina virtual
En este paso, desconectará Wrangler después de que la comprobación de limpieza se haya completado correctamente. Cerrar sesión finaliza la autorización de Wrangler guardada en esta máquina virtual; no elimina recursos de la nube ni cierra la sesión de su sesión habitual del Dashboard en el navegador.
npx wrangler logout
npx wrangler whoami --json
Confirme que el resultado estructurado informa "loggedIn": false. Este comando sin autenticación puede terminar con un estado de salida distinto de cero, lo cual es normal en este punto. Si solo aparece un error de conexión y no un estado explícito de autenticación, vuelva a intentarlo cuando la conexión funcione.
Los archivos locales restantes y el estado de KV local pertenecen a esta máquina virtual temporal. Son independientes de los recursos de la nube que ya eliminó. Ahora puede finalizar el laboratorio.
Resumen
Creó un espacio de nombres KV aislado, lo conectó mediante una vinculación y utilizó comandos locales y remotos explícitos para escribir, leer, enumerar y eliminar claves. Su Worker leyó la misma clave desde almacenes separados: el banner local estaba activado, mientras que el banner público permanecía desactivado. También utilizó un valor predeterminado seguro para un indicador inexistente y comprendió por qué las actualizaciones de KV no deben tratarse como un interruptor global inmediato.
Por último, verificó la respuesta pública, eliminó el Worker y el espacio de nombres mientras estaba autorizado y cerró sesión en Wrangler. A continuación, utilizará valores JSON estructurados para ofrecer preferencias de cuenta no confidenciales.
