diff --git a/bin/docs b/bin/docs new file mode 100755 index 00000000..08b2937a --- /dev/null +++ b/bin/docs @@ -0,0 +1,134 @@ +#!/usr/bin/env ruby +require "stringio" + +def usage + puts "Usage: #{$0} " + exit 1 +end + +usage if ARGV.size != 1 + +kamal_site_repo = ARGV[0] + +if !File.directory?(kamal_site_repo) + puts "Error: #{kamal_site_repo} is not a directory" + exit 1 +end + +DOCS = { + "accessory" => "Accessories", + "boot" => "Booting", + "builder" => "Builders", + "configuration" => "Configuration overview", + "env" => "Environment variables", + "healthcheck" => "Healthchecks", + "logging" => "Logging", + "registry" => "Docker Registry", + "role" => "Roles", + "servers" => "Servers", + "ssh" => "SSH", + "sshkit" => "SSHKit", + "traefik" => "Traefik" +} + +class DocWriter + attr_reader :from_file, :to_file, :key, :heading, :body, :output, :in_yaml + + def initialize(from_file, to_dir) + @from_file = from_file + @key = File.basename(from_file, ".yml") + @to_file = File.join(to_dir, "#{linkify(DOCS[key])}.md") + @body = File.readlines(from_file) + @heading = body.shift.chomp("\n") + @output = nil + end + + def write + puts "Writing #{to_file}" + generate_markdown + File.write(to_file, output.string) + end + + private + def generate_markdown + @output = StringIO.new + + generate_header + + place = :in_section + + loop do + line = body.shift&.chomp("\n") + break if line.nil? + + case place + when :new_section, :in_section + if line.empty? + output.puts + place = :new_section + elsif line =~ /^ *#/ + generate_line(line, place: place) + place = :in_section + else + output.puts "```yaml" + output.print line + place = :in_yaml + end + when :in_yaml + if line =~ /^ *#/ + output.puts "```" + generate_line(line, place: :new_section) + place = :in_section + else + output.puts + output.print line + end + end + end + + output.puts "\n```" if place == :in_yaml + end + + def generate_header + output.puts "---" + output.puts "title: #{heading[2..-1]}" + output.puts "---" + output.puts + output.puts heading + output.puts + end + + def generate_line(line, place: :in_section) + line = line.gsub(/^ *#\s?/, "") + + if line =~ /(.*)kamal docs ([a-z]*)(.*)/ + line = "#{$1}[#{DOCS[$2]}](../#{linkify(DOCS[$2])})#{$3}" + end + + if line =~ /(.*)https:\/\/kamal-deploy.org([a-z\/-]*)(.*)/ + line = "#{$1}[#{titlify($2.split("/").last)}](#{$2})#{$3}" + end + + if place == :new_section + output.puts "## [#{line}](##{linkify(line)})" + else + output.puts line + end + end + + def linkify(text) + text.downcase.gsub(" ", "-") + end + + def titlify(text) + text.capitalize.gsub("-", " ") + end +end + +from_dir = File.join(File.dirname(__FILE__), "../lib/kamal/configuration/docs") +to_dir = File.join(kamal_site_repo, "docs/configuration") +Dir.glob("#{from_dir}/*") do |from_file| + key = File.basename(from_file, ".yml") + + DocWriter.new(from_file, to_dir).write +end diff --git a/lib/kamal.rb b/lib/kamal.rb index 6b4800a7..2da2bbf2 100644 --- a/lib/kamal.rb +++ b/lib/kamal.rb @@ -1,8 +1,10 @@ module Kamal + class ConfigurationError < StandardError; end end require "active_support" require "zeitwerk" +require "yaml" loader = Zeitwerk::Loader.for_gem loader.ignore(File.join(__dir__, "kamal", "sshkit_with_ext.rb")) diff --git a/lib/kamal/cli.rb b/lib/kamal/cli.rb index c1501ddb..6772556e 100644 --- a/lib/kamal/cli.rb +++ b/lib/kamal/cli.rb @@ -1,6 +1,6 @@ module Kamal::Cli - class LockError < StandardError; end class HookError < StandardError; end + class LockError < StandardError; end end # SSHKit uses instance eval, so we need a global const for ergonomics diff --git a/lib/kamal/cli/healthcheck/poller.rb b/lib/kamal/cli/healthcheck/poller.rb index 06898b1c..249a1f6b 100644 --- a/lib/kamal/cli/healthcheck/poller.rb +++ b/lib/kamal/cli/healthcheck/poller.rb @@ -6,7 +6,7 @@ module Kamal::Cli::Healthcheck::Poller def wait_for_healthy(pause_after_ready: false, &block) attempt = 1 - max_attempts = KAMAL.config.healthcheck["max_attempts"] + max_attempts = KAMAL.config.healthcheck.max_attempts begin case status = block.call @@ -33,7 +33,7 @@ module Kamal::Cli::Healthcheck::Poller def wait_for_unhealthy(pause_after_ready: false, &block) attempt = 1 - max_attempts = KAMAL.config.healthcheck["max_attempts"] + max_attempts = KAMAL.config.healthcheck.max_attempts begin case status = block.call diff --git a/lib/kamal/cli/main.rb b/lib/kamal/cli/main.rb index 25272f3f..735c55f1 100644 --- a/lib/kamal/cli/main.rb +++ b/lib/kamal/cli/main.rb @@ -126,6 +126,18 @@ class Kamal::Cli::Main < Kamal::Cli::Base end end + desc "docs", "Show Kamal documentation for configuration setting" + def docs(section = nil) + case section + when NilClass + puts Kamal::Configuration.validation_doc + else + puts Kamal::Configuration.const_get(section.titlecase.to_sym).validation_doc + end + rescue NameError + puts "No documentation found for #{section}" + end + desc "init", "Create config stub in config/deploy.yml and env stub in .env" option :bundle, type: :boolean, default: false, desc: "Add Kamal to the Gemfile and create a bin/kamal binstub" def init diff --git a/lib/kamal/commands/builder.rb b/lib/kamal/commands/builder.rb index ad38fb4f..370f6b3a 100644 --- a/lib/kamal/commands/builder.rb +++ b/lib/kamal/commands/builder.rb @@ -11,17 +11,22 @@ class Kamal::Commands::Builder < Kamal::Commands::Base end def target - case - when !config.builder.multiarch? && !config.builder.cached? - native - when !config.builder.multiarch? && config.builder.cached? - native_cached - when config.builder.local? && config.builder.remote? - multiarch_remote - when config.builder.remote? - native_remote + if config.builder.multiarch? + if config.builder.remote? + if config.builder.local? + multiarch_remote + else + native_remote + end + else + multiarch + end else - multiarch + if config.builder.cached? + native_cached + else + native + end end end diff --git a/lib/kamal/commands/registry.rb b/lib/kamal/commands/registry.rb index e13c90ac..69f95360 100644 --- a/lib/kamal/commands/registry.rb +++ b/lib/kamal/commands/registry.rb @@ -3,21 +3,12 @@ class Kamal::Commands::Registry < Kamal::Commands::Base def login docker :login, - registry["server"], - "-u", sensitive(Kamal::Utils.escape_shell_value(lookup("username"))), - "-p", sensitive(Kamal::Utils.escape_shell_value(lookup("password"))) + registry.server, + "-u", sensitive(Kamal::Utils.escape_shell_value(registry.username)), + "-p", sensitive(Kamal::Utils.escape_shell_value(registry.password)) end def logout - docker :logout, registry["server"] + docker :logout, registry.server end - - private - def lookup(key) - if registry[key].is_a?(Array) - ENV.fetch(registry[key].first).dup - else - registry[key] - end - end end diff --git a/lib/kamal/commands/traefik.rb b/lib/kamal/commands/traefik.rb index 6fa9209a..07e0e6ea 100644 --- a/lib/kamal/commands/traefik.rb +++ b/lib/kamal/commands/traefik.rb @@ -1,19 +1,6 @@ class Kamal::Commands::Traefik < Kamal::Commands::Base delegate :argumentize, :optionize, to: Kamal::Utils - - DEFAULT_IMAGE = "traefik:v2.10" - CONTAINER_PORT = 80 - DEFAULT_ARGS = { - "log.level" => "DEBUG" - } - DEFAULT_LABELS = { - # These ensure we serve a 502 rather than a 404 if no containers are available - "traefik.http.routers.catchall.entryPoints" => "http", - "traefik.http.routers.catchall.rule" => "PathPrefix(`/`)", - "traefik.http.routers.catchall.service" => "unavailable", - "traefik.http.routers.catchall.priority" => 1, - "traefik.http.services.unavailable.loadbalancer.server.port" => "0" - } + delegate :port, :publish?, :labels, :env, :image, :options, :args, to: :"config.traefik" def run docker :run, "--name traefik", @@ -67,16 +54,6 @@ class Kamal::Commands::Traefik < Kamal::Commands::Base docker :image, :prune, "--all", "--force", "--filter", "label=org.opencontainers.image.title=Traefik" end - def port - "#{host_port}:#{CONTAINER_PORT}" - end - - def env - Kamal::Configuration::Env.from_config \ - config: config.traefik.fetch("env", {}), - secrets_file: File.join(config.host_env_directory, "traefik", "traefik.env") - end - def make_env_directory make_directory(env.secrets_directory) end @@ -87,7 +64,7 @@ class Kamal::Commands::Traefik < Kamal::Commands::Base private def publish_args - argumentize "--publish", port unless config.traefik["publish"] == false + argumentize "--publish", port if publish? end def label_args @@ -98,27 +75,11 @@ class Kamal::Commands::Traefik < Kamal::Commands::Base env.args end - def labels - DEFAULT_LABELS.merge(config.traefik["labels"] || {}) - end - - def image - config.traefik.fetch("image") { DEFAULT_IMAGE } - end - def docker_options_args - optionize(config.traefik["options"] || {}) + optionize(options) end def cmd_option_args - if args = config.traefik["args"] - optionize DEFAULT_ARGS.merge(args), with: "=" - else - optionize DEFAULT_ARGS, with: "=" - end - end - - def host_port - config.traefik["host_port"] || CONTAINER_PORT + optionize args, with: "=" end end diff --git a/lib/kamal/configuration.rb b/lib/kamal/configuration.rb index bed91cf6..5f1743bd 100644 --- a/lib/kamal/configuration.rb +++ b/lib/kamal/configuration.rb @@ -1,15 +1,19 @@ require "active_support/ordered_options" require "active_support/core_ext/string/inquiry" require "active_support/core_ext/module/delegation" +require "active_support/core_ext/hash/keys" require "pathname" require "erb" require "net/ssh/proxy/jump" class Kamal::Configuration - delegate :service, :image, :servers, :labels, :registry, :stop_wait_time, :hooks_path, :logging, to: :raw_config, allow_nil: true + delegate :service, :image, :labels, :stop_wait_time, :hooks_path, to: :raw_config, allow_nil: true delegate :argumentize, :optionize, to: Kamal::Utils attr_reader :destination, :raw_config + attr_reader :accessories, :boot, :builder, :env, :healthcheck, :logging, :traefik, :servers, :ssh, :sshkit, :registry + + include Validation class << self def create_from(config_file:, destination: nil, version: nil) @@ -42,7 +46,29 @@ class Kamal::Configuration @raw_config = ActiveSupport::InheritableOptions.new(raw_config) @destination = destination @declared_version = version - valid? if validate + + validate! raw_config, example: validation_yml.symbolize_keys, context: "" + + # Eager load config to validate it, these are first as they have dependencies later on + @servers = Servers.new(config: self) + @registry = Registry.new(config: self) + + @accessories = @raw_config.accessories&.keys&.collect { |name| Accessory.new(name, config: self) } || [] + @boot = Boot.new(config: self) + @builder = Builder.new(config: self) + @env = Env.new(config: @raw_config.env || {}) + + @healthcheck = Healthcheck.new(healthcheck_config: @raw_config.healthcheck) + @logging = Logging.new(logging_config: @raw_config.logging) + @traefik = Traefik.new(config: self) + @ssh = Ssh.new(config: self) + @sshkit = Sshkit.new(config: self) + + ensure_destination_if_required + ensure_required_keys_present + ensure_valid_kamal_version + ensure_retain_containers_valid + ensure_valid_service_name end @@ -71,17 +97,13 @@ class Kamal::Configuration def roles - @roles ||= role_names.collect { |role_name| Role.new(role_name, config: self) } + servers.roles end def role(name) roles.detect { |r| r.name == name.to_s } end - def accessories - @accessories ||= raw_config.accessories&.keys&.collect { |name| Kamal::Configuration::Accessory.new(name, config: self) } || [] - end - def accessory(name) accessories.detect { |a| a.name == name.to_s } end @@ -120,7 +142,7 @@ class Kamal::Configuration end def repository - [ raw_config.registry["server"], image ].compact.join("/") + [ registry.server, image ].compact.join("/") end def absolute_image @@ -157,40 +179,10 @@ class Kamal::Configuration end def logging_args - if logging.present? - optionize({ "log-driver" => logging["driver"] }.compact) + - argumentize("--log-opt", logging["options"]) - else - argumentize("--log-opt", { "max-size" => "10m" }) - end + logging.args end - def boot - Kamal::Configuration::Boot.new(config: self) - end - - def builder - Kamal::Configuration::Builder.new(config: self) - end - - def traefik - raw_config.traefik || {} - end - - def ssh - Kamal::Configuration::Ssh.new(config: self) - end - - def sshkit - Kamal::Configuration::Sshkit.new(config: self) - end - - - def healthcheck - { "path" => "/up", "port" => 3000, "max_attempts" => 7, "cord" => "/tmp/kamal-cord", "log_lines" => 50 }.merge(raw_config.healthcheck || {}) - end - def healthcheck_service [ "healthcheck", service, destination ].compact.join("-") end @@ -229,13 +221,9 @@ class Kamal::Configuration File.join(run_directory, "env") end - def env - raw_config.env || {} - end - def env_tags @env_tags ||= if (tags = raw_config.env["tags"]) - tags.collect { |name, config| Kamal::Configuration::Env::Tag.new(name, config: config) } + tags.collect { |name, config| Env::Tag.new(name, config: config) } else [] end @@ -246,10 +234,6 @@ class Kamal::Configuration end - def valid? - ensure_destination_if_required && ensure_required_keys_present && ensure_valid_kamal_version && ensure_retain_containers_valid && ensure_valid_service_name - end - def to_h { roles: role_names, @@ -265,11 +249,10 @@ class Kamal::Configuration builder: builder.to_h, accessories: raw_config.accessories, logging: logging_args, - healthcheck: healthcheck + healthcheck: healthcheck.to_h }.compact end - private # Will raise ArgumentError if any required config keys are missing def ensure_destination_if_required @@ -282,29 +265,21 @@ class Kamal::Configuration def ensure_required_keys_present %i[ service image registry servers ].each do |key| - raise ArgumentError, "Missing required configuration for #{key}" unless raw_config[key].present? + raise Kamal::ConfigurationError, "Missing required configuration for #{key}" unless raw_config[key].present? end - if raw_config.registry["username"].blank? - raise ArgumentError, "You must specify a username for the registry in config/deploy.yml" - end - - if raw_config.registry["password"].blank? - raise ArgumentError, "You must specify a password for the registry in config/deploy.yml (or set the ENV variable if that's used)" - end - - unless role_names.include?(primary_role_name) - raise ArgumentError, "The primary_role #{primary_role_name} isn't defined" + unless role(primary_role_name).present? + raise Kamal::ConfigurationError, "The primary_role #{primary_role_name} isn't defined" end if primary_role.hosts.empty? - raise ArgumentError, "No servers specified for the #{primary_role.name} primary_role" + raise Kamal::ConfigurationError, "No servers specified for the #{primary_role.name} primary_role" end unless allow_empty_roles? roles.each do |role| if role.hosts.empty? - raise ArgumentError, "No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true" + raise Kamal::ConfigurationError, "No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true" end end end @@ -313,21 +288,21 @@ class Kamal::Configuration end def ensure_valid_service_name - raise ArgumentError, "Service name can only include alphanumeric characters, hyphens, and underscores" unless raw_config[:service] =~ /^[a-z0-9_-]+$/i + raise Kamal::ConfigurationError, "Service name can only include alphanumeric characters, hyphens, and underscores" unless raw_config[:service] =~ /^[a-z0-9_-]+$/i true end def ensure_valid_kamal_version if minimum_version && Gem::Version.new(minimum_version) > Gem::Version.new(Kamal::VERSION) - raise ArgumentError, "Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}" + raise Kamal::ConfigurationError, "Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}" end true end def ensure_retain_containers_valid - raise ArgumentError, "Must retain at least 1 container" if retain_containers < 1 + raise Kamal::ConfigurationError, "Must retain at least 1 container" if retain_containers < 1 true end diff --git a/lib/kamal/configuration/accessory.rb b/lib/kamal/configuration/accessory.rb index 42b7754f..07f40b56 100644 --- a/lib/kamal/configuration/accessory.rb +++ b/lib/kamal/configuration/accessory.rb @@ -1,30 +1,39 @@ class Kamal::Configuration::Accessory + include Kamal::Configuration::Validation + delegate :argumentize, :optionize, to: Kamal::Utils - attr_accessor :name, :specifics + attr_reader :name, :accessory_config, :env def initialize(name, config:) - @name, @config, @specifics = name.inquiry, config, config.raw_config["accessories"][name] + @name, @config, @accessory_config = name.inquiry, config, config.raw_config["accessories"][name] + + validate! \ + accessory_config, + example: validation_yml["accessories"]["mysql"], + context: "accessories/#{name}", + with: Kamal::Configuration::Validator::Accessory + + @env = Kamal::Configuration::Env.new \ + config: accessory_config.fetch("env", {}), + secrets_file: File.join(config.host_env_directory, "accessories", "#{service_name}.env"), + context: "accessories/#{name}/env" end def service_name - specifics["service"] || "#{config.service}-#{name}" + accessory_config["service"] || "#{config.service}-#{name}" end def image - specifics["image"] + accessory_config["image"] end def hosts - if (specifics.keys & [ "host", "hosts", "roles" ]).size != 1 - raise ArgumentError, "Specify one of `host`, `hosts` or `roles` for accessory `#{name}`" - end - hosts_from_host || hosts_from_hosts || hosts_from_roles end def port - if port = specifics["port"]&.to_s + if port = accessory_config["port"]&.to_s port.include?(":") ? port : "#{port}:#{port}" end end @@ -34,32 +43,26 @@ class Kamal::Configuration::Accessory end def labels - default_labels.merge(specifics["labels"] || {}) + default_labels.merge(accessory_config["labels"] || {}) end def label_args argumentize "--label", labels end - def env - Kamal::Configuration::Env.from_config \ - config: specifics.fetch("env", {}), - secrets_file: File.join(config.host_env_directory, "accessories", "#{service_name}.env") - end - def env_args env.args end def files - specifics["files"]&.to_h do |local_to_remote_mapping| + accessory_config["files"]&.to_h do |local_to_remote_mapping| local_file, remote_file = local_to_remote_mapping.split(":") [ expand_local_file(local_file), expand_remote_file(remote_file) ] end || {} end def directories - specifics["directories"]&.to_h do |host_to_container_mapping| + accessory_config["directories"]&.to_h do |host_to_container_mapping| host_path, container_path = host_to_container_mapping.split(":") [ expand_host_path(host_path), container_path ] end || {} @@ -74,7 +77,7 @@ class Kamal::Configuration::Accessory end def option_args - if args = specifics["options"] + if args = accessory_config["options"] optionize args else [] @@ -82,7 +85,7 @@ class Kamal::Configuration::Accessory end def cmd - specifics["cmd"] + accessory_config["cmd"] end private @@ -116,18 +119,18 @@ class Kamal::Configuration::Accessory end def specific_volumes - specifics["volumes"] || [] + accessory_config["volumes"] || [] end def remote_files_as_volumes - specifics["files"]&.collect do |local_to_remote_mapping| + accessory_config["files"]&.collect do |local_to_remote_mapping| _, remote_file = local_to_remote_mapping.split(":") "#{service_data_directory + remote_file}:#{remote_file}" end || [] end def remote_directories_as_volumes - specifics["directories"]&.collect do |host_to_container_mapping| + accessory_config["directories"]&.collect do |host_to_container_mapping| host_path, container_path = host_to_container_mapping.split(":") [ expand_host_path(host_path), container_path ].join(":") end || [] @@ -146,30 +149,16 @@ class Kamal::Configuration::Accessory end def hosts_from_host - if specifics.key?("host") - host = specifics["host"] - if host - [ host ] - else - raise ArgumentError, "Missing host for accessory `#{name}`" - end - end + [ accessory_config["host"] ] if accessory_config.key?("host") end def hosts_from_hosts - if specifics.key?("hosts") - hosts = specifics["hosts"] - if hosts.is_a?(Array) - hosts - else - raise ArgumentError, "Hosts should be an Array for accessory `#{name}`" - end - end + accessory_config["hosts"] if accessory_config.key?("hosts") end def hosts_from_roles - if specifics.key?("roles") - specifics["roles"].flat_map { |role| config.role(role).hosts } + if accessory_config.key?("roles") + accessory_config["roles"].flat_map { |role| config.role(role).hosts } end end end diff --git a/lib/kamal/configuration/boot.rb b/lib/kamal/configuration/boot.rb index 6e254b9d..13886f5e 100644 --- a/lib/kamal/configuration/boot.rb +++ b/lib/kamal/configuration/boot.rb @@ -1,20 +1,25 @@ class Kamal::Configuration::Boot + include Kamal::Configuration::Validation + + attr_reader :boot_config, :host_count + def initialize(config:) - @options = config.raw_config.boot || {} + @boot_config = config.raw_config.boot || {} @host_count = config.all_hosts.count + validate! boot_config end def limit - limit = @options["limit"] + limit = boot_config["limit"] if limit.to_s.end_with?("%") - [ @host_count * limit.to_i / 100, 1 ].max + [ host_count * limit.to_i / 100, 1 ].max else limit end end def wait - @options["wait"] + boot_config["wait"] end end diff --git a/lib/kamal/configuration/builder.rb b/lib/kamal/configuration/builder.rb index 4663f11f..74c8d1c6 100644 --- a/lib/kamal/configuration/builder.rb +++ b/lib/kamal/configuration/builder.rb @@ -1,73 +1,79 @@ class Kamal::Configuration::Builder - def initialize(config:) - @options = config.raw_config.builder || {} - @image = config.image - @server = config.registry["server"] - @service = config.service - @destination = config.destination + include Kamal::Configuration::Validation - valid? + attr_reader :config, :builder_config + delegate :image, :service, to: :config + delegate :server, to: :"config.registry" + + def initialize(config:) + @config = config + @builder_config = config.raw_config.builder || {} + @image = config.image + @server = config.registry.server + @service = config.service + + validate! builder_config, with: Kamal::Configuration::Validator::Builder end def to_h - @options + builder_config end def multiarch? - @options["multiarch"] != false + builder_config["multiarch"] != false end def local? - !!@options["local"] + !!builder_config["local"] end def remote? - !!@options["remote"] + !!builder_config["remote"] end def cached? - !!@options["cache"] + !!builder_config["cache"] end def args - @options["args"] || {} + builder_config["args"] || {} end def secrets - @options["secrets"] || [] + builder_config["secrets"] || [] end def dockerfile - @options["dockerfile"] || "Dockerfile" + builder_config["dockerfile"] || "Dockerfile" end def target - @options["target"] + builder_config["target"] end def context - @options["context"] || "." + builder_config["context"] || "." end def local_arch - @options["local"]["arch"] if local? + builder_config["local"]["arch"] if local? end def local_host - @options["local"]["host"] if local? + builder_config["local"]["host"] if local? end def remote_arch - @options["remote"]["arch"] if remote? + builder_config["remote"]["arch"] if remote? end def remote_host - @options["remote"]["host"] if remote? + builder_config["remote"]["host"] if remote? end def cache_from if cached? - case @options["cache"]["type"] + case builder_config["cache"]["type"] when "gha" cache_from_config_for_gha when "registry" @@ -78,7 +84,7 @@ class Kamal::Configuration::Builder def cache_to if cached? - case @options["cache"]["type"] + case builder_config["cache"]["type"] when "gha" cache_to_config_for_gha when "registry" @@ -88,15 +94,15 @@ class Kamal::Configuration::Builder end def ssh - @options["ssh"] + builder_config["ssh"] end def git_clone? - Kamal::Git.used? && @options["context"].nil? + Kamal::Git.used? && builder_config["context"].nil? end def clone_directory - @clone_directory ||= File.join Dir.tmpdir, "kamal-clones", [ @service, pwd_sha ].compact.join("-") + @clone_directory ||= File.join Dir.tmpdir, "kamal-clones", [ service, pwd_sha ].compact.join("-") end def build_directory @@ -109,18 +115,12 @@ class Kamal::Configuration::Builder end private - def valid? - 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 - @options["cache"]&.fetch("image", nil) || "#{@image}-build-cache" + builder_config["cache"]&.fetch("image", nil) || "#{image}-build-cache" end def cache_image_ref - [ @server, cache_image ].compact.join("/") + [ server, cache_image ].compact.join("/") end def cache_from_config_for_gha @@ -132,11 +132,11 @@ class Kamal::Configuration::Builder end def cache_to_config_for_gha - [ "type=gha", @options["cache"]&.fetch("options", nil) ].compact.join(",") + [ "type=gha", builder_config["cache"]&.fetch("options", nil) ].compact.join(",") end def cache_to_config_for_registry - [ "type=registry", @options["cache"]&.fetch("options", nil), "ref=#{cache_image_ref}" ].compact.join(",") + [ "type=registry", builder_config["cache"]&.fetch("options", nil), "ref=#{cache_image_ref}" ].compact.join(",") end def repo_basename diff --git a/lib/kamal/configuration/docs/accessory.yml b/lib/kamal/configuration/docs/accessory.yml new file mode 100644 index 00000000..931b80a4 --- /dev/null +++ b/lib/kamal/configuration/docs/accessory.yml @@ -0,0 +1,90 @@ +# Accessories +# +# Accessories can be booted on a single host, a list of hosts, or on specific roles. +# The hosts do not need to be defined in the Kamal servers configuration. +# +# Accessories are managed separately from the main service - they are not updated +# when you deploy and they do not have zero-downtime deployments. +# +# Run `kamal accessory boot ` to boot an accessory. +# See `kamal accessory --help` for more information. + +# Configuring accessories +# +# First define the accessory in the `accessories` +accessories: + mysql: + + # Service name + # + # This is used in the service label and defaults to `-` + # where `` is the main service name from the root configuration + service: mysql + + # Image + # + # The Docker image to use, prefix with a registry if not using Docker hub + image: mysql:8.0 + + # Accessory hosts + # + # Specify one of `host`, `hosts` or `roles` + host: mysql-db1 + hosts: + - mysql-db1 + - mysql-db2 + roles: + - mysql + + # Custom command + # + # You can set a custom command to run in the container, if you do not want to use the default + cmd: "bin/mysqld" + + # Port mappings + # + # See https://docs.docker.com/network/, especially note the warning about the security + # implications of exposing ports publicly. + port: "127.0.0.1:3306:3306" + + # Labels + labels: + app: myapp + + # Options + # These are passed to the Docker run command in the form `-- ` + options: + restart: always + cpus: 2 + + # Environment variables + # See kamal docs env for more information + env: + ... + + # Copying files + # + # You can specify files to mount into the container. + # The format is `local:remote` where `local` is the path to the file on the local machine + # and `remote` is the path to the file in the container. + # + # They will be uploaded from the local repo to the host and then mounted. + # + # ERB files will be evaluated before being copied. + files: + - config/my.cnf.erb:/etc/mysql/my.cnf + - config/myoptions.cnf:/etc/mysql/myoptions.cnf + + # Directories + # + # You can specify directories to mount into the container. They will be created on the host + # before being mounted + directories: + - mysql-logs:/var/log/mysql + + # Volumes + # + # Any other volumes to mount, in addition to the files and directories. + # They are not created or copied before mounting + volumes: + - /path/to/mysql-logs:/var/log/mysql diff --git a/lib/kamal/configuration/docs/boot.yml b/lib/kamal/configuration/docs/boot.yml new file mode 100644 index 00000000..2afb967f --- /dev/null +++ b/lib/kamal/configuration/docs/boot.yml @@ -0,0 +1,19 @@ +# Booting +# +# When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time. +# +# Kamal’s default is to boot new containers on all hosts in parallel. But you can control this with the boot configuration. + +# Fixed group sizes +# +# Here we boot 2 hosts at a time with a 10 second gap between each group. +boot: + limit: 2 + wait: 10 + +# Percentage of hosts +# +# Here we boot 25% of the hosts at a time with a 2 second gap between each group. +boot: + limit: 25% + wait: 2 diff --git a/lib/kamal/configuration/docs/builder.yml b/lib/kamal/configuration/docs/builder.yml new file mode 100644 index 00000000..b1071105 --- /dev/null +++ b/lib/kamal/configuration/docs/builder.yml @@ -0,0 +1,107 @@ +# Builder +# +# The builder configuration controls how the application is built with `docker build` or `docker buildx build` +# +# If no configuration is specified, Kamal will: +# 1. Create a buildx context called `kamal--multiarch` +# 2. Use `docker buildx 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 + +# Builder options +# +# Options go under the builder key in the root configuration. +builder: + + # Multiarch + # + # Enables multiarch builds, defaults to `true` + multiarch: false + + # Local configuration + # + # The build configuration for local builds, only used if multiarch is enabled (the default) + # + # 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 + + # Remote configuration + # + # 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 + + # Builder cache + # + # The type must be either 'gha' or 'registry' + # + # The image is only used for registry cache + cache: + type: registry + options: mode=max + image: kamal-app-build-cache + + # Build context + # + # If this is not set, then a local git clone of the repo is used. + # This ensures a clean build with no uncommitted changes. + # + # To use the local checkout instead you can set the context to `.`, or a path to another directory. + context: . + + # Dockerfile + # + # The Dockerfile to use for building, defaults to `Dockerfile` + dockerfile: Dockerfile.production + + # Build target + # + # If not set, then the default target is used + target: production + + # Build Arguments + # + # Any additional build arguments, passed to `docker build` with `--build-arg =` + args: + ENVIRONMENT: production + + # Referencing build arguments + # + # ```shell + # ARG RUBY_VERSION + # FROM ruby:$RUBY_VERSION-slim as base + # ``` + + # Build secrets + # + # Values are read from the environment. + # + secrets: + - SECRET1 + - SECRET2 + + # Referencing Build Secrets + # + # ```shell + # # Copy Gemfiles + # COPY Gemfile Gemfile.lock ./ + # + # # Install dependencies, including private repositories via access token + # # Then remove bundle cache with exposed GITHUB_TOKEN) + # RUN --mount=type=secret,id=GITHUB_TOKEN \ + # BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \ + # bundle install && \ + # rm -rf /usr/local/bundle/cache + # ``` + + + # SSH + # + # SSH agent socket or keys to expose to the build + ssh: default=$SSH_AUTH_SOCK diff --git a/lib/kamal/configuration/docs/configuration.yml b/lib/kamal/configuration/docs/configuration.yml new file mode 100644 index 00000000..895d2f84 --- /dev/null +++ b/lib/kamal/configuration/docs/configuration.yml @@ -0,0 +1,157 @@ +# Kamal Configuration +# +# Configuration is read from the `config/deploy.yml` +# +# When running commands, you can specify a destination with the `-d` flag, +# e.g. `kamal deploy -d staging` +# +# In this case the configuration will also be read from `config/deploy.staging.yml` +# and merged with the base configuration. +# +# The available configuration options are explained below. + +# The service name +# This is a required value. It is used as the container name prefix. +service: myapp + +# The Docker image name +# +# The image will be pushed to the configured registry. +image: my-image + +# Labels +# +# Additional labels to add to the container +labels: + my-label: my-value + +# Additional volumes to mount into the container +volumes: + - /path/on/host:/path/in/container:ro + +# Registry +# +# The Docker registry configuration, see kamal docs registry +registry: + ... + +# Servers +# +# The servers to deploy to, optionally with custom roles, see kamal docs servers +servers: + ... + +# Environment variables +# +# See kamal docs env +env: + ... + +# Asset Bridging +# +# Used for asset bridging across deployments, default to `nil` +# +# If there are changes to CSS or JS files, we may get requests +# for the old versions on the new container and vice-versa. +# +# To avoid 404s we can specify an asset path. +# Kamal will replace that path in the container with a mapped +# 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 + +# Path to hooks, defaults to `.kamal/hooks` +# See https://kamal-deploy.org/docs/hooks for more information +hooks_path: /user_home/kamal/hooks + +# Require destinations +# +# Whether deployments require a destination to be specified, defaults to `false` +require_destination: true + +# The primary role +# +# This defaults to `web`, but if you have no web role, you can change this +primary_role: workers + +# Allowing empty roles +# +# 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 +retain_containers: 3 + +# Minimum version +# +# The minimum version of Kamal required to deploy this configuration, defaults to nil +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 +readiness_delay: 4 + +# Run directory +# +# Directory to store kamal runtime files in on the host, default `.kamal` +run_directory: /etc/kamal + +# SSH options +# +# See kamal docs ssh +ssh: + ... + +# Builder options +# +# See kamal docs builder +builder: + ... + +# Accessories +# +# Additionals services to run in Docker, see kamal docs accessory +accessories: + ... + +# Traefik +# +# The Traefik proxy is used for zero-downtime deployments, see kamal docs traefik +traefik: + ... + +# SSHKit +# +# See kamal docs sshkit +sshkit: + ... + +# Boot options +# +# See kamal docs boot +boot: + ... + +# Healthcheck +# +# Configuring healthcheck commands, intervals and timeouts, see kamal docs healthcheck +healthcheck: + ... + +# Logging +# +# Docker logging configuration, see kamal docs logging +logging: + ... diff --git a/lib/kamal/configuration/docs/env.yml b/lib/kamal/configuration/docs/env.yml new file mode 100644 index 00000000..b353228a --- /dev/null +++ b/lib/kamal/configuration/docs/env.yml @@ -0,0 +1,72 @@ +# 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. + +# Reading environment variables from the configuration +# +# Environment variables can be set directly in the configuration file. +# +# These are passed to the docker run command when deploying. +env: + DATABASE_HOST: mysql-db1 + DATABASE_PORT: 3306 + +# Using .env file to load required environment variables +# +# Kamal uses dotenv to automatically load environment variables set in the .env file present +# in the application root. +# +# 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: +# ``` +# KAMAL_REGISTRY_PASSWORD=pw +# DB_PASSWORD=secret123 +# ``` +# See https://kamal-deploy.org/docs/commands/envify/ for how to use generated .env files. +# +# 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 valies, 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 + secret: + - DB_PASSWORD + +# Tags +# +# Tags are used to add extra env variables to specific hosts. +# See kamal docs servers for how to tag hosts. +# +# Tags are only allowed in the top level env configuration (i.e not under a role specific env). +# +# The env variables can be specified with secret and clear values as explained above. +env: + tags: + : + MYSQL_USER: monitoring + : + clear: + MYSQL_USER: readonly + secret: + - MYSQL_PASSWORD + +# Example configuration +env: + clear: + MYSQL_USER: app + secret: + - MYSQL_PASSWORD + tags: + monitoring: + MYSQL_USER: monitoring + replica: + clear: + MYSQL_USER: readonly + secret: + - READONLY_PASSWORD diff --git a/lib/kamal/configuration/docs/healthcheck.yml b/lib/kamal/configuration/docs/healthcheck.yml new file mode 100644 index 00000000..e29771f5 --- /dev/null +++ b/lib/kamal/configuration/docs/healthcheck.yml @@ -0,0 +1,59 @@ +# Healthcheck configuration +# +# On roles that are running Traefik, Kamal will supply a default healthcheck to `docker run`. +# For other roles, by default no healthcheck is supplied. +# +# If no healthcheck is supplied and the image does not define one, they we wait for the container +# to reach a running state and then pause for the readiness delay. +# +# The default healthcheck is `curl -f http://localhost:/`, so it assumes that `curl` +# is available within the container. + +# Healthcheck options +# +# These go under the `healthcheck` key in the root or role configuration. +healthcheck: + + # Command + # + # The command to run, defaults to `curl -f http://localhost:/` on roles running Traefik + cmd: "curl -f http://localhost" + + # Interval + # + # The Docker healthcheck interval, defaults to `1s` + interval: 10s + + # Max attempts + # + # The maximum number of times we poll the container to see if it is healthy, defaults to `7` + # Each check is separated by an increasing interval starting with 1 second. + max_attempts: 3 + + # Port + # + # The port to use in the healthcheck, defaults to `3000` + port: "80" + + # Path + # + # The path to use in the healthcheck, defaults to `/up` + path: /health + + # Cords for zero-downtime deployments + # + # The cord file is used for zero-downtime deployments. The healthcheck is augmented with a check + # for the existance of the file. This allows us to delete the file and force the container to + # become unhealthy, causing Traefik to stop routing traffic to it. + # + # Kamal mounts a volume at this location and creates the file before starting the container. + # You can set the value to `false` to disable the cord file, but this loses the zero-downtime + # guarantee. + # + # The default value is `/tmp/kamal-cord` + cord: /cord + + # Log lines + # + # Number of lines to log from the container when the healthcheck fails, defaults to `50` + log_lines: 100 diff --git a/lib/kamal/configuration/docs/logging.yml b/lib/kamal/configuration/docs/logging.yml new file mode 100644 index 00000000..cc30a617 --- /dev/null +++ b/lib/kamal/configuration/docs/logging.yml @@ -0,0 +1,21 @@ +# Custom logging configuration +# +# Set these to control the Docker logging driver and options. + +# Logging settings +# +# These go under the logging key in the configuration file. +# +# This can be specified in the root level or for a specific role. +logging: + + # Driver + # + # The logging driver to use, passed to Docker via `--log-driver` + driver: json-file + + # Options + # + # Any logging options to pass to the driver, passed to Docker via `--log-opt` + options: + max-size: 100m diff --git a/lib/kamal/configuration/docs/registry.yml b/lib/kamal/configuration/docs/registry.yml new file mode 100644 index 00000000..3254e454 --- /dev/null +++ b/lib/kamal/configuration/docs/registry.yml @@ -0,0 +1,49 @@ +# Registry +# +# The default registry is Docker Hub, but you can change it using registry/server: +# +# A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret +# in the local environment. + +registry: + server: registry.digitalocean.com + username: + - DOCKER_REGISTRY_TOKEN + password: + - DOCKER_REGISTRY_TOKEN + +# Using AWS ECR as the container registry +# You will need to have the aws CLI installed locally for this to work. +# AWS ECR’s access token is only valid for 12hrs. In order to not have to manually regenerate the token every time, you can use ERB in the deploy.yml file to shell out to the aws cli command, and obtain the token: + +registry: + server: .dkr.ecr..amazonaws.com + username: AWS + password: <%= %x(aws ecr get-login-password) %> + +# Using GCP Artifact Registry as the container registry +# To sign into Artifact Registry, you would need to +# [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) +# 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: +# +# ```shell +# echo "KAMAL_REGISTRY_PASSWORD=$(base64 -i /path/to/key.json)" | tr -d "\\n" >> .env +# ``` +# Use the env variable as password along with _json_key_base64 as username. +# Here’s the final configuration: + +registry: + server: -docker.pkg.dev + username: _json_key_base64 + password: + - KAMAL_REGISTRY_PASSWORD + +# Validating the configuration +# +# You can validate the configuration by running: +# ```shell +# kamal registry login +# ``` diff --git a/lib/kamal/configuration/docs/role.yml b/lib/kamal/configuration/docs/role.yml new file mode 100644 index 00000000..9f6962a5 --- /dev/null +++ b/lib/kamal/configuration/docs/role.yml @@ -0,0 +1,52 @@ +# Roles +# +# Roles are used to configure different types of servers in the deployment. +# The most common use for this is to run a web servers and job servers. +# +# Kamal expects there to be a `web` role, unless you set a different `primary_role` +# in the root configuration. + +# Role configuration +# +# Roles are specified under the servers key +servers: + + # Simple role configuration + # + # + # This can be a list of hosts, if you don't need custom configuration for the role. + # + # You can set tags on the hosts for custom env variables (see kamal docs env) + web: + - 172.1.0.1 + - 172.1.0.2: experiment1 + - 172.1.0.2: [ experiment1, experiment2 ] + + # Custom role configuration + # + # 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 + # it. + # + # You can also set a custom cmd to run in the container, and overwrite other settings + # from the root configuration. + workers: + hosts: + - 172.1.0.3 + - 172.1.0.4: experiment1 + traefik: true + cmd: "bin/jobs" + options: + memory: 2g + cpus: 4 + healthcheck: + ... + logging: + ... + labels: + my-label: workers + env: + ... + asset_path: /public + diff --git a/lib/kamal/configuration/docs/servers.yml b/lib/kamal/configuration/docs/servers.yml new file mode 100644 index 00000000..01b464be --- /dev/null +++ b/lib/kamal/configuration/docs/servers.yml @@ -0,0 +1,27 @@ +# Servers +# +# Servers are split into different roles, with each role having its own configuration. +# +# For simpler deployments though where all servers are identical, you can just specify a list of servers +# They will be implicitly assigned to the `web` role. +servers: + - 172.0.0.1 + - 172.0.0.2 + - 172.0.0.3 + +# Tagging servers +# +# Servers can be tagged, with the tags used to add custom env variables (see kamal docs env). +servers: + - 172.0.0.1 + - 172.0.0.2: experiments + - 172.0.0.3: [ experiments, three ] + +# Roles +# +# For more complex deployments (e.g. if you are running job hosts), you can specify roles, and configure each separately (see kamal docs role) +servers: + web: + ... + workers: + ... diff --git a/lib/kamal/configuration/docs/ssh.yml b/lib/kamal/configuration/docs/ssh.yml new file mode 100644 index 00000000..775b8247 --- /dev/null +++ b/lib/kamal/configuration/docs/ssh.yml @@ -0,0 +1,46 @@ +# SSH configuration +# +# Kamal uses SSH to connect run commands on your hosts. +# By default it will attempt to connect to the root user on port 22 +# +# If you are using non-root user, you may need to bootstrap your servers manually, before using them with Kamal. On Ubuntu, you’d do: +# +# ```shell +# sudo apt update +# sudo apt upgrade -y +# sudo apt install -y docker.io curl git +# sudo usermod -a -G docker app +# ``` + + +# SSH options +# +# The options are specified under the ssh key in the configuration file. +ssh: + + # The SSH user + # + # Defaults to `root` + # + user: app + + # The SSH port + # + # Defaults to 22 + port: "2222" + + # Proxy host + # + # Specified in the form or @ + proxy: root@proxy-host + + # Proxy command + # + # A custom proxy command, required for older versions of SSH + proxy_command: "ssh -W %h:%p user@proxy" + + # Log level + # + # Defaults to `fatal`. Set this to debug if you are having + # SSH connection issues. + log_level: debug diff --git a/lib/kamal/configuration/docs/sshkit.yml b/lib/kamal/configuration/docs/sshkit.yml new file mode 100644 index 00000000..0c9d90b3 --- /dev/null +++ b/lib/kamal/configuration/docs/sshkit.yml @@ -0,0 +1,23 @@ +# SSHKit +# +# [SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal. +# +# The default settings should be sufficient for most use cases, but +# when connecting to a large number of hosts you may need to adjust + +# SSHKit options +# +# The options are specified under the sshkit key in the configuration file. +sshkit: + + # Max concurrent starts + # + # Creating SSH connections concurrently can be an issue when deploying to many servers. + # By default Kamal will limit concurrent connection starts to 30 at a time. + max_concurrent_starts: 10 + + # Pool idle timeout + # + # Kamal sets a long idle timeout of 900 seconds on connections to try to avoid + # re-connection storms after an idle period, like building an image or waiting for CI. + pool_idle_timeout: 300 diff --git a/lib/kamal/configuration/docs/traefik.yml b/lib/kamal/configuration/docs/traefik.yml new file mode 100644 index 00000000..756afa9e --- /dev/null +++ b/lib/kamal/configuration/docs/traefik.yml @@ -0,0 +1,62 @@ +# Traefik +# +# Traefik is a reverse proxy, used by Kamal for zero-downtime deployments. +# +# We start an instance on the hosts in it's own container. +# +# During a deployment: +# 1. We start a new container which Traefik automatically detects due to the labels we have applied +# 2. Traefik starts routing traffic to the new container +# 3. We force the old container to fail it's healthcheck, causing Traefik to stop routing traffic to it +# 4. We stop the old container + +# Traefik settings +# +# Traekik is configured in the root configuration under `traefik`. +traefik: + + # Image + # + # The Traefik image to use, defaults to `traefik:v2.10` + image: traefik:v2.9 + + # Host port + # + # The host port to publish the Traefik container on, defaults to `80` + host_port: "8080" + + # Disabling publishing + # + # To avoid publishing the Traefik container, set this to `false` + publish: false + + # Labels + # + # Additional labels to apply to the Traefik container + labels: + traefik.http.routers.catchall.entryPoints: http + traefik.http.routers.catchall.rule: PathPrefix(`/`) + traefik.http.routers.catchall.service: unavailable + traefik.http.routers.catchall.priority: "1" + traefik.http.services.unavailable.loadbalancer.server.port: "0" + + # Arguments + # + # Additional arguments to pass to the Traefik container + args: + entryPoints.http.address: ":80" + entryPoints.http.forwardedHeaders.insecure: true + accesslog: true + accesslog.format: json + + # Options + # + # Additional options to pass to `docker run` + options: + cpus: 2 + + # Environment variables + # + # See kamal docs env + env: + ... diff --git a/lib/kamal/configuration/env.rb b/lib/kamal/configuration/env.rb index a7833849..1c0fb1e9 100644 --- a/lib/kamal/configuration/env.rb +++ b/lib/kamal/configuration/env.rb @@ -1,18 +1,15 @@ class Kamal::Configuration::Env - attr_reader :secrets_keys, :clear, :secrets_file + include Kamal::Configuration::Validation + + attr_reader :secrets_keys, :clear, :secrets_file, :context delegate :argumentize, to: Kamal::Utils - def self.from_config(config:, secrets_file: nil) - secrets_keys = config.fetch("secret", []) - clear = config.fetch("clear", config.key?("secret") || config.key?("tags") ? {} : config) - - new clear: clear, secrets_keys: secrets_keys, secrets_file: secrets_file - end - - def initialize(clear:, secrets_keys:, secrets_file:) - @clear = clear - @secrets_keys = secrets_keys + def initialize(config:, secrets_file: nil, context: "env") + @clear = config.fetch("clear", config.key?("secret") || config.key?("tags") ? {} : config) + @secrets_keys = config.fetch("secret", []) @secrets_file = secrets_file + @context = context + validate! config, context: context, with: Kamal::Configuration::Validator::Env end def args @@ -33,8 +30,7 @@ class Kamal::Configuration::Env def merge(other) self.class.new \ - clear: @clear.merge(other.clear), - secrets_keys: @secrets_keys | other.secrets_keys, - secrets_file: secrets_file + config: { "clear" => clear.merge(other.clear), "secret" => secrets_keys | other.secrets_keys }, + secrets_file: secrets_file || other.secrets_file end end diff --git a/lib/kamal/configuration/env/tag.rb b/lib/kamal/configuration/env/tag.rb index 2a6a1306..c4151202 100644 --- a/lib/kamal/configuration/env/tag.rb +++ b/lib/kamal/configuration/env/tag.rb @@ -7,6 +7,6 @@ class Kamal::Configuration::Env::Tag end def env - Kamal::Configuration::Env.from_config(config: config) + Kamal::Configuration::Env.new(config: config) end end diff --git a/lib/kamal/configuration/healthcheck.rb b/lib/kamal/configuration/healthcheck.rb new file mode 100644 index 00000000..888068a4 --- /dev/null +++ b/lib/kamal/configuration/healthcheck.rb @@ -0,0 +1,63 @@ +class Kamal::Configuration::Healthcheck + include Kamal::Configuration::Validation + + attr_reader :healthcheck_config + + def initialize(healthcheck_config:, context: "healthcheck") + @healthcheck_config = healthcheck_config || {} + validate! @healthcheck_config, context: context + end + + def merge(other) + self.class.new healthcheck_config: healthcheck_config.deep_merge(other.healthcheck_config) + end + + def cmd + healthcheck_config.fetch("cmd", http_health_check) + end + + def port + healthcheck_config.fetch("port", 3000) + end + + def path + healthcheck_config.fetch("path", "/up") + end + + def max_attempts + healthcheck_config.fetch("max_attempts", 7) + end + + def interval + healthcheck_config.fetch("interval", "1s") + end + + def cord + healthcheck_config.fetch("cord", "/tmp/kamal-cord") + end + + def log_lines + healthcheck_config.fetch("log_lines", 50) + end + + def set_port_or_path? + healthcheck_config["port"].present? || healthcheck_config["path"].present? + end + + def to_h + { + "cmd" => cmd, + "interval" => interval, + "max_attempts" => max_attempts, + "port" => port, + "path" => path, + "cord" => cord, + "log_lines" => log_lines + } + end + + private + def http_health_check + "curl -f #{URI.join("http://localhost:#{port}", path)} || exit 1" if path.present? || port.present? + end +end diff --git a/lib/kamal/configuration/logging.rb b/lib/kamal/configuration/logging.rb new file mode 100644 index 00000000..b0592b46 --- /dev/null +++ b/lib/kamal/configuration/logging.rb @@ -0,0 +1,33 @@ +class Kamal::Configuration::Logging + delegate :optionize, :argumentize, to: Kamal::Utils + + include Kamal::Configuration::Validation + + attr_reader :logging_config + + def initialize(logging_config:, context: "logging") + @logging_config = logging_config || {} + validate! @logging_config, context: context + end + + def driver + logging_config["driver"] + end + + def options + logging_config.fetch("options", {}) + end + + def merge(other) + self.class.new logging_config: logging_config.deep_merge(other.logging_config) + end + + def args + if driver.present? || options.present? + optionize({ "log-driver" => driver }.compact) + + argumentize("--log-opt", options) + else + argumentize("--log-opt", { "max-size" => "10m" }) + end + end +end diff --git a/lib/kamal/configuration/registry.rb b/lib/kamal/configuration/registry.rb new file mode 100644 index 00000000..fa0ba04a --- /dev/null +++ b/lib/kamal/configuration/registry.rb @@ -0,0 +1,31 @@ +class Kamal::Configuration::Registry + include Kamal::Configuration::Validation + + attr_reader :registry_config + + def initialize(config:) + @registry_config = config.raw_config.registry || {} + validate! registry_config, with: Kamal::Configuration::Validator::Registry + end + + def server + registry_config["server"] + end + + def username + lookup("username") + end + + def password + lookup("password") + end + + private + def lookup(key) + if registry_config[key].is_a?(Array) + ENV.fetch(registry_config[key].first).dup + else + registry_config[key] + end + end +end diff --git a/lib/kamal/configuration/role.rb b/lib/kamal/configuration/role.rb index f0df5924..e9e520a7 100644 --- a/lib/kamal/configuration/role.rb +++ b/lib/kamal/configuration/role.rb @@ -1,13 +1,33 @@ class Kamal::Configuration::Role + include Kamal::Configuration::Validation + CORD_FILE = "cord" delegate :argumentize, :optionize, to: Kamal::Utils - attr_accessor :name + attr_reader :name, :config, :specialized_env, :specialized_logging, :specialized_healthcheck + alias to_s name def initialize(name, config:) @name, @config = name.inquiry, config - @tagged_hosts ||= extract_tagged_hosts_from_config + validate! \ + specializations, + example: validation_yml["servers"]["workers"], + context: "servers/#{name}", + with: Kamal::Configuration::Validator::Role + + @specialized_env = Kamal::Configuration::Env.new \ + config: specializations.fetch("env", {}), + secrets_file: File.join(config.host_env_directory, "roles", "#{container_prefix}.env"), + context: "servers/#{name}/env" + + @specialized_logging = Kamal::Configuration::Logging.new \ + logging_config: specializations.fetch("logging", {}), + context: "servers/#{name}/logging" + + @specialized_healthcheck = Kamal::Configuration::Healthcheck.new \ + healthcheck_config: specializations.fetch("healthcheck", {}), + context: "servers/#{name}/healthcheck" end def primary_host @@ -43,21 +63,17 @@ class Kamal::Configuration::Role end def logging_args - args = config.logging || {} - args.deep_merge!(specializations["logging"]) if specializations["logging"].present? + logging.args + end - if args.any? - optionize({ "log-driver" => args["driver"] }.compact) + - argumentize("--log-opt", args["options"]) - else - config.logging_args - end + def logging + @logging ||= config.logging.merge(specialized_logging) end def env(host) @envs ||= {} - @envs[host] ||= [ base_env, specialized_env, *env_tags(host).map(&:env) ].reduce(:merge) + @envs[host] ||= [ config.env, specialized_env, *env_tags(host).map(&:env) ].reduce(:merge) end def env_args(host) @@ -70,28 +86,29 @@ class Kamal::Configuration::Role def health_check_args(cord: true) - if health_check_cmd.present? + if running_traefik? || healthcheck.set_port_or_path? if cord && uses_cord? - optionize({ "health-cmd" => health_check_cmd_with_cord, "health-interval" => health_check_interval }) + optionize({ "health-cmd" => health_check_cmd_with_cord, "health-interval" => healthcheck.interval }) .concat(cord_volume.docker_args) else - optionize({ "health-cmd" => health_check_cmd, "health-interval" => health_check_interval }) + optionize({ "health-cmd" => healthcheck.cmd, "health-interval" => healthcheck.interval }) end else [] end end - def health_check_cmd - health_check_options["cmd"] || http_health_check(port: health_check_options["port"], path: health_check_options["path"]) + def healthcheck + @healthcheck ||= + if running_traefik? + config.healthcheck.merge(specialized_healthcheck) + else + specialized_healthcheck + end end def health_check_cmd_with_cord - "(#{health_check_cmd}) && (stat #{cord_container_file} > /dev/null || exit 1)" - end - - def health_check_interval - health_check_options["interval"] || "1s" + "(#{healthcheck.cmd}) && (stat #{cord_container_file} > /dev/null || exit 1)" end @@ -109,7 +126,7 @@ class Kamal::Configuration::Role def uses_cord? - running_traefik? && cord_volume && health_check_cmd.present? + running_traefik? && cord_volume && healthcheck.cmd.present? end def cord_host_directory @@ -117,7 +134,7 @@ class Kamal::Configuration::Role end def cord_volume - if (cord = health_check_options["cord"]) + if (cord = healthcheck.cord) @cord_volume ||= Kamal::Configuration::Volume.new \ host_path: File.join(config.run_directory, "cords", [ container_prefix, config.run_id ].join("-")), container_path: cord @@ -170,30 +187,24 @@ class Kamal::Configuration::Role end private - attr_accessor :config, :tagged_hosts - - def extract_tagged_hosts_from_config + def tagged_hosts {}.tap do |tagged_hosts| extract_hosts_from_config.map do |host_config| if host_config.is_a?(Hash) - raise ArgumentError, "Multiple hosts found: #{host_config.inspect}" unless host_config.size == 1 - host, tags = host_config.first tagged_hosts[host] = Array(tags) - elsif host_config.is_a?(String) || host_config.is_a?(Symbol) + elsif host_config.is_a?(String) tagged_hosts[host_config] = [] - else - raise ArgumentError, "Invalid host config: #{host_config.inspect}" end end end end def extract_hosts_from_config - if config.servers.is_a?(Array) - config.servers + if config.raw_config.servers.is_a?(Array) + config.raw_config.servers else - servers = config.servers[name] + servers = config.raw_config.servers[name] servers.is_a?(Array) ? servers : Array(servers["hosts"]) end end @@ -202,6 +213,14 @@ class Kamal::Configuration::Role { "service" => config.service, "role" => name, "destination" => config.destination } end + def specializations + if config.raw_config.servers.is_a?(Array) || config.raw_config.servers[name].is_a?(Array) + {} + else + config.raw_config.servers[name] + end + end + def traefik_labels if running_traefik? { @@ -229,35 +248,4 @@ class Kamal::Configuration::Role labels.merge!(specializations["labels"]) if specializations["labels"].present? end end - - def specializations - if config.servers.is_a?(Array) || config.servers[name].is_a?(Array) - {} - else - config.servers[name].except("hosts") - end - end - - def specialized_env - Kamal::Configuration::Env.from_config config: specializations.fetch("env", {}) - end - - # Secrets are stored in an array, which won't merge by default, so have to do it by hand. - def base_env - Kamal::Configuration::Env.from_config \ - config: config.env, - secrets_file: File.join(config.host_env_directory, "roles", "#{container_prefix}.env") - end - - def http_health_check(port:, path:) - "curl -f #{URI.join("http://localhost:#{port}", path)} || exit 1" if path.present? || port.present? - end - - def health_check_options - @health_check_options ||= begin - options = specializations["healthcheck"] || {} - options = config.healthcheck.merge(options) if running_traefik? - options - end - end end diff --git a/lib/kamal/configuration/servers.rb b/lib/kamal/configuration/servers.rb new file mode 100644 index 00000000..ef5e7942 --- /dev/null +++ b/lib/kamal/configuration/servers.rb @@ -0,0 +1,18 @@ +class Kamal::Configuration::Servers + include Kamal::Configuration::Validation + + attr_reader :config, :servers_config, :roles + + def initialize(config:) + @config = config + @servers_config = config.raw_config.servers + validate! servers_config, with: Kamal::Configuration::Validator::Servers + + @roles = role_names.map { |role_name| Kamal::Configuration::Role.new role_name, config: config } + end + + private + def role_names + servers_config.is_a?(Array) ? [ "web" ] : servers_config.keys.sort + end +end diff --git a/lib/kamal/configuration/ssh.rb b/lib/kamal/configuration/ssh.rb index b9630102..99ca1d51 100644 --- a/lib/kamal/configuration/ssh.rb +++ b/lib/kamal/configuration/ssh.rb @@ -1,22 +1,27 @@ class Kamal::Configuration::Ssh LOGGER = ::Logger.new(STDERR) + include Kamal::Configuration::Validation + + attr_reader :ssh_config + def initialize(config:) - @config = config.raw_config.ssh || {} + @ssh_config = config.raw_config.ssh || {} + validate! ssh_config end def user - config.fetch("user", "root") + ssh_config.fetch("user", "root") end def port - config.fetch("port", 22) + ssh_config.fetch("port", 22) end def proxy - if (proxy = config["proxy"]) + if (proxy = ssh_config["proxy"]) Net::SSH::Proxy::Jump.new(proxy.include?("@") ? proxy : "root@#{proxy}") - elsif (proxy_command = config["proxy_command"]) + elsif (proxy_command = ssh_config["proxy_command"]) Net::SSH::Proxy::Command.new(proxy_command) end end @@ -30,13 +35,11 @@ class Kamal::Configuration::Ssh end private - attr_accessor :config - def logger LOGGER.tap { |logger| logger.level = log_level } end def log_level - config.fetch("log_level", :fatal) + ssh_config.fetch("log_level", :fatal) end end diff --git a/lib/kamal/configuration/sshkit.rb b/lib/kamal/configuration/sshkit.rb index 9631a916..9d4d61ce 100644 --- a/lib/kamal/configuration/sshkit.rb +++ b/lib/kamal/configuration/sshkit.rb @@ -1,20 +1,22 @@ class Kamal::Configuration::Sshkit + include Kamal::Configuration::Validation + + attr_reader :sshkit_config + def initialize(config:) - @options = config.raw_config.sshkit || {} + @sshkit_config = config.raw_config.sshkit || {} + validate! sshkit_config end def max_concurrent_starts - options.fetch("max_concurrent_starts", 30) + sshkit_config.fetch("max_concurrent_starts", 30) end def pool_idle_timeout - options.fetch("pool_idle_timeout", 900) + sshkit_config.fetch("pool_idle_timeout", 900) end def to_h - options + sshkit_config end - - private - attr_accessor :options end diff --git a/lib/kamal/configuration/traefik.rb b/lib/kamal/configuration/traefik.rb new file mode 100644 index 00000000..c958afdf --- /dev/null +++ b/lib/kamal/configuration/traefik.rb @@ -0,0 +1,60 @@ +class Kamal::Configuration::Traefik + DEFAULT_IMAGE = "traefik:v2.10" + CONTAINER_PORT = 80 + DEFAULT_ARGS = { + "log.level" => "DEBUG" + } + DEFAULT_LABELS = { + # These ensure we serve a 502 rather than a 404 if no containers are available + "traefik.http.routers.catchall.entryPoints" => "http", + "traefik.http.routers.catchall.rule" => "PathPrefix(`/`)", + "traefik.http.routers.catchall.service" => "unavailable", + "traefik.http.routers.catchall.priority" => 1, + "traefik.http.services.unavailable.loadbalancer.server.port" => "0" + } + + include Kamal::Configuration::Validation + + attr_reader :config, :traefik_config + + def initialize(config:) + @config = config + @traefik_config = config.raw_config.traefik || {} + validate! traefik_config + end + + def publish? + traefik_config["publish"] != false + end + + def labels + DEFAULT_LABELS.merge(traefik_config["labels"] || {}) + end + + def env + Kamal::Configuration::Env.new \ + config: traefik_config.fetch("env", {}), + secrets_file: File.join(config.host_env_directory, "traefik", "traefik.env"), + context: "traefik/env" + end + + def host_port + traefik_config.fetch("host_port", CONTAINER_PORT) + end + + def options + traefik_config.fetch("options", {}) + end + + def port + "#{host_port}:#{CONTAINER_PORT}" + end + + def args + DEFAULT_ARGS.merge(traefik_config.fetch("args", {})) + end + + def image + traefik_config.fetch("image", DEFAULT_IMAGE) + end +end diff --git a/lib/kamal/configuration/validation.rb b/lib/kamal/configuration/validation.rb new file mode 100644 index 00000000..37a0388b --- /dev/null +++ b/lib/kamal/configuration/validation.rb @@ -0,0 +1,27 @@ +require "yaml" +require "active_support/inflector" + +module Kamal::Configuration::Validation + extend ActiveSupport::Concern + + class_methods do + def validation_doc + @validation_doc ||= File.read(File.join(File.dirname(__FILE__), "docs", "#{validation_config_key}.yml")) + end + + def validation_config_key + @validation_config_key ||= name.demodulize.underscore + end + end + + def validate!(config, example: nil, context: nil, with: Kamal::Configuration::Validator) + context ||= self.class.validation_config_key + example ||= validation_yml[self.class.validation_config_key] + + with.new(config, example: example, context: context).validate! + end + + def validation_yml + @validation_yml ||= YAML.load(self.class.validation_doc) + end +end diff --git a/lib/kamal/configuration/validator.rb b/lib/kamal/configuration/validator.rb new file mode 100644 index 00000000..7b1665b6 --- /dev/null +++ b/lib/kamal/configuration/validator.rb @@ -0,0 +1,140 @@ +class Kamal::Configuration::Validator + attr_reader :config, :example, :context + + def initialize(config, example:, context:) + @config = config + @example = example + @context = context + end + + def validate! + validate_against_example! config, example + end + + private + def validate_against_example!(validation_config, example) + validate_type! validation_config, Hash + + if (unknown_keys = validation_config.keys - example.keys).any? + unknown_keys_error unknown_keys + end + + validation_config.each do |key, value| + with_context(key) do + example_value = example[key] + + if example_value == "..." + validate_type! value, *(Array if key == :servers), Hash + elsif key == "hosts" + validate_servers! value + elsif example_value.is_a?(Array) + validate_array_of! value, example_value.first.class + elsif example_value.is_a?(Hash) + case key.to_s + when "options" + validate_type! value, Hash + when "args", "labels" + validate_hash_of! value, example_value.first[1].class + else + validate_against_example! value, example_value + end + else + validate_type! value, example_value.class + end + end + end + end + + + def valid_type?(value, type) + value.is_a?(type) || + (type == String && stringish?(value)) || + (boolean?(type) && boolean?(value.class)) + end + + def type_description(type) + if type == Integer || type == Array + "an #{type.name.downcase}" + elsif type == TrueClass || type == FalseClass + "a boolean" + else + "a #{type.name.downcase}" + end + end + + def boolean?(type) + type == TrueClass || type == FalseClass + end + + def stringish?(value) + value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric) || value.is_a?(TrueClass) || value.is_a?(FalseClass) + end + + def validate_array_of!(array, type) + validate_type! array, Array + + array.each_with_index do |value, index| + with_context(index) do + validate_type! value, type + end + end + end + + def validate_hash_of!(hash, type) + validate_type! hash, Hash + + hash.each do |key, value| + with_context(key) do + validate_type! value, type + end + end + end + + def validate_servers!(servers) + validate_type! servers, Array + + servers.each_with_index do |server, index| + with_context(index) do + validate_type! server, String, Hash + + if server.is_a?(Hash) + error "multiple hosts found" unless server.size == 1 + host, tags = server.first + + with_context(host) do + validate_type! tags, String, Array + validate_array_of! tags, String if tags.is_a?(Array) + end + end + end + end + end + + def validate_type!(value, *types) + type_error(*types) unless types.any? { |type| valid_type?(value, type) } + end + + def error(message) + raise Kamal::ConfigurationError, "#{error_context}#{message}" + end + + def type_error(*expected_types) + error "should be #{expected_types.map { |type| type_description(type) }.join(" or ")}" + end + + def unknown_keys_error(unknown_keys) + error "unknown #{"key".pluralize(unknown_keys.count)}: #{unknown_keys.join(", ")}" + end + + def error_context + "#{context}: " if context.present? + end + + def with_context(context) + old_context = @context + @context = [ @context, context ].select(&:present?).join("/") + yield + ensure + @context = old_context + end +end diff --git a/lib/kamal/configuration/validator/accessory.rb b/lib/kamal/configuration/validator/accessory.rb new file mode 100644 index 00000000..33245e24 --- /dev/null +++ b/lib/kamal/configuration/validator/accessory.rb @@ -0,0 +1,9 @@ +class Kamal::Configuration::Validator::Accessory < Kamal::Configuration::Validator + def validate! + super + + if (config.keys & [ "host", "hosts", "roles" ]).size != 1 + error "specify one of `host`, `hosts` or `roles`" + end + end +end diff --git a/lib/kamal/configuration/validator/builder.rb b/lib/kamal/configuration/validator/builder.rb new file mode 100644 index 00000000..ebccdf81 --- /dev/null +++ b/lib/kamal/configuration/validator/builder.rb @@ -0,0 +1,9 @@ +class Kamal::Configuration::Validator::Builder < Kamal::Configuration::Validator + def validate! + super + + if config["cache"] && config["cache"]["type"] + error "Invalid cache type: #{config["cache"]["type"]}" unless [ "gha", "registry" ].include?(config["cache"]["type"]) + end + end +end diff --git a/lib/kamal/configuration/validator/env.rb b/lib/kamal/configuration/validator/env.rb new file mode 100644 index 00000000..a0d90d6d --- /dev/null +++ b/lib/kamal/configuration/validator/env.rb @@ -0,0 +1,54 @@ +class Kamal::Configuration::Validator::Env < Kamal::Configuration::Validator + SPECIAL_KEYS = [ "clear", "secret", "tags" ] + + def validate! + if known_keys.any? + validate_complex_env! + else + validate_simple_env! + end + end + + private + def validate_simple_env! + validate_hash_of!(config, String) + end + + def validate_complex_env! + unknown_keys_error unknown_keys if unknown_keys.any? + + with_context("clear") { validate_hash_of!(config["clear"], String) } if config.key?("clear") + with_context("secret") { validate_array_of!(config["secret"], String) } if config.key?("secret") + validate_tags! if config.key?("tags") + end + + def known_keys + @known_keys ||= config.keys & SPECIAL_KEYS + end + + def unknown_keys + @unknown_keys ||= config.keys - SPECIAL_KEYS + end + + def validate_tags! + if context == "env" + with_context("tags") do + validate_type! config["tags"], Hash + + config["tags"].each do |tag, value| + with_context(tag) do + validate_type! value, Hash + + Kamal::Configuration::Validator::Env.new( + value, + example: example["tags"].values[1], + context: context + ).validate! + end + end + end + else + error "tags are only allowed in the root env" + end + end +end diff --git a/lib/kamal/configuration/validator/registry.rb b/lib/kamal/configuration/validator/registry.rb new file mode 100644 index 00000000..2b9c0859 --- /dev/null +++ b/lib/kamal/configuration/validator/registry.rb @@ -0,0 +1,25 @@ +class Kamal::Configuration::Validator::Registry < Kamal::Configuration::Validator + STRING_OR_ONE_ITEM_ARRAY_KEYS = [ "username", "password" ] + + def validate! + validate_against_example! \ + config.except(*STRING_OR_ONE_ITEM_ARRAY_KEYS), + example.except(*STRING_OR_ONE_ITEM_ARRAY_KEYS) + + validate_string_or_one_item_array! "username" + validate_string_or_one_item_array! "password" + end + + private + def validate_string_or_one_item_array!(key) + with_context(key) do + value = config[key] + + error "is required" unless value.present? + + unless value.is_a?(String) || (value.is_a?(Array) && value.size == 1 && value.first.is_a?(String)) + error "should be a string or an array with one string (for secret lookup)" + end + end + end +end diff --git a/lib/kamal/configuration/validator/role.rb b/lib/kamal/configuration/validator/role.rb new file mode 100644 index 00000000..ce28c039 --- /dev/null +++ b/lib/kamal/configuration/validator/role.rb @@ -0,0 +1,11 @@ +class Kamal::Configuration::Validator::Role < Kamal::Configuration::Validator + def validate! + validate_type! config, Array, Hash + + if config.is_a?(Array) + validate_servers! "servers", config + else + super + end + end +end diff --git a/lib/kamal/configuration/validator/servers.rb b/lib/kamal/configuration/validator/servers.rb new file mode 100644 index 00000000..5a734c78 --- /dev/null +++ b/lib/kamal/configuration/validator/servers.rb @@ -0,0 +1,7 @@ +class Kamal::Configuration::Validator::Servers < Kamal::Configuration::Validator + def validate! + validate_type! config, Array, Hash + + validate_servers! config if config.is_a?(Array) + end +end diff --git a/test/cli/main_test.rb b/test/cli/main_test.rb index 40c11d39..94748fe8 100644 --- a/test/cli/main_test.rb +++ b/test/cli/main_test.rb @@ -380,19 +380,6 @@ class CliMainTest < CliTestCase end end - test "config with aliases" do - run_command("config", config_file: "deploy_with_aliases").tap do |output| - config = YAML.load(output) - - assert_equal [ "web", "web_tokyo", "workers", "workers_tokyo" ], config[:roles] - assert_equal [ "1.1.1.1", "1.1.1.2", "1.1.1.3", "1.1.1.4" ], config[:hosts] - assert_equal "999", config[:version] - assert_equal "registry.digitalocean.com/dhh/app", config[:repository] - assert_equal "registry.digitalocean.com/dhh/app:999", config[:absolute_image] - assert_equal "app-999", config[:service_with_version] - end - end - test "init" do Pathname.any_instance.expects(:exist?).returns(false).times(3) Pathname.any_instance.stubs(:mkpath) @@ -445,11 +432,10 @@ class CliMainTest < CliTestCase end test "envify" do - Pathname.any_instance.expects(:exist?).returns(true).times(3) - File.expects(:read).with(".env.erb").returns("HELLO=<%= 'world' %>") - File.expects(:write).with(".env", "HELLO=world", perm: 0600) - - run_command("envify") + with_test_dot_env_erb(contents: "HELLO=<%= 'world' %>") do + run_command("envify") + assert_equal("HELLO=world", File.read(".env")) + end end test "envify with blank line trimming" do @@ -460,19 +446,17 @@ class CliMainTest < CliTestCase <% end -%> EOF - Pathname.any_instance.expects(:exist?).returns(true).times(3) - File.expects(:read).with(".env.erb").returns(file.strip) - File.expects(:write).with(".env", "HELLO=world\nKEY=value\n", perm: 0600) - - run_command("envify") + with_test_dot_env_erb(contents: file) do + run_command("envify") + assert_equal("HELLO=world\nKEY=value\n", File.read(".env")) + end end test "envify with destination" do - Pathname.any_instance.expects(:exist?).returns(true).times(4) - File.expects(:read).with(".env.world.erb").returns("HELLO=<%= 'world' %>") - File.expects(:write).with(".env.world", "HELLO=world", perm: 0600) - - run_command("envify", "-d", "world", config_file: "deploy_for_dest") + with_test_dot_env_erb(contents: "HELLO=<%= 'world' %>", file: ".env.world.erb") do + run_command("envify", "-d", "world", config_file: "deploy_for_dest") + assert_equal "HELLO=world", File.read(".env.world") + end end test "envify with skip_push" do @@ -508,6 +492,24 @@ class CliMainTest < CliTestCase end end + test "docs" do + run_command("docs").tap do |output| + assert_match "# Kamal Configuration", output + end + end + + test "docs subsection" do + run_command("docs", "accessory").tap do |output| + assert_match "# Accessories", output + end + end + + test "docs unknown" do + run_command("docs", "foo").tap do |output| + assert_match "No documentation found for foo", output + end + end + test "version" do version = stdouted { Kamal::Cli::Main.new.version } assert_equal Kamal::VERSION, version @@ -517,4 +519,17 @@ class CliMainTest < CliTestCase def run_command(*command, config_file: "deploy_simple") stdouted { Kamal::Cli::Main.start([ *command, "-c", "test/fixtures/#{config_file}.yml" ]) } end + + def with_test_dot_env_erb(contents:, file: ".env.erb") + Dir.mktmpdir do |dir| + fixtures_dup = File.join(dir, "test") + FileUtils.mkdir_p(fixtures_dup) + FileUtils.cp_r("test/fixtures/", fixtures_dup) + + Dir.chdir(dir) do + File.write(file, contents) + yield + end + end + end end diff --git a/test/cli/traefik_test.rb b/test/cli/traefik_test.rb index 69f283d4..29171150 100644 --- a/test/cli/traefik_test.rb +++ b/test/cli/traefik_test.rb @@ -4,7 +4,7 @@ class CliTraefikTest < CliTestCase test "boot" do run_command("boot").tap do |output| assert_match "docker login", output - assert_match "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Commands::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", output + assert_match "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Configuration::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", output end end @@ -14,7 +14,7 @@ class CliTraefikTest < CliTestCase run_command("reboot", "-y").tap do |output| assert_match "docker container stop traefik", output assert_match "docker container prune --force --filter label=org.opencontainers.image.title=Traefik", output - assert_match "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Commands::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", output + assert_match "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Configuration::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", output end end diff --git a/test/commander_test.rb b/test/commander_test.rb index 6a7ec536..c2b78b21 100644 --- a/test/commander_test.rb +++ b/test/commander_test.rb @@ -137,17 +137,17 @@ class CommanderTest < ActiveSupport::TestCase end test "traefik hosts should observe filtered roles" do - configure_with(:deploy_with_aliases) + configure_with(:deploy_with_multiple_traefik_roles) @kamal.specific_roles = [ "web_tokyo" ] assert_equal [ "1.1.1.3", "1.1.1.4" ], @kamal.traefik_hosts end test "traefik hosts should observe filtered hosts" do - configure_with(:deploy_with_aliases) + configure_with(:deploy_with_multiple_traefik_roles) - @kamal.specific_hosts = [ "1.1.1.4" ] - assert_equal [ "1.1.1.4" ], @kamal.traefik_hosts + @kamal.specific_hosts = [ "1.1.1.2" ] + assert_equal [ "1.1.1.2" ], @kamal.traefik_hosts end private diff --git a/test/commands/accessory_test.rb b/test/commands/accessory_test.rb index 3eb80fc9..94c1bebc 100644 --- a/test/commands/accessory_test.rb +++ b/test/commands/accessory_test.rb @@ -24,7 +24,7 @@ class CommandsAccessoryTest < ActiveSupport::TestCase "host" => "1.1.1.6", "port" => "6379:6379", "labels" => { - "cache" => true + "cache" => "true" }, "env" => { "SOMETHING" => "else" diff --git a/test/commands/traefik_test.rb b/test/commands/traefik_test.rb index 74085967..27a3cb86 100644 --- a/test/commands/traefik_test.rb +++ b/test/commands/traefik_test.rb @@ -91,7 +91,7 @@ class CommandsTraefikTest < ActiveSupport::TestCase @config.delete(:traefik) assert_equal \ - "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Commands::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", + "docker run --name traefik --detach --restart unless-stopped --publish 80:80 --volume /var/run/docker.sock:/var/run/docker.sock --env-file .kamal/env/traefik/traefik.env --log-opt max-size=\"10m\" --label traefik.http.routers.catchall.entryPoints=\"http\" --label traefik.http.routers.catchall.rule=\"PathPrefix(\\`/\\`)\" --label traefik.http.routers.catchall.service=\"unavailable\" --label traefik.http.routers.catchall.priority=\"1\" --label traefik.http.services.unavailable.loadbalancer.server.port=\"0\" #{Kamal::Configuration::Traefik::DEFAULT_IMAGE} --providers.docker --log.level=\"DEBUG\"", new_command.run.join(" ") end diff --git a/test/configuration/accessory_test.rb b/test/configuration/accessory_test.rb index 51c98c6e..581cdab3 100644 --- a/test/configuration/accessory_test.rb +++ b/test/configuration/accessory_test.rb @@ -35,7 +35,7 @@ class ConfigurationAccessoryTest < ActiveSupport::TestCase "hosts" => [ "1.1.1.6", "1.1.1.7" ], "port" => "6379:6379", "labels" => { - "cache" => true + "cache" => "true" }, "env" => { "SOMETHING" => "else" @@ -44,7 +44,7 @@ class ConfigurationAccessoryTest < ActiveSupport::TestCase "/var/lib/redis:/data" ], "options" => { - "cpus" => 4, + "cpus" => "4", "memory" => "2GB" } }, @@ -54,13 +54,13 @@ class ConfigurationAccessoryTest < ActiveSupport::TestCase "roles" => [ "web" ], "port" => "4321:4321", "labels" => { - "cache" => true + "cache" => "true" }, "env" => { "STATSD_PORT" => "8126" }, "options" => { - "cpus" => 4, + "cpus" => "4", "memory" => "2GB" } } @@ -89,22 +89,20 @@ class ConfigurationAccessoryTest < ActiveSupport::TestCase test "missing host" do @deploy[:accessories]["mysql"]["host"] = nil - @config = Kamal::Configuration.new(@deploy) - assert_raises(ArgumentError) do - @config.accessory(:mysql).hosts + assert_raises(Kamal::ConfigurationError) do + Kamal::Configuration.new(@deploy) end end test "setting host, hosts and roles" do - @deploy[:accessories]["mysql"]["hosts"] = true - @deploy[:accessories]["mysql"]["roles"] = true - @config = Kamal::Configuration.new(@deploy) + @deploy[:accessories]["mysql"]["hosts"] = [ "mysql-db1" ] + @deploy[:accessories]["mysql"]["roles"] = [ "db" ] - exception = assert_raises(ArgumentError) do - @config.accessory(:mysql).hosts + exception = assert_raises(Kamal::ConfigurationError) do + Kamal::Configuration.new(@deploy) end - assert_equal "Specify one of `host`, `hosts` or `roles` for accessory `mysql`", exception.message + assert_equal "accessories/mysql: specify one of `host`, `hosts` or `roles`", exception.message end test "all hosts" do diff --git a/test/configuration/builder_test.rb b/test/configuration/builder_test.rb index a519be67..4b37b5e8 100644 --- a/test/configuration/builder_test.rb +++ b/test/configuration/builder_test.rb @@ -7,41 +7,37 @@ class ConfigurationBuilderTest < ActiveSupport::TestCase servers: [ "1.1.1.1" ] } - @config = Kamal::Configuration.new(@deploy) - @deploy_with_builder_option = { service: "app", image: "dhh/app", registry: { "username" => "dhh", "password" => "secret" }, servers: [ "1.1.1.1" ], builder: {} } - - @config_with_builder_option = Kamal::Configuration.new(@deploy_with_builder_option) end test "multiarch?" do - assert_equal true, @config.builder.multiarch? + assert_equal true, config.builder.multiarch? end test "setting multiarch to false" do @deploy_with_builder_option[:builder] = { "multiarch" => false } - assert_equal false, @config_with_builder_option.builder.multiarch? + assert_equal false, config_with_builder_option.builder.multiarch? end test "local?" do - assert_equal false, @config.builder.local? + assert_equal false, config.builder.local? end test "remote?" do - assert_equal false, @config.builder.remote? + assert_equal false, config.builder.remote? end test "remote_arch" do - assert_nil @config.builder.remote_arch + assert_nil config.builder.remote_arch end test "remote_host" do - assert_nil @config.builder.remote_host + assert_nil config.builder.remote_host end test "setting both local and remote configs" do @@ -50,112 +46,121 @@ class ConfigurationBuilderTest < ActiveSupport::TestCase "remote" => { "arch" => "amd64", "host" => "ssh://root@192.168.0.1" } } - assert_equal true, @config_with_builder_option.builder.local? - assert_equal true, @config_with_builder_option.builder.remote? + assert_equal true, config_with_builder_option.builder.local? + assert_equal true, config_with_builder_option.builder.remote? - assert_equal "amd64", @config_with_builder_option.builder.remote_arch - assert_equal "ssh://root@192.168.0.1", @config_with_builder_option.builder.remote_host + assert_equal "amd64", config_with_builder_option.builder.remote_arch + assert_equal "ssh://root@192.168.0.1", config_with_builder_option.builder.remote_host - assert_equal "arm64", @config_with_builder_option.builder.local_arch - assert_equal "unix:///Users/<%= `whoami`.strip %>/.docker/run/docker.sock", @config_with_builder_option.builder.local_host + assert_equal "arm64", config_with_builder_option.builder.local_arch + assert_equal "unix:///Users/<%= `whoami`.strip %>/.docker/run/docker.sock", config_with_builder_option.builder.local_host end test "cached?" do - assert_equal false, @config.builder.cached? + assert_equal false, config.builder.cached? end test "invalid cache type specified" do @deploy_with_builder_option[:builder] = { "cache" => { "type" => "invalid" } } - assert_raises(ArgumentError) do - @config_with_builder_option.builder + assert_raises(Kamal::ConfigurationError) do + config_with_builder_option.builder end end test "cache_from" do - assert_nil @config.builder.cache_from + assert_nil config.builder.cache_from end test "cache_to" do - assert_nil @config.builder.cache_to + assert_nil config.builder.cache_to end test "setting gha cache" do @deploy_with_builder_option[:builder] = { "cache" => { "type" => "gha", "options" => "mode=max" } } - assert_equal "type=gha", @config_with_builder_option.builder.cache_from - assert_equal "type=gha,mode=max", @config_with_builder_option.builder.cache_to + assert_equal "type=gha", config_with_builder_option.builder.cache_from + assert_equal "type=gha,mode=max", config_with_builder_option.builder.cache_to end test "setting registry cache" do @deploy_with_builder_option[:builder] = { "cache" => { "type" => "registry", "options" => "mode=max,image-manifest=true,oci-mediatypes=true" } } - assert_equal "type=registry,ref=dhh/app-build-cache", @config_with_builder_option.builder.cache_from - assert_equal "type=registry,mode=max,image-manifest=true,oci-mediatypes=true,ref=dhh/app-build-cache", @config_with_builder_option.builder.cache_to + assert_equal "type=registry,ref=dhh/app-build-cache", config_with_builder_option.builder.cache_from + assert_equal "type=registry,mode=max,image-manifest=true,oci-mediatypes=true,ref=dhh/app-build-cache", config_with_builder_option.builder.cache_to end test "setting registry cache when using a custom registry" do - @config_with_builder_option.registry["server"] = "registry.example.com" + @deploy_with_builder_option[:registry]["server"] = "registry.example.com" @deploy_with_builder_option[:builder] = { "cache" => { "type" => "registry", "options" => "mode=max,image-manifest=true,oci-mediatypes=true" } } - assert_equal "type=registry,ref=registry.example.com/dhh/app-build-cache", @config_with_builder_option.builder.cache_from - assert_equal "type=registry,mode=max,image-manifest=true,oci-mediatypes=true,ref=registry.example.com/dhh/app-build-cache", @config_with_builder_option.builder.cache_to + assert_equal "type=registry,ref=registry.example.com/dhh/app-build-cache", config_with_builder_option.builder.cache_from + assert_equal "type=registry,mode=max,image-manifest=true,oci-mediatypes=true,ref=registry.example.com/dhh/app-build-cache", config_with_builder_option.builder.cache_to end test "setting registry cache with image" do @deploy_with_builder_option[:builder] = { "cache" => { "type" => "registry", "image" => "kamal", "options" => "mode=max" } } - assert_equal "type=registry,ref=kamal", @config_with_builder_option.builder.cache_from - assert_equal "type=registry,mode=max,ref=kamal", @config_with_builder_option.builder.cache_to + assert_equal "type=registry,ref=kamal", config_with_builder_option.builder.cache_from + assert_equal "type=registry,mode=max,ref=kamal", config_with_builder_option.builder.cache_to end test "args" do - assert_equal({}, @config.builder.args) + assert_equal({}, config.builder.args) end test "setting args" do @deploy_with_builder_option[:builder] = { "args" => { "key" => "value" } } - assert_equal({ "key" => "value" }, @config_with_builder_option.builder.args) + assert_equal({ "key" => "value" }, config_with_builder_option.builder.args) end test "secrets" do - assert_equal [], @config.builder.secrets + assert_equal [], config.builder.secrets end test "setting secrets" do @deploy_with_builder_option[:builder] = { "secrets" => [ "GITHUB_TOKEN" ] } - assert_equal [ "GITHUB_TOKEN" ], @config_with_builder_option.builder.secrets + assert_equal [ "GITHUB_TOKEN" ], config_with_builder_option.builder.secrets end test "dockerfile" do - assert_equal "Dockerfile", @config.builder.dockerfile + assert_equal "Dockerfile", config.builder.dockerfile end test "setting dockerfile" do @deploy_with_builder_option[:builder] = { "dockerfile" => "Dockerfile.dev" } - assert_equal "Dockerfile.dev", @config_with_builder_option.builder.dockerfile + assert_equal "Dockerfile.dev", config_with_builder_option.builder.dockerfile end test "context" do - assert_equal ".", @config.builder.context + assert_equal ".", config.builder.context end test "setting context" do @deploy_with_builder_option[:builder] = { "context" => ".." } - assert_equal "..", @config_with_builder_option.builder.context + assert_equal "..", config_with_builder_option.builder.context end test "ssh" do - assert_nil @config.builder.ssh + assert_nil config.builder.ssh end test "setting ssh params" do @deploy_with_builder_option[:builder] = { "ssh" => "default=$SSH_AUTH_SOCK" } - assert_equal "default=$SSH_AUTH_SOCK", @config_with_builder_option.builder.ssh + assert_equal "default=$SSH_AUTH_SOCK", config_with_builder_option.builder.ssh end + + private + def config + Kamal::Configuration.new(@deploy) + end + + def config_with_builder_option + Kamal::Configuration.new(@deploy_with_builder_option) + end end diff --git a/test/configuration/env_test.rb b/test/configuration/env_test.rb index d24c6211..49d800ef 100644 --- a/test/configuration/env_test.rb +++ b/test/configuration/env_test.rb @@ -19,7 +19,7 @@ class ConfigurationEnvTest < ActiveSupport::TestCase test "secret" do ENV["PASSWORD"] = "hello" - env = Kamal::Configuration::Env.from_config config: { "secret" => [ "PASSWORD" ] } + env = Kamal::Configuration::Env.new config: { "secret" => [ "PASSWORD" ] } assert_config \ config: { "secret" => [ "PASSWORD" ] }, @@ -34,7 +34,7 @@ class ConfigurationEnvTest < ActiveSupport::TestCase "secret" => [ "PASSWORD" ] } - assert_raises(KeyError) { Kamal::Configuration::Env.from_config(config: { "secret" => [ "PASSWORD" ] }).secrets } + assert_raises(KeyError) { Kamal::Configuration::Env.new(config: { "secret" => [ "PASSWORD" ] }).secrets } end test "secret and clear" do @@ -67,7 +67,7 @@ class ConfigurationEnvTest < ActiveSupport::TestCase private def assert_config(config:, clear:, secrets:) - env = Kamal::Configuration::Env.from_config config: config + env = Kamal::Configuration::Env.new config: config, secrets_file: "secrets.env" assert_equal clear, env.clear assert_equal secrets, env.secrets end diff --git a/test/configuration/role_test.rb b/test/configuration/role_test.rb index 84fdfe6b..da9a3d1c 100644 --- a/test/configuration/role_test.rb +++ b/test/configuration/role_test.rb @@ -18,7 +18,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase "cmd" => "bin/jobs", "env" => { "REDIS_URL" => "redis://a/b", - "WEB_CONCURRENCY" => 4 + "WEB_CONCURRENCY" => "4" } } } @@ -53,7 +53,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase test "custom labels via role specialization" do @deploy_with_roles[:labels] = { "my.custom.label" => "50" } @deploy_with_roles[:servers]["workers"]["labels"] = { "my.custom.label" => "70" } - assert_equal "70", @config_with_roles.role(:workers).labels["my.custom.label"] + assert_equal "70", Kamal::Configuration.new(@deploy_with_roles).role(:workers).labels["my.custom.label"] end test "overwriting default traefik label" do @@ -63,7 +63,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase test "default traefik label on non-web role" do config = Kamal::Configuration.new(@deploy_with_roles.tap { |c| - c[:servers]["beta"] = { "traefik" => "true", "hosts" => [ "1.1.1.5" ] } + c[:servers]["beta"] = { "traefik" => true, "hosts" => [ "1.1.1.5" ] } }) assert_equal [ "--label", "service=\"app\"", "--label", "role=\"beta\"", "--label", "destination", "--label", "traefik.http.services.app-beta.loadbalancer.server.scheme=\"http\"", "--label", "traefik.http.routers.app-beta.rule=\"PathPrefix(\\`/\\`)\"", "--label", "traefik.http.routers.app-beta.priority=\"2\"", "--label", "traefik.http.middlewares.app-beta-retry.retry.attempts=\"5\"", "--label", "traefik.http.middlewares.app-beta-retry.retry.initialinterval=\"500ms\"", "--label", "traefik.http.routers.app-beta.middlewares=\"app-beta-retry@docker\"" ], config.role(:beta).label_args @@ -102,7 +102,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase @deploy_with_roles[:servers]["workers"]["env"] = { "clear" => { "REDIS_URL" => "redis://a/b", - "WEB_CONCURRENCY" => 4 + "WEB_CONCURRENCY" => "4" }, "secret" => [ "DB_PASSWORD" @@ -117,7 +117,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase DB_PASSWORD=secret&\"123 ENV - assert_equal expected_secrets_file, @config_with_roles.role(:workers).env("1.1.1.3").secrets_io.string + assert_equal expected_secrets_file, Kamal::Configuration.new(@deploy_with_roles).role(:workers).env("1.1.1.3").secrets_io.string assert_equal [ "--env-file", ".kamal/env/roles/app-workers.env", "--env", "REDIS_URL=\"redis://a/b\"", "--env", "WEB_CONCURRENCY=\"4\"" ], @config_with_roles.role(:workers).env_args("1.1.1.3") ensure ENV["REDIS_PASSWORD"] = nil @@ -128,7 +128,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase @deploy_with_roles[:servers]["workers"]["env"] = { "clear" => { "REDIS_URL" => "redis://a/b", - "WEB_CONCURRENCY" => 4 + "WEB_CONCURRENCY" => "4" }, "secret" => [ "DB_PASSWORD" @@ -141,7 +141,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase DB_PASSWORD=secret123 ENV - assert_equal expected_secrets_file, @config_with_roles.role(:workers).env("1.1.1.3").secrets_io.string + assert_equal expected_secrets_file, Kamal::Configuration.new(@deploy_with_roles).role(:workers).env("1.1.1.3").secrets_io.string assert_equal [ "--env-file", ".kamal/env/roles/app-workers.env", "--env", "REDIS_URL=\"redis://a/b\"", "--env", "WEB_CONCURRENCY=\"4\"" ], @config_with_roles.role(:workers).env_args("1.1.1.3") ensure ENV["DB_PASSWORD"] = nil @@ -163,7 +163,7 @@ class ConfigurationRoleTest < ActiveSupport::TestCase REDIS_PASSWORD=secret456 ENV - assert_equal expected_secrets_file, @config_with_roles.role(:workers).env("1.1.1.3").secrets_io.string + assert_equal expected_secrets_file, Kamal::Configuration.new(@deploy_with_roles).role(:workers).env("1.1.1.3").secrets_io.string assert_equal [ "--env-file", ".kamal/env/roles/app-workers.env", "--env", "REDIS_URL=\"redis://a/b\"", "--env", "WEB_CONCURRENCY=\"4\"" ], @config_with_roles.role(:workers).env_args("1.1.1.3") ensure ENV["REDIS_PASSWORD"] = nil @@ -191,8 +191,9 @@ class ConfigurationRoleTest < ActiveSupport::TestCase REDIS_PASSWORD=secret456 ENV - assert_equal expected_secrets_file, @config_with_roles.role(:workers).env("1.1.1.3").secrets_io.string - assert_equal [ "--env-file", ".kamal/env/roles/app-workers.env", "--env", "REDIS_URL=\"redis://c/d\"" ], @config_with_roles.role(:workers).env_args("1.1.1.3") + config = Kamal::Configuration.new(@deploy_with_roles) + assert_equal expected_secrets_file, config.role(:workers).env("1.1.1.3").secrets_io.string + assert_equal [ "--env-file", ".kamal/env/roles/app-workers.env", "--env", "REDIS_URL=\"redis://c/d\"" ], config.role(:workers).env_args("1.1.1.3") ensure ENV["REDIS_PASSWORD"] = nil end diff --git a/test/configuration/validation_test.rb b/test/configuration/validation_test.rb new file mode 100644 index 00000000..71a0aa11 --- /dev/null +++ b/test/configuration/validation_test.rb @@ -0,0 +1,116 @@ +require "test_helper" +class ConfigurationValidationTest < ActiveSupport::TestCase + test "unknown root key" do + assert_error "unknown key: unknown", unknown: "value" + assert_error "unknown keys: unknown, unknown2", unknown: "value", unknown2: "value" + end + + test "wrong root types" do + [ :service, :image, :asset_path, :hooks_path, :primary_role, :minimum_version, :run_directory ].each do |key| + assert_error "#{key}: should be a string", **{ key => [] } + end + + [ :require_destination, :allow_empty_roles ].each do |key| + assert_error "#{key}: should be a boolean", **{ key => "foo" } + end + + [ :stop_wait_time, :retain_containers, :readiness_delay ].each do |key| + assert_error "#{key}: should be an integer", **{ key => "foo" } + end + + assert_error "volumes: should be an array", volumes: "foo" + + assert_error "servers: should be an array or a hash", servers: "foo" + + [ :labels, :registry, :accessories, :env, :ssh, :sshkit, :builder, :traefik, :boot, :healthcheck, :logging ].each do |key| + assert_error "#{key}: should be a hash", **{ key =>[] } + end + end + + test "servers" do + assert_error "servers: should be an array or a hash", servers: "foo" + assert_error "servers/0: should be a string or a hash", servers: [ [] ] + assert_error "servers/0: multiple hosts found", servers: [ { "a" => "b", "c" => "d" } ] + assert_error "servers/0/foo: should be a string or an array", servers: [ { "foo" => {} } ] + assert_error "servers/0/foo/0: should be a string", servers: [ { "foo" => [ [] ] } ] + end + + test "roles" do + assert_error "servers/web: should be an array or a hash", servers: { "web" => "foo" } + assert_error "servers/web/hosts: should be an array", servers: { "web" => { "hosts" => "" } } + assert_error "servers/web/hosts/0: should be a string or a hash", servers: { "web" => { "hosts" => [ [] ] } } + assert_error "servers/web/options: should be a hash", servers: { "web" => { "options" => "" } } + assert_error "servers/web/logging/options: should be a hash", servers: { "web" => { "logging" => { "options" => "" } } } + assert_error "servers/web/logging/driver: should be a string", servers: { "web" => { "logging" => { "driver" => [] } } } + assert_error "servers/web/labels: should be a hash", servers: { "web" => { "labels" => [] } } + assert_error "servers/web/env: should be a hash", servers: { "web" => { "env" => [] } } + assert_error "servers/web/env: tags are only allowed in the root env", servers: { "web" => { "hosts" => [ "1.1.1.1" ], "env" => { "tags" => {} } } } + end + + test "registry" do + assert_error "registry/username: is required", registry: {} + assert_error "registry/password: is required", registry: { "username" => "foo" } + assert_error "registry/password: should be a string or an array with one string (for secret lookup)", registry: { "username" => "foo", "password" => [ "SECRET1", "SECRET2" ] } + assert_error "registry/server: should be a string", registry: { "username" => "foo", "password" => "bar", "server" => [] } + end + + test "accessories" do + assert_error "accessories/accessory1: should be a hash", accessories: { "accessory1" => [] } + assert_error "accessories/accessory1: unknown key: unknown", accessories: { "accessory1" => { "unknown" => "baz" } } + assert_error "accessories/accessory1/options: should be a hash", accessories: { "accessory1" => { "options" => [] } } + assert_error "accessories/accessory1/host: should be a string", accessories: { "accessory1" => { "host" => [] } } + assert_error "accessories/accessory1/env: should be a hash", accessories: { "accessory1" => { "env" => [] } } + assert_error "accessories/accessory1/env: tags are only allowed in the root env", accessories: { "accessory1" => { "host" => "host", "env" => { "tags" => {} } } } + end + + test "env" do + assert_error "env: should be a hash", env: [] + assert_error "env/FOO: should be a string", env: { "FOO" => [] } + assert_error "env/clear/FOO: should be a string", env: { "clear" => { "FOO" => [] } } + assert_error "env/secret: should be an array", env: { "secret" => { "FOO" => [] } } + assert_error "env/secret/0: should be a string", env: { "secret" => [ [] ] } + assert_error "env/tags: should be a hash", env: { "tags" => [] } + assert_error "env/tags/tag1: should be a hash", env: { "tags" => { "tag1" => "foo" } } + assert_error "env/tags/tag1/FOO: should be a string", env: { "tags" => { "tag1" => { "FOO" => [] } } } + assert_error "env/tags/tag1/clear/FOO: should be a string", env: { "tags" => { "tag1" => { "clear" => { "FOO" => [] } } } } + assert_error "env/tags/tag1/secret: should be an array", env: { "tags" => { "tag1" => { "secret" => {} } } } + assert_error "env/tags/tag1/secret/0: should be a string", env: { "tags" => { "tag1" => { "secret" => [ [] ] } } } + assert_error "env/tags/tag1: tags are only allowed in the root env", env: { "tags" => { "tag1" => { "tags" => {} } } } + end + + test "ssh" do + assert_error "ssh: unknown key: foo", ssh: { "foo" => "bar" } + assert_error "ssh/user: should be a string", ssh: { "user" => [] } + end + + test "sshkit" do + assert_error "sshkit: unknown key: foo", sshkit: { "foo" => "bar" } + assert_error "sshkit/max_concurrent_starts: should be an integer", sshkit: { "max_concurrent_starts" => "foo" } + end + + test "builder" do + assert_error "builder: unknown key: foo", builder: { "foo" => "bar" } + assert_error "builder/remote: should be a hash", builder: { "remote" => true } + assert_error "builder/remote: unknown key: foo", builder: { "remote" => { "foo" => "bar" } } + assert_error "builder/local: unknown key: foo", builder: { "local" => { "foo" => "bar" } } + assert_error "builder/remote/arch: should be a string", builder: { "remote" => { "arch" => [] } } + assert_error "builder/args/foo: should be a string", builder: { "args" => { "foo" => [] } } + assert_error "builder/cache/options: should be a string", builder: { "cache" => { "options" => [] } } + end + + private + def assert_error(message, **invalid_config) + valid_config = { + service: "app", + image: "app", + registry: { "username" => "user", "password" => "secret" }, + servers: [ "1.1.1.1" ] + } + + error = assert_raises Kamal::ConfigurationError do + Kamal::Configuration.new(valid_config.merge(invalid_config)) + end + + assert_equal message, error.message + end +end diff --git a/test/configuration_test.rb b/test/configuration_test.rb index e7e7f151..6e83054b 100644 --- a/test/configuration_test.rb +++ b/test/configuration_test.rb @@ -28,7 +28,7 @@ class ConfigurationTest < ActiveSupport::TestCase %i[ service image registry ].each do |key| test "#{key} config required" do - assert_raise(ArgumentError) do + assert_raise(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.tap { _1.delete key } end end @@ -36,19 +36,21 @@ class ConfigurationTest < ActiveSupport::TestCase %w[ username password ].each do |key| test "registry #{key} required" do - assert_raise(ArgumentError) do + assert_raise(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.tap { _1[:registry].delete key } end end end test "service name valid" do - assert Kamal::Configuration.new(@deploy.tap { _1[:service] = "hey-app1_primary" }).valid? - assert Kamal::Configuration.new(@deploy.tap { _1[:service] = "MyApp" }).valid? + assert_nothing_raised do + Kamal::Configuration.new(@deploy.tap { _1[:service] = "hey-app1_primary" }) + Kamal::Configuration.new(@deploy.tap { _1[:service] = "MyApp" }) + end end test "service name invalid" do - assert_raise(ArgumentError) do + assert_raise(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.tap { _1[:service] = "app.com" } end end @@ -158,39 +160,34 @@ class ConfigurationTest < ActiveSupport::TestCase assert_equal "healthcheck-app", @config.healthcheck_service end - test "valid config" do - assert @config.valid? - assert @config_with_roles.valid? - end - test "hosts required for all roles" do # Empty server list for implied web role - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: []) end # Empty server list - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => [] }) end # Missing hosts key - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => {} }) end # Empty hosts list - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => { "hosts" => [] } }) end # Nil hosts - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => { "hosts" => nil } }) end # One role with hosts, one without - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => %w[ web ], "workers" => { "hosts" => %w[ ] } }) end end @@ -200,7 +197,7 @@ class ConfigurationTest < ActiveSupport::TestCase Kamal::Configuration.new @deploy.merge(servers: { "web" => %w[ web ], "workers" => { "hosts" => %w[ ] } }, allow_empty_roles: true) end - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new @deploy.merge(servers: { "web" => %w[], "workers" => { "hosts" => %w[] } }, allow_empty_roles: true) end end @@ -215,17 +212,17 @@ class ConfigurationTest < ActiveSupport::TestCase test "logging args with configured options" do config = Kamal::Configuration.new(@deploy.tap { |c| c.merge!(logging: { "options" => { "max-size" => "100m", "max-file" => 5 } }) }) - assert_equal [ "--log-opt", "max-size=\"100m\"", "--log-opt", "max-file=\"5\"" ], @config.logging_args + assert_equal [ "--log-opt", "max-size=\"100m\"", "--log-opt", "max-file=\"5\"" ], config.logging_args end test "logging args with configured driver and options" do config = Kamal::Configuration.new(@deploy.tap { |c| c.merge!(logging: { "driver" => "local", "options" => { "max-size" => "100m", "max-file" => 5 } }) }) - assert_equal [ "--log-driver", "\"local\"", "--log-opt", "max-size=\"100m\"", "--log-opt", "max-file=\"5\"" ], @config.logging_args + assert_equal [ "--log-driver", "\"local\"", "--log-opt", "max-size=\"100m\"", "--log-opt", "max-file=\"5\"" ], config.logging_args end test "erb evaluation of yml config" do config = Kamal::Configuration.create_from config_file: Pathname.new(File.expand_path("fixtures/deploy.erb.yml", __dir__)) - assert_equal "my-user", config.registry["username"] + assert_equal "my-user", config.registry.username end test "destination yml config merge" do @@ -249,7 +246,7 @@ class ConfigurationTest < ActiveSupport::TestCase test "destination required" do dest_config_file = Pathname.new(File.expand_path("fixtures/deploy_for_required_dest.yml", __dir__)) - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do config = Kamal::Configuration.create_from config_file: dest_config_file end @@ -272,7 +269,7 @@ class ConfigurationTest < ActiveSupport::TestCase volume_args: [ "--volume", "/local/path:/container/path" ], builder: {}, logging: [ "--log-opt", "max-size=\"10m\"" ], - healthcheck: { "path"=>"/up", "port"=>3000, "max_attempts" => 7, "cord" => "/tmp/kamal-cord", "log_lines" => 50 } } + healthcheck: { "cmd"=>"curl -f http://localhost:3000/up || exit 1", "interval" => "1s", "path"=>"/up", "port"=>3000, "max_attempts" => 7, "cord" => "/tmp/kamal-cord", "log_lines" => 50 } } assert_equal expected_config, @config.to_h end @@ -288,7 +285,7 @@ class ConfigurationTest < ActiveSupport::TestCase end test "min version is higher" do - assert_raises(ArgumentError) do + assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new(@deploy.tap { |c| c.merge!(minimum_version: "10000.0.0") }) end end @@ -334,7 +331,7 @@ class ConfigurationTest < ActiveSupport::TestCase end test "primary role missing" do - error = assert_raises(ArgumentError) do + error = assert_raises(Kamal::ConfigurationError) do Kamal::Configuration.new(@deploy.merge(primary_role: "bar")) end assert_match /bar isn't defined/, error.message @@ -345,6 +342,6 @@ class ConfigurationTest < ActiveSupport::TestCase config = Kamal::Configuration.new(@deploy_with_roles.merge(retain_containers: 2)) assert_equal 2, config.retain_containers - assert_raises(ArgumentError) { Kamal::Configuration.new(@deploy_with_roles.merge(retain_containers: 0)) } + assert_raises(Kamal::ConfigurationError) { Kamal::Configuration.new(@deploy_with_roles.merge(retain_containers: 0)) } end end diff --git a/test/fixtures/deploy_primary_web_role_override.yml b/test/fixtures/deploy_primary_web_role_override.yml index e372c602..694a9be7 100644 --- a/test/fixtures/deploy_primary_web_role_override.yml +++ b/test/fixtures/deploy_primary_web_role_override.yml @@ -2,12 +2,12 @@ service: app image: dhh/app servers: web_chicago: - traefik: enabled + traefik: true hosts: - 1.1.1.1 - 1.1.1.2 web_tokyo: - traefik: enabled + traefik: true hosts: - 1.1.1.3 - 1.1.1.4 diff --git a/test/fixtures/deploy_with_aliases.yml b/test/fixtures/deploy_with_aliases.yml deleted file mode 100644 index 90c18b57..00000000 --- a/test/fixtures/deploy_with_aliases.yml +++ /dev/null @@ -1,36 +0,0 @@ -# helper aliases -chicago_hosts: &chicago_hosts - hosts: - - 1.1.1.1 - - 1.1.1.2 -tokyo_hosts: &tokyo_hosts - hosts: - - 1.1.1.3 - - 1.1.1.4 -web_common: &web_common - env: - ROLE: "web" - traefik: true - -# actual config -service: app -image: dhh/app -servers: - web: - <<: *chicago_hosts - <<: *web_common - web_tokyo: - <<: *tokyo_hosts - <<: *web_common - workers: - cmd: bin/jobs - <<: *chicago_hosts - workers_tokyo: - cmd: bin/jobs - <<: *tokyo_hosts -env: - REDIS_URL: redis://x/y -registry: - server: registry.digitalocean.com - username: user - password: pw diff --git a/test/fixtures/deploy_with_multiple_traefik_roles.yml b/test/fixtures/deploy_with_multiple_traefik_roles.yml new file mode 100644 index 00000000..a36a409f --- /dev/null +++ b/test/fixtures/deploy_with_multiple_traefik_roles.yml @@ -0,0 +1,34 @@ +# actual config +service: app +image: dhh/app +servers: + web: + hosts: + - 1.1.1.1 + - 1.1.1.2 + env: + ROLE: "web" + traefik: true + web_tokyo: + hosts: + - 1.1.1.3 + - 1.1.1.4 + env: + ROLE: "web" + traefik: true + workers: + cmd: bin/jobs + hosts: + - 1.1.1.1 + - 1.1.1.2 + workers_tokyo: + cmd: bin/jobs + hosts: + - 1.1.1.3 + - 1.1.1.4 +env: + REDIS_URL: redis://x/y +registry: + server: registry.digitalocean.com + username: user + password: pw diff --git a/test/integration/integration_test.rb b/test/integration/integration_test.rb index f8f54d42..ea445d9e 100644 --- a/test/integration/integration_test.rb +++ b/test/integration/integration_test.rb @@ -146,6 +146,6 @@ class IntegrationTest < ActiveSupport::TestCase end def container_running?(host:, name:) - docker_compose("exec #{host} docker ps --filter=name=#{name} | tail -n+2", capture: true).tap { |x| p [ x, x.strip, x.strip.present? ] }.strip.present? + docker_compose("exec #{host} docker ps --filter=name=#{name} | tail -n+2", capture: true).strip.present? end end diff --git a/test/integration/main_test.rb b/test/integration/main_test.rb index 62857d4a..c4558c1d 100644 --- a/test/integration/main_test.rb +++ b/test/integration/main_test.rb @@ -79,7 +79,7 @@ class MainTest < IntegrationTest assert_equal({ user: "root", port: 22, keepalive: true, keepalive_interval: 30, log_level: :fatal }, config[:ssh_options]) assert_equal({ "multiarch" => false, "args" => { "COMMIT_SHA" => version } }, config[:builder]) assert_equal [ "--log-opt", "max-size=\"10m\"" ], config[:logging] - assert_equal({ "path" => "/up", "port" => 3000, "max_attempts" => 3, "cord"=>"/tmp/kamal-cord", "log_lines" => 50, "cmd"=>"wget -qO- http://localhost > /dev/null || exit 1" }, config[:healthcheck]) + assert_equal({ "cmd"=>"wget -qO- http://localhost > /dev/null || exit 1", "interval"=>"1s", "max_attempts"=>3, "port"=>3000, "path"=>"/up", "cord"=>"/tmp/kamal-cord", "log_lines"=>50 }, config[:healthcheck]) end test "setup and remove" do