azure-img-utils 2.3.0

Description:

azureimgutils 2.3.0

Overview
azure-img-utils provides a command line utility and API for publishing
images in the Azure Cloud. This includes helper functions for uploading
image blobs, creating compute images and publish/share images across
all available regions.
See the Azure docs to get
more info on the Azure cloud.
Requirements
The requirements for the project can be found in the following repo files:

requirements
requirements for testing
requirements for development

Installation
To install the package on openSUSE and SLES use the following commands as root:
# zypper ar https://download.opensuse.org/repositories/Cloud:Tools:CI/<distribution>
# zypper refresh
# zypper in python3-azure-img-utils

To install from PyPI:
$ pip install azure-img-utils

Configuration
azure-img-utils can be configured with yaml based profiles. The configuration
directory is ~/.config/azure_img_utils and the default profile is default.yaml
(~/.config/azure_img_utils/default.yaml).
The following configration options are available in a configuration profile:

no_color
log_level
credentials_file
resource_group
region
container
storage_account

An example configuration profile may look like:
region: westus
no_color: True
credentials_file: mycredentials.json
container: my_container

When running any command the profile can be chosen via the --profile option.
For example, azure-img-utils image blobexists --profile production would pull
configuration from ~/.config/azure_img_utils/production.yaml.
CLI
The CLI is broken into multiple distinct subcommands that handle different
steps of creating and publishing images in the Azure cloud framework.
Authentication
This cli tool expects the user to provide a json file containing the
credentials of a service principal to access his/her Azure services.
Per Azure documentation:

An Azure service principal is an identity created for use with applications,
hosted services, and automated tools to access Azure resources.

Here
you can find how to create a service principal with the azure cli.
With your subscriptionId, the resourceGroupId and the required permissions, you can
create the service principal with the following command:
az ad sp create-for-rbac \
--sdk-auth \
--role Contributor \
--scopes /subscriptions/{YOUR_SUSCRI_ID}/resourceGroups/{YOUR_RES_GROUP_ID} \
--name "YOUR_SP_NAME" > mycredentials.json

The expected format for the json file is the output for that create-for-rbac az
command. Note that the API this repo provides allows additional methods of
authentication, but these are not supported in this CLI tool.
blob command
Group of commands for blob management.
exists subcommand
This subcommand allows the user to check if a blob exists in the storage
container specified. The subcommand is azure-img-utils blob exists.
The required parameters for the execution of the command (authentication
aside):

--storage-account
--blob-name
--container

Example:
$ azure-img-utils blob exists --storage-account myStorageAccount \
--blob-name myBlobName \
--container myContainerName

This command will output true or false depending on the existence of the
blob.
For more information about the blob exists command see the help message:
$ azure-img-utils blob exists --help

upload subcommand
This subcommand allows the user to upload a file as a blob to the storage
container specified. The subcommand is azure-img-utils blob upload.
The required parameters for the execution of the command (authentication
aside):

--storage-account
--blob-name
--container
--image-file

Some optional parameters for the execution of the command include:

--force-replace-image (defaults to False)
--page-blob (defaults to False)
--expand-image (defaults to False)
--max-workers (defaults to 5(no limit))
--max-attempts (defaults to 5(no limit))

Example:
$ azure-img-utils blob upload --storage-account myStorageAccount \
--blob-name myBlobName \
--container myContainerName \
--image-file myImageFile.qcow2

This command will output if the upload has been successful or not.
For more information about the blob upload command see the help message:
$ azure-img-utils blob upload --help

delete subcommand
This subcommand allows the user to delete a blob file from the storage
container specified. The subcommand is azure-img-utils blob delete.
The required parameters for the execution of the command (authentication
aside):

--storage-account
--blob-name
--container

Some optional parameters for the execution of the command:

--yes (avoids interactive confirmation for the deletion)

Example:
$ azure-img-utils blob delete --storage-account myStorageAccount \
--blob-name myBlobName \
--container myContainerName \
--yes

This command will output if the deletion has been successful or not.
For more information about the blob delete command see the help message:
$ azure-img-utils blob delete --help

image command
Group of commands for image management.
exists subcommand
This subcommand allows the user to check if an image exists.
The subcommand is azure-img-utils image exists.
The required parameters for the execution of the command (authentication
aside):

--image-name

Example:
$ azure-img-utils image exists --image-name myImageName

This command will output true or false depending on the existence of the
image.
For more information about the image exists command see the help message:
$ azure-img-utils image exists --help

create subcommand
This subcommand allows the user to create an image based in one blob.
The subcommand is azure-img-utils image create.
The required parameters for the execution of the command (authentication
aside):

--blob-name
--image-name
--container
--resource-group
--storage-account

Some optional parameters for the execution of the command include:

