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

2024-02-26 06:35:03 55

Docker-clientforpython使用指南:

客户端初始化的三种方法

importdocker
docker.api()
docker.APIClient()
docker.client()
docker.DockerClient()其实也是docker.client()的一个子集
docker.from_env()其实就是docker.client()的一个子集

一、初始化客户端

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

>>>importdocker
>>>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(boolor:py:class:`~docker.tls.TLSConfig`):EnableTLS.Pass
``True``toenableitwithdefaultoptions,orpassa
:py:class:`~docker.tls.TLSConfig`objecttousecustom
configuration.

查看docker引擎当前版本:

$sudodockerversion
Client:
Version:1.9.1
APIversion:1.21
Goversion:go1.4.3
Gitcommit:a34a1d5-dirty
Built:TueMar2815:39:19UTC2017
OS/Arch:linux/amd64

Server:
Version:1.9.1
APIversion:1.21
Goversion:go1.4.3
Gitcommit:a34a1d5-dirty
Built:TueMar2815:39:19UTC2017
OS/Arch:linux/amd64

Thesdkofdockerforpython--docker==2.0.0:

1.丢弃了python2.6的支持
2.最低支持API版本为1.12(Engineversion1.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客户端的具体方法

importdocker
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的相关信息，相当于dockerinfo
C.info()

二、api方法使用示例

1.login方法定义

C.login()
login(*args,**kwargs)methodofdocker.client.DockerClientinstance
Authenticatewitharegistry.Similartothe``dockerlogin``command.

Args:
username(str):Theregistryusername
password(str):Theplaintextpassword
email(str):Theemailfortheregistryaccount
registry(str):URLtotheregistry.E.g.
``https://index.docker.io/v1/``
reauth(bool):Whetherrefreshexistingauthenticationonthe
Dockerserver.
dockercfg_path(str):Useacustompathforthe``.dockercfg``file
(default``$HOME/.dockercfg``)

Returns:返回的错误日志信息
(dict):Theresponsefromtheloginrequest

Raises:
:py:class:`docker.errors.APIError`
Iftheserverreturnsanerror.

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

2.images类定义：

build方法
get方法：
get(self,name)
Getsanimage.

Args:
name(str):Thenameoftheimage.

Returns:
(:py:class:`Image`):Theimage.

Raises:
:py:class:`docker.errors.ImageNotFound`Iftheimagedoesnot
exist.
:py:class:`docker.errors.APIError`
Iftheserverreturnsanerror.
list方法：
list(self,name=None,all=False,filters=None)
Listimagesontheserver.

Args:
name(str):Onlyshowimagesbelongingtotherepository``name``
all(bool):Showintermediateimagelayers.Bydefault,theseare
filteredout.
filters(dict):Filterstobeprocessedontheimagelist.
Availablefilters:
-``dangling``(bool)
-``label``(str):formateither``key``or``key=value``

Returns:
(listof:py:class:`Image`):Theimages.

Raises:
:py:class:`docker.errors.APIError`
Iftheserverreturnsanerror.

示例：

查看默认所有的镜像文件，以image-id进行区分
In[34]:C.images.list()
Out[34]:
[,
,
,
,
]

load方法：相当于dockerload

pull方法：下载镜像文件
pull(self,name,**kwargs)
Pullanimageofthegivennameandreturnit.Similartothe
``dockerpull``command.

Ifyouwanttogettherawpulloutput,usethe
:py:meth:`~docker.api.image.ImageApiMixin.pull`methodinthe
low-levelAPI.

Args:
repository(str):Therepositorytopull
tag(str):Thetagtopull
insecure_registry(bool):Useaninsecureregistry
auth_config(dict):Overridethecredentialsthat
:py:meth:`~docker.client.DockerClient.login`hassetfor
thisrequest.``auth_config``shouldcontainthe``username``
and``password``keystobevalid.

Returns:
(:py:class:`Image`):Theimagethathasbeenpulled.

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

push方法：上传镜像文件

push(self,repository,tag=None,**kwargs)
Pushanimageorarepositorytotheregistry.Similartothe``docker
push``command.

Args:
repository(str):Therepositorytopushto
tag(str):Anoptionaltagtopush
stream(bool):Streamtheoutputasablockinggenerator
insecure_registry(bool):Use``http://``toconnecttothe
registry
auth_config(dict):Overridethecredentialsthat
:py:meth:`~docker.api.daemon.DaemonApiMixin.login`hassetfor
thisrequest.``auth_config``shouldcontainthe``username``
and``password``keystobevalid.

Returns:
(generatororstr):Theoutputfromtheserver.

Raises:
:py:class:`docker.errors.APIError`

remove方法：dockerrmi
remove(self,*args,**kwargs)
Removeanimage.Similartothe``dockerrmi``command.

Args:
image(str):Theimagetoremove
force(bool):Forceremovaloftheimage
noprune(bool):Donotdeleteuntaggedparents

search方法：
search(self,*args,**kwargs)
SearchforimagesonDockerHub.Similartothe``dockersearch``
command.

Args:
term(str):Atermtosearchfor.

Returns:
(listofdicts):Theresponseofthesearch.

3.docker管理容器相关

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

client，create，get，list，model，run

列出当前存活的容器：

C.containers.list()

列出指定容器：

C.containers.get('')

创建容器：

C.containers.create
create(image,command=None,**kwargs)methodofdocker.models.containers.ContainerCollectioninstance
Createacontainerwithoutstartingit.Similarto``dockercreate``.

Takesthesameargumentsas:py:meth:`run`,exceptfor``stdout``,
``stderr``,and``remove``.

Returns:
A:py:class:`Container`object.

Raises:
:py:class:`docker.errors.ImageNotFound`
Ifthespecifiedimagedoesnotexist.
:py:class:`docker.errors.APIError`
Iftheserverreturnsanerror.


run一个容器：类似于命令行的dockerrun方法
run(image,command=None,stdout=True,stderr=False,remove=False,**kwargs)methodofdocker.models.containers.ContainerCollectioninstance
Runacontainer.Bydefault,itwillwaitforthecontainertofinish
andreturnitslogs,similarto``dockerrun``.

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

>>>importdocker
>>>client=docker.from_env()
>>>client.containers.run('alpine','echohelloworld')
b'helloworld\n'

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

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

blkio_weight_device:设置设备BlockIO权重：``[{"Path":"device_path","Weight":weight}]``.
blkio_weight:设置blockIO的权重范围10-1000.
cap_add(listofstr):增加内核特性比如：``["SYS_ADMIN","MKNOD"]``.
cap_drop(listofstr):删除内核特性
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):后台运行一个容器，布尔类型值.相当于dockerrun-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):映射主机的设备到容器中``::``.
dns(list):配置当前的dns-server
dns_opt(list):添加额外的dns参数选项到容器内部，比如resolv.conf文件
dns_search(list):设置dns搜索域
domainname(strorlist):设置当前dns搜索域名

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

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

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

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

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

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

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


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

