Ovation Ventures Ovation Developer Docs

Tools

Clúster EKS/Kubernetes

Clúster EKS/Kubernetes

Aviso: Esta es una traducción generada automáticamente. El documento original en inglés es la fuente de referencia: k8s.md.

Contenido

Motivación

Si bien AWS Amplify es la forma más rápida de poner en línea un proyecto de repositorio único, tiene varias desventajas:

A medida que nuestro proyecto crece más allá de Balance Web para incluir pipelines de reportes y microservicios como APIs de cuestionarios, generadores de certificados e integraciones con terceros, hemos superado las capacidades de Amplify. De hecho, Amplify y el cumplimiento de SOC2 pueden ser incompatibles.

AWS ofrece soluciones “sin servidor” como Lambdas y tareas de Fargate. Las Lambdas son difíciles de desarrollar porque requieren un entorno operativo específico que solo puede emularse parcialmente en la estación de trabajo de un desarrollador. Fargate es bastante complicado de configurar, involucrando una desconcertante profundidad de abstracciones y recursos conectados.

Nuestra configuración actual de Terraform trata todo el entorno de AWS como un todo único y atómico. Los despliegues se vuelven difíciles porque cualquier cambio en la infraestructura implica re-analizar todo el entorno, lo que puede romper o revertir cambios en componentes no relacionados.

Explicación

Kubernetes

Kubernetes (K8s) es un “orquestador de contenedores”. Es similar a “Docker Compose”, pero capaz de programar contenedores para ejecutarse en cualquier número de “nodos” distribuidos (computadoras individuales o máquinas virtuales) y gestiona la red entre ellos. Kubernetes ofrece muchas de las mismas funciones que EC2, pero con un modelo más simple.

Helm Charts

Un Helm Chart es una colección de archivos de recursos, muy similar a Terraform. En lugar del Lenguaje de Configuración de Hashicorp, los Helm Charts son archivos de plantillas Go que se renderizan como archivos YAML. Al igual que un módulo de Terraform, un Helm chart expone variables de configuración que pueden tener valores predeterminados. A diferencia de los módulos de Terraform, los Helm charts tienen versiones y se publican en un repositorio que gestiona múltiples versiones de cada chart. Así, un release fallido siempre puede revertirse a la versión anterior. Cada Helm Chart contendrá una descripción de todos los recursos que requiere como una única unidad desplegable de forma atómica.

Helmsman

Helmsman es análogo a un archivo package.json. Mapea los Helm Charts con sus archivos de valores sobreescritos y versiones.

Recetario

Agregar un Dominio a un Clúster EKS

En el repositorio terraform-infrastructure, encuentra el archivo main.tf para el entorno al que estás agregando el dominio.

Hacia el final, habrá un bloque para el Clúster EKS, que será reconocible por el comentario # EKS Cluster, el sufijo -k8s en el nombre del módulo, y el parámetro source, que debería ser ../../modules/eks_cluster.

Encuentra el arreglo de nombres de dominio y agrega el nuevo dominio como una cadena de texto.

Cuando apliques la configuración, parecerá que se detiene mientras crea la validación del certificado para el nuevo dominio. Necesita un poco de ayuda externa.

Si registraste el dominio en Route53, habrá una Zona Alojada. El módulo también creará una Zona Alojada de Route53. Deberás eliminar una de ellas.

Comentario Acción
HostedZone creada por el Registrador de Route53 Elimina esta
Gestionada por Terraform Conserva esta

Ya sea que el dominio haya sido registrado en Route53 o en un registrador externo, deberás actualizar los registros NS con el registrador. Examina la Zona Alojada “Gestionada por Terraform” y encuentra los cuatro servidores NS configurados allí. Copia estos cuatro nombres de dominio en los registros NS o de Servidor de Nombres del dominio, eliminando el . final al pegar. Debes eliminar cualquier registro NS existente.

La certificación puede tardar hasta 24 horas en crearse, y es seguro presionar CTRL-C en el plan de Terraform. Sin embargo, en la práctica, generalmente se resuelve en pocos minutos.

