feat: Add kustomize module for kubectl kustomize operations (#209)

* chore: add flake + fmt

Signed-off-by: Mohammed Naser <[email protected]>

* Add kustomize module for kubectl kustomize operations

This commit introduces a new `kustomize` module that provides a clean,
idempotent interface for running `kubectl kustomize` operations.

Key features:
- Runs kubectl kustomize against a source directory
- Saves output to a destination file
- Proper change detection using SHA256 checksums via Ansible's built-in
  module.sha256() method
- Check mode (dry-run) support
- Atomic file operations using module.atomic_move()
- Clean temporary file handling with context managers

Refactored the openstack_resource_controller role to use this new module
instead of shell commands, improving idempotency and maintainability.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
Signed-off-by: Mohammed Naser <[email protected]>

---------

Signed-off-by: Mohammed Naser <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: mnaser

.envrc

@@ -0,0 +1 @@
+use flake

.gitignore

@@ -1,3 +1,4 @@
 .ansible
+.direnv
 __pycache__
 tests/output

flake.lock

@@ -0,0 +1,58 @@
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+
+    treefmt-nix = {
+      url = "github:numtide/treefmt-nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    devshell = {
+      url = "github:numtide/devshell";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.treefmt-nix.flakeModule
+        inputs.devshell.flakeModule
+      ];
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "aarch64-darwin"
+        "x86_64-darwin"
+      ];
+      perSystem =
+        {
+          config,
+          self',
+          inputs',
+          pkgs,
+          system,
+          ...
+        }:
+        {
+          treefmt = {
+            programs = {
+              black.enable = true;
+              nixfmt.enable = true;
+            };
+          };
+
+          devshells.default = {
+            packages =
+              with pkgs;
+              [
+                python3Packages.flake8
+              ]
+              ++ (builtins.attrValues config.treefmt.build.programs);
+          };
+        };
+    };
+}

flake.nix

@@ -0,0 +1,119 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2025 VEXXHOST, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+import os
+import tempfile
+
+from ansible.module_utils.basic import AnsibleModule
+
+DOCUMENTATION = r"""
+---
+module: kustomize
+short_description: Run kubectl kustomize and save output to a file
+description:
+  - Generates Kubernetes manifests using kubectl kustomize from a kustomization directory
+  - Saves the output to a destination file
+  - Supports check mode (dry-run)
+  - Properly detects changes based on content checksum
+version_added: "2.5.0"
+options:
+  src:
+    description:
+      - Path to the kustomization directory
+    required: true
+    type: path
+  dest:
+    description:
+      - Path where the generated manifests should be saved
+    required: true
+    type: path
+  kubectl_path:
+    description:
+      - Path to the kubectl binary
+    type: path
+    default: kubectl
+author:
+  - Mohammed Naser <[email protected]>
+"""
+
+EXAMPLES = r"""
+- name: Generate manifests using kubectl kustomize
+  vexxhost.kubernetes.kustomize:
+    src: /path/to/kustomization
+    dest: /path/to/manifests.yaml
+
+- name: Generate manifests with custom kubectl path
+  vexxhost.kubernetes.kustomize:
+    src: /path/to/kustomization
+    dest: /path/to/manifests.yaml
+    kubectl_path: /usr/local/bin/kubectl
+"""
+
+RETURN = r"""
+changed:
+  description: Whether the destination file was changed
+  returned: always
+  type: bool
+  sample: true
+dest:
+  description: Path to the destination file
+  returned: always
+  type: str
+  sample: /path/to/manifests.yaml
+checksum:
+  description: SHA256 checksum of the generated content
+  returned: always
+  type: str
+  sample: 2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
+"""
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            src=dict(type="path", required=True),
+            dest=dict(type="path", required=True),
+            kubectl_path=dict(type="path", default="kubectl"),
+        ),
+        supports_check_mode=True,
+    )
+
+    _, stdout, _ = module.run_command(
+        [module.params["kubectl_path"], "kustomize", module.params["src"]],
+        check_rc=True,
+    )
+
+    dest = module.params["dest"]
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        dir=os.path.dirname(dest) or None,
+    ) as temp_file:
+        temp_file.write(stdout)
+        temp_file.flush()
+
+        new_checksum = module.sha256(temp_file.name)
+        old_checksum = module.sha256(dest) if os.path.exists(dest) else None
+
+        changed = old_checksum != new_checksum
+
+        result = {
+            "changed": changed,
+            "dest": dest,
+            "checksum": new_checksum,
+        }
+
+        if changed and not module.check_mode:
+            module.atomic_move(temp_file.name, dest)
+
+        module.exit_json(**result)
+
+
+if __name__ == "__main__":
+    main()

plugins/modules/kustomize.py

@@ -18,10 +18,9 @@
     group: root
 
 - name: Generate manifests
-  ansible.builtin.shell:
-    cmd: "kubectl kustomize {{ openstack_resource_controller_build_directory }} > {{ openstack_resource_controller_build_file }}"
-    chdir: "{{ openstack_resource_controller_build_directory }}"
-    creates: "{{ openstack_resource_controller_build_file }}"
+  vexxhost.kubernetes.kustomize:
+    src: "{{ openstack_resource_controller_build_directory }}"
+    dest: "{{ openstack_resource_controller_build_file }}"
 
 - name: Apply manifest to cluster
   kubernetes.core.k8s: