Saltar al contenido principal
Version: 1.8.1

Configuracion Inicial

Clonado del repositorio​

El repositorio de despliegue contiene un submodulo como repositorio base llamado siu-k8s

Para clonar simulanteamente tanto el repositorio de despliegue como el submodulo debe ejecutarse el siguiente comando:

git clone --recursive https://hub.siu.edu.ar/siu/kubernetes/deployments-k8s.git

Una vez clonado, cambie la referencia del repositorio que por defecto es origin a upstream

git remote rename origin upstream

Finalmente, agregue su repositorio personal como origin para poder subir sus cambios locales

git remote add origin <link-a-su-repositorio-remoto>
Importante

Si ya posee commits en su repositorio origin, al querer subir posteriormente sus cambios locales tendrá conflicto por ramas divergentes. Asegurese de que su repositorio origin se encuentre vacio.

Estructura de proyecto​

A continuación se presenta un diagrama como referencia de la estructura del proyecto y una breve explicación del mismo:

Diagrama de estructura del proyecto

link al diagrama

A la hora de trabajar localmente, el repositorio base (es decir, el submodulo SIU-k8s) es considerado una dependencia y no se modifica manualmente ya que la estructura de dicho repositorio (particularmente sus archivos YAML) se utilizan como referencia para la herramienta kustomize. No obstante, este repositorio tendrá modificaciones, ya que el SIU brindará actualizaciones del mismo para ofrecer versiones actualizadas de las aplicaciones bajo este esquema de despliegue.

Las personalizaciones de kustomize propuestas en este despliegue se encuentran dentro de la carpeta denominada template. Esta carpeta, a su vez, cuenta con un script de bash en template/scripts-init/nuevo-overlay.sh el cuál deberá ejecutar junto con determinados argumentos para generar un directorio final denominado en el diagrama como overlay. Este overlay contendrá los archivos kustomization.yaml que terminarán impactando en su despliegue.

En resumen:

  • El directorio siu-k8s es una dependencia de su despliegue y no debe modificarse manualmente, más si actualizarse.
  • El directorio template solamente lo utilizará para generar la carpeta de su nuevo overlay con el script template/scripts-init/nuevo-overlay.sh.
  • El directorio que corresponde a su overlay (cuyo nombre cambiará al que usted elija al ejecutar el script nuevo-overlay.sh) tendrá los archivos que debe modificar para su entorno.

Crear un namespace para su cluster​

El formato de template actual propone el despliegue de las aplicaciones SIU (y sus dependencias) dentro de un único namespace en un primer momento, ya que es necesario para ejecutar el script inicial (template/scripts-init/nuevo-overlay.sh).

Para crear el namespace en el cluster al cual está conectado, utilice el siguiente comando

kubectl create namespace <namespace>

por ejemplo

kubectl create namespace template-universidad
Advertencia sobre multiples namespaces

Si usted ya posee conocimientos sobre kubernetes y namespaces, y considera preferible utilizar multiples namespaces en su entorno, es posible hacerlo.

Para esto es importante que, antes de desplegar cualquier pod y después de haber ejecutado el script ./nuevo-overlay.sh, siga las instrucciones de la siguiente guia: Multi Namespaces donde se detalla cómo realizar esta configuración.

Crear un Overlay Personalizado​

Para crear un overlay personalizado primeramente hay que dirigirse a la ruta template/scripts-init/ donde estará el script para poder generarlo.

cd template/scripts-init/

En segundo lugar es necesario guardar sus credenciales del registry privado donde se alojan las imagenes de las aplicaciones SIU necesarias para el despliegue (las mismas están alojadas en la instancia Gitlab del SIU: hub.siu.edu.ar). Para esto, realice una copia del archivo registry-secrets.json.dist y edite el mismo con sus credenciales:

cp registry-secrets.json.dist registry-secrets.json
vi registry-secrets.json
Nota

Se recomienda utilizar tokens de acceso para ambos registries, con el fin de evitar guardar la contraseña de su usuario como texto plano en el registry-secrets.json

Como último paso debe ejecutar el script nuevo-overlay.sh, proporcionando como argumentos el nombre del overlay, el dominio de su entorno y el namespace.

./nuevo-overlay.sh <nombre-del-overlay> <dominio> <namespace>
Nota
  • Tiene que tener permisos de escritura sobre el directorio raiz para ejecutar el script.
  • Después de ejecutar el script, si necesita realizar alguna personalización adicional en los secrets generados, puede editar los archivos en <nombre-del-overlay>/secrets según sea necesario.
  • El dominio uunn.edu.ar tiene que tener una entrada en su DNS apuntando a la IP que luego se configura en el controlador del ingress. Deberá hacer lo mismo para cada subdominio, en caso que los tenga.

por ejemplo

