Example: DynamoDB, CloudWatch, and SNS

To install eb, its prerequisite software, and initialize your Git repository

1. Install the following software onto your local computer:

   1. Linux/Unix/MAC

      • Download and unzip the Elastic Beanstalk command line tools package at the AWS Sample Code & Libraries website.

      • Git 1.6.6 or later. To download Git, go to http://git-scm.com/.

      • Ruby version 1.8.7 or later. To view and download Ruby clients, go to http://www.ruby-lang.org/en/.

      • Python 2.7 or 3.0.

   2. Windows

      • Git 1.6.6 or later. To download Git, go to http://git-scm.com/.

      • PowerShell 2.0.

        Note

        Windows 7 and Windows Server 2008 R2 come with PowerShell 2.0. If you are running an earlier version of Windows, you can download PowerShell 2.0. Visit http://technet.microsoft.com/en-us/scriptcenter/dd742419.aspx for more details.

2. Initialize your Git repository.

   git init .

To configure AWS Elastic Beanstalk

1. From your directory where you created your local repository, type the following command.

   eb init

2. When you are prompted for the AWS access key, type your access key. To get your access key information, go to Access Credentials.

   Enter your AWS Access Key ID (current value is "AKIAIOSFODNN7EXAMPLE"): 

3. When you are prompted for the AWS secret key, type your secret key. To get your secret key information, go to Access Credentials.

   Enter your AWS Secret Access Key (current value is "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"): 

4. When you are prompted for the AWS Elastic Beanstalk region, type the number of the region. For information about this product's regions, go to Regions and Endpoints in the Amazon Web Services General Reference. For this example, we'll use US East (Virginia).

5. When you are prompted for the AWS Elastic Beanstalk application name, type the name of the application. AWS Elastic Beanstalk auto-generates an application name based on the current directory name if an application name has not been previously configured. In this example, we use HelloWorld.

   Enter an AWS Elastic Beanstalk application name (auto-generated value is "windows"): HelloWorld

   Note

   If you have a space in your application name, make sure you do not use quotes.

6. When you are prompted for the AWS Elastic Beanstalk environment name, type the name of the environment. AWS Elastic Beanstalk automatically creates an environment name based on your application name. If you want to accept the default, press Enter.

   Enter an AWS Elastic Beanstalk environment name (current value is "HelloWorld-env"): 

   Note

   If you have a space in your application name, make sure you do not have a space in your environment name.

7. When you are prompted for the solution stack, type the number of the solution stack you want. For this example, we'll use 64bit Amazon Linux running PHP 5.4.

8. When you are prompted to create an Amazon RDS database, type y or n. For this example, we'll type n.

   Create RDS instance? [y/n]: n

9. When you are prompted to enter your instance profile name, you can choose to create a default instance profile or use an existing instance profile. Using an instance profile enables IAM users and AWS services to gain access to temporary security credentials to make AWS API calls. Using instance profiles prevents you from having to store long-term security credentials on the EC2 instance. For more information about instance profiles, see Granting Permissions to Users and Services Using IAM Roles. For this example, we'll use Create a default instance profile.

To create the application

• From your directory where you created your local repository, type the following command.

  eb start

To view the application

1. From your directory where you created your local repository, type the following command.

   eb status --verbose

   AWS Elastic Beanstalk displays the environment status. If the environment is set to Green, AWS Elastic Beanstalk displays the URL for the application. If you attached an RDS DB Instance to your environment, your RDS DB information is displayed.

2. Copy and paste the URL into your web browser to view your application.

To update the application

