### Minimal Kubesolo Setup

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Start Kubesolo using default configurations. This setup enables local storage and load balancer support without Portainer integration.

```bash
# Start with defaults
kubesolo

# Results in:
# - Runs at /var/lib/kubesolo
# - Local storage enabled
# - LoadBalancer support enabled
# - No Portainer integration
```

--------------------------------

### Kubelet Service Initialization and Run Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Demonstrates initializing the kubelet service and starting its execution, including waiting for the API server and the kubelet itself to be ready.

```go
readyCh := make(chan struct{})
kubeletService := kubelet.NewService(ctx, cancel, readyCh, &embedded)

go kubeletService.Run(apiServerReadyCh)  // Waits for API server
<-readyCh  // Wait for kubelet ready
```

--------------------------------

### Buildroot Kubesolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Example of how to add Kubesolo installation to a Buildroot package definition.

```bash
define KUBESOLO_INSTALL_TARGET_CMDS
    $(INSTALL) -D -m 0755 $(KUBESOLO_PKGDIR)/install-minimal.sh $(TARGET_DIR)/usr/bin/
endef
```

--------------------------------

### Controller Manager Service Initialization and Run Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Demonstrates initializing the controller manager service and starting its execution. It includes waiting for the controller to become ready.

```go
readyCh := make(chan struct{})
controllerService := controller.NewService(
    ctx,
    cancel,
    readyCh,
    embedded.ControllerDir,
    embedded,
)

go controllerService.Run(apiServerReadyCh)  // Waits for API server
<-readyCh  // Wait for controller to be ready
```

--------------------------------

### Download and Run KubeSolo Installer

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Downloads the universal installer script directly from GitHub and executes it. This is an alternative to the standard installation method.

```bash
curl -sfL https://raw.githubusercontent.com/portainer/kubesolo/develop/install.sh | sudo sh -
```

--------------------------------

### KubeSolo Installation with Options

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo using the universal installer with specific options for version, installation path, and run mode. Useful for custom deployments.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- \
  --version=v1.1.6 \
  --path=/opt/kubesolo \
  --run-mode=service
```

--------------------------------

### Install KubeSolo in Daemon Mode

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Use the `--run-mode=daemon` flag to start KubeSolo as a background process with a PID file and logs. This is useful when no supported init system is available.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --run-mode=daemon
```

--------------------------------

### Minimal KubeSolo Installation with Environment Variables

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo using the minimal script, specifying the version and installation path via environment variables. This allows for customized minimal installations.

```bash
KUBESOLO_VERSION=v1.1.6 KUBESOLO_PATH=/opt/kubesolo sh install-minimal.sh
```

--------------------------------

### Example KubeSolo Version Output

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

This is an example of how the version information is displayed at startup, including the version, build date, and commit hash.

```text
version=v1.0.0 build-date=2024-01-15T10:30:00Z commit=abc123def456
```

--------------------------------

### Yocto/OpenEmbedded Kubesolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Example of how to include the Kubesolo installation script in a Yocto recipe.

```bash
SRC_URI += "https://raw.githubusercontent.com/portainer/kubesolo/develop/install-minimal.sh"

do_install() {
    install -d ${D}${bindir}
    install -m 0755 ${WORKDIR}/install-minimal.sh ${D}${bindir}/
}
```

--------------------------------

### Install KubeSolo from Downloaded Script

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Installs KubeSolo by running a downloaded script directly. Flags are passed as normal arguments.

```bash
sudo sh install.sh --version=v1.1.2 --local-storage=true
```

--------------------------------

### Install Kubesolo with Proxy and Custom Options

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Combine proxy settings with other installation options like version and path.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- \
  --proxy=http://proxy.company.com:8080 \
  --version=v1.1.6 \
  --path=/opt/kubesolo
```

--------------------------------

### Manual KubeSolo Installation for Air-Gapped Environments

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Manually installs KubeSolo in an air-gapped environment by pre-downloading the binary, extracting it, and placing it in the system's PATH. This method bypasses the need for direct internet access during installation.

```bash
wget https://github.com/portainer/kubesolo/releases/download/v1.1.6/kubesolo-v1.1.6-linux-arm64.tar.gz
tar -xzf kubesolo-*.tar.gz
mv kubesolo /usr/local/bin/kubesolo
chmod +x /usr/local/bin/kubesolo
```

--------------------------------

### Start Profiling Server

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Starts the pprof profiling server on http://localhost:6060/debug/pprof/. This should only be enabled if the --pprof-server flag is used.

```go
func StartMonitoring()
```

--------------------------------

### Example KubeSolo Command-Line Execution

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Demonstrates how to execute the KubeSolo application from the command line with specified path and debug flags.

```bash
kubesolo --path=/var/lib/kubesolo --debug
```

--------------------------------

### Run

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-runtime.md

Starts the containerd service and blocks until shutdown. This method handles the entire lifecycle of the containerd daemon, from setup to graceful termination.

```APIDOC
## Run

