nit documentation

pulumi/src/README.md

@@ -1,6 +1,6 @@
 # Kargo Modules Development Guide
 
-Welcome to the Kargo modules development guide! This document provides an overview of the design principles, code structure, and best practices for developing and maintaining modules within the Kargo codebase. It is intended for developers and AI language models (like ChatGPT) to quickly understand and contribute to the project.
+Welcome to the Kargo Kubevirt PaaS IaC module developer guide. This document provides an overview of the design principles, code structure, and best practices for developing and maintaining modules within the Kargo IaC codebase. It is intended for developers and AI language models (like ChatGPT) to quickly understand and contribute to the project.
 
 ## Table of Contents
 
@@ -21,7 +21,7 @@ Welcome to the Kargo modules development guide! This document provides an overvi
 
 ## Introduction
 
-Kargo is a Kubernetes deployment framework that leverages Pulumi for infrastructure as code (IaC). This guide aims to standardize module development by centralizing version handling, simplifying module code, and promoting consistency across the codebase.
+Kargo is a Kubernetes & Kubevirt based Platform Engineering IaC development & deployment framework that leverages Pulumi for infrastructure as code (IaC). This guide aims to standardize module development by centralizing version handling, simplifying module code, and promoting consistency across the codebase.
 
 ---
 
@@ -35,12 +35,15 @@ Kargo is a Kubernetes deployment framework that leverages Pulumi for infrastruct
 
 ---
 
-## Code Structure
+## IaC Module Structure
 
 - **`__main__.py`**: The entry point of the Pulumi program. Handles global configurations, Kubernetes provider setup, version loading, and module deployments.
 - **`src/lib/`**: Contains shared utilities and libraries, such as version management (`versions.py`) and shared types (`types.py`).
 - **`src/<module_name>/`**: Each module resides in its own directory under `src/`, containing its specific types (`types.py`) and deployment logic (`deploy.py`).
-- **`default_versions.json`**: A JSON file containing default versions for modules. Can be overridden by user configurations.
+- **`src/<module_name>/types.py`**: Defines data classes for module configurations with default values and merging logic.
+- **`src/<module_name>/deploy.py`**: Contains the module-specific deployment logic, taking in the merged configuration and returning relevant outputs.
+- **`src/<module_name>/README.md`**: Module-specific documentation with configuration options, features, and usage instructions.
+- **`src/<module_name>/*.py`**: Additional utility files or scripts specific to the module.
 
 ---
 

pulumi/src/cert_manager/README.md

@@ -1,8 +1,8 @@
-# Cert Manager Module for Kargo PaaS
+# Cert Manager Module
 
