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 proceed 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 /and so on/systemd/machine/docker.provider.d/choices.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/bins/json --cert client-cert.pem --key client-key.pem
Talvez você não actual 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/bins
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 america 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 associated with container operations http://127.0.0.1:2375/v1.41/bins
A API america 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 reproduction 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 foremost do Docker.
Listando contêineres
A lista completa de contêineres no host pode ser obtida no /bins/json ponto ultimate:
curl http://127.0.0.1:2375/v1.41/bins/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 overall de contêineres devolvidos com o prohibit parâmetro, como prohibit=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/bins/json?filters="identify":"demo"
Este URL retorna as informações associadas ao demo recipiente. Outros filtros podem ser expressos de maneira semelhante, como "standing":["running","paused"] para colocar contêineres em execução e pausados ou "well being=["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 /bins/create ponto ultimate. 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/bins/create
-X POST
-H "Content material-Kind: software/json"
-d '"Symbol": "example-image:newest"'
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 /bins/:identity/get started ponto ultimate:
curl http://127.0.0.1:2375/v1.41/bins/abc123/get started -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 /bins/prune ponto ultimate:
curl http://127.0.0.1:2375/v1.41/bins/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 overall de armazenamento liberado em bytes.
Esse endpoint aceita dois parâmetros de string de consulta para restringir a operação. o till parâmetro limita a exclusão a contêineres criados antes de um determinado momento, como till=10m ou till=2022-03-01. o label opção de filtros para recipientes com ou sem rótulos; contexto label=demo=instance só irá remover recipientes com o demo=instance etiqueta.
Listando imagens
o /photographs/json endpoint é usado para enumerar as imagens armazenadas no host do Docker:
curl http://127.0.0.1:2375/v1.41/photographs/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:newest".
Construindo imagens
Você pode usar a API para criar novas imagens do Docker a partir de Dockerfiles. o /construct 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/construct?t=example-image:newest -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:newest e armazenado no host do Docker.
Esse endpoint aceita muitos parâmetros de string de consulta adicionais que correspondem à funcionalidade do docker construct CLI. Esses incluem dockerfile=trail/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 /occasions A API mostra os dados do log de eventos do daemon que também podem ser acessados com o docker occasions Comando CLI. Esse endpoint transmite eventos em pace actual à medida que eles acontecem.
curl http://127.0.0.1:2375/v1.41/occasions
Vários tipos diferentes de eventos são expostos, incluindo criações de contêineres, tags de imagem, montagens de quantity e alterações de rede. Você pode filtrar para um tipo específico de evento usando o kind campo do filters parâmetro de consulta:
# Most effective get container occasions curl http://127.0.0.1:2375/v1.41/occasions?filters='kind':'container'
Também é possível restringir a eventos relacionados a um objeto específico:
# Get occasions relating the container with ID abc123 curl http://127.0.0.1:2375/v1.41/occasions?filters='container':'identity'
Dois outros parâmetros de string de consulta, since e tillpermitem especificar um intervalo de carimbo de information/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/data
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 further 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++, Cross, Java, NodeJS, PHP, Python e Ruby. Os SDKs envolvem os endpoints da API em categories 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.
Fonte da Notícia: www.howtogeek.com
