Kubernetes (Helm)

El chart de Helm rikoo despliega la api, el worker, el sidecar de análisis de documentos y el entorno aislado de las herramientas en un clúster, con PostgreSQL, Redis y el almacenamiento de objetos incluidos en el chart o sustituidos por servicios gestionados. Las migraciones del esquema se ejecutan en un Job durante la instalación y antes de cada actualización.

El chart está en un repositorio público, Rikoo-app/rikoo-k8s, con licencia MIT. Las imágenes de contenedor que despliega están en un registro privado: necesita la dirección del registro y las credenciales que proporciona el equipo de Rikoo (consulte la Visión general).

Requisitos previos

• Kubernetes 1.27 o posterior, y Helm 3.14 o posterior.
• Un plugin de red que aplique las NetworkPolicies, como Cilium o Calico. El entorno aislado se apoya en ellas para cortar su acceso a la red, consulte Confinamiento del entorno aislado.
• Una StorageClass por defecto, si mantiene los almacenes incluidos: reclaman 20 GiB para PostgreSQL, 8 GiB para Redis y 50 GiB para MinIO.
• Para una dirección pública: un controlador de ingress y cert-manager, o equivalentes.
• Capacidad: con los valores por defecto, los pods solicitan unos 2,2 vCPU y 4 GiB de memoria, y sus límites de memoria suman unos 11 GiB.

Instalación

Los pasos siguen la carpeta examples/minimal-installation del repositorio del chart: todos los almacenes incluidos y todas las credenciales en un único Secret creado de antemano.

1. Obtener el chart

git clone https://github.com/Rikoo-app/rikoo-k8s.git
cd rikoo-k8s/examples/minimal-installation
helm dependency update ../../charts/rikoo

2. Crear el namespace y el secreto del registro

kubectl create namespace rikoo
kubectl -n rikoo create secret docker-registry rikoo-registry \
  --docker-server=<registry> --docker-username=<user> --docker-password=<token>

3. Crear el secreto de la aplicación

Genere el par de claves de sellado de la bóveda. El chart nunca lo genera, y perder la clave privada hace ilegibles todos los secretos almacenados.

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out sealing.private
openssl pkey -in sealing.private -pubout -out sealing.public

Después edite secret.yaml y sustituya cada marcador de posición:

Clave	Valor
widget-signing-key, totp-key, sandbox-token-secret	Cadenas aleatorias de al menos 32 caracteres, por ejemplo generadas con openssl rand -hex 24
sealing.pub, sealing.key	El contenido de sealing.public y de sealing.private
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	Las credenciales del PostgreSQL incluido
rootUser, rootPassword	Las credenciales del MinIO incluido

kubectl -n rikoo apply -f secret.yaml

En un pipeline GitOps, genere este Secret con un operador de secretos externos en lugar de versionarlo en el repositorio.

4. Instalar el chart

helm install rikoo ../../charts/rikoo -n rikoo -f values.yaml \
  --set rikoo.image.registry=<registry>/<namespace> \
  --set rikoo.image.tag=v0.2.0

Tanto rikoo.image.registry como rikoo.image.tag son obligatorios: sin ellos, el chart se niega a generar sus manifiestos.

5. Comprobar

kubectl -n rikoo get pods
kubectl -n rikoo port-forward svc/rikoo-api 3000:http
curl -fsS http://localhost:3000/api/v1/health

Abra http://localhost:3000 y cree la primera cuenta: mientras no exista ninguna organización, puede registrarse y obtiene el rol Owner (propietario) de la primera organización.

Exponer la instancia

El archivo de valores adicional with-ingress.yaml de la misma carpeta añade un ingress con TLS, suponiendo ingress-nginx, cert-manager y un ClusterIssuer llamado letsencrypt. Sustituya sus hosts de ejemplo, rikoo.example.com y s3.rikoo.example.com, por los suyos. Este archivo además:

• asigna a rikoo.publicUrl la dirección pública y a rikoo.trustProxyHops el valor 1, ya que el controlador de ingress es un proxy situado delante de la api;
• da al MinIO incluido una ruta pública, porque los navegadores suben los adjuntos directamente al almacenamiento de objetos, en la dirección indicada en s3.browserEndpoint;
• desactiva el búfer del proxy y amplía los tiempos de espera a una hora, porque las respuestas llegan en flujo como server-sent events. Con otro controlador de ingress, aplique los mismos ajustes.

helm upgrade --install rikoo ../../charts/rikoo -n rikoo \
  -f values.yaml -f with-ingress.yaml \
  --set rikoo.image.registry=<registry>/<namespace> --set rikoo.image.tag=v0.2.0

