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>