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,
  "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.
  "canonical-host": :edge,
  redirect: :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.



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/kamal/configuration/proxy.rb', line 173

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.



168
169
170
 
# File 'lib/kamal/configuration/proxy.rb', line 168

def config
  @config
end

#proxy_config ⇒ Object (readonly)

Returns the value of attribute proxy_config.



168
169
170
 
# File 'lib/kamal/configuration/proxy.rb', line 168

def proxy_config
  @proxy_config
end

#role_name ⇒ Object (readonly)

Returns the value of attribute role_name.



168
169
170
 
# File 'lib/kamal/configuration/proxy.rb', line 168

def role_name
  @role_name
end

#run ⇒ Object (readonly)

Returns the value of attribute run.



168
169
170
 
# File 'lib/kamal/configuration/proxy.rb', line 168

def run
  @run
end

#secrets ⇒ Object (readonly)

Returns the value of attribute secrets.



168
169
170
 
# File 'lib/kamal/configuration/proxy.rb', line 168

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.



159
160
161
162
163
164
 
# File 'lib/kamal/configuration/proxy.rb', line 159

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.



321
322
323
324
325
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
 
# File 'lib/kamal/configuration/proxy.rb', line 321

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 



184
185
186
 
# File 'lib/kamal/configuration/proxy.rb', line 184

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

#certificate_pem_content ⇒ Object 



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

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) 


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

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.



277
278
279
 
# File 'lib/kamal/configuration/proxy.rb', line 277

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.



289
290
291
292
293
294
295
 
# File 'lib/kamal/configuration/proxy.rb', line 289

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 



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

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

#container_tls_cert ⇒ Object 



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

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

#container_tls_key ⇒ Object 



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

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) 


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

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 



364
365
366
 
# File 'lib/kamal/configuration/proxy.rb', line 364

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

#deploy_options ⇒ Object 



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

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

#effective_loadbalancer ⇒ Object 



213
214
215
216
217
218
219
220
221
 
# File 'lib/kamal/configuration/proxy.rb', line 213

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.



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

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

#host_client_ca ⇒ Object 



297
298
299
 
# File 'lib/kamal/configuration/proxy.rb', line 297

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

#host_tls_cert ⇒ Object 



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

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

#host_tls_key ⇒ Object 



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

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

#hosts ⇒ Object 



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

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

#load_balanced? ⇒ Boolean

Returns:

  • (Boolean) 


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

def load_balanced?
  @load_balanced
end

#load_balancing? ⇒ Boolean

Returns:

  • (Boolean) 


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

def load_balancing?
  effective_loadbalancer.present?
end

#loadbalancer ⇒ Object 



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

def loadbalancer
  proxy_config["loadbalancer"]
end

#loadbalancer_on_proxy_host? ⇒ Boolean

Returns:

  • (Boolean) 


223
224
225
 
# File 'lib/kamal/configuration/proxy.rb', line 223

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

#merge(other) ⇒ Object 



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

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 



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

def on_demand_url
  ssl_config["on_demand_url"]
end

#path_prefixes ⇒ Object 



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

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

#private_key_pem_content ⇒ Object 



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

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) 


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

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

#rollout_deploy_command_args(target:) ⇒ Object 



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

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.



370
371
372
373
374
375
 
# File 'lib/kamal/configuration/proxy.rb', line 370

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 



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

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

#ssl? ⇒ Boolean

Returns:

  • (Boolean) 


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

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.



264
265
266
 
# File 'lib/kamal/configuration/proxy.rb', line 264

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

#stop_command_args(**options) ⇒ Object 



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

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

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



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

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