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. We work with our partners and community to provide
        you with the most choice possible.
    </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 AMI 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 role="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 AMI. Once deregistered, instances
                of the AMI can no longer be launched.
            </para>
            <para>
                <code>deregister</code> returns boolean true or false.
            </para>

            <programlisting role="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 AMIs, AKIs, and ARIs
                available to the user. Information returned includes image type,
                product codes, architecture, and kernel and RAM 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 AMI granted launch permissions for the AMI
                                to the all group. All users have launch permissions for these AMIs.
                            </para></entry>
                        </row>
                        <row>
                            <entry><code>explicit</code></entry>
                            <entry><para>
                                The owner of the AMI 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 AMIs he or she owns.
                            </para></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            </para>
            <para>
                The list of AMIs returned can be modified by specifying AMI IDs, AMI owners,
                or users with launch permissions. If no options are specified, Amazon EC2 returns
                all AMIs for which the user has launch permissions.
            </para>
            <para>
                If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned.
                If you specify an invalid AMI ID, a fault is returned. If you specify an AMI 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 AMI owners, only AMIs 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 AMIs owned by Amazon or self for AMIs that you own.
            </para>
            <para>
                If you specify a list of executable users, only users that have launch permissions
                for the AMIs are returned. You can specify account IDs (if you own the AMI(s)), self
                for AMIs for which you own or have explicit permissions, or all for public AMIs.
            </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 role="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->allocate();
]]></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 AMI</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 AMI. Launch permissions
                                can be granted to specific users by adding userIds.
                            </para><para>To make the AMI public, add the all group.</para></entry>
                        </row>
                        <row>
                            <entry><code>productCodes</code></entry>
                            <entry><para>
                                Associates a product code with AMIs. This allows developers to
                                charge users for using AMIs. The user must be signed up for the
                                product before they can launch the AMI.
                                <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 ture or false.
            </para>
            <programlisting role="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 reest the attirbute of an AMI to its default value.
                <emphasis>The productCodes attribute cannot be reset.</emphasis>
            </para>
            <programlisting role="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 AMI.
                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 the value of the attirbute
                that was requested.
            </para>
            <programlisting role="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>