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 =

rubocop:disable Sorbet/ForbidTUntyped

T.let(::Pastel.new, T.untyped)
VERSION = 
'0.3.1'

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 ⇒ Object

: -> Configuration

Raises:



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

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

: (Configuration | Hash[String | Symbol, Object] | String | Pathname) -> void



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

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.to_s
  end
end

.find_backend(backend_name) ⇒ Object

Find the HAProxy backend config with a particular name.

@return: HAProxy backend config. : (Symbol | String) -> Configuration::Backend

Raises:



209
210
211
212
213
214
215
216
217
218
 
# File 'lib/capistrano/data_plane_api.rb', line 209

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) ⇒ Object

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

@return:

Two-element Array
where the first element is the HAProxy server config and the second one
is the HAProxy backend config

: (Symbol | String) -> [Configuration::Server, Configuration::Backend]



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/capistrano/data_plane_api.rb', line 228

def find_server_and_backend(deployment_stage)
  haproxy_server = T.let(nil, T.nilable(Configuration::Server))
  deployment_stage_str = deployment_stage.to_s

  # find the HAProxy backend that the
  # current deployment target is a part of
  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

  [T.must(haproxy_server), haproxy_backend]
end

.get_backend_servers_settings(backend_name, config: nil) ⇒ Object

: (Symbol | String, ::DataPlaneApi::Configuration?) -> Faraday::Response



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/capistrano/data_plane_api.rb', line 250

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,
    url:            haproxy_backend.api_url || configuration.api_url,
    parent:         config,
  )
  response = ::DataPlaneApi::Server.get_runtime_settings(
    backend: backend_name.to_s,
    config:  conf,
  )
  unless response.status.between?(200, 299)
    raise QueryError,
          "HAProxy query failed! Couldn't fetch servers' states"
  end

  response
end

.get_server_settings(backend_name, server_name, config: nil) ⇒ Object

: (Symbol | String, Symbol | String, ::DataPlaneApi::Configuration?) -> Faraday::Response



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/capistrano/data_plane_api.rb', line 271

def get_server_settings(backend_name, server_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,
    url:            haproxy_backend.api_url || configuration.api_url,
    parent:         config,
  )
  response = ::DataPlaneApi::Server.get_runtime_settings(
    backend: backend_name.to_s,
    name:    server_name.to_s,
    config:  conf,
  )
  unless response.status.between?(200, 299)
    raise QueryError,
          "HAProxy query failed! Couldn't fetch server's state"
  end

  response
end

.server_get_state(deployment_stage, config: nil) ⇒ Object

Get the state of the server.

@return: Server state : (String | Symbol, ::DataPlaneApi::Configuration?) -> Hash[String, untyped]?

Raises:

  • (Error) —

    The process failed due to some reason



196
197
198
199
200
201
202
 
# File 'lib/capistrano/data_plane_api.rb', line 196

def server_get_state(deployment_stage, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)

  # set the target server's state to `drain`
  response = get_server_settings(T.must(haproxy_backend.name), T.must(haproxy_server.name), config: config)
  response.body
end

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

Set server’s admin_state to ‘drain`.

@return: Server state after the change, or ‘nil`

when no change happened

: (String | Symbol, bool, ::DataPlaneApi::Configuration?) -> Hash[String, untyped]?

Parameters:

  • force: (defaults to: false) —

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

Raises:

  • (Error) —

    The process failed due to some reason



86
87
88
89
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
 
# File 'lib/capistrano/data_plane_api.rb', line 86

def server_set_drain(deployment_stage, force: false, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  servers = T.must haproxy_backend.servers
  return if 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,
    url:            haproxy_backend.api_url || configuration.api_url,
    parent:         config,
  )

  # 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) ⇒ Object

Set server’s admin_state to ‘maint`.

@return: Server state after the change, or ‘nil` when no change happened : (String | Symbol, bool, ::DataPlaneApi::Configuration?) -> Hash[String, untyped]?

Parameters:

  • force: (defaults to: false) —

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

Raises:

  • (Error) —

    The process failed due to some reason



123
124
125
126
127
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
 
# File 'lib/capistrano/data_plane_api.rb', line 123

def server_set_maint(deployment_stage, force: false, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  servers = T.must haproxy_backend.servers
  return if 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,
    url:            haproxy_backend.api_url || configuration.api_url,
    parent:         config,
  )

  # 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) ⇒ Object

Set server’s admin_state to ‘ready`

@return: Server state after the change, or ‘nil` when no change happened : (String | Symbol, ::DataPlaneApi::Configuration?) -> Hash[String, untyped]?

Raises:

  • (Error) —

    The process failed due to some reason



159
160
161
162
163
164
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
 
# File 'lib/capistrano/data_plane_api.rb', line 159

def server_set_ready(deployment_stage, config: nil)
  haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
  servers = T.must haproxy_backend.servers
  return if 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,
    url:            haproxy_backend.api_url || configuration.api_url,
    parent:         config,
  )

  # 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 ⇒ Object

Prints the current configuration in a human readable format.

: -> void



65
66
67
 
# File 'lib/capistrano/data_plane_api.rb', line 65

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

.show_state ⇒ Object

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

: -> void



73
74
75
76
77
 
# File 'lib/capistrano/data_plane_api.rb', line 73

def show_state
  TerminalPrintLoop.call do
    ShowState.call
  end
end