gcloudwrap 1.0.5

gcloudwrap

gcloudwrap提供对Google API客户端的封装，以帮助您管理您的Google云（即其“计算”组件）。原始客户端提供了所有必需的功能，而gcloudwrap在额外功能方面添加得很少。然而，我们发现围绕云管理的一个薄封装更容易使用，这为我们提供了接近我们反复执行的任务的领域语言。

最初，由于原始的Google API客户端缺乏类型注解，并且其动态创建对象的方式在PyCharm等IDE中无法进行代码检查，我们发现使用它进行开发比较困难。由于涉及云管理的脚本通常执行时间较长，我们发现我们的开发迭代周期相当长，并且经常因为与类型错误相关的微小错误而中断。因此，我们添加了类型注解，以便静态分析器（如mypy）可以提前捕获类型错误。这极大地简化了部署脚本的开发。

请注意，我们并没有包装所有的Google Compute API。我们只关注了部署所需的那些部分。如果您希望包装更多功能，请创建一个问题。

场景

相关项目

• https://github.com/google/google-api-python-client/ – 我们包装的原始Google API客户端

• https://googlecloudplatform.github.io/google-cloud-python/ – Google Cloud Platform服务的客户端；在我们开始开发gcloudwrap时（2018-05-01）它仍然缺乏Compute支持

• https://pypi.ac.cn/project/gwrappy/ – Google API的用户友好封装。这个封装覆盖了比我们想象的更多服务。由于它不专注于部署，因此与我们的简单部署语言理念不符。

• https://libcloud.readthedocs.io/en/latest/index.html – 抽象化不同云服务提供商之间的差异，并提供统一的API。如果您计划使用不同的云服务提供商，这是一个更好的替代方案。如果您只想使用Google云，我们发现这样的抽象库引入了不必要的复杂性。

使用方法

我们尽可能遵循API的命名。API的定义和描述可以在这里找到：Google Compute API。然而，我们遵循Python命名规范，将所有camelCase参数重命名为snake_case。

以下代码片段显示了一个常见的部署示例，它创建了一个具有持久磁盘和预留外部IP地址的实例。该实例被标记为‘default-allow-http’，以在防火墙中打开HTTP端口。最后，我们授权实例使用公共SSH密钥。

import pathlib

import gcloudwrap

instance = 'some-instance'
address = 'some-address'
disk = 'some-persistent-disk'
device_name = 'persistency'

service_account = 'some-service-account@some-project-221984.iam.gserviceaccount.com

public_ssh_key = pathlib.Path(
    '/some/path/to/ssh/id_rsa.pub').read_text()

gce = gcloudwrap.Gce()

gce.addresses.insert(name=address)
static_ip = gce.addresses.static_ip(
    address=address)

gce.disks.insert(
    name=disk,
    disk_type='pd-standard',
    size_gb=5)

gce.instances.insert(
    name=instance,
    machine_type='f1-micro',
    address=static_ip,
    service_account=service_account)

gce.instances.attach_disk(
    instance=instance,
    disk=disk,
    device_name=device_name)

# open up HTTP port
tags = gce.instances.tags(instance=instance)
tags.items.add('default-allow-http')
gce.instances.set_tags(
    instance=instance, tags=tags)

# authorize the SSH key
keys = gcloudwrap.SSHKey(
    user='some-user',
    public_key=public_key)

metadata = gce.instances.metadata(instance=instance)
metadata.set_ssh_keys(keys=[key])

gce.instances.set_metadata(
    instance=instance,
    metadata=metadata)

# format the persistent disk and mount it
ssh = gce.instances.ssh(
    instance=instance,
    user="some-devop-user")

operator = gcloudwrap.Operator(call_fn=ssh.call)

operator.format_disk(
    device_name=device_name)

operator.mount_disk(
    device_name=device_name,
    path=pathlib.Path('/mnt/disks/persistency'))

有时，将授权SSH密钥的列表存储在文件中并在部署实例时重用该列表是很方便的。我们提供了一个快捷函数gcloudwrap.ssh_keys_from_file来实现这一点

import gcloudwrap

instance = 'some-instance'
keys_path = '/path/to/some/keys.txt'

keys = gcloudwrap.ssh_keys_from_file(
    path=keys_path,
    default_user='some-default-user')

metadata = gce.instances.metadata(instance=instance)
metadata.set_ssh_keys(keys=keys)

gce.instances.set_metadata(
    instance=instance,
    metadata=metadata)

安装

• 创建一个虚拟环境

python3 -m venv venv3

• 激活它

source venv3/bin/activate

• 使用pip安装gcloudwrap

pip3 install gcloudwrap

• 设置应用程序默认凭证

gcloud auth application-default login

开发

• 检出存储库。

• 在存储库根目录中，创建虚拟环境

python3 -m venv venv3

• 激活虚拟环境

source venv3/bin/activate

• 安装开发依赖项

pip3 install -e .[dev]

• 我们提供了一套实时测试。您需要设置环境，以便测试可以直接推断凭证。除了凭证外，您还可以使用以下环境变量

  • TEST_GCLOUDWRAP_SERVICE_ACCOUNT 用于指定在测试过程中创建的实例附加的服务账户。如果未指定，则使用GCE项目的默认服务账户。

  • TEST_GCLOUDWRAP_PREFIX 用于指定所有创建的Google云资源的名称前缀；如果未指定，则等于“test-gcloudwrap”

  • TEST_GCLOUDWRAP_SSH_PUBLIC_KEY_PATH 用于指定SSH公钥的路径；如果未指定，则等于 ~/.ssh/id_rsa.pub（其中“~”展开为用户主目录）

  请注意，实时测试将使用Google Cloud资源，您将为此付费。请始终检查测试完成后没有使用任何资源，以避免产生不必要的费用！

• 我们使用tox进行测试和打包发行版。假设虚拟环境已激活并且已安装开发依赖项，请运行

tox

• 我们还提供了一套预提交检查，用于lint和检查代码格式。在激活的虚拟环境中运行带有开发依赖项的本地版本

./precommit.py

• 预提交脚本还可以自动格式化代码

./precommit.py  --overwrite

版本控制

我们遵循语义版本控制。版本X.Y.Z表示

• X是主版本（不向后兼容），

• Y是次要版本（向后兼容），

• Z是补丁版本（向后兼容的bug修复）。