hashicorp / consul-template

Este projeto fornece uma maneira conveniente de preencher valores do Consul no sistema de arquivos usando o daemon.consul-template daemon.

O daemon consul-template consulta um Consul ou Vaultcluster e atualiza qualquer número de templates especificados no sistema de arquivos. Como bônus adicional, ele pode opcionalmente executar comandos arbitrários quando o processcompletes de atualização estiver completo. Veja a pasta de exemplos para alguns cenários onde esta funcionalidade pode ser útil.

A documentação neste README corresponde ao ramo mestre do Consul Template. Ele pode conter funcionalidades não liberadas ou APIs diferentes da versão mais recente.

Por favor veja a tag Git que corresponde à sua versão do Consul Template para a documentação apropriada.

Tabela de Conteúdos

• Suporte Comunitário
• Instalação
• Exemplo Rápido
• Guia de Aprendizagem
• Configuração
  • Bandeiras de Linha de Comando
  • Arquivo de Configuração
• Configuração Recarregar e Modelos
• Linguagem de Modelos
  • FunçõesAPI
  • Scratch

  >

  • Funções Helper

  >

  • Funções Matemáticas

  >

  >

• Abservabilidade
  • Logging

>

• Modos
  >
  • Modo Once

  >

  • De-Modo Duplicação
  • Exec Mode
• Plugins
• Caveats
  • Docker Image Use
  • Dots in Service Nomes
  • Terminação do Erro
  • Comandos
    • Ambiente
    • Comandos Múltiplos
  • Multi-Execução de fases
• Ciclo de vida de execução e processo
• Debugging
• FAQ
• Contribuir

Apoio à comunidade

Se você tiver dúvidas sobre como funciona o consul-template, suas capacidades ou qualquer outra coisa além de um bug ou pedido de recurso (use o github’s issue tracker forthose), por favor veja nossos recursos de suporte comunitário.

Portal da comunidade: https://discuss.hashicorp.com/c/consul

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

Adicionalmente, para problemas e pedidos de puxar, usaremos o 👍 como um sistema de votação grosseiro para ajudar a avaliar as prioridades da comunidade. Então, por favor adicione 👍to qualquer problema ou pedido de puxar que você gostaria de ver trabalhado. Obrigado.

Instalação

1. Baixar uma versão pré-compilada e lançada da página de lançamentos do Consul Template.

2. Extrair o binário usando unzip ou tar.

3. Mover o binário para $PATH.

Para compilar a partir do código fonte, por favor veja as instruções na seção de contribuição.

Exemplo rápido

Este pequeno exemplo assume que o Consul está instalado localmente.

Para mais exemplos e casos de uso, por favor veja a pasta de exemplos neste repositório.

Guia de Aprendizagem

Além destes exemplos, a HashiCorp publicou guias e documentação oficial para ajudar a percorrer alguns casos de uso comum para o ConsulTemplate.

• Consul KV
• Catálogo do ConsulTemplate
• Templates de Agente de Salvaguarda
• Segredos de Salvaguarda

Configuração

Documentação de configuração foi movida para docs/configuração.md.

Reload Configuration and Templates

Embora existam múltiplas formas de executar o Consul Template, o padrão mais comum é executar o Consul Template como um serviço do sistema. Quando o Consul Template inicia, ele lê quaisquer arquivos de configuração e templates do disco e os carrega intomemory. A partir daí, alterações nos arquivos no disco não se propagam para o processo em execução sem uma recarga.

A razão para este comportamento é simples e se alinha com outras ferramentas como haproxy.Um usuário pode querer executar verificações de validação pré-voo na configuração ou modelos antes de carregá-los no processo. Além disso, um usuário pode querer a configuração do touchpdate e dos templates simultaneamente. Ter o Consul Template Automaticamente observar e recarregar esses arquivos em mudanças é operacionalmente perigoso e contra alguns dos paradigmas da infra-estrutura moderna. Em vez disso, o Consul Template ouve a chamada do syscall SIGHUP para acionar uma configuração de recarga. Se você atualizar a configuração ou templates, simplesmente envie HUP para o processo Consul Template e o Consul Template irá recarregar todas as configurações e templates a partir do disco.

Linguagem de Template

A documentação da Linguagem de Template foi movida para todocs/templating-language.md.

Caveats

Docker Image Use

A imagem do Docker Alpine está configurada para suportar um volume externo para renderizar templates compartilhados. Se montado você precisará ter certeza de que o usuário da imagem do Docker tem permissões de escrita no diretório. Também se você construir sua própria imagem usando essas permissões você precisa ter certeza que você tem as permissões corretas.

O usuário do consul-template na docker tem um UID de 100 e um GID de 1000.

Isso afeta os diretórios de imagens /consul-template/config, usados para adicionar configuração quando se usa como imagem pai, e /consul-template/dados,exportados como um VOLUME como um local para renderizar resultados compartilhados.

Anteriormente a imagem funcionava inicialmente como raiz para garantir as permissões permitidas. Mas isso correu contra as melhores práticas e políticas de segurança da docker.

Se você construir sua própria imagem com base na nossa, você pode sobrescrever esses valores com--build-arg parâmetros.

Pontos nos Nomes dos Serviços

Usar pontos . nos nomes dos serviços irá conflitar com o uso de pontos para TAGdelineation no modelo. Os pontos já interferem com o uso de nomes de serviços DNSfor, por isso recomendamos evitar pontos sempre que possível.

