kamal 1.8.3 → 2.0.0.beta1

data/lib/kamal/configuration/builder.rb

@@ -19,16 +19,38 @@ class Kamal::Configuration::Builder
     builder_config
   end
 
-  def multiarch?
-    builder_config["multiarch"] != false
+  def remote
+    builder_config["remote"]
   end
 
-  def local?
-    !!builder_config["local"]
+  def arches
+    Array(builder_config.fetch("arch", default_arch))
+  end
+
+  def local_arches
+    @local_arches ||= if local_disabled?
+      []
+    elsif remote
+      arches & [ Kamal::Utils.docker_arch ]
+    else
+      arches
+    end
+  end
+
+  def remote_arches
+    @remote_arches ||= if remote
+      arches - local_arches
+    else
+      []
+    end
   end
 
   def remote?
-    !!builder_config["remote"]
+    remote_arches.any?
+  end
+
+  def local?
+    !local_disabled? && (arches.empty? || local_arches.any?)
   end
 
   def cached?
@@ -40,7 +62,7 @@ class Kamal::Configuration::Builder
   end
 
   def secrets
-    builder_config["secrets"] || []
+    (builder_config["secrets"] || []).to_h { |key| [ key, config.secrets[key] ] }
   end
 
   def dockerfile
@@ -55,20 +77,12 @@ class Kamal::Configuration::Builder
     builder_config["context"] || "."
   end
 
-  def local_arch
-    builder_config["local"]["arch"] if local?
-  end
-
-  def local_host
-    builder_config["local"]["host"] if local?
+  def driver
+    builder_config.fetch("driver", "docker-container")
   end
 
-  def remote_arch
-    builder_config["remote"]["arch"] if remote?
-  end
-
-  def remote_host
-    builder_config["remote"]["host"] if remote?
+  def local_disabled?
+    builder_config["local"] == false
   end
 
   def cache_from
@@ -114,7 +128,23 @@ class Kamal::Configuration::Builder
       end
   end
 
+  def docker_driver?
+    driver == "docker"
+  end
+
   private
+    def valid?
+      if docker_driver?
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support remote builders" if remote
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support caching" if cached?
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support multiple arches" if arches.many?
+      end
+
+      if @options["cache"] && @options["cache"]["type"]
+        raise ArgumentError, "Invalid cache type: #{@options["cache"]["type"]}" unless [ "gha", "registry" ].include?(@options["cache"]["type"])
+      end
+    end
+
     def cache_image
       builder_config["cache"]&.fetch("image", nil) || "#{image}-build-cache"
     end
@@ -150,4 +180,8 @@ class Kamal::Configuration::Builder
     def pwd_sha
       Digest::SHA256.hexdigest(Dir.pwd)[0..12]
     end
+
+    def default_arch
+      docker_driver? ? [] : [ "amd64", "arm64" ]
+    end
 end

data/lib/kamal/configuration/docs/alias.yml

@@ -0,0 +1,26 @@
+# Aliases
+#
+# Aliases are shortcuts for Kamal commands.
+#
+# For example, for a Rails app, you might open a console with:
+#
+# ```shell
+# kamal app exec -i -r console "rails console"
+# ```
+#
+# By defining an alias, like this:
+aliases:
+  console: app exec -r console -i "rails console"
+# You can now open the console with:
+# ```shell
+# kamal console
+# ```
+
+# Configuring aliases
+#
+# Aliases are defined in the root config under the alias key
+#
+# Each alias is named and can only contain lowercase letters, numbers, dashes and underscores.
+
+aliases:
+  uname: app exec -p -q -r web "uname -a"

data/lib/kamal/configuration/docs/builder.yml

@@ -1,10 +1,10 @@
 # Builder
 #
-# The builder configuration controls how the application is built with `docker build` or `docker buildx build`
+# The builder configuration controls how the application is built with `docker build`
 #
 # If no configuration is specified, Kamal will:
