Docker-client for python详解及简单示例

docker-client for python使用指南:

客户端初始化的三种方法

import docker
docker.api()
docker.apiclient()
docker.client()
docker.dockerclient() 其实也是docker.client()的一个子集
docker.from_env() 其实就是docker.client()的一个子集

一、初始化客户端

1.docker客户端的初始化工作

>>> import docker
>>> client = docker.apiclient(base_url='unix://var/run/docker.sock',version='1.21',timeout=5)
>>> client.version()
{u'apiversion': u'1.21',
 u'arch': u'amd64',
 u'buildtime': u'2016-09-27t23:38:15.810178467+00:00',
 u'experimental': true,
 u'gitcommit': u'45bed2c',
 u'goversion': u'go1.6.3',
 u'kernelversion': u'4.4.22-moby',
 u'os': u'linux',
 u'version': u'1.12.2-rc1'}

  args:
   base_url (str): 指定链接路径，可以通过socket或者tcp方式链接
     ``unix:///var/run/docker.sock`` or ``tcp://127.0.0.1:1234``.
   version (str): 指定api使用的版本(docker=2.0.0默认的api版本是1.24,最低支持1.21,docker1.9+的api是1.21),因此在使用python的docker模块时一定要注意docker的api以及docker模块的api是否兼容。当然如果设置为 ``auto`` 降回去自动检测server的版本
   timeout (int): 使用api调用的默认超时时间，默认单位为秒
   tls (bool or :py:class:`~docker.tls.tlsconfig`): enable tls. pass
     ``true`` to enable it with default options, or pass a
     :py:class:`~docker.tls.tlsconfig` object to use custom
     configuration.

查看docker引擎当前版本:

$ sudo docker version
client:
 version:   1.9.1
 api version: 1.21
 go version:  go1.4.3
 git commit:  a34a1d5-dirty
 built:    tue mar 28 15:39:19 utc 2017
 os/arch:   linux/amd64

server:
 version:   1.9.1
 api version: 1.21
 go version:  go1.4.3
 git commit:  a34a1d5-dirty
 built:    tue mar 28 15:39:19 utc 2017
 os/arch:   linux/amd64

the sdk of docker for python--docker==2.0.0:

1.丢弃了python2.6的支持
2.最低支持api版本为1.12(engine version 1.9.0+)
3.`docker.client`被替换成`docker.apiclient`
4.`docker.from_env`初始化一个docker客户端实例代替了`apiclient `实例 
5.从`apiclient.start`中移除了hostconfig参数
6.开始由之前的docker-py模块变为docker
7.`docker.ssladapter`替换为`docker.transport.ssladapter`

2.docker客户端的具体方法

import docker
c = docker.dockerclient(base_url='unix://var/run/docker.sock',version='auto',timeout=10)

##docker相关的方法使用
使用dockerclient对象，会有以下方法：
c.api,
c.containers,
c.events,
c.from_env,
c.images,
c.info,
c.login,
c.networks,
c.nodes,
c.ping,
c.services,
c.swarm,
c.version,
c.volumes,


#输出docker的相关信息，相当于docker info
c.info()

二、api方法使用示例

1. login方法定义

c.login()
login(*args, **kwargs) method of docker.client.dockerclient instance
  authenticate with a registry. similar to the ``docker login`` command.

  args:
    username (str): the registry username
    password (str): the plaintext password
    email (str): the email for the registry account
    registry (str): url to the registry. e.g.
      ``https://index.docker.io/v1/``
    reauth (bool): whether refresh existing authentication on the
      docker server.
    dockercfg_path (str): use a custom path for the ``.dockercfg`` file
  (default ``$home/.dockercfg``)

  returns:返回的错误日志信息
    (dict): the response from the login request

     raises:
    :py:class:`docker.errors.apierror`
      if the server returns an error.

##使用login方法登录
c.login('xxbandy123','nslalla')

2.images 类定义：

build方法
get方法：
get(self, name)
  gets an image.

  args:
    name (str): the name of the image.

  returns:
    (:py:class:`image`): the image.

  raises:
    :py:class:`docker.errors.imagenotfound` if the image does not
    exist.
    :py:class:`docker.errors.apierror`
      if the server returns an error.
list方法：
  list(self, name=none, all=false, filters=none)
  list images on the server.

  args:
    name (str): only show images belonging to the repository ``name``
    all (bool): show intermediate image layers. by default, these are
      filtered out.
    filters (dict): filters to be processed on the image list.
      available filters:
      - ``dangling`` (bool)
      - ``label`` (str): format either ``key`` or ``key=value``

  returns:
    (list of :py:class:`image`): the images.

  raises:
    :py:class:`docker.errors.apierror`
      if the server returns an error.

示例：

查看默认所有的镜像文件，以image-id进行区分
in [34]: c.images.list()
out[34]: 
[<image: 'busybox:latest'>,
 <image: '172.24.254.235:5010/rancher-server:latest', 'rancher/server:latest'>,
 <image: '172.24.254.235:5010/jdsingleuser:latest'>,
 <image: 'registry:2'>,
 <image: '172.24.254.235:5010/rancher-agent:latest', 'rancher/agent:v1.0.2'>]

load方法：相当于docker load

pull方法：下载镜像文件
 pull(self, name, **kwargs)
  pull an image of the given name and return it. similar to the
  ``docker pull`` command.

  if you want to get the raw pull output, use the
  :py:meth:`~docker.api.image.imageapimixin.pull` method in the
  low-level api.

  args:
    repository (str): the repository to pull
    tag (str): the tag to pull
    insecure_registry (bool): use an insecure registry
    auth_config (dict): override the credentials that
      :py:meth:`~docker.client.dockerclient.login` has set for
      this request. ``auth_config`` should contain the ``username``
      and ``password`` keys to be valid.

  returns:
    (:py:class:`image`): the image that has been pulled.

需要注意的是：使用pull的时候，会弱匹配所有的tag标签

push方法：上传镜像文件

push(self, repository, tag=none, **kwargs)
  push an image or a repository to the registry. similar to the ``docker
  push`` command.

  args:
    repository (str): the repository to push to
    tag (str): an optional tag to push
    stream (bool): stream the output as a blocking generator
    insecure_registry (bool): use ``http://`` to connect to the
      registry
    auth_config (dict): override the credentials that
      :py:meth:`~docker.api.daemon.daemonapimixin.login` has set for
      this request. ``auth_config`` should contain the ``username``
      and ``password`` keys to be valid.

  returns:
    (generator or str): the output from the server.

  raises:
    :py:class:`docker.errors.apierror`

remove方法：docker rmi 
 remove(self, *args, **kwargs)
  remove an image. similar to the ``docker rmi`` command.

  args:
    image (str): the image to remove
    force (bool): force removal of the image
    noprune (bool): do not delete untagged parents

search方法：
search(self, *args, **kwargs)
  search for images on docker hub. similar to the ``docker search``
  command.

  args:
    term (str): a term to search for.

  returns:
    (list of dicts): the response of the search.

3.docker管理容器相关

c.containers类，下面有相关的方法：

client，create，get，list，model，run

列出当前存活的容器：

c.containers.list()

列出指定容器：

c.containers.get('')

创建容器：

c.containers.create
create(image, command=none, **kwargs) method of docker.models.containers.containercollection instance
  create a container without starting it. similar to ``docker create``.

  takes the same arguments as :py:meth:`run`, except for ``stdout``,
  ``stderr``, and ``remove``.

  returns:
    a :py:class:`container` object.

  raises:
    :py:class:`docker.errors.imagenotfound`
      if the specified image does not exist.
    :py:class:`docker.errors.apierror`
      if the server returns an error.


run一个容器：类似于命令行的docker run方法
run(image, command=none, stdout=true, stderr=false, remove=false, **kwargs) method of docker.models.containers.containercollection instance
  run a container. by default, it will wait for the container to finish
  and return its logs, similar to ``docker run``.

  如果'detach'参数设置为'true',他将立即返回一个container对象，类似于'docker run -d'  
  实例:
    运行一个容器并获取输出。

    >>> import docker
    >>> client = docker.from_env()
    >>> client.containers.run('alpine', 'echo hello world')
    b'hello world\n'

    后台运行一个容器:
    >>> container = client.containers.run('bfirsh/reticulate-splines',
                       detach=true)
    获取该容器的日志信息
    >>> container.logs()
    'reticulating spline 1...\nreticulating spline 2...\n'

  参数介绍:
    image (str): run一个容器所需要的镜像(str类型)
    command (str or list): 容器启动默认运行的命令(字符串或者列表类型).

    blkio_weight_device: 设置设备block io 权重：``[{"path": "device_path", "weight": weight}]``.
    blkio_weight: 设置block io 的权重 范围10-1000.
    cap_add (list of str): 增加内核特性 比如：``["sys_admin", "mknod"]``.
    cap_drop (list of str): 删除内核特性
    cpu_group (int): 每颗cpu的长度
    cpu_period (int): 容器在每一个cpu的时间周期内可以得到多少的的cpu时间(ms)
    cpu_shares (int): 共享cpu权重cpu 相对权重
    cpuset_cpus (str): 绑定cpu的执行 (``0-3``,``0,1``).

    detach (bool): 后台运行一个容器，布尔类型值.相当于docker run -d选项

    device_read_bps: 从一个设备上限制读速率(bytes/s) `[{"path": "device_path", "rate": rate}]`
    device_read_iops: 从一个设备中限制读取速率(io/s)
    device_write_bps: 从一个设备上限制写速率(bytes/s)
    device_write_iops: 从一个设备中限制读取速率(io/s)
    devices (list): 映射主机的设备到容器中``<path_on_host>:<path_in_container>:<cgroup_permissions>``.
    dns (list): 配置当前的dns-server
    dns_opt (list): 添加额外的dns参数选项到容器内部，比如resolv.conf文件
    dns_search (list): 设置dns搜索域
    domainname (str or list): 设置当前dns搜索域名

    entrypoint (str or list): 为容器设置入口,覆盖镜像中的entrypoint

    environment (dict or list): 内部环境变量["somevariable=xxx"]``
    extra_hosts (dict): 在容器内部添加额外的主机名解析(本地hosts文件)
    group_add (list): 设置容器内部进程运行时额外的组名（gid）

    hostname (str): 容器设置额外的主机名.相当于docker run -h/--hostname 选项

    ipc_mode (str): 为容器设置ipc模式
    isolation (str): 隔离技术的使用default: `none`.
    labels (dict or list): 一个k/v类型的标签存储``{"label1": "value1", "label2": "value2"}``)或一个列表类型的k/v存储``["label1", "label2"]``
    links (dict or list of tuples): 为容器映射一个别名``(name, alias)`` 
    log_config (dict): 容器的日志配置。
      keys:
      - ``type`` the logging driver name.
      - ``config`` a dictionary of configuration for the logging
       driver.
    mac_address (str): 绑定mac地址.

    mem_limit (float or str): 内存限制，允许浮点型数据或单位区分的字符串(``100000b``, ``1000k``, ``128m``, ``1g``). 如果一个字符串没有指定单位，默认会使用字节(bytes)
    mem_limit (str or int): 容器可以使用的最大内存数量(e.g. ``1g``).

    mem_swappiness (int): 调整容器内存的swappiness行为状态，允许的数值为0-100 
    memswap_limit (str or int): 最大内存限制，容器可用的内存为(memory+swap)
    networks (list): 设置连接到该容器网络的名称
    name (str): 为容器设置名字
    network_disabled (bool): 禁用容器网络
    network_mode (str): 网络模式 相当于docker run --net='none'

      - ``bridge`` 默认使用桥接模式
      - ``none`` 无网络模式
      - ``container:<name|id>`` 重用另外一个容器的网络
      - ``host`` 使用本机的网络栈


    oom_kill_disable (bool): 是否启用oom
    oom_score_adj (int): 一个整数，以调整oom的整体性能.
    pid_mode (str): pid模式，如果设置为'host',在容器内部将会使用宿主机的host pid
    pids_limit (int): 调整容器的pid的限制。'-1'表示不限制

    ports (dict): 为容器内部绑定端口 相当于docker run -p 
      实例：
       ``{'2222/tcp': 3333}`` 暴露容器内部的2222端口到本机的3333端
       ``{'2222/tcp': none}`` 将容器内部的2222随机映射到本机
       ``{'1111/tcp': ('127.0.0.1', 1111)}``.
       ``{'1111/tcp': [1234, 4567]}`` 绑定多个端口


    privileged (bool): 给容器额外的特权

    publish_all_ports (bool): 开放所有的端口到本机上 相当于docker run -p 

    read_only (bool): 以只读方式挂载容器的根文件系统
    remove (bool): 当容器退出的时候删除，默认是'false'
    restart_policy (dict): 当容器退出时重启容器
      配置参数如下：
      - ``name`` one of ``on-failure``, or ``always``.
      - ``maximumretrycount`` 容器失败多少次后进行重启
      实例:
      ``{"name": "on-failure", "maximumretrycount": 5}``

    security_opt (list): 设置安全标签，类似于selinux
    shm_size (str or int): /dev/shm 的大小(e.g. ``1g``).

    stdin_open (bool): 保持 ``stdin`` 打开即使没有attach到容器内部相当于docker run -i

    stdout (bool): 当detach=false的时候，从'stdout'返回日志。默认为true
    stdout (bool): 当detach=false的时候，从'stderr'返回日志，默认为false
    stop_signal (str): 设置用于停止容器的信号。(e.g. ``sigint``).
    sysctls (dict): 容器内部设置内核参数
    tmpfs (dict): 挂载临时文件系统 
            .. code-block:: python

        {
          '/mnt/vol2': '',
          '/mnt/vol1': 'size=3g,uid=1000'
        }

    tty (bool): 分配一个tty 相当于docker run -t

    ulimits (list): 在容器内部设置ulimits值，一个字典类型的列表
    user (str or int): 设置容器启动的用户名以及id

    userns_mode (str): 为容器设置用户的命名空间模式，当用户的namespace的remapping参数被启用的时候，支持参数有'host'
      values are: ``host``
    volume_driver (str): 数据卷挂载驱动名
    volumes (dict or list): 一个字典配置，将外部数据卷挂载到容器内部，key是主机或者数据卷的名字，value是带有key的字典：
        实例：
        {'/home/user1/': {'bind': '/mnt/vol2', 'mode': 'rw'},
         '/var/www': {'bind': '/mnt/vol1', 'mode': 'ro'}}

    volumes_from (list): 获取容器名或者id标识。
    working_dir (str): 容器默认的工作目录

  返回参数:
    容器的日志，包含 ``stdout``, ``stderr``
    if ``detach`` is ``true``, a :py:class:`container` object is
    returned instead.

  异常信息:
    如果容器以非0状态退出，或者`detach`参数为`false`
    :py:class:`docker.errors.containererror`
    如果指定的镜像不存在
    :py:class:`docker.errors.imagenotfound`
    如果是服务返回一个错误
    :py:class:`docker.errors.apierror`
      if the server returns an error.