-Welcome to the Cert Manager module for the ContainerCraft Kargo PaaS platform! This module automates the deployment and management of certificates in your Kubernetes cluster using [cert-manager](https://cert-manager.io/). It simplifies the process of issuing and renewing SSL/TLS certificates, enhancing the security of your applications.
+ContainerCraft Kargo Kubevirt PaaS Cert Manager module.
 
-This guide provides an overview of the Cert Manager module, instructions on how to enable and configure it, and explanations of its functionality within the Kargo PaaS platform. Whether you're new to Kubernetes, cert-manager, or ContainerCraft Kargo PaaS, this guide will help you get started.
+The `cert_manager` module automates SSL certificates and certificate issuers in your platform using [cert-manager](https://cert-manager.io/). Cert Manager is a dependency of many components in Kargo Kubevirt PaaS including Containerized Data Importer, Kubevirt, Hostpath Provisioner, and more. Cert Manager improves the simplicity of issuing and renewing SSL/TLS certificates making PKI (Private Key Infrastructure) an integrated and automated feature of the platform.
 
 ---
 
@@ -29,32 +29,23 @@ This guide provides an overview of the Cert Manager module, instructions on how
 
 ## Introduction
 
-The Cert Manager module automates the installation and configuration of cert-manager in your Kubernetes cluster using Pulumi and the Kargo PaaS platform. By integrating cert-manager, you can easily manage SSL/TLS certificates for your applications, enabling secure communication and compliance with industry standards.
-
----
-
-## Prerequisites
-
-- **Kubernetes Cluster**: A running Kubernetes cluster accessible via `kubeconfig`.
-- **Pulumi Installed**: Ensure Pulumi is installed and configured.
-- **Kargo PaaS Setup**: Basic setup of the Kargo PaaS platform.
-- **Access to Helm Charts**: Ability to pull Helm charts from `https://charts.jetstack.io`.
+This guide provides an overview of the Cert Manager module, instructions on how to enable and configure it, and explanations of its functionality within the Kargo PaaS platform. Whether you're new to Kubernetes, cert-manager, or ContainerCraft Kargo PaaS, this guide will help you get started.
 
 ---
 
 ## Features
 
 - **Automated Deployment**: Installs cert-manager using Helm charts.
-- **Version Management**: Supports specific versions or defaults to the latest version.
+- **Version Management**: Supports explicit version pinning or accepts `latest`.
 - **Namespace Isolation**: Deploys cert-manager in a dedicated namespace.
 - **Self-Signed Certificates**: Sets up a self-signed ClusterIssuer for certificate management.
-- **Customizable Configuration**: Allows overriding default settings to fit your needs.
+- **Customizable Configuration**: Allows setting overrides for customization.
 
 ---
 
 ## Enabling the Module
 
-To enable the Cert Manager module, update your Pulumi configuration to include the `cert_manager` section with `enabled: true`.
+The Cert Manager module is enabled by default and executes with sane defaults. Customization can be configured in the Pulumi Stack Configuration.
 
 ### Example Pulumi Configuration
 
@@ -66,10 +57,10 @@ config:
     enabled: true # (default: true)
 ```
 
-Alternatively, you can set the configuration via the Pulumi CLI:
+Alternatively, you can set configuration values via the Pulumi CLI:
 
 ```bash
-pulumi config set --path cert_manager.enabled true
+pulumi config set --path cert_manager.key value
 ```
 
 ---
@@ -100,14 +91,15 @@ You can customize the module's behavior by providing additional configuration op
 
 ```yaml
 # Pulumi.<stack-name>.yaml
+# Default values are shown for reference
 
 config:
   cert_manager:
     enabled: true
     version: "1.15.3"
     cluster_issuer: "my-cluster-issuer"
     namespace: "custom-cert-manager"
-    install_crds: true # (default: true)
+    install_crds: true
 ```
 
 ---
@@ -125,69 +117,40 @@ The module creates a dedicated namespace for cert-manager to ensure isolation an
 
 The module deploys cert-manager using the official Helm chart from Jetstack.
 
-- **Repository**: `https://charts.jetstack.io`
 - **Chart Name**: `cert-manager`
-- **Version**: Configurable; defaults to the version specified in `default_versions.json`.
+- **Repository**: `https://charts.jetstack.io`
 - **Custom Values**: Resources and replica counts are configured for optimal performance.
+- **Version**: Configurable; defaults to the version specified in `default_versions.json`.
 
 ### Self-Signed Cluster Issuer
 
-To enable certificate issuance, the module sets up a self-signed ClusterIssuer.
+To enable self signed local certificates, the module includes a self-signed ClusterIssuer chain of trust.
 
 - **Root ClusterIssuer**: `cluster-selfsigned-issuer-root`
 - **CA Certificate**: Generated and stored in a Kubernetes Secret.
 - **Primary ClusterIssuer**: Uses the CA certificate to issue certificates for your applications.
 - **Secret Export**: The CA certificate data is exported and available for other modules or applications.
 
----
-
-## Integration with Kargo PaaS
-
-The Cert Manager module integrates seamlessly with the Kargo PaaS platform, leveraging shared configurations and best practices.
-
-- **Version Handling**: Uses centralized version management from `src/lib/versions.py`.
-- **Configuration Merging**: Combines user-provided configurations with defaults for consistency.
-- **Resource Dependencies**: Manages dependencies between resources to ensure correct deployment order.
-- **Exported Outputs**: Provides necessary outputs for other modules or services to consume.
-
----
-
-## Best Practices
-
-- **Version Specification**: While the module can use the latest version, specifying a version ensures consistency across deployments.
-- **CRD Management**: Set `install_crds` to `true` unless CRDs are managed externally.
-- **ClusterIssuer Naming**: Use meaningful names for ClusterIssuers to avoid conflicts.
-- **Resource Monitoring**: Keep an eye on resource usage, especially if adjusting the default resource requests and limits.
-
----
-
 ## Troubleshooting
 
 ### Common Issues
 
 - **Connection Errors**: Ensure your `kubeconfig` and Kubernetes context are correctly configured.
-- **Version Conflicts**: If deployment fails due to version issues, verify the specified version is available in the Helm repository.
-- **CRD Issues**: If CRDs are not installed, cert-manager components may fail to function properly.
+- **Version Conflicts**: If deployment fails due to version issues, verify the specified version is available in the Helm repository. Alternatively use `'latest'` and Kargo will fetch the latest version.
+- **CRD Issues**: If `install_crds` is set to false and are not otherwise installed, cert-manager components may fail install or function properly.
 
 ### Debugging Steps
 
 1. **Check Pulumi Logs**: Look for error messages during deployment.
 2. **Verify Kubernetes Resources**: Use `kubectl` to inspect the cert-manager namespace and resources.
-3. **Review Configuration**: Ensure all configuration options are correctly set in your Pulumi config.
+3. **Review Configuration**: Ensure all configuration options are correctly set in your Pulumi config or remove configuration to use defaults.
 
 ---
 
 ## Additional Resources
 
 - **cert-manager Documentation**: [https://cert-manager.io/docs/](https://cert-manager.io/docs/)
-- **Kargo PaaS Documentation**: Refer to the main [Kargo README](../README.md) for developer guidelines.
+- **Kargo Kubevirt PaaS IaC Documentation**: Refer to the main [Kargo README](../README.md) for developer guidelines.
 - **Pulumi Kubernetes Provider**: [https://www.pulumi.com/docs/reference/pkg/kubernetes/](https://www.pulumi.com/docs/reference/pkg/kubernetes/)
 - **Helm Charts**: [https://artifacthub.io/packages/helm/cert-manager/cert-manager](https://artifacthub.io/packages/helm/cert-manager/cert-manager)
-
----
-
-## Conclusion
-
-The Cert Manager module simplifies the integration of cert-manager into your Kubernetes cluster within the Kargo PaaS platform. By following this guide, you can easily enable and configure the module to enhance the security and reliability of your applications.
-
-**Need Help?** If you have questions or need assistance, feel free to reach out to the community or maintainers.
+- **Need Help?** If you have questions or need assistance, feel free to reach out to the community or maintainers on GitHub, Discord, or Twitter.