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

Class: Aws::AutoScaling::LifecycleHook

Inherits:
Object
  • Object
show all
Defined in:
gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb

Defined Under Namespace

Classes: Collection

Actions collapse

Associations collapse

Read-Only Attributes collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of LifecycleHook

Overloads:

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

    Parameters:

    • group_name (String)
    • name (String)

    Options Hash (options):

  • #initialize(options = {}) ⇒ LifecycleHook

    Options Hash (options):

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


21
22
23
24
25
26
27
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 21

def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @group_name = extract_group_name(args, options)
  @name = extract_name(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
end

Instance Method Details

#clientClient

Returns:



106
107
108
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 106

def client
  @client
end

#complete(options = {}) ⇒ Types::CompleteLifecycleActionAnswer

Examples:

Request syntax with placeholder values


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

Parameters:

  • options (Hash) (defaults to: {})

    ({})

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:



257
258
259
260
261
262
263
264
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 257

def complete(options = {})
  options = options.merge(
    auto_scaling_group_name: @group_name,
    lifecycle_hook_name: @name
  )
  resp = @client.complete_lifecycle_action(options)
  resp.data
end

#dataTypes::LifecycleHook

Returns the data for this Aws::AutoScaling::LifecycleHook. Calls Client#describe_lifecycle_hooks if #data_loaded? is false.

Returns:



129
130
131
132
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 129

def data
  load unless @data
  @data
end

#data_loaded?Boolean

Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.

Returns:

  • (Boolean)

    Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.



137
138
139
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 137

def data_loaded?
  !!@data
end

#default_resultString

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

Returns:

  • (String)


99
100
101
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 99

def default_result
  data[:default_result]
end

#delete(options = {}) ⇒ Types::DeleteLifecycleHookAnswer

Examples:

Request syntax with placeholder values


lifecycle_hook.delete()

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Returns:



271
272
273
274
275
276
277
278
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 271

def delete(options = {})
  options = options.merge(
    auto_scaling_group_name: @group_name,
    lifecycle_hook_name: @name
  )
  resp = @client.delete_lifecycle_hook(options)
  resp.data
end

#global_timeoutInteger

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)


90
91
92
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 90

def global_timeout
  data[:global_timeout]
end

#groupAutoScalingGroup

Returns:



373
374
375
376
377
378
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 373

def group
  AutoScalingGroup.new(
    name: @group_name,
    client: @client
  )
end

#group_nameString Also known as: auto_scaling_group_name

Returns:

  • (String)


32
33
34
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 32

def group_name
  @group_name
end

#heartbeat_timeoutInteger

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 default action. You can prevent the lifecycle hook from timing out by calling RecordLifecycleActionHeartbeat.

Returns:

  • (Integer)


81
82
83
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 81

def heartbeat_timeout
  data[:heartbeat_timeout]
end

#lifecycle_transitionString

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

  • autoscaling:EC2_INSTANCE_LAUNCHING

  • autoscaling:EC2_INSTANCE_TERMINATING

Returns:

  • (String)


50
51
52
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 50

def lifecycle_transition
  data[:lifecycle_transition]
end

#loadself Also known as: reload

Loads, or reloads #data for the current Aws::AutoScaling::LifecycleHook. Returns self making it possible to chain methods.

lifecycle_hook.reload.data

Returns:

  • (self)


116
117
118
119
120
121
122
123
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 116

def load
  resp = @client.describe_lifecycle_hooks(
    auto_scaling_group_name: @group_name,
    lifecycle_hook_names: [@name]
  )
  @data = resp.lifecycle_hooks[0]
  self
end

#nameString Also known as: lifecycle_hook_name

Returns:

  • (String)


38
39
40
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 38

def name
  @name
end

#notification_metadataString

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

Returns:

  • (String)


72
73
74
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 72

def 
  data[:notification_metadata]
end

#notification_target_arnString

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)


58
59
60
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 58

def notification_target_arn
  data[:notification_target_arn]
end

#put(options = {}) ⇒ Types::PutLifecycleHookAnswer

Examples:

Request syntax with placeholder values


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

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Options Hash (options):

  • :lifecycle_transition (String)

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

    • autoscaling:EC2_INSTANCE_LAUNCHING

    • autoscaling:EC2_INSTANCE_TERMINATING

    This parameter is 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.

    This parameter is 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 will use 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 contains the following additional key/value pair: "Event": "autoscaling:TEST_NOTIFICATION".

  • :notification_metadata (String)

    Contains 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 is 3600 seconds (1 hour).

    If the lifecycle hook times out, Amazon EC2 Auto Scaling performs the default action. You can prevent the lifecycle hook from timing out by calling RecordLifecycleActionHeartbeat.

  • :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:



337
338
339
340
341
342
343
344
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 337

def put(options = {})
  options = options.merge(
    auto_scaling_group_name: @group_name,
    lifecycle_hook_name: @name
  )
  resp = @client.put_lifecycle_hook(options)
  resp.data
end

#record_heartbeat(options = {}) ⇒ Types::RecordLifecycleActionHeartbeatAnswer

Examples:

Request syntax with placeholder values


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

Parameters:

  • options (Hash) (defaults to: {})

    ({})

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 you specified when you created the lifecycle hook.

  • :instance_id (String)

    The ID of the instance.

Returns:



361
362
363
364
365
366
367
368
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 361

def record_heartbeat(options = {})
  options = options.merge(
    auto_scaling_group_name: @group_name,
    lifecycle_hook_name: @name
  )
  resp = @client.record_lifecycle_action_heartbeat(options)
  resp.data
end

#role_arnString

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

Returns:

  • (String)


65
66
67
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 65

def role_arn
  data[:role_arn]
end

#wait_until(options = {}, &block) ⇒ Resource

Deprecated.

Use [Aws::AutoScaling::Client] #wait_until instead

Note:

The waiting operation is performed on a copy. The original resource remains unchanged

Waiter polls an API operation until a resource enters a desired state.

Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

Example

instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }

Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

Callbacks

You can be notified before each polling attempt and before each delay. If you throw :success or :failure from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

attempts attempt in seconds invoked before each attempt invoked before each wait

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 10

    Maximum number of

  • :delay (Integer) — default: 10

    Delay between each

  • :before_attempt (Proc) — default: nil

    Callback

  • :before_wait (Proc) — default: nil

    Callback

Returns:

  • (Resource)

    if the waiter was successful

Raises:

  • (Aws::Waiters::Errors::FailureStateError)

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

    yet successful.

  • (Aws::Waiters::Errors::UnexpectedError)

    Raised when an error is encountered while polling for a resource that is not expected.

  • (NotImplementedError)

    Raised when the resource does not



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
# File 'gems/aws-sdk-autoscaling/lib/aws-sdk-autoscaling/lifecycle_hook.rb', line 219

def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end