Docker Swarm Service

18 min

Resumo

Gerenciar serviços de um swarm docker por meio de um node manager.

Requisitos

A ferramenta Docker API na versão 1.24 ou maior.

Parâmetros

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
api_version aliases: docker_api_version	string	- "auto" (default)	A versão da Docker API em execução no Docker Host. O padrão é a versão mais recente da API suportada pelo Docker SDK e o docker daemon. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_API_VERSION será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
args	list / elements=string		Liste os argumentos a serem passados para o contêiner. Corresponde ao parâmetro ARG da criação do serviço docker.
ca_cert / aliases: tls_ca_cert, cacert_path	path		Use um certificado CA ao executar a verificação do servidor, fornecendo o caminho para um arquivo de certificado CA. Se o valor não for especificado na tarefa e a variável de ambiente DOCKER_CERT_PATH estiver definida, o arquivo ca.pem do diretório especificado na variável de ambiente DOCKER_CERT_PATH será usado.
client_cert aliases: tls_client_cert, cert_path	path		Caminho para o arquivo de certificado TLS do cliente. Se o valor não for especificado na tarefa e a variável de ambiente DOCKER_CERT_PATH for definida, o arquivo cert.pem do diretório especificado na variável de ambiente DOCKER_CERT_PATH será usado.
client_key aliases: tls_client_key, key_path	path		Caminho para o arquivo de chave TLS do cliente. Se o valor não for especificado na tarefa e a variável de ambiente DOCKER_CERT_PATH for definida, o arquivo key.pem do diretório especificado na variável de ambiente DOCKER_CERT_PATH será usado.
command	raw		Comando a ser executado quando o contêiner é iniciado. Um comando pode ser uma string, uma lista ou uma lista de strings. Corresponde ao parâmetro COMMAND do serviço docker create.
configs (Possíveis elementos)	list / elements=dictionary		Lista de dicionários que descrevem o serviço configs. Corresponde à opção --config do docker service create.
container_labels	dictionary		Dicionário de pares de valores-chave. Corresponde à opção --container-label do docker service create.
debug	boolean	Escolhas: - false (default) - true	Modo de depuração
dns l	ist / elements=string		Lista de servidores DNS personalizados. Corresponde à opção --dns de criação do docker service create.
dns_options	list / elements=string		Lista de opções de DNS personalizadas. Corresponde à opção --dns-option do docker service create.
dns_search	list / elements=string		Lista de domínios de pesquisa DNS personalizados. Corresponde à opção --dns-search do docker service create.
docker_host aliases: docker_url	string	- "unix://var/run/docker.sock" (default)	O URL ou o caminho do soquete Unix usado para se conectar à API Docker. Para se conectar a um host remoto, forneça a string de conexão TCP. Por exemplo, tcp: //192.0.2.23: 2376. Se TLS for usado para criptografar a conexão, o módulo substituirá automaticamente tcp no URL de conexão por https. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_HOST será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
endpoint_mode	string	Escolhas: - vip - dnsrr	Modo de terminal de serviço. Corresponde à opção --endpoint-mode do docker service create.
env	raw		Lista ou dicionário das variáveis de ambiente do serviço. Se for passada uma lista, cada item deve estar no formato de KEY = VALUE. Se for passado um dicionário, os valores que podem ser analisados como números, booleanos ou outros tipos pelo analisador YAML devem ser citados ( por exemplo, "true") para evitar perda de dados. Corresponde à opção --env do docker service create.
env_files	list / elements=path		Lista de caminhos para arquivos, presentes no destino, contendo variáveis de ambiente FOO = BAR. A ordem da lista é significativa para determinar o valor atribuído a uma variável que aparece mais de uma vez. Se a variável também estiver presente em env, então o valor de env irá substituir.
force_update	boolean	Escolhas: - false (default) - true	Força a atualização mesmo que nenhuma mudança exija. Corresponde à opção --force de atualização do docker service create.
groups	list / elements=string		Lista de nomes de grupos adicionais e / ou IDs com os quais o processo do contêiner será executado. Corresponde à opção --group da atualização do docker service create.
healthcheck (Possíveis elementos)	dictionary		Configure uma verificação que é executada para determinar se os contêineres para este serviço estão "íntegros" ou não. Consulte a documentação da instrução HEALTHCHECK Dockerfile para obter detalhes sobre como healthchecks work.interval, timeout e start_period são especificados como durações. Eles aceitam a duração como uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, me h.
hostname	string		Nome do host do contêiner. Corresponde à opção --hostname do docker service create.
hosts	dictionary		Dict of host-to-IP mappings, onde cada host name é uma chave no dicionário. Cada nome de host será adicionado ao arquivo / etc / hosts do contêiner. Corresponde à opção --host do docker service create.
image	string		Caminho e tag da imagem de serviço. Corresponde ao parâmetro IMAGE da criação do docker service create.
init	boolean	Escolhas: - false - true	Use um init dentro de cada container de serviço para encaminhar sinais e colher processos. Corresponde à opção --init do docker service create.
labels	dictionary		Dicionário de pares de valores-chave. Corresponde à opção --label do docker service create.
limits (Possíveis elementos)	dictionary		Configura limites de recursos de serviço.
logging (Possíveis elementos)	dictionary		Configuração de registro para o serviço.
mode	string		Modo de replicação de serviço. O serviço será removido e recriado quando alterado. Corresponde à opção --mode do docker service create.
mounts (Possíveis elementos)	list / elements=dictionary		Lista de dicionários que descrevem o serviço mounts. Corresponde à opção --mount do docker service create.
name / required	string		Nome do serviço. Corresponde à opção --name do docker service create.
networks	list / elements=raw		Lista de nomes ou dicionários de redes de serviço. Quando os dicionários são passados, as subopções válidas são name, que é obrigatório, e aliases e options. Corresponde à opção --network do docker service create.
placement (Possíveis elementos)	dictionary		Configura preferências e restrições de colocação de serviço.
publish (Possíveis elementos)	list / elements=dictionary		Lista de dicionários que descrevem as portas publicadas do serviço. Corresponde à opção --publish do docker service create.
read_only	boolean	Escolhas: - false - true	Monte o sistema de arquivos raiz dos contêineres como somente leitura. Corresponde à opção --read-only do docker service create.
replicas	integer	- -1 (default)	Número de containers instanciados no serviço. Válido apenas se o modo for replicado. Se definido como -1 e o serviço não estiver presente, as réplicas de serviço serão definidas como 1. Se definido como -1 e o serviço estiver presente, as réplicas de serviço não serão alteradas. Corresponde à opção --replicas do docker service create.
reservations (Possíveis elementos)	dictionary		Configura reservas de recursos de serviço.
resolve_image	boolean	Escolhas: - false (default) - true	Se o resumo da imagem atual deve ser resolvido do registro e atualizado se alterado.
restart_config (Possíveis elementos)	dictionary		Configura se e como reiniciar os contêineres quando eles saem.
rollback_config (Possíveis elementos)	dictionary		Configura como o serviço deve ser revertido em caso de falha na atualização.
secrets (Possíveis elementos)	list / elements=dictionary		Lista de dicionários que descrevem os segredos do serviço. Corresponde à opção --secret do docker service create.
ssl_version	string		Forneça um número de versão SSL válido. Valor padrão determinado pelo módulo ssl.py. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_SSL_VERSION será usado.
state	string	Escolhas: - present (default) - absent	absent - Um serviço que corresponde ao nome especificado será removido e terá suas tarefas interrompidas. present - Afirma a existência de um serviço que corresponde ao nome e aos parâmetros de configuração fornecidos. Os parâmetros de configuração não especificados serão definidos para os padrões do docker.
stop_grace_period	string		Tempo de espera antes de forçar a eliminação de um contêiner. Aceita uma duração como uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --stop-grace- do docker service create.
stop_signal	string		Substituir o sinal padrão usado para parar o container. Corresponde à opção --stop-signal do docker service create.
timeout	integer	- 60 (default)	O tempo máximo em segundos para aguardar uma resposta da API. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_TIMEOUT será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
tls	boolean	Escolhas: - false (default) - true	Proteja a conexão com a API usando TLS sem verificar a autenticidade do servidor host Docker. Observe que, se validate_certs também for definido como yes, ele terá precedência. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_TLS será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
tls_hostname	string	- "localhost" (default)	Ao verificar a autenticidade do servidor Docker Host, forneça o nome esperado do servidor. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_TLS_HOSTNAME será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
tty	boolean	Escolhas: - false - true	Aloque um pseudo-TTY. Corresponde à opção --tty do docker service create.
update_config (Possíveis elementos)	dictionary		Configura como o serviço deve ser atualizado. Útil para configurar atualizações contínuas.
user	string		Define o nome de usuário ou UID usado para o comando especificado. O padrão foi removido para que o usuário definido na imagem seja usado se nenhum usuário for especificado aqui. Corresponde à opção --user do docker service create.
validate_certs	boolean	Escolhas: - false (default) - true	Proteja a conexão com a API usando TLS e verificando a autenticidade do servidor host Docker. Se o valor não for especificado na tarefa, o valor da variável de ambiente DOCKER_TLS_VERIFY será usado. Se a variável de ambiente não for definida, o valor padrão será usado.
working_dir	string		Caminho para o diretório de trabalho. Corresponde à opção --workdir do docker service create.

