Hands-on Lab

Cómo desplegar OpenBao en Docker con almacenamiento Raft

21 de octubre de 2026 4 min

0 / 9

Chuleta

¿Te ha servido? No te pierdas el próximo lab

El vídeo tiene subtítulos y transcripción. Todo lo que se ve está escrito, paso a paso, más abajo. Chuleta con todos los comandos

0:00 / 0:00

Creamos config/openbao.hcl con la configuración de la guía. El bloque storage "raft" guarda los datos en /openbao/file con el nodo bao-1 y el listener escucha en el puerto 8200 sin TLS. El bloque audit declara el registro de auditoría en fichero, y cluster_addr es obligatorio con Raft aunque haya un solo nodo.

mkdir -p /root/openbao/config && cd /root/openbao && cat > config/openbao.hcl <<'EOF'
ui = true

storage "raft" {
  path    = "/openbao/file"
  node_id = "bao-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

audit "file" "fichero" {
  options {
    file_path = "/openbao/logs/audit.log"
  }
}

api_addr     = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
EOF

Lo hice yo

Escribimos compose.yaml con la imagen openbao/openbao:2.6.2 y command: server, que evita el modo de desarrollo en memoria. El puerto 8200 queda solo en 127.0.0.1 y la configuración se monta en solo lectura. Dos volúmenes con nombre guardan los datos: bao-datos para Raft y bao-logs para la auditoría. El healthcheck consulta /v1/sys/health cada 30 s.

cd /root/openbao && cat > compose.yaml <<'EOF'
services:
  openbao:
    image: openbao/openbao:2.6.2
    command: server
    ports:
      - "127.0.0.1:8200:8200"
    environment:
      BAO_ADDR: "http://127.0.0.1:8200"
    volumes:
      - ./config:/openbao/config:ro
      - bao-datos:/openbao/file
      - bao-logs:/openbao/logs
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8200/v1/sys/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  bao-datos:
  bao-logs:
EOF

Lo hice yo

Comprobamos los dos ficheros. La configuración declara Raft y su ruta, y docker compose config valida el YAML y resuelve la imagen 2.6.2 con sus volúmenes en /openbao/file y /openbao/logs.

cd /root/openbao && grep -nE 'storage|path|cluster_addr' config/openbao.hcl && docker compose config | grep -E 'image:|target: /openbao/(file|logs)'

Qué demuestra

image: openbao/openbao:2.6.2 Compose resuelve la imagen con la versión fijada 2.6.2 Objetivo · sabes que el lab ejecuta la misma versión que la guía, no la última que haya en Docker Hub
target: /openbao/file el volumen de datos se monta en /openbao/file, la ruta que pide la configuración de Raft Objetivo · confirmas que los datos de Raft vivirán en un volumen y sobrevivirán al contenedor

Reproducimos el error de la guía con dos volúmenes nuevos. El contenedor se ejecuta como openbao; /openbao/file, que ya existe en la imagen, hereda ese propietario, pero /openbao/data queda de root y escribir en él falla con Permission denied. Por eso el volumen de Raft va en /openbao/file.

docker pull -q openbao/openbao:2.6.2 >/dev/null && docker run --rm --entrypoint sh -v /openbao/file -v /openbao/data openbao/openbao:2.6.2 -c 'id -un; stat -c "%U:%G %n" /openbao/file /openbao/data; touch /openbao/data/vault.db'

Lo hice yo

Levantamos OpenBao en segundo plano con docker compose up -d. Compose crea la red y los dos volúmenes y arranca el contenedor. El servidor empieza sellado y sin inicializar: tiene dónde guardar datos, pero todavía no existe ninguna clave.

cd /root/openbao && docker compose up -d

Lo hice yo

Esperamos a que la API responda y comprobamos tres cosas. El registro de arranque dice Storage: raft (HA available) y la versión 2.6.2. /v1/sys/health devuelve 501, el código de un servidor sin inicializar, y /openbao/file pertenece a openbao:openbao.

cd /root/openbao && for i in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8200/v1/sys/health)" = 501 ] && break; sleep 2; done; docker compose logs openbao | grep -E 'Storage:|Version:'; curl -s -o /dev/null -w 'sys/health: HTTP %{http_code}\n' http://127.0.0.1:8200/v1/sys/health; docker compose exec openbao stat -c '%U:%G %n' /openbao/file

Qué demuestra