Starts the containerd service and blocks until shutdown.

### Description

This method initiates the containerd service, managing its lifecycle including directory creation, binary extraction, configuration generation, and daemon startup. It blocks execution until the service is shut down.

### Signature

```go
func (s *service) Run() error
```

### Parameters

* None

### Returns

* `nil` if shut down gracefully.
* `error` on fatal error during operation.

### Startup Sequence

1. Creates necessary directories (root, state, images)
2. Extracts containerd and crun binaries from embedded resources
3. Generates containerd configuration file (config.toml)
4. Configures container runtimes (runc and crun)
5. Configures CNI (Container Network Interface) plugins
6. Configures registry settings (for image pulling)
7. Starts containerd daemon
8. Loads embedded container images into containerd
9. Checks containerd readiness (via socket connectivity)
10. Signals readiness through `containerdReady` channel
11. Blocks until context cancelled
12. Gracefully terminates on shutdown
```

--------------------------------

### Online Kubesolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Installs Kubesolo using the default online method, which downloads container images at startup. Run this with sudo.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -
```

--------------------------------

### Kubesolo Command Line Arguments

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Examples of how to run Kubesolo with and without edge credentials.

```bash
kubesolo  # Don't provide edge credentials

# Then add credentials later
kubesolo --portainer-edge-id=valid-id --portainer-edge-key=valid-key
```

--------------------------------

### Install KubeSolo with Custom Data Path

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Installs KubeSolo and overrides the default data directory. Use this when the default location lacks sufficient disk space.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --path=/data/kubesolo
```

--------------------------------

### Air-gapped Kubesolo Installation from Bundle

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Installs Kubesolo on an air-gapped machine using a previously downloaded bundle. Ensure the archive file path is correct.

```bash
sudo sh install.sh --offline-install=<archive.tar.gz>
```

--------------------------------

### Install KubeSolo with Specific Version (URL)

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Installs a specific version of KubeSolo by piping the install script from a URL. Defaults to the latest stable release if --version is omitted.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --version=v1.1.2
```

--------------------------------

### Example Usage of KubeSolo Service Factory

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Illustrates how to use the `service` factory function to create, bootstrap, and run the KubeSolo service, including error handling.

```go
svc, err := service()
if err != nil {
    log.Fatal("Failed to create service:", err)
}
svc.bootstrap()
svc.run()
```

--------------------------------

### Check Detected Init System

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Use the --help flag with the installer to check which init system it detects on your system.

```bash
curl -sfL https://get.kubesolo.io | sh -s -- --help
```

--------------------------------

### KubeSolo Installation with Minimal Installer and Disabled Local Storage

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo using the minimal installer and explicitly disables local storage provisioner. This is for devices with limited storage or when local storage is not needed.

```bash
./install-minimal.sh
export KUBESOLO_LOCAL_STORAGE="false"
```

--------------------------------

### Create SysV init Service for Kubesolo

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

This snippet shows how to create a basic SysV init script for managing the Kubesolo service. It includes start and stop commands.

```bash
#!/bin/sh
case "$1" in
    start) /usr/local/bin/kubesolo --path=/var/lib/kubesolo & ;; 
    stop) pkill kubesolo ;; 
    *) echo "Usage: $0 {start|stop}" ;; 
esac

```

--------------------------------

### Install KubeSolo with Specific Version and Local Storage

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Installs a specific version of KubeSolo and enables local storage provisioning. Use this when piping the script from a URL.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --version=v1.1.2 --local-storage=true
```

--------------------------------

### Test Configuration Before Starting

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

While Kubesolo lacks a built-in dry-run option, you can test if configuration files like the admin kubeconfig have been generated from a previous run. This verifies PKI setup.

```bash
# No built-in dry-run, but can check:
ls -la /var/lib/kubesolo/pki/admin/admin.kubeconfig
# Certificate already generated from previous run
```

--------------------------------

### Basic KubeSolo Usage

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

The basic command to start KubeSolo. No flags are specified, so default values will be used.

```bash
kubesolo [flags]
```

--------------------------------

### Enable Profiling for Kubesolo

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Start the pprof server to profile memory usage and performance issues.

```bash
kubesolo --pprof-server
# Then
go tool pprof http://localhost:6060/debug/pprof/heap
```

--------------------------------

### Logging Configuration Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Example log output demonstrating structured JSON format with component names. Logging level is controlled by the --debug flag.

```Log
level=info component=kubesolo msg="starting kubesolo..."
level=info component=containerd msg="starting containerd..."
level=info component=kine msg="kine is ready..."
```

--------------------------------

### Orchestrate Kubesolo Services

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Starts all services in dependency order and manages their lifecycle, including infrastructure services, network setup, node services, and add-on components. It also handles graceful shutdown via signal catching and context cancellation.

```go
func (s *kubesolo) run()
```

```text
INFO Starting kubesolo...
  version=v1.0.0
  build-date=2024-01-15T10:30:00Z
  commit=abc123def456
  profile=edge

INFO Ensuring all embedded dependencies are available...
INFO Generating relevant certificates...
INFO Starting kubesolo services...

INFO Starting containerd...
INFO containerd is ready...
INFO Starting kine...
INFO kine is ready...
INFO Starting apiserver...
INFO apiserver is ready...
INFO Starting controller...
INFO controller is ready...

INFO Setting up pod masquerade rules...

INFO Starting kubelet...
INFO kubelet is ready...
INFO Starting kubeproxy...
INFO kubeproxy is ready...

INFO Deploying coredns...
INFO Deploying local path...
INFO Deploying portainer edge agent...

INFO All services ready. Cluster is operational.
```

--------------------------------

### Create and Run Containerd Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-runtime.md

Instantiates and starts the containerd service. Use this to initialize the container runtime and wait for it to become ready.

```go
readyCh := make(chan struct{})
containerdService := containerd.NewService(ctx, cancel, readyCh, &embedded)

g o containerdService.Run()
<-readyCh  // Wait for containerd ready
```

--------------------------------

### Minimal KubeSolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo using a minimal script designed for extremely constrained busybox-based systems. It has minimal dependencies and creates a simple init script.

```bash
wget -O - https://raw.githubusercontent.com/portainer/kubesolo/develop/install-minimal.sh | sh
```

--------------------------------

### Service Run Method Pattern

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Demonstrates the typical structure for a service's Run method, including dependency waiting, setup, readiness signaling, context handling, and cleanup.

```go
func (s *service) Run(...readyChs chan struct{}) error {
    // Wait for dependencies
    <-dependencyReadyCh
    
    // Initialize
    if err := s.setup(); err != nil {
        return err
    }
    
    // Signal readiness
    close(s.readyCh)
    
    // Run until context cancelled
    <-s.ctx.Done()
    
    // Cleanup
    s.terminate()
    return nil
}
```

--------------------------------

### Install KubeSolo Development Version with Local Storage

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Installs the development version of KubeSolo from the 'develop' branch, enabling local storage provisioning. Use this for testing unreleased changes.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --local-storage=true
```

--------------------------------

### KubeSolo Installation with Proxy

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo using the universal installer, specifying a corporate proxy for HTTP/HTTPS requests. Essential for environments with network restrictions.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- \
  --proxy=http://proxy.company.com:8080
```

--------------------------------

### Install Cross-Compilation Toolchains for Kubesolo

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Installs necessary GCC toolchains for cross-compiling Kubesolo for different architectures like ARM64, AMD64, and ARMHF.

```bash
sudo make install-cross-compilers
```

--------------------------------

### Portainer Edge Agent Configuration Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

Example of how to configure the types.EdgeAgentConfig struct for deploying the Portainer Edge Agent. Ensure all required fields like EdgeID and EdgeKey are provided.

```go
config := types.EdgeAgentConfig{
    EdgeID:          "abc123",
    EdgeKey:         "xyz789",
    EdgeAsync:       true,
    EdgeInsecurePoll: "false",
}

err := portainer.DeployEdgeAgent(
    "/var/lib/kubesolo/pki/admin/admin.kubeconfig",
    config,
)
if err != nil {
    log.Fatal("Failed to deploy Portainer Edge Agent:", err)
}
```

--------------------------------

### Install Kubesolo with Corporate Proxy Support (Environment Variable)

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Alternatively, set the KUBESOLO_PROXY environment variable before running the installer to configure proxy settings.

```bash
export KUBESOLO_PROXY="http://proxy.company.com:8080"
curl -sfL https://get.kubesolo.io | sudo sh -
```

--------------------------------

### Install KubeSolo using tmpfs for Runtime Data

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo with its runtime data stored in a tmpfs (temporary file system). This is suitable for devices where data persistence is not required or managed externally.

```bash
export KUBESOLO_PATH="/tmp/kubesolo"
```

--------------------------------

### Deploy Portainer Edge with Environment Variables

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

Example of deploying the Portainer Edge Agent by setting environment variables for Edge ID and Key before running the Kubesolo command.

```bash
export KUBESOLO_PORTAINER_EDGE_ID=my-edge-id
export KUBESOLO_PORTAINER_EDGE_KEY=my-edge-key
kubesolo
```

--------------------------------

### Install musl Cross-Compilers for Kubesolo

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Installs the necessary cross-compilation toolchains for building musl-compatible static binaries, primarily for Alpine Linux.

```bash
sudo make install-musl-cross-compilers
```

--------------------------------

### Troubleshooting Pod Startup Failures

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Commands to check pod status, logs, and container runtime details when pods fail to start.

```bash
# Check pod status
kubectl describe pod <name>

