repo_zf1/documentation/manual/en/module_specs/Zend_Service_Amazon_Ec2-Image.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.amazon.ec2.images">
    <title>Zend_Service_Amazon_Ec2: Amazon Machine Images (AMI)</title>
    <para>
        Amazon Machine Images (AMIs) are preconfigured with an ever-growing list
        of operating systems.
    </para>

    <sect2 id="zend.service.amazon.ec2.images.info">
        <title>AMI Information Utilities</title>

        <example id="zend.service.amazon.ec2.images.register">
            <title>Register an AMI with EC2</title>
            <para>
                <code>register</code> Each <acronym>AMI</acronym> is associated with an unique ID which
                is provided by the Amazon EC2 service through the RegisterImage
                operation. During registration, Amazon EC2 retrieves the specified
                image manifest from Amazon S3 and verifies that the image is owned by
                the user registering the image.
            </para>
            <para>
                <code>register</code> returns the imageId for the registered Image.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->register('imageLocation');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.deregister">
            <title>Deregister an AMI with EC2</title>
            <para>
                <code>deregister</code>, Deregisters an <acronym>AMI</acronym>. Once deregistered, instances
                of the <acronym>AMI</acronym> can no longer be launched.
            </para>

            <para>
                <code>deregister</code> returns boolean <constant>TRUE</constant> or
                <constant>FALSE</constant>.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->deregister('imageId');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.describe">
            <title>Describe an AMI</title>
            <para>
                <code>describe</code> Returns information about <acronym>AMI</acronym>s, AKIs, and ARIs
                available to the user. Information returned includes image type,
                product codes, architecture, and kernel and <acronym>RAM</acronym> disk IDs. Images
                available to the user include public images available for any user
                to launch, private images owned by the user making the request,
                and private images owned by other users for which the user has
                explicit launch permissions.
            </para>
            <para>
            <table id="zend.service.amazon.ec2.images.describe-table">
                <title>Launch permissions fall into three categories</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><code>public</code></entry>
                            <entry><para>
                                The owner of the <acronym>AMI</acronym> granted launch permissions for the <acronym>AMI</acronym>
                                to the all group. All users have launch permissions for these <constant>AMIs</constant>.
                            </para></entry>
                        </row>
                        <row>
                            <entry><code>explicit</code></entry>
                            <entry><para>
                                The owner of the <acronym>AMI</acronym> granted launch permissions to a specific user.
                            </para></entry>
                        </row>
                        <row>
                            <entry><code>implicit</code></entry>
                            <entry><para>
                                A user has implicit launch permissions for all <constant>AMIs</constant> he or she owns.
                            </para></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            </para>
            <para>
                The list of <acronym>AMI</acronym>s returned can be modified by specifying <acronym>AMI</acronym> IDs, <acronym>AMI</acronym> owners,
                or users with launch permissions. If no options are specified, Amazon EC2 returns
                all <acronym>AMI</acronym>s for which the user has launch permissions.
            </para>
            <para>
                If you specify one or more <acronym>AMI</acronym> IDs, only <acronym>AMI</acronym>s that have the specified IDs are returned.
                If you specify an invalid <acronym>AMI</acronym> ID, a fault is returned. If you specify an <acronym>AMI</acronym> ID for which
                you do not have access, it will not be included in the returned results.
            </para>
            <para>
                If you specify one or more <acronym>AMI</acronym> owners, only <acronym>AMI</acronym>s from the specified owners and for
                which you have access are returned. The results can include the account IDs of the
                specified owners, amazon for <acronym>AMI</acronym>s owned by Amazon or self for <acronym>AMI</acronym>s that you own.
            </para>
            <para>
                If you specify a list of executable users, only users that have launch permissions
                for the <acronym>AMI</acronym>s are returned. You can specify account IDs (if you own the <acronym>AMI</acronym>(s)), self
                for <acronym>AMI</acronym>s for which you own or have explicit permissions, or all for public <acronym>AMI</acronym>s.
            </para>
            <para>
                <code>describe</code> returns an array for all the images that match the critera that was
                passed in. The array contains the imageId, imageLocation, imageState, imageOwnerId, isPublic,
                architecture, imageType, kernelId, ramdiskId and platform.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->describe();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.amazon.ec2.images.attribute">
        <title>AMI Attribute Utilities</title>

        <example id="zend.service.amazon.ec2.images.attribute.modify">
            <title>Modify Image Attributes</title>
            <para>Modifies an attribute of an <acronym>AMI</acronym></para>
            <para>
            <table id="zend.service.amazon.ec2.images.attribute.modify-table">
                <title>Valid Attributes</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><code>launchPermission</code></entry>
                            <entry><para>
                                Controls who has permission to launch the <acronym>AMI</acronym>. Launch permissions
                                can be granted to specific users by adding userIds.
                            </para><para>To make the <acronym>AMI</acronym> public, add the all group.</para></entry>
                        </row>
                        <row>
                            <entry><code>productCodes</code></entry>
                            <entry><para>
                                Associates a product code with <constant>AMIs</constant>. This allows developers to
                                charge users for using <constant>AMIs</constant>. The user must be signed up for the
                                product before they can launch the <acronym>AMI</acronym>.
                                <emphasis>This is a write once attribute;
                                after it is set, it cannot be changed or
                                removed.</emphasis>
                            </para></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            </para>

            <para>
                <code>modifyAttribute</code> returns boolean <constant>TRUE</constant> or
                <constant>FALSE</constant>.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
// modify the launchPermission of an AMI
$return = $ec2_img->modifyAttribute('imageId',
                                    'launchPermission',
                                    'add',
                                    'userId',
                                    'userGroup');

// set the product code of the AMI.
$return = $ec2_img->modifyAttribute('imageId',
                                    'productCodes',
                                    'add',
                                    null,
                                    null,
                                    'productCode');
]]></programlisting>

        </example>

        <example id="zend.service.amazon.ec2.images.attribute.reset">
            <title>Reset an AMI Attribute</title>
            <para>
                <code>resetAttribute</code> will reset the attribute of an <acronym>AMI</acronym> to its default value.
                <emphasis>The productCodes attribute cannot be reset.</emphasis>
            </para>
            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$return = $ec2_img->resetAttribute('imageId', 'launchPermission');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.attribute.describe">
            <title>Describe AMI Attribute</title>
            <para>
                <code>describeAttribute</code> returns information about an attribute of an <acronym>AMI</acronym>.
                Only one attribute can be specified per call. Currently only launchPermission and
                productCodes are supported.
            </para>
            <para>
                <code>describeAttribute</code> returns an array with the value of the attribute
                that was requested.
            </para>
            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$return = $ec2_img->describeAttribute('imageId', 'launchPermission');
]]></programlisting>
        </example>

    </sect2>
</sect1>