Storage: raft (HA available) el servidor arrancó con el backend Raft de la configuración Objetivo · confirmas que OpenBao no cayó en el modo de desarrollo en memoria
sys/health: HTTP 501 la API de salud responde 501, servidor sin inicializar Objetivo · sabes que el servicio escucha y que el siguiente paso es inicializarlo
openbao:openbao /openbao/file el volumen de datos pertenece al usuario openbao Objetivo · compruebas que Raft podrá escribir en su volumen, al contrario que en /openbao/data

Inicializamos OpenBao con bao operator init, 5 claves y umbral 3 como en la guía. Con -format=json la salida va a init.json, y jq extrae las claves a unseal-keys y el token raíz a root-token, con permisos 600. Son claves de usar y tirar dentro de un contenedor que destruimos al final; en un servidor real se copian fuera ahora, porque OpenBao no las vuelve a mostrar.

cd /root/openbao && docker compose exec -T openbao bao operator init -key-shares=5 -key-threshold=3 -format=json > init.json && jq -r '.unseal_keys_b64[]' init.json > unseal-keys && jq -r .root_token init.json > root-token && chmod 600 init.json unseal-keys root-token

Lo hice yo

Comprobamos el resultado sin imprimir ningún secreto: los dos ficheros existen con permisos 600, init.json declara 5 claves con umbral 3, el token raíz lleva el prefijo s. de OpenBao y bao status muestra Initialized true, Sealed true y Unseal Progress 0/3.

cd /root/openbao && ls -l unseal-keys root-token && jq '{unseal_shares, unseal_threshold}' init.json && echo "token prefix: $(cut -c1-2 root-token)" && docker compose exec openbao bao status | grep -E 'Initialized|Sealed|Total Shares|Threshold|Unseal Progress'

Qué demuestra

"unseal_threshold": 3 la inicialización generó claves con umbral 3 Objetivo · sabes cuántas claves tendrás que reunir para abrir OpenBao tras cada reinicio
token prefix: s. el token raíz empieza por s., el prefijo de OpenBao, mostrado sin revelar el resto Objetivo · confirmas que tienes el token guardado sin haberlo expuesto en pantalla
Unseal Progress 0/3 el servidor está inicializado pero sellado, con 0 de 3 claves introducidas Objetivo · ves que inicializar no basta: los datos siguen cifrados hasta desellar

Desellamos con 3 de las 5 claves, leídas del fichero y pasadas como argumento porque en el lab no hay teclado. En un servidor real ejecuta bao operator unseal sin argumento: pide la clave oculta y no queda en el historial. Tras cada clave filtramos el progreso: 1/3, 2/3 y Sealed false.

cd /root/openbao && for k in $(head -n 3 unseal-keys); do docker compose exec -T openbao bao operator unseal "$k" | grep -E '^(Sealed|Unseal Progress)'; done

Lo hice yo

bao status sale con código 0 y confirma el desellado: Sealed false, Total Shares 5 y Threshold 3. Storage Type raft y HA Mode active indican que bao-1 dirige su clúster Raft de un solo nodo.

cd /root/openbao && docker compose exec openbao bao status

Qué demuestra

Sealed false el servidor está desellado Objetivo · sabes que OpenBao ya descifra sus datos y puede atender peticiones
Storage Type raft el almacenamiento en uso es Raft Objetivo · confirmas que los secretos irán al volumen de Raft y no a memoria
HA Mode active el nodo es el activo de su clúster Objetivo · ves que el nodo único ya ganó la elección de líder de Raft

Exportamos BAO_TOKEN desde el fichero root-token y -e BAO_TOKEN lo pasa al contenedor sin escribirlo en la orden. Activamos kv-v2 en secret/ y guardamos app/db con user=app; con password=- el valor de prueba changeme entra por la entrada estándar. El bucle repite el put si OpenBao todavía responde Upgrading from non-versioned to versioned data, la dificultad que cuenta la guía.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao secrets enable -path=secret kv-v2 && for i in $(seq 1 10); do printf '%s' changeme | docker compose exec -T -e BAO_TOKEN openbao bao kv put -mount=secret app/db user=app password=- && break; sleep 1; done

Lo hice yo

Leemos el secreto con bao kv get. La ruta real es secret/data/app/db, con el segmento data/ propio de KV v2. Los metadatos marcan la versión 1 y los datos devuelven user app y password changeme, el valor de prueba.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao kv get -mount=secret app/db

Qué demuestra