# Check logs
kubectl logs <pod>

# Check containerd
ctr images list
ctr tasks list

# Check kubelet
journalctl -u kubelet -f  # If systemd
```

--------------------------------

### Install KubeSolo to Writable Partition on Read-Only Filesystem

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Installs KubeSolo to a specified writable partition when the root filesystem is read-only. This is common on industrial devices with persistent storage separate from the OS.

```bash
export KUBESOLO_PATH="/data/kubesolo"
curl -sfL https://get.kubesolo.io | sudo sh -s -- --path=/data/kubesolo
```

--------------------------------

### Initialize and Run API Server Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-apiserver.md

Initializes the API server service and starts its execution. It waits for Kine to be ready before proceeding and signals its own readiness upon successful startup.

```go
readyCh := make(chan struct{})
apiService := apiserver.NewService(
    ctx,
    cancel,
    readyCh,
    system.GetHostname(),
    embedded,  // types.Embedded struct
)

go apiService.Run(kineReadyCh)  // Wait for Kine to be ready first
<-readyCh  // Wait for API server to be ready
```

--------------------------------

### Enable Profiling Server

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Starts the KubeSolo application with the profiling server enabled via the --pprof-server flag, allowing access to various performance profiles.

```bash
kubesolo --pprof-server
```

--------------------------------

### Enable pprof HTTP Server

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Starts the Go pprof HTTP server on port 6060. This is intended for profiling and performance analysis.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --pprof-server=true
```

--------------------------------

### Run Service Method

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-apiserver.md

Starts the API Server service. This method blocks until the service is shut down. It handles the startup sequence, including waiting for Kine readiness, generating kubeconfig, configuring flags, and starting the API server.

```APIDOC
## Run

Starts the API Server service and blocks until shutdown.

### Signature

```go
func (s *service) Run(kineReadyCh chan struct{}) error
```

### Parameters

#### Path Parameters

*   **kineReadyCh** (chan struct{}) - Channel that signals when Kine is ready (waits for this before starting)

### Returns

*   `nil` if shut down gracefully
*   `error` on fatal error

### Startup Sequence

1. Waits for Kine to signal readiness (blocks until `kineReadyCh` is closed)
2. Generates kubeconfig file (`admin.kubeconfig`)
3. Configures API server flags for KubeSolo environment
4. Registers NodeSetter admission webhook plugin (KubeSolo's custom scheduler replacement)
5. Initializes Kubernetes client for RBAC setup
6. Applies RBAC policies for:
   - API server to kubelet communication
   - Admin user permissions
7. Starts gRPC webhook server for mutations
8. Starts API server on `localhost:6443`
9. Checks API server readiness with probe
10. Signals readiness through `apiServerReady` channel
11. Blocks until context cancelled

### Example

```go
ctx, cancel := context.WithCancel(context.Background())
apiService := apiserver.NewService(ctx, cancel, readyCh, "mynode", embedded)

// Start API server (waits for Kine)
if err := apiService.Run(kineReadyCh); err != nil {
    log.Fatal("API server failed:", err)
}
```
```

--------------------------------

### Deploy Portainer Edge with CLI Flags

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

Example of deploying the Portainer Edge Agent using command-line flags for Edge ID and Key.

```bash
kubesolo --portainer-edge-id=my-edge-id --portainer-edge-key=my-edge-key
```

--------------------------------

### Offline Kubesolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Installs Kubesolo using an offline binary that includes all necessary container images. This method requires no internet access at runtime. Run this with sudo.

```bash
curl -sfL https://get.kubesolo.io | KUBESOLO_OFFLINE=true sudo -E sh -
```

--------------------------------

### Check Kubesolo Service Logs

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Monitor the service logs to troubleshoot issues with Kubesolo not starting.

```bash
tail -f /var/log/kubesolo.log
```

--------------------------------

### Portainer Edge Agent ConfigMap Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

Example of the configuration data included in the Portainer Edge Agent's ConfigMap. This includes the agent tag and Kubernetes namespace.

```yaml
AGENT_TAG: 3  # Edge agent version
AGENT_KUBERNETES_NAMESPACE: portainer
```

--------------------------------

### Configure Kubesolo via Environment Variables

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Set KubeSolo configuration options using environment variables prefixed with KUBESOLO_. This example shows setting path, debug mode, and Portainer integration details.

```bash
# Using environment variables
export KUBESOLO_PATH=/opt/kubesolo
export KUBESOLO_DEBUG=true
export KUBESOLO_PORTAINER_EDGE_ID=abc123
export KUBESOLO_PORTAINER_EDGE_KEY=xyz789

kubesolo
```

--------------------------------

### Enable Portainer Integration

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/README.md

Start Kubesolo with Portainer credentials to enable integration. The Edge Agent will be deployed to the 'portainer' namespace.

```bash
# Start with Portainer credentials
kubesolo \
  --portainer-edge-id=your-edge-id \
  --portainer-edge-key=your-edge-key

# Agent deployed to 'portainer' namespace
kubectl get pods -n portainer
```

--------------------------------

### Run Method

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kine.md

Starts the Kine service and blocks until the context is cancelled or a fatal error occurs. It handles database repair, gRPC server startup, and readiness signaling.

```APIDOC
## Run

Starts the Kine service and blocks until context is cancelled or fatal error occurs.

### Signature

```go
func (s *service) Run() error
```

### Returns

- **nil** - if service shut down gracefully
- **error** - if service encountered a fatal error during startup or operation

### Behavior

1. Repairs SQLite database if `dbWALRepair` enabled and corruption detected
2. Creates necessary directories and files
3. Starts gRPC server on Kine socket
4. Signals readiness through `kineReady` channel
5. Blocks until context is cancelled or error occurs
6. Gracefully terminates resources

### Example

```go
ctx, cancel := context.WithCancel(context.Background())
kineService := kine.NewService(ctx, cancel, "/path/to/kine", readyCh, true)

if err := kineService.Run(); err != nil {
    log.Fatal("Kine service failed:", err)
}
```
```

--------------------------------

### Configure Kubesolo with Portainer Edge

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Use this command to install KubeSolo and configure it to use Portainer Edge by setting environment variables for the Edge ID and key.

```bash
curl -sfL https://get.kubesolo.io | KUBESOLO_PORTAINER_EDGE_ID=your-portainer-edge-id KUBESOLO_PORTAINER_EDGE_KEY=your-portainer-edge-key sudo -E sh
```

--------------------------------

### KubeSolo Service Creation and Readiness

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/README.md

Demonstrates the pattern for creating a new service, running it in a goroutine, and waiting for its readiness signal.

```go
readyCh := make(chan struct{})
svc := component.NewService(ctx, cancel, readyCh, ...params)
go svc.Run(dependencyReadyCh)
<-readyCh  // Wait for readiness
```

--------------------------------

### Webhook Mutation Example for Pods

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Illustrates the transformation of a Pod manifest by the webhook, showing the addition of node assignment and node selector fields.

```yaml
# Before:
spec:
  containers:
  - name: app
    image: myapp:latest

# After (webhook mutated):
spec:
  nodeName: kubesolo-node
  nodeSelector:
    kubernetes.io/hostname: kubesolo-node
  containers:
  - name: app
    image: myapp:latest
```

--------------------------------

### Create New Kine Service Instance

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kine.md

Instantiates a new Kine service. The service needs to be started with `Run()` in a goroutine. Always wait for the `kineReady` channel to be closed before proceeding.

```go
ctx, cancel := context.WithCancel(context.Background())
readyCh := make(chan struct{})

kineService := kine.NewService(
    ctx,
    cancel,
    "/var/lib/kubesolo/kine",
    readyCh,
    false,  // WAL repair disabled
)

// Start service in goroutine
go kineService.Run()

// Wait for readiness
<-readyCh
```

--------------------------------

### Development Setup with Full Kubernetes Defaults

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Configure Kubesolo for development with full Kubernetes defaults. This enables the --full flag, debug mode, and specifies extra SANs for the API server.

```bash
kubesolo \
  --full \
  --debug \
  --apiserver-extra-sans=localhost,127.0.0.1,kubesolo.local
```

--------------------------------

### Run Kubelet Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Starts the kubelet service, which manages containers on a node. It waits for the API server to be ready, generates kubeconfig, configures flags for single-node operation, and registers the node with the API server.

```go
func (s *service) Run(apiServerReadyCh chan struct{}) error

```

```go
ctx, cancel := context.WithCancel(context.Background())
kubeletService := kubelet.NewService(ctx, cancel, readyCh, &embedded)

if err := kubeletService.Run(apiServerReadyCh); err != nil {
    log.Fatal("Kubelet failed:", err)
}

```

--------------------------------

### Containerd Health Check Example

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-runtime.md

A Go code snippet demonstrating how to check containerd's readiness by attempting to connect to its socket. The service is considered ready when the socket is accessible and responsive.

```go
// Attempt connection to socket
conn, err := client.New(socketPath)
if err != nil {
    // Not ready
}
conn.Close()
// Ready
```

--------------------------------

### Controller Manager Service Run with Error Handling

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Shows how to run the controller manager service and handle potential errors during its execution. This example includes context cancellation.

```go
ctx, cancel := context.WithCancel(context.Background())
controllerService := controller.NewService(ctx, cancel, readyCh, "/path/to/controller", embedded)

if err := controllerService.Run(apiServerReadyCh); err != nil {
    log.Fatal("Controller failed:", err)
}
```

--------------------------------

### Network Masquerading Setup

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-runtime.md

This bash command ensures Source Network Address Translation (SNAT) for the pod network, allowing pods to reach external services using the host's IP address. It is executed after containerd is ready and before kubelet starts.

```bash
# Ensure SNAT for pod network
iptables -t nat -A POSTROUTING -s 10.42.0.0/16 ! -d 10.42.0.0/16 -j MASQUERADE
```

--------------------------------

### Run Kube Proxy Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Starts the kube-proxy service, which manages service endpoints and load balancing. It waits for the kubelet to be ready, configures proxy flags, and selects the appropriate proxy mode (nftables or iptables).

```go
func (s *service) Run(kubeletReadyCh chan struct{}) error

```

```go
ctx, cancel := context.WithCancel(context.Background())
proxyService := kubeproxy.NewService(ctx, cancel, readyCh, adminKubeconfig, false)

if err := proxyService.Run(kubeletReadyCh); err != nil {
    log.Fatal("Kube-proxy failed:", err)
}

```

--------------------------------

### Install KubeSolo with Proxy Configuration

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Configure KubeSolo to route outbound HTTP and HTTPS traffic through a proxy using the `--proxy` flag. The value is applied as `HTTP_PROXY` and `HTTPS_PROXY` environment variables.

```bash
curl -sfL https://get.kubesolo.io | sudo sh -s -- --proxy=http://proxy.corp.internal:3128
```

--------------------------------

### Create and Set Permissions for Kubesolo Path

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Create the necessary directory for Kubesolo and set appropriate permissions. This resolves 'failed to create directory' errors.

```bash
sudo mkdir -p /var/lib/kubesolo
sudo chmod 755 /var/lib/kubesolo
```

--------------------------------

### Alpine Linux Kubesolo Installation

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Install Kubesolo on Alpine Linux. The installer automatically detects OpenRC and musl libc, downloading the appropriate binary.

```bash
# Alpine uses OpenRC and musl libc - installer detects both automatically
apka add curl
curl -sfL https://get.kubesolo.io | sh
```

--------------------------------

### Set KubeSolo Environment Variables

Source: https://github.com/portainer/kubesolo/blob/develop/INSTALL.md

Demonstrates setting various environment variables to configure KubeSolo during installation or runtime. These variables control version, path, Portainer Edge integration, local storage, debug logging, and proxy settings.

```bash
export KUBESOLO_VERSION="v1.1.6"
export KUBESOLO_PATH="/var/lib/kubesolo"
export KUBESOLO_PORTAINER_EDGE_ID="your-id"
export KUBESOLO_PORTAINER_EDGE_KEY="your-key"
export KUBESOLO_PORTAINER_EDGE_ASYNC="false"
export KUBESOLO_LOCAL_STORAGE="false"
export KUBESOLO_DEBUG="false"
export KUBESOLO_PPROF_SERVER="false"
export KUBESOLO_RUN_MODE="service"
export KUBESOLO_PROXY="http://proxy.company.com:8080"
```

--------------------------------

### Re-run KubeSolo with Increased Startup Timeout

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Increase the startup timeout to allow more time for certificate generation. Use for 'failed to generate full certificates' issues.

```bash
kubesolo --startup-timeout=1200
```

--------------------------------

### Install iptables on CentOS/RHEL

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Install the iptables package on CentOS/RHEL-based systems. This is a recovery step for 'failed to set up pod masquerade' errors.

```bash
sudo yum install iptables
```

--------------------------------

### Install iptables on Debian/Ubuntu

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Install the iptables package on Debian-based systems. This is a recovery step for 'failed to set up pod masquerade' errors.

```bash
sudo apt-get update && sudo apt-get install iptables
```

--------------------------------

### Check Command Line Syntax

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Verify command-line flags and syntax for KubeSolo. Use this to troubleshoot 'failed to create service' errors.

```bash
kubesolo --help
```

--------------------------------

### main

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

The entry point for the KubeSolo application. It handles command-line argument parsing, version checking, configuration, service creation, and lifecycle management.

