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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.amazon.ec2.ebs">
    <title>Zend_Service_Amazon_Ec2: Elastic Block Storage (EBS)</title>

    <para>
        Amazon Elastic Block Store (Amazon EBS) is a new type of storage
        designed specifically for Amazon EC2 instances. Amazon EBS allows
        you to create volumes that can be mounted as devices by Amazon EC2
        instances. Amazon EBS volumes behave like raw unformatted external
        block devices. They have user supplied device names and provide a block
        device interface. You can load a file system on top of Amazon EBS volumes,
        or use them just as you would use a block device.
    </para>

    <para>
        You can create up to twenty Amazon EBS volumes of any size (from one GiB up
        to one TiB). Each Amazon EBS volume can be attached to any Amazon EC2
        instance in the same Availability Zone or can be left unattached.
    </para>

    <para>
        Amazon EBS provides the ability to create snapshots of your Amazon EBS volumes
        to Amazon S3. You can use these snapshots as the starting point for new Amazon
        EBS volumes and can protect your data for long term durability.
    </para>

    <sect2 id="zend.service.amazon.ec2.ebs.creating">
        <title>Create EBS Volumes and Snapshots</title>

        <example id="zend.service.amazon.ec2.ebs.creating.volume">
            <title>Create a new EBS Volume</title>

            <para>
                Creating a brand new EBS Volume requires the size and which zone you
                want the EBS Volume to be in.
            </para>

            <para>
                <code>createNewVolume</code> will return an array containing information
                about the new Volume which includes the volumeId, size, zone, status
                and createTime.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->createNewVolume(40, 'us-east-1a');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.creating.volumesnapshot">
            <title>Create an EBS Volume from a Snapshot</title>

            <para>
                Creating an EBS Volume from a snapshot requires the snapshot_id and which zone you
                want the EBS Volume to be in.
            </para>

            <para>
                <code>createVolumeFromSnapshot</code> will return an array containing information
                about the new Volume which includes the volumeId, size, zone, status, createTime and
                snapshotId.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->createVolumeFromSnapshot('snap-78a54011', 'us-east-1a');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.creating.snapshot">
            <title>Create a Snapshot of an EBS Volume</title>

            <para>
                Creating a Snapshot of an EBS Volume requires the volumeId of the EBS Volume.
            </para>

            <para>
                <code>createSnapshot</code> will return an array containing information about the
                new Volume Snapshot which includes the snapshotId, volumeId, status, startTime
                and progress.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->createSnapshot('volumeId');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.amazon.ec2.ebs.describing">
        <title>Describing EBS Volumes and Snapshots</title>

        <example id="zend.service.amazon.ec2.ebs.describing.volume">
            <title>Describing an EBS Volume</title>

            <para>
                <code>describeVolume</code> allows you to get information on an EBS Volume or a set
                of EBS Volumes. If nothing is passed in then it will return all EBS Volumes. If only
                one EBS Volume needs to be described a string can be passed in while an array of
                EBS Volume Id's can be passed in to describe them.
            </para>

            <para>
                <code>describeVolume</code> will return an array with information about each Volume
                which includes the volumeId, size, status and createTime. If the volume is attached
                to an instance, an addition value of attachmentSet will be returned. The attachment
                set contains information about the instance that the EBS Volume is attached to,
                which includes volumeId, instanceId, device, status and attachTime.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->describeVolume('volumeId');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.describing.attachedvolumes">
            <title>Describe Attached Volumes</title>

            <para>
                To return a list of EBS Volumes currently attached to a running instance you can
                call this method. It will only return EBS Volumes attached to the instance with the
                passed in instanceId.
            </para>

            <para>
                <code>describeAttachedVolumes</code> returns the same information as the
                <code>describeVolume</code> but only for the EBS Volumes that are currently attached
                to the specified instanceId.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->describeAttachedVolumes('instanceId');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.describing.snapshot">
            <title>Describe an EBS Volume Snapshot</title>

            <para>
                <code>describeSnapshot</code> allows you to get information on an EBS Volume
                Snapshot or a set of EBS Volume Snapshots. If nothing is passed in then it will
                return information about all EBS Volume Snapshots. If only one EBS Volume Snapshot
                needs to be described its snapshotId can be passed in while an array of EBS Volume
                Snapshot Id's can be passed in to describe them.
            </para>

            <para>
                <code>describeSnapshot</code> will return an array containing information about each
                EBS Volume Snapshot which includes the snapshotId, volumeId, status, startTime and
                progress.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->describeSnapshot('volumeId');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.amazon.ec2.ebs.attachdetach">
        <title>Attach and Detaching Volumes from Instances</title>

        <example id="zend.service.amazon.ec2.ebs.attachdetach.attach">
            <title>Attaching an EBS Volume</title>

            <para>
                <code>attachVolume</code> will attach an EBS Volume to a running Instance. To
                attach a volume you need to specify the volumeId, the instanceId and the
                device <emphasis>(ex: /dev/sdh)</emphasis>.
            </para>

            <para>
                <code>attachVolume</code> will return an array with information about the
                attach status which contains volumeId, instanceId, device, status and
                attachTime
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->attachVolume('volumeId', 'instanceid', '/dev/sdh');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.attachdetach.detach">
            <title>Detaching an EBS Volume</title>

            <para>
                <code>detachVolume</code> will detach an EBS Volume from a running Instance.
                <code>detachVolume</code> requires that you specify the volumeId with the optional
                instanceId and device name that was passed when attaching the volume. If you need to
                force the detachment you can set the fourth parameter to be
                <constant>TRUE</constant> and it will force the volume to detach.
            </para>

            <para>
                <code>detachVolume</code> returns an array containing status information about
                the EBS Volume which includes volumeId, instanceId, device, status and attachTime.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->detachVolume('volumeId');
]]></programlisting>
        </example>

        <note>
            <title>Forced Detach</title>

            <para>
                You should only force a detach if the previous detachment attempt did not occur
                cleanly (logging into an instance, unmounting the volume, and detaching normally).
                This option can lead to data loss or a corrupted file system. Use this option
                only as a last resort to detach a volume from a failed instance. The instance
                will not have an opportunity to flush file system caches or file system meta
                data. If you use this option, you must perform file system check and repair
                procedures.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.service.amazon.ec2.ebs.deleting">
        <title>Deleting EBS Volumes and Snapshots</title>

        <example id="zend.service.amazon.ec2.ebs.deleting.volume">
            <title>Deleting an EBS Volume</title>

            <para>
                <code>deleteVolume</code> will delete an unattached EBS Volume.
            </para>

            <para>
                <code>deleteVolume</code> will return boolean <constant>TRUE</constant> or
                <constant>FALSE</constant>.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->deleteVolume('volumeId');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.ebs.deleting.snapshot">
            <title>Deleting an EBS Volume Snapshot</title>

            <para>
                <code>deleteSnapshot</code> will delete an EBS Volume Snapshot.
            </para>

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

            <programlisting language="php"><![CDATA[
$ec2_ebs = new Zend_Service_Amazon_Ec2_Ebs('aws_key','aws_secret_key');
$return = $ec2_ebs->deleteSnapshot('snapshotId');
]]></programlisting>
        </example>
    </sect2>
</sect1>