You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::AutoScaling::LifecycleHook

Inherits:
Resources::Resource show all
Defined in:
(unknown)

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(group_name, name, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(group_name, name, options = {}) ⇒ Object

    Parameters:

    • group_name (String)
    • name (String)

    Options Hash (options):

    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :group_name (required, String)
    • :name (required, String)
    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#auto_scaling_group_name ⇒ String (readonly)

The name of the Auto Scaling group for the lifecycle hook.

Returns:

  • (String) —

    The name of the Auto Scaling group for the lifecycle hook.

#default_result ⇒ String (readonly)

Defines the action the Auto Scaling group should take when the lifecycle hook timeout elapses or if an unexpected failure occurs. The possible values are CONTINUE and ABANDON.

Returns:

  • (String) —

    Defines the action the Auto Scaling group should take when the lifecycle hook timeout elapses or if an unexpected failure occurs.

#global_timeout ⇒ Integer (readonly)

The maximum time, in seconds, that an instance can remain in a Pending:Wait or Terminating:Wait state. The maximum is 172800 seconds (48 hours) or 100 times HeartbeatTimeout, whichever is smaller.

Returns:

  • (Integer) —

    The maximum time, in seconds, that an instance can remain in a Pending:Wait or Terminating:Wait state.

#group_name ⇒ String (readonly)

Returns:

  • (String)

#heartbeat_timeout ⇒ Integer (readonly)

The maximum time, in seconds, that can elapse before the lifecycle hook times out. If the lifecycle hook times out, Amazon EC2 Auto Scaling performs the action that you specified in the DefaultResult parameter.

Returns:

  • (Integer) —

    The maximum time, in seconds, that can elapse before the lifecycle hook times out.

#lifecycle_hook_name ⇒ String (readonly)

The name of the lifecycle hook.

Returns:

  • (String) —

    The name of the lifecycle hook.

#lifecycle_transition ⇒ String (readonly)

The state of the EC2 instance to which to attach the lifecycle hook. The following are possible values:

  • autoscaling:EC2_INSTANCE_LAUNCHING

  • autoscaling:EC2_INSTANCE_TERMINATING

Returns:

  • (String) —

    The state of the EC2 instance to which to attach the lifecycle hook.

#name ⇒ String (readonly)

Returns:

  • (String)

#notification_metadata ⇒ String (readonly)

Additional information that is included any time Amazon EC2 Auto Scaling sends a message to the notification target.

Returns:

  • (String) —

    Additional information that is included any time Amazon EC2 Auto Scaling sends a message to the notification target.

#notification_target_arn ⇒ String (readonly)

The ARN of the target that Amazon EC2 Auto Scaling sends notifications to when an instance is in the transition state for the lifecycle hook. The notification target can be either an SQS queue or an SNS topic.

Returns:

  • (String) —

    The ARN of the target that Amazon EC2 Auto Scaling sends notifications to when an instance is in the transition state for the lifecycle hook.

#role_arn ⇒ String (readonly)

The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.

Returns:

  • (String) —

    The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.

Instance Method Details

#complete(options = {}) ⇒ Struct

Completes the lifecycle action for the specified token or instance with the specified result.

This step is a part of the procedure for adding a lifecycle hook to an Auto Scaling group:

  1. (Optional) Create a Lambda function and a rule that allows CloudWatch Events to invoke your Lambda function when Amazon EC2 Auto Scaling launches or terminates instances.

  2. (Optional) Create a notification target and an IAM role. The target can be either an Amazon SQS queue or an Amazon SNS topic. The role allows Amazon EC2 Auto Scaling to publish lifecycle notifications to the target.

  3. Create the lifecycle hook. Specify whether the hook is used when the instances launch or terminate.

  4. If you need more time, record the lifecycle action heartbeat to keep the instance in a pending state.

  5. If you finish before the timeout period ends, complete the lifecycle action.

For more information, see Amazon EC2 Auto Scaling lifecycle hooks in the Amazon EC2 Auto Scaling User Guide.

Examples:

Request syntax example with placeholder values


lifecyclehook.complete({
  lifecycle_action_token: "LifecycleActionToken",
  lifecycle_action_result: "LifecycleActionResult", # required
  instance_id: "XmlStringMaxLen19",
})

Options Hash (options):

  • :lifecycle_action_token (String) —

    A universally unique identifier (UUID) that identifies a specific lifecycle action associated with an instance. Amazon EC2 Auto Scaling sends this token to the notification target you specified when you created the lifecycle hook.

  • :lifecycle_action_result (required, String) —

    The action for the group to take. This parameter can be either CONTINUE or ABANDON.

  • :instance_id (String) —

    The ID of the instance.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#delete ⇒ Struct

Deletes the specified lifecycle hook.

If there are any outstanding lifecycle actions, they are completed first (ABANDON for launching instances, CONTINUE for terminating instances).

Examples:

Request syntax example with placeholder values


lifecyclehook.delete()

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#group ⇒ AutoScalingGroup

Returns:

#put(options = {}) ⇒ Struct

Creates or updates a lifecycle hook for the specified Auto Scaling group.

A lifecycle hook tells Amazon EC2 Auto Scaling to perform an action on an instance when the instance launches (before it is put into service) or as the instance terminates (before it is fully terminated).

This step is a part of the procedure for adding a lifecycle hook to an Auto Scaling group:

  1. (Optional) Create a Lambda function and a rule that allows CloudWatch Events to invoke your Lambda function when Amazon EC2 Auto Scaling launches or terminates instances.

  2. (Optional) Create a notification target and an IAM role. The target can be either an Amazon SQS queue or an Amazon SNS topic. The role allows Amazon EC2 Auto Scaling to publish lifecycle notifications to the target.

  3. Create the lifecycle hook. Specify whether the hook is used when the instances launch or terminate.

  4. If you need more time, record the lifecycle action heartbeat to keep the instance in a pending state using the RecordLifecycleActionHeartbeat API call.

  5. If you finish before the timeout period ends, complete the lifecycle action using the CompleteLifecycleAction API call.

For more information, see Amazon EC2 Auto Scaling lifecycle hooks in the Amazon EC2 Auto Scaling User Guide.

If you exceed your maximum limit of lifecycle hooks, which by default is 50 per Auto Scaling group, the call fails.

You can view the lifecycle hooks for an Auto Scaling group using the DescribeLifecycleHooks API call. If you are no longer using a lifecycle hook, you can delete it by calling the DeleteLifecycleHook API.

Examples:

Request syntax example with placeholder values


lifecyclehook.put({
  lifecycle_transition: "LifecycleTransition",
  role_arn: "ResourceName",
  notification_target_arn: "NotificationTargetResourceName",
  notification_metadata: "XmlStringMaxLen1023",
  heartbeat_timeout: 1,
  default_result: "LifecycleActionResult",
})

Options Hash (options):

  • :lifecycle_transition (String) —

    The instance state to which you want to attach the lifecycle hook. The valid values are:

    • autoscaling:EC2_INSTANCE_LAUNCHING

    • autoscaling:EC2_INSTANCE_TERMINATING

    Required for new lifecycle hooks, but optional when updating existing hooks.

  • :role_arn (String) —

    The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target, for example, an Amazon SNS topic or an Amazon SQS queue.

    Required for new lifecycle hooks, but optional when updating existing hooks.

  • :notification_target_arn (String) —

    The ARN of the notification target that Amazon EC2 Auto Scaling uses to notify you when an instance is in the transition state for the lifecycle hook. This target can be either an SQS queue or an SNS topic.

    If you specify an empty string, this overrides the current ARN.

    This operation uses the JSON format when sending notifications to an Amazon SQS queue, and an email key-value pair format when sending notifications to an Amazon SNS topic.

    When you specify a notification target, Amazon EC2 Auto Scaling sends it a test message. Test messages contain the following additional key-value pair: "Event": "autoscaling:TEST_NOTIFICATION".

  • :notification_metadata (String) —

    Additional information that you want to include any time Amazon EC2 Auto Scaling sends a message to the notification target.

  • :heartbeat_timeout (Integer) —

    The maximum time, in seconds, that can elapse before the lifecycle hook times out. The range is from 30 to 7200 seconds. The default value is 3600 seconds (1 hour).

    If the lifecycle hook times out, Amazon EC2 Auto Scaling performs the action that you specified in the DefaultResult parameter. You can prevent the lifecycle hook from timing out by calling the RecordLifecycleActionHeartbeat API.

  • :default_result (String) —

    Defines the action the Auto Scaling group should take when the lifecycle hook timeout elapses or if an unexpected failure occurs. This parameter can be either CONTINUE or ABANDON. The default value is ABANDON.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#record_heartbeat(options = {}) ⇒ Struct

Records a heartbeat for the lifecycle action associated with the specified token or instance. This extends the timeout by the length of time defined using the PutLifecycleHook API call.

This step is a part of the procedure for adding a lifecycle hook to an Auto Scaling group:

  1. (Optional) Create a Lambda function and a rule that allows CloudWatch Events to invoke your Lambda function when Amazon EC2 Auto Scaling launches or terminates instances.

  2. (Optional) Create a notification target and an IAM role. The target can be either an Amazon SQS queue or an Amazon SNS topic. The role allows Amazon EC2 Auto Scaling to publish lifecycle notifications to the target.

  3. Create the lifecycle hook. Specify whether the hook is used when the instances launch or terminate.

  4. If you need more time, record the lifecycle action heartbeat to keep the instance in a pending state.

  5. If you finish before the timeout period ends, complete the lifecycle action.

For more information, see Auto Scaling lifecycle in the Amazon EC2 Auto Scaling User Guide.

Examples:

Request syntax example with placeholder values


lifecyclehook.record_heartbeat({
  lifecycle_action_token: "LifecycleActionToken",
  instance_id: "XmlStringMaxLen19",
})

Options Hash (options):

  • :lifecycle_action_token (String) —

    A token that uniquely identifies a specific lifecycle action associated with an instance. Amazon EC2 Auto Scaling sends this token to the notification target that you specified when you created the lifecycle hook.

  • :instance_id (String) —

    The ID of the instance.

Returns:

  • (Struct) —

    Returns an empty response.

See Also: