documentation/manual/en/module_specs/Zend_Service_Amazon_Ec2-Instance.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.amazon.ec2.instance">
   4     <title>Zend_Service_Amazon_Ec2: Instances</title>
   5
   6     <sect2 id="zend.service.amazon.ec2.instance.types">
   7         <title>Instance Types</title>
   8
   9         <para>
  10             Amazon EC2 instances are grouped into two families: standard and
  11             High-CPU. Standard instances have memory to <acronym>CPU</acronym> ratios suitable
  12             for most general purpose applications; High-CPU instances have
  13             proportionally more <acronym>CPU</acronym> resources than memory (RAM) and are well
  14             suited for compute-intensive applications. When selecting instance
  15             types, you might want to use less powerful instance types for your
  16             web server instances and more powerful instance types for your
  17             database instances. Additionally, you might want to run <acronym>CPU</acronym> instance
  18             types for <acronym>CPU</acronym>-intensive data processing tasks.
  19         </para>
  20
  21         <para>
  22             One of the advantages of EC2 is that you pay by the instance hour,
  23             which makes it convenient and inexpensive to test the performance of
  24             your application on different instance families and types. One good
  25             way to determine the most appropriate instance family and instance
  26             type is to launch test instances and benchmark your application.
  27         </para>
  28
  29         <note>
  30             <title>Instance Types</title>
  31
  32             <para>
  33                 The instance types are defined as constants in the code. Column eight
  34                 in the table is the defined constant name
  35             </para>
  36         </note>
  37
  38         <table id="zend.service.amazon.ec2.instance.types-table">
  39             <title>Available Instance Types</title>
  40
  41             <tgroup cols="8">
  42                 <thead>
  43                     <row>
  44                         <entry>Type</entry>
  45                         <entry><acronym>CPU</acronym></entry>
  46                         <entry>Memory</entry>
  47                         <entry>Storage</entry>
  48                         <entry>Platform</entry>
  49                         <entry>I/O</entry>
  50                         <entry>Name</entry>
  51                         <entry>Constant Name</entry>
  52                     </row>
  53                 </thead>
  54
  55                 <tbody>
  56                     <row>
  57                         <entry><code>Small</code></entry>
  58
  59                         <entry>
  60                             <para>
  61                                 1 <constant>EC2</constant> Compute Unit (1 virtual core with 1
  62                                 <constant>EC2</constant> Compute Unit)
  63                             </para>
  64                         </entry>
  65
  66                         <entry><para>1.7 GB</para></entry>
  67
  68                         <entry>
  69                             <para>160 GB instance storage (150 GB plus 10 GB root partition)</para>
  70                         </entry>
  71
  72                         <entry><para>32-bit</para></entry>
  73                         <entry><para>Moderate</para></entry>
  74                         <entry><para>m1.small</para></entry>
  75                         <entry><constant>Zend_Service_Amazon_Ec2_Instance::SMALL</constant></entry>
  76                     </row>
  77
  78                     <row>
  79                         <entry><code>Large</code></entry>
  80
  81                         <entry>
  82                             <para>
  83                                 4 <constant>EC2</constant> Compute Units (2 virtual cores with 2
  84                                 <constant>EC2</constant> Compute Units each)
  85                             </para>
  86                         </entry>
  87
  88                         <entry><para>7.5 GB</para></entry>
  89
  90                         <entry>
  91                             <para>
  92                                 850 GB instance storage (2 x 420 GB plus 10 GB root partition)
  93                             </para>
  94                         </entry>
  95
  96                         <entry><para>64-bit</para></entry>
  97                         <entry><para>High</para></entry>
  98                         <entry><para>m1.large</para></entry>
  99                         <entry><constant>Zend_Service_Amazon_Ec2_Instance::LARGE</constant></entry>
 100                     </row>
 101
 102                     <row>
 103                         <entry><code>Extra Large</code></entry>
 104                         <entry>
 105                             <para>
 106                                 8 <constant>EC2</constant> Compute Units (4 virtual cores with 2
 107                                 <constant>EC2</constant> Compute Units each)
 108                             </para>
 109                         </entry>
 110
 111                         <entry><para>15 GB</para></entry>
 112
 113                         <entry>
 114                             <para>
 115                                 1,690 GB instance storage (4 x 420 GB plus 10 GB root partition)
 116                             </para>
 117                         </entry>
 118
 119                         <entry><para>64-bit</para></entry>
 120                         <entry><para>High</para></entry>
 121                         <entry><para>m1.xlarge</para></entry>
 122                         <entry><constant>Zend_Service_Amazon_Ec2_Instance::XLARGE</constant></entry>
 123                     </row>
 124
 125                     <row>
 126                         <entry><code>High-CPU Medium</code></entry>
 127
 128                         <entry>
 129                             <para>
 130                                 5 <constant>EC2</constant> Compute Units (2 virtual cores with 2.5
 131                                 <constant>EC2</constant> Compute Units each)
 132                             </para>
 133                         </entry>
 134
 135                         <entry><para>1.7 GB</para></entry>
 136
 137                         <entry>
 138                             <para>350 GB instance storage (340 GB plus 10 GB root partition)</para>
 139                         </entry>
 140
 141                         <entry><para>32-bit</para></entry>
 142                         <entry><para>Moderate</para></entry>
 143                         <entry><para>c1.medium</para></entry>
 144
 145                         <entry>
 146                             <constant>Zend_Service_Amazon_Ec2_Instance::HCPU_MEDIUM</constant>
 147                         </entry>
 148                     </row>
 149
 150                     <row>
 151                         <entry><code>High-CPU Extra Large</code></entry>
 152
 153                         <entry>
 154                             <para>
 155                                 20 <constant>EC2</constant> Compute Units (8 virtual cores with 2.5
 156                                 <constant>EC2</constant> Compute Units each)
 157                             </para>
 158                         </entry>
 159
 160                         <entry><para>7 GB</para></entry>
 161
 162                         <entry>
 163                             <para>
 164                                 1,690 GB instance storage (4 x 420 GB plus 10 GB root partition)
 165                             </para>
 166                         </entry>
 167
 168                         <entry><para>64-bit</para></entry>
 169                         <entry><para>High</para></entry>
 170                         <entry><para>c1.xlarge</para></entry>
 171
 172                         <entry>
 173                             <constant>Zend_Service_Amazon_Ec2_Instance::HCPU_XLARGE</constant>
 174                         </entry>
 175                     </row>
 176                 </tbody>
 177             </tgroup>
 178         </table>
 179     </sect2>
 180
 181     <sect2 id="zend.service.amazon.ec2.instance.operations">
 182         <title>Running Amazon EC2 Instances</title>
 183
 184         <para>
 185             This section describes the operation methods for maintaining Amazon EC2 Instances.
 186         </para>
 187
 188         <example id="zend.service.amazon.ec2.instance.operations.run">
 189             <title>Starting New Ec2 Instances</title>
 190
 191             <para>
 192                 <code>run</code> will launch a specified number of EC2 Instances.
 193                 <code>run</code> takes an array of parameters to start, below is a table
 194                 containing the valid values.
 195             </para>
 196
 197             <para>
 198                 <table id="zend.service.amazon.ec2.instance.operations.run-table">
 199                     <title>Valid Run Options</title>
 200
 201                     <tgroup cols="3">
 202                         <thead>
 203                             <row>
 204                                 <entry>Name</entry>
 205                                 <entry>Description</entry>
 206                                 <entry>Required</entry>
 207                             </row>
 208                         </thead>
 209
 210                         <tbody>
 211                             <row>
 212                                 <entry><code>imageId</code></entry>
 213
 214                                 <entry>
 215                                     <para>
 216                                         ID of the <acronym>AMI</acronym> with which to launch
 217                                         instances.
 218                                     </para>
 219                                 </entry>
 220
 221                                 <entry><para>Yes</para></entry>
 222                             </row>
 223
 224                             <row>
 225                                 <entry><code>minCount</code></entry>
 226
 227                                 <entry>
 228                                     <para>Minimum number of instances to launch. Default: 1</para>
 229                                 </entry>
 230
 231                                 <entry><para>No</para></entry>
 232                             </row>
 233
 234                             <row>
 235                                 <entry><code>maxCount</code></entry>
 236
 237                                 <entry>
 238                                     <para>Maximum number of instances to launch. Default: 1</para>
 239                                 </entry>
 240
 241                                 <entry><para>No</para></entry>
 242                             </row>
 243
 244                             <row>
 245                                 <entry><code>keyName</code></entry>
 246
 247                                 <entry>
 248                                     <para>
 249                                         Name of the key pair with which to launch instances.
 250                                         If you do not provide a key, all instances will
 251                                         be inaccessible.
 252                                     </para>
 253                                 </entry>
 254
 255                                 <entry><para>No</para></entry>
 256                             </row>
 257
 258                             <row>
 259                                 <entry><code>securityGroup</code></entry>
 260
 261                                 <entry>
 262                                     <para>
 263                                         Names of the security groups with which to associate
 264                                         the instances.
 265                                     </para>
 266                                 </entry>
 267
 268                                 <entry><para>No</para></entry>
 269                             </row>
 270
 271                             <row>
 272                                 <entry><code>userData</code></entry>
 273
 274                                 <entry>
 275                                     <para>
 276                                         The user data available to the launched instances.
 277                                         This should not be Base64 encoded.
 278                                     </para>
 279                                 </entry>
 280
 281                                 <entry><para>No</para></entry>
 282                             </row>
 283
 284                             <row>
 285                                 <entry><code>instanceType</code></entry>
 286
 287                                 <entry>
 288                                     <para>
 289                                         Specifies the instance type. Default: m1.small
 290                                     </para>
 291                                 </entry>
 292
 293                                 <entry><para>No</para></entry>
 294                             </row>
 295
 296                             <row>
 297                                 <entry><code>placement</code></entry>
 298
 299                                 <entry>
 300                                     <para>
 301                                         Specifies the availability zone in which to
 302                                         launch the instance(s). By default, Amazon
 303                                         <constant>EC2</constant> selects an availability zone for
 304                                         you.
 305                                     </para>
 306                                 </entry>
 307
 308                                 <entry><para>No</para></entry>
 309                             </row>
 310
 311                             <row>
 312                                 <entry><code>kernelId</code></entry>
 313
 314                                 <entry>
 315                                     <para>
 316                                         The ID of the kernel with which to launch
 317                                         the instance.
 318                                     </para>
 319                                 </entry>
 320
 321                                 <entry><para>No</para></entry>
 322                             </row>
 323
 324                             <row>
 325                                 <entry><code>ramdiskId</code></entry>
 326
 327                                 <entry>
 328                                     <para>
 329                                         The ID of the <acronym>RAM</acronym> disk with which to
 330                                         launch the instance.
 331                                     </para>
 332                                 </entry>
 333
 334                                 <entry><para>No</para></entry>
 335                             </row>
 336
 337                             <row>
 338                                 <entry><code>blockDeviceVirtualName</code></entry>
 339
 340                                 <entry>
 341                                     <para>
 342                                         Specifies the virtual name to map to the
 343                                         corresponding device name. For example:
 344                                         instancestore0
 345                                     </para>
 346                                 </entry>
 347
 348                                 <entry><para>No</para></entry>
 349                             </row>
 350
 351                             <row>
 352                                 <entry><code>blockDeviceName</code></entry>
 353
 354                                 <entry>
 355                                     <para>
 356                                          Specifies the device to which you are
 357                                          mapping a virtual name. For example: sdb
 358                                     </para>
 359                                 </entry>
 360
 361                                 <entry><para>No</para></entry>
 362                             </row>
 363                             <row>
 364                                 <entry><code>monitor</code></entry>
 365
 366                                 <entry>
 367                                     <para>
 368                                          Turn on <acronym>AWS</acronym> CloudWatch Instance
 369                                          Monitoring
 370                                     </para>
 371                                 </entry>
 372
 373                                 <entry><para>No</para></entry>
 374                             </row>
 375                         </tbody>
 376                     </tgroup>
 377                 </table>
 378             </para>
 379
 380             <para>
 381                 <code>run</code> will return information about each instance
 382                 that is starting up.
 383             </para>
 384
 385             <programlisting language="php"><![CDATA[
 386 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 387                                                      'aws_secret_key');
 388 $return = $ec2_instance->run(array('imageId' => 'ami-509320',
 389                                    'keyName' => 'myKey',
 390                                    'securityGroup' => array('web',
 391                                                             'default')));
 392 ]]></programlisting>
 393         </example>
 394
 395         <example id="zend.service.amazon.ec2.instance.operations.reboot">
 396             <title>Rebooting an Ec2 Instances</title>
 397
 398             <para>
 399                 <code>reboot</code> will reboot one or more instances.
 400             </para>
 401
 402             <para>
 403                 This operation is asynchronous; it only queues a request to
 404                 reboot the specified instance(s). The operation will succeed
 405                 if the instances are valid and belong to the user. Requests
 406                 to reboot terminated instances are ignored.
 407             </para>
 408
 409             <para>
 410                 <code>reboot</code> returns boolean <constant>TRUE</constant> or
 411                 <constant>FALSE</constant>
 412             </para>
 413
 414             <programlisting language="php"><![CDATA[
 415 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 416                                                      'aws_secret_key');
 417 $return = $ec2_instance->reboot('instanceId');
 418 ]]></programlisting>
 419         </example>
 420
 421         <example id="zend.service.amazon.ec2.instance.operations.terminate">
 422             <title>Terminating an Ec2 Instances</title>
 423
 424             <para>
 425                 <code>terminate</code> shuts down one or more instances. This
 426                 operation is idempotent; if you terminate an instance more
 427                 than once, each call will succeed.
 428             </para>
 429
 430             <para>
 431                 <code>terminate</code> returns boolean <constant>TRUE</constant> or
 432                 <constant>FALSE</constant>
 433             </para>
 434
 435             <programlisting language="php"><![CDATA[
 436 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 437                                                      'aws_secret_key');
 438 $return = $ec2_instance->terminate('instanceId');
 439 ]]></programlisting>
 440         </example>
 441
 442         <note>
 443             <title>Terminated Instances</title>
 444             <para>Terminated instances will remain visible after termination
 445             (approximately one hour).</para>
 446         </note>
 447     </sect2>
 448
 449     <sect2 id="zend.service.amazon.ec2.instance.utility">
 450         <title>Amazon Instance Utilities</title>
 451
 452         <para>
 453             In this section you will find out how to retreive information, the console
 454             output and see if an instance contains a product code.
 455         </para>
 456
 457         <example id="zend.service.amazon.ec2.instance.utility.describe">
 458             <title>Describing Instances</title>
 459
 460             <para>
 461                 <code>describe</code> returns information about instances that you own.
 462             </para>
 463
 464             <para>
 465                 If you specify one or more instance IDs, Amazon EC2 returns information
 466                 for those instances. If you do not specify instance IDs, Amazon EC2
 467                 returns information for all relevant instances. If you specify an invalid
 468                 instance ID, a fault is returned. If you specify an instance that you do
 469                 not own, it will not be included in the returned results.
 470             </para>
 471
 472             <para>
 473                 <code>describe</code> will return an array containing information on the
 474                 instance.
 475             </para>
 476
 477             <programlisting language="php"><![CDATA[
 478 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 479                                                      'aws_secret_key');
 480 $return = $ec2_instance->describe('instanceId');
 481 ]]></programlisting>
 482         </example>
 483
 484         <note>
 485             <title>Terminated Instances</title>
 486
 487             <para>
 488                 Recently terminated instances might appear in the returned results. This interval is
 489                 usually less than one hour. If you do not want terminated instances to be returned,
 490                 pass in a second variable of boolean <constant>TRUE</constant> to
 491                 <code>describe</code> and the terminated instances will be ignored.
 492             </para>
 493         </note>
 494
 495         <example id="zend.service.amazon.ec2.instance.utility.describebyimageid">
 496             <title>Describing Instances By Image Id</title>
 497
 498             <para>
 499                 <code>describeByImageId</code> is functionally the same as <code>describe</code>
 500                 but it will only return the instances that are using the provided imageId.
 501             </para>
 502
 503             <para>
 504                 <code>describeByImageId</code> will return an array containing information on the
 505                 instances thare were started by the passed in imageId
 506             </para>
 507
 508             <programlisting language="php"><![CDATA[
 509 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 510                                                      'aws_secret_key');
 511 $return = $ec2_instance->describeByImageId('imageId');
 512 ]]></programlisting>
 513         </example>
 514
 515         <note>
 516             <title>Terminated Instances</title>
 517
 518             <para>
 519                 Recently terminated instances might appear in the returned results. This
 520                 interval is usually less than one hour. If you do not want terminated
 521                 instances to be returned, pass in a second variable of boolean
 522                 <constant>TRUE</constant> to <code>describe</code> and the terminated instances
 523                 will be ignored.
 524             </para>
 525         </note>
 526
 527         <example id="zend.service.amazon.ec2.instance.utility.consoleOutput">
 528             <title>Retreiving Console Output</title>
 529
 530             <para>
 531                 <code>consoleOutput</code> retrieves console output for the specified
 532                 instance.
 533             </para>
 534
 535             <para>
 536                 Instance console output is buffered and posted shortly after instance
 537                 boot, reboot, and termination. Amazon EC2 preserves the most recent
 538                 64 KB output which will be available for at least one hour after the
 539                 most recent post.
 540             </para>
 541
 542             <para>
 543                 <code>consoleOutput</code> returns an array containing the
 544                 <code>instanceId</code>, <code>timestamp</code> from the last output
 545                 and the <code>output</code> from the console.
 546             </para>
 547
 548             <programlisting language="php"><![CDATA[
 549 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 550                                                      'aws_secret_key');
 551 $return = $ec2_instance->consoleOutput('instanceId');
 552 ]]></programlisting>
 553         </example>
 554
 555         <example id="zend.service.amazon.ec2.instance.utility.confirmproduct">
 556             <title>Confirm Product Code on an Instance</title>
 557
 558             <para>
 559                 <code>confirmProduct</code> returns <constant>TRUE</constant> if the specified
 560                 product code is attached to the specified instance. The operation returns
 561                 <constant>FALSE</constant> if the product code is not attached to the instance.
 562             </para>
 563
 564             <para>
 565                 The <code>confirmProduct</code> operation can only be executed by the owner of the
 566                 <acronym>AMI</acronym>. This feature is useful when an <acronym>AMI</acronym> owner
 567                 is providing support and wants to verify whether a user's instance is eligible.
 568             </para>
 569
 570             <programlisting language="php"><![CDATA[
 571 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 572                                                      'aws_secret_key');
 573 $return = $ec2_instance->confirmProduct('productCode', 'instanceId');
 574 ]]></programlisting>
 575         </example>
 576
 577         <example id="zend.service.amazon.ec2.instance.utility.monitor">
 578             <title>Turn on CloudWatch Monitoring on an Instance(s)</title>
 579
 580             <para>
 581                 <code>monitor</code> returns the list of instances and their
 582                 current state of the CloudWatch Monitoring. If the instance
 583                 does not currently have Monitoring enabled it will be turned on.
 584             </para>
 585
 586             <programlisting language="php"><![CDATA[
 587 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 588                                                      'aws_secret_key');
 589 $return = $ec2_instance->monitor('instanceId');
 590 ]]></programlisting>
 591         </example>
 592
 593         <example id="zend.service.amazon.ec2.instance.utility.unmonitor">
 594             <title>Turn off CloudWatch Monitoring on an Instance(s)</title>
 595
 596             <para>
 597                 <code>monitor</code> returns the list of instances and their
 598                 current state of the CloudWatch Monitoring. If the instance
 599                 currently has Monitoring enabled it will be turned off.
 600             </para>
 601
 602             <programlisting language="php"><![CDATA[
 603 $ec2_instance = new Zend_Service_Amazon_Ec2_Instance('aws_key',
 604                                                      'aws_secret_key');
 605 $return = $ec2_instance->unmonitor('instanceId');
 606 ]]></programlisting>
 607         </example>
 608     </sect2>
 609 </sect1>