Subcampos da opção configs

Parâmetro	Tipo	Comentários
config_id	string	ID de configuração.
config_name - required	string	O nome do config conforme definido na sua criação.
filename	string	Nome do arquivo que contém a configuração. O padrão é config_name se não for especificado.
gid	string	GID do grupo do arquivo de configuração.
mode	integer	Modo de acesso ao arquivo dentro do contêiner. Deve ser um número octal (como 0644 ou 0444).
uid	string	UID do proprietário do arquivo de configuração.

Subcampos da opção healthcheck

Parâmetro	Tipo	Comentários
interval	string	Tempo entre a execução da verificação.
retries	integer	Falhas consecutivas necessárias para relatar desintegridade. Aceita valores inteiros.
start_period	string	Período inicial para o contêiner inicializar antes de iniciar a contagem regressiva de tentativas de integridade.
test	raw	Comando a ser executado para verificar a integridade. Deve ser uma string ou uma lista. Se for uma lista, o primeiro item deve ser NONE, CMD ou CMD-SHELL.
timeout	string	Tempo máximo para permitir a execução de uma verificação.

Subcampos da opção limits

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
cpus	float		Limite de CPU de serviço. 0 é igual a nenhum limite. Corresponde à opção --limit-cpu de criação do serviço docker.
memory	string		Limite de memória de serviço no formato <número> [<unidade>]. O número é um número inteiro positivo. A unidade pode ser B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte) ou P (pebibyte) .0 é igual a nenhum limite. O padrão da unidade é bytes. Corresponde a a opção --limit-memory de criação do serviço docker.

