hashicorp / consul-template

Este proyecto proporciona una manera conveniente de poblar los valores de Consulinto el sistema de archivos utilizando el demonio consul-template.

El demonio consul-template consulta un Consul o Vaultcluster y actualiza cualquier número de plantillas especificadas en el sistema de archivos. Como ventaja añadida, puede ejecutar opcionalmente comandos arbitrarios cuando el proceso de actualización finaliza. Por favor, vea la carpeta de ejemplos para algunos escenarios en los que esta funcionalidad podría ser útil.

La documentación en este README corresponde a la rama maestra de Consul Template. Puede contener características inéditas o APIs diferentes a las de la versión más reciente.

Por favor, vea la etiqueta Git que corresponde a su versión de Consul Template para la documentación adecuada.

Tabla de contenidos

• Soporte comunitario
• Instalación
• Ejemplo rápido
• Guías de aprendizaje
• Configuración
  • Bandas de línea de comandos
  • Archivo de configuración
• Recargar configuración y plantillas
• Lenguaje de plantillas
  • Funciones de la API
  • Scratch
  • Funciones de ayuda
  • Funciones matemáticas
• Observabilidad
  • Registro
• Modos
  • Modo único
  • De-Modo Duplicación
  • Modo Exec
• Plugins
• Cauciones
  • Uso de la Imagen del Docker
  • Puntos en Servicio Nombres
  • Terminación en caso de error
  • Comandos
    • Entorno
    • Múltiples comandos
  • Multifase de ejecución
• Correr y ciclo de vida del proceso
• Depuración
• FAQ
• Contribuir

Asistencia de la comunidad

Si tiene preguntas sobre el funcionamiento de consul-template, sus capacidades ocualquier otra cosa que no sea una solicitud de error o característica (utilice el rastreador de problemas de github para ello), consulte nuestros recursos de soporte de la comunidad.

Portal de la comunidad: https://discuss.hashicorp.com/c/consul

Otros recursos: https://www.consul.io/community.html

Además, para los temas y pull requests, usaremos las reacciones 👍 como un sistema de votación aproximado para ayudar a medir las prioridades de la comunidad. Así que, por favor, añade 👍 a cualquier tema o pull request en el que te gustaría que se trabajara. Gracias.

Instalación

1. Descargue una versión precompilada y liberada desde la página de liberaciones de Consul Template.

2. Extraiga el binario usando unzip o tar.

3. Mueva el binario a $PATH.

Para compilar desde el código fuente, por favor vea las instrucciones en la sección de contribución.

Ejemplo rápido

Este breve ejemplo asume que Consul está instalado localmente.

Para más ejemplos y casos de uso, por favor vea la carpeta de ejemplos en este repositorio.

Guías de aprendizaje

Además de estos ejemplos, HashiCorp ha publicado guías y documentación oficial para ayudar a recorrer algunos casos de uso comunes para ConsulTemplate.

• Consul KV
• Consul Catalog
• Plantillas de Agente de Bóveda
• Secretos de Bóveda

Configuración

La documentación de configuración se ha movido a docs/configuración.md.

Recargar la configuración y las plantillas

Aunque hay múltiples formas de ejecutar Consul Template, el patrón más común es ejecutar Consul Template como un servicio del sistema. Cuando Consul Template se inicia por primera vez, lee los archivos de configuración y las plantillas del disco y los carga en la memoria. A partir de ese momento, los cambios en los archivos del disco no se propagan al proceso en ejecución sin una recarga.

La razón de este comportamiento es simple y se alinea con otras herramientas como haproxy.Un usuario puede querer realizar comprobaciones de validación previas al vuelo en la configuración o las plantillas antes de cargarlas en el proceso. Además, un usuario puede querer actualizar la configuración y las plantillas simultáneamente. Hacer que Consul Template observe y recargue automáticamente esos archivos cuando se producen cambios es peligroso desde el punto de vista operativo y va en contra de algunos de los paradigmas de la infraestructura moderna. En su lugar, Consul Template espera la llamada al sistema SIGHUP para activar una recarga de la configuración. Si actualiza la configuración o las plantillas, simplemente envíe HUP al proceso de Consul Template en ejecución y Consul Template recargará todas las configuraciones y plantillas desde el disco.

Lenguaje de plantillas

La documentación del Lenguaje de plantillas se ha movido a todocs/templating-language.md.

Advertencias

Uso de la imagen Docker

La imagen Docker de Alpine está configurada para soportar un volumen externo al que renderizar las plantillas compartidas. Si se monta tendrá que asegurarse de que el usuarioconsul-template en la imagen docker tiene permisos de escritura en eldirectorio. Además, si construyes tu propia imagen usando esto, necesitas asegurarte de que tienes los permisos correctos.

El usuario consul-template en docker tiene un UID de 100 y un GID de 1000.

Esto afecta a los directorios de la imagen /consul-template/config, que se utiliza para añadir la configuración cuando se utiliza como imagen principal, y /consul-template/data, que se exporta como un VOLUMEN como una ubicación para obtener resultados compartidos.

Antes, la imagen se ejecutaba inicialmente como root para asegurarse de que los permisos lo permitían. Pero esto iba en contra de las mejores prácticas y políticas de seguridad de Docker.

Si usted construye su propia imagen basada en la nuestra puede anular estos valores con--build-arg parámetros.

Puntos en los nombres de servicio

El uso de puntos . en los nombres de servicio entrará en conflicto con el uso de puntos para TAGdelineación en la plantilla. Los puntos ya interfieren con el uso de DNS para los nombres de servicio, por lo que recomendamos evitar los puntos siempre que sea posible.

Terminación en caso de error