--force-replace-image (defaults to False)
--hyper-v-generation (defaults to 'V1'(legacy bios).)
(Use 'V2' for uefi boot.)

Example:
$ azure-img-utils image create --blob-name myBlobName \
--image-name myImageName

For more information about the image create command see the help message:
$ azure-img-utils image create --help

delete subcommand
This subcommand allows the user to delete an existing image.
The subcommand is azure-img-utils image delete.
The required parameters for the execution of the command (authentication
aside):

--image-name

Example:
$ azure-img-utils image delete --image-name myImageName

For more information about the image delete command see the help message:
$ azure-img-utils image delete --help

gallery-image-version command
Group of commands for gallery image version management.
exists subcommand
This subcommand allows the user to check if a gallery image version exists in a
gallery.
The subcommand is azure-img-utils gallery-image-version exists.
The required parameters for the execution of the command (authentication
aside):

--gallery-image-name
--gallery-name
--gallery-image-version

Example:
$ azure-img-utils gallery-image-version exists \
--gallery-image-name myImageName \
--gallery-name myGalleryName \
--gallery-image-version 0.0.1

This command will output true or false depending on the existence of the
gallery image version in the gallery.
For more information about the gallery image version exists command see the
help message:
$ azure-img-utils gallery-image-version exists --help

create subcommand
This subcommand allows the user to create a gallery image version in a gallery based
on a blob.
The subcommand is azure-img-utils gallery-image-version create.
The required parameters for the execution of the command (authentication
aside):

--blob-name
--gallery-name
--gallery-image-name
--gallery-image-version
--resource-group

Some optional parameters for the execution of the command include:

--force-replace-image (defaults to False)

Example:
$ azure-img-utils gallery-image-version create \
--blob-name myBlobName \
--gallery-image-name myImageName \
--gallery-name myGalleryName \
--image-version 0.0.1 \
--resource-group myResourceGroup

For more information about the gallery image version create command see the help
message:
$ azure-img-utils gallery-image-version create --help

delete subcommand
This subcommand allows the user to delete an existing gallery image version of
a gallery image.
The subcommand is azure-img-utils gallery-image-version delete.
The required parameters for the execution of the command (authentication
aside):

--gallery-name
--gallery-image-name
--gallery-image-version

Example:
$ azure-img-utils gallery-image-version delete \
--gallery-image-name myImageName \
--gallery-name myGalleryName \
--gallery-image-version 0.0.1

For more information about the gallery image version delete command see the
help message:
$ azure-img-utils gallery-image-version delete --help

cloud-partner-offer command
Group of commands for cloud partner offer management.
publish subcommand
This subcommand allows the user to publish a cloud partner offer.
The subcommand is azure-img-utils cloud-partner-offer publish.
The required parameters for the execution of the command (authentication
aside):

--offer-id

Example:
$ azure-img-utils cloud-partner-offer publish \
--offer-id myOfferId

This command will output the job id for the published cloud partner offer
operation if successful.
For more information about the cloud partner offer publish command see the
help message:
$ azure-img-utils cloud-partner-offer publish --help

### go-live subcommand

This subcommand allows the user to set a cloud partner offer as go-live.

The subcommand is *azure-img-utils cloud-partner-offer go-live*.

The *required* parameters for the execution of the command (authentication
aside):
- --offer-id

The result of the subcommand is that all new changes made to the offer are
publicly visible.

Example:

