kubernetes_template_rendering 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5db190341419a622d7593eea77f9ad5525839c0c2039d540edd55a6ce8117479
-  data.tar.gz: ac8e1ec55caccb59e15cc7b552c58e433f14ac3d3946b9100a1895cfcab97ea2
+  metadata.gz: 2834614aaa2465ab9be3a1c50b6c2d2a1b1f4264ecadafddcb5bf8365c5bb151
+  data.tar.gz: 6142bd0df1d9da48f1058409017f2080082deb81d13b4c02b4dce2bef2ed80ef
 SHA512:
-  metadata.gz: 34090f91339fc87a45fb91bd3174f281953d952f618ee91b035fb4ecc1dca9c9f2f1cbc8c0f7450cdac739c93229e5b18c4a7e547d22bc735f550808747de74b
-  data.tar.gz: 8bac2935eb16a00898e10f132f8fb5260a71feae470719267111ea2118c3a2d25267130e8d71683936e4faa40473aa8616f2ba90060abdbcf1af29e2a8c721be
+  metadata.gz: bd84f186eda857691bb2825188bcabb8dfc8af8e9c9054623263d72db981d3bba853177f31fd63de4a57f6b982ead442724515a54cc2c42b0454c41c0a9aff6f
+  data.tar.gz: 8aa7fac766cd4f19e6994a1a51a68bbaf09db56384ae979d403ee4f795a6d7d78a0d9fc4211330d620253033a730306a7eb3d0541995a6436ecfe150a720320e

data/CHANGELOG.md

@@ -4,6 +4,22 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-07-23
+### Added
+- `--variable-override` now supports dotted-path keys (`components.webServer.hpa.minReplicas:2`) that deep-merge into nested variables, with JSON value coercion (integers, floats, booleans, `null`, quoted strings; non-JSON values stay raw strings) and `\.` escaping for literal dots. Plain `KEY:VALUE` (no dot) behaves exactly as before: top-level key, raw string value.
+- Added `--variable-override-json '<json object>'` (repeatable), deep-merged with all other override flags in command-line order (later flags win). Use it for values containing commas or whole structures.
+- Overrides are echoed once to stdout at render start (`Variable overrides (deep-merged after definitions.yaml): {...}`). Rendered files still carry no override comment (see 0.3.0).
+
+### Changed
+- `Template#initialize` merges `variable_overrides` with `deep_merge` instead of `merge`. Behavior-identical for all previously-valid inputs (legacy override values are always strings, so no hash-vs-hash merge could occur).
+
+## [0.6.2] - 2026-07-15
+### Fixed
+- Fixed the `--reconcile` sweep root for entries whose `subdirectory:` nests more than one level deep (e.g. `subdirectory: exclude-argocd/auth`). The sweep root is now the entry's canonical base — `<region>/<cluster_type>/<color>` for non-SPP entries and `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER` for SPP entries — regardless of `subdirectory:` depth, rather than the immediate parent of the rendered output directory. Previously a nested `subdirectory:` pushed the sweep root one level too deep, so when a `subdirectory:` was renamed or nested deeper the files left at the old shallower path were siblings of the sweep root and were never swept.
+
+### Changed
+- Under `--reconcile`, non-SPP entries must now render within their canonical `<region>/<cluster_type>/<color>` base; an entry that renders outside it (only reachable via the deprecated `directory:` field) hard-errors before any writes. This completes the reconcile layout hard-validation deferred in ADR-0001 — SPP entries were already constrained to the `spp/SPP-PLACEHOLDER` prefix. See ADR-0001.
+
 ## [0.6.1] - 2026-07-08
 ### Fixed
 - Fixed `variable_overrides` and `source_repo` not being forwarded to child `Resource` instances created by `DeployGroupedResource`. Previously, `--variable-override` values (e.g. `deploySha`) were silently unavailable inside all `*-deploy.jsonnet` and `*-deploy.yaml.erb` templates, causing a `KeyError` at render time. `DeployGroupedResource#initialize` now accepts both as optional keyword arguments and passes them through to each `Resource.new` call in `#render`. `ResourceSet#grouped_resources` is updated to supply both values.

data/README.md

