Despliegue de una app en K3S en AWS EC2 con GitHub Actions y ECR

En este artículo práctico repasamos cómo desplegar una aplicación multicontenedor en un clúster K3S alojado en una instancia EC2 de AWS, integrando GitHub Actions para CI CD y AWS ECR como registro de imágenes. Además presentamos recomendaciones y buenas prácticas útiles para equipos que buscan implementar soluciones de software a medida y servicios en la nube.

Q2BSTUDIO es una empresa de desarrollo de software especializada en aplicaciones a medida y software a medida, con experiencia en inteligencia artificial, ciberseguridad y servicios cloud. Si necesitas migrar o desplegar cargas en la nube, podemos ayudarte con servicios cloud AWS y Azure y arquitecturas seguras y automatizadas.

Resumen del stack de la demo: frontend en React, backend en Node y Express, base de datos MongoDB, contenedorización con Docker, orquestación con K3S y registro de imágenes en AWS ECR. El flujo general: construir images, subir a ECR, actualizar manifiestos Kubernetes y aplicar cambios en K3S mediante un job de GitHub Actions que se comunica por SSH con la EC2.

Preparación de la instancia EC2 y K3S: actualizar el sistema, instalar K3S con el script oficial curl -sfL https://get.k3s.io | sh - y comprobar el nodo con sudo k3s kubectl get node. K3S es una distribución ligera de Kubernetes ideal para nodos con recursos limitados; soporte completo de API Kubernetes, instalación sencilla y optimizada para entornos edge y pruebas.

Instalar Docker en Ubuntu y limpiar paquetes conflictivos, configurar la key GPG de Docker, añadir el repositorio y ejecutar sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin seguido de sudo docker run hello-world para verificar la instalación.

Clonar el repositorio de demo, revisar docker compose y Dockerfiles para frontend, backend y MongoDB. El flujo de desarrollo local usa docker compose up -d para construir y ejecutar contenedores; comprobar con docker ps -a y probar la aplicación accediendo a la IP de la EC2 en el puerto mapeado para el frontend.

Antes de pasar a Kubernetes conviene ajustar variables de entorno en el frontend para que apunten a la IP o al NodePort del backend. En local se editan archivos .env y se validan las llamadas a la API desde el navegador con las herramientas de desarrollador para confirmar respuestas 200 al crear tareas o consultar endpoints.

Manifiestos Kubernetes esenciales: Deployment para api con replicas para disponibilidad y estrategia RollingUpdate, Service tipo NodePort para exponer la API, Secret para credenciales MongoDB en base64, Service headless tipo ClusterIP None y StatefulSet con PV y PVC para MongoDB para garantizar identidad estable y persistencia de datos. Adicionalmente ConfigMap para inyectar REACT_APP_API_URL al frontend y Deployment para el web con requests y limits para un correcto scheduling.

Por ejemplo, conceptos clave a incluir en los manifiestos: definir replicas, strategy RollingUpdate, selector matchLabels, volumeClaimTemplates en el StatefulSet, clusterIP None para servicio headless y uso de secretKeyRef y configMapKeyRef para no hardcodear credenciales ni endpoints.

Crear repositorio ECR: desde la consola AWS ECR crear repositorio privado, anotar el endpoint y autenticar Docker con aws ecr get-login-password --region region | docker login --username AWS --password-stdin ACCOUNT.dkr.ecr.region.amazonaws.com. Es recomendable configurar políticas de retención y escaneo de imágenes automático.

Pipeline de GitHub Actions: pasos principales son checkout del repo, preparar buildx, autenticación en ECR con aws-actions/amazon-ecr-login, generar un tag de imagen con timestamp, construir y etiquetar las imágenes con docker compose build y docker tag, escanear con Trivy, push a ECR y finalmente ejecutar comandos por SSH en la EC2 para actualizar los manifiestos y aplicar kubectl apply -f. En el job remoto conviene sustituir en los YAML solo la parte image para mantener trazabilidad de los manifiestos y versionado.

Configurar secrets en GitHub: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ECR_REGISTRY, EC2_HOST, EC2_USER, EC2_SSH_KEY entre otros. En la EC2 crear el secret mongo-secret con kubectl create secret generic mongo-secret --from-literal=username=admin --from-literal=password=clave segura para evitar exponer credenciales en texto plano dentro de los manifiestos.

Buenas prácticas operativas: usar namespaces para separar entornos, health checks readiness y liveness probes, recursos requests y limits, backups de volúmenes para bases de datos, control de acceso a ECR mediante roles IAM y rotación de claves, y escaneos automáticos de seguridad en la pipeline con herramientas como Trivy. Para auditoría y seguridad adicional, Q2BSTUDIO ofrece servicios de ciberseguridad y pentesting que pueden integrarse en el ciclo de despliegue para endurecer la plataforma servicios de ciberseguridad.

Al desplegar, validar con kubectl get all y kubectl rollout status deployment/web y deployment/api, comprobar que los NodePorts están accesibles desde la IP de la EC2 y que las peticiones del frontend al backend retornan códigos 200. Monitorizar logs con kubectl logs y revisar estado del StatefulSet y los PVC para confirmar persistencia de MongoDB.

Beneficios de esta arquitectura: despliegue reproducible y automatizado, control de versiones de imagen y manifiestos, escalabilidad del backend mediante replicas, persistencia garantizada para MongoDB y posibilidad de implementar estrategias de despliegue como blue green o canary si se desea mayor seguridad en la entrega. Además, combinando K3S con pipelines GitHub Actions y ECR se obtiene un flujo CI CD ligero y efectivo para entornos de pruebas y producción ligera.

En Q2BSTUDIO desarrollamos soluciones a medida, desde la automatización de procesos hasta proyectos complejos de inteligencia artificial e inteligencia de negocio con Power BI. Si te interesa implementar agentes IA o IA para empresas que integren modelos en tus aplicaciones, podemos ayudarte a diseñar la arquitectura y la pipeline de despliegue necesaria. Consulta nuestros servicios de inteligencia artificial para empresas y proyectos a medida en inteligencia artificial.

Palabras clave: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi. Si quieres que Q2BSTUDIO te acompañe en la implantación, auditoría o migración de tus aplicaciones a una arquitectura basada en contenedores y nube, contacta para una evaluación personalizada y una propuesta de valor alineada con tus objetivos de negocio.