ec2deprecateimg.1

.\" Process this file with
.\" groff -man -Tascii ec2deprecateimg.1
.\"
.TH ec2deprecateimg 1
.SH NAME
ec2deprecateimg \- Deprecate images in EC2 by adding tags
.SH SYNOPSIS
.B ec2deprecateimg [option]
.SH DESCRIPTION
.B ec2deprecateimg
Deprecate images in EC2 by adding tags to an image and enabling AWS image
deprecation. Image tagging is retained for backwards compatibility. The
tagging mechanism is an implementation based on convention. Tags are not
sticky, i.e. not visible to others if the image is shared.

Images are tagged with:
- Deprecated on     -> provided deprecation date (or today's date if no value
provided) in YYYYMMDD format
- Removal date      -> deprecation date plus the deprecation period specified
- Replacement image -> The AMI ID and name of the replacement image(optional)

In EC2 a deprecated image is set into a state that makes it invisible to
new users. This can be considered equivalent to a deletion. As such the tool
sets the deprecation data in EC2 to the removal date set for the tag.

The image set as the replacement is removed from the list of potential images
to be deprecated before any matching takes place. Therefore, the deprecation
search criteria specified with
.I --image-name-frag
or
.I --image-name-match
cannot match the replacement image.
.SH OPTIONS
.IP "-a --account ACCOUNT_NAME"
Specifies the account to use to connect to EC2. The account is specified
in the config file
.IR ~/.ec2utils.conf.
The account is specified as a section with [account-ACCOUNT_NAME] delimiter.
The options of the sections are:
.IR access_key_id
.IR secret_access_key
.I ssh_key_name
and
.IR ssh_private_key .
This allows the program to connect to EC2.
If the access_key_id and/or secret_access_key are not found in
.IR ~/.ec2utils.conf,
the search will use the ACCOUNT_NAME to look for a matching section
[profile ACCOUNT_NAME] in
.IR ~/.aws/config
or [ACCOUNT_NAME] in
.IR ~/.aws/credentials.
.IP "--access-id AWS_ACCESS_KEY"
Specifies the AWS access key and overrides the value given for the
.I account
with the
.I access_key_id
in the configuration file.
.IP "--deprecation-date YYYYMMDD"
Specifies the date when the image is considered deprecated. This parameter is
optional and if it's not provided it will default to the date on which the
program is executed.
.IP "-d --deprecation-period NUMBER_OF_MONTHS"
Specifies the number of months this image will be considered deprecated. After
the deprecation period expires the image may be removed. The deprecation time
is added to the deprecation date and forms the value for the
.I Removal date
tag in the format
.I YYYYMMDD.
The default deprecation period is 6 months. 
.IP "--force"
Specify that any images that have already been tagged as deprecated should be
tagged again with the new deprecation information. This overwrites the
previous information and the old data is lost.
.IP "-n --dry-run"
The program will not perform any action. It will provide information on
.I stdout
about the actions it would perform.
.IP "-f --file CONFIG_FILE"
Specifies the configuration file to use. The default is
.IR ~/.ec2utils.conf .
.IP "--image-id AMI_ID"
Specify the AMI ID of the image to be marked as deprecated. This option is
mutually exclusive with the
.IR --image-name ,
.IR --image-name-frag ,
and
.IR --image-name-match .
.IP "--image-name IMAGE_NAME"
Specify the name of the image to be deprecated. The program will look for
an exact match of the name. This option is mutually exclusive with
.IR --image-id ,
.IR --image-name-frag ,
and
.IR --image-name-match .
.IP "--image-name-frag IMAGE_NAME_FRAGMENT"
Specify a section of an image name for the image(s) to be deprecated. Every
image that matches the name fragment will be marked as deprecated. This
option is mutually exclusive with
.IR --image-id ,
.IR --image-name-name ,
and
.IR --image-name-match .
.IP "--image-name-match REGEX"
Specify a regular expression to match an image name. Every image matching the
regular expression will be deprecated. This option is mutually
exclusive with
.IR --image-id ,
.IR --image-name-name ,
and
.IR --image-name-frag .
.IP "--image-virt-type hvm|para"
Specify the virtualization type of the image to be deprecated. This option
works in addition to
.IR --image-id ,
.IR --image-name ,
.IR --image-name-frag ,
.IR --image-name-match .
Every specified condition must be satisfied in order to deprecate the image.
.IP "--public-only"
Consider only images that are public as a replacement or for deprecation
purposes.
.IP "--replacement-id AMI_ID"
Specify the AMI ID of the image considered to be the replacement for the
image(s) that are being deprecated. The option is mutually exclusive
with
.IR --replacement-name ,
.IR --replacement-name-frag ,
and 
.IR --replacement-name-match .
The AMI ID and the dynamically determined image name are used in
combination to form the value for the
.I Replacement image
tag in the form
.I AMI_ID -- IMAGE_NAME.
One of
.IR --replacement-id ,
.IR --replacement-name ,
.IR --replacement-name-frag ,
or
.IR --replacement-name-match ,
can be specified(optional).
.IP "--replacement-name IMAGE_NAME"
Specify the name of the image considered to be the replacement for the
image(s) that are being deprecated. The option is mutually exclusive
with the
.I --replacement-id
option. The image name and the dynamically determined AMI ID are used in
combination to form the value for the
.I Replacement image
tag in the form
.I AMI_ID -- IMAGE_NAME.
One of
.IR --replacement-id ,
.IR --replacement-name ,
.IR --replacement-name-frag ,
or
.IR --replacement-name-match ,
can be specified(optional).
.IP "--replacement-name-frag IMAGE_NAME_FRAGMENT"
Specify a section of an image name to be considered for the replacement
image. This option is mutually exclusive with
.IR --replacement-id ,
.IR --replacement-name ,
and 
.IR --replacement-name-match .
The dynamically determined AMI ID and the dynamically determined
image name are used in combination to form the value for the
.I Replacement image
tag in the form
.I AMI_ID -- IMAGE_NAME.
One of
.IR --replacement-id ,
.IR --replacement-name ,
.IR --replacement-name-frag ,
or
.IR --replacement-name-match ,
can be specified(optional).
.IP "--replacement-name-match REGEX"
Specify a regular expression to match an image name to be considered for
the replacement image. This option is mutually exclusive with
.IR --replacement-id ,
.IR --replacement-name ,
and
.IR --replacement-name-frag .
 The dynamically determined AMI ID and the dynamically determined image name