@@ -71,6 +71,43 @@ Useful when one `--cluster_type` matches multiple sibling entries (e.g. `staging
 
 If an `--only` value matches no entry across any template directory, the gem raises with the list of valid keys so the caller can self-correct.
 
+### Variable overrides
+
+Pass `--variable-override KEY:VALUE` (repeatable) to override values from `definitions.yaml` after all per-section variables and auto-injected region/cluster vars are resolved. Overrides always win.
+
+**Legacy form (no dot in KEY):** sets a top-level key to the raw string value — exactly the pre-0.7.0 behavior. Values are never type-coerced (`deploySha:12345` stays the string `"12345"`; `enabled:true` stays `"true"`). The value is everything after the first colon (`image:registry:5000/app` → `"registry:5000/app"`). Arguments with no colon are silently ignored.
+
+```bash
+gem exec -g kubernetes_template_rendering render_templates \
+    --rendered-directory path/to/resources \
+    --variable-override deploySha:abc123 \
+    deployment/templates
+```
+
+**Dotted-path form (KEY contains `.`):** the key is split on unescaped dots into a nested path and deep-merged into variables. The value is JSON-coerced when it parses as JSON (`2` → integer, `true`/`false` → booleans, `null` → nil, `"2"` → string); otherwise the raw string is kept (`hello` → `"hello"`, `02` → `"02"`).
+
+```bash
+gem exec -g kubernetes_template_rendering render_templates \
+    --rendered-directory path/to/resources \
+    --variable-override components.webServer.hpa.minReplicas:2 \
+    deployment/templates
+```
+
+Escape literal dots in a segment with `\.` (e.g. `metadata.labels.app\.kubernetes\.io/name:foo`). Only `\.` is an escape sequence; all other backslashes — including trailing ones — are kept literally. Keys that would need a literal backslash immediately before a path-splitting dot must use `--variable-override-json` instead.
+
+**`--variable-override-json` (repeatable):** deep-merges a JSON object. Use this for values containing commas or whole arrays/objects (the legacy Array acceptor comma-splits `KEY:VALUE` arguments).
+
+```bash
+gem exec -g kubernetes_template_rendering render_templates \
+    --rendered-directory path/to/resources \
+    --variable-override-json '{"ephemeral":{"mysql":{"enabled":true}}}' \
+    deployment/templates
+```
+
+**Precedence:** all override flags are folded into one hash in command-line order via deep merge (later flags win on conflict), then deep-merged last over the fully-resolved variables.
+
+Overrides are echoed once to stdout at render start (`Variable overrides (deep-merged after definitions.yaml): {...}`). Rendered files carry no override comment (removed in [0.3.0](CHANGELOG.md#030---2026-06-24) to avoid content-free diffs on every deploy).
+
 ### Staging Partial Platforms
 
 Pass `--spp NAME` (repeatable) to expand any entry whose `definitions.yaml` name contains `SPP-PLACEHOLDER` into a per-SPP sibling output. Substitutes `SPP-PLACEHOLDER` with `NAME` and the `PLACEHOLDER` suffix with the suffix of `NAME` (everything after the last `-`), in both file paths and contents. Source mtimes are preserved.

data/lib/kubernetes_template_rendering/cli.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+require "json"
+
 require_relative "template_directory_renderer"
 require_relative "cli_arguments"
+require_relative "variable_override_parser"
 
 module KubernetesTemplateRendering
   class CLI
@@ -43,21 +46,30 @@ module KubernetesTemplateRendering
             args.only << name
           end
 
-          op.on("--variable-override=KEY:VALUE", "override a variable value set within definitions.yaml", Array) do |overrides|
+          op.on("--variable-override=KEY:VALUE", "override a variable value set within definitions.yaml (KEY may be a dotted path, e.g. components.webServer.hpa.minReplicas:2; escape literal dots as \\.)", Array) do |overrides|
             args.variable_overrides ||= {} # Initialize as a Hash
             overrides.each do |override|
-              key, value = override.split(":", 2)
-              args.variable_overrides[key] = value if key && value
+              VariableOverrideParser.merge_override!(args.variable_overrides, override)
             end
           end
 
+          op.on("--variable-override-json=JSON", "deep-merge a JSON object of variable overrides (repeatable; later flags win)") do |json|
+            args.variable_overrides ||= {}
+            VariableOverrideParser.merge_json!(args.variable_overrides, json)
+          end
+
           op.on("-h", "--help") do
             puts op
             exit
           end
         end
 
-        parser.parse!(options)
+        begin
+          parser.parse!(options)
+        rescue VariableOverrideParser::ParseError => ex
+          STDERR.puts(ex.message)
+          exit(1)
+        end
         args.template_directory = options.first
         args.spps = (args.spps || []).uniq
         args.only = (args.only || []).uniq
@@ -80,6 +92,10 @@ module KubernetesTemplateRendering
           exit(1)
         end
 
+        if args.variable_overrides&.any?
+          puts "Variable overrides (deep-merged after definitions.yaml): #{JSON.generate(args.variable_overrides)}"
+        end
+
         [renderer_from_args(args), args]
       end
 

data/lib/kubernetes_template_rendering/resource_set.rb

@@ -74,12 +74,13 @@ module KubernetesTemplateRendering
 
     # Bounded reconcile scope roots for this entry, one per region × color.
     #
-    # The sweep root is the parent directory of the entry's rendered `output_directory`, derived
-    # from the actual `directory:` pattern rather than assuming a fixed layout. For a
-    # `.../<service>` pattern that parent is the `<region>/<cluster_type>/<color>` base; for a
-    # `<region>/<service>` pattern it is `<region>`. The parent is shared with sibling entries, so
-    # leftovers from a deleted/renamed entry under it are swept. The renderer validates each
-    # `base_root` stays within `rendered_directory` (out-of-prefix, full or relative, is a hard error).
+    # The sweep root is the entry's canonical base — `<region>/<cluster_type>/<color>` for a non-SPP
+    # entry, or `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER` for an SPP one — independent of
+    # how deep the `subdirectory:` nests. Anchoring at the canonical base (rather than the rendered
+    # `output_directory`'s parent) keeps the sweep root fixed when a `subdirectory:` is renamed or
+    # nested deeper, so leftovers at the old shallower path are still swept. The renderer validates
+    # that the `output_directory` actually falls within this root before sweeping (an entry that
+    # renders elsewhere — only reachable via the deprecated `directory:` field — is a hard error).
     #
     # Each scope also carries `spp:` (whether this entry is an SPP definition) and `spp_base_root:`
     # (the canonical `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER` prefix for that region ×
@@ -88,8 +89,10 @@ module KubernetesTemplateRendering
       @regions.flat_map do |plain_region|
         @colors.map do |c|
           output_directory = File.join(@rendered_directory, format(@target_output_directory, plain_region: plain_region, color: c, type: @kubernetes_cluster_type))
+          base_path        = File.join(@rendered_directory, format(BASE_OUTPUT_DIRECTORY, plain_region: plain_region, color: c, type: @kubernetes_cluster_type))
           spp_base_root    = File.join(@rendered_directory, format(SPP_BASE_OUTPUT_DIRECTORY, plain_region: plain_region, color: c, type: @kubernetes_cluster_type))
-          { base_root: File.dirname(output_directory), output_directory: output_directory, spp: @spp, spp_base_root: spp_base_root }
+          base_root        = @spp ? spp_base_root : base_path
+          { base_root: base_root, output_directory: output_directory, spp: @spp, spp_base_root: spp_base_root }
         end
       end
     end

data/lib/kubernetes_template_rendering/template.rb

@@ -4,6 +4,7 @@ require "ostruct"
 require "open3"
 require "shellwords"
 require "yaml"
+require "active_support/core_ext/hash/deep_merge"
 
 # This is a base class for all Templates. Derived classes must implement the render method.
 module KubernetesTemplateRendering
@@ -12,7 +13,7 @@ module KubernetesTemplateRendering
 
     def initialize(template_path, variables, source_repo: nil, variable_overrides: {})
       @template_path      = template_path
-      @variables          = variables.merge(variable_overrides)
+      @variables          = variables.deep_merge(variable_overrides)
       @source_repo        = source_repo
       @variable_overrides = variable_overrides
     end

data/lib/kubernetes_template_rendering/template_directory_renderer.rb

@@ -92,6 +92,11 @@ module KubernetesTemplateRendering
       scopes.each do |scope|
         validate_within_scope!(scope[:base_root], @rendered_directory)
         validate_spp_layout!(scope)
+        # Every entry must render within its canonical root so reconcile owns exactly what it sweeps.
+        # SPP entries are already constrained to the spp/SPP-PLACEHOLDER prefix by validate_spp_layout!;
+        # a non-SPP entry can only escape its base via the deprecated `directory:` field, which reconcile
+        # cannot own — so reject it before any writes rather than sweep a tree it does not render into.
+        validate_within_scope!(scope[:output_directory], scope[:base_root]) unless scope[:spp]
       end
 
       base_roots = []
@@ -142,7 +147,8 @@ module KubernetesTemplateRendering
     # is always re-rendered (it is the expansion source) and each target is freshly expanded from it,
     # so both are marker-safe. Unrequested SPP siblings are not re-rendered this run and stay excluded.
     def spp_reconcile_roots(scope)
-      root = spp_sweep_root(scope)
+      # base_root is the canonical `.../spp/SPP-PLACEHOLDER` prefix for SPP entries.
+      root = scope[:base_root]
       return [root] if @spps.empty?
       return [root] unless root.include?(ResourceSet::SPP_PLACEHOLDER)
 
@@ -153,13 +159,6 @@ module KubernetesTemplateRendering
       Pathname.new(root).relative_path_from(Pathname.new(@rendered_directory)).each_filename.include?(SPP_FENCE_DIRNAME)
     end
 
-    # When the directory pattern has no service subdirectory (e.g. `.../spp/SPP-PLACEHOLDER`),
-    # base_root lands at the `spp/` level itself — sweeping that would touch all SPP siblings.
-    # Use output_directory (= `spp/<spp-name>`) in that case instead.
-    def spp_sweep_root(scope)
-      File.basename(scope[:base_root]) == SPP_FENCE_DIRNAME ? scope[:output_directory] : scope[:base_root]
-    end
-
     def reconcile_sweep(reconciler, scopes)
       scopes[:base_roots].each { |r| reconciler.sweep!(root: r, fences: [File.join(r, SPP_FENCE_DIRNAME)]) }
       scopes[:spp_roots].each  { |r| reconciler.sweep!(root: r) }

data/lib/kubernetes_template_rendering/variable_override_parser.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/core_ext/hash/deep_merge"
+
+module KubernetesTemplateRendering
+  # Parses --variable-override / --variable-override-json values into (possibly nested)
+  # override fragments and deep-merges them, in command-line order, into one overrides hash.
+  #
+  # Key forms:
+  #   * Legacy: KEY contains no "." -> top-level key, value kept as the raw string
+  #     (exactly the pre-0.7.0 behavior; never type-coerced).
+  #   * Dotted: KEY contains "." -> split on unescaped dots into a nested path ("\." is a
+  #     literal dot within a segment). The value is JSON-coerced when it parses as JSON
+  #     (2 -> Integer, true/false -> booleans, null -> nil, "2" -> String), else kept raw.
+  class VariableOverrideParser
+    class ParseError < StandardError; end
+
+    UNESCAPED_DOT = /(?<!\\)\./.freeze
+
+    class << self
+      # Deep-merges a KEY:VALUE override fragment into +overrides+.
+      #
+      # @param overrides [Hash] accumulated overrides hash (mutated in place)
+      # @param raw [String] raw KEY:VALUE argument
+      # @return [Hash] +overrides+ after merging
+      def merge_override!(overrides, raw)
+        key, value = raw.split(":", 2)
+        return overrides if key.nil? || value.nil? # preserve legacy silent-skip of colon-less args
+
+        overrides.deep_merge!(fragment_for(key, value))
+      end
+
+      # Deep-merges a JSON object string into +overrides+.
+      #
+      # @param overrides [Hash] accumulated overrides hash (mutated in place)
+      # @param json [String] JSON object string
+      # @return [Hash] +overrides+ after merging
+      # @raise [ParseError] when +json+ is invalid or not a JSON object
+      def merge_json!(overrides, json)
+        fragment =
+          begin
+            JSON.parse(json)
+          rescue JSON::ParserError => ex
+            raise ParseError, "--variable-override-json value is not valid JSON: #{ex.message}"
+          end
+        fragment.is_a?(Hash) or raise ParseError, "--variable-override-json value must be a JSON object, got #{fragment.class}: #{json.inspect}"
+        overrides.deep_merge!(fragment)
+      end
+
+      private
+
+      def fragment_for(key, value)
+        if key.include?(".")
+          nest(path_segments(key), coerce(value))
+        else
+          { key => value } # legacy: literal key, raw string value
+        end
+      end
+
+      def path_segments(key)
+        segments = key.split(UNESCAPED_DOT, -1)
+        segments.none?(&:empty?) or
+          raise ParseError, "--variable-override key #{key.inspect} has an empty path segment (leading, trailing, or doubled '.')"
+        segments.map { |segment| segment.gsub("\\.", ".") }
+      end
+
+      def nest(segments, value)
+        segments.reverse.reduce(value) { |acc, segment| { segment => acc } }
+      end
+
+      def coerce(value)
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+    end
+  end
+end

data/lib/kubernetes_template_rendering/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KubernetesTemplateRendering
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kubernetes_template_rendering
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Octothorpe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -101,6 +101,7 @@ files:
 - lib/kubernetes_template_rendering/resource_set.rb
 - lib/kubernetes_template_rendering/template.rb
 - lib/kubernetes_template_rendering/template_directory_renderer.rb
+- lib/kubernetes_template_rendering/variable_override_parser.rb
 - lib/kubernetes_template_rendering/version.rb
 - mkdocs.yml
 - sig/kubernetes_template_rendering.rbs