-# 1. Create a buildx context called `kamal-<service>-multiarch`
-# 2. Use `docker buildx build` to build a multiarch image for linux/amd64,linux/arm64 with that context
+# 1. Create a buildx context called `kamal-local-docker-container`, using the docker-container driver
+# 2. Use `docker build` to build a multiarch image for linux/amd64,linux/arm64 with that context
 #
 # See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information
 
@@ -13,35 +13,33 @@
 # Options go under the builder key in the root configuration.
 builder:
 
-  # Multiarch
+  # Arch
   #
-  # Enables multiarch builds, defaults to `true`
-  multiarch: false
-
-  # Local configuration
+  # The architectures to build for - you can set an array or just a single value.
   #
-  # The build configuration for local builds, only used if multiarch is enabled (the default)
+  # Allowed values are `amd64` and `arm64`
+  arch:
+    - amd64
+
+  # Remote
   #
-  # If there is no remote configuration, by default we build for amd64 and arm64.
-  # If you only want to build for one architecture, you can specify it here.
-  # The docker socket is optional and uses the default docker host socket when not specified
-  local:
-    arch: amd64
-    host: /var/run/docker.sock
+  # The connection string for a remote builder. If supplied Kamal will use this
+  # for builds that do not match the local architecture of the deployment host.
+  remote: ssh://docker@docker-builder
 
-  # Remote configuration
+  # Local
+  #
+  # If set to false, Kamal will always use the remote builder even when building
+  # the local architecture.
   #
-  # The build configuration for remote builds, also only used if multiarch is enabled.
-  # The arch is required and can be either amd64 or arm64.
-  remote:
-    arch: arm64
-    host: ssh://docker@docker-builder
+  # Defaults to true
+  local: true
 
   # Builder cache
   #
   # The type must be either 'gha' or 'registry'
   #
-  # The image is only used for registry cache
+  # The image is only used for registry cache. Not compatible with the docker driver
   cache:
     type: registry
     options: mode=max
@@ -80,7 +78,7 @@ builder:
 
   # Build secrets
   #
-  # Values are read from the environment.
+  # Values are read from the .kamal/secrets.
   #
   secrets:
     - SECRET1
@@ -105,3 +103,8 @@ builder:
   #
   # SSH agent socket or keys to expose to the build
   ssh: default=$SSH_AUTH_SOCK
+
+  # Driver
+  #
+  # The build driver to use, defaults to `docker-container`
+  driver: docker

data/lib/kamal/configuration/docs/configuration.yml

@@ -70,7 +70,7 @@ env:
 # volume containing both sets of files.
 # This requires that file names change when the contents change
 # (e.g. by including a hash of the contents in the name).
-
+#
 # To configure this, set the path to the assets:
 asset_path: /path/to/assets
 
@@ -93,11 +93,6 @@ primary_role: workers
 # Whether roles with no servers are allowed. Defaults to `false`.
 allow_empty_roles: false
 
-# Stop wait time
-#
-# How long we wait for a container to stop before killing it, defaults to 30 seconds
-stop_wait_time: 60
-
 # Retain containers
 #
 # How many old containers and images we retain, defaults to 5
@@ -111,9 +106,20 @@ minimum_version: 1.3.0
 # Readiness delay
 #
 # Seconds to wait for a container to boot after is running, default 7
-# This only applies to containers that do not specify a healthcheck
+#
+# This only applies to containers that do not run a proxy or specify a healthcheck
 readiness_delay: 4
 
+# Deploy timeout
+#
+# How long to wait for a container to become ready, default 30
+deploy_timeout: 10
+
+# Drain timeout
+#
+# How long to wait for a containers to drain, default 30
+drain_timeout: 10
+
 # Run directory
 #
 # Directory to store kamal runtime files in on the host, default `.kamal`
@@ -137,10 +143,10 @@ builder:
 accessories:
   ...
 
-# Traefik
+# Proxy
 #
-# The Traefik proxy is used for zero-downtime deployments, see kamal docs traefik
-traefik:
+# Configuration for kamal-proxy, see kamal docs proxy
+proxy:
   ...
 
 # SSHKit
