merge-helm-values 1.0.0__tar.gz

merge_helm_values-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ergon-public
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

merge_helm_values-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: merge-helm-values
+Version: 1.0.0
+Summary: Load, decrypt (ansible-vault), and deep-merge Helm value YAML files.
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: ansible-vault
+Requires-Dist: mergedeep
+Requires-Dist: oyaml
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

merge_helm_values-1.0.0/README.md

@@ -0,0 +1,150 @@
+# merge-helm-values
+
+Managing Helm values across multiple environments (development, integration, production) quickly becomes error-prone. Configuration is scattered, secrets end up duplicated or stored insecurely, and there is no single source of truth for what a deployment actually receives.
+
+**merge-helm-values** solves this by giving you:
+
+- **A structured, multi-environment value layout** — split configuration by concern (database, cache, frontend, ...) and by environment, with shared defaults that reduce duplication
+- **Inline secret encryption** — sensitive values are encrypted with [ansible-vault](https://docs.ansible.com/ansible/latest/vault_guide/index.html) directly inside your YAML files, right next to the configuration they belong to. No separate secret files, no manual decryption steps
+- **Deterministic deep merge** — folders and files are merged in a well-defined order (lexicographic within folders, folders left to right), producing a single, predictable values file for `helm upgrade`
+
+The result is a reliable, auditable, and version-controllable source for all your Helm values — plain and secret — across all environments.
+
+## Installation
+
+```bash
+pip install merge-helm-values
+```
+
+## How it works
+
+1. Point the library at one or more folders containing YAML files
+2. Files are loaded in **lexicographic order** within each folder, folders are processed in the order given
+3. Values tagged with `!vault` are **decrypted inline** during YAML parsing
+4. All loaded dictionaries are **deep-merged** — later values override earlier ones
+
+## Encrypting values
+
+Use `ansible-vault encrypt_string` to create inline encrypted values:
+
+```bash
+# Encrypt a simple value
+echo -n "my-secret-password" | ansible-vault encrypt_string --stdin-name password
+
+# Output (paste this into your YAML file):
+# password: !vault |
+#   $ANSIBLE_VAULT;1.1;AES256
+#   6163326163...
+```
+
+The `!vault` tag tells the loader to decrypt the value during parsing. Untagged values pass through unchanged.
+
+## Value file structure
+
+Organize your Helm values into folders by concern — common defaults, environment-specific overrides, and secrets:
+
+```
+values/
+├── common/                   # shared defaults (loaded first)
+│   ├── backend.yaml
+│   ├── database.yaml
+│   └── frontend.yaml
+├── development/              # env overrides + secrets
+│   ├── backend.yaml
+│   ├── database_vault.yaml   # contains !vault encrypted values
+│   └── frontend.yaml
+└── production/
+    ├── backend.yaml
+    ├── database_vault.yaml
+    └── frontend.yaml
+```
+
+Files are sorted lexicographically within each folder. A common convention is to suffix files containing secrets with `_vault`.
+
+## Inline vault example
+
+A file mixing plain and encrypted values:
+
+```yaml
+backend:
+  database:
+    host: "db.prod.example.com"
+    port: 5432
+    username: myapp
+    password: !vault |
+      $ANSIBLE_VAULT;1.1;AES256
+      6163326163613032373733...
+  cache:
+    host: "redis.prod.internal"
+    password: !vault |
+      $ANSIBLE_VAULT;1.1;AES256
+      3430613966353766366538...
+```
+
+After decryption and merge, this produces a flat dictionary with all secrets resolved to their plaintext values.
+
+## Python API
+
+### `make_vault_loader(passphrase)`
+
+Creates a YAML loader that decrypts `!vault` tagged values inline.
+
+```python
+import oyaml as yaml
+from merge_helm_values import make_vault_loader
+
+loader = make_vault_loader("my-vault-passphrase")
+with open("values.yaml") as f:
+    data = yaml.load(f, Loader=loader)
+```
+
+### `merge_value_folders(passphrase, folders)`
+
+Loads and deep-merges all YAML/YML files from the given folders. Files within each folder are sorted lexicographically. Folders are processed in order — later folders override earlier ones.
+
+```python
+from merge_helm_values import merge_value_folders
+
+merged = merge_value_folders("my-vault-passphrase", [
+    "values/common",
+    "values/production",
+])
+```
+
+## CLI wrapper example
+
+The library provides the building blocks. You write a thin CLI wrapper that handles passphrase resolution for your setup:
+
+```python
+#!/usr/bin/env python3
+import os
+import sys
+import oyaml as yaml
+from merge_helm_values import merge_value_folders
+
+passphrase = os.environ.get("ANSIBLE_VAULT_PASSWORD")
+if not passphrase:
+    # resolve from your secret manager, e.g. 1Password, AWS SSM, etc.
+    raise SystemExit("Set ANSIBLE_VAULT_PASSWORD")
+
+merged = merge_value_folders(passphrase, sys.argv[1:])
+print(yaml.dump(merged))
+```
+
+Use it in your deploy script:
+
+```bash
+merge-values.py values/common/ values/$ENVIRONMENT/ > merged.yaml
+helm upgrade --install myapp ./chart --values merged.yaml
+```
+
+## Merge behavior
+
+- **Deep merge**: nested dictionaries are merged recursively, not replaced
+- **Lexicographic order**: within a folder, `a.yaml` is loaded before `b.yaml`
+- **Folder order**: folders are processed left to right — the last folder wins on conflicts
+- **File extensions**: only `.yaml` and `.yml` files are loaded, everything else is ignored
+
+## License
+
+MIT

merge_helm_values-1.0.0/merge_helm_values.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: merge-helm-values
+Version: 1.0.0
+Summary: Load, decrypt (ansible-vault), and deep-merge Helm value YAML files.
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: ansible-vault
+Requires-Dist: mergedeep
+Requires-Dist: oyaml
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

merge_helm_values-1.0.0/merge_helm_values.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+merge_helm_values.py
+pyproject.toml
+merge_helm_values.egg-info/PKG-INFO
+merge_helm_values.egg-info/SOURCES.txt
+merge_helm_values.egg-info/dependency_links.txt
+merge_helm_values.egg-info/requires.txt
+merge_helm_values.egg-info/top_level.txt
+tests/test_merge_helm_values.py

merge_helm_values-1.0.0/merge_helm_values.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

merge_helm_values-1.0.0/merge_helm_values.egg-info/requires.txt

@@ -0,0 +1,6 @@
+ansible-vault
+mergedeep
+oyaml
+
+[test]
+pytest

merge_helm_values-1.0.0/merge_helm_values.egg-info/top_level.txt

@@ -0,0 +1 @@
+merge_helm_values

merge_helm_values-1.0.0/merge_helm_values.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# Read and merge all values to a single value structure.
+# Values tagged with !vault are decrypted inline using ansible-vault.
+# Please note, the files in the folders are sorted lexicographically
+# and are processed in this order.
+
+import os.path
+from os import listdir
+from ansible_vault import Vault
+import oyaml as yaml
+from mergedeep import merge
+
+
+def make_vault_loader(passphrase):
+    """Create a YAML loader that decrypts !vault tagged values inline."""
+    loader = type('VaultLoader', (yaml.SafeLoader,), {})
+
+    def vault_constructor(loader, node):
+        encrypted = loader.construct_scalar(node)
+        if not encrypted.startswith("$ANSIBLE_VAULT"):
+            encrypted = "$ANSIBLE_VAULT;1.1;AES256\n" + encrypted
+        vault = Vault(passphrase)
+        return vault.load_raw(encrypted.encode()).decode("utf-8")
+
+    loader.add_constructor('!vault', vault_constructor)
+    return loader
+
+
+def merge_value_folders(passphrase, value_folders):
+    """Load and deep-merge all YAML files from the given folders (lexicographic order)."""
+    vault_loader = make_vault_loader(passphrase)
+
+    value_dics = []
+    for value_folder in value_folders:
+        for file in sorted(listdir(value_folder)):
+            if not (file.endswith(".yml") or file.endswith(".yaml")):
+                continue
+
+            values_path = os.path.join(value_folder, file)
+            with open(values_path) as fh:
+                content = yaml.load(fh, Loader=vault_loader)
+            value_dics.append(content)
+
+    return merge(*value_dics)

merge_helm_values-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "merge-helm-values"
+version = "1.0.0"
+description = "Load, decrypt (ansible-vault), and deep-merge Helm value YAML files."
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "ansible-vault",
+    "mergedeep",
+    "oyaml",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools]
+py-modules = ["merge_helm_values"]