are used in combination to form the value for the
.I Replacement image
tag in the form
.I AMI_ID -- IMAGE_NAME.
One of
.IR --replacement-id ,
.IR --replacement-name ,
.IR --replacement-name-frag ,
or
.IR --replacement-name-match ,
can be specified(optional).
.IP "-r --regions EC2_REGIONS"
A comma separated list of Amazon EC2 regions, or a single region. If no
region argument is specified all EC2 connected regions will be processed.
EC2 disconnected regions have different API keys and thus the specified
.I account
would not work with the disconnected regions. If a disconnected region is to
be processed specify the region explicitly on the command line, and only the
region of interest along with the matching
.IR account .
.IP "-s --secret-key AWS_SECRET_KEY"
Specifies the AWS secret access key and overrides the value given for the
.I account
with the
.I secret_access_key
in the configuration file.
.IP "--verbose"
Print extra output about the operations performed to STDOUT.
.IP "--version"
Print the version of he program
.SH EXAMPLE
ec2deprecateimg --account example --image-name-match v15 --image-virt-type hvm --replacement-name exampleimage_v16

Will mark all images in all connected regions that have the
.I HVM
virtualization type and match the
.I v15
regular expression as deprecated. The replacement image will be set to the
AMI ID found in the region being processed that matches the
.I exampleimage_v16
name exactly.
.SH AUTHOR
SUSE Public Cloud Team