Saltar al contenido principal
Version: 1.8.1

Configuracion Inicial

Clonado del repositorio​

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

Para clonar simulanteamente tanto el repositorio de deployment como el submodulo debe ejecutarse el siguiente comando a la hora del git clone

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

En caso de tener problemas para clonar el submodulo por https, puede settearse la url por ssh con

git submodule set-url siu-k8s git@hub.siu.edu.ar:siu/kubernetes/siu-k8s.git

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
......

Despliegue de Postgresql, Ldap, Minio (Opcional).​

Si bien para entornos productivos es posible realizar las conexiones de los módulos del cluster a servicios on premise (siempre que la red lo permita), el repositorio de la estructura propuesta cuenta también con manifiestos para realizar el despliegue de servicios tales como postgres, ldap y minio. De esta manera puede utilizar pods de Kubernetes en lugar de binarios on-premise.

Para desplegar los servicios debe ejecutar los siguientes comandos:

kustomize build --load-restrictor LoadRestrictionsNone uunn-overlay/services/postgres | kubectl apply -f -
kustomize build --load-restrictor LoadRestrictionsNone uunn-overlay/services/ldap | kubectl apply -f -
kustomize build --load-restrictor LoadRestrictionsNone uunn-overlay/services/minio | kubectl apply -f -

Output esperado:

configmap/db-siu-c48f578kb6 created
secret/db-siu-d9fc2b7cmd created
service/db-siu created
persistentvolumeclaim/db-siu-data created
deployment.apps/db-siu createdconfigmap/ldap-k25cbdk25g created
configmap/ldap.env-h4mf8fd4kg created
secret/ldap-9b7cb68kbf created
service/ldap-siu created
persistentvolumeclaim/ldap-config created
persistentvolumeclaim/ldap-data created
deployment.apps/ldap-siu createdsecret/minio-8989mhc7c5 created
service/minio created
persistentvolumeclaim/minio-data created
deployment.apps/minio created