```shell
$ azure-img-utils cloud-partner-offer go-live \
--offer-id myOfferId

This command will output the URI for the cloud partner offer go-live operation
if successful.
For more information about the cloud partner offer go-live command see the
help message:
$ azure-img-utils cloud-partner-offer go-live --help

upload-offer-document subcommand
This subcommand allows the user to upload an offer document to a cloud
partner offer.
The subcommand is azure-img-utils cloud-partner-offer upload-offer-document.
The required parameters for the execution of the command (authentication
aside):

--offer-id
--offer-document-file

The '--offer-document-file' parameter has to contain the path for a text file
containing the json document for the offer.
Example:
$ azure-img-utils cloud-partner-offer upload-offer-document \
--offer-id myOfferId \
--offer-document-file /path/to/my/documentfile.json

This command will output only if there's any problem uploading the document for
the offer.
For more information about the cloud partner offer upload-offer-document
command see the help message:
$ azure-img-utils cloud-partner-offer upload-offer-document --help

add-image-to-offer subcommand
This subcommand allows the user to add an image to a cloud partner offer.
The subcommand is azure-img-utils cloud-partner-offer add-image-to-offer.
The required parameters for the execution of the command (authentication
aside):

--blob-name
--image-name
--offer-id
--sku

Some optional parameters for the execution of the command include:

--blob-url (A blob-url is generated if not provided)
--generation-id

Example:
$ azure-img-utils cloud-partner-offer add-image-to-offer \
--blob-name myBlobName \
--image-name myImageName \
--offer-id myOfferId \
--sku mySKU

This command will output only if there's any problem adding the image
to the offer.
For more information about the cloud partner offer add-image-to-offer
command see the help message:
$ azure-img-utils cloud-partner-offer add-image-to-offer --help

remove-image-from-offer subcommand
This subcommand allows the user to remove an image from a cloud partner offer.
The subcommand is azure-img-utils cloud-partner-offer remove-image-from-offer.
The required parameters for the execution of the command (authentication
aside):

--image-urn

Example:
$ azure-img-utils cloud-partner-offer remove-image-to-offer \
--image-urn myImageUrn

This command will output only if there's any problem removing the image
from the offer.
For more information about the cloud partner offer remove-image-from-offer
command see the help message:
$ azure-img-utils cloud-partner-offer remove-image-from-offer --help

API
The AzureImage 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 AzureImage you need a storage_account,
credentials dictionary object or credentials file or sas token
container and resource group. Optionally you can pass
in a Python log object and/or a log_level and/or a timeout value.
Note that you can provide authentication credentials in 3 different ways:

with a sas_token
with a dictionary of credentials containing the required key values
with the credentials file name
Providing just one of these options is enough to perform the authentication
in the Azure API.

azure_image = AzureImage(
container="my_container_name",
storage_account="my_storage_account",
credentials=my_credentials_dict,
credentials_file="my_credentials_file.json",
resource_group="my_resource_group",
sas_token="my_sas_token",
log_level=my_log_level,
log_callback=logger
timeout=myTimeout
)

Code examples
With an instance of AzureImage you can perform any of the image functions
which are available through the CLI.
azure_image = AzureImage(
container="my_container",
storage_account="my_storage_account",
credentials_file="my_credentials.json",
resource_gropu="my_resource_group",
sas_token="my_sas_token"
)

Check if image blob exists
blob_exists = azure_image.image_blob_exists("my_blob_name")

Delete storage blob
blob_deleted = azure_image.delete_storage_blob("my_blob_name")

Upload image blob
blob_name = azure_image.upload_image_blob(
"my_image_file.qcow2",
blob_name="my_blob_name"
)

Check if image exists
image_exists = azure_image.image_exists("my_image_name")

Check if gallery image version exists
gallery_image_version_exists = azure_image.gallery_image_version_exists(
"my_gallery_name",
"my_gallery_image_name",
"my_image_version",
gallery_resource_group="my_gallery_resource_group"
)

Delete compute image
azure_image.delete_compute_image("my_image_name")

Delete gallery image version
azure_image.delete_gallery_image_version(
"my_gallery_name",
"my_gallery_image_name",
"my_image_version",
gallery_resource_group="my_gallery_resource_group"
)

Get compute image dictionary
image_dict = azure_image.get_compute_image("my_image_name")

Get gallery image version
image_dict = azure_image.get_gallery_image_version(
"my_gallery_name",
"my_gallery_image_name",
"my_image_version",
gallery_resource_group="my_gallery_resource_group"
)

Create compute image
image_name = azure_image.create_compute_image(
"my_blob_name",
"my_image_name",
"my_region",
force_replace_image=True,
hyper_v_generation='V1'
)

Create gallery image version
image_name = azure_image.create_gallery_image_version(
"my_blob_name",
"my_gallery_name",
"my_gallery_image_name",
"my_image_version",
"my_region",
force_replace_image=True,
gallery_resource_group="my_gallery_resource_group"
)

Get offer doc dictionary
offer_doc = azure_image.get_offer_doc(
"my_offer_id"
)

Upload offer doc
azure_image.upload_offer_doc(
"my_offer_id",
my_offer_doc_dict
)

Add image to offer
azure_image.add_image_to_offer(
"my_blob_name",
"my_image_name",
"my_offer_id",
"my_sku",
blob_url="https://my.blob.url",
generation_id="my_generation_id"
)

Remove image from offer
azure_image.remove_image_from_offer("my_image_urn")

Publish offer
operation_uri = azure_image.publish_offer(
"my_offer_id"
)

Go live with offer
operation_uri = azure_image.go_live_with_offer(
"my_offer_id"
)

Get offer status
offer_status = azure_image.get_offer_status(
"my_offer_id"
)

Get operation
operation_status = azure_image.get_operation("my_operation")

Issues/Enhancements
Please submit issues and requests to
Github.
Contributing
Contributions to azure-img-utils are welcome and encouraged. See
CONTRIBUTING
for info on getting started.
License
Copyright (c) 2022 SUSE LLC.
Distributed under the terms of GPL-3.0+ license, see
LICENSE
for details.