secret/data/app/db el secreto vive en la ruta de datos de KV v2 Objetivo · sabes qué ruta poner en las políticas de lectura de tus aplicaciones
version 1 es la versión 1 del secreto Objetivo · confirmas que el motor guarda versiones y la siguiente escritura no borrará esta
password changeme OpenBao devuelve el valor de prueba guardado Objetivo · compruebas el ciclo completo de escritura y lectura de un secreto

Guardamos un snapshot de Raft con bao operator raft snapshot save en /tmp del contenedor de OpenBao, lo copiamos al directorio del proyecto con docker compose cp y borramos la copia interna. Es una copia en caliente: el servidor sigue atendiendo peticiones.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao operator raft snapshot save /tmp/bao.snap && docker compose cp openbao:/tmp/bao.snap ./bao.snap && docker compose exec openbao rm /tmp/bao.snap

Lo hice yo

Comprobamos la copia: bao.snap es un tar.gz con meta.json, state.bin, que guarda los datos todavía cifrados, SHA256SUMS y SHA256SUMS.sealed. bao operator raft list-peers confirma que bao-1 es el líder y votante del clúster.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && ls -l bao.snap && tar -tzf bao.snap && docker compose exec -e BAO_TOKEN openbao bao operator raft list-peers

Qué demuestra

state.bin el snapshot contiene state.bin, los datos de Raft Objetivo · sabes que la copia lleva los secretos, cifrados, listos para restaurar
SHA256SUMS.sealed incluye las sumas de control selladas con la clave de OpenBao Objetivo · entiendes por qué restaurarlo exige las claves de desellado originales
leader bao-1 aparece como líder del clúster Raft Objetivo · confirmas que el snapshot salió de un nodo sano que dirige el clúster

Comprobamos el estado desde fuera: /v1/sys/health responde initialized true y sealed false con la versión 2.6.2. El healthcheck de Compose, que consulta esa misma ruta, marca el contenedor como healthy. /openbao/logs contiene audit.log con las peticiones del lab.

cd /root/openbao && curl -s http://127.0.0.1:8200/v1/sys/health | jq '{initialized, sealed, version}' && for i in $(seq 1 45); do [ "$(docker inspect -f '{{.State.Health.Status}}' openbao-openbao-1)" = healthy ] && break; sleep 2; done; docker compose ps --format '{{.Name}} {{.Status}}'; docker compose exec openbao ls -l /openbao/logs

Qué demuestra

"sealed": false la API de salud informa de que el servidor está desellado Objetivo · tienes el comprobante que usaría tu sistema de supervisión
(healthy) Docker marca el contenedor como healthy Objetivo · sabes que otros servicios pueden esperar a OpenBao con depends_on y service_healthy
audit.log el registro de auditoría declarado en la configuración existe Objetivo · confirmas que cada petición queda registrada desde el primer arranque

Limpiamos el laboratorio: docker compose down -v elimina el contenedor, la red y los volúmenes bao-datos y bao-logs, y borramos init.json, unseal-keys, root-token y bao.snap. Sin las claves, el snapshot ya no se podría restaurar en ningún sitio.

cd /root/openbao && docker compose down -v && rm -f init.json unseal-keys root-token bao.snap

Lo hice yo

Comprobamos que no queda ningún contenedor ni volumen de OpenBao y que en /root/openbao solo quedan config y compose.yaml, sin ficheros de claves.

cd /root/openbao && echo "openbao containers: $(docker ps -aq --filter name=openbao | wc -l)"; echo "openbao volumes: $(docker volume ls -q --filter name=openbao | wc -l)"; ls

Qué demuestra

openbao volumes: 0 no queda ningún volumen de OpenBao Objetivo · dejas la máquina sin datos cifrados ni claves del laboratorio

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

Transcripción del vídeo

