{"id":39616999,"url":"https://github.com/bojanraic/loko","last_synced_at":"2026-01-18T08:20:07.360Z","repository":{"id":325798642,"uuid":"1100103837","full_name":"bojanraic/loko","owner":"bojanraic","description":"LoKO - Local Kubernetes Oasis","archived":false,"fork":false,"pushed_at":"2026-01-18T00:07:03.000Z","size":588,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T04:37:22.565Z","etag":null,"topics":["developer-tools","development","kubernetes","kubernetes-setup","local-development"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bojanraic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-19T21:01:51.000Z","updated_at":"2026-01-18T00:07:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bojanraic/loko","commit_stats":null,"previous_names":["bojanraic/loko"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/bojanraic/loko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanraic%2Floko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanraic%2Floko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanraic%2Floko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanraic%2Floko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bojanraic","download_url":"https://codeload.github.com/bojanraic/loko/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanraic%2Floko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","development","kubernetes","kubernetes-setup","local-development"],"created_at":"2026-01-18T08:20:06.802Z","updated_at":"2026-01-18T08:20:07.302Z","avatar_url":"https://github.com/bojanraic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LoKO - Local Kubernetes Oasis - simplified Kubernetes development environments\n\n[![PyPI version](https://img.shields.io/pypi/v/loko-k8s.svg)](https://badge.fury.io/py/loko-k8s)\n[![Python Versions](https://img.shields.io/pypi/pyversions/loko-k8s.svg)](https://pypi.org/project/loko-k8s/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/bojanraic/loko/main/loko-logo.svg\" alt=\"LoKO Logo\" width=\"200\" height=\"200\"\u003e\n\u003c/div\u003e\n\nA Python CLI utility to manage local Kubernetes environments with Kind, providing simplified configuration management, version upgrades, DNS, wildcard certificates, local container registry, and extensive customization options.\n\n## Features\n\n- **Easy Setup**: Initialize local Kubernetes clusters with a single command\n- **Smart Version Management**: Upgrade component versions using loko-updater comments\n- **Automatic Backups**: Config files are automatically backed up before upgrades\n- **Custom Templates**: Use your own Jinja2 templates for configuration generation\n- **Extensive CLI Overrides**: Override any configuration value via command-line flags\n- **Built-in Local Registry**: Local container registry with TLS support\n- **Automatic HTTPS**: Built-in certificate management with mkcert\n- **Local DNS**: Automatic DNS configuration for local development\n- **Metrics \u0026 Monitoring**: Built-in metrics-server for resource monitoring and HPA support\n- **Comprehensive Status**: Detailed view of cluster resources with `loko status`\n- **Granular Workload Management**: List, deploy, and undeploy individual workloads with `loko workload`\n- **Advanced Node Scheduling**: Flexible node labeling and workload placement\n- **Registry Mirroring**: Automatic caching/mirroring of external registries (Docker Hub, Quay, etc.)\n- **Workload Presets**: Pre-configured settings for common workloads (MySQL, PostgreSQL, Valkey, etc.)\n- **Helm-based Deployment**: Deploy workloads from public repositories (groundhog2k, etc.)\n- **Centralized Helm Repos**: Define repositories once, reference everywhere\n- **Automatic Secrets Management**: Automatically generate, fetch and save workload credentials with deduplication\n- **Port Availability Checking**: Pre-flight validation ensures all required ports are available before cluster creation\n- **Smart Error Handling**: Clear, actionable error messages guide you to solutions\n\n## Breaking Changes in v0.1.0\n\n\u003e **Important for existing users**: The configuration schema has been restructured for better organization and clarity. If you have an existing `loko.yaml`, you'll need to regenerate it.\n\n### Migration Steps\n\n1. **Backup your existing config** (if you have customizations):\n   ```bash\n   cp loko.yaml loko.yaml.backup\n   ```\n\n2. **Regenerate the config**:\n   ```bash\n   loko config generate --force\n   ```\n\n3. **Re-apply your customizations** to the new config structure.\n\n### Key Schema Changes\n\n| Old Path | New Path |\n|----------|----------|\n| `local-ip` | `network.ip` |\n| `local-domain` | `network.domain` |\n| `local-dns-port` | `network.dns-port` |\n| `local-lb-ports` | `network.lb-ports` |\n| `use-apps-subdomain` | `network.subdomain.enabled` |\n| `apps-subdomain` | `network.subdomain.value` |\n| `provider` | `cluster.provider` |\n| `kubernetes` | `cluster.kubernetes` |\n| `nodes` | `cluster.nodes` |\n| `nodes.allow-scheduling-on-control-plane` | `cluster.nodes.scheduling.control-plane.allow-workloads` |\n| `nodes.internal-components-on-control-plane` | `cluster.nodes.scheduling.control-plane.isolate-internal-components` |\n| `run-workloads-on-workers-only` | `cluster.nodes.scheduling.workers.isolate-workloads` |\n| `internal-components` (list) | `internal-components` (dict with named components) |\n| `helm-repositories` | `workloads.helm-repositories` |\n\n## Prerequisites\n\n- Python 3.9 or higher\n- Docker\n- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)\n- [mkcert](https://github.com/FiloSottile/mkcert#installation) (for HTTPS certificates)\n- [Helm](https://helm.sh/docs/intro/install/)\n- [Helmfile](https://github.com/helmfile/helmfile#installation)\n- (optional) nss (for macOS) or libnss3-tools (for Linux) - needed for Firefox to trust mkcert certificates\n\n### Installing Prerequisites with Mise (Recommended)\n\n[Mise](https://mise.jdx.dev/) is the recommended way to install and manage CLI tools. Clone the repo and run `mise install` from the project root to install all prerequisites:\n\n```bash\ngit clone https://github.com/bojanraic/loko.git\ncd loko\nmise install  # Installs kind, helm, kubectl, mkcert, helmfile\n```\n\n## Installation\n\n### From PyPI (recommended)\n\nUsing pip:\n```bash\npip install loko-k8s\n```\n\nUsing uv:\n```bash\nuv tool install loko-k8s\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/bojanraic/loko.git\ncd loko\npip install -e .\n```\n\n### Using uv (for development)\n\n```bash\ngit clone https://github.com/bojanraic/loko.git\ncd loko\nuv sync\nuv run loko --help\n```\n\n## Quick Start\n\n1. Check prerequisites:\n   ```bash\n   loko check-prerequisites\n   ```\n\n2. Generate a default configuration:\n   ```bash\n   loko config generate\n   # Or use --minimal for a compact config without comments/disabled sections:\n   # loko config generate --minimal\n   ```\n\n3. Initialize your environment:\n   ```bash\n   loko init\n   ```\n\n4. Create the full environment:\n   ```bash\n   loko create\n   ```\n\n## Demo\n\nWatch Loko in action - see the complete workflow from installation to cluster validation:\n\n[![asciicast](https://asciinema.org/a/ZU2gJvGoCxTkJeYgGiFdpwe9k.svg)](https://asciinema.org/a/ZU2gJvGoCxTkJeYgGiFdpwe9k)\n\n\n**Demo highlights:**\n\n- Installing loko\n- Generating a default configuration with auto-detected IP\n- Creating a local Kubernetes cluster with Kind\n- Deploying workloads (Traefik, container registry, PostgreSQL) with Helm\n- Validating the cluster setup\n- Checking environment status\n- Upgrading component versions\n- Viewing workload secrets \u0026 connecting to PostgreSQL and test application\n- Stopping and starting environment\n- Installing shell completion (via `loko completion \u003cshell\u003e`)\n\n## Commands\n\n### Environment Lifecycle\n- `loko init` - Initialize environment (generate configs, setup certs, network)\n- `loko create` - Create full environment with complete workflow\n- `loko start` - Start all cluster containers\n- `loko stop` - Stop all cluster containers\n- `loko destroy` - Destroy the environment\n- `loko recreate` - Destroy and recreate the environment\n- `loko clean` - Destroy environment and remove all artifacts\n\n### Status \u0026 Validation\n- `loko status` - Show comprehensive environment status\n- `loko validate` - Validate the environment\n- `loko check-prerequisites` - Check if required tools are installed\n- `loko completion \u003cshell\u003e` - Generate shell completion script (bash, zsh, fish)\n\n### Configuration \u0026 Secrets\n- `loko config generate` - Generate default loko.yaml with auto-detected local IP (use `--minimal` for compact config without comments)\n- `loko config compact` - Compact existing config by removing comments and disabled sections\n- `loko config detect-ip` - Detect and display the local IP address\n- `loko config validate` - Validate configuration file structure and values\n- `loko config port-check` - Check availability of all configured ports\n- `loko config dns-check` - Check DNS configuration and resolution status\n- `loko config upgrade` - Upgrade component versions using loko-updater comments\n- `loko config helm-repo-add` - Add Helm repositories to config\n- `loko config helm-repo-remove` - Remove Helm repositories from config\n- `loko workload list` - List workloads and their status (with filtering options)\n- `loko workload deploy` - Deploy all or specific workloads\n- `loko workload undeploy` - Undeploy all or specific workloads\n- `loko secret fetch` - Fetch workload credentials from cluster\n- `loko secret show` - Display saved workload credentials\n- `loko registry status` - Show registry statistics and configuration\n- `loko registry list-repos` - List all repositories in the registry\n- `loko registry show-repo \u003cname\u003e` - Show details about a specific repository\n- `loko registry list-tags \u003cname\u003e` - List all tags for a repository\n\n## Checking Cluster Status\n\nUse the `status` command to get a comprehensive overview of your local Kubernetes environment:\n\n```bash\nloko status\n```\n\nThis will display:\n\n- **Cluster Status**: Overall health of the Kubernetes cluster\n- **Container Status**: Status of all related containers (nodes, DNS, etc.)\n- **Node Status**: List of all nodes with their roles and status\n- **DNS Status**: Status of the local DNS service\n\n## Version Management \u0026 Upgrades\n\n\u003e **Migration Note:** If you're upgrading from an earlier version of Loko that used `# renovate:` comments, you'll need to update them to `# loko-updater:`. A simple find-and-replace in your `loko.yaml` will do:\n\u003e ```bash\n\u003e sed -i '' 's/# renovate:/# loko-updater:/g' loko.yaml  # macOS\n\u003e sed -i 's/# renovate:/# loko-updater:/g' loko.yaml     # Linux\n\u003e ```\n\nLoko uses loko-updater comments in your configuration file to track and upgrade component versions. This approach allows you to:\n- Keep component versions up-to-date\n- Track version sources directly in your config\n- Automatically query Docker Hub and Helm repositories for latest versions\n\n### How It Works\n\nAdd loko-updater comments above the version fields in your `loko.yaml`:\n\n```yaml\ncluster:\n  kubernetes:\n    image: kindest/node\n    # loko-updater: datasource=docker depName=kindest/node\n    tag: v1.35.0\n\ninternal-components:\n  traefik:\n    # loko-updater: datasource=helm depName=traefik repositoryUrl=https://traefik.github.io/charts\n    version: \"38.0.2\"\n\nworkloads:\n  system:\n    - name: mysql\n      config:\n        chart: groundhog2k/mysql\n        # loko-updater: datasource=helm depName=mysql repositoryUrl=https://groundhog2k.github.io/helm-charts\n        version: 3.0.8\n```\n\n### Supported Datasources\n\n- **Docker Hub** (`datasource=docker`): Fetches latest tags from Docker Hub\n- **Helm Repositories** (`datasource=helm`): Fetches latest chart versions from Helm repos\n\n### Running Upgrades\n\n```bash\nloko config upgrade\n```\n\nThis will:\n1. Scan your config for loko-updater comments\n2. Query each datasource for the latest version (in parallel)\n3. Create a backup (`loko-prev.yaml`)\n4. Update versions in place\n5. Show a summary of changes\n\n**Performance:** Helm repository checks are performed in parallel, significantly reducing upgrade time when checking multiple repositories.\n\nExample output:\n```\nUpgrading component versions...\n\nUpdates found:\n  kindest/node: v1.34.0 → v1.35.0\n  traefik: 37.3.0 → 38.0.2\n  mysql: 3.0.7 → 3.0.8\n\nBackup created: loko-prev.yaml\nUpdated 3 version(s) in loko.yaml\n\nTotal fetch time: 8.18s (Helm ops: 8.18s)\n```\n\n### Restoring from Backup\n\nIf an upgrade causes issues, easily revert:\n\n```bash\nmv loko-prev.yaml loko.yaml\n```\n\n## Managing Helm Repositories\n\nLoko provides commands to manage Helm repositories in your configuration file:\n\n### Adding Repositories\n\n```bash\n# Add a single repository\nloko config helm-repo-add \\\n  --helm-repo-name bitnami \\\n  --helm-repo-url https://charts.bitnami.com/bitnami\n\n# Add multiple repositories at once\nloko config helm-repo-add \\\n  --helm-repo-name bitnami --helm-repo-url https://charts.bitnami.com/bitnami \\\n  --helm-repo-name jetstack --helm-repo-url https://charts.jetstack.io\n```\n\n### Removing Repositories\n\n```bash\n# Remove a single repository\nloko config helm-repo-remove --helm-repo-name bitnami\n\n# Remove multiple repositories\nloko config helm-repo-remove \\\n  --helm-repo-name bitnami \\\n  --helm-repo-name jetstack\n```\n\n### Using Added Repositories\n\nAdded repositories appear in your config and can be referenced:\n\n```yaml\nenvironment:\n  workloads:\n    helm-repositories:\n      - name: bitnami\n        url: https://charts.bitnami.com/bitnami/\n\n    user:\n      - name: my-app\n        config:\n          repo:\n            ref: bitnami          # Reference the added repository\n          chart: bitnami/nginx\n          version: 1.0.0\n```\n\n## Managing Workload Credentials\n\nWorkload credentials (database passwords, etc.) are automatically generated during deployment:\n\n```bash\n# Fetch credentials from the cluster\nloko secret fetch\n\n# Display saved credentials\nloko secret show\n```\n\n\u003e **Tip**: `loko secret show` will automatically trigger a `fetch` if the secrets file doesn't exist yet.\n\nCredentials are saved locally to:\n```\n\u003cbase-dir\u003e/\u003cenv-name\u003e/workload-secrets.txt\n```\n\nExample workloads with auto-generated credentials:\n- MySQL (root password)\n- PostgreSQL (postgres password)\n- MongoDB (root password)\n- RabbitMQ (admin password)\n- Valkey (default password)\n\n## Directory Structure\n\nWhen you run `loko init` or `loko create`, a `.loko` directory is created (configurable via `base-dir`).\n\n```\n.\n├── loko.yaml                       # Main configuration file\n├── .loko/                          # Default directory for cluster data and configs\n│   └── \u003cenv-name\u003e/                 # Environment-specific directory (e.g. dev-me)\n│       ├── certs/                  # TLS certificates and keys\n│       │   ├── rootCA.pem          # Root CA certificate\n│       │   ├── \u003cdomain\u003e.pem        # Domain certificate\n│       │   ├── \u003cdomain\u003e-key.pem    # Domain private key\n│       │   └── \u003cdomain\u003e-combined.pem  # Combined cert and key\n│       ├── config/                 # Generated configuration files\n│       │   ├── cluster.yaml        # KinD cluster configuration\n│       │   ├── containerd/         # Container runtime config (per registry)\n│       │   │   ├── cr.dev.me/hosts.toml\n│       │   │   └── docker.io/hosts.toml\n│       │   ├── dnsmasq.conf        # Local DNS configuration\n│       │   └── helmfile.yaml       # Helm releases definition\n│       ├── logs/                   # Kubernetes node logs\n│       ├── storage/                # Persistent volume data\n│       ├── kubeconfig              # Cluster access configuration\n│       └── workload-secrets.txt    # Generated workload credentials\n```\n\n\u003e **Note**: The `.loko` directory is git-ignored by default.\n\n## Workload Management\n\nLoko permits granular control over your workloads through the `workload` command group.\n\n### Listing Workloads\n\nView all enabled workloads, their type, namespace, and current status:\n\n```bash\nloko workload list\n```\n\nFilter by type or status:\n```bash\nloko workload list --all       # All workloads including disabled\nloko workload list --user      # Only enabled user workloads\nloko workload list --system    # Only enabled system workloads\nloko workload list --internal  # Only enabled internal components (Traefik, Registry, etc.)\nloko workload list --disabled  # Only disabled workloads\nloko workload list --system --disabled  # Disabled system workloads only\n```\n\n### Deploying and Undeploying\n\nDeploy or undeploy specific workloads:\n\n```bash\n# Deploy all user and system workloads\nloko workload deploy\n\n# Deploy a specific workload\nloko workload deploy mongodb\n\n# Undeploy a specific workload\nloko workload undeploy garage\n\n# Include internal workloads\nloko workload deploy --internal\n```\n\nThe `deploy` and `undeploy` commands default to targeting **user** and **system** workloads. Use `--all` or specific type flags to include internal components.\n\n\u003e **Note**: Selective deployment uses `helmfile --selector` under the hood.\n\n### Workload Types and DNS Structure\n\n1. **System Workloads** (`workload.network.domain`):\n   - Core infrastructure workloads (databases, message queues, etc.)\n   - Direct DNS resolution (e.g., `mysql.dev.me`, `postgres.dev.me`)\n\n2. **User Workloads** (`workload.network.subdomain.value.network.domain`):\n   - Custom applications and workloads\n   - Either under subdomain (`myapp.apps.dev.me`) or direct domain (`myapp.dev.me`)\n   - Configurable via `network.subdomain.enabled` setting\n\n3. **Internal Components**:\n   - Registry (e.g., `cr.dev.me`)\n   - Traefik ingress controller\n   - DNS service (dnsmasq)\n   - Metrics server (optional)\n\n### Accessing Workloads\n\nOnce the environment is running, workloads are accessible through:\n\n1. **Direct Port Access**:\n   ```bash\n   # Example for PostgreSQL\n   psql -h localhost -p 5432 -U postgres\n   ```\n\n2. **Domain Names**:\n   ```bash\n   # Example for system workload\n   psql -h postgres.dev.me -U postgres\n   ```\n\n3. **Workload Credentials**:\n   - Passwords are automatically generated and stored in `\u003cbase-dir\u003e/\u003cenv-name\u003e/workload-secrets.txt`\n   - Or fetch them with: `loko secret show`\n\n### Using the Local Container Registry\n\nThe environment includes a local container registry accessible at `\u003cregistry.name\u003e.\u003cnetwork.domain\u003e`.\n\n1. **Push Images**:\n   ```bash\n   docker tag myapp:latest cr.dev.me/myapp:latest\n   docker push cr.dev.me/myapp:latest\n   ```\n\n2. **Use in Kubernetes**:\n   ```yaml\n   image: cr.dev.me/myapp:latest\n   ```\n\n## Node Scheduling and Workload Placement\n\nThe environment supports advanced node scheduling configurations to separate infrastructure and application workloads.\n\n### Node Labels\n\nConfigure custom labels in `loko.yaml`:\n\n```yaml\ncluster:\n  nodes:\n    labels:\n      control-plane:\n        tier: \"infrastructure\"\n      worker:\n        tier: \"application\"\n```\n\n### Scheduling Configuration\n\nControl workload placement with the scheduling section:\n\n```yaml\ncluster:\n  nodes:\n    scheduling:\n      control-plane:\n        allow-workloads: true              # Allow user/system workloads on control-plane\n        isolate-internal-components: true  # Force Traefik/registry to control-plane only\n      workers:\n        isolate-workloads: true            # Force user/system workloads to workers only\n```\n\n## OCI Registry and Helm Chart Validation\n\nLoko includes validation workflows for testing OCI registry functionality.\n\nRun validation with:\n```bash\nloko validate\n```\n\nThis runs a comprehensive check including:\n1. Cluster status and node readiness\n2. DNS service health\n3. System pods status\n4. Kubectl connectivity\n5. **Registry \u0026 TLS Validation**: Builds a test image, pushes to local registry, deploys a test app, and verifies connectivity.\n\n### Inspecting the Registry\n\nUse the `registry` command group to inspect and manage the local container registry:\n\n```bash\n# Show registry statistics and configuration\nloko registry status\n\n# List all repositories (local and mirrored)\nloko registry list-repos\n\n# Show details about a specific repository\nloko registry show-repo myapp\nloko registry show-repo docker.io/library/nginx\n\n# List all tags for a repository\nloko registry list-tags myapp\n```\n\nWhen mirroring is enabled, images pulled through the cluster are cached in the local registry. Use `list-repos` to verify mirroring is working.\n\n## Configuration\n\nThe environment is configured through `loko.yaml`. Generate a default one with `loko config generate`.\n\n### Schema Structure\n\n```yaml\nenvironment:\n  # General settings\n  name: string                    # Name of the environment\n  base-dir: string                # Base directory for storage\n  expand-env-vars: boolean        # Whether to expand OS and loko variables\n\n  # Cluster configuration\n  cluster:\n    provider:\n      name: string                # Provider name (currently only \"kind\" supported)\n      runtime: string             # Container runtime (docker or podman)\n\n    kubernetes:\n      api-port: integer           # API server port\n      image: string               # Node image\n      tag: string                 # Node image tag\n\n    nodes:\n      servers: integer            # Number of control-plane nodes\n      workers: integer            # Number of worker nodes\n      scheduling:\n        control-plane:\n          allow-workloads: boolean\n          isolate-internal-components: boolean\n        workers:\n          isolate-workloads: boolean\n      labels:                     # Optional custom node labels\n        control-plane: {}\n        worker: {}\n\n  # Network configuration\n  network:\n    ip: string                    # Local IP for DNS resolution\n    domain: string                # Domain name\n    dns-port: integer             # DNS resolver port (default 53)\n    subdomain:\n      enabled: boolean            # Use subdomain for user apps\n      value: string               # Subdomain value (e.g., \"apps\")\n    lb-ports: array               # Load balancer ports [80, 443]\n\n  # Registry configuration\n  registry:\n    name: string                  # Registry name (e.g., \"cr\")\n    storage:\n      size: string                # PVC size (e.g., \"10Gi\")\n    mirroring:\n      enabled: boolean\n      sources: array              # List of mirror sources\n\n  # Internal components (infrastructure)\n  internal-components:\n    traefik:\n      version: string\n    zot:\n      version: string\n    dnsmasq:\n      version: string\n    metrics-server:\n      version: string\n      enabled: boolean            # Only metrics-server is optional\n\n  # Workload configuration\n  workloads:\n    use-presets: boolean          # Whether to use workload presets\n    helm-repositories: array      # Centralized Helm repo definitions\n    system: array                 # List of system workloads\n    user: array                   # List of user-defined workloads\n```\n\n### CLI Overrides\n\nLoko provides extensive CLI options to override almost any configuration value during initialization:\n\n```bash\nloko init --name my-cluster --workers 3 --registry-storage 50Gi --no-schedule-on-control\n```\n\nSee `loko init --help` for all available overrides.\n\n### Custom DNS Port\n\nLoko runs a lightweight DNS container on your machine so that services such as `postgres.dev.me` resolve locally. By default it binds to the standard DNS port 53, but some hosts already listen on that port. If you need to avoid a conflict, set `network.dns-port` in `loko.yaml` (or pass `--dns-port` to `loko init`). Loko will start the DNS container on the specified port and automatically update the `/etc/resolver/\u003cdomain\u003e` entry so lookups continue to work.\n\n## Troubleshooting\n\n1. **DNS Resolution Issues**\n   - Run DNS diagnostics: `loko config dns-check`\n   - Verify local DNS container is running: `loko status`\n   - Check DNS configuration: `cat /etc/resolver/\u003cyour-domain\u003e`\n\n2. **Certificate Issues**\n   - Regenerate certificates: `loko init` (will re-run certificate setup)\n   - Verify cert location: `ls \u003cbase-dir\u003e/\u003cenv-name\u003e/certs/`\n\n3. **Workload Access Issues**\n   - Validate environment: `loko validate`\n   - Verify ingress: `kubectl get ingress -A`\n   - Check credentials: `loko secret show`\n\n4. **OCI Registry Issues**\n   - Test registry connectivity: `docker pull cr.dev.me/test:latest`\n   - Run validation: `loko validate`\n\n5. **Version Upgrade Issues**\n   - Restore from backup: `mv loko-prev.yaml loko.yaml`\n   - Check loko-updater comment syntax in config file\n\n6. **Port Conflicts**\n   - Check what's using a port: `sudo lsof -i :53` (macOS) or `sudo netstat -tlnp | grep :53` (Linux)\n   - Change the DNS port in config: `network.dns-port: 5353`\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/bojanraic/loko.git\ncd loko\nuv sync\nuv run loko --help\n```\n\n### Running Tests\n\n```bash\n# Run all unit tests\nuv run pytest tests/ --ignore=tests/integration\n\n# Run with verbose output\nuv run pytest tests/ -v --ignore=tests/integration\n```\n\n### Code Quality\n\n```bash\nuv run ruff check loko/\nuv run ruff format loko/\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbojanraic%2Floko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbojanraic%2Floko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbojanraic%2Floko/lists"}