```APIDOC
## main

### Description
The entry point for the KubeSolo application. It parses command-line flags, checks for version information, configures startup timeouts, creates the KubeSolo service, bootstraps necessary components, runs all services, and handles graceful shutdown signals.

### Signature
```go
func main()
```

### Execution Flow
1. Parse Flags
2. Check Version
3. Configure Startup Timeout
4. Create Service
5. Bootstrap
6. Run
7. Handle Shutdown

### Example Execution
```bash
kubesolo --path=/var/lib/kubesolo --debug
```
```

--------------------------------

### Service Initialization and Run Pattern

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/INDEX.md

Standard pattern for initializing and running services within the project. Ensures proper dependency management and readiness signaling.

```go
service := NewService(ctx, cancel, readyCh, ...params)
go service.Run(dependencyReadyCh)
<-readyCh  // Wait for readiness
```

--------------------------------

### Service Constructor Pattern

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Illustrates the common pattern for constructing services in Go, accepting parameters and initializing struct fields.

```go
func NewService(...params) *service {
    return &service{
        field1: param1,
        field2: param2,
        // ...
    }
}
```

--------------------------------

### KubeSolo Dependency Waiting Pattern

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/README.md

Illustrates how a service waits for its dependencies to become ready before proceeding with its own startup sequence.

```go
func (s *service) Run(dependencyReadyCh chan struct{}) error {
    <-dependencyReadyCh  // Block until dependency ready
    // ... continue startup
}
```

--------------------------------

### Download KubeSolo Offline Bundle

Source: https://github.com/portainer/kubesolo/blob/develop/docs/installation/flags.md

Use the `--download-only` flag to download the KubeSolo binary archive and install script without performing an installation. This is useful for preparing offline bundles.

```bash
curl -sfL https://get.kubesolo.io | sh -s -- --download-only
```

```bash
curl -sfL https://get.kubesolo.io | sh -s -- --download-only=./kubesolo-offline
```

--------------------------------

### Download Kubesolo Dependencies

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Downloads all necessary dependencies required for building and running Kubesolo. This command only needs to be run once.

```bash
make deps
```

--------------------------------

### Run Kubernetes API Server Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-apiserver.md

Starts the API Server service and blocks until shutdown. It waits for Kine readiness, generates configurations, and registers necessary components before starting the API server.

```go
func (s *service) Run(kineReadyCh chan struct{}) error
```

```go
ctx, cancel := context.WithCancel(context.Background())
apiService := apiserver.NewService(ctx, cancel, readyCh, "mynode", embedded)

// Start API server (waits for Kine)
if err := apiService.Run(kineReadyCh); err != nil {
    log.Fatal("API server failed:", err)
}
```

--------------------------------

### Display Version Information

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Show the KubeSolo version and build details, then exit. This flag does not take any value.

```bash
kubesolo --version
```

--------------------------------

### Run KubeSolo as Root

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Execute KubeSolo with root privileges to overcome permission issues. Addresses 'permission denied creating directory' for containerd.

```bash
sudo kubesolo
```

--------------------------------

### Get System Hostname

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Retrieves the system's hostname. This is used as the node name in Kubernetes.

```go
func GetHostname() string
```

--------------------------------

### Kubelet Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Provides functionality to start and manage the Kubelet service, which is responsible for running containers on a node.

```APIDOC
## Run Kubelet Service

### Description
Starts the kubelet service, which manages containers on the node and registers it with the API server.

### Method
`Run`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **apiServerReadyCh** (chan struct{}) - Required - Waits for API server ready before starting

### Returns
- `nil` if shut down gracefully
- `error` on fatal error

### Startup Steps
1. Waits for API server to be ready
2. Creates containerd client connection
3. Generates kubelet kubeconfig file
4. Configures kubelet flags for single-node operation
5. Sets cgroup driver (auto-detects cgroupv1 vs cgroupv2)
6. Starts kubelet
7. Registers node with API server
8. Signals readiness when node ready
9. Blocks until context cancelled

### Configuration
- **Container Runtime**: containerd (via socket)
- **CGroup Driver**: Detected (v1 or v2)
- **Cluster DNS**: 10.43.0.10
- **Pod CIDR**: 10.42.0.0/16

### Example
```go
ctx, cancel := context.WithCancel(context.Background())
kubeletService := kubelet.NewService(ctx, cancel, readyCh, &embedded)

if err := kubeletService.Run(apiServerReadyCh); err != nil {
    log.Fatal("Kubelet failed:", err)
}
```
```

--------------------------------

### Disable Local Storage

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

Example of how to disable the local storage provisioner using the --local-storage=false flag.

```bash
kubesolo --local-storage=false
```

--------------------------------

