Reference for the API¶

If in doubt, use the high level API. This should work well for most of the use cases.

High-level API¶

awspub.cleanup(config: Path, config_mapping: Path, group: str | None)¶

Cleanup available images in the partition of the used account based on the given configuration file

Parameters:

config (pathlib.Path) – the configuration file path
config_mapping (pathlib.Path) – the config template mapping file path
group (Optional[str]) – only handles images from given group

awspub.create(config: Path, config_mapping: Path, group: str | None) → Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, Dict[str, str]]]]¶

Create images in the partition of the used account based on the given configuration file and the config mapping

Parameters:

config (pathlib.Path) – the configuration file path
config_mapping (pathlib.Path) – the config template mapping file path
group (Optional[str]) – only handles images from given group

Returns:

the images grouped by name and by group

Return type:

Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, Dict[str, str]]]

awspub.list(config: Path, config_mapping: Path, group: str | None) → Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, Dict[str, str]]]]¶

List images in the partition of the used account based on the given configuration file and the config mapping

Parameters:

config (pathlib.Path) – the configuration file path
config_mapping (pathlib.Path) – the config template mapping file path
group (Optional[str]) – only handles images from given group

Returns:

the images grouped by name and by group

Return type:

Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, Dict[str, str]]]

awspub.publish(config: Path, config_mapping: Path, group: str | None)¶

Make available images in the partition of the used account based on the given configuration file public

Parameters:

config (pathlib.Path) – the configuration file path
config_mapping (pathlib.Path) – the config template mapping file path
group (Optional[str]) – only handles images from given group

awspub.verify(config: Path, config_mapping: Path, group: str | None) → Dict[str, Dict]¶

Verify available images in the partition of the used account based on the given configuration file. This is EXPERIMENTAL and doesn’t work reliable yet!

Parameters:

config (pathlib.Path) – the configuration file path
config_mapping (pathlib.Path) – the config template mapping file path
group (Optional[str]) – only handles images from given group

Low-level API¶

class awspub.context.Context(conf_path: Path, conf_template_mapping_path: Path)¶

Context holds the used configuration and some automatically calculated values

property source_sha256¶: The sha256 sum hexdigest of the source->path value from the given configuration. This value is used in different places (eg. to automatically upload to S3 with this value as key)

property tags¶: Helper to make tags directly usable by the AWS EC2 API which requires a list of dicts with “Key” and “Value” defined.

property tags_dict: Dict[str, str]¶: Common tags which will be used for all AWS resources This includes tags defined in the configuration file but doesn’t include image group specific tags. Usually the tags() method should be used.

class awspub.s3.S3(context: Context)¶

Handle S3 API interaction

upload_file(source_path: str)¶

Upload a given file to the bucket from context. The key name will be the sha256sum hexdigest of the file. If a file with that name already exist in the given bucket and the calculated sha256sum matches the sha256sum from S3, nothing will be uploaded. Instead the existing file will be used. This method does use a multipart upload internally so an upload can be retriggered in case of errors and the previously uploaded content will be reused. Note: be aware that failed multipart uploads are not deleted. So it’s recommended to setup a bucket lifecycle rule to delete incomplete multipart uploads. See https://docs.aws.amazon.com/AmazonS3/latest/userguide//mpu-abort-incomplete-mpu-lifecycle-config.html

Parameters:: source_path (str) – the path to the local file to upload (usually a .vmdk file)

class awspub.snapshot.Snapshot(context: Context)¶

Handle EC2 Snapshot API interaction

copy(snapshot_name: str, source_region: str, destination_regions: List[str]) → Dict[str, str]¶

Copy a snapshot to multiple regions

Parameters:

snapshot_name (str) – the Snapshot name to copy
source_region (str) – a region to copy the snapshot from
destination_regions – a list of regions to copy the snaphot to

Returns:

a dict with region/snapshot-id mapping for the newly copied snapshots

Return type:

Dict[str, str] where the key is a region name and the value a snapshot-id

create(ec2client: EC2Client, snapshot_name: str) → str¶

Create a EC2 snapshot with the given name If the snapshot already exists, just return the snapshot-id for the existing snapshot.

Parameters:

ec2client (EC2Client) – EC2 client for a specific region
snapshot_name (str) – the Snapshot name

Returns:

a snapshot-id

Return type:

str

class awspub.image.Image(context: Context, image_name: str)¶

Handle EC2 Image/AMI API interaction

cleanup() → None¶

Cleanup/delete the temporary images

If an image is marked as “temporary” in the configuration, do delete that image in all regions. Note: if a temporary image is public, it won’t be deleted. A temporary image should never be public Note: the underlying snapshot is currently not deleted. That might change in the future

property conf: Dict[str, Any]¶: The configuration for the current image (based on “image_name”) from context

create() → Dict[str, _ImageInfo]¶

Get or create a image based on the available configuration

Returns:: a Dict with region names as keys and _ImageInfo objects as values
Return type:: Dict[str, _ImageInfo]

property image_name: str¶: Get the image name

property image_regions: List[str]¶: Get the image regions. Either configured in the image configuration or all available regions. If a region is listed that is not available in the currently used partition, that region will be ignored (eg. having us-east-1 configured but running in the aws-cn partition doesn’t include us-east-1 here).

list() → Dict[str, _ImageInfo]¶: Get image based on the available configuration This doesn’t change anything - it just tries to get the available image for the different configured regions :return: a Dict with region names as keys and _ImageInfo objects as values :rtype: Dict[str, _ImageInfo]

publish() → None¶: Handle all publication steps - make image and underlying root device snapshot public if the public flag is set - request a new marketplace version for the image in us-east-1 if the marketplace config is present Note: if the temporary flag is set in the image, this method will do nothing Note: this command doesn’t unpublish anything!

property snapshot_name: str¶

Get the snapshot name which is a sha256 hexdigest

The snapshot name is the sha256 hexdigest of the source file given in the source->path configuration option.

if the “separate_snapshot” config option is set to True, the snapshot name is sha256 hexdigest of the source file given in the source->path conf option and then the sha256 hexdigest of the image-name appended and then the sha256 hexdigest calculated of this concatenated string.

if the “billing_products” config option is set, the snapshot name is sha256 hexdigest of the source file given in the source->path conf option and then the sha256 hexdigest of each entry in the billing_products appended and then the sha256 hexdigest calculated of this concatenated string.

Note that both options (“separate_snapshot” and “billing_products”) can be combined and the snapshot calculation steps would be combined, too.

verify() → Dict[str, List[ImageVerificationErrors]]¶: Verify (but don’t modify or create anything) that the image configuration matches what is on AWS

class awspub.image.ImageVerificationErrors(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶: Possible errors for image verification

class awspub.image_marketplace.ImageMarketplace(context: Context, image_name: str)¶

Handle AWS Marketplace API interaction

property conf: Dict[str, Any]¶: The marketplace configuration for the current image (based on “image_name”) from context

request_new_version(image_id: str) → None¶

Request a new Marketplace version for the given image Id

Parameters:: image_id (str) – an image Id (in the format ‘ami-123’)

Methods used to handle notifications for AWS using SNS

class awspub.sns.SNSNotification(context: Context, image_name: str, region_name: str)¶

A data object that contains validation logic and structuring rules for SNS notification JSON

property conf: List[Dict[str, Any]]¶: The sns configuration for the current image (based on “image_name”) from context

publish() → None¶: send notification to subscribers