Subcampos da opção logging

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
driver	string		Configure o driver de registro para um serviço. Corresponde à opção --log-driver de criação do serviço docker.
options	dictionary		Opções para driver de registro de serviço. Corresponde à opção --log-opt de criação d serviço docker.

Subcampos da opção mounts

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
driver_config options: name teste	dictionary string dictionary		Configuração do driver de volume. Só pode ser usado quando o tipo é o volume. Nome do plugin de driver de volume a ser usado para o volume. Opções como pares de valores-chave para passar ao driver para este volume.
labels	dictionary		Rótulos de volume a serem aplicados.
no_copy	boolean	Escolhas: - false - true	Desabilite a cópia de dados de um contêiner quando um volume é criado. Só pode ser usado quando o tipo é volume.
propagation	string	Escolhas: - shared - slave - private - rshared - rslave - rprivate	O modo de propagação a ser usado. Só pode ser usado quando o tipo é vinculado.
readonly	boolean	Escolhas: - false - true	Se a montagem deve ser somente leitura.
source	string		Fonte de montagem (por exemplo, um nome de volume ou um caminho de host). Deve ser especificado se o tipo não for tmpfs.
target - required	string		Caminho do contêiner.
tmpfs_mode	integer		O modo de arquivo do tmpfs em octal. Só pode ser usado quando o tipo é tmpfs.
tmpfs_size	string		Tamanho da montagem tmpfs no formato <número> [<unidade>]. O número é um número inteiro positivo. A unidade pode ser B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte) ou P (pebibyte). Só pode ser usado quando o tipo é tmpfs.
type	string	Escolhas: - bind (default) - volume - tmpfs - npipe	O tipo de montagem. Observe que o npipe só é compatível com o Docker para Windows.

Subcampos da opção placement