@@ -155,14 +161,14 @@ sshkit:
 boot:
   ...
 
-# Healthcheck
-#
-# Configuring healthcheck commands, intervals and timeouts, see kamal docs healthcheck
-healthcheck:
-  ...
-
 # Logging
 #
 # Docker logging configuration, see kamal docs logging
 logging:
   ...
+
+# Aliases
+#
+# Alias configuration, see kamal docs alias
+aliases:
+  ...

data/lib/kamal/configuration/docs/env.yml

@@ -1,7 +1,7 @@
 # Environment variables
 #
-# Environment variables can be set directory in the Kamal configuration or
-# for loaded from a .env file, for secrets that should not be checked into Git.
+# Environment variables can be set directly in the Kamal configuration or
+# read from .kamal/secrets.
 
 # Reading environment variables from the configuration
 #
@@ -12,26 +12,25 @@ env:
   DATABASE_HOST: mysql-db1
   DATABASE_PORT: 3306
 
-# Using .env file to load required environment variables
+# Using .kamal/secrets file to load required environment variables
 #
-# Kamal uses dotenv to automatically load environment variables set in the .env file present
-# in the application root.
+# Kamal uses dotenv to automatically load environment variables set in the .kamal/secrets file.
 #
 # This file can be used to set variables like KAMAL_REGISTRY_PASSWORD or database passwords.
-# But for this reason you must ensure that .env files are not checked into Git or included
-# in your Dockerfile! The format is just key-value like:
+# You can use variable or command substitution in the secrets file.
+#
 # ```
-# KAMAL_REGISTRY_PASSWORD=pw
-# DB_PASSWORD=secret123
+# KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
+# RAILS_MASTER_KEY=$(cat config/master.key)
 # ```
-# See https://kamal-deploy.org/docs/commands/envify/ for how to use generated .env files.
+#
+# If you store secrets directly in .kamal/secrets, ensure that it is not checked into version control.
 #
 # To pass the secrets you should list them under the `secret` key. When you do this the
 # other variables need to be moved under the `clear` key.
 #
 # Unlike clear values, secrets are not passed directly to the container,
 # but are stored in an env file on the host
-# The file is not updated when deploying, only when running `kamal envify` or `kamal env push`.
 env:
   clear:
     DB_USER: app

data/lib/kamal/configuration/docs/proxy.yml

@@ -0,0 +1,100 @@
+# Proxy
+#
+# Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to provide
+# gapless deployments. It runs on ports 80 and 443 and forwards requests to the
+# application container.
+#
+# The proxy is configured in the root configuration under `proxy`. These are
+# options that are set when deploying the application, not when booting the proxy
+#
+# They are application specific, so are not shared when multiple applications
+# run on the same proxy.
+#
+# The proxy is enabled by default on the primary role, but can be disabled by
+# setting `proxy: false`.
+#
+# It is disabled by default on all other roles, but can be enabled by setting
+# `proxy: true`, or providing a proxy configuration.
+proxy:
+
+  # Host
+  #
+  # The hosts that will be used to serve the app. The proxy will only route requests
+  # to this host to your app.
+  #
+  # If no hosts are set, then all requests will be forwarded, except for matching
+  # requests for other apps deployed on that server that do have a host set.
+  host: foo.example.com
+
+  # App port
+  #
+  # The port the application container is exposed on
+  #
+  # Defaults to 80
+  app_port: 3000
+
+  # SSL
+  #
+  # kamal-proxy can provide automatic HTTPS for your application via Let's Encrypt.
+  #
+  # This requires that we are deploying to a one server and the host option is set.
+  # The host value must point to the server we are deploying to and port 443 must be
+  # open for the Let's Encrypt challenge to succeed.
+  #
+  # Defaults to false
+  ssl: true
+
+  # Response timeout
+  #
+  # How long to wait for requests to complete before timing out, defaults to 30 seconds
+  response_timeout: 10s
+
+  # Healthcheck
+  #
+  # When deploying, the proxy will by default hit /up once every second until we hit
+  # the deploy timeout, with a 5 second timeout for each request.
+  #
+  # Once the app is up, the proxy will stop hitting the healthcheck endpoint.
+  healthcheck:
+    interval: 3
+    path: /health
+    timeout: 3
+
+  # Buffering
+  #
+  # Whether to buffer request and response bodies in the proxy
+  #
+  # By default buffering is enabled with a max request body size of 1GB and no limit
+  # for response size.
+  #
+  # You can also set the memory limit for buffering, which defaults to 1MB, anything
+  # larger than that is written to disk.
+  buffering:
+    requests: true
+    responses: true
+    max_request_body: 40_000_000
+    max_response_body: 0
+    memory: 2_000_000
+
+  # Logging
+  #
+  # Configure request logging for the proxy
+  # You can specify request and response headers to log.
+  # By default, Cache-Control, Last-Modified and User-Agent request headers are logged
+  logging:
+    request_headers:
+      - Cache-Control
+      - X-Forwarded-Proto
+    response_headers:
+      - X-Request-ID
+      - X-Request-Start
+
+  # Forward headers
+  #
+  # Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers (defaults to false)
+  #
+  # If you are behind a trusted proxy, you can set this to true to forward the headers.
+  #
+  # By default kamal-proxy will not forward the headers the ssl option is set to true, and
+  # will forward them if it is set to false.
+  forward_headers: true