0:01 OpenBao en Docker, desellado con 3 de 5 claves.
0:06 Escribimos la configuración de la guía:
0:09 almacenamiento Raft en /openbao/file y el puerto 8200.
0:16 OpenBao en Docker con Raft:
0:18 desellar, guardar un secreto y respaldarlo.
0:22 Configurar, arrancar, inicializar, desellar, guardar el secreto y hacer el
0:27 snapshot.
0:29 Compose fija la versión 2.6.2 y monta los datos en un volumen.
0:35 Lo comprobamos con docker compose config:
0:38 la imagen fijada es la 2.6.2 y el volumen de datos se monta en
0:43 /openbao/file.
0:46 Un volumen nuevo hereda el propietario solo si la ruta existe en la imagen.
0:52 Una de las dificultades con las que me he topado:
0:54 en /openbao/data el volumen es de root y OpenBao no puede escribir.
1:01 Levantamos el servicio con docker compose up.
1:04 OpenBao arranca sellado y sin inicializar.
1:09 Lo comprobamos:
1:11 el registro muestra Raft, la API responde 501, sin inicializar, y el
1:16 volumen es de openbao.
1:19 La clave se parte en 5 y bastan 3 para reconstruirla.
1:24 Inicializamos con 5 claves y umbral 3, y jq las guarda en ficheros sin mostrarlas.
1:30 Lo comprobamos:
1:31 hay 5 claves y un token que empieza por s punto, y bao status dice inicializado,
1:37 sellado y progreso 0 de 3.
1:42 Introducimos 3 de las 5 claves, una tras otra.
1:46 El progreso pasa por 1 y 2 de 3, y con la tercera OpenBao queda abierto, ya sin
1:51 sellar.
1:53 Lo comprobamos con bao status:
1:55 Sealed false, almacenamiento raft y nodo activo.
1:59 OpenBao ya puede leer sus datos.
2:05 Activamos KV versión 2 en secret y guardamos un secreto de prueba.
2:13 Lo comprobamos con kv get:
2:16 el secreto está en secret/data/app/db, versión 1, con el usuario y la contraseña
2:22 de prueba.
2:26 Una copia consistente de todos los datos, en caliente.
2:30 La copia de seguridad:
2:32 un snapshot de Raft, copiado fuera con docker compose cp.
2:36 Lo comprobamos:
2:37 el snapshot es un tar con los datos y sus sumas firmadas, y Raft lista a bao-1 como
2:43 líder.
2:47 Última comprobación de estado:
2:50 la API de salud dice sellado false, Docker marca el contenedor healthy y existe el
2:55 registro de auditoría.
2:59 Limpiamos:
3:00 borramos OpenBao, sus volúmenes, las claves y el snapshot.
3:06 Lo comprobamos:
3:08 no queda contenedor ni volumen de OpenBao, solo la configuración y compose.yaml.

Este laboratorio reproduce en vídeo la guía cómo instalar OpenBao con Docker y almacenamiento Raft: la misma imagen openbao/openbao:2.6.2, la misma configuración y las mismas órdenes, ejecutadas de verdad en un contenedor desechable. Si buscas montar OpenBao en Docker para guardar las credenciales de tus servicios, aquí ves cada salida real, del primer bao status sellado al snapshot de Raft.

Qué es OpenBao y por qué Raft

OpenBao es la bifurcación de HashiCorp Vault que conserva la licencia MPL 2.0 y mantiene su API, así que los conceptos del artículo sobre Vault de HashiCorp para gestión de secretos se aplican igual. El almacenamiento Raft va integrado en el binario: escribe los datos cifrados en un directorio y no necesita una base de datos externa. La documentación del backend Raft exige cluster_addr incluso con un solo nodo.

El propietario del volumen de datos

La imagen se ejecuta con el usuario sin privilegios openbao, y Docker solo copia ese propietario a un volumen nuevo cuando la ruta ya existe en la imagen. Por eso el volumen va en /openbao/file: en /openbao/data el directorio queda de root y el lab muestra el Permission denied. Los detalles de cómo se inicializa un volumen están en la documentación de volúmenes de Docker y en el laboratorio sobre cómo persisten los datos en Docker.

Inicializar y desellar sin enseñar las claves

bao operator init genera 5 claves de desellado y el token raíz, y el lab las vuelca con jq a ficheros con permisos 600 para no imprimirlas. Después desella con 3 de ellas. En el lab las claves se pasan como argumento porque no hay teclado; en tu servidor ejecuta bao operator unseal sin argumento, que pide la clave oculta y la deja fuera del historial. La referencia completa está en la documentación de bao operator init.

Qué cambia respecto a la guía

El compose.yaml del lab omite mem_limit y memswap_limit: el contenedor anidado donde se graba no delega el controlador de memoria de cgroup v2, y Docker rechaza cualquier límite de memoria. En tu servidor mantén esas dos líneas con el mismo valor, como explica la guía, para que el swap del contenedor quede en 0 y los secretos no acaben en disco. El token raíz tampoco se revoca aquí, porque el contenedor se destruye al terminar.