Usar almacenes gestionados

Cada almacén incluido puede sustituirse por un servicio gestionado. La carpeta examples/external-components tiene un archivo de valores adicional por almacén.

Almacén	Valores	Requisitos
PostgreSQL	postgresql.deploy: false, después postgresql.url, o host, port y auth.*	Las extensiones vector (pgvector) y citext. El rol que ejecuta las migraciones debe tener permiso para crear extensiones y roles.
Redis	redis.deploy: false, después redis.url, o host, port y database	maxmemory-policy noeviction: desalojar una clave hace perder trabajos en cola.
Almacenamiento de objetos	s3.deploy: false, después endpoint, browserEndpoint, region, bucket, forcePathStyle y el par de claves	Cualquier servicio compatible con S3.

Para que la seguridad a nivel de fila (RLS) de PostgreSQL filtre las consultas sobre los datos de las organizaciones, dé a la aplicación un segundo rol, no propietario, mediante postgresql.appUrl. Sin él, esas consultas usan la conexión del propietario.

Configurar

El chart define lo que puede a partir de sus propios valores. Cualquier otro ajuste del producto va en un mapa verificado: rikoo.settings (leído por la api y el worker), rikoo.api.settings o rikoo.worker.settings. El chart contrasta cada nombre con la lista de variables que lee el producto, y se niega a generar sus manifiestos ante un nombre que el producto no conoce, un secreto escrito en claro o un valor con un formato incorrecto.

La lista completa de variables, con su formato y el servicio que las lee, está en charts/rikoo/VARIABLES.md.

Edición Enterprise

Despliegue las imágenes Enterprise (solicite la etiqueta junto con su licencia), después guarde la licencia en un Secret y haga que rikoo.license.deploymentLicense apunte a él:

kubectl -n rikoo create secret generic rikoo-license \
  --from-literal=RIKOO_DEPLOYMENT_LICENSE='<license>'

rikoo:
  license:
    deploymentLicense:
      secretKeyRef:
        name: rikoo-license
        key: RIKOO_DEPLOYMENT_LICENSE

Consulte Licencia Enterprise para saber qué desbloquea la licencia.

Confinamiento del entorno aislado

Las herramientas integradas se ejecutan en los pods mcp-sandbox, confinados por tres NetworkPolicies: el espacio de trabajo solo alcanza el navegador, el navegador solo sale por el proxy mcp-egress, que aplica la misma protección anti-SSRF que el worker, y la api no alcanza ninguno de ellos. El contenedor del espacio de trabajo elimina todas las capabilities excepto las cuatro que necesita para adoptar la identidad de sistema de la conversación (SETUID, SETGID, CHOWN, DAC_OVERRIDE), con un sistema de archivos raíz de solo lectura y el perfil seccomp RuntimeDefault.

Las NetworkPolicies solo se aplican con un plugin de red que las admita. En un clúster sin él, el espacio de trabajo del entorno aislado puede alcanzar la red: instale un plugin así o desactive el entorno aislado con rikoo.sandbox.enabled: false. Las ejecuciones siguen funcionando sin él, y las herramientas integradas devuelven un error.

La pila de Docker Compose añade un perfil seccomp dedicado y admite gVisor. El chart todavía no ofrece ninguna de las dos cosas.

Actualización

Haga una copia de seguridad de la base de datos y después ejecute el mismo comando con la nueva etiqueta:

helm upgrade --install rikoo ../../charts/rikoo -n rikoo -f values.yaml \
  --set rikoo.image.registry=<registry>/<namespace> --set rikoo.image.tag=<new tag>

El Job de migraciones se ejecuta antes que los nuevos pods. Si falla, la nueva versión no se despliega: consulte kubectl -n rikoo logs job/rikoo-migrations. helm rollback vuelve a las imágenes anteriores, pero no revierte las migraciones. Restaure la copia de seguridad de la base de datos cuando haya que deshacer una versión.

Desinstalación

helm uninstall rikoo -n rikoo

El chart conserva lo que no se puede volver a crear: sus Secrets llevan la anotación helm.sh/resource-policy: keep, y el volumen del PostgreSQL incluido se conserva. Elimínelos a mano, junto con el namespace, solo cuando quiera perder los datos.

Probarlo en un portátil

La carpeta examples/local-kind ejecuta el chart en un clúster local de kind, con imágenes compiladas desde el repositorio de código fuente de Rikoo. Su README recorre los pasos e incluye una comprobación de que la red del entorno aislado está realmente cortada.