Parâmetro	Tipo	Comentários
constraints	list / elements=string	Lista de restrições de serviço. Corresponde à opção --constraint de criação de serviço docker.
preferences	list / elements=dictionary	Lista das preferências de posicionamento como pares de valores-chave. Corresponde à opção --placement-pref da criação do serviço docker.
replicas_max_per_node	integer	Número máximo de tarefas por nó. Corresponde à opção --replicas_max_per_node da criação do serviço docker.

Subcampos da opção publish

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
mode	string	Escolhas: - ingress - host	Qual modo de publicação usar.
protocol	string	Escolhas: - tcp (default) - udp	Qual protocolo usar.
published_port - required	integer		A porta a ser disponibilizada externamente.
target_port - required	integer		A porta dentro do contêiner à ser exposta.

Subcampos da opção reservations

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
cpus	float		Reserva de CPU de serviço. 0 equivale a nenhuma reserva. Corresponde à opção --reserve-cpu do docker service create.
memory	string		Reserva de memória de serviço no formato <número> [<unidade>]. O número é um número inteiro positivo. A unidade pode ser B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte) ou P (pebibyte) .0 equivale a nenhuma reserva. O padrão da unidade é bytes. Corresponde à opção --reserve-memory do docker service create.

Subcampos da opção restart config

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
condition	string	Escolhas: - none - on-failure - any	Reiniciar condição do serviço. Corresponde à opção --restart-condition do docker service create.
delay	string		Atraso entre reinicializações. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --restart-delay do docker service create.
max_attempts	integer		Número máximo de reinicializações do serviço. Corresponde à opção --restart-condition da criação do docker service create.
window	string		Reinicia a janela de avaliação da política. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --restart-window do docker service create.

Subcampos da opção rollback config

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
delay	string		Atraso entre rollbacks de tarefa. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --rollback-delay do docker service create.
failure_action	string	Escolhas: - continue - pause	Ação a ser executada em caso de falha de reversão. Corresponde à opção --rollback-failure-action do docker service create.
max_failure_ratio	float		Fração de tarefas que podem falhar durante uma reversão. Corresponde à opção --rollback-max-failure-ratio do docker service create.
monitor	string		Duração após cada reversão de tarefa para monitorar a falha. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --rollback-monitor do docker service create.
order	string		Especifica a ordem das operações durante rollbacks. Corresponde à opção --rollback-order do docker service create.
parallelism	integer		O número de contêineres a serem revertidos por vez. Se definido como 0, todos os contêineres são revertidos simultaneamente. Corresponde à opção --rollback-parallelism do docker service create.

Subcampos da opção secrets

Parâmetro	Tipo	Comentários
filename	string	Nome do arquivo que contém o segredo. O padrão é o secret_name, se não for especificado. Corresponde à chave de destino do serviço docker create --secret.
gid	string	GID do grupo do arquivo secreto.
mode	integer	Modo de acesso ao arquivo dentro do contêiner. Deve ser um número octal (como 0644 ou 0444).
secret_id	string	ID do segredo.
secret_name - required	string	Nome do segredo conforme definido na sua criação.
uid	string	UID do proprietário do arquivo secreto.

Subcampos da opção update config

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
delay	string		Atraso de atualização contínua. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --update-delay do docker service create.
failure_action	string	Escolhas: - continue - pause - rollback	Ação a ser executada em caso de falha do contêiner. Corresponde à opção --update-failure-action do docker service create.
max_failure_ratio	float		Fração de tarefas que podem falhar durante uma atualização antes que a ação de falha seja invocada. Corresponde à opção --update-max-failure-ratio do docker service create.
monitor	string		Tempo para monitorar tarefas atualizadas quanto a falhas. Aceita uma string em um formato semelhante a: 5h34m56s, 1m30s etc. As unidades suportadas são us, ms, s, m e h. Corresponde à opção --update-monitor do docker service create.
order	string		Especifica a ordem das operações ao lançar uma tarefa atualizada. Corresponde à opção --update-order do docker service create.
parallelism	integer		Paralelismo de atualização contínua. Corresponde à opção --update-parallelism do docker service create.

Notas

