ansible-role-shipyard

Acerca de Shipyard

Shipyard es una herramienta para orquestar clústeres y pilas de Docker Swarm a partir de playbooks de Ansible.

Está inspirada en gran medida en Helm y helmfile y proporciona los mismos conceptos en un entorno habilitado para Swarm, pero no específico de Kubernetes.

Conceptos:

• Shipyard Chart: Un paquete que define una pila de docker compose y todos sus archivos relacionados (archivos de configuración, variables de entorno, etc.), similar a un Helm Chart, un archivo RPM de yum o una fórmula de Homebrew. Un chart contiene todas las definiciones de recursos necesarias para desplegar y ejecutar una aplicación como una pila de Docker Swarm, organizadas en un formato específico. Un chart puede usarse para desplegar una aplicación simple o una pila completa de aplicación web con múltiples dependencias, como servidores HTTP, bases de datos, cachés, etc. (similar a un Helm Chart).
• Shipyard Stack: una instancia de un Shipyard Chart, personalizada a través de un archivo values.yaml. (similar a un Helm Release).
• shipyard.yaml: un archivo que define qué Charts instanciar utilizando qué valores en qué hosts de docker. (similar a un archivo helmfile.yaml).

Como puedes ver, los conceptos son muy similares a Helm y helmfile. La principal diferencia es que Shipyard no es específico de Kubernetes y no requiere un clúster de Kubernetes para funcionar. En su lugar, usa Docker Swarm para desplegar las pilas.

Requisitos previos

El rol de Ansible asume que has preconfigurado los hosts de destino con:

• Docker Swarm (es decir, docker swarm deploy funciona).
• Docker Compose (es decir, docker-compose funciona).
• Autenticación de pull de Docker para las imágenes utilizadas (es decir, docker pull mi-imagen funciona).

Variables del rol

El rol se puede personalizar mediante algunas variables opcionales:

• shipyard_filename: Ruta a tu archivo shipyard.yaml. Por defecto: {{inventory_path}}/shipyard.yaml. Este archivo puede ser una plantilla Jinja2.
• shipyard_charts_path: Ruta a tu directorio de charts. Por defecto: {{inventory_path}}/shipyard/charts.
• shipyard_stacks_path: Ruta a tu directorio de pilas (values.yaml / values.sops.yaml). Por defecto: {{inventory_path}}/shipyard/stacks.
• shipyard_stacks_docker_secrets: Una lista de Docker Secrets. Por defecto [].
• shipyard_tag: opcionalmente solo despliega pilas con esta etiqueta. Por defecto: vacío.

Uso

Obtener el rol desde Ansible galaxy

Configura tu archivo requirements.yml para incluir el rol:

roles:
  - name: linkorb.shipyard

Luego ejecuta ansible-galaxy install -r requirements.yml para instalar el rol.

Crear un archivo shipyard.yaml:

El archivo shipyard.yaml define qué pilas se despliegan en qué hosts. Es similar a un archivo helmfile.yaml.

# shipyard.yaml
stacks:
  - name: mi-traefik
    chart: traefik
    host: swarm-host-a
    values: mi-traefik/values.yaml
    tag: lb

  - name: mi-whoami
    chart: whoami
    host: swarm-host-a
    values: mi-whoami/values.yaml
    tag: apps

  - name: mi-mariadb
    chart: mariadb
    host: swarm-host-a
    values: mi-mariadb/values.yaml
    tag: db

  - name: mi-whoami-b
    chart: whoami
    host: swarm-host-b
    values: mi-whoami-b/values.yaml
    tag: apps

Agregar el rol de shipyard a tu playbook de ansible

En tu playbook de ansible (normalmente site.yml), agrega lo siguiente:

- name: Configuración del host de Docker Shipyard
  hosts: mis-hosts-swarm # o un grupo de hosts - se espera que sean gerentes de docker swarm con autenticación configurada para la descarga de imágenes de docker
  tags:
    - shipyard # o cualquier otra etiqueta que desees usar para ejecutar este playbook
  roles:
    - role: linkorb.shipyard # el rol de ansible galaxy
      vars:
        shipyard_tag: apps