PRECAUCIÓN Solo presiona CTRL-C una vez. Terraform lo detectará e intentará limpiarse a sí mismo. Si cancelas esta limpieza “elegante”, quedarás con un bloqueo obsoleto que impedirá futuros intentos de usar Terraform hasta que realices una limpieza simple, pero incómoda e intimidante.

Actualizar un Despliegue EKS en Helmsman

  1. Ejecuta task choose-env para obtener las credenciales del clúster y el registro ECR.
  2. Confirma que la imagen OCI ha sido publicada en un registro al que el clúster pueda acceder.
  3. Ejecuta task utils:update-deployment-tag para actualizar el tag de la imagen de forma interactiva, o task edit para actualizar el helmsman.yaml manualmente.
  4. Ejecuta TARGET=your_deployment task plan para revisar los cambios, luego TARGET=your_deployment task apply para desplegar.

Para instrucciones detalladas, consulta Desplegar una Actualización en una App Existente en la sección de Configuración de Helmsman.

Agregar/Actualizar un Secreto en un Despliegue EKS

La configuración de Helmsman usa sops y age para cifrar secretos con claves asimétricas, por lo que incluso si no tienes acceso a la clave de descifrado para un entorno, aún puedes agregar o actualizar los valores usando la herramienta sops.

sops set environments/prod/my-app-secrts.yaml '["connection"]["password"]' '"Sw0ordfish"'

Puedes usar una sintaxis similar para eliminar una clave si ya no es necesaria.

sops unset environments/prod/my-app-secrets.yaml '["connection"]["password"]'

Si sí tienes acceso a la clave privada (almacenada en 1Password e instalada en tu estación de trabajo con el comando task setup), puedes usar el comando sops edit para editar la versión en texto plano del archivo de secretos.

EDITOR="$(which codium) --wait" sops edit environments/prod/my-app-secrets.yaml

Tu editor elegido debe bloquear la línea de comandos hasta que el archivo se guarde, porque sops volverá a cifrar el archivo cuando termine.

Descripción de Seguridad, Secretos y Autenticación

Los administradores del clúster inician sesión usando sus cuentas de AWS, que deben tener MFA habilitado y deben tener un Rol específico asociado a su cuenta.

Autenticación de Usuarios

Los usuarios que hayan ejecutado el script de configuración deberían tener un usuario en su ~/.kube/config como este:

- name: arn:aws:eks:us-west-2:614522506954:cluster/dev-k8s
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - --region
      - us-west-2
      - eks
      - get-token
      - --cluster-name
      - dev-k8s
      - --output
      - json
      - --role
      - arn:aws:iam::614522506954:role/KubeUser
      command: aws
      env:
      - name: AWS_PROFILE
        value: dev
      interactiveMode: IfAvailable
      provideClusterInfo: false

Esto usa la herramienta AWS CLI para proporcionar un token de autenticación al clúster. El perfil en este ejemplo es dev. La entrada correspondiente en ~/.aws/config se ve así:

[profile dev]
credential_process = op_credential_process --account 44LNRCZQE5D4RI6QWR34XDZJ5Y --item frqist4nocaclkbvpyyffahvva --mfa-field mfa' device' --otp-field one-time' password' --access-key-field access_key_id --secret-key-field secret_access_key --region-field region
region = us-west-2

Esto usa op_credential_process para obtener credenciales de seguridad desde 1Password, incluyendo un código de un solo uso basado en tiempo. 1Password realizará su propia autenticación de usuario mediante una combinación de contraseñas y biometría.

El usuario pertenece al grupo KubeUsers, que tiene dos políticas: UseKube y KubeUserAssumer. La política UseKube permite al usuario obtener el token de autenticación (usando el comando aws eks get-token listado en el archivo .kube/config). La política KubeUserAssumer permite al usuario asumir el rol KubeUser (también listado en el comando del archivo .kube/config).

Ese ARN de Rol también se menciona en un config map especial en el clúster.

# Contenido editado
apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: arn:aws:iam::614522506954:role/KubeUser
      username: "{{SessionName}}"
      groups:
      - system:masters

