kubernetes_template_rendering 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c71eb502c7b52355ee6d9040a8401a6e7937477b4ffc81b725951187340e325
-  data.tar.gz: 07e31b80f5c7c2e0d95860d10a4a73390dd919eeed86000867e151faad9f7113
+  metadata.gz: 2834614aaa2465ab9be3a1c50b6c2d2a1b1f4264ecadafddcb5bf8365c5bb151
+  data.tar.gz: 6142bd0df1d9da48f1058409017f2080082deb81d13b4c02b4dce2bef2ed80ef
 SHA512:
-  metadata.gz: 3113be1c65d2e3f356e82b0b3388f9a090fab3945dcc9c54720146f12f9f95d8c95e7dd7fae7af0c00687aa6e557cf84c7fc6de5754f16c7e831fe101b283770
-  data.tar.gz: 64b29afd0de7680e0a8c4aa57010268bc3e1e0bb6ec502c11d91e1ac518d633371d8b1b8f7fa368cb71b73f5e89754e42fecc36cbdd56e698077064269316e0a
+  metadata.gz: bd84f186eda857691bb2825188bcabb8dfc8af8e9c9054623263d72db981d3bba853177f31fd63de4a57f6b982ead442724515a54cc2c42b0454c41c0a9aff6f
+  data.tar.gz: 8aa7fac766cd4f19e6994a1a51a68bbaf09db56384ae979d403ee4f795a6d7d78a0d9fc4211330d620253033a730306a7eb3d0541995a6436ecfe150a720320e

data/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.

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/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/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.2"
+  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.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Octothorpe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-15 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