562 lines
29 KiB
HTML
562 lines
29 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
|
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<!-- Book generated using mdBook -->
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<title>KCL Module Organization Summary - Provisioning Platform Documentation</title>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Custom HTML head -->
|
|||
|
|
|
|||
|
|
<meta name="description" content="Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust">
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|||
|
|
<meta name="theme-color" content="#ffffff">
|
|||
|
|
|
|||
|
|
<link rel="icon" href="../../favicon.svg">
|
|||
|
|
<link rel="shortcut icon" href="../../favicon.png">
|
|||
|
|
<link rel="stylesheet" href="../../css/variables.css">
|
|||
|
|
<link rel="stylesheet" href="../../css/general.css">
|
|||
|
|
<link rel="stylesheet" href="../../css/chrome.css">
|
|||
|
|
<link rel="stylesheet" href="../../css/print.css" media="print">
|
|||
|
|
|
|||
|
|
<!-- Fonts -->
|
|||
|
|
<link rel="stylesheet" href="../../FontAwesome/css/font-awesome.css">
|
|||
|
|
<link rel="stylesheet" href="../../fonts/fonts.css">
|
|||
|
|
|
|||
|
|
<!-- Highlight.js Stylesheets -->
|
|||
|
|
<link rel="stylesheet" id="highlight-css" href="../../highlight.css">
|
|||
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../../tomorrow-night.css">
|
|||
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../../ayu-highlight.css">
|
|||
|
|
|
|||
|
|
<!-- Custom theme stylesheets -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Provide site root and default themes to javascript -->
|
|||
|
|
<script>
|
|||
|
|
const path_to_root = "../../";
|
|||
|
|
const default_light_theme = "ayu";
|
|||
|
|
const default_dark_theme = "navy";
|
|||
|
|
</script>
|
|||
|
|
<!-- Start loading toc.js asap -->
|
|||
|
|
<script src="../../toc.js"></script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div id="mdbook-help-container">
|
|||
|
|
<div id="mdbook-help-popup">
|
|||
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|||
|
|
<div>
|
|||
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|||
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|||
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|||
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div id="body-container">
|
|||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|||
|
|
<script>
|
|||
|
|
try {
|
|||
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|||
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|||
|
|
|
|||
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|||
|
|
}
|
|||
|
|
} catch (e) { }
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|||
|
|
<script>
|
|||
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|||
|
|
let theme;
|
|||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|||
|
|
const html = document.documentElement;
|
|||
|
|
html.classList.remove('ayu')
|
|||
|
|
html.classList.add(theme);
|
|||
|
|
html.classList.add("js");
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|||
|
|
|
|||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|||
|
|
<script>
|
|||
|
|
let sidebar = null;
|
|||
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|||
|
|
if (document.body.clientWidth >= 1080) {
|
|||
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|||
|
|
sidebar = sidebar || 'visible';
|
|||
|
|
} else {
|
|||
|
|
sidebar = 'hidden';
|
|||
|
|
}
|
|||
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|||
|
|
html.classList.remove('sidebar-visible');
|
|||
|
|
html.classList.add("sidebar-" + sidebar);
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|||
|
|
<!-- populated by js -->
|
|||
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|||
|
|
<noscript>
|
|||
|
|
<iframe class="sidebar-iframe-outer" src="../../toc.html"></iframe>
|
|||
|
|
</noscript>
|
|||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|||
|
|
<div class="sidebar-resize-indicator"></div>
|
|||
|
|
</div>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
<div id="page-wrapper" class="page-wrapper">
|
|||
|
|
|
|||
|
|
<div class="page">
|
|||
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|||
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|||
|
|
<div class="left-buttons">
|
|||
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|||
|
|
<i class="fa fa-bars"></i>
|
|||
|
|
</label>
|
|||
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|||
|
|
<i class="fa fa-paint-brush"></i>
|
|||
|
|
</button>
|
|||
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|||
|
|
</ul>
|
|||
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|||
|
|
<i class="fa fa-search"></i>
|
|||
|
|
</button>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h1 class="menu-title">Provisioning Platform Documentation</h1>
|
|||
|
|
|
|||
|
|
<div class="right-buttons">
|
|||
|
|
<a href="../../print.html" title="Print this book" aria-label="Print this book">
|
|||
|
|
<i id="print-button" class="fa fa-print"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/provisioning/provisioning-platform" title="Git repository" aria-label="Git repository">
|
|||
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/development/kcl/KCL_MODULE_ORGANIZATION_SUMMARY.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|||
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div id="search-wrapper" class="hidden">
|
|||
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|||
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|||
|
|
</form>
|
|||
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|||
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|||
|
|
<ul id="searchresults">
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|||
|
|
<script>
|
|||
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|||
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|||
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|||
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|||
|
|
});
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<div id="content" class="content">
|
|||
|
|
<main>
|
|||
|
|
<h1 id="kcl-module-organization---implementation-summary"><a class="header" href="#kcl-module-organization---implementation-summary">KCL Module Organization - Implementation Summary</a></h1>
|
|||
|
|
<p><strong>Date</strong>: 2025-10-03
|
|||
|
|
<strong>Status</strong>: ✅ Complete
|
|||
|
|
<strong>KCL Version</strong>: 0.11.3</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="executive-summary"><a class="header" href="#executive-summary">Executive Summary</a></h2>
|
|||
|
|
<p>Successfully resolved KCL ImmutableError issues and established a clean, maintainable module organization pattern for the provisioning project. The root cause was re-export assignments in <code>main.k</code> that created immutable variables, causing E1001 errors when extensions imported schemas.</p>
|
|||
|
|
<p><strong>Solution</strong>: Direct submodule imports (no re-exports) - already implemented by the codebase, just needed cleanup and documentation.</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="problem-analysis"><a class="header" href="#problem-analysis">Problem Analysis</a></h2>
|
|||
|
|
<h3 id="root-cause"><a class="header" href="#root-cause">Root Cause</a></h3>
|
|||
|
|
<p>The original <code>main.k</code> contained 100+ lines of re-export assignments:</p>
|
|||
|
|
<pre><code class="language-kcl"># This pattern caused ImmutableError
|
|||
|
|
Settings = settings.Settings
|
|||
|
|
Server = server.Server
|
|||
|
|
TaskServDef = lib.TaskServDef
|
|||
|
|
# ... 100+ more
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Why it failed:</strong></p>
|
|||
|
|
<ol>
|
|||
|
|
<li>These assignments create <strong>immutable top-level variables</strong> in KCL</li>
|
|||
|
|
<li>When extensions import from <code>provisioning</code>, KCL attempts to re-assign these variables</li>
|
|||
|
|
<li>KCL’s immutability rules prevent this → ImmutableError E1001</li>
|
|||
|
|
<li>KCL 0.11.3 doesn’t support Python-style namespace re-exports</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="discovery"><a class="header" href="#discovery">Discovery</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>Extensions were <strong>already using direct imports</strong> correctly: <code>import provisioning.lib as lib</code></li>
|
|||
|
|
<li>Commenting out re-exports in <code>main.k</code> immediately fixed all errors</li>
|
|||
|
|
<li><code>kcl run provision_aws.k</code> worked perfectly with cleaned-up <code>main.k</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="solution-implemented"><a class="header" href="#solution-implemented">Solution Implemented</a></h2>
|
|||
|
|
<h3 id="1-cleaned-up-provisioningkclmaink"><a class="header" href="#1-cleaned-up-provisioningkclmaink">1. Cleaned Up <code>provisioning/kcl/main.k</code></a></h3>
|
|||
|
|
<p><strong>Before</strong> (110 lines):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>100+ lines of re-export assignments (commented out)</li>
|
|||
|
|
<li>Cluttered with non-functional code</li>
|
|||
|
|
<li>Misleading documentation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>After</strong> (54 lines):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Only import statements (no re-exports)</li>
|
|||
|
|
<li>Clear documentation explaining the pattern</li>
|
|||
|
|
<li>Examples of correct usage</li>
|
|||
|
|
<li>Anti-pattern warnings</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Key Changes</strong>:</p>
|
|||
|
|
<pre><code class="language-kcl"># BEFORE (❌ Caused ImmutableError)
|
|||
|
|
Settings = settings.Settings
|
|||
|
|
Server = server.Server
|
|||
|
|
# ... 100+ more
|
|||
|
|
|
|||
|
|
# AFTER (✅ Works correctly)
|
|||
|
|
import .settings
|
|||
|
|
import .defaults
|
|||
|
|
import .lib
|
|||
|
|
import .server
|
|||
|
|
# ... just imports
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="2-created-comprehensive-documentation"><a class="header" href="#2-created-comprehensive-documentation">2. Created Comprehensive Documentation</a></h3>
|
|||
|
|
<p><strong>File</strong>: <code>docs/architecture/kcl-import-patterns.md</code></p>
|
|||
|
|
<p><strong>Contents</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Module architecture overview</li>
|
|||
|
|
<li>Correct import patterns with examples</li>
|
|||
|
|
<li>Anti-patterns with explanations</li>
|
|||
|
|
<li>Submodule reference (all 10 submodules documented)</li>
|
|||
|
|
<li>Workspace integration guide</li>
|
|||
|
|
<li>Best practices</li>
|
|||
|
|
<li>Troubleshooting section</li>
|
|||
|
|
<li>Version compatibility matrix</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="architecture-pattern-direct-submodule-imports"><a class="header" href="#architecture-pattern-direct-submodule-imports">Architecture Pattern: Direct Submodule Imports</a></h2>
|
|||
|
|
<h3 id="how-it-works"><a class="header" href="#how-it-works">How It Works</a></h3>
|
|||
|
|
<p><strong>Core Module</strong> (<code>provisioning/kcl/main.k</code>):</p>
|
|||
|
|
<pre><code class="language-kcl"># Import submodules to make them discoverable
|
|||
|
|
import .settings
|
|||
|
|
import .lib
|
|||
|
|
import .server
|
|||
|
|
import .dependencies
|
|||
|
|
# ... etc
|
|||
|
|
|
|||
|
|
# NO re-exports - just imports
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Extensions Import Specific Submodules</strong>:</p>
|
|||
|
|
<pre><code class="language-kcl"># Provider example
|
|||
|
|
import provisioning.lib as lib
|
|||
|
|
import provisioning.defaults as defaults
|
|||
|
|
|
|||
|
|
schema Storage_aws(lib.Storage):
|
|||
|
|
voltype: "gp2" | "gp3" = "gp2"
|
|||
|
|
</code></pre>
|
|||
|
|
<pre><code class="language-kcl"># Taskserv example
|
|||
|
|
import provisioning.dependencies as schema
|
|||
|
|
|
|||
|
|
_deps = schema.TaskservDependencies {
|
|||
|
|
name = "kubernetes"
|
|||
|
|
requires = ["containerd"]
|
|||
|
|
}
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="why-this-works"><a class="header" href="#why-this-works">Why This Works</a></h3>
|
|||
|
|
<p>✅ <strong>No ImmutableError</strong> - No variable assignments in main.k
|
|||
|
|
✅ <strong>Explicit Dependencies</strong> - Clear what each extension needs
|
|||
|
|
✅ <strong>Works with <code>kcl run</code></strong> - Individual files can be executed
|
|||
|
|
✅ <strong>No Circular Imports</strong> - Clean dependency hierarchy
|
|||
|
|
✅ <strong>KCL-Idiomatic</strong> - Follows language design patterns
|
|||
|
|
✅ <strong>Better Performance</strong> - Only loads needed submodules
|
|||
|
|
✅ <strong>Already Implemented</strong> - Codebase was using this correctly!</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="validation-results"><a class="header" href="#validation-results">Validation Results</a></h2>
|
|||
|
|
<p>All schemas validate successfully after cleanup:</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>Test</th><th>Command</th><th>Result</th></tr></thead><tbody>
|
|||
|
|
<tr><td>Core module</td><td><code>kcl run provisioning/kcl/main.k</code></td><td>✅ Pass</td></tr>
|
|||
|
|
<tr><td>AWS provider</td><td><code>kcl run provisioning/extensions/providers/aws/kcl/provision_aws.k</code></td><td>✅ Pass</td></tr>
|
|||
|
|
<tr><td>Kubernetes taskserv</td><td><code>kcl run provisioning/extensions/taskservs/kubernetes/kcl/kubernetes.k</code></td><td>✅ Pass</td></tr>
|
|||
|
|
<tr><td>Web cluster</td><td><code>kcl run provisioning/extensions/clusters/web/kcl/web.k</code></td><td>✅ Pass</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<p><strong>Note</strong>: Minor type error in <code>version.k:105</code> (unrelated to import pattern) - can be fixed separately.</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="files-modified"><a class="header" href="#files-modified">Files Modified</a></h2>
|
|||
|
|
<h3 id="1-usersakashaproject-provisioningprovisioningkclmaink"><a class="header" href="#1-usersakashaproject-provisioningprovisioningkclmaink">1. <code>/Users/Akasha/project-provisioning/provisioning/kcl/main.k</code></a></h3>
|
|||
|
|
<p><strong>Changes</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Removed 82 lines of commented re-export assignments</li>
|
|||
|
|
<li>Added comprehensive documentation (42 lines)</li>
|
|||
|
|
<li>Kept only import statements (10 lines)</li>
|
|||
|
|
<li>Added usage examples and anti-pattern warnings</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Impact</strong>: Core module now clearly defines the import pattern</p>
|
|||
|
|
<h3 id="2-usersakashaproject-provisioningdocsarchitecturekcl-import-patternsmd"><a class="header" href="#2-usersakashaproject-provisioningdocsarchitecturekcl-import-patternsmd">2. <code>/Users/Akasha/project-provisioning/docs/architecture/kcl-import-patterns.md</code></a></h3>
|
|||
|
|
<p><strong>Created</strong>: Complete reference guide for KCL module organization</p>
|
|||
|
|
<p><strong>Sections</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Module Architecture (core + extensions structure)</li>
|
|||
|
|
<li>Import Patterns (correct usage, common patterns by type)</li>
|
|||
|
|
<li>Submodule Reference (all 10 submodules documented)</li>
|
|||
|
|
<li>Workspace Integration (how extensions are loaded)</li>
|
|||
|
|
<li>Best Practices (5 key practices)</li>
|
|||
|
|
<li>Troubleshooting (4 common issues with solutions)</li>
|
|||
|
|
<li>Version Compatibility (KCL 0.11.x support)</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Purpose</strong>: Single source of truth for extension developers</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="submodule-reference"><a class="header" href="#submodule-reference">Submodule Reference</a></h2>
|
|||
|
|
<p>The core provisioning module provides 10 submodules:</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>Submodule</th><th>Schemas</th><th>Purpose</th></tr></thead><tbody>
|
|||
|
|
<tr><td><code>provisioning.settings</code></td><td>Settings, SecretProvider, SopsConfig, KmsConfig, AIProvider</td><td>Core configuration</td></tr>
|
|||
|
|
<tr><td><code>provisioning.defaults</code></td><td>ServerDefaults</td><td>Base server defaults</td></tr>
|
|||
|
|
<tr><td><code>provisioning.lib</code></td><td>Storage, TaskServDef, ClusterDef, ScaleData</td><td>Core library types</td></tr>
|
|||
|
|
<tr><td><code>provisioning.server</code></td><td>Server</td><td>Server definitions</td></tr>
|
|||
|
|
<tr><td><code>provisioning.cluster</code></td><td>Cluster</td><td>Cluster management</td></tr>
|
|||
|
|
<tr><td><code>provisioning.dependencies</code></td><td>TaskservDependencies, HealthCheck, ResourceRequirement</td><td>Dependency management</td></tr>
|
|||
|
|
<tr><td><code>provisioning.workflows</code></td><td>BatchWorkflow, BatchOperation, RetryPolicy</td><td>Workflow definitions</td></tr>
|
|||
|
|
<tr><td><code>provisioning.batch</code></td><td>BatchScheduler, BatchExecutor, BatchMetrics</td><td>Batch operations</td></tr>
|
|||
|
|
<tr><td><code>provisioning.version</code></td><td>Version, TaskservVersion, PackageMetadata</td><td>Version tracking</td></tr>
|
|||
|
|
<tr><td><code>provisioning.k8s_deploy</code></td><td>K8s* (50+ K8s schemas)</td><td>Kubernetes deployments</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="best-practices-established"><a class="header" href="#best-practices-established">Best Practices Established</a></h2>
|
|||
|
|
<h3 id="1-direct-imports-only"><a class="header" href="#1-direct-imports-only">1. Direct Imports Only</a></h3>
|
|||
|
|
<pre><code class="language-kcl">✅ import provisioning.lib as lib
|
|||
|
|
❌ Settings = settings.Settings
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="2-meaningful-aliases"><a class="header" href="#2-meaningful-aliases">2. Meaningful Aliases</a></h3>
|
|||
|
|
<pre><code class="language-kcl">✅ import provisioning.dependencies as deps
|
|||
|
|
❌ import provisioning.dependencies as d
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="3-import-what-you-need"><a class="header" href="#3-import-what-you-need">3. Import What You Need</a></h3>
|
|||
|
|
<pre><code class="language-kcl">✅ import provisioning.version as v
|
|||
|
|
❌ import provisioning.* (not even possible in KCL)
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="4-group-related-imports"><a class="header" href="#4-group-related-imports">4. Group Related Imports</a></h3>
|
|||
|
|
<pre><code class="language-kcl"># Core schemas
|
|||
|
|
import provisioning.settings
|
|||
|
|
import provisioning.lib as lib
|
|||
|
|
|
|||
|
|
# Workflow schemas
|
|||
|
|
import provisioning.workflows as wf
|
|||
|
|
import provisioning.batch as batch
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="5-document-dependencies"><a class="header" href="#5-document-dependencies">5. Document Dependencies</a></h3>
|
|||
|
|
<pre><code class="language-kcl"># Dependencies:
|
|||
|
|
# - provisioning.dependencies
|
|||
|
|
# - provisioning.version
|
|||
|
|
import provisioning.dependencies as schema
|
|||
|
|
import provisioning.version as v
|
|||
|
|
</code></pre>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="workspace-integration"><a class="header" href="#workspace-integration">Workspace Integration</a></h2>
|
|||
|
|
<p>Extensions can be loaded into workspaces and used in infrastructure definitions:</p>
|
|||
|
|
<p><strong>Structure</strong>:</p>
|
|||
|
|
<pre><code>workspace-librecloud/
|
|||
|
|
├── .providers/ # Loaded providers (aws, upcloud, local)
|
|||
|
|
├── .taskservs/ # Loaded taskservs (kubernetes, containerd, etc.)
|
|||
|
|
└── infra/ # Infrastructure definitions
|
|||
|
|
└── production/
|
|||
|
|
├── kcl.mod
|
|||
|
|
└── servers.k
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-kcl"># workspace-librecloud/infra/production/servers.k
|
|||
|
|
import provisioning.server as server
|
|||
|
|
import provisioning.lib as lib
|
|||
|
|
import aws_prov.defaults_aws as aws
|
|||
|
|
|
|||
|
|
_servers = [
|
|||
|
|
server.Server {
|
|||
|
|
hostname = "k8s-master-01"
|
|||
|
|
defaults = aws.ServerDefaults_aws {
|
|||
|
|
zone = "eu-west-1"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
</code></pre>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="troubleshooting-guide"><a class="header" href="#troubleshooting-guide">Troubleshooting Guide</a></h2>
|
|||
|
|
<h3 id="immutableerror-e1001"><a class="header" href="#immutableerror-e1001">ImmutableError (E1001)</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Cause</strong>: Re-export assignments in modules</li>
|
|||
|
|
<li><strong>Solution</strong>: Use direct submodule imports</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="schema-not-found"><a class="header" href="#schema-not-found">Schema Not Found</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Cause</strong>: Importing from wrong submodule</li>
|
|||
|
|
<li><strong>Solution</strong>: Check submodule reference table</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="circular-import"><a class="header" href="#circular-import">Circular Import</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Cause</strong>: Module A imports B, B imports A</li>
|
|||
|
|
<li><strong>Solution</strong>: Extract shared schemas to separate module</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="version-mismatch"><a class="header" href="#version-mismatch">Version Mismatch</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Cause</strong>: Extension kcl.mod version conflict</li>
|
|||
|
|
<li><strong>Solution</strong>: Update kcl.mod to match core version</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="kcl-version-compatibility"><a class="header" href="#kcl-version-compatibility">KCL Version Compatibility</a></h2>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>Version</th><th>Status</th><th>Notes</th></tr></thead><tbody>
|
|||
|
|
<tr><td>0.11.3</td><td>✅ Current</td><td>Direct imports work perfectly</td></tr>
|
|||
|
|
<tr><td>0.11.x</td><td>✅ Supported</td><td>Same pattern applies</td></tr>
|
|||
|
|
<tr><td>0.10.x</td><td>⚠️ Limited</td><td>May have import issues</td></tr>
|
|||
|
|
<tr><td>Future</td><td>🔄 TBD</td><td>Namespace traversal planned (<a href="https://github.com/kcl-lang/kcl/issues/1686">#1686</a>)</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="impact-assessment"><a class="header" href="#impact-assessment">Impact Assessment</a></h2>
|
|||
|
|
<h3 id="immediate-benefits"><a class="header" href="#immediate-benefits">Immediate Benefits</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>✅ All ImmutableErrors resolved</li>
|
|||
|
|
<li>✅ Clear, documented import pattern</li>
|
|||
|
|
<li>✅ Cleaner, more maintainable codebase</li>
|
|||
|
|
<li>✅ Better onboarding for extension developers</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="long-term-benefits"><a class="header" href="#long-term-benefits">Long-term Benefits</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>✅ Scalable architecture (no central bottleneck)</li>
|
|||
|
|
<li>✅ Explicit dependencies (easier to track and update)</li>
|
|||
|
|
<li>✅ Better IDE support (submodule imports are clearer)</li>
|
|||
|
|
<li>✅ Future-proof (aligns with KCL evolution)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="performance-impact"><a class="header" href="#performance-impact">Performance Impact</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>⚡ Faster compilation (only loads needed submodules)</li>
|
|||
|
|
<li>⚡ Better caching (submodules cached independently)</li>
|
|||
|
|
<li>⚡ Reduced memory usage (no unnecessary schema loading)</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="next-steps-optional-improvements"><a class="header" href="#next-steps-optional-improvements">Next Steps (Optional Improvements)</a></h2>
|
|||
|
|
<h3 id="1-fix-minor-type-error"><a class="header" href="#1-fix-minor-type-error">1. Fix Minor Type Error</a></h3>
|
|||
|
|
<p><strong>File</strong>: <code>provisioning/kcl/version.k:105</code>
|
|||
|
|
<strong>Issue</strong>: Type mismatch in PackageMetadata
|
|||
|
|
<strong>Priority</strong>: Low (doesn’t affect imports)</p>
|
|||
|
|
<h3 id="2-add-import-examples-to-extension-templates"><a class="header" href="#2-add-import-examples-to-extension-templates">2. Add Import Examples to Extension Templates</a></h3>
|
|||
|
|
<p><strong>Location</strong>: Extension scaffolding tools
|
|||
|
|
<strong>Purpose</strong>: New extensions start with correct patterns
|
|||
|
|
<strong>Priority</strong>: Medium</p>
|
|||
|
|
<h3 id="3-create-ide-snippets"><a class="header" href="#3-create-ide-snippets">3. Create IDE Snippets</a></h3>
|
|||
|
|
<p><strong>Platforms</strong>: VS Code, Vim, Emacs
|
|||
|
|
<strong>Content</strong>: Common import patterns
|
|||
|
|
<strong>Priority</strong>: Low</p>
|
|||
|
|
<h3 id="4-automated-validation"><a class="header" href="#4-automated-validation">4. Automated Validation</a></h3>
|
|||
|
|
<p><strong>Tool</strong>: CI/CD check for anti-patterns
|
|||
|
|
<strong>Check</strong>: Ensure no re-exports in new code
|
|||
|
|
<strong>Priority</strong>: Medium</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h2>
|
|||
|
|
<p>The KCL module organization is now clean, well-documented, and follows best practices. The direct submodule import pattern:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>✅ Resolves all ImmutableError issues</li>
|
|||
|
|
<li>✅ Aligns with KCL language design</li>
|
|||
|
|
<li>✅ Was already implemented by the codebase</li>
|
|||
|
|
<li>✅ Just needed cleanup and documentation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Status</strong>: Production-ready. No further changes required for basic functionality.</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="related-documentation"><a class="header" href="#related-documentation">Related Documentation</a></h2>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Import Patterns Guide</strong>: <code>docs/architecture/kcl-import-patterns.md</code> (comprehensive reference)</li>
|
|||
|
|
<li><strong>Core Module</strong>: <code>provisioning/kcl/main.k</code> (documented entry point)</li>
|
|||
|
|
<li><strong>KCL Official Docs</strong>: https://www.kcl-lang.io/docs/reference/lang/spec/</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="support"><a class="header" href="#support">Support</a></h2>
|
|||
|
|
<p>For questions about KCL imports:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Check <code>docs/architecture/kcl-import-patterns.md</code></li>
|
|||
|
|
<li>Review <code>provisioning/kcl/main.k</code> documentation</li>
|
|||
|
|
<li>Examine working examples in <code>provisioning/extensions/</code></li>
|
|||
|
|
<li>Consult KCL language specification</li>
|
|||
|
|
</ol>
|
|||
|
|
<hr />
|
|||
|
|
<p><strong>Last Updated</strong>: 2025-10-03
|
|||
|
|
<strong>Maintained By</strong>: Architecture Team
|
|||
|
|
<strong>Review Cycle</strong>: Quarterly or when KCL version updates</p>
|
|||
|
|
|
|||
|
|
</main>
|
|||
|
|
|
|||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
|
<!-- Mobile navigation buttons -->
|
|||
|
|
<a rel="prev" href="../../development/kcl/KCL_GUIDELINES_IMPLEMENTATION.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../development/kcl/KCL_MODULE_SYSTEM_IMPLEMENTATION.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<div style="clear: both"></div>
|
|||
|
|
</nav>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|||
|
|
<a rel="prev" href="../../development/kcl/KCL_GUIDELINES_IMPLEMENTATION.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../development/kcl/KCL_MODULE_SYSTEM_IMPLEMENTATION.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Livereload script (if served using the cli tool) -->
|
|||
|
|
<script>
|
|||
|
|
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|||
|
|
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
|||
|
|
const socket = new WebSocket(wsAddress);
|
|||
|
|
socket.onmessage = function (event) {
|
|||
|
|
if (event.data === "reload") {
|
|||
|
|
socket.close();
|
|||
|
|
location.reload();
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
window.onbeforeunload = function() {
|
|||
|
|
socket.close();
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
window.playground_copyable = true;
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script src="../../elasticlunr.min.js"></script>
|
|||
|
|
<script src="../../mark.min.js"></script>
|
|||
|
|
<script src="../../searcher.js"></script>
|
|||
|
|
|
|||
|
|
<script src="../../clipboard.min.js"></script>
|
|||
|
|
<script src="../../highlight.js"></script>
|
|||
|
|
<script src="../../book.js"></script>
|
|||
|
|
|
|||
|
|
<!-- Custom JS scripts -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|