./nuevo-overlay.sh uunn-overlay uunn.edu.ar uunn-namespace

Este script se encargará de realizar las siguientes tareas:

  • Crear la estructura de directorios del overlay.
  • Configurar el dominio especificado.
  • Configurar el namespace especificado.
  • Generar y configurar todos los secrets necesarios para el despliegue.
Advertencia sobre dominio

El repositorio de dependencia siu-k8s propone por defecto el acceso mediante ingress a todos los servicios bajo un subpath (Ejemplo: Para ingresar a arai-usuarios, ingresaría mediante https://uunn.edu.ar/usuarios, como puede observar).

Advertencia sobre secrets

Notese que el .gitignore del proyecto está excluyendo los siguientes directorios

**/secrets/**
!template/secrets/**

Asegurese que los secrets que haya creado para su overlay no sean commiteados dentro de su repositorio para evitar filtraciones de los mismos.

Posterior a la ejecucion del script anterior dirijase a la raíz del proyecto para facilitar los pasos posteriores

cd ../..

Configuracion servicios basicos​

En este apartado se detallan los objetos y servicios que deben estar configurados y funcionando en su ambiente. Por motivos de confiabilidad, performance y simplicidad se recomienda instalar Postgres, MinIO y LDAP por fuera del cluster (En el despliegue de cada módulo se explaya la manera de conectarse con estos últimos servicios mencionados).

Storage Class​

Para la arquitectura de este despliegue deberá elegir un proveedor de Storage Class acorde a su infraestructura y requerimientos (ej: TrueNAS). Tenga en cuenta que para configurar esto, deberá realizar modificaciones en los siguientes archivos, acompañandose de la documentación del proveedor elegido:

 nano uunn-overlay/common/pvc/kustomization.yaml

Lectura adicional sugerida sobre storage classes:

Nota

El proveedor de Storage Class debe soportar ReadWriteMany. Pues se necesita que varios pods puedan escribir en el volumen desde diferentes nodos.

Lectura adicional sugerida sobre persistent volumen:

Ingress​

En la arquitectura de este despliegue se optó por utilizar nginx como proveedor de ingress, por lo que las configuraciones por defecto son en torno a este IngressClass.

Lectura adicional sugerida sobre ingress nginx:

Advertencia

Si lo desea puede utilizar un Ingress distinto, pero tenga en cuenta que eso requerirá un mayor mantenimiento y personalización de los archivos de kustomize, y deberá sostenerse sobre la documentación oficial de su ingress elegido para las modificaciones pertinentes.

Por defecto, las APIs se encuentran expuestas en el rango 127.0.0.1/32, es decir que no se pueden acceder externamente. De requerirlo, puede habilitar el acceso de otros rangos de su red a las APIs de cada servicio siguiendo la siguiente guía: Personalización: Habilitar acceso externo a las APIs.

El administrador de certificados que usa este despliegue es cert-manager que gestiona los certificados del cluster y el emisor a nivel del cluster (CRDS ClusterIssuer) por el que se opto es Let’s Encrypt.

Lectura adicional sugerida sobre cert-manager: https://cert-manager.io/docs/

El Ingress Nginx del proyecto tiene habilitado por defecto el WAP (Web Application Firewall) ModSecurity. Si se experimenta problemas con códigos de error 403 en alguna aplicación, es posible que una regla de ModSecurity esté bloqueando la solicitud.

Para obtener más información sobre cómo agregar o ajustar reglas de ModSecurity, consulte la siguiente guía.

Uso de nombres DNS en kubernetes​

En Kubernetes, los Services actúan como una capa de abstracción, habilitando la comunicación entre diferentes partes de una aplicación. Esto es posible gracias a un mecanismo conocido como Kubernetes Service DNS, que asigna nombres DNS a los Services, facilitando que las aplicaciones descubran y se comuniquen entre ellas de manera dinámica.

Cuando un Service es creado dentro de un clúster de Kubernetes, se le asigna automáticamente un registro DNS que es accesible dentro del clúster.

Dependiendo de si los pods que necesitan acceder al servicio se encuentran en el mismo o en diferentes namespaces, la forma de utilizacion puede variar.

A continuacion se muestra un ejemplo que es aplicable a lo largo del despliegue:

Mismo Namespace​

En este caso, al estar dentro del mismo namespace, solo es necesario utilizar el nombre del servicio para que Kubernetes lo resuelva correctamente.

###### CONFIG DB ######
DB_HOST=db-siu
DB_PORT=5432
DB_DBNAME=usuarios
......

Distinto Namespace​

Si el servicio de base de datos está en un namespace diferente, se debe incluir el nombre completo del servicio y seguido del namespace.

###### CONFIG DB ######
DB_HOST=db-siu.<namespace>
DB_PORT=5432
DB_DBNAME=usuarios
......