O Docker Engine expõe uma API REST que você pode usar para controlar seus contêineres sem o docker CLI. A API expõe uma funcionalidade equivalente usando chamadas de rede HTTP. Você pode criar scripts de operações comuns do Docker usando sua linguagem de programação favorita ou controlar remotamente um de seus hosts. A CLI internamente depende da mesma API para fornecer seus comandos integrados.
Neste artigo, veremos os conceitos básicos de como habilitar e usar a API. Se você tiver um caso de uso específico em mente, consulte a documentação de referência da API para identificar os endpoints necessários.
Habilitando a API do Docker Engine
A API é integrada ao Docker Engine. Qualquer host do Docker em funcionamento já está preparado para atender às interações da API. Para expor o serviço, você precisa vincular o daemon do Docker a um soquete TCP, bem como, ou em vez do soquete Unix padrão. Começar dockerd com o -H sinalizador para especificar os soquetes para escutar:
sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
Este comando expõe a API na porta 2375. O soquete Unix padrão é retido para que a CLI do Docker continue funcionando sem qualquer reconfiguração. A porta 2375 é usada para o Docker por convenção; sinta-se à vontade para alterá-lo para se adequar ao seu ambiente.
Você pode fazer com que o Docker sempre comece com essas configurações editando seu systemd arquivo de configuração do serviço. Editar ou criar /etc/systemd/system/docker.service.d/options.confencontre o ExecStart line e modifique-o para incluir seus sinalizadores extras:
[Service] ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
Recarregue seu systemd configuração para aplicar a alteração:
sudo systemctl daemon-reload
Agora você está pronto para interagir com a API do Docker Engine em 127.0.0.1:2375.
Uma nota sobre segurança
As etapas acima expõem a API sem nenhuma proteção. Qualquer pessoa com acesso à porta 2375 em seu host pode enviar comandos arbitrários ao daemon do Docker, iniciando novos contêineres, preenchendo seu disco com imagens ou destruindo cargas de trabalho existentes.
Você deve configurar seu firewall para bloquear conexões com a porta, a menos que esteja expondo intencionalmente o Docker em sua rede. Se você deseja habilitar o acesso remoto, você deve configurar o TLS para o soquete do daemon para limitar o acesso a clientes autenticados.
Quando o TLS estiver habilitado, você precisará instalar a autoridade de certificação do daemon em cada um de seus clientes. Você terá que fornecer o certificado do cliente e a chave do cliente com cada solicitação que fizer. As etapas a serem seguidas dependerão da ferramenta que você está usando. Aqui está um exemplo para curl:
curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem
Talvez você não precise vincular um soquete TCP, dependendo do seu caso de uso. Se o seu cliente suporta soquetes Unix, você pode usar o existente do Docker para fazer suas conexões:
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers
Esta pode ser uma escolha mais segura do que arriscar a exposição não intencional de um soquete TCP.
Usando a API
A API usa endpoints com versão para que você possa fixar versões específicas de formatos de solicitação e resposta. Você deve indicar a versão que está usando no início de cada URL de endpoint. v1.41 é a versão mais recente presente nas compilações de produção do Docker no momento da escrita.
http://127.0.0.1:2375/v1.41
Os endpoints da API são agrupados em unidades funcionais REST. Eles são mapeados para os tipos de objetos fundamentais do Docker, como contêineres, imagens e volumes. Normalmente, você pode encontrar as APIs para um tipo de objeto específico na URL base que começa com seu nome:
# APIs related to container operations http://127.0.0.1:2375/v1.41/containers
A API usa JSON para todas as trocas de dados com seu cliente HTTP. Os endpoints aceitam corpos de solicitação JSON e emitem respostas JSON em troca. Isso deve simplificar o manuseio de dados dentro de seus aplicativos, pois você pode usar a biblioteca JSON incluída em seu ambiente de programação. Ferramentas como jq pode ser usado para condensar, filtrar e classificar respostas se você estiver experimentando em seu terminal.
Pontos de extremidade comuns
Como a API replica a funcionalidade da CLI do Docker, há muitos endpoints possíveis para abranger todos eles aqui. Em vez disso, demonstraremos algumas das opções mais usadas relacionadas à funcionalidade principal do Docker.
Listando contêineres
A lista completa de contêineres no host pode ser obtida no /containers/json ponto final:
curl http://127.0.0.1:2375/v1.41/containers/json
O padrão é exibir apenas contêineres em execução. Adicionar all=true para a string de consulta para incluir contêineres parados também. Limite o número total de contêineres devolvidos com o limit parâmetro, como limit=10. Apenas os 10 contêineres criados mais recentemente serão incluídos.
Vários filtros diferentes estão disponíveis para remover a lista de contêineres com atributos específicos. Eles são definidos com a seguinte sintaxe:
curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}
Este URL retorna as informações associadas ao demo recipiente. Outros filtros podem ser expressos de maneira semelhante, como {"status":["running","paused"]} para colocar contêineres em execução e pausados ou {"health=["healthy"]} apenas para recipientes saudáveis.
Iniciando um novo contêiner
Iniciar um contêiner é um processo de dois estágios ao usar a API. Primeiro, você precisa criar o contêiner e, em seguida, iniciá-lo em uma chamada de API separada.
Crie seu container fazendo um POST pedido ao /containers/create ponto final. Isso precisa de um corpo JSON com campos que correspondam aos sinalizadores aceitos pelo docker run Comando CLI.
Aqui está um exemplo mínimo de criação de um contêiner:
curl http://127.0.0.1:2375/v1.41/containers/create
-X POST
-H "Content-Type: application/json"
-d '{"Image": "example-image:latest"}'
A resposta JSON incluirá o ID do novo contêiner e quaisquer avisos decorrentes de sua criação. Envie o ID em uma chamada para o /containers/:id/start ponto final:
curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST
O contêiner agora será executado no host do Docker.
Limpeza de recipientes
Remova os contêineres parados emitindo um POST pedido ao /containers/prune ponto final:
curl http://127.0.0.1:2375/v1.41/containers/prune -X POST
Você receberá uma resposta JSON com ContainersDeleted e SpaceReclaimed Campos. ContainersDeleted é uma matriz dos IDs de contêiner que foram removidos com sucesso. SpaceReclaimed informa de você o espaço total de armazenamento liberado em bytes.
Esse endpoint aceita dois parâmetros de string de consulta para restringir a operação. o until parâmetro limita a exclusão a contêineres criados antes de um determinado momento, como until=10m ou until=2022-03-01. o label opção de filtros para recipientes com ou sem rótulos; contexto label=demo=example só irá remover recipientes com o demo=example etiqueta.
Listando imagens
o /images/json endpoint é usado para enumerar as imagens armazenadas no host do Docker:
curl http://127.0.0.1:2375/v1.41/images/json
Você pode usar filtros para alterar o conteúdo da resposta. Eles são fornecidos como um objeto JSON no filters parâmetro de string de consulta, de forma semelhante à API da lista de contêineres. Uma opção digna de nota é reference que seleciona a imagem com uma determinada tag: filters={"reference":"hello-world:latest"}.
Construindo imagens
Você pode usar a API para criar novas imagens do Docker a partir de Dockerfiles. o /build endpoint deve ser enviado um tar arquivo. O conteúdo deste arquivo será usado como contexto de construção da imagem. O arquivo deve incluir Dockerfile contendo as instruções para a compilação.
cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST
O comando acima enviará context.tar para o daemon do Docker e construa uma imagem usando o Dockerfile dentro de. A imagem será marcada como example-image:latest e armazenado no host do Docker.
Esse endpoint aceita muitos parâmetros de string de consulta adicionais que correspondem à funcionalidade do docker build CLI. Esses incluem dockerfile=path/to/dockerfilepara especificar o caminho para o Dockerfile do contexto de compilação, rm=trueque exclui contêineres intermediários criados pela compilação e pull=true para tentar adquirir versões atualizadas de imagens referenciadas pelo Dockerfile.
A API exige que seu cliente permaneça conectado até que a compilação seja concluída. A compilação será cancelada se a rede cair e a conexão for fechada.
Como listar logs de eventos do daemon
o /events A API mostra os dados do log de eventos do daemon que também podem ser acessados com o docker events Comando CLI. Esse endpoint transmite eventos em tempo real à medida que eles acontecem.
curl http://127.0.0.1:2375/v1.41/events
Vários tipos diferentes de eventos são expostos, incluindo criações de contêineres, tags de imagem, montagens de volume e alterações de rede. Você pode filtrar para um tipo específico de evento usando o type campo do filters parâmetro de consulta:
# Only get container events
curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}
Também é possível restringir a eventos relacionados a um objeto específico:
# Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}
Dois outros parâmetros de string de consulta, since e untilpermitem especificar um intervalo de carimbo de data/hora para exibir eventos históricos.
Obtendo informações do sistema
A API do Docker Engine pode ser usada para obter informações sobre o host físico em que está sendo executado:
curl http://127.0.0.1:2375/v1.41/info
Esse endpoint fornece detalhes abrangentes que descrevem o estado atual e a configuração do host e do daemon do Docker. Os campos na resposta incluem contagens do número de contêineres em execução, pausados e parados, o caminho para o diretório de instalação do Docker, detalhes de hardware e sistema operacional e a configuração do Swarm do servidor quando ele está operando em um cluster.
Conclusão
A API do Docker Engine oferece uma maneira de enviar comandos para o daemon do Docker do seu host por HTTP. Isso simplifica o script de interações programáticas sem depender de comportamentos específicos da CLI do Docker. A API também pode ser usada para gerenciar remotamente seus servidores Docker para monitoramento aprimorado e facilidade de manutenção.
Embora chamar a API deva ser simples, você precisa prestar atenção às proteções de segurança em torno do seu soquete TCP. Evite expor o soquete em sua rede, a menos que esteja protegido com TLS para que apenas clientes aprovados possam se conectar. Omitir esse estágio extra de configuração pode custar caro se um invasor descobrir sua instância do daemon e começar a emitir comandos.
Você pode facilitar ainda mais o uso da API em seus próprios aplicativos adotando um dos SDKs. Uma opção oficial ou fornecida pela comunidade está disponível para todas as linguagens de programação populares, incluindo C, C#, C++, Go, Java, NodeJS, PHP, Python e Ruby. Os SDKs envolvem os endpoints da API em classes e funções convenientes para chamar de seu código, reduzindo a quantidade de clichê necessária para interagir com uma instalação do Docker.
0 Comments