1. In the directory where you created your local repository, use your favorite text editor to create an index.php file and paste the following PHP code.

   <?php
   
   // Include the SDK using the Composer autoloader
   require '../vendor/autoload.php';
   
   use Aws\DynamoDb\DynamoDbClient;
   
   // Grab the session table name and region from the configuration file
   list($tableName, $region) = file(__DIR__ . '/../sessiontable');
   $tableName = rtrim($tableName);
   $region = rtrim($region);
   
   // Create a DynamoDB client and register the table as the session handler
   $dynamodb = DynamoDbClient::factory(array('region' => $region));
   $handler = $dynamodb->registerSessionHandler(array('table_name' => $tableName, 'hash_key' => 'username'));
   
   // Grab the instance ID so we can display the EC2 instance that services the request
   $instanceId = file_get_contents("http://169.254.169.254/latest/meta-data/instance-id");
   ?>
   <h1>Elastic Beanstalk PHP Sessions Sample</h1>
   <p>This sample application shows the integration of the Elastic Beanstalk PHP
   container and the session support for DynamoDB from the AWS SDK for PHP 2.
   Using DynamoDB session support, the application can be scaled out across
   multiple web servers. For more details, see the
   <a href="http://aws.amazon.com/php/">PHP Developer Center</a>.</p>
   
   <form id="SimpleForm" name="SimpleForm" method="post" action="index.php">
   <?php
   echo 'Request serviced from instance ' . $instanceId . '<br/>';
   echo '<br/>';
   
   if (isset($_POST['continue'])) {
     session_start();
     $_SESSION['visits'] = $_SESSION['visits'] + 1;
     echo 'Welcome back ' . $_SESSION['username'] . '<br/>';
     echo 'This is visit number ' . $_SESSION['visits'] . '<br/>';
     session_write_close();
     echo '<br/>';
     echo '<input type="Submit" value="Refresh" name="continue" id="continue"/>';
     echo '<input type="Submit" value="Delete Session" name="killsession" id="killsession"/>';
   } elseif (isset($_POST['killsession'])) {
     session_start();
     echo 'Goodbye ' . $_SESSION['username'] . '<br/>';
     session_destroy();
     echo 'Username: <input type="text" name="username" id="username" size="30"/><br/>';
     echo '<br/>';
     echo '<input type="Submit" value="New Session" name="newsession" id="newsession"/>';
   } elseif (isset($_POST['newsession'])) {
     session_start();
     $_SESSION['username'] = $_POST['username'];
     $_SESSION['visits'] = 1;
     echo 'Welcome to a new session ' . $_SESSION['username'] . '<br/>';
     session_write_close();
     echo '<br/>';
     echo '<input type="Submit" value="Refresh" name="continue" id="continue"/>';
     echo '<input type="Submit" value="Delete Session" name="killsession" id="killsession"/>';
   } else {
     echo 'To get started, enter a username.<br/>';
     echo '<br/>';
     echo 'Username: <input type="text" name="username" id="username" size="30"/><br/>';
     echo '<input type="Submit" value="New Session" name="newsession" id="newsession"/>';
   }
   ?>
   </form>
   

2. Create an .ebextensions directory in the top-level directory of your source bundle.

3. Create a configuration file named dynamodb.config, paste the code in the listing below, and save the file in the .ebextensions top-level directory of your source bundle.

   Resources:
     SessionTable:
       Type: AWS::DynamoDB::Table
       Properties:
         KeySchema: 
           HashKeyElement:
             AttributeName:
               Fn::GetOptionSetting:
                 OptionName : SessionHashKeyName
                 DefaultValue: "username"
             AttributeType:
               Fn::GetOptionSetting:
                 OptionName : SessionHashKeyType
                 DefaultValue: "S"
         ProvisionedThroughput:
           ReadCapacityUnits:
             Fn::GetOptionSetting:
               OptionName : SessionReadCapacityUnits
               DefaultValue: 1
           WriteCapacityUnits:
             Fn::GetOptionSetting:
               OptionName : SessionWriteCapacityUnits
               DefaultValue: 1
   
     SessionWriteCapacityUnitsLimit:
       Type: AWS::CloudWatch::Alarm
       Properties:
         AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, " write capacity limit on the session table." ]]}
         Namespace: "AWS/DynamoDB"
         MetricName: ConsumedWriteCapacityUnits
         Dimensions:
           - Name: TableName
             Value: { "Ref" : "SessionTable" }
         Statistic: Sum
         Period: 300
         EvaluationPeriods: 12
         Threshold:
             Fn::GetOptionSetting:
               OptionName : SessionWriteCapacityUnitsAlarmThreshold
               DefaultValue: 240
         ComparisonOperator: GreaterThanThreshold
         AlarmActions:
           - Ref: SessionAlarmTopic
         InsufficientDataActions:
           - Ref: SessionAlarmTopic
   
     SessionReadCapacityUnitsLimit:
       Type: AWS::CloudWatch::Alarm
       Properties:
         AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, " read capacity limit on the session table." ]]}
         Namespace: "AWS/DynamoDB"
         MetricName: ConsumedReadCapacityUnits
         Dimensions:
           - Name: TableName
             Value: { "Ref" : "SessionTable" }
         Statistic: Sum
         Period: 300
         EvaluationPeriods: 12
         Threshold:
             Fn::GetOptionSetting:
               OptionName : SessionReadCapacityUnitsAlarmThreshold
               DefaultValue: 240
         ComparisonOperator: GreaterThanThreshold
         AlarmActions:
           - Ref: SessionAlarmTopic
         InsufficientDataActions:
           - Ref: SessionAlarmTopic
   
     SessionThrottledRequestsAlarm:
       Type: AWS::CloudWatch::Alarm
       Properties:
         AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, ": requests are being throttled." ]]}
         Namespace: AWS/DynamoDB
         MetricName: ThrottledRequests
         Dimensions:
           - Name: TableName
             Value: { "Ref" : "SessionTable" }
         Statistic: Sum
         Period: 300
         EvaluationPeriods: 1
         Threshold: 
           Fn::GetOptionSetting:
             OptionName: SessionThrottledRequestsThreshold
             DefaultValue: 1
         ComparisonOperator: GreaterThanThreshold
         AlarmActions:
           - Ref: SessionAlarmTopic
         InsufficientDataActions:
           - Ref: SessionAlarmTopic
   
     SessionAlarmTopic:
       Type: AWS::SNS::Topic
       Properties:
         Subscription:
           - Endpoint:
               Fn::GetOptionSetting:
                 OptionName: SessionAlarmEmail
                 DefaultValue: "nobody@amazon.com"
             Protocol: email
   
   files:
     "/var/app/sessiontable":
       mode: "000444"
       content: |
         `{"Ref" : "SessionTable"}`
         `{"Ref" : "AWS::Region"}`
   
     "/var/app/composer.json":
       mode: "000744"
       content:
         {
           "require": {
              "aws/aws-sdk-php": "*"
           }
         }
   
   container_commands:
    "1-install-composer":
      command: "cd /var/app; curl -s http://getcomposer.org/installer | php"
    "2-install-dependencies":
      command: "cd /var/app; php composer.phar install"
    "3-cleanup-composer":
      command: "rm -Rf /var/app/composer.*"
      			

   In the sample configuration file, we first create the DynamoDB table and configure the primary key structure for the table and the capacity units to allocate sufficient resources to provide the requested throughput. Next, we create CloudWatch alarms for WriteCapacity and ReadCapacity. We create an SNS topic that sends email to "nobody@amazon.com" if the alarm thresholds are breached.

   After we create and configure our AWS resources for our environment, we need to customize the EC2 instances. We use the files key to pass the details of the DynamoDB table to the EC2 instances in our environment as well as add a "require" in the composer.json file for the AWS SDK for PHP 2. Finally, we run container commands to install composer, the required dependencies, and then remove the installer. The example snippet looks like the following.

   For more information about the resources used in this example, see the following references:

   • AWS::DynamoDB::Table

   • AWS::CloudWatch::Alarm

   • AWS::SNS::Topic

