banshee/cloud-collection/cloud/aws/https/ec2-instances

EC2 instances, by the Amazon EC2 API

Returns, for each EC2 instance of an AWS region, its state and the results of its two status checks: the system status check, which AWS runs on the hardware and the network the instance lives on, and the instance status check, which tests the instance itself. Read through the Amazon EC2 API with an access key that may only read. Four watches are offered, each one set on the probe.

Versions

Generic: the Amazon EC2 API is one service, the same in every region. The collector asks for its version 2016-11-15, the one the EC2 API Reference documents.

How it works

GET https://ec2.<aws:region>.amazonaws.com/?Action=DescribeInstanceStatus&IncludeAllInstances=true&Version=2016-11-15, signed by aws.sign (Signature Version 4, service ec2), page after page by NextToken. The answer is XML:

<DescribeInstanceStatusResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>…</requestId>
  <instanceStatusSet>
    <item>
      <instanceId>i-0123456789abcdef0</instanceId>
      <availabilityZone>eu-west-3a</availabilityZone>
      <instanceState><code>16</code><name>running</name></instanceState>
      <systemStatus><status>ok</status><details>…</details></systemStatus>
      <instanceStatus><status>ok</status><details>…</details></instanceStatus>
    </item>
  </instanceStatusSet>
  <nextToken>…</nextToken>
</DescribeInstanceStatusResponse>

An instance is named by its ID, i-0123456789abcdef0: the only name AWS gives every instance, and the only one that is unique.
state is instanceState.name: pending, running, shutting-down, terminated, stopping, stopped. IncludeAllInstances=true lists the instances that do not run too, which AWS leaves out by default; a terminated instance stays listed about an hour, then disappears.
system-status and instance-status are the status of each check: ok, impaired, initializing, insufficient-data, not-applicable (a stopped instance is not checked).
The region goes into the name of the host: a region with other characters than lower-case letters, digits and hyphens stops the collector misconfigured before anything leaves.
A code 400, 401 or 403 stops the collector misconfigured, with the error code AWS writes (AuthFailure, UnauthorizedOperation, SignatureDoesNotMatch…); a throttled request (RequestLimitExceeded), a code 500 or above, or any other code but 200 stops it unreachable.

The keys come from protocol:aws: the secret key never leaves the poller, only the signature it makes. The answer is not secret.

Prerequisites

An IAM user with an access key, or a role whose temporary keys are set with their session token, allowed this action and nothing else:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "ec2:DescribeInstanceStatus", "Resource": "*" }
  ]
}

DescribeInstanceStatus takes no resource-level permission: its resource is *. The access key ID goes in protocol:aws:access-key-id, the secret key in protocol:aws:secret-access-key, the session token, for temporary keys only, in protocol:aws:session-token.

The poller reaches ec2.<region>.amazonaws.com in HTTPS, and its clock is right within a few minutes: AWS refuses a request signed more than fifteen minutes away from its own time. The certificates of AWS are issued by public authorities: the profile "Standard" trusts them.

Variables

Name	Label	Says	Default
`aws:region`	Region	the AWS region of the instances, `eu-west-3`	—

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per instance
`system-status`	System status check	—	yes, per instance
`instance-status`	Instance status check	—	yes, per instance

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	Instance not running	expected value, on `state`	critical when not `running` for 2 runs: a start or a stop in progress does not raise	yes
`system-impaired`	System status check failed	state to avoid, on `system-status`	critical on `impaired`	yes
`instance-impaired`	Instance status check failed	state to avoid, on `instance-status`	critical on `impaired`	yes
`missing`	Instance missing	expected instances, on `state`	no name given: it raises nothing until names are set on the probe	no

An instance stopped on purpose is left out by the selection of the probe (Instances: All except i-0fedcba9876543210). In a region where an Auto Scaling group replaces its instances, the IDs change, and a terminated instance raises until AWS stops listing it.

Limits

One region per probe. The regions of AWS in China (amazonaws.com.cn) are not served.
The scheduled events of an instance (a retirement, a reboot) are not read.
Not checked against an AWS account: the action, its parameters and its fields are those of the Amazon EC2 API Reference ("DescribeInstanceStatus", its sample answer, and the enumerations of its filters), the signature that of "Create a signed AWS API request".