🌌 Polaris Fleet Controller (Infrastructure-as-Code)
Welcome to the command center for Polaris IT Solutions. This repository is the heart of our operations, managing the infrastructure for all our clients from a single location.
❓ What is Infrastructure-as-Code (IaaC)?
If you are new to DevOps, think of Infrastructure-as-Code as "programmable hardware."
Instead of manually logging into a server, clicking buttons, or typing random commands to install software (which is slow, error-prone, and hard to track), we write code that describes what the server should look like.
- Manual Way: "I think I installed the antivirus on Server A... but I forgot Server B."
- IaaC Way: You write a script that says "Ensure Antivirus is installed on ALL servers." When you run it, the computer does the work. If a server dies, you just run the code again on a new one, and it's identical.
This repository stores all those blueprints. It allows us to manage 100 clients as easily as managing 1.
🏗️ Repository Structure
This is a Fleet Controller (Git Superproject). It connects multiple separate repositories together.
clients/: Where the magic happens. Each folder here is a separate Git submodule representing a client. Each client has its ownsop/directory for specific details.management-scripts/: The toolbox. Contains shared scripts (Ansible, Terraform) and technician setup scripts.sops/: Master Standard Operating Procedures. The fleet-wide rules for staff.documentation/: Platform-specific technical documentation (AWS, Azure, GCP, Cloudflare, etc.).specs/: Architectural specifications for this project.
🚀 Getting Started (New Technician Setup)
Before you can work on our infrastructure, you need to prepare your machine. We have automated this for you.
🖥️ For Windows Users
- Open PowerShell as Administrator.
- Run the following command to install VS Code, WSL (Linux Subsystem), and Ubuntu:
powershell -ExecutionPolicy Bypass -File .\management-scripts\setup-wsl.ps1 - REBOOT YOUR PC.
- After reboot, open the Ubuntu app (it will finish installing).
- Inside the Ubuntu terminal, run the Linux steps below.
🐧 For Linux Users (or inside WSL Ubuntu)
- Open your terminal (or Ubuntu terminal).
- Navigate to this folder.
- Run the bootstrap script to install Python, Ansible, Terraform, Docker, and Security tools:
./management-scripts/bootstrap-technician.sh - Restart your terminal. You are ready to go!
🛡️ Sovereign Infrastructure Stack
We use a "Zero Local Installation" approach. All major tools run as Docker containers, ensuring every technician uses the exact same version and configuration.
| Category | Tool | Function | VS Code Task Label |
|---|---|---|---|
| Security | Prowler | Audits AWS/GCP/Azure accounts for security best practices. | 🛡️ Security: Run Prowler Audit (Live - AWS/GCP/Azure) |
| Security | Checkov | Scans Terraform code for misconfigurations. | 🛡️ Security: Scan IaC Code (Checkov) |
| Cost | Infracost | Estimates cloud costs based on Terraform changes. | 💸 Cost: Infracost (Pre-deploy Estimate) |
| Cost | Komiser | Analyzes live accounts to find "zombie" resources. | 💰 Cost: Komiser (Live Waste Report) |
| Governance | Custodian | "Auto-Janitor" that enforces policies. | ⚖️ Policy: Cloud Custodian (Auto-Janitor) |
| Inventory | NetBox | Source of Truth for IPAM, Hardware, and Network map. | (Managed via Terraform/API) |
| Catalog | Port.io | Software Catalog tracking installed services/libraries. | (Managed via API/CI) |
| Deployment | Terraform | Deploys infrastructure via Terraform. | 🏗️ Infra: Terraform Apply |
| Scanning | Trivy | Scans Docker images for vulnerabilities. | 🐳 Audit: Scan Docker Image (Trivy) |
| Pentest | Nmap+Nuclei | Performs external penetration testing. | ☠️ Audit: External Pen Test (Nmap+Nuclei) |
🎮 Common Actions
1. Running Fleet Tasks (The Easy Way)
We have pre-configured VS Code Tasks for all common operations.
- Open Task Runner: Press
Ctrl+Shift+P(orCmd+Shift+Pon Mac). - Select Task: Type
Tasks: Run Taskand pressEnter. - Choose from List: Select a task from the table above (e.g.,
🛡️ Security: Run Prowler...). - Provide Inputs: Follow the prompts at the top of the window (e.g., Select Client, Cloud Provider).
Note: These tasks automatically use Infisical to inject secrets into the containers. Ensure you have run infisical login first.
2. Connecting to a Client
To work on a specific client (e.g., "Koruna Assist"), navigate to their folder:
cd clients/koruna-assist-iaac
Note: Any files you change here belong to that client's separate repository.
3. Updating the Fleet
Because this repo is a collection of other repos, keeping everything in sync can be tricky. We created a helper script:
./git-update-all.sh
This will go through every client, save your changes, push them to the cloud, and then update the main controller.
🔐 Secrets Management
This project uses Infisical as the single source of truth for all secrets.
Core Workflow
- Log In: Authenticate once.
infisical login - Initialize Client: Link a new client folder to its Infisical project.
cd clients/client-omega-iaac
infisical init - Run Tools: Use the helper wrapper (or our VS Code Tasks) to inject secrets.
# Manually running a command with secrets
infisical run --env=prod -- terraform plan
IMPORTANT: Never store credentials in .env files or commit them to Git.
➕ Creating a New Client
To onboard a new client, follow these steps strictly to ensure they are properly linked to the Fleet Controller.
Step 1: Create the Remote Repository
- Go to GitHub/GitLab and create a new empty repository (e.g.,
client-omega-iaac). - Do not initialize it with a README or .gitignore.
Step 2: Add Submodule to Fleet Controller
From the root of this repository (infrastructure-as-code):
# Syntax: git submodule add <REPO_URL> clients/<FOLDER_NAME>
git submodule add git@github.com:polaris-it/client-omega-iaac.git clients/client-omega-iaac
Step 3: Initialize from Template
Copy the standard structure from our template directory into the new client folder.
# Copy template contents (including hidden files)
cp -r clients/client-template/. clients/client-omega-iaac/
Step 4: Customize & Push
- Navigate to the new client folder:
cd clients/client-omega-iaac - Edit
sop/Client_Operations.md: Fill in the client code and known details. - Commit and Push:
git add .
git commit -m "feat: init client from template"
git push -u origin main
Step 5: Sync the Fleet
Go back to the root and update the controller.
cd ../..
./git-update-all.sh
📂 Client Repository Standard Structure
Every client submodule follows this exact structure. This consistency allows any technician (or Gemini) to jump between clients without confusion.
| Path | Purpose |
|---|---|
.specify/ | The Brain. Contains the project constitution, templates, and scripts for Gemini. Do not edit manually. |
configs/ | Configuration. Stores config files mounted into containers (e.g., nginx.conf, prometheus.yml). |
data/ | Local Data. Stores persistent volume data for local development. Gitignored to prevent leaking DBs. |
sop/ | Procedures. Contains Client_Operations.md, the human-readable manual for this specific client. |
compose.yaml | The Truth. The Docker Compose / Swarm definition defining the runtime infrastructure. |
.env.example | The Key. Lists all required environment variables. Copy this to .env (gitignored) and fill in secrets. |
gemini.md | The Persona. Instructions for the AI agent when working inside this specific client folder. |
📖 Key Documentation
- Constitution: Our core rules and coding standards.
- Baseline Specs: The architectural design of this system.
Maintained by the Polaris Platform Team.
💼 Business Capabilities & Sales Info
1. Overview
This Infrastructure-as-Code (IaC) platform, built around the Polaris Fleet Controller, provides a centralized, automated, and secure system for managing the complete technology lifecycle of multiple clients. By defining all infrastructure, services, and identity management in code, we deliver consistent, repeatable, and auditable results.
2. Core Capabilities
- Centralized Client Management: Manage all clients from a single repository, with each client's infrastructure isolated in its own secure, version-controlled submodule.
- Automated Provisioning: Rapidly deploy and update services across the entire fleet or for individual clients using a unified set of tools.
- Secure Secrets Management: All sensitive credentials (API keys, tokens, etc.) are centrally managed in Infisical, ensuring they are never hard-coded.
- Declarative Configuration: Infrastructure is defined as code, providing a single source of truth and eliminating configuration drift.
- AI-Assisted Operations: Designed for both human technicians and AI agents (Gemini) with clear documentation and operational glossaries.
3. Supported Platforms & Services
This platform provides a unified interface to manage a wide range of services across multiple cloud, SaaS, and on-premises environments.
🛡️ Managed Security & RMM (Cyber-Security Offering)
- Service: Automated deployment and management of a full-spectrum security and monitoring stack to every client server.
- Core Tools: Ansible, Terraform.
- Integrated Stack:
- Bitdefender / RocketCyber: Managed EDR, Advanced Threat Security (ATS), and 24/7 SOC triage.
- Pulseway / Datto: Remote Monitoring & Management (RMM) with automated OS and 3rd-party patching.
- Ransomware Protection: Hardened configurations and active protection agents.
☁️ Major Cloud Providers (AWS, Azure, GCP, OCI)
- Service: Provision, configure, and manage core cloud infrastructure across all major providers.
- Terraform Providers:
hashicorp/aws,hashicorp/azurerm,hashicorp/google,hashicorp/oci. - Examples: VMs (EC2, Azure VM), Object Storage (S3, Blob), Networking (VPC, VNET).
🌐 Networking & Connectivity (Netbird & Cloudflare)
- Service: Secure, zero-trust connectivity and edge optimization.
- Tools: Netbird (Zero-Trust Mesh VPN), Cloudflare (DNS/WAF).
- Benefits: Securely connects staff, VS Code environments, and all client servers in a private, encrypted mesh.
📊 Observability & PSA (Grafana & Odoo)
- Service: Real-time monitoring and business-process integration.
- Tools: Grafana Cloud (Logs/Metrics), Odoo (Helpdesk/PSA).
- Capability: Client-facing dashboards for transparency and automated ticket/asset tracking for compliance.
🏢 On-Premises & Hybrid Cloud
- Service: Extend IaC to on-premises servers and hybrid cloud environments.
- Core Tool: Ansible.
- Examples: Software Installation/Patching, Security Hardening, Configuration Management.
4. Business Benefits (Why Clients Buy This)
- Consistency & Reliability: Every environment is built from the same code, eliminating human error.
- Speed & Agility: Onboard new clients and deploy new services in minutes, not days.
- Full-Stack Managed Security:
- Zero-Trust Mesh: Every client server is isolated and protected via Netbird.
- Automated Compliance: Prowler and Checkov ensure infrastructure meets global standards.
- SOC-Ready: Integrated Bitdefender and RocketCyber provide enterprise-grade protection.
- Cost Optimization:
- Pre-Deploy Estimates: Infracost tells you the price tag before you launch.
- Waste Detection: Komiser finds "zombie" resources to save money.
- Operational Transparency: Clients get access to Grafana dashboards and an Odoo portal to see their status in real-time.
- Scalability: Manage 100 clients as easily as 1.
- Disaster Recovery: Re-provision entire infrastructures from scratch with a single command.