Esto permite que el usuario que puede asumir el rol KubeUser pertenezca al grupo incorporado system:masters y asocia su nombre de usuario de IAM como su nombre de usuario de Kubernetes, en caso de que existan RoleBindings o ClusterRoleBindings personalizados adicionales para ese usuario.

Para obtener acceso al clúster de Kubernetes, por lo tanto, un usuario debe:

Para revocar el acceso a un individuo, se puede hacer cualquiera de lo siguiente:

Además, cada entorno (infra-test, dev, test y prod) tiene su propio clúster y su propio conjunto redundante de usuarios. El acceso puede por tanto otorgarse y denegarse por clúster.

Formas en que este sistema puede ser eludido.

Un usuario con acceso a Kubernetes otorgado de esta manera tiene privilegios de administrador en el clúster. Por lo tanto, podría crear para sí mismo un certificado firmado que lo coloque en el grupo system:masters y usarlo sin referencia a IAM ni necesitar una segunda credencial MFA. Este es un riesgo necesario, porque los usuarios a quienes se les otorga acceso al clúster son administradores y necesitan tener la capacidad de crear usuarios adicionales dentro de Kubernetes para crear cuentas de servicio y otorgar acceso a herramientas externas, según corresponda.

Mejoras Sugeridas

Crear un grupo separado de Desarrolladores Ticket 868jh3vmt

El acceso al clúster debería separarse en administradores del clúster (la configuración actual) y usuarios que solo tengan acceso al espacio de nombres apps para desplegar, actualizar y eliminar código. Estos usuarios de apps deberían tener la capacidad de editar la mayoría de los recursos en el espacio de nombres apps, pero no tener acceso a recursos del clúster, como certificados.

Secretos de la App

Los secretos que necesita la app (p. ej. contraseñas de bases de datos, claves API) son gestionados por el plugin de secretos de Helm, que usa sops y age para almacenar secretos cifrados en GitHub, pero usa 1Password para controlar el acceso de los desarrolladores a las claves de cifrado.

Las claves privadas de cifrado para cada entorno se almacenan en 1Password en bóvedas separadas para proporcionar acceso basado en roles. Un script de configuración usa tu acceso a 1Password para descargar estas claves y almacenarlas en una ubicación del sistema en tu estación de trabajo. 1Password usa una combinación de contraseñas y validación biométrica para asegurarse de que se te haya otorgado acceso a estas claves.

La herramienta Helmsman coordina las llamadas a la herramienta Helm, que descifra estos valores sobre la marcha en el momento del despliegue.

Debido a que se usa cifrado asimétrico y sops cifra cada valor individualmente, debería ser posible para los desarrolladores agregar nuevos secretos a los archivos cifrados sin poder descifrar los existentes. NB Requiere verificación.

En Helmsman y Helm, los secretos descifrados de esta manera nunca se imprimen en pantalla al listar los cambios que se van a aplicar. Por lo tanto, ejecutar la fase de planificación en una sesión compartida de Zoom o compartir la salida es seguro. Sin embargo, si se proporciona la opción --dry-run, estos secretos sí se emiten en la consola, por lo que esto siempre debe ser un paso separado.

Formas en que este sistema puede ser eludido.

Dado que las claves privadas se encuentran en la estación de trabajo del desarrollador, no hay una forma sencilla de revocar el acceso de un desarrollador una vez otorgado sin rotar y redistribuir las claves. La herramienta sops lo soporta, y la herramienta de configuración facilita la descarga de nuevas claves para los desarrolladores que conservan acceso a las claves rotadas. Sin embargo, una mejor solución implicaría obtener las claves de 1Password cuando se necesiten, en lugar de pre-compartir las claves con desarrolladores seleccionados.

Mejoras Sugeridas

Mover las Claves a KMS Ticket 868jh48yt

La herramienta sops soporta varios esquemas alternativos de recuperación de claves además de almacenar la clave en un archivo en disco. Estos incluyen el uso de servicios de claves proporcionados por AWS, GCP, Azure y Hashicorp. sops también proporciona su propio servicio de claves con un protocolo propio. Una mejora podría ser usar AWS KMS para proporcionar estas claves y usar permisos IAM para otorgar acceso basado en roles a los desarrolladores. Otra solución podría ser ejecutar el servicio de claves de sops en un servidor SSH y usar los controles de acceso de usuarios del servidor SSH para controlar el acceso de los desarrolladores.

