Class: Kamal::Configuration::Proxy

Inherits:
Object
  • Object
show all
Includes:
Validation
Defined in:
lib/kamal/configuration/proxy.rb

Direct Known Subclasses

Loadbalancer

Defined Under Namespace

Classes: Acme, Boot, Run

Constant Summary collapse

DEFAULT_LOG_REQUEST_HEADERS = 
[ "Cache-Control", "Last-Modified", "User-Agent" ]
CONTAINER_NAME = 
"kamal-proxy"
LOADBALANCER_CONTAINER_NAME = 
"kamal-loadbalancer"
CLIENT_CA_FILENAME = 
"client-ca.pem"
DEFAULT_COMPRESSION_ENCODINGS =

What compress: true offers. kamal-proxy has no "on" state without an explicit list - --compress is the list - so the shorthand has to pick. Best ratio first, matching the proxy's own default ordering; the client's Accept-Encoding q-values still outrank this preference.

%w[ zstd br gzip ].freeze
SUPPORTED_COMPRESSION_ENCODINGS = 
%w[ gzip br zstd ].freeze
COMPRESSION_ENCODING_ALIASES =

kamal-proxy maps brotli onto the br token that travels in Content-Encoding.

{ "brotli" => "br" }.freeze
DEPLOY_OPTION_DISPOSITIONS =

The layering contract. When the fork's load balancer fronts the per-host proxies, every deploy option lives at exactly one layer — or at both, on purpose. Nothing is allowed to be undecided: #deploy_options refuses to emit a key that has no disposition here, and test/proxy_layering_test.rb fails the build if a new option is added without one.

:edge    — only where clients connect. Stripped from the per-app deploy,
         applied by the load balancer.
:per_app — only next to the app. Applied per-app, stripped from the
         load balancer.
:both    — each layer genuinely has its own copy of the concern.

Without load balancing the single proxy is every layer at once and the whole surface applies to it.