Término no erro

Por padrão o Consultemplate é altamente tolerante a falhas. Se o Consul Template for inalcançável ou se o template for alterado, o Consul Template continuará a funcionar com prazer. A única exceção a esta regra é se o opcional command sair não-zero. Neste caso, o Consulado Modelo também sairá não-zero. O motivo desta decisão é que o usuário pode facilmente configurar algo como Upstart ou Deus para gerenciar o ConsulTemplate como um serviço.

Se você quiser que o Consul Template continue observando as mudanças, mesmo que o argumento de comando opcional falhe, você pode anexar || true ao seu comando. Note que || é um “shell-ism”, não uma função embutida. Você também precisará executar seu comando sob uma shell:

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

Neste exemplo, mesmo que o comando Nginx restart retorne não-zero, a função de sobrealimentação ainda retornará um código de saída OK; o Consul Template continuará a ser executado como um serviço. Adicionalmente, se você tiver uma lógica complexa para reiniciar o seu serviço, você pode escolher inteligentemente quando você quer que o Consul Template saia e quando você quer que ele continue a observar as mudanças. Para estes tipos de scripts complexos, recomendamos usar um sh ou bash script personalizado em vez de colocar a lógica diretamente no arquivo de comando ou configuração consul-template.

Comandos

Ambiente

O ambiente atual de processos é usado ao executar comandos com as seguintes variáveis de ambiente adicionais:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Estas variáveis de ambiente são exportadas com seus valores atuais quando o comando é executado. Outras ferramentas Consul lê estas variáveis de ambiente, proporcionando uma integração suave com outras ferramentas Consul (como consul maint ou consul lock). Adicionalmente, a exposição destas variáveis de ambiente dá aos powerusers a capacidade de personalizar ainda mais o seu script de comando.

Múltiplos Comandos

O comando configurado para executar na renderização de templates deve ser um comando singlecommand. Isto é, você não pode juntar comandos múltiplos com &&, ;, |, etc. Esta é uma restrição de como eles são executados. No entanto você é capaz de dothis combinando os comandos múltiplos em um comando shell explícito usando sh -c. Isto é provavelmente melhor explicado pelo exemplo.

Dizer que você tem alguns scripts que precisa executar quando um template é renderizado,/opt/foo e /opt/bar, e você só quer que /opt/bar seja executado se /opt/foo for bem sucedido. Você pode fazer isso com o comando…

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

Como este é um comando shell completo você pode até usar condicionadores. Assim consegue o mesmo.

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

Utilizando este método você pode executar tantos comandos shell quantos você precisar com qualquer que seja a lógica que você precise. Apesar de ser sugerido que se ficar muito longo você pode querer embrulhá-lo em um script shell, deploy e executar isso.

Execução Multi-phase

Consul Template faz uma avaliação n-pass dos templates, acumulando dependências em cada passagem. Isto é necessário devido às dependências aninhadas, tais como:

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

No primeiro passe, o Consul Template não conhece nenhum dos serviços do Consul, por isso tem que realizar uma consulta. Quando esses resultados são retornados, o loopinner é então avaliado com esse resultado, potencialmente criando mais consultas e relógios.

Por causa dessa implementação, as funções do modelo precisam de um valor padrão que é um parâmetro aceitável para uma função range (ou similar), mas não executa notavelmente o loop interno (o que causaria o pânico). Isto é importante mencionar porque os templates complexos devem ser responsáveis pelo caso “vazio”. Forexample, o seguinte não funcionará:

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

Isto levantará um erro como:

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

Isso porque, durante a primeira avaliação do template, a tecla service está retornando uma fatia vazia. Você pode contabilizar isso em seu template como:

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

Isso ainda adicionará a dependência à lista de relógios, mas notará a avaliação do erro interno-if, evitando o erro fora do índice.

FAQ

Q: Como isso é diferente do confd?
A: A resposta é simples: O Service Discovery como um cidadão de primeira classe. Você também é encorajado a ler este Pull Request no projeto para mais informações de fundo. Achamos que o confd é um grande projeto, mas o Consul Template preenche uma lacuna que falta. Além disso, o Consul Template tem integração de primeira classe com o Vault, facilitando a incorporação de material secreto como credenciais de banco de dados ou tokens API em arquivos de configuração.

Q: Como isso é diferente do Puppet/Chef/Ansible/Salt?
A: Ferramentas de gerenciamento de configuração são projetadas para serem usadas em uníssono com o Consul Template. Ao invés de renderizar um arquivo de configuração obsoleto, use seu software de gerenciamento de configuração para renderizar um template dinâmico que será preenchido pelo Consul.

Contribuindo

Para construir e instalar o Consul-Template localmente, você precisará instalar o Go.

Clonar o repositório:

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

Para compilar o binário consul-template para sua máquina local:

$ make dev

Isto compilará o binário consul-template em bin/consul-template assim como seu $GOPATH e executará a suíte de testes.

Se você quiser compilar um binário específico, defina XC_OS e XC_ARCH ou execute o seguinte para gerar todos os binários:

$ make build

Se você quiser executar os testes, primeiro instale o cônsul e o cofre localmente, depois:

$ make test

Or para executar um teste específico no conjunto:

go test ./... -run SomeTestFunction_name