Cloud9 environments status monitoring with Step Functions

As developers using AWS Cloud9 as their choice of development environment, they often run the cost of the EC2 instance which is used under-the-hood. In this blog, you will understand how to monitor environments which are not in stopped state and trigger an SES email to a designated email address. This helps AWS administrators stay on track with Cloud9 environments.

Understanding the workflow

The Step Functions's state machine uses AWS Cloud9 and Amazon SES APIs which are integrated with Step function's SDK integration.
The different steps uses - AWS Cloud9 SDK API listEnvironments and describeEnvironmentStatus along with Amazon SES SDK API sendEmail. So the state machine's IAM execution role would need access to perform the same actions.

ListEnvironments state

Using AWS Cloud9 SDK API listEnvironments, we can list all the environment's IDs and the API restricts upto 25 max items then they would have to be paginated. This state machine is using the first page (first 25 records) only from the API response.

Map state

In state machines, we could use map state for looping items. In this map state, each of the environment ID is used to fetch the status and do the needed processing.

"Map": {
      "Type": "Map",
      "Iterator": {
        "StartAt": "DescribeEnvironmentStatus",
        "States": {
          "DescribeEnvironmentStatus": {
            "Type": "Task",
            "Parameters": {
              "EnvironmentId.$": "$.value"
            },
            "Resource": "arn:aws:states:::aws-sdk:cloud9:describeEnvironmentStatus",
            "ResultPath": "$.envStatus",
            "Next": "Choice"
          },
          "Choice": {
            "Type": "Choice",
            "Choices": [
              {
                "Not": {
                  "Variable": "$.envStatus.Status",
                  "StringEquals": "stopped"
                },
                "Next": "SendEmail"
              }
            ],
            "Default": "Pass"
          },
          "SendEmail": {
            "Type": "Task",
            "End": true,
            "Parameters": {
              "Destination": {
                "ToAddresses": [
                  "zachjonesnoel@mailinator.com"
                ]
              },
              "Message": {
                "Body": {
                  "Html": {
                    "Charset": "UTF-8",
                    "Data.$": "States.Format('[{}] Environment ID {} is {}', $.envStatus.Status, $.value, $.envStatus.Message)"
                  }
                },
                "Subject": {
                  "Data": "Your Cloud9 Environment status!!!"
                }
              },
              "Source": "test@zachjonesnoel.com"
            },
            "Resource": "arn:aws:states:::aws-sdk:ses:sendEmail"
          },
          "Pass": {
            "Type": "Pass",
            "End": true
          }
        }
      },
      "End": true,
      "ItemsPath": "$.envs.EnvironmentIds",
      "Parameters": {
        "index.$": "$$.Map.Item.Index",
        "value.$": "$$.Map.Item.Value"
      }
    }

DescribeEnvironmentStatus state

With each environment ID, we can get the status of that environment with AWS Cloud9 describeEnvironmentStatus SDK API. This responds with one of the status -

• connecting - Environment with connection in progress.
• creating - For an environment which is creation in progress.
• deleting - Whenever the CloudFormation stack is deleting the environment and the other AWS resources used under-the-hood.
• error - When the environment is in an error state.
• ready - For a successfully connected environment which is ready for usage.
• stopped - Based on the idle time stop, the environment would be stopped.
• stopping - Whenever the stop is initiated.

Choice state

With response status from describeEnvironmentStatus, a choice condition is used to check if the status is anything other than stopped then trigger the next step else pass.

SendEmail state

The sendEmail SDK API of Amazon SES is used to send email from a verified identity on SES. This uses HTML based body. For ensuring the email body is well formatted, States.Format intrinsic function is used.

Workflow executions

This state machine execution walks though the different states and also the iterations of each environment ID. There are cases, where the email has been triggered with SendEmail state.

When a new environment is created, an email with the status creating is sent along with the message.

When the environment is successfully created, or the state is successfully connected it's status is changed to ready.

When the environment is deleted, this invokes a CloudFormation stack delete and email with the following body is sent.

Conclusion

AWS Step Functions helps orchestration of various workflows. This involves some administrative monitoring workflows also automated helping to monitor different status changes in Cloud9 environment and notifying the needed users via email leveraging Amazon SES.
And as part of cost-optimizaton, the pass state could be avoided.