Esto buscará el archivo shipyard.yml en la raíz del directorio del playbook. Desplegará en los hosts gestionados las pilas etiquetadas como apps listadas allí.

Crear un Shipyard Chart

Estructura de directorio de un Shipyard Chart:

mi-shipyard-chart/
  Chart.yaml # los metadatos del chart
  LICENSE # la licencia para este chart
  README.md # el documento de lectura para este chart
  values.yaml # los valores predeterminados para este chart
  templates/ # las plantillas jinja2 para este chart
    docker-compose.yml # el archivo de plantilla de docker compose para este chart
    example.conf # una plantilla de archivo de configuración de ejemplo para este chart
    env.example # otra plantilla de archivo de configuración de ejemplo para este chart
    un-directorio/ # un directorio que se copiará en el host de destino

El rol de Shipyard copiará todos los archivos y carpetas en el directorio templates/ en el host de destino y luego renderizará los archivos utilizando los valores del Chart y de la Stack (consulta la siguiente sección para más información sobre esto).

values.yaml / values.sops.yaml y valores predeterminados del chart

Cada pila (una instancia de un chart) toma un archivo de valores que contiene los valores para esa instancia del chart. Los valores se cargan desde {{shipyard_stacks_path}}/{{stack_name}}/values.yaml. Si se detecta un values.sops.yaml, también se carga y descifra automáticamente (basado en el archivo .sops.yaml en la raíz de tu repositorio).

Cada chart proporciona un archivo values.yaml predeterminado también. Cualquier valor a nivel de pila que siga sin definirse se establecerá en el valor predeterminado del chart.

El orden de carga (y de precedencia de sobrescritura) es:

1. los valores predeterminados del chart
2. el values.yaml de la pila
3. el values.sops.yaml de la pila

Valores especiales

• primed_volumes: una lista de objetos de información de volumen de docker que se crearán para la pila.

  Este valor solo es significativo cuando un Chart lo admite.

  Cada objeto de información del volumen tiene las siguientes propiedades:

  • name: El nombre del volumen.
  • target: El lugar en el contenedor donde montar el volumen.
  • path: La ruta, bajo la ruta de la pila en el host remoto, para copiar recursivamente en el volumen.

  Por ejemplo, un volumen que contiene scripts de inicialización de base de datos de MariaDB se puede crear así:

  # mi-pila/values.yaml
  primed_volumes:
  - name: mariadb_init_data
    target: /docker-entrypoint-initdb.d # aquí es donde el contenedor de MariaDB busca datos de inicialización
    path: docker-entrypoint-initdb.d # este directorio está presente en las plantillas del Chart
  

Estructura de directorio en el host de destino

En los hosts de destino (gerentes de Docker Swarm), el rol creará la siguiente estructura de directorio:

/opt/shipyard/stacks/
  mi-shipyard-stack/
    docker-compose.yml # el archivo de docker compose renderizado
    example.conf # el archivo de configuración de ejemplo renderizado
    # ... etc

Desplegando las pilas en Docker Swarm

Después de que las plantillas se hayan renderizado y escrito en el host, el rol ejecutará docker stack deploy en el host de destino para desplegar la pila de Docker Swarm.

Ejemplo de Shipyard Chart

Consulta el directorio example/shipyard/charts/whoami para un ejemplo de Shipyard Chart.

Contribuciones

Damos la bienvenida a las contribuciones para mejorar aún más este repositorio. Ya sea para arreglar un error, agregar una función o mejorar la documentación, tu ayuda es muy apreciada. Para comenzar, haz un fork de este repositorio y luego clona tu fork.

Asegúrate de familiarizarte con las Guías de Contribución de LinkORB para nuestros estándares con respecto a commits, ramas y solicitudes de extracción, así como con nuestro código de conducta antes de enviar cualquier cambio.

Si no puedes implementar los cambios que te gustaría tú mismo, no dudes en abrir un nuevo informe de problema para que nosotros o otros puedan encargarse de ello.

Presentado por el equipo de ingeniería de LinkORB

Consulta nuestros otros proyectos en linkorb.com/engineering. ¡Por cierto, estamos contratando!