Para el resto de opciones de secretos en contenedores tienes el laboratorio de gestión de secretos en Docker, y para mandar los snapshots fuera del servidor, la guía de restic para copias cifradas. La imagen y sus etiquetas están en openbao/openbao en Docker Hub, y el código en el repositorio de OpenBao.

Preguntas frecuentes

¿Por qué OpenBao arranca sellado después de cada reinicio?

Porque con desellado Shamir la clave que descifra los datos no se guarda en disco: se reconstruye en memoria con 3 de las 5 claves de desellado. Hasta entonces bao status muestra Sealed true y Unseal Progress 0/3, como en el lab, y los secretos siguen cifrados.

¿En qué ruta monto el volumen de Raft de OpenBao en Docker?

En /openbao/file. La imagen se ejecuta con el usuario openbao y Docker solo copia ese propietario a un volumen nuevo cuando la ruta ya existe en la imagen. En una ruta como /openbao/data el directorio queda de root y escribir falla con Permission denied, como muestra el lab.

¿Un snapshot de Raft guarda los secretos en claro?

No. El fichero es un tar.gz con meta.json, state.bin, SHA256SUMS y SHA256SUMS.sealed, y state.bin conserva los datos cifrados con la clave de OpenBao. Por eso solo se restaura con las claves de desellado originales, que deben guardarse en un sitio distinto al snapshot.

¿Por qué falla el primer kv put justo después de activar KV v2?

Al activar kv-v2, OpenBao prepara el almacenamiento versionado y durante un momento responde Upgrading from non-versioned to versioned data. La guía lo encontró en una de sus instalaciones: espera un segundo y repite la orden. El lab lo resuelve con un bucle de hasta 10 intentos.

Chuleta

mkdir -p /root/openbao/config && cd /root/openbao && cat > config/openbao.hcl <<'EOF'
ui = true

storage "raft" {
  path    = "/openbao/file"
  node_id = "bao-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

audit "file" "fichero" {
  options {
    file_path = "/openbao/logs/audit.log"
  }
}

api_addr     = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
EOF

cd /root/openbao && cat > compose.yaml <<'EOF'
services:
  openbao:
    image: openbao/openbao:2.6.2
    command: server
    ports:
      - "127.0.0.1:8200:8200"
    environment:
      BAO_ADDR: "http://127.0.0.1:8200"
    volumes:
      - ./config:/openbao/config:ro
      - bao-datos:/openbao/file
      - bao-logs:/openbao/logs
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8200/v1/sys/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  bao-datos:
  bao-logs:
EOF

docker pull -q openbao/openbao:2.6.2 >/dev/null && docker run --rm --entrypoint sh -v /openbao/file -v /openbao/data openbao/openbao:2.6.2 -c 'id -un; stat -c "%U:%G %n" /openbao/file /openbao/data; touch /openbao/data/vault.db'

cd /root/openbao && docker compose up -d

cd /root/openbao && docker compose exec -T openbao bao operator init -key-shares=5 -key-threshold=3 -format=json > init.json && jq -r '.unseal_keys_b64[]' init.json > unseal-keys && jq -r .root_token init.json > root-token && chmod 600 init.json unseal-keys root-token

cd /root/openbao && for k in $(head -n 3 unseal-keys); do docker compose exec -T openbao bao operator unseal "$k" | grep -E '^(Sealed|Unseal Progress)'; done

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao secrets enable -path=secret kv-v2 && for i in $(seq 1 10); do printf '%s' changeme | docker compose exec -T -e BAO_TOKEN openbao bao kv put -mount=secret app/db user=app password=- && break; sleep 1; done

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao operator raft snapshot save /tmp/bao.snap && docker compose cp openbao:/tmp/bao.snap ./bao.snap && docker compose exec openbao rm /tmp/bao.snap

cd /root/openbao && docker compose down -v && rm -f init.json unseal-keys root-token bao.snap

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

Qué es OpenBao y por qué Raft

El propietario del volumen de datos

Inicializar y desellar sin enseñar las claves

Qué cambia respecto a la guía

Preguntas frecuentes

¿Por qué OpenBao arranca sellado después de cada reinicio?

¿En qué ruta monto el volumen de Raft de OpenBao en Docker?

¿Un snapshot de Raft guarda los secretos en claro?

¿Por qué falla el primer kv put justo después de activar KV v2?

Chuleta