commit a0feba3bc4952de378829efd6af61ea7f6e8a5ff Author: jon brookes Date: Wed Jul 9 12:08:08 2025 +0100 initial commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..ac8bd10 --- /dev/null +++ b/README.md @@ -0,0 +1,325 @@ +# INFCTL CLI + +A command-line tool for automated deployment and management of an MVK (Minimal Viable Kubernetes) infrastrucure. The CLI orchestrates Kubernetes deployments by executing shell scripts and applying Kubernetes manifests through a pipeline-based approach. + +## Table of Contents + +- [Overview](#overview) +- [Features](#features) +- [Prerequisites](#prerequisites) +- [Installation](#installation) +- [Configuration](#configuration) +- [Usage](#usage) +- [Pipeline Execution](#pipeline-execution) +- [Scripts Directory](#scripts-directory) +- [Kubernetes Manifests](#kubernetes-manifests) +- [Project Structure](#project-structure) +- [Development](#development) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +INFCTL CLI is a Go-based deployment orchestrator that automates the setup and deployment of INFCTL applications in Kubernetes environments. The tool executes a series of predefined scripts from the `scripts/` directory and applies Kubernetes manifests from the `k8s-manifests/` directory using kubectl and kustomize. + +## Features + +- **Automated Pipeline Execution**: Runs deployment scripts and manifests in a specific order +- **Script Orchestration**: Executes shell scripts from the `scripts/` directory for various setup tasks +- **Kustomize Integration**: Applies Kubernetes manifests using kubectl kustomize +- **Multi-Component Deployment**: Supports INFCTL, Galene, and SL application deployments +- **Namespace Management**: Automatically creates required Kubernetes namespaces +- **Secret Management**: Automated creation of secrets for databases, SMTP, AWS, etc. +- **ConfigMap Management**: Creates and manages application configuration maps +- **Infrastructure Setup**: Installs and configures cert-manager, Traefik, Longhorn, and PostgreSQL operators +- **Retry Logic**: Built-in retry mechanism for failed operations +- **Structured Logging**: JSON-based logging with debug support + +## Prerequisites + +- Go 1.23.3 or later +- `DEPLOYMENT_TYPE` environment variable set to one of: `customer_k8s_setup`, `infctl_k8s_setup`, or `sl_k8s_setup` +- Kubernetes cluster with kubectl configured (for K8s deployment types) +- Bash shell environment +- Required Kubernetes operators (installed by the tool for K8s deployments): + - cert-manager + - Traefik ingress controller + - PostgreSQL operator (Crunchy Data) + - Longhorn storage + +## Installation + +1. Clone the repository: +```bash +git clone +cd infctl-cli +``` + +2. Build the application: +```bash +go mod download +go build -o infctl-cli . +``` + +3. (Optional) Install globally: +```bash +sudo mv infctl-cli /usr/local/bin/ +``` + +4. Quick start example: +```bash +# Copy configuration examples +cp base.json.example base.json +cp config.json.example config.json + +# Edit configuration files as needed +# nano base.json +# nano config.json + +# Run with desired deployment type +DEPLOYMENT_TYPE=customer_k8s_setup ./infctl-cli +``` + +## Configuration + +The infctl-cli requires two configuration files: + +### Base Configuration (`base.json`) + +Copy and customize the base configuration: + +```bash +cp base.json.example base.json +``` + +Key configuration options: +- `projects_directory`: Base directory for project deployments +- `app_image`: Docker image for the INFCTL application +- `webserver_image`: Docker image for the web server +- `env`: Environment file path +- `preview_path`: Path for preview functionality + +### Customer Configuration (`config.json`) + +Copy and customize the customer-specific configuration: + +```bash +cp config.json.example config.json +``` + +Key configuration options: +- `project`: Project name/identifier (used as Kubernetes namespace) +- `customer_directory`: Customer-specific directory +- `ui_url`: UI service URL +- `static_url`: Static content URL +- `port`: Service port + +## Usage + +The infctl-cli requires the `DEPLOYMENT_TYPE` environment variable to be set to specify the type of deployment. Run the CLI from a directory containing your configuration files. + +### Available Deployment Types + +#### 1. Customer Kubernetes Setup +For customer-specific Kubernetes deployments: + +```bash +DEPLOYMENT_TYPE=customer_k8s_setup ./infctl-cli +``` + +This deployment type: +- Creates customer-specific Kubernetes resources +- Sets up namespaces, secrets, and config maps +- Deploys customer applications with custom configurations + +#### 2. INFCTL Kubernetes Setup +For INFCTL infrastructure and application deployment: + +```bash +DEPLOYMENT_TYPE=inf_k8s_setup ./infctl-cli +``` + +This deployment type: +- Sets up core INFCTL infrastructure +- Installs required operators (cert-manager, Traefik, PostgreSQL) +- Deploys INFCTL applications and services + +#### 3. SL Kubernetes Setup +For SL (Share Lite) application deployment: + +```bash +DEPLOYMENT_TYPE=sl_k8s_setup ./infctl-cli +``` + +This deployment type: +- Deploys SL applications using Helm charts +- Configures SL-specific resources and networking +- Sets up SL instance management + +### Running from Source + +You can also run directly with Go: + +```bash +# For Docker Compose setup +DEPLOYMENT_TYPE=customer_compose_setup go run main.go + +# For customer Kubernetes setup +DEPLOYMENT_TYPE=customer_k8s_setup go run main.go + +# For INFCTL Kubernetes setup +DEPLOYMENT_TYPE=inf_k8s_setup go run main.go + +# For SL Kubernetes setup +DEPLOYMENT_TYPE=sl_k8s_setup go run main.go +``` + +The tool will automatically: + +1. Load base and customer configurations +2. Initialize SQLite database for state management +3. Execute the appropriate deployment pipeline based on `DEPLOYMENT_TYPE` +4. Run scripts from the `scripts/` directory +5. Apply Kubernetes manifests using kustomize (for K8s deployments) + +## Pipeline Execution + +The CLI executes deployment tasks in two main pipelines: + +### Infrastructure Setup Pipeline + +Sets up the Kubernetes cluster infrastructure: + +- Creates required namespaces (project, redis, traefik, metallb-system, longhorn-system, cert-manager) +- Installs Traefik ingress controller +- Sets up PostgreSQL operator (Crunchy Data) +- Configures cert-manager and Redis + +### Application Deployment Pipeline + +Deploys the INFCTL application: + +- Creates database secrets and configurations +- Sets up SMTP secrets +- Creates application secrets and config maps +- Applies INFCTL Kubernetes manifests +- Configures ingress and networking + +## Scripts Directory + +The `scripts/` directory contains shell scripts executed by the CLI: + +### Infrastructure Scripts +- `install_traefik.sh` - Installs Traefik ingress controller +- `install_cert-manager.sh` - Installs cert-manager +- `install_longhorn.sh` - Installs Longhorn storage +- `install_cloudnative_pg.sh` - Installs PostgreSQL operator + +### Database Scripts +- `create_crunchy_operator.sh` - Sets up PostgreSQL operator +- `check_crunchy_operator.sh` - Verifies operator installation +- `create_crunchy_db.sh` - Creates PostgreSQL database +- `create_crunchy_inf_secrets.sh` - Creates database secrets + +### Application Scripts +- `create_app_secret_inf.sh` - Creates application secrets +- `create_smtp_inf_secrets.sh` - Creates SMTP configuration +- `create_init_configmap_inf.sh` - Creates initialization config maps +- `create_nginx_configmap_inf.sh` - Creates Nginx configuration +- `create_php_configmap_inf.sh` - Creates PHP configuration + +### Cloud Provider Scripts +- `create_aws_secrets.sh` - Creates AWS secrets +- `create_cloudflare_secret.sh` - Creates Cloudflare secrets +- `create_redis_secret.sh` - Creates Redis secrets + +## Kubernetes Manifests + +The `k8s-manifests/` directory contains Kubernetes resources applied via kustomize: + +### INFCTL Application (`k8s-manifests/inf/`) +- `deployment.yaml` - Main application deployment +- `pvc.yaml` - Persistent volume claims +- `kustomization.yaml` - Kustomize configuration + +### INFCTL Ingress (`k8s-manifests/inf-ingress/`) +- `ingress.yaml` - Ingress rules +- `service.yaml` - Service definitions +- `issuer.yaml` - Certificate issuer +- `kustomization.yaml` - Kustomize configuration + +### Galene (`k8s-manifests/galene/`) +- WebRTC conferencing application manifests +- TCP/UDP ingress configurations +- Certificate management + +### SL Applications (`k8s-manifests/sl/`) +- Helm chart templates for SL instances +- `Chart.yaml` and `values.yaml` for Helm deployments + +## Project Structure + +``` +infctl-cli/ +├── main.go # Application entry point +├── go.mod # Go module definition +├── base.json.example # Base configuration template +├── config.json.example # Customer configuration template +├── app/ # Core application logic +│ ├── app.go # Pipeline orchestration and state management +│ └── k8s.go # Kubernetes operations (kubectl, kustomize) +├── config/ # Configuration management +│ ├── base.go # Base configuration handling +│ └── customer.go # Customer configuration handling +├── database/ # SQLite database operations +├── scripts/ # Shell scripts executed by the CLI +│ ├── install_*.sh # Infrastructure installation scripts +│ ├── create_*_secrets.sh # Secret creation scripts +│ ├── create_*_configmap_*.sh # ConfigMap creation scripts +│ └── galene/ # Galene-specific scripts +├── k8s-manifests/ # Kubernetes manifests applied via kustomize +│ ├── inf/ # INFCTL application manifests +│ ├── inf-ingress/ # INFCTL ingress configuration +│ ├── galene/ # Galene application manifests +│ ├── sl/ # SL application Helm charts +│ └── sl-certificate/ # SSL certificate management +├── templates/ # Template files for configuration generation +└── files/ # Static configuration files +``` + +## Development + +### Building from Source + +```bash +go mod download +go build -o infctl-cli . +``` + +### Running with Debug Logging + +The CLI uses structured JSON logging. Debug logs are enabled by default and include detailed information about script execution and kustomize operations. + +### Adding New Scripts + +1. Place shell scripts in the `scripts/` directory +2. Add script execution to the appropriate pipeline in `app/app.go` +3. Use the `k8sRunSriptCommand()` function to execute scripts + +### Adding New Manifests + +1. Create Kubernetes YAML files in the appropriate `k8s-manifests/` subdirectory +2. Include a `kustomization.yaml` file for kustomize processing +3. Add manifest application to the pipeline using `k8sRunKustomizeCommand()` + +## Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add some amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## License + +This project is licensed under the GNU General Public License v3.0. See the [LICENSE](./LICENSE) file for details.