merge_helm_values-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

merge_helm_values-1.0.0/tests/test_merge_helm_values.py

@@ -0,0 +1,164 @@
+import os
+import textwrap
+import pytest
+from ansible_vault import Vault
+import oyaml as yaml
+from mergedeep import merge
+
+from merge_helm_values import make_vault_loader, merge_value_folders
+
+
+VAULT_PASSPHRASE = "test-passphrase-for-unit-tests"
+FIXTURES_DIR = os.path.join(os.path.dirname(__file__), "fixtures")
+ENCRYPTION_FIXTURES = os.path.join(FIXTURES_DIR, "encryption")
+MERGE_FIXTURES = os.path.join(FIXTURES_DIR, "merge")
+
+
+def encrypt_full(value: str) -> str:
+    """Encrypt a string and return the full vault blob including header."""
+    vault = Vault(VAULT_PASSPHRASE)
+    encrypted = vault.dump_raw(value.encode())
+    if isinstance(encrypted, bytes):
+        encrypted = encrypted.decode("utf-8")
+    return encrypted.strip()
+
+
+def encrypt_no_header(value: str) -> str:
+    """Encrypt a string and return the ciphertext without the header line."""
+    full = encrypt_full(value)
+    lines = full.splitlines()
+    assert lines[0].startswith("$ANSIBLE_VAULT")
+    return "\n".join(lines[1:])
+
+
+def indent_vault_block(ciphertext: str, spaces: int) -> str:
+    """Indent every line of a vault ciphertext block for YAML literal scalar embedding."""
+    prefix = " " * spaces
+    return "\n".join(prefix + line for line in ciphertext.splitlines())
+
+
+def load_yaml(text: str, passphrase: str = VAULT_PASSPHRASE) -> dict:
+    loader = make_vault_loader(passphrase)
+    return yaml.load(text, Loader=loader)
+
+
+class TestInlineVaultDecryption:
+    def test_single_inline_vault_value(self):
+        secret = "super-secret-key"
+        vault_block = indent_vault_block(encrypt_full(secret), 4)
+        doc = (
+            "backend:\n"
+            "  accessKey: !vault |\n"
+            f"{vault_block}\n"
+            "  bucket: plain-value\n"
+        )
+        result = load_yaml(doc)
+        assert result["backend"]["accessKey"] == secret
+        assert result["backend"]["bucket"] == "plain-value"
+
+    def test_multiple_inline_vault_values(self):
+        access = "my-access-key"
+        secret = "my-secret-key"
+        access_block = indent_vault_block(encrypt_full(access), 4)
+        secret_block = indent_vault_block(encrypt_full(secret), 4)
+        doc = (
+            "s3:\n"
+            "  accessKey: !vault |\n"
+            f"{access_block}\n"
+            "  secretKey: !vault |\n"
+            f"{secret_block}\n"
+            '  endpoint: "https://minio.example.com/"\n'
+        )
+        result = load_yaml(doc)
+        assert result["s3"]["accessKey"] == access
+        assert result["s3"]["secretKey"] == secret
+        assert result["s3"]["endpoint"] == "https://minio.example.com/"
+
+    def test_vault_without_header_is_prepended(self):
+        secret = "no-header-secret"
+        vault_block = indent_vault_block(encrypt_no_header(secret), 2)
+        doc = (
+            "key: !vault |\n"
+            f"{vault_block}\n"
+        )
+        result = load_yaml(doc)
+        assert result["key"] == secret
+
+    def test_no_vault_tags_passes_through(self):
+        doc = textwrap.dedent("""\
+            plain:
+              nested: value
+              number: 42
+        """)
+        result = load_yaml(doc)
+        assert result == {"plain": {"nested": "value", "number": 42}}
+
+    def test_wrong_passphrase_raises(self):
+        vault_block = indent_vault_block(encrypt_full("secret"), 2)
+        doc = (
+            "key: !vault |\n"
+            f"{vault_block}\n"
+        )
+        wrong_loader = make_vault_loader("wrong-passphrase")
+        with pytest.raises(Exception):
+            yaml.load(doc, Loader=wrong_loader)
+
+
+class TestMergeWithFixtureFiles:
+    def test_deep_merge_plain_and_vault_files(self):
+        """Load fixture files from disk, merge them, and verify the result."""
+        plain_path = os.path.join(ENCRYPTION_FIXTURES, "plain_config.yaml")
+        vault_path = os.path.join(ENCRYPTION_FIXTURES, "vault_config.yaml")
+
+        plain_dict = yaml.safe_load(open(plain_path))
+
+        loader = make_vault_loader(VAULT_PASSPHRASE)
+        with open(vault_path) as fh:
+            vault_dict = yaml.load(fh, Loader=loader)
+
+        merged = merge(plain_dict, vault_dict)
+
+        assert merged["backend"]["storage"]["s3"]["endpoint"] == "https://minio.example.com/"
+        assert merged["backend"]["storage"]["s3"]["bucket"] == "my-app-dev"
+        assert merged["backend"]["storage"]["s3"]["region"] == "us-east-1"
+        assert merged["backend"]["storage"]["s3"]["accessKey"] == "SEMI_SECRET"
+        assert merged["backend"]["storage"]["s3"]["secretKey"] == "TOP_SECRET"
+
+    def test_vault_on_different_levels(self):
+        """Decrypt inline vault values at different nesting depths and compare to expected output."""
+        input_path = os.path.join(ENCRYPTION_FIXTURES, "on_different_levels_input.yaml")
+        expected_path = os.path.join(ENCRYPTION_FIXTURES, "on_different_levels_expected.yaml")
+
+        loader = make_vault_loader(VAULT_PASSPHRASE)
+        with open(input_path) as fh:
+            actual = yaml.load(fh, Loader=loader)
+
+        expected = yaml.safe_load(open(expected_path))
+
+        assert actual == expected
+
+
+class TestMergeMultipleFiles:
+    def test_lexicographic_deep_merge(self):
+        """Merge multiple input files lexicographically and compare to expected output."""
+        input_dir = os.path.join(MERGE_FIXTURES, "test1", "input")
+        expected_path = os.path.join(MERGE_FIXTURES, "test1", "expected.yml")
+
+        actual = merge_value_folders(VAULT_PASSPHRASE, [input_dir])
+        expected = yaml.safe_load(open(expected_path))
+
+        assert actual == expected
+
+    def test_three_layer_merge_common_env_secrets(self):
+        """Simulate real deploy: common/ + environment/ + secrets/ folders merged in order."""
+        base = os.path.join(MERGE_FIXTURES, "test2", "input")
+        expected_path = os.path.join(MERGE_FIXTURES, "test2", "expected.yaml")
+
+        actual = merge_value_folders(VAULT_PASSPHRASE, [
+            os.path.join(base, "common"),
+            os.path.join(base, "environment"),
+            os.path.join(base, "secrets"),
+        ])
+        expected = yaml.safe_load(open(expected_path))
+
+        assert actual == expected