provisioning/docs/book/user/SERVICE_MANAGEMENT_QUICKREF.html
Jesús Pérez 6a59d34bb1
chore: update provisioning configuration and documentation
Update configuration files, templates, and internal documentation
for the provisioning repository system.

Configuration Updates:
- KMS configuration modernization
- Plugin system settings
- Service port mappings
- Test cluster topologies
- Installation configuration examples
- VM configuration defaults
- Cedar authorization policies

Documentation Updates:
- Library module documentation
- Extension API guides
- AI system documentation
- Service management guides
- Test environment setup
- Plugin usage guides
- Validator configuration documentation

All changes are backward compatible.
2025-12-11 21:50:42 +00:00

537 lines
22 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Service Management Quick Reference - 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/user/SERVICE_MANAGEMENT_QUICKREF.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="service-management-quick-reference"><a class="header" href="#service-management-quick-reference">Service Management Quick Reference</a></h1>
<p><strong>Version</strong>: 1.0.0</p>
<h2 id="platform-commands-manage-all-services"><a class="header" href="#platform-commands-manage-all-services">Platform Commands (Manage All Services)</a></h2>
<pre><code class="language-bash"># Start all auto-start services
provisioning platform start
# Start specific services with dependencies
provisioning platform start control-center mcp-server
# Stop all running services
provisioning platform stop
# Stop specific services
provisioning platform stop orchestrator
# Restart services
provisioning platform restart
# Show platform status
provisioning platform status
# Check platform health
provisioning platform health
# View service logs
provisioning platform logs orchestrator --follow
</code></pre>
<hr />
<h2 id="service-commands-individual-services"><a class="header" href="#service-commands-individual-services">Service Commands (Individual Services)</a></h2>
<pre><code class="language-bash"># List all services
provisioning services list
# List only running services
provisioning services list --running
# Filter by category
provisioning services list --category orchestration
# Service status
provisioning services status orchestrator
# Start service (with pre-flight checks)
provisioning services start orchestrator
# Force start (skip checks)
provisioning services start orchestrator --force
# Stop service
provisioning services stop orchestrator
# Force stop (ignore dependents)
provisioning services stop orchestrator --force
# Restart service
provisioning services restart orchestrator
# Check health
provisioning services health orchestrator
# View logs
provisioning services logs orchestrator --follow --lines 100
# Monitor health continuously
provisioning services monitor orchestrator --interval 30
</code></pre>
<hr />
<h2 id="dependency--validation"><a class="header" href="#dependency--validation">Dependency &amp; Validation</a></h2>
<pre><code class="language-bash"># View dependency graph
provisioning services dependencies
# View specific service dependencies
provisioning services dependencies control-center
# Validate all services
provisioning services validate
# Check readiness
provisioning services readiness
# Check required services for operation
provisioning services check server
</code></pre>
<hr />
<h2 id="registered-services"><a class="header" href="#registered-services">Registered Services</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Service</th><th>Port</th><th>Type</th><th>Auto-Start</th><th>Dependencies</th></tr></thead><tbody>
<tr><td>orchestrator</td><td>8080</td><td>Platform</td><td>Yes</td><td>-</td></tr>
<tr><td>control-center</td><td>8081</td><td>Platform</td><td>No</td><td>orchestrator</td></tr>
<tr><td>coredns</td><td>5353</td><td>Infrastructure</td><td>No</td><td>-</td></tr>
<tr><td>gitea</td><td>3000, 222</td><td>Infrastructure</td><td>No</td><td>-</td></tr>
<tr><td>oci-registry</td><td>5000</td><td>Infrastructure</td><td>No</td><td>-</td></tr>
<tr><td>mcp-server</td><td>8082</td><td>Platform</td><td>No</td><td>orchestrator</td></tr>
<tr><td>api-gateway</td><td>8083</td><td>Platform</td><td>No</td><td>orchestrator, control-center, mcp-server</td></tr>
</tbody></table>
</div>
<hr />
<h2 id="docker-compose"><a class="header" href="#docker-compose">Docker Compose</a></h2>
<pre><code class="language-bash"># Start all services
cd provisioning/platform
docker-compose up -d
# Start specific services
docker-compose up -d orchestrator control-center
# Check status
docker-compose ps
# View logs
docker-compose logs -f orchestrator
# Stop all services
docker-compose down
# Stop and remove volumes
docker-compose down -v
</code></pre>
<hr />
<h2 id="service-state-directories"><a class="header" href="#service-state-directories">Service State Directories</a></h2>
<pre><code>~/.provisioning/services/
├── pids/ # Process ID files
├── state/ # Service state (JSON)
└── logs/ # Service logs
</code></pre>
<hr />
<h2 id="health-check-endpoints"><a class="header" href="#health-check-endpoints">Health Check Endpoints</a></h2>
<div class="table-wrapper"><table><thead><tr><th>Service</th><th>Endpoint</th><th>Type</th></tr></thead><tbody>
<tr><td>orchestrator</td><td>http://localhost:9090/health</td><td>HTTP</td></tr>
<tr><td>control-center</td><td>http://localhost:9080/health</td><td>HTTP</td></tr>
<tr><td>coredns</td><td>localhost:5353</td><td>TCP</td></tr>
<tr><td>gitea</td><td>http://localhost:3000/api/healthz</td><td>HTTP</td></tr>
<tr><td>oci-registry</td><td>http://localhost:5000/v2/</td><td>HTTP</td></tr>
<tr><td>mcp-server</td><td>http://localhost:8082/health</td><td>HTTP</td></tr>
<tr><td>api-gateway</td><td>http://localhost:8083/health</td><td>HTTP</td></tr>
</tbody></table>
</div>
<hr />
<h2 id="common-workflows"><a class="header" href="#common-workflows">Common Workflows</a></h2>
<h3 id="start-platform-for-development"><a class="header" href="#start-platform-for-development">Start Platform for Development</a></h3>
<pre><code class="language-bash"># Start core services
provisioning platform start orchestrator
# Check status
provisioning platform status
# Check health
provisioning platform health
</code></pre>
<h3 id="start-full-platform-stack"><a class="header" href="#start-full-platform-stack">Start Full Platform Stack</a></h3>
<pre><code class="language-bash"># Use Docker Compose
cd provisioning/platform
docker-compose up -d
# Verify
docker-compose ps
provisioning platform health
</code></pre>
<h3 id="debug-service-issues"><a class="header" href="#debug-service-issues">Debug Service Issues</a></h3>
<pre><code class="language-bash"># Check service status
provisioning services status &lt;service&gt;
# View logs
provisioning services logs &lt;service&gt; --follow
# Check health
provisioning services health &lt;service&gt;
# Validate prerequisites
provisioning services validate
# Restart service
provisioning services restart &lt;service&gt;
</code></pre>
<h3 id="safe-service-shutdown"><a class="header" href="#safe-service-shutdown">Safe Service Shutdown</a></h3>
<pre><code class="language-bash"># Check dependents
nu -c "use lib_provisioning/services/mod.nu *; can-stop-service orchestrator"
# Stop with dependency check
provisioning services stop orchestrator
# Force stop if needed
provisioning services stop orchestrator --force
</code></pre>
<hr />
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<h3 id="service-wont-start"><a class="header" href="#service-wont-start">Service Wont Start</a></h3>
<pre><code class="language-bash"># 1. Check prerequisites
provisioning services validate
# 2. View detailed status
provisioning services status &lt;service&gt;
# 3. Check logs
provisioning services logs &lt;service&gt;
# 4. Verify binary/image exists
ls ~/.provisioning/bin/&lt;service&gt;
docker images | grep &lt;service&gt;
</code></pre>
<h3 id="health-check-failing"><a class="header" href="#health-check-failing">Health Check Failing</a></h3>
<pre><code class="language-bash"># Check endpoint manually
curl http://localhost:9090/health
# View health details
provisioning services health &lt;service&gt;
# Monitor continuously
provisioning services monitor &lt;service&gt; --interval 10
</code></pre>
<h3 id="pid-file-stale"><a class="header" href="#pid-file-stale">PID File Stale</a></h3>
<pre><code class="language-bash"># Remove stale PID file
rm ~/.provisioning/services/pids/&lt;service&gt;.pid
# Restart service
provisioning services restart &lt;service&gt;
</code></pre>
<h3 id="port-already-in-use"><a class="header" href="#port-already-in-use">Port Already in Use</a></h3>
<pre><code class="language-bash"># Find process using port
lsof -i :9090
# Kill process
kill &lt;PID&gt;
# Restart service
provisioning services start &lt;service&gt;
</code></pre>
<hr />
<h2 id="integration-with-operations"><a class="header" href="#integration-with-operations">Integration with Operations</a></h2>
<h3 id="server-operations"><a class="header" href="#server-operations">Server Operations</a></h3>
<pre><code class="language-bash"># Orchestrator auto-starts if needed
provisioning server create
# Manual check
provisioning services check server
</code></pre>
<h3 id="workflow-operations"><a class="header" href="#workflow-operations">Workflow Operations</a></h3>
<pre><code class="language-bash"># Orchestrator auto-starts
provisioning workflow submit my-workflow
# Check status
provisioning services status orchestrator
</code></pre>
<h3 id="test-operations"><a class="header" href="#test-operations">Test Operations</a></h3>
<pre><code class="language-bash"># Orchestrator required for test environments
provisioning test quick kubernetes
# Pre-flight check
provisioning services check test-env
</code></pre>
<hr />
<h2 id="advanced-usage"><a class="header" href="#advanced-usage">Advanced Usage</a></h2>
<h3 id="custom-service-startup-order"><a class="header" href="#custom-service-startup-order">Custom Service Startup Order</a></h3>
<p>Services start based on:</p>
<ol>
<li>Dependency order (topological sort)</li>
<li><code>start_order</code> field (lower = earlier)</li>
</ol>
<h3 id="auto-start-configuration"><a class="header" href="#auto-start-configuration">Auto-Start Configuration</a></h3>
<p>Edit <code>provisioning/config/services.toml</code>:</p>
<pre><code class="language-toml">[services.&lt;service&gt;.startup]
auto_start = true # Enable auto-start
start_timeout = 30 # Timeout in seconds
start_order = 10 # Startup priority
</code></pre>
<h3 id="health-check-configuration"><a class="header" href="#health-check-configuration">Health Check Configuration</a></h3>
<pre><code class="language-toml">[services.&lt;service&gt;.health_check]
type = "http" # http, tcp, command, file
interval = 10 # Seconds between checks
retries = 3 # Max retry attempts
timeout = 5 # Check timeout
[services.&lt;service&gt;.health_check.http]
endpoint = "http://localhost:9090/health"
expected_status = 200
</code></pre>
<hr />
<h2 id="key-files"><a class="header" href="#key-files">Key Files</a></h2>
<ul>
<li><strong>Service Registry</strong>: <code>provisioning/config/services.toml</code></li>
<li><strong>KCL Schema</strong>: <code>provisioning/kcl/services.k</code></li>
<li><strong>Docker Compose</strong>: <code>provisioning/platform/docker-compose.yaml</code></li>
<li><strong>User Guide</strong>: <code>docs/user/SERVICE_MANAGEMENT_GUIDE.md</code></li>
</ul>
<hr />
<h2 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h2>
<pre><code class="language-bash"># View documentation
cat docs/user/SERVICE_MANAGEMENT_GUIDE.md | less
# Run verification
nu provisioning/core/nulib/tests/verify_services.nu
# Check readiness
provisioning services readiness
</code></pre>
<hr />
<p><strong>Quick Tip</strong>: Use <code>--help</code> flag with any command for detailed usage information.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../user/SERVICE_MANAGEMENT_GUIDE.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="../user/test-environment-guide.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="../user/SERVICE_MANAGEMENT_GUIDE.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="../user/test-environment-guide.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>