### Configure KubeSolo Logger

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Initializes the structured logging system using zerolog. Supports JSON output for production and pretty-printing for development.

```go
func ConfigureLogger()
```

--------------------------------

### Initialize Kubesolo Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Initializes system configuration, directories, and the embedded configuration struct. This function sets up logging, loads kernel modules, disables IPv6 if specified, detects the node IP, cleans stale state, and initializes the embedded configuration with all necessary paths.

```go
func (s *kubesolo) bootstrap()
```

```go
svc := &kubesolo{...}
svc.bootstrap()
// After bootstrap(), svc.embedded contains all paths
```

--------------------------------

### Check Directory Permissions for PKI

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Verify and adjust permissions for the KubeSolo data directory. Essential for resolving 'failed to generate full certificates' errors.

```bash
ls -la /var/lib/kubesolo/
chmod 755 /var/lib/kubesolo
```

--------------------------------

### Create Kubelet Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Constructs a new kubelet service instance. This is used to initialize the kubelet service before it is run.

```go
func NewService(
    ctx context.Context,
    cancel context.CancelFunc,
    kubeletReady chan<- struct{},
    embedded *types.Embedded,
) *service
```

--------------------------------

### Create Controller Manager Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kubernetes-services.md

Constructs a new controller manager service instance. Use this to initialize the service before running it.

```go
func NewService(
    ctx context.Context,
    cancel context.CancelFunc,
    controllerReady chan<- struct{},
    controllerDir string,
    embedded types.Embedded,
) *service
```

--------------------------------

### Check Kine Socket Existence

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Verify if the Kine socket file exists. This helps diagnose issues where Kine might not have started correctly.

```bash
ls -la /var/lib/kubesolo/kine/socket
```

--------------------------------

### Build All Supported musl Architectures

Source: https://github.com/portainer/kubesolo/blob/develop/README.md

Compiles musl-compatible static binaries for all architectures currently supported by the build system.

```bash
make build-all-musl
```

--------------------------------

### Kubesolo Service Readiness Channels

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-main.md

Defines and utilizes channels for coordinating service startup. Each service signals its readiness by sending a value to its respective channel, allowing other services to wait for their dependencies.

```go
var (
    containerdReadyCh = make(chan struct{})
    kineReadyCh       = make(chan struct{})
    apiServerReadyCh  = make(chan struct{})
    kubeletReadyCh    = make(chan struct{})
    controllerReadyCh = make(chan struct{})
    kubeproxyReadyCh  = make(chan struct{})
)
```

```go
// In service startup
readyCh <- struct{}{}

// In main startup loop
<-readyCh
```

--------------------------------

### Check API Server Listening

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/error-handling.md

Verify if the API server is listening on the expected port. This helps confirm if the API server process has started successfully.

```bash
netstat -tlnp | grep 6443
```

--------------------------------

### Local Path Provisioner Storage Configuration

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-components.md

The local-path-provisioner configuration specifies the base directory for storing volumes and an optional shared path for multi-node setups.

```yaml
paths:
  - /opt/local-path-provisioner/data
sharedPath: <sharedPath>
```

--------------------------------

### Create Air-gapped Environment Directory

Source: https://github.com/portainer/kubesolo/blob/develop/docs/configuration/registry.md

Creates the directory for configuring registries in an air-gapped environment using the `_default` catch-all.

```bash
mkdir -p /var/lib/kubesolo/containerd/registry/_default
```

--------------------------------

### Profile Heap Usage

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Use the go tool to profile heap usage via the pprof server. This command connects to the running pprof server and fetches heap data.

```bash
go tool pprof http://localhost:6060/debug/pprof/heap
```

--------------------------------

### Verify Kubesolo File Paths

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/configuration.md

Check the contents of the /var/lib/kubesolo/ directory to ensure all necessary directories and certificates have been created. This is crucial for troubleshooting.

```bash
ls -la /var/lib/kubesolo/
# Shows all created directories and certificates
```

--------------------------------

### Run Kine Service

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/api-kine.md

Starts the Kine service and blocks until the context is cancelled or a fatal error occurs. Handles database repair, gRPC server startup, and readiness signaling.

```go
ctx, cancel := context.WithCancel(context.Background())
kineService := kine.NewService(ctx, cancel, "/path/to/kine", readyCh, true)

if err := kineService.Run(); err != nil {
    log.Fatal("Kine service failed:", err)
}
```

--------------------------------

### Get KubeSolo Node IP Address

Source: https://github.com/portainer/kubesolo/blob/develop/_autodocs/internals.md

Detects and returns the system's primary IPv4 address on non-loopback interfaces. Falls back to 127.0.0.1 if no suitable interface is found.

```go
func GetNodeIP() (string, error)
```