From a5eeaaa2166484a068458394807c390795b4418e Mon Sep 17 00:00:00 2001 From: Santiago Lo Coco Date: Sun, 21 Apr 2024 12:44:09 +0200 Subject: [PATCH] Add English and Spanish README(s) --- README.md | 80 +++++++++++++++++++++-------------------- README_es.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++ helm/README.md | 67 +++++++++++++++++----------------- helm/README_es.md | 89 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 255 insertions(+), 72 deletions(-) create mode 100644 README_es.md create mode 100644 helm/README_es.md diff --git a/README.md b/README.md index 24e0522..7405880 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,93 @@ -# Uso de `run.sh` +[Leer en español](README_es.md) -El script `run.sh` automatiza el proceso de implementación para un entorno de `k8s` utilizando `minikube`. Incluye la construcción de imágenes `docker`, la personalización de versiones de `postgres`, la habilitación de `SSL` y la configuración de réplicas para la API. +# Using `run.sh` -## Requisitos +The `run.sh` script automates the deployment process for a `k8s` environment using `minikube`. It includes building `docker` images, customizing `postgres` versions, enabling `SSL`, and configuring replicas for the API. + +## Requirements - [minikube](https://minikube.sigs.k8s.io/docs/start/) - [docker](https://docs.docker.com/get-docker/) - [helm](https://helm.sh/docs/intro/install/) -## Uso +## Usage ```bash -./run.sh -i # Modo interactivo -./run.sh -p -s -r # Modo no interactivo -./run.sh -p -s -r -f # Modo no interactivo con Fluentd habilitado +./run.sh -i # Interactive mode +./run.sh -p -s -r # Non-interactive mode +./run.sh -p -s -r -f # Non-interactive mode with Fluentd enabled ``` -## Opciones de línea de comandos +## Command Line Options -- **-i:** Modo interactivo -- **-p :** Especificar la versión de `postgres` -- **-s :** Habilitar o deshabilitar `SSL` (Y para sí, N para no) -- **-r :** Especificar el número de réplicas para la API -- **-f:** Habilitar `fluentd` para la agregación de registros -- **-u:** Desinstalar el chart -- **-d:** Agrega datos básicos a la DB +- **-i:** Interactive mode +- **-p :** Specify the `postgres` version +- **-s :** Enable or disable `SSL` (Y for yes, N for no) +- **-r :** Specify the number of replicas for the API +- **-f:** Enable `fluentd` for log aggregation +- **-u:** Uninstall the chart +- **-d:** Add basic data to the DB -## Ejemplos +## Examples -### Cambio de versión de postgres +### Changing postgres version -Si se quiere modificar la versión de la base de datos se puede hacer simplemente: +If you want to modify the database version, you can simply do: ```bash ./run.sh -p 13.1 ``` -Esto actualizará todo lo que sea necesario para que se pueda hacer este cambio. +This will update everything necessary for this change. -### Especificar número de réplicas para la API +### Specifying number of replicas for the API ```bash ./run.sh -r 6 ``` -## Funcionalidad del script +## Script Functionality -1. **Verificación del estado de minikube:** +1. **Minikube Status Check:** - El script verifica si `minikube` ya está en ejecución y lo inicia si no lo está. + The script checks if `minikube` is already running and starts it if it's not. -2. **Versión de postgres y construcción:** +2. **Postgres Version and Build:** - Solicita al usuario la versión de postgres, construye imágenes `docker` y actualiza la versión en el archivo de valores de `helm`. + It prompts the user for the postgres version, builds `docker` images, and updates the version in the `helm` values file. -3. **Configuración de TLS:** +3. **TLS Configuration:** - Pregunta al usuario si desea habilitar `TLS` y actualiza el archivo de valores de `helm` en consecuencia. + It asks the user if they want to enable `TLS` and updates the `helm` values file accordingly. -4. **Configuración de réplicas para la API:** +4. **Configuring Replicas for the API:** - Solicita al usuario el número de réplicas para la API y actualiza el archivo de valores de `helm`. + It prompts the user for the number of replicas for the API and updates the `helm` values file. -5. **Configuración de Ingress:** +5. **Ingress Configuration:** - Habilita extensión ingress si `minikube` está en ejecución. + It enables the ingress extension if `minikube` is running. -6. **Configuración de fluentd (opcional):** +6. **Fluentd Configuration (Optional):** - Se consulta al usuario si desea habilitar `fluentd` para la agregación de registros. Puede activarse o desactivarse directamente en el archivo `values.yaml`. Es importante destacar que, con el objetivo de mantener la simplicidad y evitar el "bloat" de `values.yaml`, se proporciona un archivo adicional llamado `fluentd.yaml`. Este archivo debe pasarse como parámetro `-f` a `helm` para configurar `fluentd` con los parámetros necesarios. Cabe señalar que esto es opcional, ya que `Fluentd` puede funcionar sin estas configuraciones, pero se recomienda su uso debido a que realiza algunas condiciones de contenedores de inicio para esperar el servicio de `fluentd` y para recopilar solo los registros de los contenedores `exam-*` (y no todos los registros de `k8s`). + The user is asked whether to enable `fluentd` for log aggregation. This can be toggled directly in the `values.yaml` file. It's worth noting that, to maintain simplicity and avoid "bloat" in `values.yaml`, an additional file named `fluentd.yaml` is provided. This file should be passed as a parameter `-f` to `helm` to configure `fluentd` with necessary parameters. It's optional, as `Fluentd` can function without these configurations, but it's recommended due to performing some container startup conditions to wait for the `fluentd` service and to collect only logs from `exam-*` containers (not all logs from `k8s`). - Se utiliza la siguiente instrucción al instalar o actualizar `helm`: + The following instruction is used when installing or upgrading `helm`: ```bash helm install exam ./helm -n exam -f helm/values.yaml -f helm/fluentd.yaml ``` - Para ver los registros de los contenedores `exam-*`, podés usar: + To view logs from `exam-*` containers, you can use: ```bash kubectl logs -n exam exam-fluentd-0 ``` - Para realizar la configuración y el envío a un backend de registros como `elasticsearch`, podés editar `fluentd.yaml` según tus necesidades. + To configure and send logs to a log backend like `elasticsearch`, you can edit `fluentd.yaml` as per your requirements. -7. **Configuración de Secrets (opcional):** +7. **Secrets Configuration (Optional):** - Para no mantener los secretos en el SVC (si se utiliza uno), se pueden pasar a `helm` mediante un archivo `secrets.yaml` con la opción `-f`. Si existe `./helm/secrets.yaml` (en la carpeta `./helm`, es decir en la misma ubicación que `values.yaml`), se utilizarán estos valores; de lo contrario, se utilizarán los definidos en `values.yaml`. Estos valores sobrescribirán los existentes. + To avoid keeping secrets in the SVC (if one is used), they can be passed to `helm` via a `secrets.yaml` file with the `-f` option. If `./helm/secrets.yaml` exists (in the `./helm` folder, i.e., in the same location as `values.yaml`), these values will be used; otherwise, those defined in `values.yaml` will be used. These values will override existing ones. - Cabe destacar que al crear `./helm/secrets.yaml`, el script `run.sh` lo detectará automáticamente y lo utilizará al ejecutar `helm`. Por lo tanto, no es necesario realizar acciones adicionales, ya que el script gestionará la detección y el paso de este archivo a `helm`. + It's worth noting that upon creating `./helm/secrets.yaml`, the `run.sh` script will automatically detect and use it when running `helm`. Therefore, no additional actions are required, as the script will handle the detection and passing of this file to `helm`. diff --git a/README_es.md b/README_es.md new file mode 100644 index 0000000..24e0522 --- /dev/null +++ b/README_es.md @@ -0,0 +1,91 @@ +# Uso de `run.sh` + +El script `run.sh` automatiza el proceso de implementación para un entorno de `k8s` utilizando `minikube`. Incluye la construcción de imágenes `docker`, la personalización de versiones de `postgres`, la habilitación de `SSL` y la configuración de réplicas para la API. + +## Requisitos + +- [minikube](https://minikube.sigs.k8s.io/docs/start/) +- [docker](https://docs.docker.com/get-docker/) +- [helm](https://helm.sh/docs/intro/install/) + +## Uso + +```bash +./run.sh -i # Modo interactivo +./run.sh -p -s -r # Modo no interactivo +./run.sh -p -s -r -f # Modo no interactivo con Fluentd habilitado +``` + +## Opciones de línea de comandos + +- **-i:** Modo interactivo +- **-p :** Especificar la versión de `postgres` +- **-s :** Habilitar o deshabilitar `SSL` (Y para sí, N para no) +- **-r :** Especificar el número de réplicas para la API +- **-f:** Habilitar `fluentd` para la agregación de registros +- **-u:** Desinstalar el chart +- **-d:** Agrega datos básicos a la DB + +## Ejemplos + +### Cambio de versión de postgres + +Si se quiere modificar la versión de la base de datos se puede hacer simplemente: + +```bash +./run.sh -p 13.1 +``` + +Esto actualizará todo lo que sea necesario para que se pueda hacer este cambio. + +### Especificar número de réplicas para la API + +```bash +./run.sh -r 6 +``` + +## Funcionalidad del script + +1. **Verificación del estado de minikube:** + + El script verifica si `minikube` ya está en ejecución y lo inicia si no lo está. + +2. **Versión de postgres y construcción:** + + Solicita al usuario la versión de postgres, construye imágenes `docker` y actualiza la versión en el archivo de valores de `helm`. + +3. **Configuración de TLS:** + + Pregunta al usuario si desea habilitar `TLS` y actualiza el archivo de valores de `helm` en consecuencia. + +4. **Configuración de réplicas para la API:** + + Solicita al usuario el número de réplicas para la API y actualiza el archivo de valores de `helm`. + +5. **Configuración de Ingress:** + + Habilita extensión ingress si `minikube` está en ejecución. + +6. **Configuración de fluentd (opcional):** + + Se consulta al usuario si desea habilitar `fluentd` para la agregación de registros. Puede activarse o desactivarse directamente en el archivo `values.yaml`. Es importante destacar que, con el objetivo de mantener la simplicidad y evitar el "bloat" de `values.yaml`, se proporciona un archivo adicional llamado `fluentd.yaml`. Este archivo debe pasarse como parámetro `-f` a `helm` para configurar `fluentd` con los parámetros necesarios. Cabe señalar que esto es opcional, ya que `Fluentd` puede funcionar sin estas configuraciones, pero se recomienda su uso debido a que realiza algunas condiciones de contenedores de inicio para esperar el servicio de `fluentd` y para recopilar solo los registros de los contenedores `exam-*` (y no todos los registros de `k8s`). + + Se utiliza la siguiente instrucción al instalar o actualizar `helm`: + + ```bash + helm install exam ./helm -n exam -f helm/values.yaml -f helm/fluentd.yaml + ``` + + Para ver los registros de los contenedores `exam-*`, podés usar: + + ```bash + kubectl logs -n exam exam-fluentd-0 + ``` + + Para realizar la configuración y el envío a un backend de registros como `elasticsearch`, podés editar `fluentd.yaml` según tus necesidades. + +7. **Configuración de Secrets (opcional):** + + Para no mantener los secretos en el SVC (si se utiliza uno), se pueden pasar a `helm` mediante un archivo `secrets.yaml` con la opción `-f`. Si existe `./helm/secrets.yaml` (en la carpeta `./helm`, es decir en la misma ubicación que `values.yaml`), se utilizarán estos valores; de lo contrario, se utilizarán los definidos en `values.yaml`. Estos valores sobrescribirán los existentes. + + Cabe destacar que al crear `./helm/secrets.yaml`, el script `run.sh` lo detectará automáticamente y lo utilizará al ejecutar `helm`. Por lo tanto, no es necesario realizar acciones adicionales, ya que el script gestionará la detección y el paso de este archivo a `helm`. diff --git a/helm/README.md b/helm/README.md index b29ffcf..87be56b 100644 --- a/helm/README.md +++ b/helm/README.md @@ -1,21 +1,23 @@ -# Decisiones de diseño del chart +[Leer en español](README_es.md) -Este README explica algunas de las decisiones de diseño tomadas durante el desarrollo del chart `helm`. +# Design decisions of the chart -## Uso de namespace +This README explains some of the design decisions made during the development of the `helm` chart. -Se utiliza el namespace `exam` para poder aislar los recursos (con todos los beneficios que eso trae) y no usar el namespace `default`. +## Usage of Namespace -## Uso de default values +The namespace `exam` is used to isolate the resources (with all the benefits that brings) and avoid using the `default` namespace. -Todas las variables que se repiten y que, en un principio, no tendría sentido cambiarlas para este chart se marcaron con default. +## Usage of Default Values -Por ejemplo, busque los default de service.yaml. Verá que `type` es por defecto "ClusterIP" y que `targetPort` es por defecto `$port`. +All variables that are repeated and that, initially, wouldn't make sense to change for this chart are marked with default values. -Esto tiene dos beneficios: +For example, look for the defaults in `service.yaml`. You'll see that `type` defaults to "ClusterIP" and `targetPort` defaults to `$port`. -1) Elimina redundancia en values.yaml -2) Da libertad para que en un futuro se pueda simplemente modificarlo en `values.yaml`. Por ejemplo, supongamos que queremos cambiar el `type` a "NodePort" en el servicio de `api`, basta con hacer el siguiente cambio: +This has two benefits: + +1) Reduces redundancy in `values.yaml`. +2) Provides freedom to easily modify it in the future in `values.yaml`. For example, suppose we want to change the `type` to "NodePort" in the `api` service, it's sufficient to make the following change: ```yaml services: @@ -26,9 +28,9 @@ services: type: "NodePort" ``` -## Flexibilidad con el dominio +## Flexibility with Domain -En `ingress` se repite el `host` debido a que esto facilita que la api pueda estar en otro dominio. Por ejemplo: +In `ingress`, the `host` is repeated to facilitate the API being on another domain. For example: ```yaml ingress: @@ -54,37 +56,36 @@ ingress: - api.kube.slc.ar ``` -## Certicados para el ingress +## Certificates for Ingress -Se puede pasar certificados autogenerados en `ingress.ssl.*` PERO se debe notar las restricciones de `helm` de seguridad: solo se pueden usar archivos relativos al path del chart. Por lo tanto, si se desea usar un archivo de "afuera" se puede hacer un symbolic link. Por ejemplo: `cd helm && ln -sf /usr/local/etc/ssl/certs/ca.crt ca.crt && ln -sf /usr/local/etc/ssl/private/ca.key ca.key`. Y luego se puede pasar esos archivos al `ingress.ssl.*`. +Autogenerated certificates can be passed in `ingress.ssl.*`, BUT note the security restrictions of `helm`: only files relative to the chart path can be used. Therefore, if you want to use a file from "outside," you can create a symbolic link. For example: `cd helm && ln -sf /usr/local/etc/ssl/certs/ca.crt ca.crt && ln -sf /usr/local/etc/ssl/private/ca.key ca.key`. Then, pass those files to `ingress.ssl.*`. -Note que para que se usen estos secrets: -1) si ya existía el `secret-crt` se debe borrar y hacer un `helm upgrade` -2) si no existía con un `helm install` basta (o mismo un `helm upgrade` si ya estaba andando) +Note that for these secrets to be used: +1) If `secret-crt` already existed, it must be deleted and a `helm upgrade` performed. +2) If it didn't exist, a `helm install` is sufficient (or even a `helm upgrade` if it was already running). -Por lo tanto, supongamos que se quieren actualizar los certificados por unos autogenerados por usted (y para actualizarlos una vez expirados los autogenerados por usted). Los pasos son los siguientes: +Therefore, suppose you want to update the certificates with ones autogenerated by you (and to update them once the ones autogenerated by you expire). The steps are as follows: -1) Borrar `exam-crt` -2) Actualizar certificados -3) Ponerlos en el `values.yaml` de haberse modificado el path o si antes se usaba uno autogenerado por helm -4) Hacer `helm upgrade` +1) Delete `exam-crt`. +2) Update certificates. +3) Put them in the `values.yaml` if the path has been modified or if a helm-autogenerated one was used before. +4) Perform `helm upgrade`. -Si se quiere actualizar los autogenerados por helm los pasos son: +If you want to update the ones autogenerated by helm, the steps are: -1) Borrar `exam-crt` -2) Hacer `helm upgrade` +1) Delete `exam-crt`. +2) Perform `helm upgrade`. -Note que si se hace un upgrade solo NO se regenerará el `exam-crt`. Esto es esperado ya que sino cada vez que modificamos algo se estará autogenerando un nuevo certificado! +Note that if you only perform an upgrade, the `exam-crt` will not be regenerated. This is expected because otherwise, every time we modify something, a new certificate would be autogenerated! +## Stateful for Postgres -## Stateful para postgres +Choosing to implement a `stateful.yaml` file as we need PostgreSQL to be an application with "stable, persistent storage" (see [documentation](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#using-statefulsets)). Additionally, in the future, if we wanted to have READ replicas, it could be done very easily by adding containers and necessary logic. For that case, a stateful set must be used to always keep the master identified. I left it as more of a future-proofing measure. -Se eligió implementar un archivo `stateful.yaml` ya que necesitamos que postgres sea una aplicación con "Stable, persistent storage" (ver (documentación)[https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#using-statefulsets]). Además, en un futuro, si quisieramos tener READ replicas se podría hacer muy fácilmente agregando containers y la lógica necesaria. Para ese caso se debe usar si o si un stateful set para mantener al master siempre identificado. Lo dejé como algo más bien future-proof. +Note that if we were using a deployment, we would have many problems with the application's `stop` because they are sharing the same data volume at the same time (until the new pod is successfully up, the old one will remain active and then stop). This could lead to corruption of the database. This problem is easily fixed with a StatefulSet. -Notemos que de usar un deployment tendríamos muchos problemas con el `stop` de la aplicación ya que están compartiendo el mismo volumen de datos al mismo tiempo (pues hasta que no levante correctamente el nuevo pod el viejo seguirá activo y luego parará). Esto podría pasar que se corrompa la base de datos. Se arregla simplemente con un StatefulSet este problema. +On the other hand, if we were using a cluster, `RollingUpdate` would save us from an image that does not exist, for example, as it starts with the pods with the highest cardinal and if one fails, it doesn't continue updating. -Por otro lado, si estuvisemos usando un cluster el `RollingUpdate` nos salvaría de una imagen que no existe por ejemplo ya que empieza por los pods con cardinal más alto y si alguno falla no sigue actualizando. +## Connection Tests -## Tests de conexión - -Se pueden correr con `helm test exam -n exam` \ No newline at end of file +They can be run with `helm test exam -n exam`. diff --git a/helm/README_es.md b/helm/README_es.md new file mode 100644 index 0000000..82f3e90 --- /dev/null +++ b/helm/README_es.md @@ -0,0 +1,89 @@ +# Decisiones de diseño del chart + +Este README explica algunas de las decisiones de diseño tomadas durante el desarrollo del chart `helm`. + +## Uso de namespace + +Se utiliza el namespace `exam` para poder aislar los recursos (con todos los beneficios que eso trae) y no usar el namespace `default`. + +## Uso de default values + +Todas las variables que se repiten y que, en un principio, no tendría sentido cambiarlas para este chart se marcaron con default. + +Por ejemplo, busque los default de service.yaml. Verá que `type` es por defecto "ClusterIP" y que `targetPort` es por defecto `$port`. + +Esto tiene dos beneficios: + +1) Elimina redundancia en values.yaml +2) Da libertad para que en un futuro se pueda simplemente modificarlo en `values.yaml`. Por ejemplo, supongamos que queremos cambiar el `type` a "NodePort" en el servicio de `api`, basta con hacer el siguiente cambio: + +```yaml +services: + - api: + name: "api" + tier: "backend" + port: 5000 + type: "NodePort" +``` + +## Flexibilidad con el dominio + +En `ingress` se repite el `host` debido a que esto facilita que la api pueda estar en otro dominio. Por ejemplo: + +```yaml +ingress: + ssl: true + annotations: + nginx.ingress.kubernetes.io/ssl-redirect: "true" + hosts: + - host: kube.slc.ar + paths: + - path: / + name: "client" + port: 8080 + pathType: "Prefix" + - host: api.kube.slc.ar + - path: / + name: "api" + port: 5000 + pathType: "Prefix" + tls: + - secretName: exam-crt + hosts: + - kube.slc.ar + - api.kube.slc.ar +``` + +## Certicados para el ingress + +Se puede pasar certificados autogenerados en `ingress.ssl.*` PERO se debe notar las restricciones de `helm` de seguridad: solo se pueden usar archivos relativos al path del chart. Por lo tanto, si se desea usar un archivo de "afuera" se puede hacer un symbolic link. Por ejemplo: `cd helm && ln -sf /usr/local/etc/ssl/certs/ca.crt ca.crt && ln -sf /usr/local/etc/ssl/private/ca.key ca.key`. Y luego se puede pasar esos archivos al `ingress.ssl.*`. + +Note que para que se usen estos secrets: +1) si ya existía el `secret-crt` se debe borrar y hacer un `helm upgrade` +2) si no existía con un `helm install` basta (o mismo un `helm upgrade` si ya estaba andando) + +Por lo tanto, supongamos que se quieren actualizar los certificados por unos autogenerados por usted (y para actualizarlos una vez expirados los autogenerados por usted). Los pasos son los siguientes: + +1) Borrar `exam-crt` +2) Actualizar certificados +3) Ponerlos en el `values.yaml` de haberse modificado el path o si antes se usaba uno autogenerado por helm +4) Hacer `helm upgrade` + +Si se quiere actualizar los autogenerados por helm los pasos son: + +1) Borrar `exam-crt` +2) Hacer `helm upgrade` + +Note que si se hace un upgrade solo NO se regenerará el `exam-crt`. Esto es esperado ya que sino cada vez que modificamos algo se estará autogenerando un nuevo certificado! + +## Stateful para postgres + +Se eligió implementar un archivo `stateful.yaml` ya que necesitamos que postgres sea una aplicación con "Stable, persistent storage" (ver (documentación)[https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#using-statefulsets]). Además, en un futuro, si quisieramos tener READ replicas se podría hacer muy fácilmente agregando containers y la lógica necesaria. Para ese caso se debe usar si o si un stateful set para mantener al master siempre identificado. Lo dejé como algo más bien future-proof. + +Notemos que de usar un deployment tendríamos muchos problemas con el `stop` de la aplicación ya que están compartiendo el mismo volumen de datos al mismo tiempo (pues hasta que no levante correctamente el nuevo pod el viejo seguirá activo y luego parará). Esto podría pasar que se corrompa la base de datos. Se arregla simplemente con un StatefulSet este problema. + +Por otro lado, si estuvisemos usando un cluster el `RollingUpdate` nos salvaría de una imagen que no existe por ejemplo ya que empieza por los pods con cardinal más alto y si alguno falla no sigue actualizando. + +## Tests de conexión + +Se pueden correr con `helm test exam -n exam` \ No newline at end of file