Module: Capistrano::DataPlaneApi

Extended by:
Helper
Defined in:
lib/capistrano/data_plane_api.rb,
lib/capistrano/data_plane_api/type.rb,
lib/capistrano/data_plane_api/deploy.rb,
lib/capistrano/data_plane_api/helper.rb,
lib/capistrano/data_plane_api/version.rb,
lib/capistrano/data_plane_api/diggable.rb,
lib/capistrano/data_plane_api/equatable.rb,
lib/capistrano/data_plane_api/show_state.rb,
lib/capistrano/data_plane_api/deploy/args.rb,
lib/capistrano/data_plane_api/deploy/group.rb,
lib/capistrano/data_plane_api/configuration.rb,
lib/capistrano/data_plane_api/deploy/helper.rb,
lib/capistrano/data_plane_api/deploy/server_stats.rb,
lib/capistrano/data_plane_api/terminal_print_loop.rb,
lib/capistrano/data_plane_api/configuration/server.rb,
lib/capistrano/data_plane_api/configuration/symbol.rb,
lib/capistrano/data_plane_api/configuration/backend.rb,
lib/capistrano/data_plane_api/deploy/deployment_stats.rb

Overview

Main module/namespace of the ‘capistrano-data_plane_api` gem.

Defined Under Namespace

Modules: Deploy, Diggable, Equatable, Helper, ShowState, TerminalPrintLoop Classes: Configuration, Error, NoBackendForThisStageError, NoOtherServerReadyError, NoSuchBackendError, NotConfiguredError, QueryError, Type, UpdateServerStateError

Constant Summary collapse

COLORS =

Returns:

  • (Pastel::Delegator) 
::Pastel.new
VERSION =

Returns:

  • (String) 
'0.1.5'

Constants included from Helper

Helper::ADMIN_STATE_COLORS, Helper::OPERATIONAL_STATE_COLORS

Class Method Summary collapse

Methods included from Helper

force_haproxy?, humanize_admin_state, humanize_backend_name, humanize_operational_state, no_haproxy?

Class Method Details

.configuration ⇒ Capistrano::DataPlaneApi::Configuration

Returns:

Raises:



33
34
35
36
37
38
39
40
41
 
# File 'lib/capistrano/data_plane_api.rb', line 33

def configuration
  raise NotConfiguredError, <<~ERR unless @configuration
    `Capistrano::DataPlaneApi` is not configured!
    You should register a configuration file like so:
      Capistrano::DataPlaneApi.configuration = '/path/to/your/file.yaml'
  ERR

  @configuration
end

.configuration=(val) ⇒ Object

Parameters:



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/capistrano/data_plane_api.rb', line 44

def configuration=(val)
  case val
  when ::Hash
    # as of now `shale` does not support
    # symbol keys in hashes, so
    # we convert it to JSON an back
    # to a Hash to convert all Symbols
    # to Strings
    @configuration = Configuration.from_json(val.to_json)
  when Configuration
    @configuration = val
  when ::String, ::Pathname
    @configuration = Configuration.from_file(val.to_s)
    @configuration.file_path = val
  else
    raise ::ArgumentError,
          "Configuration should be a `#{::Hash}`, `#{Configuration}`, #{::String} or #{::Pathname}" \
          ", received: #{val.inspect} (#{val.class.inspect})"
  end
end

.find_backend(backend_name) ⇒ Capistrano::DataPlaneApi::Configuration::Backend

Find the HAProxy backend config with a particular name.

Parameters:

  • backend_name (String)

Returns:

Raises:



201
202
203
204
205
206
207
208
209
210
 
# File 'lib/capistrano/data_plane_api.rb', line 201

def find_backend(backend_name)
  backend = configuration.backends.find { _1.name == backend_name }
  if backend.nil?
    raise NoSuchBackendError,
          'There is no HAProxy backend with this name! ' \
          "`#{backend_name.inspect}`"
  end

  backend
end

.find_server_and_backend(deployment_stage) ⇒ Capistrano::DataPlaneApi::Configuration::Server, Capistrano::DataPlaneApi::Configuration::Backend

Find the server and backend config for a particular deployment stage.

Parameters:

  • deployment_stage (Symbol, String)

Returns:



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/capistrano/data_plane_api.rb', line 220

def find_server_and_backend(deployment_stage)
  # @type [Capistrano::DataPlaneApi::Configuration::Server, nil]
  haproxy_server = nil
  deployment_stage_str = deployment_stage.to_s
  # find the HAProxy backend that the
  # current deployment target is a part of
  # @type [Capistrano::DataPlaneApi::Configuration::Backend]
  haproxy_backend =
    configuration.backends.each do |backend|
      haproxy_server = backend.servers.find { _1.stage == deployment_stage_str }
      break backend if haproxy_server
    end

  unless haproxy_backend.is_a?(Configuration::Backend)
    raise NoBackendForThisStageError,
          'There are no HAProxy backends for this deployment stage! ' \
          "#{deployment_stage.inspect} `#{configuration.file_path.inspect}`"
  end

  [haproxy_server, haproxy_backend]
end

.get_backend_servers_settings(backend_name, config: nil) ⇒ Faraday::Response

Parameters:

  • backend_name (String)
  • config (::DataPlaneApi::Configuration, nil) (defaults to: nil)

Returns:

  • (Faraday::Response) 


245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/capistrano/data_plane_api.rb', line 245

def get_backend_servers_settings(backend_name, config: nil)
  haproxy_backend = find_backend(backend_name)
  conf = ::DataPlaneApi::Configuration.new(
    basic_user: haproxy_backend.basic_user || @configuration.basic_user,
    basic_password: haproxy_backend.basic_password || @configuration.basic_password,
    parent: config,
    url: configuration.api_url
  )
  response = ::DataPlaneApi::Server.get_runtime_settings(backend: backend_name, config: conf)
  unless response.status.between?(200, 299)
    raise QueryError,
          "HAProxy query failed! Couldn't fetch servers' states"
  end

  response
end

.server_set_drain(deployment_stage, force: false, config: nil) ⇒ Hash, FalseClass

Set server’s admin_state to ‘drain`.

Parameters:

  • deployment_stage (Symbol)
  • force (Boolean) (defaults to: false) —

    Change the server’s state even when no other server is ‘up`

  • config (::DataPlaneApi::Configuration, nil) (defaults to: nil)

Returns:

  • (Hash, FalseClass) —

    Server state after the change, or ‘false` when no change happened

Raises:

  • (Error) —

    The process failed due to some reason



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/capistrano/data_plane_api.rb', line 90

def server_set_drain(deployment_stage, force: false, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server

  validate_backend_state(haproxy_backend, haproxy_server) unless force

  conf = ::DataPlaneApi::Configuration.new(
    basic_user: haproxy_backend.basic_user || @configuration.basic_user,
    basic_password: haproxy_backend.basic_password || @configuration.basic_password,
    parent: config,
    url: configuration.api_url
  )

  # set the target server's state to `drain`
  response =
    ::DataPlaneApi::Server.update_transient_settings(
      backend: haproxy_backend.name,
      name: haproxy_server.name,
      settings: { admin_state: :drain },
      config: conf
    )

  unless response.status.between?(200, 299) && response.body['admin_state'] == 'drain'
    raise UpdateServerStateError,
          "HAProxy mutation failed! Couldn't set server's `admin_state` to `drain`."
  end

  response.body
end

.server_set_maint(deployment_stage, force: false, config: nil) ⇒ Hash, FalseClass

Set server’s admin_state to ‘maint`.

Parameters:

  • deployment_stage (Symbol)
  • force (Boolean) (defaults to: false) —

    Change the server’s state even when no other server is ‘up`

  • config (::DataPlaneApi::Configuration, nil) (defaults to: nil)

Returns:

  • (Hash, FalseClass) —

    Server state after the change, or ‘false` when no change happened

Raises:

  • (Error) —

    The process failed due to some reason



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/capistrano/data_plane_api.rb', line 128

def server_set_maint(deployment_stage, force: false, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server

  validate_backend_state(haproxy_backend, haproxy_server) unless force

  conf = ::DataPlaneApi::Configuration.new(
    basic_user: haproxy_backend.basic_user || @configuration.basic_user,
    basic_password: haproxy_backend.basic_password || @configuration.basic_password,
    parent: config,
    url: configuration.api_url
  )

  # set the target server's state to `maint`
  response =
    ::DataPlaneApi::Server.update_transient_settings(
      backend: haproxy_backend.name,
      name: haproxy_server.name,
      settings: { admin_state: :maint },
      config: conf
    )

  unless response.status.between?(200, 299) && response.body['admin_state'] == 'maint'
    raise UpdateServerStateError,
          "HAProxy mutation failed! Couldn't set server's `admin_state` to `drain`."
  end

  response.body
end

.server_set_ready(deployment_stage, config: nil) ⇒ Hash, FalseClass

Set server’s admin_state to ‘ready`

Parameters:

  • deployment_stage (Symbol)
  • config (::DataPlaneApi::Configuration, nil) (defaults to: nil)

Returns:

  • (Hash, FalseClass) —

    Server state after the change, or ‘false` when no change happened

Raises:

  • (Error) —

    The process failed due to some reason



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/capistrano/data_plane_api.rb', line 165

def server_set_ready(deployment_stage, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server

  conf = ::DataPlaneApi::Configuration.new(
    basic_user: haproxy_backend.basic_user || @configuration.basic_user,
    basic_password: haproxy_backend.basic_password || @configuration.basic_password,
    parent: config,
    url: configuration.api_url
  )

  # set the target server's state to `drain`
  response =
    ::DataPlaneApi::Server.update_transient_settings(
      backend: haproxy_backend.name,
      name: haproxy_server.name,
      settings: { admin_state: :ready },
      config: conf
    )

  unless response.status.between?(200, 299) &&
         response.body['admin_state'] == 'ready' &&
         response.body['operational_state'] == 'up'

    raise UpdateServerStateError,
          "HAProxy mutation failed! Couldn't set server's `admin_state` to `ready`."
  end

  response.body
end

.show_config ⇒ void

This method returns an undefined value.

Prints the current configuration in a human readable format.



68
69
70
 
# File 'lib/capistrano/data_plane_api.rb', line 68

def show_config
  puts ::JSON.pretty_generate(configuration.to_h)
end

.show_state ⇒ void

This method returns an undefined value.

Prints the current state of all backends and their servers in a human readable format.



76
77
78
79
80
 
# File 'lib/capistrano/data_plane_api.rb', line 76

def show_state
  TerminalPrintLoop.call do
    ShowState.call
  end
end