{
  # --- Edge: TLS terminates where the handshake happens, and kamal-proxy
  # gates TLSRedirect on TLSEnabled, so the whole family travels together.
  host: :edge,
  tls: :edge,
  "tls-staging": :edge,
  "tls-certificate-path": :edge,
  "tls-private-key-path": :edge,
  "tls-redirect": :edge,
  "tls-domains-source": :edge,
  "tls-domains-interval": :edge,
  "tls-domains-batch-size": :edge,
  "tls-on-demand-url": :edge,
  "tls-client-ca-path": :edge,

  # --- Edge: the load balancer is the only proxy that ever sees the real
  # client address — an allow list on a per-app proxy would refuse every
  # request (its peer is the LB) and one limiter would count the whole
  # fleet as a single client.
  "allow-ip": :edge,
  "deny-ip": :edge,
  "deny-user-agent": :edge,
  "trusted-proxy": :edge,
  "client-ip-header": :edge,
  "rate-limit": :edge,
  "rate-limit-burst": :edge,
  "rate-limit-exempt": :edge,

  # --- Edge: kamal-proxy deletes the Authorization header once a service
  # enforces basic auth, so an inner proxy would 401 the credential-less
  # request the load balancer forwards. Credentials belong at the edge only.
  "basic-auth": :edge,

  # --- Edge: both layers used to pin with the same cookie name but separate
  # HMAC keys, so the inner proxy clobbered the edge pin every other request.
  # Only the edge pin can stick.
  "session-affinity": :edge,
  "session-affinity-cookie": :edge,

  # --- Edge: redirectURLIfNeeded consults r.TLS only, so behind the LB a
  # per-app redirect emits http:// Locations to HTTPS clients. The dynamic
  # redirect map answers where clients connect, for the same reason.
  "canonical-host": :edge,
  redirect: :edge,
  "redirects-source": :edge,
  "redirects-interval": :edge,

  # --- Edge: one response cache, at the edge — two layers of cache would
  # double the storage and let the inner cache serve entries the edge
  # already invalidated. The store it writes into is proxy-wide (proxy/run).
  cache: :edge,
  "cache-max-ttl": :edge,
  "cache-max-body": :edge,
  "cache-max-variants": :edge,
  "cache-vary-header": :edge,
  "cache-vary-cookie": :edge,
  "cache-allow-set-cookie": :edge,

  # --- Edge: splitting reads from writes is a fleet-level routing decision;
  # per-app proxies each front a single host and have nothing to split.
  "read-target": :edge,
  "read-target-websockets": :edge,
  "writer-affinity-timeout": :edge,

  # --- Per-app: applied next to the app, exactly once. The LB forwards to
  # the per-host proxies, so running these at both layers would add a header
  # twice or run a rewrite over its own output.
  "set-request-header": :per_app,
  "add-request-header": :per_app,
  "remove-request-header": :per_app,
  "set-response-header": :per_app,
  "add-response-header": :per_app,
  "remove-response-header": :per_app,
  rewrite: :per_app,
  "intercept-errors": :per_app,

  # --- Per-app: sleep stops and starts app containers through the docker
  # socket — the LB has neither the socket nor the containers, and its
  # targets are host addresses, so a sleep flag there fails the deploy.
  "sleep-after": :per_app,
  "wake-timeout": :per_app,
  "sleep-container": :per_app,

  # --- Per-app: compress once, next to the app. Double-running was only
  # safe by accident of the Content-Encoding guard.
  compress: :per_app,
  "compress-content-type": :per_app,
  "compress-min-length": :per_app,

  # --- Both, deliberately: each layer has a real connection pool to its own
  # targets (LB -> per-host proxies, per-host proxy -> app containers), so
  # pool tuning and request deadlines apply to each hop.
  "target-timeout": :both,
  "target-max-conns": :both,
  "target-max-idle-conns": :both,
  "target-idle-conn-timeout": :both,
  "target-dial-timeout": :both,
  "target-disable-keep-alives": :both,
  "target-try-duration": :both,
  "target-try-interval": :both,
  "path-timeout": :both,
  "request-timeout": :both,
  "path-request-timeout": :both,
  "deploy-timeout": :both,
  "drain-timeout": :both,

  # --- Both: each layer health-checks its own targets, buffers its own
  # connections, routes its own paths and writes its own logs.
  "health-check-interval": :both,
  "health-check-timeout": :both,
  "health-check-path": :both,
  "health-check-port": :both,
  "health-check-host": :both,
  "buffer-requests": :both,
  "buffer-responses": :both,
  "buffer-memory": :both,
  "max-request-body": :both,
  "max-response-body": :both,
  "path-prefix": :both,
  "strip-path-prefix": :both,
  "forward-headers": :both,
  "log-request-header": :both,
  "log-response-header": :both,
  "error-pages": :both,
  "exclude-metrics-path": :both
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Validation

#validate!, #validation_yml

Constructor Details

#initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy", load_balanced: true) ⇒ Proxy

load_balanced: false marks a registration the fork's load balancer can never front - accessories, whose targets it does not collect. Such a proxy keeps its own host/TLS/basic-auth instead of deferring them to the edge.



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/kamal/configuration/proxy.rb', line 178

def initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy", load_balanced: true)
  @config = config
  @proxy_config = proxy_config
  @proxy_config = {} if @proxy_config.nil?
  @role_name = role_name
  @load_balanced = load_balanced
  @secrets = secrets
  validate! @proxy_config, with: Kamal::Configuration::Validator::Proxy, context: context
  @run = Kamal::Configuration::Proxy::Run.new(config, run_config: @proxy_config["run"], context: "#{context}/run") if @proxy_config && @proxy_config["run"].present?
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



173
174
175
 
# File 'lib/kamal/configuration/proxy.rb', line 173

def config
  @config
end

#proxy_config ⇒ Object (readonly)

Returns the value of attribute proxy_config.



173
174
175
 
# File 'lib/kamal/configuration/proxy.rb', line 173

def proxy_config
  @proxy_config
end

#role_name ⇒ Object (readonly)

Returns the value of attribute role_name.



173
174
175
 
# File 'lib/kamal/configuration/proxy.rb', line 173

def role_name
  @role_name
end

#run ⇒ Object (readonly)

Returns the value of attribute run.



173
174
175
 
# File 'lib/kamal/configuration/proxy.rb', line 173

def run
  @run
end

#secrets ⇒ Object (readonly)

Returns the value of attribute secrets.



173
174
175
 
# File 'lib/kamal/configuration/proxy.rb', line 173

def secrets
  @secrets
end

Class Method Details

.disposition(key) ⇒ Object

Refusing beats guessing: a deploy option nobody placed would silently land on both layers, which is how session affinity broke in the only topology where it matters.



164
165
166
167
168
169
 
# File 'lib/kamal/configuration/proxy.rb', line 164

def self.disposition(key)
  DEPLOY_OPTION_DISPOSITIONS.fetch(key) do
    raise Kamal::ConfigurationError,
      "proxy deploy option --#{key} has no layering disposition - add it to Kamal::Configuration::Proxy::DEPLOY_OPTION_DISPOSITIONS"
  end
end

Instance Method Details

#all_deploy_options ⇒ Object

The full option surface before the layering contract is applied — what a single proxy (no load balancer) deploys with. Public so the layering canary can enumerate every key the gem emits.



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
 
# File 'lib/kamal/configuration/proxy.rb', line 326

def all_deploy_options
  {
    host: hosts,
    tls: ssl? ? true : nil,
    "tls-staging": proxy_config["ssl_staging"] ? true : nil,
    "tls-certificate-path": container_tls_cert,
    "tls-private-key-path": container_tls_key,
    "deploy-timeout": seconds_duration(config.deploy_timeout),
    "drain-timeout": seconds_duration(config.drain_timeout),
    "health-check-interval": seconds_duration(proxy_config.dig("healthcheck", "interval")),
    "health-check-timeout": seconds_duration(proxy_config.dig("healthcheck", "timeout")),
    "health-check-path": healthcheck_path,
    "health-check-port": proxy_config.dig("healthcheck", "port"),
    "health-check-host": proxy_config.dig("healthcheck", "host"),
    "target-timeout": seconds_duration(proxy_config["response_timeout"]),
    "read-target": proxy_config.dig("read_routing", "targets").presence,
    "read-target-websockets": proxy_config.dig("read_routing", "websockets") ? true : nil,
    "writer-affinity-timeout": seconds_duration(proxy_config.dig("read_routing", "writer_affinity_timeout")),
    "path-timeout": path_timeout_args("path_response_timeouts"),
    "request-timeout": seconds_duration(proxy_config["request_timeout"]),
    "path-request-timeout": path_timeout_args("path_request_timeouts"),
    "buffer-requests": proxy_config.fetch("buffering", { "requests": true }).fetch("requests", true),
    "buffer-responses": proxy_config.fetch("buffering", { "responses": true }).fetch("responses", true),
    "buffer-memory": proxy_config.dig("buffering", "memory"),
    "max-request-body": proxy_config.dig("buffering", "max_request_body"),
    "max-response-body": proxy_config.dig("buffering", "max_response_body"),
    "path-prefix": path_prefixes,
    "strip-path-prefix": proxy_config.dig("strip_path_prefix"),
    "forward-headers": proxy_config.dig("forward_headers"),
    "tls-redirect": proxy_config.dig("ssl_redirect"),
    "basic-auth": basic_auth_credential,
    "log-request-header": proxy_config.dig("logging", "request_headers") || DEFAULT_LOG_REQUEST_HEADERS,
    "log-response-header": proxy_config.dig("logging", "response_headers"),
    "error-pages": error_pages,
    # A deploy flag despite reading like metrics configuration: where the
    # metrics are served and who may read them are proxy-wide and live under
    # proxy/run, but which of *this service's* paths are counted is per service.
    "exclude-metrics-path": proxy_config["exclude_metrics_paths"].presence
  }.merge(ssl_domains_options).merge(tls_options).merge(cache_options).merge(compress_options)
    .merge(access_control_options).merge(traffic_options).merge(lifecycle_options)
    .merge(target_options).compact
end

#app_port ⇒ Object 



189
190
191
 
# File 'lib/kamal/configuration/proxy.rb', line 189

def app_port
  proxy_config.fetch("app_port", 80)
end

#certificate_pem_content ⇒ Object 



238
239
240
241
242
 
# File 'lib/kamal/configuration/proxy.rb', line 238

def certificate_pem_content
  ssl = proxy_config["ssl"]
  return nil unless ssl.is_a?(Hash)
  secrets[ssl["certificate_pem"]]
end

#client_ca? ⇒ Boolean

Returns:

  • (Boolean) 


286
287
288
 
# File 'lib/kamal/configuration/proxy.rb', line 286

def client_ca?
  client_ca_pem.present?
end

#client_ca_pem ⇒ Object

The name of a secret in .kamal/secrets holding the CA bundle client certificates must chain to - mirroring ssl.certificate_pem, not a local file path. Kamal uploads the content into the app's TLS directory, which the proxy container already mounts, and hands the proxy the path it sees there.



282
283
284
 
# File 'lib/kamal/configuration/proxy.rb', line 282

def client_ca_pem
  ssl_config["client_ca_pem"]
end

#client_ca_pem_content ⇒ Object

Resolved at upload time, not config time, so kamal app logs and friends work on machines without the secret. A blank secret raises like basic_auth.password_secret - silently deploying without the client CA would turn mTLS off.



294
295
296
297
298
299
300
 
# File 'lib/kamal/configuration/proxy.rb', line 294

def client_ca_pem_content
  secrets[client_ca_pem].tap do |content|
    if content.blank?
      raise Kamal::ConfigurationError, "proxy/ssl: client_ca_pem secret '#{client_ca_pem}' is empty"
    end
  end
end

#container_client_ca ⇒ Object 



306
307
308
 
# File 'lib/kamal/configuration/proxy.rb', line 306

def container_client_ca
  tls_file_path(config.proxy_boot.tls_container_directory, CLIENT_CA_FILENAME) if client_ca?
end

#container_tls_cert ⇒ Object 



258
259
260
 
# File 'lib/kamal/configuration/proxy.rb', line 258

def container_tls_cert
  tls_path(config.proxy_boot.tls_container_directory, "cert.pem")
end

#container_tls_key ⇒ Object 



262
263
264
 
# File 'lib/kamal/configuration/proxy.rb', line 262

def container_tls_key
  tls_path(config.proxy_boot.tls_container_directory, "key.pem") if custom_ssl_certificate?
end

#custom_ssl_certificate? ⇒ Boolean

Returns:

  • (Boolean) 


232
233
234
235
236
 
# File 'lib/kamal/configuration/proxy.rb', line 232

def custom_ssl_certificate?
  ssl = proxy_config["ssl"]
  return false unless ssl.is_a?(Hash)
  ssl["certificate_pem"].present? && ssl["private_key_pem"].present?
end

#deploy_command_args(target:) ⇒ Object 



369
370
371
 
# File 'lib/kamal/configuration/proxy.rb', line 369

def deploy_command_args(target:)
  optionize ({ target: "#{target}:#{app_port}" }).merge(deploy_options), with: "="
end

#deploy_options ⇒ Object 



319
320
321
 
# File 'lib/kamal/configuration/proxy.rb', line 319

def deploy_options
  all_deploy_options.select { |key, _| retained_dispositions.include?(self.class.disposition(key)) }
end

#effective_loadbalancer ⇒ Object 



218
219
220
221
222
223
224
225
226
 
# File 'lib/kamal/configuration/proxy.rb', line 218

def effective_loadbalancer
  return nil unless load_balanced?
  return false if loadbalancer == false
  return primary_role_first_host if loadbalancer == true
  return loadbalancer if loadbalancer.present?
  return primary_role_first_host if auto_load_balanced_primary_role?

  nil
end

#healthcheck_path ⇒ Object

Nil when unset: the default lives in kamal-proxy, not here.



315
316
317
 
# File 'lib/kamal/configuration/proxy.rb', line 315

def healthcheck_path
  proxy_config.dig("healthcheck", "path")
end

#host_client_ca ⇒ Object 



302
303
304
 
# File 'lib/kamal/configuration/proxy.rb', line 302

def host_client_ca
  tls_file_path(config.proxy_boot.tls_directory, CLIENT_CA_FILENAME) if client_ca?
end

#host_tls_cert ⇒ Object 



250
251
252
 
# File 'lib/kamal/configuration/proxy.rb', line 250

def host_tls_cert
  tls_path(config.proxy_boot.tls_directory, "cert.pem")
end

#host_tls_key ⇒ Object 



254
255
256
 
# File 'lib/kamal/configuration/proxy.rb', line 254

def host_tls_key
  tls_path(config.proxy_boot.tls_directory, "key.pem")
end

#hosts ⇒ Object 



197
198
199
 
# File 'lib/kamal/configuration/proxy.rb', line 197

def hosts
  proxy_config["hosts"] || proxy_config["host"]&.split(",") || []
end

#load_balanced? ⇒ Boolean

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/kamal/configuration/proxy.rb', line 214

def load_balanced?
  @load_balanced
end

#load_balancing? ⇒ Boolean

Returns:

  • (Boolean) 


210
211
212
 
# File 'lib/kamal/configuration/proxy.rb', line 210

def load_balancing?
  effective_loadbalancer.present?
end

#loadbalancer ⇒ Object 



201
202
203
 
# File 'lib/kamal/configuration/proxy.rb', line 201

def loadbalancer
  proxy_config["loadbalancer"]
end

#loadbalancer_on_proxy_host? ⇒ Boolean

Returns:

  • (Boolean) 


228
229
230
 
# File 'lib/kamal/configuration/proxy.rb', line 228

def loadbalancer_on_proxy_host?
  load_balancing? && config.proxy_hosts.include?(effective_loadbalancer)
end

#merge(other) ⇒ Object 



401
402
403
 
# File 'lib/kamal/configuration/proxy.rb', line 401

def merge(other)
  self.class.new config: config, proxy_config: other.proxy_config.deep_merge(proxy_config), role_name: role_name, secrets: secrets, load_balanced: load_balanced?
end

#on_demand_url ⇒ Object 



273
274
275
 
# File 'lib/kamal/configuration/proxy.rb', line 273

def on_demand_url
  ssl_config["on_demand_url"]
end

#path_prefixes ⇒ Object 



310
311
312
 
# File 'lib/kamal/configuration/proxy.rb', line 310

def path_prefixes
  proxy_config["path_prefixes"] || proxy_config["path_prefix"]&.split(",") || []
end

#private_key_pem_content ⇒ Object 



244
245
246
247
248
 
# File 'lib/kamal/configuration/proxy.rb', line 244

def private_key_pem_content
  ssl = proxy_config["ssl"]
  return nil unless ssl.is_a?(Hash)
  secrets[ssl["private_key_pem"]]
end

#reboot_on_deploy? ⇒ Boolean

Root-level proxy setting only; ignored inside role-specific proxy blocks.

Returns:

  • (Boolean) 


206
207
208
 
# File 'lib/kamal/configuration/proxy.rb', line 206

def reboot_on_deploy?
  proxy_config.fetch("reboot_on_deploy", true)
end

#rollout_deploy_command_args(target:) ⇒ Object 



382
383
384
 
# File 'lib/kamal/configuration/proxy.rb', line 382

def rollout_deploy_command_args(target:)
  optionize ({ target: "#{target}:#{app_port}" }).merge(rollout_deploy_options), with: "="
end

#rollout_deploy_options ⇒ Object

kamal-proxy rollout deploy only accepts the target and the timeouts - the service already exists, so it keeps the host, TLS, buffering and logging options of the live deploy.



375
376
377
378
379
380
 
# File 'lib/kamal/configuration/proxy.rb', line 375

def rollout_deploy_options
  {
    "deploy-timeout": seconds_duration(config.deploy_timeout),
    "drain-timeout": seconds_duration(config.drain_timeout)
  }.compact
end

#rollout_set_command_args(percent: nil, list: nil) ⇒ Object 



386
387
388
 
# File 'lib/kamal/configuration/proxy.rb', line 386

def rollout_set_command_args(percent: nil, list: nil)
  optionize({ percent: percent, list: list }.compact, with: "=")
end

#ssl? ⇒ Boolean

Returns:

  • (Boolean) 


193
194
195
 
# File 'lib/kamal/configuration/proxy.rb', line 193

def ssl?
  proxy_config.fetch("ssl", false)
end

#ssl_config ⇒ Object

Everything TLS lives in the one ssl hash - certificate material, on-demand issuance and the mTLS client CA. One naming family instead of a separate tls: block.



269
270
271
 
# File 'lib/kamal/configuration/proxy.rb', line 269

def ssl_config
  proxy_config["ssl"].is_a?(Hash) ? proxy_config["ssl"] : {}
end

#stop_command_args(**options) ⇒ Object 



397
398
399
 
# File 'lib/kamal/configuration/proxy.rb', line 397

def stop_command_args(**options)
  optionize stop_options(**options), with: "="
end

#stop_options(drain_timeout: nil, message: nil) ⇒ Object 



390
391
392
393
394
395
 
# File 'lib/kamal/configuration/proxy.rb', line 390

def stop_options(drain_timeout: nil, message: nil)
  {
    "drain-timeout": seconds_duration(drain_timeout),
    message: message
  }.compact
end