Initial commit: loc_az_hci (smom-dbis-138 excluded via .gitignore)
Some checks failed
Test / test (push) Has been cancelled
Some checks failed
Test / test (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
289
docs/getting-started/installation.md
Normal file
289
docs/getting-started/installation.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Installation Guide
|
||||
|
||||
Step-by-step installation instructions for the Azure Stack HCI infrastructure.
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks you through the complete installation process, from initial setup to service deployment.
|
||||
|
||||
## Installation Phases
|
||||
|
||||
1. **Prerequisites Verification** - Verify all requirements are met
|
||||
2. **Proxmox Cluster Setup** - Configure Proxmox VE cluster
|
||||
3. **Azure Arc Onboarding** - Connect infrastructure to Azure
|
||||
4. **Kubernetes Deployment** - Deploy K3s cluster
|
||||
5. **Git Server Setup** - Deploy Git repository
|
||||
6. **GitOps Configuration** - Configure GitOps workflow
|
||||
7. **Service Deployment** - Deploy HC Stack services
|
||||
|
||||
## Phase 1: Prerequisites Verification
|
||||
|
||||
### Step 1.1: Verify Prerequisites
|
||||
|
||||
Run the prerequisites check:
|
||||
|
||||
```bash
|
||||
./scripts/utils/prerequisites-check.sh
|
||||
```
|
||||
|
||||
### Step 1.2: Configure Environment
|
||||
|
||||
Create and configure `.env` file:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your credentials
|
||||
```
|
||||
|
||||
### Step 1.3: Test Connections
|
||||
|
||||
```bash
|
||||
# Test Proxmox connections
|
||||
./scripts/utils/test-proxmox-connection.sh
|
||||
|
||||
# Test Cloudflare (if configured)
|
||||
./scripts/utils/test-cloudflare-connection.sh
|
||||
```
|
||||
|
||||
## Phase 2: Proxmox Cluster Setup
|
||||
|
||||
### Step 2.1: Configure Network on Node 1
|
||||
|
||||
```bash
|
||||
export NODE_IP=192.168.1.10
|
||||
export NODE_GATEWAY=192.168.1.1
|
||||
export NODE_HOSTNAME=pve-node-1
|
||||
|
||||
./infrastructure/proxmox/network-config.sh
|
||||
```
|
||||
|
||||
### Step 2.2: Create Cluster on Node 1
|
||||
|
||||
```bash
|
||||
./infrastructure/proxmox/cluster-setup.sh
|
||||
```
|
||||
|
||||
### Step 2.3: Configure Network on Node 2
|
||||
|
||||
```bash
|
||||
export NODE_IP=192.168.1.11
|
||||
export NODE_GATEWAY=192.168.1.1
|
||||
export NODE_HOSTNAME=pve-node-2
|
||||
export CLUSTER_NODE_IP=192.168.1.10
|
||||
|
||||
./infrastructure/proxmox/network-config.sh
|
||||
```
|
||||
|
||||
### Step 2.4: Join Node 2 to Cluster
|
||||
|
||||
```bash
|
||||
export NODE_ROLE=join
|
||||
./infrastructure/proxmox/cluster-setup.sh
|
||||
```
|
||||
|
||||
### Step 2.5: Verify Cluster
|
||||
|
||||
```bash
|
||||
# On either node
|
||||
pvecm status
|
||||
pvecm nodes
|
||||
```
|
||||
|
||||
## Phase 3: Azure Arc Onboarding
|
||||
|
||||
### Step 3.1: Prepare Azure
|
||||
|
||||
```bash
|
||||
export RESOURCE_GROUP=HC-Stack
|
||||
export TENANT_ID=$(az account show --query tenantId -o tsv)
|
||||
export SUBSCRIPTION_ID=$(az account show --query id -o tsv)
|
||||
export LOCATION=eastus
|
||||
|
||||
# Create resource group
|
||||
az group create --name $RESOURCE_GROUP --location $LOCATION
|
||||
```
|
||||
|
||||
### Step 3.2: Onboard Proxmox Hosts
|
||||
|
||||
**On each Proxmox node:**
|
||||
|
||||
```bash
|
||||
./scripts/azure-arc/onboard-proxmox-hosts.sh
|
||||
```
|
||||
|
||||
### Step 3.3: Create Service VMs
|
||||
|
||||
Create VMs using Proxmox Web UI or Terraform:
|
||||
|
||||
```bash
|
||||
# Using Terraform
|
||||
cd terraform/proxmox
|
||||
terraform init
|
||||
terraform plan
|
||||
terraform apply
|
||||
```
|
||||
|
||||
### Step 3.4: Onboard VMs to Azure Arc
|
||||
|
||||
After VMs are created and OS is installed:
|
||||
|
||||
```bash
|
||||
./scripts/azure-arc/onboard-vms.sh
|
||||
```
|
||||
|
||||
## Phase 4: Kubernetes Deployment
|
||||
|
||||
### Step 4.1: Install K3s
|
||||
|
||||
**On K3s VM:**
|
||||
|
||||
```bash
|
||||
./infrastructure/kubernetes/k3s-install.sh
|
||||
```
|
||||
|
||||
### Step 4.2: Verify K3s
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
|
||||
kubectl get nodes
|
||||
kubectl get pods --all-namespaces
|
||||
```
|
||||
|
||||
### Step 4.3: Onboard to Azure Arc
|
||||
|
||||
```bash
|
||||
export RESOURCE_GROUP=HC-Stack
|
||||
export CLUSTER_NAME=proxmox-k3s-cluster
|
||||
|
||||
./infrastructure/kubernetes/arc-onboard-k8s.sh
|
||||
```
|
||||
|
||||
### Step 4.4: Install Base Infrastructure
|
||||
|
||||
```bash
|
||||
kubectl apply -f gitops/infrastructure/namespace.yaml
|
||||
kubectl apply -f gitops/infrastructure/ingress-controller.yaml
|
||||
kubectl apply -f gitops/infrastructure/cert-manager.yaml
|
||||
```
|
||||
|
||||
## Phase 5: Git Server Setup
|
||||
|
||||
### Option A: Deploy Gitea (Recommended)
|
||||
|
||||
```bash
|
||||
export GITEA_DOMAIN=git.local
|
||||
export GITEA_PORT=3000
|
||||
|
||||
./infrastructure/gitops/gitea-deploy.sh
|
||||
```
|
||||
|
||||
Access Gitea at `http://git.local:3000` and complete initial setup.
|
||||
|
||||
### Option B: Deploy GitLab CE
|
||||
|
||||
```bash
|
||||
export GITLAB_DOMAIN=gitlab.local
|
||||
export GITLAB_PORT=8080
|
||||
|
||||
./infrastructure/gitops/gitlab-deploy.sh
|
||||
```
|
||||
|
||||
**Note**: GitLab requires at least 8GB RAM.
|
||||
|
||||
## Phase 6: GitOps Configuration
|
||||
|
||||
### Step 6.1: Create Git Repository
|
||||
|
||||
1. Create a new repository in your Git server (Gitea/GitLab)
|
||||
2. Clone the repository locally
|
||||
3. Copy the `gitops/` directory to repository
|
||||
|
||||
```bash
|
||||
git clone http://git.local:3000/user/gitops-repo.git
|
||||
cd gitops-repo
|
||||
cp -r /path/to/loc_az_hci/gitops/* .
|
||||
git add .
|
||||
git commit -m "Initial GitOps configuration"
|
||||
git push
|
||||
```
|
||||
|
||||
### Step 6.2: Connect GitOps to Azure Arc
|
||||
|
||||
In Azure Portal:
|
||||
|
||||
1. Navigate to: Azure Arc → Kubernetes → Your cluster
|
||||
2. Go to "GitOps" section
|
||||
3. Click "Add configuration"
|
||||
4. Configure:
|
||||
- Repository URL: `http://git.local:3000/user/gitops-repo.git`
|
||||
- Branch: `main`
|
||||
- Path: `gitops/`
|
||||
- Authentication: Configure as needed
|
||||
|
||||
## Phase 7: Service Deployment
|
||||
|
||||
### Option A: Deploy via GitOps (Recommended)
|
||||
|
||||
1. Update Helm chart values in your Git repository
|
||||
2. Commit and push changes
|
||||
3. Flux will automatically deploy updates
|
||||
|
||||
### Option B: Deploy Manually with Helm
|
||||
|
||||
```bash
|
||||
# Add Helm charts
|
||||
helm install besu ./gitops/apps/besu -n blockchain
|
||||
helm install firefly ./gitops/apps/firefly -n blockchain
|
||||
helm install chainlink-ccip ./gitops/apps/chainlink-ccip -n blockchain
|
||||
helm install blockscout ./gitops/apps/blockscout -n blockchain
|
||||
helm install cacti ./gitops/apps/cacti -n monitoring
|
||||
helm install nginx-proxy ./gitops/apps/nginx-proxy -n hc-stack
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Verify Proxmox Cluster
|
||||
|
||||
```bash
|
||||
pvecm status
|
||||
pvecm nodes
|
||||
```
|
||||
|
||||
### Verify Azure Arc
|
||||
|
||||
In Azure Portal:
|
||||
- Navigate to Azure Arc → Servers
|
||||
- Verify all hosts and VMs are connected
|
||||
|
||||
### Verify Kubernetes
|
||||
|
||||
```bash
|
||||
kubectl get nodes
|
||||
kubectl get pods --all-namespaces
|
||||
```
|
||||
|
||||
### Verify Services
|
||||
|
||||
```bash
|
||||
kubectl get services --all-namespaces
|
||||
kubectl get ingress --all-namespaces
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See [Troubleshooting Guide](../troubleshooting/common-issues.md) for common issues and solutions.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation:
|
||||
1. Configure monitoring and alerting
|
||||
2. Set up backup and disaster recovery
|
||||
3. Implement security policies
|
||||
4. Review [Operations Guide](../operations/runbooks/)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Deployment Guide](../deployment/deployment-guide.md)
|
||||
- [Bring-Up Checklist](../deployment/bring-up-checklist.md)
|
||||
- [Architecture Overview](../architecture/overview.md)
|
||||
|
||||
160
docs/getting-started/prerequisites.md
Normal file
160
docs/getting-started/prerequisites.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Prerequisites
|
||||
|
||||
This document outlines all prerequisites for deploying the Azure Stack HCI infrastructure.
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
### Proxmox VE Hosts
|
||||
|
||||
- **Minimum**: 2 Proxmox VE hosts
|
||||
- **Proxmox Version**: 7.0 or higher
|
||||
- **RAM**: Minimum 8GB per node (16GB+ recommended)
|
||||
- **Storage**: Sufficient storage for VMs and templates
|
||||
- **Network**:
|
||||
- Static IP addresses configured
|
||||
- Network connectivity between nodes
|
||||
- Internet access for Azure Arc connectivity
|
||||
|
||||
### Optional: Router/Storage Server
|
||||
|
||||
If implementing the full Azure Stack HCI architecture:
|
||||
- Server with multiple PCIe slots
|
||||
- 4× Spectrum WAN connections
|
||||
- Storage shelves with HBAs
|
||||
- Intel QAT 8970 for crypto acceleration
|
||||
|
||||
See [Hardware BOM](../architecture/hardware-bom.md) for complete hardware specifications.
|
||||
|
||||
## Software Requirements
|
||||
|
||||
### Required Tools
|
||||
|
||||
- **Azure CLI**: Installed and authenticated
|
||||
```bash
|
||||
az login
|
||||
az account show
|
||||
```
|
||||
- **kubectl**: For Kubernetes management
|
||||
```bash
|
||||
kubectl version --client
|
||||
```
|
||||
- **SSH**: Access to all nodes
|
||||
- **Terraform** (optional): For Infrastructure as Code
|
||||
- **Helm** (optional): For GitOps deployments
|
||||
|
||||
### Azure Subscription
|
||||
|
||||
- Azure subscription with **Contributor** role
|
||||
- Resource group creation permissions
|
||||
- Azure Arc enabled subscription
|
||||
|
||||
### Network Requirements
|
||||
|
||||
- **Static IP addresses** for all nodes
|
||||
- **DNS resolution** (or hosts file configuration)
|
||||
- **Outbound HTTPS (443)** for Azure Arc connectivity
|
||||
- **Cluster communication ports** (5404-5412 UDP) for Proxmox cluster
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file from the template:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Required variables:
|
||||
- **Azure**: `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`
|
||||
- **Cloudflare**: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_TUNNEL_TOKEN`
|
||||
- **Proxmox**: `PVE_ROOT_PASS`, `PROXMOX_ML110_URL`, `PROXMOX_R630_URL`
|
||||
|
||||
See `.env.example` for all available configuration options.
|
||||
|
||||
### Network Configuration
|
||||
|
||||
Ensure the following network ranges are available:
|
||||
- **VLAN 10**: Storage (10.10.10.0/24)
|
||||
- **VLAN 20**: Compute (10.10.20.0/24)
|
||||
- **VLAN 30**: App Tier (10.10.30.0/24)
|
||||
- **VLAN 40**: Observability (10.10.40.0/24)
|
||||
- **VLAN 50**: Dev/Test (10.10.50.0/24)
|
||||
- **VLAN 60**: Management (10.10.60.0/24)
|
||||
- **VLAN 99**: DMZ (10.10.99.0/24)
|
||||
|
||||
See [Network Topology](../architecture/network-topology.md) for detailed network design.
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
Before starting deployment, verify:
|
||||
|
||||
- [ ] Proxmox VE installed and updated on all hosts
|
||||
- [ ] Static IP addresses configured
|
||||
- [ ] Network connectivity between nodes tested
|
||||
- [ ] Azure CLI installed and authenticated
|
||||
- [ ] Azure subscription has Contributor role
|
||||
- [ ] `.env` file created and configured
|
||||
- [ ] SSH access to all nodes verified
|
||||
- [ ] DNS resolution working (or hosts file configured)
|
||||
- [ ] Outbound HTTPS (443) connectivity verified
|
||||
- [ ] Sufficient storage available on Proxmox hosts
|
||||
- [ ] VM IDs planned (avoid conflicts)
|
||||
|
||||
## Verification Scripts
|
||||
|
||||
Run the prerequisites check script:
|
||||
|
||||
```bash
|
||||
./scripts/utils/prerequisites-check.sh
|
||||
```
|
||||
|
||||
This will verify:
|
||||
- Proxmox VE installation
|
||||
- Network configuration
|
||||
- Azure CLI installation and authentication
|
||||
- kubectl installation
|
||||
- Helm installation (optional)
|
||||
- Docker installation (optional)
|
||||
- System resources
|
||||
|
||||
## Next Steps
|
||||
|
||||
After verifying prerequisites:
|
||||
1. Follow the [Quick Start Guide](quick-start.md)
|
||||
2. Review the [Deployment Guide](../deployment/deployment-guide.md)
|
||||
3. Use the [Bring-Up Checklist](../deployment/bring-up-checklist.md)
|
||||
|
||||
## Troubleshooting Prerequisites
|
||||
|
||||
### Azure CLI Not Authenticated
|
||||
```bash
|
||||
az login
|
||||
az account set --subscription "your-subscription-id"
|
||||
az account show
|
||||
```
|
||||
|
||||
### Network Connectivity Issues
|
||||
```bash
|
||||
# Test connectivity between nodes
|
||||
ping <node-ip>
|
||||
ssh <node-ip> "echo 'Connection successful'"
|
||||
```
|
||||
|
||||
### Proxmox Connection Issues
|
||||
```bash
|
||||
# Test Proxmox API access
|
||||
./scripts/utils/test-proxmox-connection.sh
|
||||
```
|
||||
|
||||
### Insufficient Resources
|
||||
- Check available RAM: `free -h`
|
||||
- Check available disk space: `df -h`
|
||||
- Check CPU: `nproc`
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Architecture Overview](../architecture/overview.md)
|
||||
- [Network Topology](../architecture/network-topology.md)
|
||||
- [Hardware BOM](../architecture/hardware-bom.md)
|
||||
|
||||
168
docs/getting-started/quick-start.md
Normal file
168
docs/getting-started/quick-start.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Get your Azure Stack HCI infrastructure up and running quickly.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
- Two Proxmox VE hosts with Proxmox VE 7.0+ installed
|
||||
- Azure subscription with Contributor role
|
||||
- Azure CLI installed and authenticated
|
||||
- SSH access to all nodes
|
||||
- Network connectivity between nodes
|
||||
|
||||
See [Prerequisites](prerequisites.md) for detailed requirements.
|
||||
|
||||
## Quick Start Steps
|
||||
|
||||
### 1. Clone and Configure
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd loc_az_hci
|
||||
cp .env.example .env
|
||||
# Edit .env with your credentials
|
||||
```
|
||||
|
||||
### 2. Test Connections
|
||||
|
||||
```bash
|
||||
# Test Proxmox connections
|
||||
./scripts/utils/test-proxmox-connection.sh
|
||||
|
||||
# Test Cloudflare (if configured)
|
||||
./scripts/utils/test-cloudflare-connection.sh
|
||||
```
|
||||
|
||||
### 3. Configure Proxmox Cluster
|
||||
|
||||
**On Node 1:**
|
||||
```bash
|
||||
export NODE_IP=192.168.1.10
|
||||
export NODE_GATEWAY=192.168.1.1
|
||||
export NODE_HOSTNAME=pve-node-1
|
||||
|
||||
./infrastructure/proxmox/network-config.sh
|
||||
./infrastructure/proxmox/cluster-setup.sh
|
||||
```
|
||||
|
||||
**On Node 2:**
|
||||
```bash
|
||||
export NODE_IP=192.168.1.11
|
||||
export NODE_GATEWAY=192.168.1.1
|
||||
export NODE_HOSTNAME=pve-node-2
|
||||
export CLUSTER_NODE_IP=192.168.1.10
|
||||
|
||||
./infrastructure/proxmox/network-config.sh
|
||||
export NODE_ROLE=join
|
||||
./infrastructure/proxmox/cluster-setup.sh
|
||||
```
|
||||
|
||||
### 4. Onboard to Azure Arc
|
||||
|
||||
**On each Proxmox node:**
|
||||
```bash
|
||||
export RESOURCE_GROUP=HC-Stack
|
||||
export TENANT_ID=$(az account show --query tenantId -o tsv)
|
||||
export SUBSCRIPTION_ID=$(az account show --query id -o tsv)
|
||||
export LOCATION=eastus
|
||||
|
||||
./scripts/azure-arc/onboard-proxmox-hosts.sh
|
||||
```
|
||||
|
||||
### 5. Deploy Kubernetes
|
||||
|
||||
**On K3s VM:**
|
||||
```bash
|
||||
./infrastructure/kubernetes/k3s-install.sh
|
||||
|
||||
export RESOURCE_GROUP=HC-Stack
|
||||
export CLUSTER_NAME=proxmox-k3s-cluster
|
||||
./infrastructure/kubernetes/arc-onboard-k8s.sh
|
||||
```
|
||||
|
||||
### 6. Deploy Git Server
|
||||
|
||||
**Option A: Gitea (Recommended):**
|
||||
```bash
|
||||
./infrastructure/gitops/gitea-deploy.sh
|
||||
```
|
||||
|
||||
**Option B: GitLab CE:**
|
||||
```bash
|
||||
./infrastructure/gitops/gitlab-deploy.sh
|
||||
```
|
||||
|
||||
### 7. Configure GitOps
|
||||
|
||||
1. Create Git repository in your Git server
|
||||
2. Copy `gitops/` directory to repository
|
||||
3. Configure GitOps in Azure Portal or using Flux CLI
|
||||
|
||||
### 8. Deploy HC Stack Services
|
||||
|
||||
Deploy via GitOps (recommended) or manually:
|
||||
```bash
|
||||
# Manual deployment
|
||||
helm install besu ./gitops/apps/besu -n blockchain
|
||||
helm install firefly ./gitops/apps/firefly -n blockchain
|
||||
helm install chainlink-ccip ./gitops/apps/chainlink-ccip -n blockchain
|
||||
helm install blockscout ./gitops/apps/blockscout -n blockchain
|
||||
helm install cacti ./gitops/apps/cacti -n monitoring
|
||||
helm install nginx-proxy ./gitops/apps/nginx-proxy -n hc-stack
|
||||
```
|
||||
|
||||
## Service VM Specifications
|
||||
|
||||
| VM Name | VM ID | IP Address | CPU | RAM | Disk | Purpose |
|
||||
|---------|-------|------------|-----|-----|------|---------|
|
||||
| cloudflare-tunnel | 100 | 192.168.1.60 | 2 | 4GB | 40GB | Cloudflare Tunnel |
|
||||
| k3s-master | 101 | 192.168.1.188 | 4 | 8GB | 80GB | Kubernetes |
|
||||
| git-server | 102 | 192.168.1.121 | 4 | 8GB | 100GB | Git Server |
|
||||
| observability | 103 | 192.168.1.82 | 4 | 8GB | 200GB | Monitoring |
|
||||
|
||||
## Connection Information
|
||||
|
||||
### Proxmox
|
||||
- **ML110**: https://192.168.1.206:8006
|
||||
- **R630**: https://192.168.1.49:8006
|
||||
- **Username**: root@pam
|
||||
- **Password**: (from `.env` file: `PVE_ROOT_PASS`)
|
||||
|
||||
### Cloudflare
|
||||
- **Dashboard**: https://dash.cloudflare.com
|
||||
- **Zero Trust**: https://one.dash.cloudflare.com
|
||||
- **Tunnel Token**: (from `.env` file: `CLOUDFLARE_TUNNEL_TOKEN`)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Proxmox Connection Issues
|
||||
- Verify IP addresses in `.env` file
|
||||
- Check network connectivity: `ping 192.168.1.206`
|
||||
- Accept self-signed certificate in browser
|
||||
|
||||
### VM Creation Issues
|
||||
- Ensure sufficient storage on Proxmox host
|
||||
- Check VM ID availability
|
||||
- Verify network bridge configuration
|
||||
|
||||
### Cloudflare Tunnel Issues
|
||||
- Verify tunnel token in `.env`
|
||||
- Check DNS records in Cloudflare Dashboard
|
||||
- Review tunnel logs: `journalctl -u cloudflared -f`
|
||||
|
||||
## Next Steps
|
||||
|
||||
After completing the quick start:
|
||||
1. Review [Deployment Guide](../deployment/deployment-guide.md) for detailed instructions
|
||||
2. Set up monitoring and alerting
|
||||
3. Configure backup and disaster recovery
|
||||
4. Implement security policies
|
||||
5. Plan for scaling and expansion
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Complete Deployment Guide](../deployment/deployment-guide.md)
|
||||
- [Architecture Overview](../architecture/overview.md)
|
||||
- [Troubleshooting Guide](../troubleshooting/common-issues.md)
|
||||
|
||||
Reference in New Issue
Block a user