示例： 一个完成的创建容器的基本粒子：

command line:
$ docker run -itd -p --cpuset_cpus='0,1' --cpu_shares=2 --cpu_period=10000 --hostname=xxbandy --mem_limit=512m --net=none --oom_kill_disable=true -p -u admin busybox /bin/sh

python api:
c1 = c.containers.run('busybox',command='/bin/sh',name='xxb-test',detach=true,tty=true,stdin_open=true,cpuset_cpus='0,1',cpu_shares=2,cpu_period=10000,hostname='xxbandy',mem_limit='512m',network_mode='none',oom_kill_disable=true,publish_all_ports=true,user='root')

查看容器相关信息：
容器id，64位的字符
in [20]: c1.id
out[20]: '499db0824206d61d09db2f36c70aa84bdb1a4b6d508b001a618d2010a23fea7e'


c1.logs 
c1.name   获取容器名信息
c1.reload
c1.remove  删除容器信息，相当于docker rm 参数：c1.remove(v=true,link=true,force=true)
c2.rename   重命名容器名，相当于docker renmame oldname newname
c1.resize   设置tty session信息
c1.restart  重启容器信息
c1.start   启动容器信息
c1.stats   容器状态

c1.update  动态调整容器内部信息（blkio_weight，cpu_period，cpu_quota，cpu_shares，cpuset_cpus，cpuset_mems，mem_limit，mem_reservation）
  args:
    blkio_weight (int): 块io权重比例（10-100）
    cpu_period (int): 限制cpu公平调度周期
    cpu_quota (int): 限制cpu公平调度配额
    cpu_shares (int): 设置cpu共享权重
    cpuset_cpus (str): 指定cpu执行(0-3, 0,1)
    cpuset_mems (str): 指定cpu内存的执行(0-3, 0,1)
    mem_limit (int or str): 内存限制
    mem_reservation (int or str): 内存软限制
    memswap_limit (int or str): swap限制总的可使用内存限制(memory + swap)，-1表示关闭swap
    kernel_memory (int or str): 内核内存限制
    restart_policy (dict): 重启策略

注意:update方法在docker1.10之后才增加了改功能

查看容器相关信息：
容器id，64位的字符
in [20]: c1.id
out[20]: '499db0824206d61d09db2f36c70aa84bdb1a4b6d508b001a618d2010a23fea7e'

可以在/sys/fs/cgroup/memory/docker目录下面查看到每个容器的相关cgroup配置信息。
查看内存信息：
# grep hierarchical memory.stat   分别显示容器的内存限制和swap限制
hierarchical_memory_limit 536870912
hierarchical_memsw_limit 1073741824

#cat memory.limit_in_bytes
536870912

可以在/sys/fs/cgroup/cpuset/docker目录下面查看到容器cpu的相关配置
# cat cpuset.cpus    显示当前绑定的cpu信息
0-1
使用docker update动态调整内存信息:
docker update -m 1024m xuxuebiao-test

# cat memory.limit_in_bytes 
1073741824
# grep hierarchical_memory_limit memory.stat 
hierarchical_memory_limit 1073741824

感谢阅读 ，希望能帮助到大家，谢谢大家对本站的支持！