# Overview
**aliyun-img-utils** provides a command line utility and API for publishing
images in the Aliyun Cloud. This includes helper functions for uploading
image blobs, creating compute images and replicating/publishing/deprecating/
images across all available regions.
See the [Alibaba docs](https://www.alibabacloud.com/getting-started) to get
more info on the Aliyun cloud.
# Requirements
- oss2
- Click
- PyYAML
- aliyun-python-sdk-core
- aliyun-python-sdk-ecs
# Installation
To install the package on openSUSE and SLES use the following commands as root:
```shell
$ zypper ar http://download.opensuse.org/repositories/Cloud:/Tools/<distribution>
$ zypper refresh
$ zypper in python3-aliyun-img-utils
```
To install from PyPI:
```shell
$ pip install aliyun-img-utils
```
# Configuration
**aliyun-img-utils** can be configured with yaml based profiles. The configuration
directory is `~/.config/aliyun_img_utils` and the default profile is default.yaml
(~/.config/aliyun_img_utils/default.yaml).
The following configration options are available in a configuration profile:
- no_color
- log_level
- region
- access_key
- access_secret
- bucket_name
An example configuration profile may look like:
```yaml
region: cn-beijing
access_key: FakeKEY
access_secret: FAKESecret
bucket_name: smarlow-testing
```
When running any command the profile can be chosen via the *--profile* option.
For example, *aliyun-img-utils image upload --profile production* would pull
configuration from ~/.config/aliyun_img_utils/production.yaml.
# CLI
The CLI is broken into multiple distinct subcommands that handle different
steps of creating and publishing images in the Aliyun cloud framework.
## Image blob upload
The first step is to upload a qcow2 image to a storage bucket. For this
*aliyun-img-utils image upload* is available.
Example:
```shell
$ aliyun-img-utils image upload --image-file ~/Documents/test.qcow2
```
In this example the qcow2 file will be uploaded to the storage bucket configured
for the given profile and the blob will be named test.qcow2. If you want to
override the name of the blob there is a *--blob-name* option.
For more information about the image upload function see the help message:
```shell
$ aliyun-img-utils image upload --help
```
## Compute image create
The next step is to create a compute image from the qcow2 blob. For this
*aliyun-img-utils image create* is available.
Example:
```shell
$ aliyun-img-utils image create --image-name SLES15-SP2-BYOS --image-description "Test image" --platform SUSE --blob-name SLES15-SP2-BYOS.qcow2
```
In this example the qcow2 blob will be used to create the compute image.
for the given profile and the blob will be named test.qcow2. If you want to
override the default (20GB) root disk size there is a *--disk-size* option.
For more information about the image create function see the help message:
```shell
$ aliyun-img-utils image create --help
```
## Replicate (copy) image
Once an image is created in a single region it can be replicated or copied to any other region: *aliyun-img-utils image replicate*.
Example:
```shell
$ aliyun-img-utils image replicate --image-name test-image-v20210303 --regions cn-shanghai
```
In this example the image will be replicated to the cn-shanghai region. If
no regions are provided the image will be replicated to all available regions.
For more information about the image replicate function see the help message:
```shell
$ aliyun-img-utils image replicate --help
```
## Publish image
The image can then be published or shared to other accounts with
*aliyun-img-utils image publish*.
Example:
```shell
$ aliyun-img-utils image publish --image-name test-image-v20210303 --launch-permission EXAMPLE
```
In this example the launch permission for the image will be set to *EXAMPLE*. If
no regions are provided the image will be published in all available regions.
For more information about the image publish function see the help message:
```shell
$ aliyun-img-utils image publish --help
```
## Deprecate image
An image can be set to the deprecated state with *aliyun-img-utils image deprecate*.
Example:
```shell
$ aliyun-img-utils image deprecate --image-name test-image-v20210303
```
As with the other commands, if no regions are provided the image will be deprecated
in all available regions.
For more information about the image deprecate function see the help message:
```shell
$ aliyun-img-utils image deprecate --help
```
## Activate image
An image can be set back to the active state with *aliyun-img-utils image activate*.
Example:
```shell
$ aliyun-img-utils image activate --image-name test-image-v20210303
```
As with the other commands, if no regions are provided the image will be activated
in all available regions.
For more information about the image activate function see the help message:
```shell
$ aliyun-img-utils image activate --help
```
## Get image info
Info about a specific compute image can be retrieved with
*aliyun-img-utils image info*.
Example:
```shell
$ aliyun-img-utils image info --image-name test-image-v20210303
```
The image can be searched by the *--image-name* or *--image-id*. By
default only active images will be searched. To filter deprecated images
there is a *--deprecated* option.
For more information about the image info function see the help message:
```shell
$ aliyun-img-utils image info --help
```
## Delete image
A compute image can be deleted with *aliyun-img-utils image delete*.
Example:
```shell
$ aliyun-img-utils image delete --image-name test-image-v20210303
```
As with the other commands, if no regions are provided the image will be
deleted in all available regions.
For more information about the image delete function see the help message:
```shell
$ aliyun-img-utils image delete --help
```
# API
The AliyunImage class can be instantiated and used as an API from code.
This provides all the same functions as the CLI with a few additional
helpers. For example there are waiter functions which will wait for
a compute image to be created and/or deleted.
To create an instance of AliyunImage you need an *access_key*,
*access_secret*, *region* and *bucket_name*. optionally you can pass
in a Python log object and/or a *log_level*.
```python
aliyun_image = AliyunImage(
access_key,
access_secret,
region,
bucket_name,
log_level=log_level,
log_callback=logger
)
```
## Code examples
With an instance of AliyunImage you can perform any of the image functions
which are available through the CLI.
```python
aliyun_image = AliyunImage(
'accessKEY',
'superSECRET',
'cn-beijing',
'images
)
# Upload image blob
blob_name = aliyun_image.upload_image_tarball('/path/to/image.qcow2')
# Create compute image
image_id = aliyun_image.create_compute_image(
'test-image-v20220202',
'A great image to use.',
'test_image.qcow2',
'SUSE'
)
# Delete compute image
# Deletes the image from the current region
deleted = aliyun_image.delete_compute_image('test-image-v20220202')
# Delete compute image in all available regions
aliyun_image.delete_compute_image_in_regions('test-image-v20220202')
# Delete storage blob from current bucket
deleted = aliyun_image.delete_storage_blob('test_image.qcow2')
# Copy image to a single region
image_id = aliyun_image.copy_compute_image(
'test-image-v20220202',
'cn-shanghai'
)
# Replicate (copy) image to all available regions
# A dictionary mapping region names to image ids is returned.
images = aliyun_image.replicate_image('test-image-v20220202')
# Publish image in current region
aliyun_image.publish_image('test-image-v20220202', 'EXAMPLE_PERMISSION')
# Publish image in all available regions
aliyun_image.publish_image_to_regions(
'test-image-v20220202',
'EXAMPLE_PERMISSION'
)
# Deprecate image in current region
aliyun_image.deprecate_image('test-image-v20220202')
# Deprecate image in all available regions
aliyun_image.deprecate_image_in_regions('test-image-v20220202')
# Activate image in current region
aliyun_image.activate_image('test-image-v20220202')
# Activate image in all available regions
aliyun_image.activate_image_in_regions('test-image-v20220202')
# Wait for image to become available based on image id
aliyun_image.wait_on_compute_image('i-123456789')
# Wait for image to be deleted based on image id
aliyun_image.wait_on_compute_image_delete('i-123456789')
# Return True if the image exists based on image name
exists = aliyun_image.image_exists('test-image-v20220202')
#
exists = aliyun_image.image_tarball_exists('test_image.qcow2')
# Get image info as a dictionary
image_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')
# Get a list of available regions
regions = aliyun_image.get_regions()
```
The current *region* or *bucket_name* can be changed at any time.
When the *bucket_name* is changed the current *bucket_client* session
is closed. The session will reconnect in a lazy fashion on the next
storage operation.
```python
aliyun_image = AliyunImage(
'accessKEY',
'superSECRET',
'cn-beijing',
'images
)
exists = aliyun_image.image_tarball_exists('test_image.qcow2')
# Resets the storage bucket client
aliyun_image.bucket_name = 'old-images'
# Storage bucket client connects to the new bucket lazily
exists = aliyun_image.image_tarball_exists('test_image.qcow2')
```
Similarly when the *region* is changed both the *bucket_client* and
the *compute_client* sessions are closed.
```python
aliyun_image = AliyunImage(
'accessKEY',
'superSECRET',
'cn-beijing',
'images
)
image_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')
# Resets the compute client
aliyun_image.region = 'cn-shanghai'
# Compute client connects to the new region lazily
image_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')
```
# Issues/Enhancements
Please submit issues and requests to
[Github](https://github.com/SUSE-Enceladus/aliyun-img-utils/issues).
# Contributing
Contributions to **aliyun-img-utils** are welcome and encouraged. See
[CONTRIBUTING](https://github.com/SUSE-Enceladus/aliyun-img-utils/blob/master/CONTRIBUTING.md)
for info on getting started.
# License
Copyright (c) 2021 SUSE LLC.
Distributed under the terms of GPL-3.0+ license, see
[LICENSE](https://github.com/SUSE-Enceladus/aliyun-img-utils/blob/master/LICENSE)
for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/SUSE-Enceladus/aliyun-img-utils",
"name": "aliyun-img-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "aliyun-img-utils aliyun_img_utils",
"author": "SUSE",
"author_email": "public-cloud-dev@susecloud.net",
"download_url": "https://files.pythonhosted.org/packages/75/bf/f5349a35d0d80b3781fb6c4a0ed803de4d58a42717f04ca364d30316f39b/aliyun_img_utils-2.2.0.tar.gz",
"platform": null,
"description": "# Overview\n\n**aliyun-img-utils** provides a command line utility and API for publishing\nimages in the Aliyun Cloud. This includes helper functions for uploading\nimage blobs, creating compute images and replicating/publishing/deprecating/\nimages across all available regions.\n\nSee the [Alibaba docs](https://www.alibabacloud.com/getting-started) to get\nmore info on the Aliyun cloud.\n\n# Requirements\n\n- oss2\n- Click\n- PyYAML\n- aliyun-python-sdk-core\n- aliyun-python-sdk-ecs\n\n# Installation\n\nTo install the package on openSUSE and SLES use the following commands as root:\n\n```shell\n$ zypper ar http://download.opensuse.org/repositories/Cloud:/Tools/<distribution>\n$ zypper refresh\n$ zypper in python3-aliyun-img-utils\n```\n\nTo install from PyPI:\n\n```shell\n$ pip install aliyun-img-utils\n```\n\n# Configuration\n\n**aliyun-img-utils** can be configured with yaml based profiles. The configuration\ndirectory is `~/.config/aliyun_img_utils` and the default profile is default.yaml\n(~/.config/aliyun_img_utils/default.yaml).\n\nThe following configration options are available in a configuration profile:\n\n- no_color\n- log_level\n- region\n- access_key\n- access_secret\n- bucket_name\n\nAn example configuration profile may look like:\n\n```yaml\nregion: cn-beijing\naccess_key: FakeKEY\naccess_secret: FAKESecret\nbucket_name: smarlow-testing\n```\n\nWhen running any command the profile can be chosen via the *--profile* option.\nFor example, *aliyun-img-utils image upload --profile production* would pull\nconfiguration from ~/.config/aliyun_img_utils/production.yaml.\n\n# CLI\n\nThe CLI is broken into multiple distinct subcommands that handle different\nsteps of creating and publishing images in the Aliyun cloud framework.\n\n## Image blob upload\n\nThe first step is to upload a qcow2 image to a storage bucket. For this\n*aliyun-img-utils image upload* is available.\n\nExample:\n\n```shell\n$ aliyun-img-utils image upload --image-file ~/Documents/test.qcow2\n```\n\nIn this example the qcow2 file will be uploaded to the storage bucket configured\nfor the given profile and the blob will be named test.qcow2. If you want to\noverride the name of the blob there is a *--blob-name* option.\n\nFor more information about the image upload function see the help message:\n\n```shell\n$ aliyun-img-utils image upload --help\n```\n\n## Compute image create\n\nThe next step is to create a compute image from the qcow2 blob. For this\n*aliyun-img-utils image create* is available.\n\nExample:\n\n```shell\n$ aliyun-img-utils image create --image-name SLES15-SP2-BYOS --image-description \"Test image\" --platform SUSE --blob-name SLES15-SP2-BYOS.qcow2\n```\n\nIn this example the qcow2 blob will be used to create the compute image.\nfor the given profile and the blob will be named test.qcow2. If you want to\noverride the default (20GB) root disk size there is a *--disk-size* option.\n\nFor more information about the image create function see the help message:\n\n```shell\n$ aliyun-img-utils image create --help\n```\n\n## Replicate (copy) image\n\nOnce an image is created in a single region it can be replicated or copied to any other region: *aliyun-img-utils image replicate*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image replicate --image-name test-image-v20210303 --regions cn-shanghai\n```\n\nIn this example the image will be replicated to the cn-shanghai region. If\nno regions are provided the image will be replicated to all available regions.\n\nFor more information about the image replicate function see the help message:\n\n```shell\n$ aliyun-img-utils image replicate --help\n```\n\n## Publish image\n\nThe image can then be published or shared to other accounts with\n*aliyun-img-utils image publish*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image publish --image-name test-image-v20210303 --launch-permission EXAMPLE\n```\n\nIn this example the launch permission for the image will be set to *EXAMPLE*. If\nno regions are provided the image will be published in all available regions.\n\nFor more information about the image publish function see the help message:\n\n```shell\n$ aliyun-img-utils image publish --help\n```\n\n## Deprecate image\n\nAn image can be set to the deprecated state with *aliyun-img-utils image deprecate*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image deprecate --image-name test-image-v20210303\n```\n\nAs with the other commands, if no regions are provided the image will be deprecated\nin all available regions.\n\nFor more information about the image deprecate function see the help message:\n\n```shell\n$ aliyun-img-utils image deprecate --help\n```\n\n## Activate image\n\nAn image can be set back to the active state with *aliyun-img-utils image activate*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image activate --image-name test-image-v20210303\n```\n\nAs with the other commands, if no regions are provided the image will be activated\nin all available regions.\n\nFor more information about the image activate function see the help message:\n\n```shell\n$ aliyun-img-utils image activate --help\n```\n\n## Get image info\n\nInfo about a specific compute image can be retrieved with\n*aliyun-img-utils image info*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image info --image-name test-image-v20210303\n```\n\nThe image can be searched by the *--image-name* or *--image-id*. By\ndefault only active images will be searched. To filter deprecated images\nthere is a *--deprecated* option.\n\nFor more information about the image info function see the help message:\n\n```shell\n$ aliyun-img-utils image info --help\n```\n\n## Delete image\n\nA compute image can be deleted with *aliyun-img-utils image delete*.\n\nExample:\n\n```shell\n$ aliyun-img-utils image delete --image-name test-image-v20210303\n```\n\nAs with the other commands, if no regions are provided the image will be\ndeleted in all available regions.\n\nFor more information about the image delete function see the help message:\n\n```shell\n$ aliyun-img-utils image delete --help\n```\n\n# API\n\nThe AliyunImage class can be instantiated and used as an API from code.\nThis provides all the same functions as the CLI with a few additional\nhelpers. For example there are waiter functions which will wait for\na compute image to be created and/or deleted.\n\nTo create an instance of AliyunImage you need an *access_key*,\n*access_secret*, *region* and *bucket_name*. optionally you can pass\nin a Python log object and/or a *log_level*.\n\n```python\naliyun_image = AliyunImage(\n access_key,\n access_secret,\n region,\n bucket_name,\n log_level=log_level,\n log_callback=logger\n)\n```\n\n## Code examples\n\nWith an instance of AliyunImage you can perform any of the image functions\nwhich are available through the CLI.\n\n```python\naliyun_image = AliyunImage(\n 'accessKEY',\n 'superSECRET',\n 'cn-beijing',\n 'images\n)\n\n# Upload image blob\nblob_name = aliyun_image.upload_image_tarball('/path/to/image.qcow2')\n\n# Create compute image\nimage_id = aliyun_image.create_compute_image(\n 'test-image-v20220202',\n 'A great image to use.',\n 'test_image.qcow2',\n 'SUSE'\n)\n\n# Delete compute image\n# Deletes the image from the current region\ndeleted = aliyun_image.delete_compute_image('test-image-v20220202')\n\n# Delete compute image in all available regions\naliyun_image.delete_compute_image_in_regions('test-image-v20220202')\n\n# Delete storage blob from current bucket\ndeleted = aliyun_image.delete_storage_blob('test_image.qcow2')\n\n# Copy image to a single region\nimage_id = aliyun_image.copy_compute_image(\n 'test-image-v20220202',\n 'cn-shanghai'\n)\n\n# Replicate (copy) image to all available regions\n# A dictionary mapping region names to image ids is returned.\nimages = aliyun_image.replicate_image('test-image-v20220202')\n\n# Publish image in current region\naliyun_image.publish_image('test-image-v20220202', 'EXAMPLE_PERMISSION')\n\n# Publish image in all available regions\naliyun_image.publish_image_to_regions(\n 'test-image-v20220202',\n 'EXAMPLE_PERMISSION'\n)\n\n# Deprecate image in current region\naliyun_image.deprecate_image('test-image-v20220202')\n\n# Deprecate image in all available regions\naliyun_image.deprecate_image_in_regions('test-image-v20220202')\n\n# Activate image in current region\naliyun_image.activate_image('test-image-v20220202')\n\n# Activate image in all available regions\naliyun_image.activate_image_in_regions('test-image-v20220202')\n\n# Wait for image to become available based on image id\naliyun_image.wait_on_compute_image('i-123456789')\n\n# Wait for image to be deleted based on image id\naliyun_image.wait_on_compute_image_delete('i-123456789')\n\n# Return True if the image exists based on image name\nexists = aliyun_image.image_exists('test-image-v20220202')\n\n# \nexists = aliyun_image.image_tarball_exists('test_image.qcow2')\n\n# Get image info as a dictionary\nimage_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')\n\n# Get a list of available regions\nregions = aliyun_image.get_regions()\n```\n\nThe current *region* or *bucket_name* can be changed at any time.\n\nWhen the *bucket_name* is changed the current *bucket_client* session\nis closed. The session will reconnect in a lazy fashion on the next\nstorage operation.\n\n```python\naliyun_image = AliyunImage(\n 'accessKEY',\n 'superSECRET',\n 'cn-beijing',\n 'images\n)\nexists = aliyun_image.image_tarball_exists('test_image.qcow2')\n\n# Resets the storage bucket client\naliyun_image.bucket_name = 'old-images'\n\n# Storage bucket client connects to the new bucket lazily\nexists = aliyun_image.image_tarball_exists('test_image.qcow2')\n```\n\nSimilarly when the *region* is changed both the *bucket_client* and\nthe *compute_client* sessions are closed.\n\n```python\naliyun_image = AliyunImage(\n 'accessKEY',\n 'superSECRET',\n 'cn-beijing',\n 'images\n)\nimage_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')\n\n# Resets the compute client\naliyun_image.region = 'cn-shanghai'\n\n# Compute client connects to the new region lazily\nimage_info = aliyun_image.get_compute_image(image_name='test_image.qcow2')\n```\n\n# Issues/Enhancements\n\nPlease submit issues and requests to\n[Github](https://github.com/SUSE-Enceladus/aliyun-img-utils/issues).\n\n# Contributing\n\nContributions to **aliyun-img-utils** are welcome and encouraged. See\n[CONTRIBUTING](https://github.com/SUSE-Enceladus/aliyun-img-utils/blob/master/CONTRIBUTING.md)\nfor info on getting started.\n\n# License\n\nCopyright (c) 2021 SUSE LLC.\n\nDistributed under the terms of GPL-3.0+ license, see\n[LICENSE](https://github.com/SUSE-Enceladus/aliyun-img-utils/blob/master/LICENSE)\nfor details.\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Package that provides utilities for handling images in Aliyun Cloud.",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/SUSE-Enceladus/aliyun-img-utils"
},
"split_keywords": [
"aliyun-img-utils",
"aliyun_img_utils"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9501f2cfc8d580d5d32750a6cc84677b82c95e2a753d8695371efd81de73772b",
"md5": "1b3f4406d080e303741aaf5f5f42ac72",
"sha256": "1aeaa678d3f5968e676d00619e5d6f98b5acf972ee048985adbd8f9270829370"
},
"downloads": -1,
"filename": "aliyun_img_utils-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b3f4406d080e303741aaf5f5f42ac72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29797,
"upload_time": "2024-05-28T19:13:35",
"upload_time_iso_8601": "2024-05-28T19:13:35.734483Z",
"url": "https://files.pythonhosted.org/packages/95/01/f2cfc8d580d5d32750a6cc84677b82c95e2a753d8695371efd81de73772b/aliyun_img_utils-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75bff5349a35d0d80b3781fb6c4a0ed803de4d58a42717f04ca364d30316f39b",
"md5": "b8d3fb2493d617692720f88786576965",
"sha256": "c3d00518de9dc2c58de98826e71927b28ace16714dbe440b2cc3c0c00f1ee767"
},
"downloads": -1,
"filename": "aliyun_img_utils-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b8d3fb2493d617692720f88786576965",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35242,
"upload_time": "2024-05-28T19:13:38",
"upload_time_iso_8601": "2024-05-28T19:13:38.918664Z",
"url": "https://files.pythonhosted.org/packages/75/bf/f5349a35d0d80b3781fb6c4a0ed803de4d58a42717f04ca364d30316f39b/aliyun_img_utils-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-28 19:13:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SUSE-Enceladus",
"github_project": "aliyun-img-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "aliyun-img-utils"
}
JSON
