INFCTL CLI

A command-line tool for automated deployment and management of an MVK (Minimal Viable Kubernetes) infrastructure. The CLI orchestrates Kubernetes deployments by executing shell scripts and applying Kubernetes manifests through a JSON-defined pipeline approach.

Table of Contents

• Overview
• Features
• Design Philosophy
• Prerequisites
• Installation
• Configuration
• Usage
• Pipeline Execution
• Scripts Directory
• Kubernetes Manifests
• Project Structure
• Development
• Contributing
• 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, all defined in a JSON pipeline file.

Features

• JSON-Defined Pipeline Execution: Runs deployment scripts and manifests in an order specified in a JSON pipeline file
• Script Orchestration: Executes shell scripts from the scripts/ directory for various setup tasks
• Kustomize Integration: Applies Kubernetes manifests using kubectl kustomize
• 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
• Integrated Testing: Includes smoke tests using k3d for validation

Design Philosophy

infctl-cli is built on principles derived from over 20 years of experience tackling deployment and orchestration challenges. The design is inspired by a "plugin" mentality, where each plugin is essentially a script. This approach emphasizes simplicity and modularity, allowing each script to act as an independent unit of execution.

Key principles include:

• Script-Based Orchestration: Each script or program, when executed, returns an exit code that indicates success or failure. This exit code is used to determine the next steps in the pipeline, enabling robust and predictable orchestration.
• Structured Logging: Scripts produce structured logs that can be consumed by web interfaces or stored in a database. This ensures transparency and traceability, making it easier to debug and monitor deployments.
• Modularity and Reusability: By treating scripts as plugins, the system encourages reusability and flexibility. New functionality can be added by simply introducing new scripts without altering the core logic.
• UNIX Philosophy: The design adheres to the UNIX philosophy of building small, composable tools that do one thing well. Each script is a self-contained unit that performs a specific task.

This philosophy underpins infctl's ability to orchestrate complex deployments while remaining simple and extensible.

Prerequisites

• Go 1.23.3 or later
• Bash shell environment
• For running tests: k3d installed
• Kubernetes cluster with kubectl configured (for actual deployments)
• Required Kubernetes operators (installed by the tool for K8s deployments):
  • cert-manager
  • Traefik ingress controller
  • PostgreSQL operator (Crunchy Data)
  • Longhorn storage

Installation

Option 1: Download Pre-built Binary

You can run an install from curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/chore/code-refactor/install.sh | bash

.or.

manually download the pre-built binary for your platform from the releases page.

1. Download the binary for your platform:

   • Linux:

     wget https://codeberg.org/headshed/infctl-cli/releases/download/v0.0.2/infctl-linux-amd64 -O /usr/local/bin/infctl
     

   • Windows: Download the .exe file from the releases page and place it in a directory included in your PATH.

   • macOS (Intel):

     wget https://codeberg.org/headshed/infctl-cli/releases/download/v0.0.2/infctl-darwin-amd64 -O /usr/local/bin/infctl
     

   • macOS (Apple Silicon):

     wget https://codeberg.org/headshed/infctl-cli/releases/download/v0.0.2/infctl-darwin-arm64 -O /usr/local/bin/infctl
     

2. Make the binary executable:

   chmod +x /usr/local/bin/infctl
   

Option 2: Clone Repository and Build Binary

1. Clone the repository:

git clone <repository-url>
cd infctl-cli

2. Build the application:

go mod download
go build -o infctl-cli .

Quick start example

# Copy configuration examples
cp base.json.example base.json
cp config.json.example config.json
cp pipeline.json.example pipeline.json

# Edit* configuration files as needed
# vim base.json
# vim config.json
# vim pipeline.json
# - where vim may be your default or chosen editor be it nano, vi, ed, emacs, etc ...

# Run with pipeline file
./infctl-cli --deployment-file pipeline.json

Configuration

The infctl-cli requires three configuration files:

Base Configuration (base.json)

Copy and customize the base configuration:

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:

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

Pipeline Configuration (pipeline.json)

Copy and customize the pipeline definition:

cp pipeline.json.example pipeline.json

This file defines the sequence of operations to be executed, including:

• Scripts to run
• Kubernetes manifests to apply
• Order of operations
• Specific deployment type configuration

Usage

Run the CLI by providing a path to your pipeline JSON file:

./infctl-cli --deployment-file /path/to/pipeline.json

The tool will automatically:

1. Load base and customer configurations
2. Initialize SQLite database for state management
3. Execute the deployment pipeline defined in your JSON file
4. Run scripts from the scripts/ directory
5. Apply Kubernetes manifests using kustomize (for K8s deployments)

Running from Source

You can also run directly with Go:

go run main.go -pipeline /path/to/pipeline.json

Running Tests

The project includes smoke tests using k3d for validation:

# Run all tests
go test ./... -v

# Run specific test
go test ./app -run TestRunPipeline

Pipeline Execution

The CLI executes deployment tasks defined in your pipeline.json file, which typically includes:

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

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
├── k8s-manifests/              # Kubernetes manifests applied via kustomize
│   ├── ctl/                    # INFCTL application manifests
│   └── ctl-ingress/            # INFCTL ingress configuration
├── templates/                  # Template files for configuration generation
└── files/                      # Static configuration files

Development

Building from Source

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 / executables in the scripts/ directory
2. Add confiiguration as appropriate into pipeline.json
3. Re-run cnfctl --deployment-file pipeline.json

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 confiiguration as appropriate into pipeline.json
4. Re-run cnfctl --deployment-file pipeline.json

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 file for details.