Las claves privadas deberían moverse a AWS KMS y estar controladas por políticas y grupos de IAM. La desventaja es que descentraliza los permisos basados en roles, que actualmente son gestionados por 1Password.

Investigar qué tan complicado es otorgar acceso a usuarios de otras cuentas (dentro de la misma cuenta empresarial paraguas) a los secretos. El objetivo es mantener las claves y los permisos juntos en un solo lugar y otorgar acceso controlado a los entornos desde allí.

Apps

Por “app” entiendo un único sitio web, microservicio, cron-job u cualquier otra unidad de código autocontenida e individualmente ejecutable.

Para las apps, se sugiere que el desarrollador considere cómo se va a desplegar la app e incluya en cada repositorio de código:

Para el script de construcción, recomiendo Taskfile.yaml, aunque ciertamente hay muchas opciones.

Se recomienda instalar un clúster de Kubernetes de un solo nodo en tu estación de trabajo y desplegar tu chart en él en lugar de usar Docker Compose. La razón es que, aunque Kubernetes con un solo nodo es funcionalmente idéntico a Docker Compose, te permitirá desplegar tu app y todas sus dependencias en tu “clúster” local usando las mismas herramientas y configuraciones que usaremos para desplegarlo en entornos de nube.

Para el desarrollo local, puedes crear un archivo Helmsman apuntando a tu clúster local y usar rutas de archivo locales para apuntar a tu Helm chart. Cuando despliegues a un clúster, incluyendo “development”, deberás publicar tu imagen Docker en el registro ECR de desarrollo. También debes empaquetar y desplegar tu Helm chart versionado en el mismo registro ECR y usar su dirección oci:// en el archivo Helmsman de desarrollo. La razón es que los charts publicados tienen versiones y puedes desplegar múltiples versiones de tu chart en el recurso de nube compartido (con diferentes subdominios) o revertir a una anterior.

El Dockerfile Multi-Etapa

El siguiente es un ejemplo de un Dockerfile simple que usa una construcción multi-etapa para crear un servicio web.

FROM golang:1.25 AS build
ENV CGO_ENABLED=1
RUN go install -tags extended github.com/gohugoio/hugo@latest
RUN mkdir -p /build
WORKDIR /build
COPY . .
RUN hugo build --baseURL "https://unquabain.com/" --environment "production"

FROM nginx:stable
COPY --from=build build/public /usr/share/nginx/html

Tiene dos líneas FROM: la primera instala las herramientas necesarias para construir el código (Go, desde la imagen base, y Hugo desde el comando install), y la segunda copia solo lo que se necesita en la imagen de producción. La imagen que se despliega, por lo tanto, no tendrá Go ni Hugo ni ninguno de los archivos fuente (en este caso, un sistema de archivos Markdown).

El Helm Chart

La mejor manera de escribir un Helm chart es copiar uno existente que sea similar. Puedes comenzar con este servidor HTTP muy simple del repositorio k8s-infrastructure.

Comienza con un Chart.yaml. Las partes más importantes de este archivo son el name y la version. Estos son utilizados por Helmsman para rastrear todos los recursos que despliega en tu clúster.

A continuación está el values.yaml, que es la interfaz de tu chart. Debe incluir todos los valores que necesitan cambiar de entorno a entorno. El comando helm puede mostrar este archivo, o claves individuales de este archivo junto con sus comentarios, así que asegúrate de documentar bien este archivo. Los valores aquí no tienen que seguir la estructura de los recursos de Kubernetes que se crearán. Debes estructurar este archivo para que tenga sentido para la app que estás creando.