As imagens só serão resolvidas para o resumo mais recente ao usar Docker API e Docker SDK em versões mais recentes. Ao usar versões mais antigas, use force_update: true para acionar o swarm para resolver uma nova imagem.
Conecte-se ao daemon Docker fornecendo parâmetros para cada tarefa ou definindo variáveis de ambiente. Você pode definir DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY e DOCKER_TIMEOUT. Se você estiver usando uma máquina docker, execute o script enviado com o produto que configura o ambiente. Ele definirá essas variáveis para você. Veja https://docs.docker.com/machine/reference/env/ para mais detalhes.
Observe que o SDK do Docker permite apenas especificar o caminho para a configuração do Docker para muito poucas funções. Em geral, ele usará $ HOME / .docker / config.json se a variável de ambiente DOCKER_CONFIG não for especificada e, caso contrário, usará $ DOCKER_CONFIG / config.json.

Exemplos

# Exemplo: Definir comando e argumentos
- docker_swarm_service:
    name: myservice
    image: alpine
    command: sleep
    args:
      - "3600"

# Exemplo: Definir uma montagem
- docker_swarm_service:
    name: myservice
    image: alpine
    mounts:
      - source: /tmp/
        target: /remote_tmp/
        type: bind

# Exemplo: Definir rótulos em um serviço
- docker_swarm_service:
    name: myservice
    image: alpine
    labels:
      com.example.description: "Accounting webapp"
      com.example.department: "Finance"

# Exemplo: Definir variáveis de ambiente
- docker_swarm_service:
    name: myservice
    image: alpine
    env:
      ENVVAR1: envvar1
      ENVVAR2: envvar2
    env_files:
      - envs/common.env
      - envs/apps/web.env

# Exemplo: Definir registro fluente
- docker_swarm_service:
    name: myservice
    image: alpine
    logging:
      driver: fluentd
      options:
        fluentd-address: "127.0.0.1:24224"
        fluentd-async-connect: "true"
        tag: myservice

# Exemplo: Definir regras de reinicialização
- docker_swarm_service:
    name: myservice
    image: alpine
    restart_config:
      condition: on-failure
      delay: 5s
      max_attempts: 3
      window: 120s

# Exemplo: Definir configuração de atualização
- docker_swarm_service:
    name: myservice
    image: alpine
    update_config:
      parallelism: 2
      delay: 10s
      order: stop-first

# Exemplo: Definir configuração de reversão
- docker_swarm_service:
    name: myservice
    image: alpine
    update_config:
      failure_action: rollback
    rollback_config:
      parallelism: 2
      delay: 10s
      order: stop-first

# Exemplo: Definir preferências de posicionamento
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    placement:
      preferences:
        - spread: node.labels.mylabel
      constraints:
        - node.role == manager
        - engine.labels.operatingsystem == ubuntu 14.04

# Exemplo: Definir configurações
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    configs:
      - config_name: myconfig_name
        filename: "/tmp/config.txt"

# Exemplo: Definir redes
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    networks:
      - mynetwork

# Exemplo: Definir redes como dicionário
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    networks:
      - name: "mynetwork"
        aliases:
          - "mynetwork_alias"
        options:
          foo: bar

# Exemplo: Definir segredos
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    secrets:
      - secret_name: mysecret_name
        filename: "/run/secrets/secret.txt"

# Exemplo: Iniciar o serviço com verificação de integridade
- docker_swarm_service:
    name: myservice
    image: nginx:1.13
    healthcheck:
      # Verificar se o servidor nginx está íntegro com o comando (curl).
      # Se isso falhar ou atingir o tempo limite, a verificação de integridade falhará.
      test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 30s

# Exemplo: Configurar recursos de serviço
- docker_swarm_service:
    name: myservice
    image: alpine:edge
    reservations:
      cpus: 0.25
      memory: 20M
    limits:
      cpus: 0.50
      memory: 50M

# Exemplo: Excluir um serviço
- docker_swarm_service:
    name: myservice
    state: absent

Valores retornados

Chave	Tipo	Retornado quando	Descrição
changes	list / elements=string	Sempre	Lista de atributos de serviço alterados se um serviço foi alterado.
rebuilt	boolean	Sempre	Retornará verdadeiro se o serviço foi recriado (removido e criado)
swarm_service	dictionary	Sempre	Dicionário de variáveis que representam o estado atual do serviço. Corresponde ao formato dos parâmetros do módulo. Observe que os fatores não fazem parte dos vars registrados, mas são acessíveis diretamente.