4. Create a configuration file named options.config. Replace <email here> with the email where you want alarm notifications sent, and save the file in the .ebextensions top-level directory of your source bundle.

    option_settings:
     "aws:elasticbeanstalk:customoption":
        SessionHashKeyName                      : username
        SessionHashKeyType                      : S
        SessionReadCapacityUnits                : 1
        SessionReadCapacityUnitsAlarmThreshold  : 240
        SessionWriteCapacityUnits               : 1 
        SessionWriteCapacityUnitsAlarmThreshold : 240
        SessionThrottledRequestsThreshold       : 1
        SessionAlarmEmail                       : <email here>
   
   

   After you've made your changes, your file should look like the following.

    option_settings:
     "aws:elasticbeanstalk:customoption":
        SessionHashKeyName                      : username
        SessionHashKeyType                      : S
        SessionReadCapacityUnits                : 1
        SessionReadCapacityUnitsAlarmThreshold  : 240
        SessionWriteCapacityUnits               : 1 
        SessionWriteCapacityUnitsAlarmThreshold : 240
        SessionThrottledRequestsThreshold       : 1
        SessionAlarmEmail                       : <email here>
   
   

   The options.config file contains the values used for some of the variables defined in dynamodb.config. For example, dynamodb.config contains the following lines.

   Subscription:
     - Endpoint:
         Fn::GetOptionSetting:
           OptionName: SessionAlarmEmail
           DefaultValue: "nobody@amazon.com"

   These lines that tell AWS Elastic Beanstalk to get the value for the Endpoint property from the SessionAlarmEmail value in a config file (options.config in our sample application) that contains an option_settings section with an aws:elasticbeanstalk:customoption section that contains a name-value pair that contains the actual value to use. In the example above, this means SessionAlarmEmail would be assigned the value nobody@amazon.com.

5. Add your files to your local Git repository, and then commit your change.

   git add .
   git commit -m "eb configuration"

   Note

   For information about Git commands, go to Git - Fast Version Control System.

6. Create an application version matching your local repository and deploy to the Elastic Beanstalk environment if specified.

   git aws.push

7. Use the eb status --verbose command to check your environment status. When your environment is green and ready, refresh your web browser to view your updated application.