Por defecto, Consul Template es altamente tolerante a fallos. Si Consul es inalcanzable o una plantilla cambia, Consul Template continuará felizmente ejecutándose. La única excepción a esta regla es si el opcional command sale distinto de cero. En este caso, Consul Template también saldrá distinto de cero. La razón de esta decisión es que el usuario puede configurar fácilmente algo como Upstart o Dios para gestionar ConsulTemplate como un servicio.

Si desea que Consul Template continúe observando los cambios, incluso si el argumento opcional del comando falla, puede añadir || true a su comando. Tenga en cuenta que || es un «shell-ism», no una función incorporada. También necesitarás ejecutar tu comando bajo un shell:

$ consul-template \ -template "in.ctmpl:out.file:/bin/bash -c 'service nginx restart || true'"

En este ejemplo, incluso si el comando de reinicio de Nginx devuelve un valor distinto de cero, la función general devolverá un código de salida OK; Consul Template continuará ejecutándose como un servicio. Además, si tienes una lógica compleja para reiniciar tu servicio, puedes elegir de forma inteligente cuándo quieres que Consul Template salga y cuándo quieres que continúe buscando cambios. Para este tipo de secuencias de comandos complejas, recomendamos utilizar una secuencia de comandos sh o bash personalizada en lugar de poner la lógica directamente en el comando consul-template o en el archivo de configuración.

Comandos

Entorno

El entorno de los procesos actuales se utiliza cuando se ejecutan comandos con las siguientes variables de entorno adicionales:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Estas variables de entorno se exportan con sus valores actuales cuando se ejecuta elcomando. Otras herramientas de Consul leen estas variables de entorno, proporcionando una integración fluida con otras herramientas de Consul (como consul maint oconsul lock). Además, la exposición de estas variables de entorno ofrece a los usuarios avanzados la posibilidad de personalizar aún más su secuencia de comandos.

Comandos múltiples

El comando configurado para ejecutarse en la representación de plantillas debe ser un solo comando. Es decir, no se pueden unir varios comandos con &&, ;, |, etc.Esta es una restricción de cómo se ejecutan. Sin embargo, se puede hacer esto combinando los múltiples comandos en un comando de shell explícito usando sh -c. Esto probablemente se explica mejor con un ejemplo.

Supongamos que tiene un par de scripts que necesita ejecutar cuando una plantilla se renderiza, /opt/foo y /opt/bar, y sólo quiere que /opt/bar se ejecute si /opt/foo tiene éxito. Puedes hacer eso con el comando…

command = "sh -c '/opt/foo && /opt/bar'"

Como este es un comando de shell completo puedes incluso usar condicionales. Así se consigue lo mismo.

command = "sh -c 'if /opt/foo; then /opt/bar ; fi'"

Usando este método puedes ejecutar tantos comandos del shell como necesites con la lógica que necesites. Aunque se sugiere que si se hace demasiado largo puede querer envolverlo en un script de shell, desplegarlo y ejecutarlo.

Ejecución multifase

Consul Template hace una evaluación de n pases de plantillas, acumulando dependencias en cada pase. Esto es necesario debido a las dependencias anidadas, como:

{{ range services }}{{ range service .Name }} {{ .Address }}{{ end }}{{ end }}

Durante la primera pasada, Consul Template no conoce ninguno de los servicios enConsul, por lo que tiene que realizar una consulta. Cuando se devuelven esos resultados, el bucle interno se evalúa con ese resultado, creando potencialmente más consultas y relojes.

Debido a esta implementación, las funciones de plantilla necesitan un valor por defecto que es un parámetro aceptable para una función range (o similar), pero no ejecuta realmente el bucle interno (lo que causaría un pánico). Es importante mencionar esto porque las plantillas complejas deben tener en cuenta el caso «vacío». Por ejemplo, lo siguiente no funcionará:

{{ with index (service "foo") 0 }}# ...{{ end }}

Esto generará un error como:

<index $services 0>: error calling index: index out of range: 0

Esto se debe a que, durante la primera evaluación de la plantilla, la clave service está devolviendo una porción vacía. Puede tener en cuenta esto en su plantilla como:

{{ with service "foo" }}{{ with index . 0 }}{{ .Node }}{{ end }}{{ end }}

Esto todavía añadirá la dependencia a la lista de relojes, pero no evaluará el inner-if, evitando el error de fuera de índice.

FAQ

Por qué es esto diferente de confd?
A: La respuesta es simple: Service Discovery como ciudadano de primera clase. También se le anima a leer este Pull Request en el proyecto para obtener más información de fondo. Creemos que confd es un gran proyecto, pero Consul Template llena un vacío que falta. Además, Consul Template tiene una integración de primera clase con Vault, lo que facilita la incorporación de material secreto como credenciales de bases de datos o tokens de API en los archivos de configuración.

P: ¿En qué se diferencia de Puppet/Chef/Ansible/Salt?
A: Las herramientas de gestión de la configuración están diseñadas para ser utilizadas al unísono con Consul Template. En lugar de renderizar un archivo de configuración obsoleto, utilice su software de gestión de configuración para renderizar una plantilla dinámica que será poblada por Consul.

Contribuyendo

Para construir e instalar Consul-Template localmente, necesitará instalar Go.

Clonar el repositorio:

$ git clone https://github.com/hashicorp/consul-template.git

Para compilar el binario consul-template para su máquina local:

$ make dev

Esto compilará el binario consul-template en bin/consul-template así como su $GOPATH y ejecutará el conjunto de pruebas.

Si desea compilar un binario específico, establezca XC_OS y XC_ARCH o ejecute lo siguiente para generar todos los binarios:

$ make build

Si desea ejecutar las pruebas, primero instale consul y vault localmente, entonces:

$ make test

O para ejecutar una prueba específica en la suite:

go test ./... -run SomeTestFunction_name