data/lib/kamal/configuration/docs/registry.yml

@@ -27,11 +27,13 @@ registry:
 # and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions).
 # Normally, assigning a roles/artifactregistry.writer role should be sufficient.
 #
-# Once the service account is ready, you need to generate and download a JSON key, base64 encode it and add to .env:
+# Once the service account is ready, you need to generate and download a JSON key and base64 encode it:
 #
 # ```shell
-# echo "KAMAL_REGISTRY_PASSWORD=$(base64 -i /path/to/key.json)" | tr -d "\\n"  >> .env
+# base64 -i /path/to/key.json | tr -d "\\n")
 # ```
+# You'll then need to set the KAMAL_REGISTRY_PASSWORD secret to that value.
+#
 # Use the env variable as password along with _json_key_base64 as username.
 # Here’s the final configuration:
 

data/lib/kamal/configuration/docs/role.yml

@@ -26,7 +26,7 @@ servers:
   #
   # When there are other options to set, the list of hosts goes under the `hosts` key
   #
-  # By default only the primary role uses Traefik, but you can set `traefik` to change
+  # By default only the primary role uses a proxy, but you can set `proxy` to change
   # it.
   #
   # You can also set a custom cmd to run in the container, and overwrite other settings
@@ -35,18 +35,16 @@ servers:
     hosts:
       - 172.1.0.3
       - 172.1.0.4: experiment1
-    traefik: true
     cmd: "bin/jobs"
     options:
       memory: 2g
       cpus: 4
-    healthcheck:
-      ...
     logging:
       ...
+    proxy:
+      ...
     labels:
       my-label: workers
     env:
       ...
     asset_path: /public
-

data/lib/kamal/configuration/env/tag.rb

@@ -1,12 +1,13 @@
 class Kamal::Configuration::Env::Tag
-  attr_reader :name, :config
+  attr_reader :name, :config, :secrets
 
-  def initialize(name, config:)
+  def initialize(name, config:, secrets:)
     @name = name
     @config = config
+    @secrets = secrets
   end
 
   def env
-    Kamal::Configuration::Env.new(config: config)
+    Kamal::Configuration::Env.new(config: config, secrets: secrets)
   end
 end

data/lib/kamal/configuration/env.rb

@@ -1,36 +1,29 @@
 class Kamal::Configuration::Env
   include Kamal::Configuration::Validation
 
-  attr_reader :secrets_keys, :clear, :secrets_file, :context
+  attr_reader :context, :secrets
+  attr_reader :clear, :secret_keys
   delegate :argumentize, to: Kamal::Utils
 
-  def initialize(config:, secrets_file: nil, context: "env")
+  def initialize(config:, secrets:, context: "env")
     @clear = config.fetch("clear", config.key?("secret") || config.key?("tags") ? {} : config)
-    @secrets_keys = config.fetch("secret", [])
-    @secrets_file = secrets_file
+    @secrets = secrets
+    @secret_keys = config.fetch("secret", [])
     @context = context
     validate! config, context: context, with: Kamal::Configuration::Validator::Env
   end
 
-  def args
-    [ "--env-file", secrets_file, *argumentize("--env", clear) ]
+  def clear_args
+    argumentize("--env", clear)
   end
 
   def secrets_io
-    StringIO.new(Kamal::EnvFile.new(secrets).to_s)
-  end
-
-  def secrets
-    @secrets ||= secrets_keys.to_h { |key| [ key, ENV.fetch(key) ] }
-  end
-
-  def secrets_directory
-    File.dirname(secrets_file)
+    Kamal::EnvFile.new(secret_keys.to_h { |key| [ key, secrets[key] ] }).to_io
   end
 
   def merge(other)
     self.class.new \
-      config: { "clear" => clear.merge(other.clear), "secret" => secrets_keys | other.secrets_keys },
-      secrets_file: secrets_file || other.secrets_file
+      config: { "clear" => clear.merge(other.clear), "secret" => secret_keys | other.secret_keys },
+      secrets: secrets
   end
 end

data/lib/kamal/configuration/proxy.rb

@@ -0,0 +1,66 @@
+class Kamal::Configuration::Proxy
+  include Kamal::Configuration::Validation
+
+  DEFAULT_LOG_REQUEST_HEADERS = [ "Cache-Control", "Last-Modified", "User-Agent" ]
+  CONTAINER_NAME = "kamal-proxy"
+
+  delegate :argumentize, :optionize, to: Kamal::Utils
+
+  attr_reader :config, :proxy_config
+
+  def initialize(config:, proxy_config:, context: "proxy")
+    @config = config
+    @proxy_config = proxy_config
+    validate! @proxy_config, with: Kamal::Configuration::Validator::Proxy, context: context
+  end
+
+  def app_port
+    proxy_config.fetch("app_port", 80)
+  end
+
+  def ssl?
+    proxy_config.fetch("ssl", false)
+  end
+
+  def host
+    proxy_config["host"]
+  end
+
+  def deploy_options
+    {
+      host: proxy_config["host"],
+      tls: proxy_config["ssl"],
+      "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": proxy_config.dig("healthcheck", "path"),
+      "target-timeout": seconds_duration(proxy_config["response_timeout"]),
+      "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"),
+      "forward-headers": proxy_config.dig("forward_headers"),
+      "log-request-header": proxy_config.dig("logging", "request_headers") || DEFAULT_LOG_REQUEST_HEADERS,
+      "log-response-header": proxy_config.dig("logging", "response_headers")
+    }.compact
+  end
+
+  def deploy_command_args(target:)
+    optionize ({ target: "#{target}:#{app_port}" }).merge(deploy_options)
+  end
+
+  def remove_command_args(target:)
+    optionize({ target: "#{target}:#{app_port}" })
+  end
+
+  def merge(other)
+    self.class.new config: config, proxy_config: proxy_config.deep_merge(other.proxy_config)
+  end
+
+  private
+    def seconds_duration(value)
+      value ? "#{value}s" : nil
+    end
+end

data/lib/kamal/configuration/registry.rb

@@ -1,10 +1,11 @@
 class Kamal::Configuration::Registry
   include Kamal::Configuration::Validation
 
-  attr_reader :registry_config
+  attr_reader :registry_config, :secrets
 
   def initialize(config:)
     @registry_config = config.raw_config.registry || {}
+    @secrets = config.secrets
     validate! registry_config, with: Kamal::Configuration::Validator::Registry
   end
 
@@ -23,7 +24,7 @@ class Kamal::Configuration::Registry
   private
     def lookup(key)
       if registry_config[key].is_a?(Array)
-        ENV.fetch(registry_config[key].first).dup
+        secrets[registry_config[key].first]
       else
         registry_config[key]
       end