update readme
This commit is contained in:
@@ -1,82 +1,109 @@
|
||||
# Kubernetes Local Development Environment
|
||||
|
||||
## Overview
|
||||
|
||||
This project provides automation scripts to create and manage local Kubernetes development environments using Multipass VMs. It enables developers to quickly set up fully functional Kubernetes clusters for testing, development, and learning purposes on their local machines.
|
||||
|
||||
## Features
|
||||
|
||||
- **Kubernetes Cluster**: Automated setup of a multi-node Kubernetes cluster with one control plane and multiple worker nodes
|
||||
- **Modular Design**: Clean separation of provisioning, configuration, and application deployment
|
||||
- **Local Storage**: Integration with Rancher's Local Path Provisioner for persistent storage
|
||||
- **Minimal Requirements**: Runs on your local machine using lightweight Multipass VMs
|
||||
- **Full Automation**: Simple commands to provision, configure, and clean up environments
|
||||
- **Production-like Setup**: Mirrors real-world configurations for realistic testing
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Multipass](https://canonical.com/multipass/install) - for VM provisioning
|
||||
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) - for configuration automation
|
||||
- SSH tools (OpenSSH client)
|
||||
- Python 3 (required by Ansible)
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Setting Up Kubernetes Cluster
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Create and provision a Kubernetes cluster
|
||||
./scripts/provision-kubernetes.sh
|
||||
# Option 1: Using CLI tool (recommended)
|
||||
./cli/install.sh # Install the CLI tool
|
||||
provision # Run interactive provisioning
|
||||
|
||||
# To access the cluster
|
||||
# Option 2: Using scripts directly
|
||||
./scripts/provision-kubernetes.sh # Create Kubernetes cluster
|
||||
|
||||
# Access your cluster
|
||||
multipass shell controlplane
|
||||
kubectl get nodes
|
||||
```
|
||||
|
||||
### Cleaning Up
|
||||
## Overview
|
||||
|
||||
This project provides tools to create and manage local Kubernetes development environments using Multipass VMs. It enables you to quickly set up fully functional Kubernetes clusters on your local machine for testing, development, or learning.
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Host OS**: Ubuntu 24.04 or WSL Ubuntu 24.04 (scripts have only been tested on these platforms)
|
||||
- [Multipass](https://canonical.com/multipass/install) - for VM provisioning
|
||||
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) - for configuration
|
||||
- SSH tools (OpenSSH client)
|
||||
- Python 3
|
||||
|
||||
### CLI Tool (Recommended)
|
||||
|
||||
The CLI tool provides a user-friendly interface for managing your environments:
|
||||
|
||||
```bash
|
||||
# Remove Kubernetes VMs
|
||||
# Install CLI tool
|
||||
./cli/install.sh
|
||||
|
||||
# Run the tool
|
||||
provision
|
||||
```
|
||||
|
||||
[CLI Documentation](./cli/README.md) - Detailed CLI usage and development
|
||||
|
||||
### Manual Scripts
|
||||
|
||||
Alternatively, you can use the scripts directly:
|
||||
|
||||
```bash
|
||||
# Create Kubernetes cluster
|
||||
./scripts/provision-kubernetes.sh
|
||||
|
||||
# Clean up Kubernetes VMs
|
||||
./scripts/cleanup-kubernetes.sh
|
||||
```
|
||||
|
||||
## Using Your Kubernetes Cluster
|
||||
|
||||
After provisioning, you can access your cluster:
|
||||
|
||||
```bash
|
||||
# Connect to control plane node
|
||||
multipass shell controlplane
|
||||
|
||||
# Check cluster status
|
||||
kubectl get nodes
|
||||
kubectl get pods -A
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Kubernetes Environment
|
||||
- **1 Control Plane + 3 Worker Nodes**: Fully functional Kubernetes cluster
|
||||
- **Calico CNI**: For pod networking (v3.29.1)
|
||||
- **Local Path Provisioner**: For persistent storage
|
||||
- **Customizable Resources**: Adjust CPU, memory, and disk in `ansible/defaults/kubernetes.yml`
|
||||
|
||||
- **Control Plane (controlplane)**: Manages the Kubernetes cluster
|
||||
- **Worker Nodes (node01, node02, node03)**: Run your containerized applications
|
||||
- **Networking**: Configured with Calico CNI plugin (v3.29.1)
|
||||
- **Storage**: Local Path Provisioner for development persistent volumes
|
||||
## Features
|
||||
|
||||
- **Production-like Setup**: Mimics real-world cluster structure
|
||||
- **Local Storage**: Support for PersistentVolumes via Local Path Provisioner
|
||||
- **Modular Design**: Clean separation of provisioning and configuration
|
||||
- **Full Automation**: Simple commands to provision, configure, and clean up
|
||||
|
||||
## Configuration
|
||||
|
||||
Customize cluster settings by modifying:
|
||||
Customize the cluster by modifying:
|
||||
|
||||
- `ansible/defaults/kubernetes.yml` - for Kubernetes configurations
|
||||
- VM resources are configurable (CPU, memory, disk)
|
||||
- Network settings, DNS, and more can be adjusted
|
||||
|
||||
## Technical Details
|
||||
|
||||
The project uses Ansible for configuration management with a modular structure:
|
||||
|
||||
- **Playbooks**: Orchestrate the entire setup process
|
||||
- **Tasks**: Modular, reusable configuration steps
|
||||
- **Inventories**: Automatically generated during provisioning
|
||||
|
||||
Kubernetes setup includes:
|
||||
- Container runtime (containerd) configuration
|
||||
- Kubernetes components (kubelet, kubeadm, kubectl)
|
||||
- CNI networking (Calico v3.29.1)
|
||||
- Storage provisioning (Rancher Local Path Provisioner)
|
||||
- Comprehensive validation and testing
|
||||
- `ansible/defaults/kubernetes.yml` - Kubernetes and VM settings
|
||||
- VM resources (CPU, memory, disk)
|
||||
- Network settings, CNI plugin, and more
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check the Ansible logs for detailed error messages
|
||||
1. Check Ansible logs for detailed error messages
|
||||
2. Verify VM status with `multipass list`
|
||||
3. Ensure all prerequisites are properly installed
|
||||
4. For Kubernetes-specific issues, shell into the control plane and use `kubectl` to investigate
|
||||
3. For Kubernetes issues, use `kubectl` commands on the control plane
|
||||
4. Ensure all prerequisites are properly installed
|
||||
5. **Note**: This project has only been tested on Ubuntu 24.04 and WSL Ubuntu 24.04. Using other operating systems may result in compatibility issues.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Feel free to open issues or submit pull requests.
|
||||
|
||||
## License
|
||||
|
||||
[MIT License](LICENSE)
|
||||
|
||||
+59
-33
@@ -1,51 +1,49 @@
|
||||
# Infrastructure CLI Tool
|
||||
|
||||
A simple interactive CLI tool for managing infrastructure provisioning and cleanup. This tool replaces the existing scripts with a more user-friendly interface while maintaining compatibility with the Ansible playbooks.
|
||||
A user-friendly CLI tool for provisioning and managing infrastructure components, with a focus on Kubernetes clusters.
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Quick Install (Linux/macOS)
|
||||
> **Important**: This tool has only been tested on Ubuntu 24.04 and WSL Ubuntu 24.04. There is no guarantee it will work on other operating systems.
|
||||
|
||||
Run the installation script:
|
||||
### Quick Install (Ubuntu)
|
||||
|
||||
```bash
|
||||
./install.sh
|
||||
```
|
||||
|
||||
This will install the CLI tool to `~/.local/bin` and provide instructions if you need to update your PATH.
|
||||
This installs the CLI tool to `~/.local/bin` and provides PATH configuration instructions if needed.
|
||||
|
||||
### Option 2: Manual Install
|
||||
### Manual Install
|
||||
|
||||
1. Find the appropriate binary for your platform in the `bin` directory:
|
||||
- Linux/AMD64: `bin/linux_amd64/provision`
|
||||
- Linux/ARM64: `bin/linux_arm64/provision`
|
||||
- macOS/AMD64: `bin/darwin_amd64/provision`
|
||||
- macOS/ARM64: `bin/darwin_arm64/provision`
|
||||
- Windows: `bin/windows_amd64/provision.exe`
|
||||
Find the appropriate binary for your platform in the `bin` directory:
|
||||
|
||||
2. Copy it to a location in your PATH:
|
||||
```bash
|
||||
# Example for Linux/macOS
|
||||
cp bin/linux_amd64/provision ~/.local/bin/
|
||||
chmod +x ~/.local/bin/provision
|
||||
```
|
||||
```bash
|
||||
# Example for Linux/AMD64
|
||||
cp bin/linux_amd64/provision ~/.local/bin/
|
||||
chmod +x ~/.local/bin/provision
|
||||
```
|
||||
|
||||
Available binaries:
|
||||
- Linux: `bin/linux_amd64/provision` or `bin/linux_arm64/provision`
|
||||
- macOS: `bin/darwin_amd64/provision` or `bin/darwin_arm64/provision`
|
||||
- Windows: `bin/windows_amd64/provision.exe`
|
||||
|
||||
## Usage
|
||||
|
||||
Simply run the command to start the interactive CLI:
|
||||
Run the command to start the interactive CLI:
|
||||
|
||||
```bash
|
||||
provision
|
||||
```
|
||||
|
||||
You'll be guided through a series of prompts to:
|
||||
The tool will guide you through:
|
||||
1. Choosing an operation (provision or cleanup)
|
||||
2. Selecting what to provision/cleanup (Kubernetes or PostgreSQL)
|
||||
3. Configuring settings or using defaults
|
||||
4. Confirming and executing the operation
|
||||
|
||||
1. Choose an operation (provision or cleanup)
|
||||
2. Select what to provision/cleanup (Kubernetes or PostgreSQL)
|
||||
3. Configure settings or use defaults
|
||||
4. Confirm and execute the operation
|
||||
|
||||
### Example: Provisioning Kubernetes
|
||||
### Example: Provision Kubernetes
|
||||
|
||||
```
|
||||
$ provision
|
||||
@@ -54,12 +52,12 @@ $ provision
|
||||
? What would you like to provision? Kubernetes Cluster
|
||||
|
||||
Current default settings:
|
||||
Kubernetes Version: 1.28
|
||||
Kubernetes Version: 1.32
|
||||
Pod CIDR: 192.168.0.0/16
|
||||
Service CIDR: 10.96.0.0/16
|
||||
CNI Plugin: calico
|
||||
Control Plane: 2 CPUs, 4G Memory, 20G Disk
|
||||
Worker Nodes: 2 CPUs, 4G Memory, 20G Disk
|
||||
Control Plane: 4 CPUs, 8G Memory, 40G Disk
|
||||
Worker Nodes: 4 CPUs, 8G Memory, 40G Disk
|
||||
|
||||
? Do you want to use these default settings? Yes
|
||||
? Do you want to proceed? Yes
|
||||
@@ -67,7 +65,7 @@ Worker Nodes: 2 CPUs, 4G Memory, 20G Disk
|
||||
Running provisioning script...
|
||||
```
|
||||
|
||||
### Example: Cleaning Up
|
||||
### Example: Clean Up
|
||||
|
||||
```
|
||||
$ provision
|
||||
@@ -82,15 +80,43 @@ Cleanup completed successfully
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Host OS**: Ubuntu 24.04 or WSL Ubuntu 24.04 (tool has only been tested on these platforms)
|
||||
- Ansible (for provisioning operations)
|
||||
- Multipass (for VM creation)
|
||||
- SSH client tools
|
||||
|
||||
## Developing the CLI Tool
|
||||
## Development
|
||||
|
||||
If you want to modify or extend the CLI tool:
|
||||
### Project Structure
|
||||
|
||||
1. Make changes to the Go code in the `cmd/provision` directory
|
||||
2. Run the build script to rebuild binaries:
|
||||
- `cmd/provision/` - Main CLI code
|
||||
- `cmd/` - Command definitions using Cobra
|
||||
- `kubernetes/` - Kubernetes-specific functionality
|
||||
- `interactive/` - User interaction utilities
|
||||
- `ansible/` - Ansible wrapper functions
|
||||
- `config/` - Configuration management
|
||||
|
||||
### Building the CLI
|
||||
|
||||
To modify or extend the CLI tool:
|
||||
|
||||
1. Make changes to the Go code
|
||||
2. Build binaries for all platforms:
|
||||
```bash
|
||||
./scripts/build-release.sh
|
||||
```
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
1. Create a new command file in `cmd/provision/cmd/`
|
||||
2. Register the command in `cmd/provision/cmd/root.go`
|
||||
3. Implement the command functionality
|
||||
|
||||
### Testing
|
||||
|
||||
Run the tests with:
|
||||
|
||||
```bash
|
||||
cd cli
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user