El archivo values.yaml contiene todos los valores predeterminados. Helm y Helmsman los superponen con otros archivos de valores proporcionados en diferentes momentos. En el archivo de configuración helmsman.yaml, puedes apuntar a: otros archivos YAML que sobreescriben los valores predeterminados; archivos YAML de secretos, que están cifrados y serán descifrados y sobreescribirán los otros archivos YAML en el despliegue; y sobreescrituras de valores individuales, que sobreescribirán los archivos de secretos. También puedes especificar valores directamente en la línea de comandos, lo que sobreescribirá todos los anteriores.

Recomiendo convertir el campo “tag” de tu URI de imagen (en tu especificación de “Pod”, que está en tu recurso “Deployment” o “StatefulSet”) en un campo separado en tu values.yaml, porque esto te permite sobreescribirlo en tu archivo helmsman.yaml, para facilitar las actualizaciones cuando tu imagen necesite ser actualizada.

apps:
  my-service:
    chart: oci://...
    version: 0.1.23
    set:
      "image.tag": "2026-04-24-16-abcdef"

La carpeta templates/ contiene archivos YAML que son cada uno plantillas Go. Los valores serán reemplazados cuando instales tu chart en tu clúster. En el caso del “Simple HTTP Server”, hay tres archivos, cada uno creando un tipo diferente de recurso.

Algunos otros recursos que puedes querer crear en tu chart incluyen:

Puedes usar la herramienta helm para instalar un Chart en cualquier clúster de Kubernetes al que tengas acceso, incluyendo tu clúster local de minikube o Colima. Cuando tu chart funcione en tu clúster local, los comandos helm package y helm push pueden usarse para publicarlo en un registro OCI. Recuerda que para cada cambio, necesitas actualizar el campo version en tu archivo Chart.yaml. Helm intenta hacer lo menos disruptivo posible, por lo que si no sabe que tu chart cambió, no enviará ninguna actualización. Para el desarrollo, probablemente quieras usar el campo “build” de SemVer, así: 0.1.0-dev01. Eso te da algo que actualizar mientras pruebas localmente, y puedes eliminarlo cuando publiques en el registro.

El Script de Construcción

El script de construcción debe saber cómo construir y publicar tanto tu imagen de app como tu chart como imágenes OCI. Recomiendo Taskfile.yaml, porque:

No es en absoluto la única herramienta que puede hacer este trabajo.

Actualmente hay varias versiones de Taskfiles en varios repositorios que pueden usarse como modelos. El objetivo es crear una versión de biblioteca que pueda usarse para inicializar nuevos sistemas.

Una recomendación es usar este comando de shell para generar tags para tus imágenes OCI:

git log -1 --date=format:%Y-%m-%d-%H --pretty=format:%cd-%h

Esto produce un tag como 2026-04-27-15-26210f1, que incluye la fecha y hora del último commit, y el hash corto del commit. Esto te permite ver de un vistazo si un tag que estás intentando desplegar es más nuevo o más antiguo que lo que ya está desplegado, y aun así apunta de forma inequívoca a un commit específico. Otra sugerencia sería usar el número del ticket actual de ClickUp en tus tags de imagen.

# Asumiendo que tu rama es 868blahblah-do-some-task
git branch | awk '/\*/{print $2}' | cut -d- -f1

Configuración de Helmsman

Hay ejemplos de configuraciones de Helmsman funcionales para cada entorno. Por ejemplo, aquí está la de dev.

Un ejemplo de “app” es este, para la Balance Stripe API:

apps:
# ...
  balance-stripe-api:
    !!merge <<: *app-template
    enabled: true
    chart: oci://614522506954.dkr.ecr.us-west-2.amazonaws.com/charts/balance-stripe-api
    version: "0.1.1"
    valuesFile: "balance-stripe-api-values.yaml"
    secretsFile: "balance-stripe-api-secrets.yaml"
    set:
      "image.tag": "2026-04-27-15-26210f1"
    depends:
      - gateway

El nombre del despliegue, balance-stripe-api, está disponible en todo el chart como {{ .Release.Name }}, y la mayoría de los charts lo usan ampliamente para vincular sus recursos entre sí.

!!merge <<: *app-template permite que la app reutilice valores comunes definidos anteriormente en el archivo.

enabled: true te permite apagar fácilmente el despliegue, eliminando todos los recursos relacionados del clúster de una sola vez.

La clave chart le dice a Helmsman dónde encontrar tu chart. Para el despliegue en tu clúster local, puede ser una ruta de archivo relativa al directorio donde se encuentra el archivo helmsman.yaml. Para charts de terceros, puede ser la ruta completa https al chart, o puedes registrar el repositorio del chart en la sección helmRepos en la parte superior del archivo YAML. Desafortunadamente, en la versión más reciente de Helm, no puedes registrar repositorios OCI aquí y tienes que escribir el nombre de dominio completo.

La clave version debe coincidir exactamente con la clave version en tu Chart.yaml si está en disco. De lo contrario, cuando publiques tu chart en un registro OCI, Helm buscará esa versión en un “manifest” y descargará la versión correspondiente. De esta manera, puedes tener varias versiones de tu chart desplegadas simultáneamente en el mismo clúster y puedes gestionar actualizaciones y retrocesos fácilmente.

valuesFile apunta a una ruta, relativa al archivo helmsman.yaml, de tus sobreescrituras de valores. También puedes pasar un arreglo de valuesFiles si quieres dividirlo. Por ejemplo, en el futuro podríamos estandarizar algunas partes de los valores de nuestros charts internos y tener un archivo common.yaml con valores por entorno como “image.registry” y algunos valores de red.

La clave secretsFile (o secretsFiles si tienes más de uno) funciona igual que valuesFile, pero usa un plugin para descifrar el archivo en el momento del despliegue. El repositorio k8s-infrastructure usa Sops/Age para cifrar los archivos de secretos en su lugar para que puedan ser registrados en el control de versiones. El cifrado usa claves asimétricas que permiten a los desarrolladores agregar nuevos valores a los archivos, incluso si no tienen acceso para descifrar los valores existentes.

La clave set te permite otro nivel de sobreescrituras sobre los archivos de valores. Puedes usarlo para destacar los valores que cambian con más frecuencia, como el tag de imagen, para facilitar las actualizaciones de los despliegues existentes.

Desplegar una Actualización en una App Existente

Hay un Taskfile.yaml en el repositorio k8s-infrastructure que tiene algunos scripts útiles para facilitar esta tarea rutinaria.

Primero, asegúrate de estar trabajando en el entorno correcto.

task choose-env

Asegúrate de que la imagen OCI haya sido publicada en un registro al que el clúster tenga acceso. El clúster tiene acceso implícito al registro ECR en la misma cuenta y AZ que él mismo. Para otros clústeres, busca instancias de ecr-secrets-updater desplegadas.

Luego, si tu app usa un solo Deployment, es posible que puedas usar la tarea utils:update-deployment-tag.

task utils:update-deployment-tag

Esto pregunta de forma interactiva para que elijas una app elegible, luego lista todos los tags de imagen que han sido publicados en el registro.

Sin embargo, este es un script muy simple y solo está pensado para ayudar en los casos de uso de desarrollo más comunes. En otros casos, puedes ejecutar

task edit

para abrir el archivo helmsman.yaml en la carpeta del entorno apropiado usando tu editor preferido ($VISUAL si está configurado, luego $EDITOR si está configurado, de lo contrario recurriendo a vi, que estoy seguro es tu editor favorito además del mío.)

Encuentra la entrada de la app y edítala según corresponda: generalmente solo la sobreescritura de "image.tag". Buena práctica: actualiza el comentario junto al tag de imagen para indicar qué ticket se está desplegando.

Ejecuta TARGET=my-application task plan para verificar qué actualizaciones hará Helm, luego TARGET=my-application task apply para aplicar los cambios.

Puedes eliminar la parte TARGET=my-application para planificar o aplicar todos los cambios que Helmsman pueda detectar. El atributo protected: true es útil aquí para evitar que Helm despliegue ciertas apps, incluso si se detectan cambios.

Si tienes alguna pregunta sobre lo que hace una tarea, el archivo Taskfile.yaml es fácil de leer. Busca la sección con el nombre de la tarea y busca la clave cmd: o cmds: debajo de ella.