docker client

Cliente Docker

Estado: maduro

O Spotify não usa mais versões recentes deste projeto internamente. A versão do docker-client que estamos usando é a que o helios tem em seu pom.xml. Neste momento, não estamos desenvolvendo ou aceitando novos recursos ou mesmo corrigindo bugs não críticos. Sinta-se à vontade para fazer um fork deste repositório.

Este é um cliente Docker escrito em Java. É usado em muitos sistemas de produção críticos no Spotify.

• Compatibilidade de versão
• Download
• Exemplo de uso
• Começando
• Pré-requisitos
• Teste
• Liberando
• Uma nota sobre sombreamento
• Código de Conduta
• Manual do usuário

Compatibilidade de versão

docker-client é construído e testado nas seis versões secundárias mais recentes do Docker. No momento, são 17.03.1 ce - 17.12.1 ce (especificamente os aqui). Carregamos o artefato testado no Docker 17.12.1~ce. Consulte a documentação do Docker sobre o mapeamento entre a versão do Docker e a versão da API.

Download

Baixe o JAR mais recente ou pegue via Maven.

< dependency >
  < groupId >com.spotifygroupId >
  < artifactId >docker-clientartifactId >
  < version >LATEST-VERSIONversion >
dependency >

Exemplo de uso

 // Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
final DockerClient docker = DefaultDockerClient . fromEnv (). build ();

// Pull an image
docker . pull ( "busybox" );

// Bind container ports to host ports
final String [] ports = { "80" , "22" };
final Map < String , List < PortBinding >> portBindings = new HashMap <>();
for ( String port : ports ) {
    List < PortBinding > hostPorts = new ArrayList <>();
    hostPorts . add ( PortBinding . of ( "0.0.0.0" , port ));
    portBindings . put ( port , hostPorts );
}

// Bind container port 443 to an automatically allocated available host port.
List < PortBinding > randomPort = new ArrayList <>();
randomPort . add ( PortBinding . randomPort ( "0.0.0.0" ));
portBindings . put ( "443" , randomPort );

final HostConfig hostConfig = HostConfig . builder (). portBindings ( portBindings ). build ();

// Create container with exposed ports
final ContainerConfig containerConfig = ContainerConfig . builder ()
    . hostConfig ( hostConfig )
    . image ( "busybox" ). exposedPorts ( ports )
    . cmd ( "sh" , "-c" , "while :; do sleep 1; done" )
    . build ();

final ContainerCreation creation = docker . createContainer ( containerConfig );
final String id = creation . id ();

// Inspect container
final ContainerInfo info = docker . inspectContainer ( id );

// Start container
docker . startContainer ( id );

// Exec command inside running container with attached STDOUT and STDERR
final String [] command = { "sh" , "-c" , "ls" };
final ExecCreation execCreation = docker . execCreate (
    id , command , DockerClient . ExecCreateParam . attachStdout (),
    DockerClient . ExecCreateParam . attachStderr ());
final LogStream output = docker . execStart ( execCreation . id ());
final String execOutput = output . readFully ();

// Kill container
docker . killContainer ( id );

// Remove container
docker . removeContainer ( id );

// Close the docker client
docker . close ();

Começando

Se você está procurando como usar o docker-client, consulte o Manual do Usuário. Se você está procurando como construí-lo e desenvolvê-lo, continue lendo.

Pré-requisitos

docker-client deve ser compilável em qualquer plataforma com Docker 1.6+, JDK8+ e uma versão recente do Maven 3.

Uma observação sobre o uso do Docker para Mac

Se você estiver usando Docker para Mac e DefaultDockerClient.fromEnv() , pode não estar claro qual valor usar para a variável de ambiente DOCKER_HOST . O valor que você deve usar é DOCKER_HOST=unix:///var/run/docker.sock , pelo menos a partir da versão 1.11.1-beta11.

A partir da versão 4.0.8 do docker-client, DefaultDockerClient.fromEnv() usa unix:///var/run/docker.sock no OS X por padrão.

Teste

Se você estiver executando uma versão recente do docker (>= 1.12), que contém suporte nativo ao swarm, certifique-se de executar docker swarm init para inicializar o docker swarm.

Certifique-se de que o daemon do Docker esteja em execução e que você possa executar docker ps .

Você pode executar testes por conta própria com mvn test . Observe que os testes iniciam e param um grande número de contêineres, portanto, a lista de contêineres que você vê com docker ps -a começará a ficar bem longa após muitas execuções de testes. Você pode achar útil emitir ocasionalmente docker rm $(docker ps -aq) .

Liberando

Os commits no branch master acionarão nosso agente de integração contínua para construir o jar e liberá-lo fazendo upload para o Sonatype. Se você for um mantenedor de projeto com as credenciais necessárias, também poderá compilar e lançar localmente executando o comando abaixo.

mvn clean [-DskipTests -Darguments = -DskipTests] -Dgpg.keyname= < key ID used for signing artifacts > release:prepare release:perform

Uma nota sobre sombreamento

Observe que nas versões 2.7.6 e anteriores, o artefato padrão era a versão sombreada. Ao atualizar para a versão 2.7.7, você precisará incluir o classificador sombreado se dependia das dependências sombreadas no jar do docker-client.

Padrão:

< dependency >
  < groupId >com.spotifygroupId >
  < artifactId >docker-clientartifactId >
  < version >3.5.12version >
dependency >

Sombreado:

< dependency >
  < groupId >com.spotifygroupId >
  < artifactId >docker-clientartifactId >
  < classifier >shadedclassifier >
  < version >3.5.12version >
dependency >

Isto é particularmente importante se você usar Jersey 1.x em seu projeto. Para evitar conflitos com docker-client e Jersey 2.x, você precisará especificar explicitamente a versão sombreada acima.

Código de Conduta

Este projeto segue o Código de Conduta Aberto. Ao participar, espera-se que você honre este código.