ports(dict):为容器内部绑定端口相当于dockerrun-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):开放所有的端口到本机上相当于dockerrun-P

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

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

stdin_open(bool):保持``STDIN``打开即使没有attach到容器内部相当于dockerrun-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相当于dockerrun-t

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

userns_mode(str):为容器设置用户的命名空间模式，当用户的namespace的remapping参数被启用的时候，支持参数有'host'
valuesare:``host``
volume_driver(str):数据卷挂载驱动名
volumes(dictorlist):一个字典配置，将外部数据卷挂载到容器内部，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`objectis
returnedinstead.

异常信息:
如果容器以非0状态退出，或者`detach`参数为`False`
:py:class:`docker.errors.ContainerError`
如果指定的镜像不存在
:py:class:`docker.errors.ImageNotFound`
如果是服务返回一个错误
:py:class:`docker.errors.APIError`
Iftheserverreturnsanerror.

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

Commandline:
$dockerrun-itd-P--cpuset_cpus='0,1'--cpu_shares=2--cpu_period=10000--hostname=xxbandy--mem_limit=512m--net=none--oom_kill_disable=True-P-uadminbusybox/bin/sh

PythonAPI:
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删除容器信息，相当于dockerrm参数：c1.remove(v=True,link=True,force=True)
c2.rename重命名容器名，相当于dockerrenmameoldnamenewname
c1.resize设置ttysession信息
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(intorstr):内存限制
mem_reservation(intorstr):内存软限制
memswap_limit(intorstr):swap限制总的可使用内存限制(memory+swap)，-1表示关闭swap
kernel_memory(intorstr):内核内存限制
restart_policy(dict):重启策略

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

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

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

#catmemory.limit_in_bytes
536870912

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

#catmemory.limit_in_bytes
1073741824
#grephierarchical_memory_limitmemory.stat
hierarchical_memory_limit1073741824

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

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

热门推荐

随机推荐