From 9998bc86a0be5e9caba299056b9ec919fd80db1e Mon Sep 17 00:00:00 2001 From: Eddie Wassef Date: Mon, 26 Jan 2026 09:40:15 -0600 Subject: [PATCH 1/3] Revamp documentation for Vega CLI and workflows Updated all major documentation files to reflect the new Vega CLI naming, commands, and workflows. Added detailed instructions for installation, development setup, troubleshooting, cluster creation, management, and contribution guidelines. Improved clarity, structure, and completeness of docs to support new features and user onboarding. --- ReadMe.md | 105 +++++++------- docs/contribution/development-setup.md | 109 ++++++++++++--- docs/contribution/guidelines.md | 35 +++-- docs/debugging/troubleshooting.md | 132 +++++++++++++++--- docs/installation/getting-started.md | 149 +++++++++++++------- docs/usage/command-reference.md | 185 +++++++++++++++++++++---- docs/usage/creating-clusters.md | 68 +++++++-- docs/usage/managing-clusters.md | 122 +++++++++++++--- 8 files changed, 699 insertions(+), 206 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 7497c81..c6b9213 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -4,85 +4,82 @@ VDK is a Command Line Interface (CLI) tool designed to help developers quickly and securely set up local Kubernetes clusters using [KinD](https://kind.sigs.k8s.io/). It simplifies the process of creating clusters with varying configurations (versions, node counts) to assist in building and testing applications for platforms like Vega. -[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) - +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) ## Overview -Building and testing applications designed for Kubernetes often requires a realistic cluster environment. VDK streamlines the setup of local clusters via KinD, providing commands to: +Building and testing applications designed for Kubernetes often requires a realistic cluster environment. VDK streamlines the setup of local clusters via KinD, providing: -* Create single or multi-node Kubernetes clusters. -* Specify desired Kubernetes versions. -* Manage the lifecycle of these local clusters (list, delete). -* Easily integrate with `kubectl`. +- Single or multi-node Kubernetes clusters +- Configurable Kubernetes versions +- Local container registry (Zot) for image storage +- TLS-enabled reverse proxy (nginx) for secure access +- GitOps with Flux CD +- Easy cluster lifecycle management This tool is particularly useful for developers working on the Vega platform, enabling consistent and reproducible development environments. -## Installation - -For detailed installation instructions for your operating system, please refer to the **[Getting Started Guide](./docs/installation/getting-started.md)**. +## Quick Start -**Prerequisites:** +1. **Install Devbox:** -* [Docker](https://docs.docker.com/get-docker/) -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (Recommended for interacting with clusters) + ```bash + curl -fsSL https://get.jetify.com/devbox | bash + ``` -*For development prerequisites (Devbox/Nix), see the [Getting Started Guide](./docs/installation/getting-started.md).* +2. **Clone and enter the repository:** -## Quick Start + ```bash + git clone https://github.com/ArchetypicalSoftware/VDK.git + cd VDK + devbox shell + ``` -1. **Create a default cluster:** - ```bash - vdk create cluster - ``` - *(This may take a few minutes)* +3. **Initialize the environment:** -2. **Verify cluster access:** - ```bash - kubectl cluster-info --context kind-kind - ``` + ```bash + vega init + ``` -3. **Delete the cluster:** - ```bash - vdk delete cluster - ``` + This creates the registry, reverse proxy, and a default cluster. -## Usage +4. **Verify cluster access:** -For comprehensive usage details, examples, and command references, please see the **Usage Documentation**: + ```bash + kubectl cluster-info --context kind-vdk + ``` -* **[Creating Clusters](./docs/usage/creating-clusters.md)** -* **[Managing Clusters](./docs/usage/managing-clusters.md)** -* **[Command Reference](./docs/usage/command-reference.md)** +5. **When done, remove the cluster:** -## Contributing + ```bash + vega remove cluster + ``` -We welcome contributions! Please read our **[Contribution Guidelines](./docs/contribution/guidelines.md)** and **[Development Setup](./docs/contribution/development-setup.md)** guides to get started. +## Configuration -## Debugging & Troubleshooting +If port 443 is already in use, set a different port for the reverse proxy: -If you encounter issues while using VDK, consult the **[Troubleshooting Guide](./docs/debugging/troubleshooting.md)**. +```bash +export REVERSE_PROXY_HOST_PORT=8443 +``` -## License +## Documentation -This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details. *(Ensure a LICENSE file exists)* +| Topic | Description | +|-------|-------------| +| [Getting Started](./docs/installation/getting-started.md) | Installation and setup | +| [Creating Clusters](./docs/usage/creating-clusters.md) | How to create clusters | +| [Managing Clusters](./docs/usage/managing-clusters.md) | Cluster lifecycle management | +| [Command Reference](./docs/usage/command-reference.md) | Complete command documentation | +| [Troubleshooting](./docs/debugging/troubleshooting.md) | Common issues and solutions | -## Getting Started +## Contributing -- Install DevBox +We welcome contributions! Please read our guides: -``` - curl -fsSL https://get.jetify.com/devbox | bash -``` -- Clone the repository `git clone https://github.com/ArchetypicalSoftware/VDK.git` -- Start DevBox session in the cloned repository -``` - devbox shell -``` -- Run `vega --help` to see the available commands +- [Contribution Guidelines](./docs/contribution/guidelines.md) +- [Development Setup](./docs/contribution/development-setup.md) -### Configuration options +## License -If you already have a process listening on your host on port 443, you will have issues with the vega reverse proxy. -You can either stop the existing process or change the port by defining the environment variable `REVERSE_PROXY_HOST_PORT`. -The default port is 443. +This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details. diff --git a/docs/contribution/development-setup.md b/docs/contribution/development-setup.md index f8a6ba7..b22168c 100644 --- a/docs/contribution/development-setup.md +++ b/docs/contribution/development-setup.md @@ -1,34 +1,107 @@ # Development Setup -Setting up your environment to contribute to VDK. +Setting up your environment to contribute to Vega. ## Prerequisites -- [Go](https://go.dev/doc/install) (Specify required version, e.g., 1.19+) -- [Docker](https://docs.docker.com/get-docker/) -- [Make](https://www.gnu.org/software/make/) (Optional, if using Makefiles) -- [Git](https://git-scm.com/) +- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) +- [Docker](https://docs.docker.com/get-docker/) +- [Git](https://git-scm.com/) +- [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) (Kubernetes in Docker) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + +### Recommended: Using Devbox + +For a reproducible development environment, use [Devbox](https://www.jetpack.io/devbox/docs/): + +1. Install Devbox: + + ```bash + curl -fsSL https://get.jetify.com/devbox | bash + ``` + +2. Start a Devbox shell in the repository: + + ```bash + devbox shell + ``` + +This automatically sets up all required dependencies. ## Building from Source -1. Clone the repository (or your fork). -2. Navigate to the project directory. -3. Run the build command: +1. Clone the repository (or your fork): - ```bash - go build -o vdk ./cmd/vdk - # Or, if using Make: - # make build - ``` + ```bash + git clone https://github.com/ArchetypicalSoftware/VDK.git + cd VDK + ``` + +2. Navigate to the CLI project: + + ```bash + cd cli/src/Vdk + ``` + +3. Build the project: + + ```bash + dotnet build + ``` + +4. Run the CLI: + + ```bash + dotnet run -- --help + ``` ## Running Tests +From the repository root: + ```bash -go test ./... -# Or, if using Make: -# make test +cd cli +dotnet test +``` + +Or run specific tests: + +```bash +dotnet test --filter "FullyQualifiedName~YourTestName" +``` + +## Publishing + +To create a self-contained executable: + +```bash +cd cli/src/Vdk +dotnet publish -c Release +``` + +The output will be in `bin/Release/net10.0/publish/`. + +## Project Structure + +``` +VDK/ +├── cli/ +│ └── src/ +│ └── Vdk/ +│ ├── Commands/ # CLI command implementations +│ ├── Services/ # Business logic and integrations +│ ├── Models/ # Data models +│ ├── Constants/ # Configuration constants +│ ├── Certs/ # TLS certificates +│ └── ConfigMounts/ # Container configuration files +├── docs/ # Documentation +└── clusters/ # Flux GitOps configurations ``` -## Linting +## Key Technologies -*(Instructions for running linters, e.g., `golangci-lint`)* +- **System.CommandLine**: CLI framework +- **KubeOps.KubernetesClient**: Kubernetes API client +- **Docker.DotNet**: Docker API client +- **YamlDotNet**: YAML serialization +- **Flux CD**: GitOps toolkit diff --git a/docs/contribution/guidelines.md b/docs/contribution/guidelines.md index 26eea74..ee40d41 100644 --- a/docs/contribution/guidelines.md +++ b/docs/contribution/guidelines.md @@ -4,19 +4,34 @@ We welcome contributions to the Vega Development Kit (VDK)! ## How to Contribute -1. **Fork the Repository:** Start by forking the main VDK repository. -2. **Clone your Fork:** Clone your forked repository to your local machine. -3. **Create a Branch:** Create a new branch for your feature or bug fix (`git checkout -b feature/your-feature-name` or `bugfix/issue-number`). -4. **Make Changes:** Implement your changes and add relevant tests. -5. **Run Tests:** Ensure all tests pass. -6. **Commit Changes:** Commit your changes with clear and descriptive messages. -7. **Push to Your Fork:** Push your changes to your forked repository. -8. **Open a Pull Request:** Open a pull request against the main VDK repository's `main` branch. +1. **Fork the Repository:** Start by forking the main VDK repository. +2. **Clone your Fork:** Clone your forked repository to your local machine. +3. **Create a Branch:** Create a new branch for your feature or bug fix (`git checkout -b feature/your-feature-name` or `bugfix/issue-number`). +4. **Make Changes:** Implement your changes and add relevant tests. +5. **Run Tests:** Ensure all tests pass with `dotnet test`. +6. **Commit Changes:** Commit your changes with clear and descriptive messages. +7. **Push to Your Fork:** Push your changes to your forked repository. +8. **Open a Pull Request:** Open a pull request against the main VDK repository's `main` branch. ## Code Style -*(Specify Go formatting standards, linting tools used, etc.)* +- Follow standard C# conventions and .NET naming guidelines +- Use nullable reference types (`#nullable enable`) +- Prefer async/await for I/O operations +- Keep methods focused and single-purpose +- Add XML documentation for public APIs + +## Testing + +- Add unit tests for new functionality +- Ensure existing tests pass before submitting +- Run tests with: `dotnet test` ## Reporting Bugs -Please open an issue on the GitHub repository, providing detailed steps to reproduce the bug. +Please [open an issue](https://github.com/ArchetypicalSoftware/VDK/issues) on the GitHub repository, providing: + +- Steps to reproduce the bug +- Expected behavior +- Actual behavior +- Environment details (OS, .NET version, Docker version) diff --git a/docs/debugging/troubleshooting.md b/docs/debugging/troubleshooting.md index ed28d2a..7b4da98 100644 --- a/docs/debugging/troubleshooting.md +++ b/docs/debugging/troubleshooting.md @@ -1,36 +1,122 @@ -# Troubleshooting VDK Issues +# Troubleshooting Vega Issues Common issues and how to resolve them. ## Cluster Creation Fails -* **Check Docker:** Ensure Docker Desktop or Docker Engine is running. -* **Check Resources:** KinD requires sufficient RAM and CPU. Check Docker's resource limits. -* **Examine KinD Logs:** VDK uses KinD under the hood. You can often find more detailed logs using KinD's export functionality: - ```bash - kind export logs --name ./kind-logs - ``` - Replace `` with the name of the cluster that failed (or `kind` if default). -* **Network Issues:** Firewalls or VPNs can sometimes interfere with KinD's networking. +- **Check Docker:** Ensure Docker Desktop or Docker Engine is running. +- **Check Resources:** KinD requires sufficient RAM and CPU. Check Docker's resource limits. +- **Examine KinD Logs:** Vega uses KinD under the hood. You can find detailed logs using: -## Cannot Connect to Cluster (`kubectl` errors) + ```bash + kind export logs --name ./kind-logs + ``` -* **Verify Kubeconfig:** Ensure `kubectl` is using the correct context. Run `kubectl config current-context`. It should point to `kind-`. -* **Check Cluster Status:** Use `vdk get clusters` to see if the cluster is running. -* **Check `kubectl` Proxy Settings:** Ensure no conflicting proxy settings are interfering. + Replace `` with the name of the cluster that failed (or `vdk` for the default). +- **Network Issues:** Firewalls or VPNs can sometimes interfere with KinD's networking. +- **KinD Version Mismatch:** If you get version-related errors, update the version info: -## VDK Command Not Found + ```bash + vega update kind-version-info + ``` -* Ensure the VDK binary's location is in your system's `PATH` environment variable. -* Verify the installation completed successfully. +## Cannot Connect to Cluster (kubectl errors) + +- **Verify Kubeconfig:** Ensure `kubectl` is using the correct context: + + ```bash + kubectl config current-context + ``` + + It should show `kind-`. +- **Check Cluster Status:** Use `vega list clusters` to see if the cluster exists. +- **Check Container Status:** Verify the cluster containers are running: + + ```bash + docker ps --filter name= + ``` + +- **Check kubectl Proxy Settings:** Ensure no conflicting proxy settings are interfering. + +## Vega Command Not Found + +- Ensure the Vega binary's location is in your system's `PATH` environment variable. +- If using Devbox, make sure you're in a `devbox shell` session. +- Verify the installation completed successfully. + +## Registry Issues + +If the container registry isn't working: + +- **Check if running:** + + ```bash + docker ps --filter name=vega-registry + ``` + +- **Check registry logs:** + + ```bash + docker logs vega-registry + ``` + +- **Recreate the registry:** + + ```bash + vega remove registry + vega create registry + ``` + +## Reverse Proxy Issues + +If the nginx reverse proxy isn't routing correctly: + +- **Check if running:** + + ```bash + docker ps --filter name=vega-proxy + ``` + +- **Check proxy logs:** + + ```bash + docker logs vega-proxy + ``` + +- **Port conflicts:** If port 443 is in use, set a different port: + + ```bash + export REVERSE_PROXY_HOST_PORT=8443 + ``` + +- **Regenerate configuration:** + + ```bash + vega update clusters + ``` + +## Certificate Issues + +If TLS certificates are expired or mismatched: + +- **Update certificates in all clusters:** + + ```bash + vega update clusters --verbose + ``` + +- **Check certificate files exist:** + - `Certs/fullchain.pem` + - `Certs/privkey.pem` ## Reporting Issues -If you can't resolve the issue, please [open an issue](link-to-issues-page) on GitHub, providing: +If you can't resolve the issue, please [open an issue](https://github.com/ArchetypicalSoftware/VDK/issues) on GitHub, providing: -* VDK version (`vdk --version`) -* Operating System -* Docker version -* Command run -* Full output/error message -* Steps to reproduce +- Vega version (`vega --version`) +- Operating System +- Docker version (`docker --version`) +- KinD version (`kind --version`) +- Command run +- Full output/error message +- Steps to reproduce diff --git a/docs/installation/getting-started.md b/docs/installation/getting-started.md index c64df1d..7bf0ca3 100644 --- a/docs/installation/getting-started.md +++ b/docs/installation/getting-started.md @@ -1,73 +1,124 @@ -# Getting Started with VDK +# Getting Started with Vega This guide covers the installation and setup process for the Vega Development Kit (VDK) CLI and its dependencies. ## Core Prerequisites -These are required to run VDK and the KinD clusters it creates: +These are required to run Vega and the KinD clusters it creates: -* **[Docker](https://docs.docker.com/get-docker/)**: VDK uses KinD (Kubernetes in Docker), so a working Docker installation (Docker Desktop or Docker Engine) is essential. -* **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)**: The Kubernetes command-line tool, used to interact with your clusters. +- **[Docker](https://docs.docker.com/get-docker/)**: Vega uses KinD (Kubernetes in Docker), so a working Docker installation (Docker Desktop or Docker Engine) is essential. +- **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)**: The Kubernetes command-line tool, used to interact with your clusters. +- **[KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)**: Kubernetes in Docker, used to create local clusters. -## Development Environment Prerequisites (Using Devbox/Nix) +## Quick Start with Devbox -For contributing to VDK development or running it from source, we use [Devbox](https://www.jetpack.io/devbox/docs/) which leverages [Nix](https://nixos.org/download.html) for reproducible environments. +The easiest way to get started is using [Devbox](https://www.jetpack.io/devbox/docs/): -1. **Install Nix:** Follow the official [Nix installation guide](https://nixos.org/download.html). +1. **Install Devbox:** -2. **Install Devbox:** Follow the official [Devbox installation guide](https://www.jetpack.io/devbox/docs/installing_devbox/). + ```bash + curl -fsSL https://get.jetify.com/devbox | bash + ``` -3. **Environment Setup (One-time):** - * **GITHUB_VDK_TOKEN:** You might need a GitHub Personal Access Token (PAT) for accessing certain resources during development or build processes. Add it to your shell configuration (e.g., `.bashrc`, `.zshrc`): - ```bash - echo 'export GITHUB_VDK_TOKEN=""' >> ~/.your_shell_profile - # Example for bash: - # echo 'export GITHUB_VDK_TOKEN=""' >> ~/.bashrc - ``` - *Remember to source your profile (`source ~/.your_shell_profile`) or restart your terminal after adding the export.* +2. **Clone the repository:** - * **(Temporary) Add `.bin` to PATH:** While under development, you may need to manually add the local binary directory to your PATH: - ```bash - echo 'export PATH="$PATH://.bin"' >> ~/.your_shell_profile - # Example: - # echo 'export PATH="$PATH:/home/user/projects/VDK/.bin"' >> ~/.bashrc - ``` - *Source your profile again after adding this.* + ```bash + git clone https://github.com/ArchetypicalSoftware/VDK.git + cd VDK + ``` - * **Flux Secret:** Depending on the setup, you might need to create a Kubernetes secret in the `flux-system` namespace containing your `GITHUB_VDK_TOKEN`. (Details TBD). +3. **Start a Devbox shell:** -4. **macOS Sequoia/Corporate Proxy Certificate Issue:** - If you are using macOS Sequoia behind a corporate proxy (like Netskope) and encounter SSL errors (`SSL peer certificate or SSH remote key was not OK (60)`) when Nix downloads packages, you need to add your corporate certificates to Nix's trust store. Follow the steps outlined in [this Nix issue comment](https://github.com/NixOS/nix/issues/8081#issuecomment-1962419263): - - * Generate a combined certificate bundle: - ```bash - security export -t certs -f pemseq -k /Library/Keychains/System.keychain -o /tmp/certs-system.pem - security export -t certs -f pemseq -k /System/Library/Keychains/SystemRootCertificates.keychain -o /tmp/certs-root.pem - cat /tmp/certs-root.pem /tmp/certs-system.pem > /tmp/ca_cert.pem - sudo mv /tmp/ca_cert.pem /etc/nix/ - ``` - * Update `/etc/nix/nix.conf` (create it if it doesn't exist) and add: - ```ini - ssl-cert-file = /etc/nix/ca_cert.pem - ``` - * Restart the Nix daemon: - ```bash - sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist - sudo launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist - ``` + ```bash + devbox shell + ``` -## VDK Installation (Binary - Placeholder) +4. **Initialize Vega:** -*(Detailed steps will be added here based on the distribution method - e.g., package manager, binary download from releases)* + ```bash + vega init + ``` -## Verifying VDK Installation +This sets up the complete development environment including the registry, reverse proxy, and a default cluster. -Once VDK is installed (either via binary or built from source), verify it: +## Manual Installation + +If not using Devbox, ensure you have: + +- .NET 10 SDK +- Docker +- KinD +- kubectl +- Flux CLI + +Then build from source: + +```bash +cd cli/src/Vdk +dotnet build +dotnet run -- --help +``` + +## Environment Configuration + +### GitHub Token (Optional) + +For Flux GitOps integration, you may need a GitHub Personal Access Token: + +```bash +export GITHUB_VDK_TOKEN="" +``` + +Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) for persistence. + +### Reverse Proxy Port + +If port 443 is already in use on your system: + +```bash +export REVERSE_PROXY_HOST_PORT=8443 +``` + +## macOS Sequoia/Corporate Proxy Certificate Issue + +If you encounter SSL errors behind a corporate proxy (like Netskope), add your corporate certificates to Nix's trust store: + +1. Generate a combined certificate bundle: + + ```bash + security export -t certs -f pemseq -k /Library/Keychains/System.keychain -o /tmp/certs-system.pem + security export -t certs -f pemseq -k /System/Library/Keychains/SystemRootCertificates.keychain -o /tmp/certs-root.pem + cat /tmp/certs-root.pem /tmp/certs-system.pem > /tmp/ca_cert.pem + sudo mv /tmp/ca_cert.pem /etc/nix/ + ``` + +2. Update `/etc/nix/nix.conf`: + + ```ini + ssl-cert-file = /etc/nix/ca_cert.pem + ``` + +3. Restart the Nix daemon: + + ```bash + sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist + sudo launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist + ``` + +## Verifying Installation + +Once Vega is installed, verify it: + +```bash +vega --version +``` + +List available commands: ```bash -vdk --version +vega --help ``` ## Next Steps -Now that VDK is set up, learn how to [Create Clusters](../usage/creating-clusters.md). +Now that Vega is set up, learn how to [Create Clusters](../usage/creating-clusters.md). diff --git a/docs/usage/command-reference.md b/docs/usage/command-reference.md index 8c62b0c..cc76a08 100644 --- a/docs/usage/command-reference.md +++ b/docs/usage/command-reference.md @@ -1,48 +1,185 @@ -# VDK Command Reference +# Vega Command Reference -This is a comprehensive reference for all VDK commands. +This is a comprehensive reference for all Vega CLI commands. -## `vdk create cluster` +## Root Commands -Creates a new KinD cluster. +### `vega init` + +Initializes the complete Vega development environment. This command: +- Creates the reverse proxy (nginx) +- Creates the container registry (Zot) +- Creates a default KinD cluster + +**Usage:** +```bash +vega init +``` + +--- + +## Create Commands + +### `vega create cluster` + +Creates a new KinD cluster with Vega configuration. **Usage:** -`vdk create cluster [flags]` +```bash +vega create cluster [flags] +``` **Flags:** -* `--name string`: Name for the cluster (default: `kind`) -* `--version string`: Kubernetes version to use (e.g., `v1.25.3`). If not specified, uses KinD's default. -* `--config string`: Path to a KinD configuration file. -* `--nodes int`: Total number of nodes (control-plane + worker). -* `--control-planes int`: Number of control-plane nodes. -* `--wait duration`: Wait time for the control plane to be ready (default: `5m`). +| Flag | Alias | Default | Description | +|------|-------|---------|-------------| +| `--Name` | `-n` | `vdk` | Name for the cluster | +| `--ControlPlaneNodes` | `-c` | `1` | Number of control-plane nodes | +| `--Workers` | `-w` | `2` | Number of worker nodes | +| `--KubeVersion` | `-k` | `1.29` | Kubernetes API version | -*(Add other commands like `get`, `delete`, `version`, etc., as they are developed)* +**Example:** +```bash +vega create cluster --Name my-cluster --Workers 3 --KubeVersion 1.30 +``` -## `vdk get clusters` +### `vega create registry` -Lists existing KinD clusters managed by VDK. +Creates the Vega container registry (Zot) for local image storage. -## `vdk delete cluster` +**Usage:** +```bash +vega create registry +``` -Deletes a KinD cluster. +### `vega create proxy` -**Flags:** +Creates the Vega reverse proxy (nginx) for TLS termination. + +**Usage:** +```bash +vega create proxy +``` -* `--name string`: Name of the cluster to delete (default: `kind`) +### `vega create cloud-provider-kind` + +Creates a Cloud Provider KIND container that provisions load balancers for services in KinD clusters. + +**Usage:** +```bash +vega create cloud-provider-kind +``` -## `vdk get kubeconfig` +--- -Gets the kubeconfig path for a cluster. +## Remove Commands + +### `vega remove cluster` + +Removes a KinD cluster. + +**Usage:** +```bash +vega remove cluster [flags] +``` **Flags:** -* `--name string`: Name of the cluster (default: `kind`) +| Flag | Alias | Default | Description | +|------|-------|---------|-------------| +| `--Name` | `-n` | `vdk` | Name of the cluster to remove | + +**Example:** +```bash +vega remove cluster --Name my-cluster +``` + +### `vega remove registry` + +Removes the Vega container registry. + +**Usage:** +```bash +vega remove registry +``` + +### `vega remove proxy` + +Removes the Vega reverse proxy. + +**Usage:** +```bash +vega remove proxy +``` + +### `vega remove cloud-provider-kind` + +Removes the Cloud Provider KIND container. + +**Usage:** +```bash +vega remove cloud-provider-kind +``` + +--- + +## List Commands + +### `vega list clusters` + +Lists all VDK-managed KinD clusters. + +**Usage:** +```bash +vega list clusters +``` + +### `vega list kubernetes-versions` + +Lists available Kubernetes versions for the installed KinD version. + +**Usage:** +```bash +vega list kubernetes-versions +``` + +--- + +## Update Commands + +### `vega update kind-version-info` + +Updates the KinD version information cache. This maps KinD versions to available Kubernetes versions and enables support for new Kubernetes releases. + +**Usage:** +```bash +vega update kind-version-info +# or use the alias: +vega update k8s +``` + +### `vega update clusters` + +Updates cluster configurations including TLS certificates. This command: +- Checks all VDK clusters for outdated certificates +- Updates Vega-managed TLS secrets (`dev-tls` or annotated with `vega.dev/managed=true`) +- Restarts gateway deployments to pick up new certificates +- Regenerates nginx reverse proxy configuration + +**Usage:** +```bash +vega update clusters [flags] +``` + +**Flags:** -# `vdk create cloud-provider-kind` +| Flag | Alias | Description | +|------|-------|-------------| +| `--verbose` | `-v` | Enable verbose output for debugging | -Creates a cloud Provider KIND docker image which runs as a standalone binary in the local machine -and will connect to the Kind cluster and provision new Load balancer containers for the services. +**Example:** +```bash +vega update clusters --verbose +``` diff --git a/docs/usage/creating-clusters.md b/docs/usage/creating-clusters.md index 8da40e4..1d6dd9d 100644 --- a/docs/usage/creating-clusters.md +++ b/docs/usage/creating-clusters.md @@ -1,40 +1,84 @@ -# Creating KinD Clusters with VDK +# Creating KinD Clusters with Vega -This document explains how to create local Kubernetes clusters using VDK. +This document explains how to create local Kubernetes clusters using Vega. + +## Quick Start with Init + +The easiest way to get started is using the `init` command, which sets up everything you need: + +```bash +vega init +``` + +This creates: + +- The reverse proxy (nginx) for TLS termination +- The container registry (Zot) for local images +- A default KinD cluster ## Basic Cluster Creation -To create a default cluster: +To create a cluster with default settings: ```bash -vdk create cluster +vega create cluster ``` +This creates a cluster with: + +- 1 control-plane node +- 2 worker nodes +- Default Kubernetes version (1.29) + ## Specifying Cluster Name ```bash -vdk create cluster --name my-dev-cluster +vega create cluster --Name my-dev-cluster +# or using the alias +vega create cluster -n my-dev-cluster ``` ## Specifying Kubernetes Version ```bash -vdk create cluster --version v1.25.3 +vega create cluster --KubeVersion 1.30 +# or using the alias +vega create cluster -k 1.30 +``` + +To see available Kubernetes versions: + +```bash +vega list kubernetes-versions ``` ## Multi-Node Clusters -*(Details on creating clusters with multiple control-plane and worker nodes)* +Create clusters with multiple control-plane and worker nodes: ```bash -# Example (syntax TBD) -vdk create cluster --nodes 3 --control-planes 1 +# 3 control-plane nodes and 5 workers +vega create cluster --ControlPlaneNodes 3 --Workers 5 + +# Using aliases +vega create cluster -c 3 -w 5 ``` -## Using Configuration Files +## Combined Example -*(Details on using a KinD configuration file)* +Create a named cluster with specific configuration: ```bash -vdk create cluster --config path/to/kind-config.yaml +vega create cluster --Name production-test --ControlPlaneNodes 1 --Workers 4 --KubeVersion 1.30 ``` + +## What Happens During Cluster Creation + +When you create a cluster, Vega: + +1. **Ensures infrastructure exists**: Creates the reverse proxy and registry if not present +2. **Validates versions**: Checks that your KinD version supports the requested Kubernetes version +3. **Generates KinD config**: Creates a cluster configuration with proper containerd settings +4. **Creates the cluster**: Invokes KinD to create the actual cluster +5. **Bootstraps Flux**: Sets up GitOps with Flux CD +6. **Configures routing**: Updates the nginx reverse proxy to route traffic to the cluster diff --git a/docs/usage/managing-clusters.md b/docs/usage/managing-clusters.md index 77bc9e1..0a0e4b7 100644 --- a/docs/usage/managing-clusters.md +++ b/docs/usage/managing-clusters.md @@ -1,40 +1,130 @@ -# Managing VDK Clusters +# Managing Vega Clusters -Learn how to manage your VDK-created KinD clusters. +Learn how to manage your Vega-created KinD clusters. ## Listing Clusters ```bash -vdk get clusters +vega list clusters ``` -Expected Output: +This lists all VDK-managed clusters. Example output: + +``` +vdk +my-dev-cluster +production-test ``` -NAME STATUS VERSION -kind Running v1.25.3 -my-dev-cluster Running v1.25.3 + +## Listing Available Kubernetes Versions + +```bash +vega list kubernetes-versions +``` + +This shows Kubernetes versions available for your installed KinD version. + +## Removing Clusters + +Remove a specific cluster: + +```bash +vega remove cluster --Name my-dev-cluster +# or using the alias +vega remove cluster -n my-dev-cluster ``` -## Deleting Clusters +To remove the default cluster: ```bash -vdk delete cluster --name my-dev-cluster +vega remove cluster ``` -To delete the default 'kind' cluster: +## Updating Cluster Certificates + +When TLS certificates are renewed, update all clusters: + ```bash -vdk delete cluster +vega update clusters ``` -## Getting Kubeconfig +This command: + +- Scans all VDK clusters for Vega-managed TLS secrets +- Updates certificates that don't match the local certificates +- Restarts gateway deployments to pick up new certificates +- Regenerates nginx reverse proxy configuration -VDK typically configures `kubectl` automatically. To get the path to the kubeconfig file for a specific cluster: +Use verbose mode for debugging: ```bash -vdk get kubeconfig --name my-dev-cluster +vega update clusters --verbose ``` -Or for the default cluster: +## Infrastructure Management + +### Registry + +Create the Zot container registry: + +```bash +vega create registry +``` + +Remove it: + +```bash +vega remove registry +``` + +### Reverse Proxy + +Create the nginx reverse proxy: + +```bash +vega create proxy +``` + +Remove it: + +```bash +vega remove proxy +``` + +### Cloud Provider KIND + +Create the Cloud Provider KIND for load balancer support: + +```bash +vega create cloud-provider-kind +``` + +Remove it: + +```bash +vega remove cloud-provider-kind +``` + +## Using kubectl + +Vega automatically configures kubectl contexts for each cluster. After creating a cluster named `my-cluster`, switch to it: + +```bash +kubectl config use-context kind-my-cluster +``` + +Verify connectivity: + +```bash +kubectl cluster-info --context kind-my-cluster +``` + +## Updating Kind Version Information + +If you've updated KinD and need to enable new Kubernetes versions: + ```bash -vdk get kubeconfig +vega update kind-version-info +# or using the alias +vega update k8s ``` From 55edfc1a7fb11c576b28ed8237595dc45313d9ba Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 16:47:32 +0000 Subject: [PATCH 2/3] Initial plan From 3f2477bb94f2b3f6bb584d2ce8bd760677eecb11 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 16:49:11 +0000 Subject: [PATCH 3/3] Fix documentation inconsistencies per review comments Co-authored-by: ewassef <5826918+ewassef@users.noreply.github.com> --- docs/contribution/development-setup.md | 3 +-- docs/debugging/troubleshooting.md | 2 +- docs/usage/command-reference.md | 6 +++--- docs/usage/managing-clusters.md | 10 +++++----- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/contribution/development-setup.md b/docs/contribution/development-setup.md index b22168c..5dbd2d4 100644 --- a/docs/contribution/development-setup.md +++ b/docs/contribution/development-setup.md @@ -94,8 +94,7 @@ VDK/ │ ├── Constants/ # Configuration constants │ ├── Certs/ # TLS certificates │ └── ConfigMounts/ # Container configuration files -├── docs/ # Documentation -└── clusters/ # Flux GitOps configurations +└── docs/ # Documentation ``` ## Key Technologies diff --git a/docs/debugging/troubleshooting.md b/docs/debugging/troubleshooting.md index 7b4da98..6724bd7 100644 --- a/docs/debugging/troubleshooting.md +++ b/docs/debugging/troubleshooting.md @@ -12,7 +12,7 @@ Common issues and how to resolve them. kind export logs --name ./kind-logs ``` - Replace `` with the name of the cluster that failed (or `vdk` for the default). + Replace `` with the name of the cluster that failed (or `vdk` if using the default cluster name). - **Network Issues:** Firewalls or VPNs can sometimes interfere with KinD's networking. - **KinD Version Mismatch:** If you get version-related errors, update the version info: diff --git a/docs/usage/command-reference.md b/docs/usage/command-reference.md index cc76a08..6b28cff 100644 --- a/docs/usage/command-reference.md +++ b/docs/usage/command-reference.md @@ -63,7 +63,7 @@ vega create proxy ### `vega create cloud-provider-kind` -Creates a Cloud Provider KIND container that provisions load balancers for services in KinD clusters. +Creates a Cloud Provider KinD container that provisions load balancers for services in KinD clusters. **Usage:** ```bash @@ -127,7 +127,7 @@ vega remove cloud-provider-kind ### `vega list clusters` -Lists all VDK-managed KinD clusters. +Lists all Vega-managed KinD clusters. **Usage:** ```bash @@ -161,7 +161,7 @@ vega update k8s ### `vega update clusters` Updates cluster configurations including TLS certificates. This command: -- Checks all VDK clusters for outdated certificates +- Checks all Vega clusters for outdated certificates - Updates Vega-managed TLS secrets (`dev-tls` or annotated with `vega.dev/managed=true`) - Restarts gateway deployments to pick up new certificates - Regenerates nginx reverse proxy configuration diff --git a/docs/usage/managing-clusters.md b/docs/usage/managing-clusters.md index 0a0e4b7..03b540f 100644 --- a/docs/usage/managing-clusters.md +++ b/docs/usage/managing-clusters.md @@ -8,7 +8,7 @@ Learn how to manage your Vega-created KinD clusters. vega list clusters ``` -This lists all VDK-managed clusters. Example output: +This lists all Vega-managed clusters. Example output: ``` vdk @@ -50,7 +50,7 @@ vega update clusters This command: -- Scans all VDK clusters for Vega-managed TLS secrets +- Scans all Vega clusters for Vega-managed TLS secrets - Updates certificates that don't match the local certificates - Restarts gateway deployments to pick up new certificates - Regenerates nginx reverse proxy configuration @@ -91,9 +91,9 @@ Remove it: vega remove proxy ``` -### Cloud Provider KIND +### Cloud Provider KinD -Create the Cloud Provider KIND for load balancer support: +Create the Cloud Provider KinD for load balancer support: ```bash vega create cloud-provider-kind @@ -119,7 +119,7 @@ Verify connectivity: kubectl cluster-info --context kind-my-cluster ``` -## Updating Kind Version Information +## Updating KinD Version Information If you've updated KinD and need to enable new Kubernetes versions: