diff --git a/user_facing_docs/.hugo_build.lock b/user_facing_docs/.hugo_build.lock new file mode 100644 index 0000000..e69de29 diff --git a/user_facing_docs/archetypes/default.md b/user_facing_docs/archetypes/default.md new file mode 100644 index 0000000..25b6752 --- /dev/null +++ b/user_facing_docs/archetypes/default.md @@ -0,0 +1,5 @@ ++++ +date = '{{ .Date }}' +draft = true +title = '{{ replace .File.ContentBaseName "-" " " | title }}' ++++ diff --git a/user_facing_docs/config.toml b/user_facing_docs/config.toml new file mode 100644 index 0000000..23ed7ee --- /dev/null +++ b/user_facing_docs/config.toml @@ -0,0 +1,46 @@ +baseURL = "/" +languageCode = "en" +title = "User Guide - TheAPI" +theme = "hugo-book" + +[params] + BookTheme = "auto" + BookSearchEnable = true + BookToC = true + BookComments = false + BookRepo = "" + BookEditPath = "" + +[menu] + [[menu.before]] + name = "Home" + url = "/" + weight = 1 + [[menu.before]] + name = "Virtual Machines" + url = "/virtual-machines/" + weight = 2 + [[menu.before]] + name = "Containers" + url = "/containers/" + weight = 3 + [[menu.before]] + name = "Storage" + url = "/storage/" + weight = 4 + [[menu.before]] + name = "Certificates" + url = "/certificates/" + weight = 5 + [[menu.before]] + name = "DNS" + url = "/dns/" + weight = 6 + [[menu.before]] + name = "Networks" + url = "/networks/" + weight = 7 + [[menu.before]] + name = "Cloudflare" + url = "/cloudflare/" + weight = 8 diff --git a/user_facing_docs/content/_index.md b/user_facing_docs/content/_index.md new file mode 100644 index 0000000..c3ecdab --- /dev/null +++ b/user_facing_docs/content/_index.md @@ -0,0 +1,99 @@ +--- +title: Welcome +type: docs +--- + +# User Guide - TheAPI + +Welcome to the comprehensive user documentation for TheAPI, a cloud infrastructure management platform. This guide covers all user-facing features for managing virtual machines, containers, storage, certificates, DNS, networks, and Cloudflare integration. + +## Quick Start + +Get up and running in minutes with these basic steps: + +### 1. Prerequisites + +- API credentials (API key or OAuth token) +- Access to your Virtual Data Center (VDC) +- A project with appropriate permissions + +### 2. Basic Authentication + +All API requests require authentication via API key: + +```bash +# Set your API key +export API_KEY="your-api-key-here" + +# Or use in requests +curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpoints +``` + +### 3. Your First Resource + +Here's how to list all available resources: + +```bash +# List virtual machines +curl -H "Authorization: Bearer $API_KEY" \ + https://api.example.com/workloads/virtual_machines +``` + +### 4. Python Quick Start + +```python +import requests + +API_BASE = "https://api.example.com" +API_KEY = "your-api-key-here" + +headers = { + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json" +} + +# List all VMs +response = requests.get(f"{API_BASE}/workloads/virtual_machines", headers=headers) +print(response.json()) +``` + +## Documentation Overview + +| Category | Description | Key Features | +|----------|-------------|--------------| +| [Virtual Machines](/virtual-machines/) | Provision and manage VMs | Create, delete, start/stop, VNC access, snapshots | +| [Containers](/containers/) | Deploy container workloads | Pods, individual containers, lifecycle management | +| [Storage](/storage/) | Manage persistent volumes | Create, attach, detach, snapshots | +| [Certificates](/certificates/) | Manage TLS certificates | CA management, certificate issuance, revocation | +| [DNS](/dns/) | DNS record management | Custom FQDNs, record types, TTL configuration | +| [Networks](/networks/) | Network infrastructure | Create networks, ports, SDN configuration | +| [Cloudflare](/cloudflare/) | Cloudflare tunnel integration | Tunnel management, DNS records, ingress rules | + +## API Response Format + +All API responses follow a consistent envelope format: + +```json +{ + "version": "1.0", + "success": true, + "code": 200, + "message": "Operation completed successfully", + "data": { + // Response data here + }, + "request_id": "unique-request-id" +} +``` + +## Getting Help + +- **API Reference**: Browse the category sections above +- **Examples**: Copy-paste ready code snippets for each feature +- **Support**: Contact your administrator for access issues + +## Next Steps + +- [Learn about Virtual Machines](/virtual-machines/) - Provision your first VM +- [Explore Containers](/containers/) - Deploy containerized workloads +- [Set up Storage](/storage/) - Create persistent volumes diff --git a/user_facing_docs/content/certificates/_index.md b/user_facing_docs/content/certificates/_index.md new file mode 100644 index 0000000..bd7ce57 --- /dev/null +++ b/user_facing_docs/content/certificates/_index.md @@ -0,0 +1,52 @@ +--- +title: Certificates +type: docs +bookToc: true +--- + +# Certificates + +Manage TLS certificates and Certificate Authorities (CA) for secure communication. Issue, revoke, and download certificates for your services. + +## What Are Certificates? + +TLS certificates enable encrypted HTTPS connections and verify server identity. The platform supports internal Certificate Authorities for issuing certificates within your organization. + +## Key Capabilities + +- **Certificate Authorities**: Create and manage internal CAs +- **Certificate Issuance**: Issue certificates from your CA +- **Certificate Revocation**: Revoke compromised certificates +- **CRL Support**: Certificate Revocation Lists +- **Download Options**: Get certificates, private keys, and public keys + +## API Endpoints + +### Certificate Authorities + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/certificates/ca/project/` | GET | Get project CA | +| `/certificates/ca/project/` | POST | Create CA for project | +| `/certificates/ca/` | GET | Get CA details | +| `/certificates/ca/` | PUT | Update CA | +| `/certificates/ca//download` | GET | Download CA cert/key | +| `/certificates/ca` | GET | List all CAs | + +### Certificates + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/certificates/issue` | POST | Issue new certificate | +| `/certificates/cert/ca/` | GET | List certificates for CA | +| `/certificates/cert/` | GET | Get certificate details | +| `/certificates/cert/` | PUT | Update certificate | +| `/certificates/cert//revoke` | POST | Revoke certificate | +| `/certificates/cert//download` | GET | Download cert/key | +| `/certificates/cert/project/` | GET | List project certificates | +| `/certificates/crl/` | GET | Get CRL for CA | + +## Related Resources + +- [Certificate Authorities](/certificates/ca/) - Create and manage CAs +- [Certificate Issuance](/certificates/issuance/) - Issue and manage certificates diff --git a/user_facing_docs/content/certificates/ca.md b/user_facing_docs/content/certificates/ca.md new file mode 100644 index 0000000..5048d64 --- /dev/null +++ b/user_facing_docs/content/certificates/ca.md @@ -0,0 +1,79 @@ +--- +title: Certificate Authorities +type: docs +--- + +# Certificate Authorities + +Create and manage internal Certificate Authorities for issuing certificates within your organization. + +## Create a CA + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| project_id | UUID | Project to create CA for | + +## Examples + +### Bash - Create CA + +```bash +curl -X POST "https://api.example.com/certificates/ca/project/project-uuid-here" \ + -H "Authorization: Bearer $API_KEY" +``` + +### Python - Create and Download CA + +```python +# Create CA +response = requests.post( + f"{API_BASE}/certificates/ca/project/project-uuid-here", + headers=headers +) + +if response.json()["success"]: + ca_id = response.json()["data"]["ca"]["id"] + print(f"CA created: {ca_id}") + + # Download CA certificate + cert_response = requests.get( + f"{API_BASE}/certificates/ca/{ca_id}/download?type=certificate", + headers=headers + ) + with open("ca-cert.pem", "w") as f: + f.write(cert_response.text) +``` + +## List All CAs + +```bash +curl -X GET "https://api.example.com/certificates/ca" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Get CA Details + +```bash +curl -X GET "https://api.example.com/certificates/ca/ca-uuid-here" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Download CA Certificate or Key + +```bash +# Download CA certificate +curl -O "https://api.example.com/certificates/ca/ca-uuid-here/download?type=certificate" \ + -H "Authorization: Bearer $API_KEY" + +# Download CA private key (keep secure!) +curl -O "https://api.example.com/certificates/ca/ca-uuid-here/download?type=private_key" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Use Cases + +1. **Internal PKI**: Create organization-wide CA for internal services +2. **Service Mesh**: Issue certificates for microservices +3. **Development**: Separate CA for development environments diff --git a/user_facing_docs/content/certificates/issuance.md b/user_facing_docs/content/certificates/issuance.md new file mode 100644 index 0000000..e7a245c --- /dev/null +++ b/user_facing_docs/content/certificates/issuance.md @@ -0,0 +1,105 @@ +--- +title: Certificate Issuance +type: docs +--- + +# Certificate Issuance + +Issue, manage, and revoke certificates from your Certificate Authorities. + +## Issue a Certificate + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| ca_id | UUID | CA to issue from | +| common_name | string | Certificate CN | +| validity_days | number | Certificate validity | +| alt_names | array | SAN entries | + +## Examples + +### Bash - Issue Certificate + +```bash +curl -X POST "https://api.example.com/certificates/issue" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "ca_id": "ca-uuid-here", + "common_name": "app.example.com", + "validity_days": 365, + "alt_names": ["www.example.com", "api.example.com"] + }' +``` + +### Python - Issue and Download Certificate + +```python +cert_request = { + "ca_id": "ca-uuid-here", + "common_name": "app.example.com", + "validity_days": 365, + "alt_names": ["www.example.com", "api.example.com"] +} + +response = requests.post( + f"{API_BASE}/certificates/issue", + json=cert_request, + headers=headers +) + +if response.json()["success"]: + cert_id = response.json()["data"]["certificate"]["id"] + + # Download certificate + cert_response = requests.get( + f"{API_BASE}/certificates/cert/{cert_id}/download?type=certificate", + headers=headers + ) + with open("server-cert.pem", "w") as f: + f.write(cert_response.text) + + # Download private key + key_response = requests.get( + f"{API_BASE}/certificates/cert/{cert_id}/download?type=private_key", + headers=headers + ) + with open("server-key.pem", "w") as f: + f.write(key_response.text) +``` + +## List Certificates for CA + +```bash +curl -X GET "https://api.example.com/certificates/cert/ca/ca-uuid-here" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Get Certificate Details + +```bash +curl -X GET "https://api.example.com/certificates/cert/cert-uuid-here" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Revoke Certificate + +```bash +curl -X POST "https://api.example.com/certificates/cert/cert-uuid-here/revoke" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Get Certificate Revocation List + +```bash +curl -X GET "https://api.example.com/certificates/crl/ca-uuid-here" \ + -H "Authorization: Bearer $API_KEY" +``` + +## Use Cases + +1. **Web Server TLS**: Issue certificates for HTTPS servers +2. **API Authentication**: Client certificates for mTLS +3. **Service-to-Service**: Certificates for internal services diff --git a/user_facing_docs/content/cloudflare/_index.md b/user_facing_docs/content/cloudflare/_index.md new file mode 100644 index 0000000..ef08eba --- /dev/null +++ b/user_facing_docs/content/cloudflare/_index.md @@ -0,0 +1,18 @@ +--- +title: "Cloudflare" +description: "Cloudflare integration and configuration" +icon: "cloud" +--- + +# Cloudflare + +Manage Cloudflare integration for your infrastructure, including tunnels and DNS management. + +## Available Guides + +- [Tunnels](tunnels) - Secure tunnel configuration +- [DNS](dns) - DNS record management + +## Getting Started + +Cloudflare provides secure connectivity and DNS management for your services. diff --git a/user_facing_docs/content/cloudflare/dns.md b/user_facing_docs/content/cloudflare/dns.md new file mode 100644 index 0000000..b4fccc0 --- /dev/null +++ b/user_facing_docs/content/cloudflare/dns.md @@ -0,0 +1,232 @@ +--- +title: "Cloudflare DNS" +description: "DNS record management through Cloudflare" +--- + +# Cloudflare DNS + +Manage DNS records for your domains using Cloudflare's DNS interface. + +## DNS Record Types + +### A Record + +Maps a domain to an IPv4 address. + +```bash +# Create A record +cloudflare dns record create example.com \ + --type A \ + --name www \ + --content 192.0.2.1 \ + --ttl 3600 +``` + +### AAAA Record + +Maps a domain to an IPv6 address. + +```bash +# Create AAAA record +cloudflare dns record create example.com \ + --type AAAA \ + --name www \ + --content 2001:db8::1 \ + --ttl 3600 +``` + +### CNAME Record + +Maps a domain to another domain. + +```bash +# Create CNAME record +cloudflare dns record create example.com \ + --type CNAME \ + --name www \ + --content example.net \ + --ttl 3600 +``` + +### MX Record + +Specifies mail servers for the domain. + +```bash +# Create MX record +cloudflare dns record create example.com \ + --type MX \ + --name @ \ + --content mail1.example.com \ + --priority 10 + +cloudflare dns record create example.com \ + --type MX \ + --name @ \ + --content mail2.example.com \ + --priority 20 +``` + +### TXT Record + +Stores text-based records. + +```bash +# Create TXT record for verification +cloudflare dns record create example.com \ + --type TXT \ + --name @ \ + --content "verification=abc123" +``` + +### SRV Record + +Specifies services. + +```bash +# Create SRV record +cloudflare dns record create example.com \ + --type SRV \ + --name _sip._tcp \ + --content "10 60 5060 sip.example.com" +``` + +### CAA Record + +Specifies certificate authorities. + +```bash +# Create CAA record +cloudflare dns record create example.com \ + --type CAA \ + --name @ \ + --content "0 issue letsencrypt.org" +``` + +## Managing Records + +### List Records + +```bash +# List all DNS records +cloudflare dns record list example.com +``` + +### Update Records + +```bash +# Update A record +cloudflare dns record update example.com \ + --type A \ + --name www \ + --content 192.0.2.2 +``` + +### Delete Records + +```bash +# Delete a record +cloudflare dns record delete example.com --type A --name www +``` + +### Import Records + +```bash +# Import from BIND zone file +cloudflare dns record import example.com --zone-file zone.txt +``` + +### Export Records + +```bash +# Export to BIND zone file +cloudflare dns record export example.com --zone-file backup.txt +``` + +## DNS Settings + +### DNSSEC + +Enable DNSSEC for your domain: + +```bash +# Enable DNSSEC +cloudflare dnssec enable example.com + +# View DNSSEC status +cloudflare dnssec status example.com +``` + +### Proxy Status + +Control Cloudflare proxy (orange cloud): + +```bash +# Enable proxy (orange cloud on) +cloudflare dns record update example.com \ + --type A \ + --name www \ + --content 192.0.2.1 \ + --proxy + +# Disable proxy (orange cloud off) +cloudflare dns record update example.com \ + --type A \ + --name www \ + --content 192.0.2.1 \ + --no-proxy +``` + +### TTL (Time to Live) + +Configure record TTL: + +```bash +# Set TTL to 1 hour +cloudflare dns record update example.com \ + --type A \ + --name www \ + --content 192.0.2.1 \ + --ttl 3600 + +# Use automatic TTL (Cloudflare manages) +cloudflare dns record update example.com \ + --type A \ + --name www \ + --content 192.0.2.1 \ + --ttl 1 +``` + +## Bulk Operations + +### Create Multiple Records + +```bash +# Create records from CSV +cloudflare dns record bulk create example.com records.csv +``` + +CSV format: +```csv +type,name,content,ttl +A,www,192.0.2.1,3600 +A,api,192.0.2.2,3600 +CNAME,blog,example.net,3600 +``` + +### Delete Multiple Records + +```bash +# Delete records from CSV +cloudflare dns record bulk delete example.com records-to-delete.csv +``` + +## Best Practices + +1. Use CNAME for subdomains pointing to other domains +2. Set appropriate TTL values (lower for frequent changes) +3. Enable DNSSEC for security +4. Use Cloudflare proxy for HTTP/HTTPS traffic +5. Keep records organized with consistent naming +6. Document DNS changes +7. Regular audit of unused records diff --git a/user_facing_docs/content/cloudflare/tunnels.md b/user_facing_docs/content/cloudflare/tunnels.md new file mode 100644 index 0000000..264a3e7 --- /dev/null +++ b/user_facing_docs/content/cloudflare/tunnels.md @@ -0,0 +1,181 @@ +--- +title: "Cloudflare Tunnels" +description: "Secure tunnel configuration with Cloudflare" +--- + +# Cloudflare Tunnels + +Cloudflare Tunnels provide a secure way to expose your internal services to the internet without opening ports. + +## What is Cloudflare Tunnel? + +Cloudflare Tunnel (formerly Argo Tunnel) creates a secure connection between your origin server and Cloudflare's network, eliminating the need for public IP addresses. + +## Setup + +### Prerequisites + +1. A Cloudflare account +2. A domain configured in Cloudflare +3. Cloudflare daemon (cloudflared) installed + +### Installation + +**Linux (systemd):** + +```bash +# Download cloudflared +wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 + +# Make executable +chmod +x cloudflared-linux-amd64 + +# Move to PATH +sudo mv cloudflared-linux-amd64 /usr/local/bin/cloudflared +``` + +**Docker:** + +```bash +docker pull cloudflare/cloudflared:latest +``` + +### Authentication + +```bash +# Authenticate with Cloudflare +cloudflared tunnel login + +# This will open a browser for OAuth +``` + +## Creating a Tunnel + +### Create Tunnel + +```bash +# Create a new tunnel +cloudflared tunnel create my-tunnel + +# Save the credentials file path +``` + +### Configure Tunnel + +Create a config.yaml file: + +```yaml +tunnel: +credentials-file: /path/to/credentials.json + +ingress: + - hostname: app.example.com + service: http://localhost:8080 + + - hostname: api.example.com + service: http://localhost:3000 + + - service: http_status:404 +``` + +### Run Tunnel + +**As a Service:** + +```bash +# Create systemd service +sudo cloudflared service install + +# Start the tunnel +cloudflared tunnel run my-tunnel +``` + +**Docker:** + +```bash +docker run -d \ + --name cloudflared \ + -v /path/credentials.json:/etc/cloudflared/creds.json \ + cloudflare/cloudflared:latest \ + tunnel --config /etc/cloudflared/config.yml run my-tunnel +``` + +## Tunnel Management + +### View Tunnels + +```bash +# List all tunnels +cloudflared tunnel list +``` + +### Delete Tunnel + +```bash +# Delete tunnel (does not remove DNS records) +cloudflared tunnel delete my-tunnel +``` + +### Update Configuration + +Edit the config file and restart the tunnel: + +```bash +# Restart the tunnel +cloudflared tunnel run my-tunnel +``` + +## Advanced Configuration + +### HTTP Load Balancing + +```yaml +ingress: + - hostname: app.example.com + service: http://localhost:8080 + originRequest: + connectTimeout: 10s + tlsTimeout: 10s + noTLSVerify: false + + - service: http_status:404 +``` + +### TCP Routing + +```yaml +ingress: + - hostname: ssh.example.com + service: ssh://localhost:22 + + - service: http_status:404 +``` + +### Websockets + +Cloudflare Tunnels automatically support WebSocket connections. + +## Troubleshooting + +### Check Tunnel Status + +```bash +# View tunnel logs +cloudflared tunnel log my-tunnel + +# Follow logs in real-time +cloudflared tunnel log my-tunnel -f +``` + +### Test Configuration + +```bash +# Validate config file +cloudflared tunnel validate config.yml +``` + +### Common Issues + +1. **Authentication failed**: Re-run `cloudflared tunnel login` +2. **Connection refused**: Check that the local service is running +3. **DNS not resolving**: Verify DNS records are created diff --git a/user_facing_docs/content/containers/_index.md b/user_facing_docs/content/containers/_index.md new file mode 100644 index 0000000..865eb75 --- /dev/null +++ b/user_facing_docs/content/containers/_index.md @@ -0,0 +1,19 @@ +--- +title: "Containers" +description: "Deploy and manage container workloads" +icon: "box" +--- + +# Containers + +Deploy and manage containerized applications on your infrastructure. + +## Available Guides + +- [Pods](pods) - Pod management and configuration +- [Containers](containers) - Container instance management +- [Deployment](deploy) - Deploy applications + +## Getting Started + +Containers provide a lightweight, portable way to run your applications. Use this section to learn how to create and manage container workloads. diff --git a/user_facing_docs/content/containers/containers.md b/user_facing_docs/content/containers/containers.md new file mode 100644 index 0000000..a1d6032 --- /dev/null +++ b/user_facing_docs/content/containers/containers.md @@ -0,0 +1,121 @@ +--- +title: "Container Instances" +description: "Container instance management" +--- + +# Container Instances + +Individual container instances provide the foundation for running your applications. + +## Creating Containers + +### Basic Container + +```bash +# Create a basic nginx container +docker run -d --name my-nginx nginx:latest +``` + +### Container with Environment Variables + +```bash +docker run -d \ + --name my-app \ + -e NODE_ENV=production \ + -e PORT=3000 \ + my-node-app:latest +``` + +### Container with Volume Mount + +```bash +docker run -d \ + --name my-app \ + -v /host/path:/container/path \ + my-app:latest +``` + +## Managing Containers + +### Start and Stop + +```bash +# Start a container +docker start + +# Stop a container +docker stop + +# Restart a container +docker restart +``` + +### View Container Status + +```bash +# List running containers +docker ps + +# List all containers (including stopped) +docker ps -a + +# View container logs +docker logs + +# Follow logs in real-time +docker logs -f +``` + +### Inspect Container + +```bash +# View detailed container information +docker inspect + +# View container resources (CPU, memory) +docker stats +``` + +## Container Networking + +### Port Mapping + +```bash +# Map host port 8080 to container port 80 +docker run -d -p 8080:80 nginx:latest +``` + +### Network Modes + +- **bridge** - Default network mode +- **host** - Use host network directly +- **none** - No networking + +## Resource Management + +### Memory Limits + +```bash +# Set memory limit to 512MB +docker run -m 512m my-app:latest +``` + +### CPU Limits + +```bash +# Limit to 2 CPUs +docker run --cpus=2 my-app:latest +``` + +## Cleanup + +```bash +# Remove stopped container +docker rm + +# Remove container and associated volumes +docker rm -v + +# Remove all stopped containers +docker container prune +``` diff --git a/user_facing_docs/content/containers/deploy.md b/user_facing_docs/content/containers/deploy.md new file mode 100644 index 0000000..298ab35 --- /dev/null +++ b/user_facing_docs/content/containers/deploy.md @@ -0,0 +1,171 @@ +--- +title: "Container Deployment" +description: "Deploy applications using containers" +--- + +# Container Deployment + +Learn how to deploy applications using containers with various strategies and configurations. + +## Deployment Strategies + +### Rolling Updates + +Gradually replace old containers with new ones, ensuring zero downtime. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app +spec: + replicas: 3 + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + selector: + matchLabels: + app: my-app + template: + metadata: + labels: + app: my-app + spec: + containers: + - name: my-app + image: my-app:v2 +``` + +### Blue-Green Deployment + +Run two versions simultaneously and switch traffic. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app-blue +spec: + replicas: 3 + selector: + matchLabels: + app: my-app + version: blue + template: + spec: + containers: + - name: my-app + image: my-app:v1 +``` + +### Canary Deployment + +Route a small percentage of traffic to the new version. + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: my-app + annotations: + nginx.ingress.kubernetes.io/canary: "true" + nginx.ingress.kubernetes.io/canary-weight: "10" +spec: + rules: + - host: myapp.example.com +``` + +## Multi-Container Patterns + +### Sidecar Pattern + +Deploy auxiliary containers alongside the main application. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: app-with-sidecar +spec: + containers: + - name: main-app + image: my-app:latest + - name: sidecar + image: log-shipper:latest +``` + +### Ambassador Pattern + +Use a container to mediate access to external services. + +### Adapter Pattern + +Standardize output from the main container. + +## Health Checks + +### Liveness Probe + +```yaml +spec: + containers: + - name: my-app + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 +``` + +### Readiness Probe + +```yaml +spec: + containers: + - name: my-app + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 5 +``` + +## Scaling + +### Horizontal Pod Autoscaling + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: my-app-hpa +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: my-app + minReplicas: 2 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 +``` + +## Deployment Best Practices + +1. Use semantic versioning for images +2. Implement health checks +3. Set resource requests and limits +4. Use secrets for sensitive data +5. Implement proper logging +6. Use ConfigMaps for configuration +7. Plan for rollback scenarios +8. Use CI/CD pipelines for automated deployments diff --git a/user_facing_docs/content/containers/pods.md b/user_facing_docs/content/containers/pods.md new file mode 100644 index 0000000..34e5390 --- /dev/null +++ b/user_facing_docs/content/containers/pods.md @@ -0,0 +1,62 @@ +--- +title: "Pods" +description: "Pod management and configuration" +--- + +# Pods + +Pods are the smallest deployable units of computing that you can create and manage in Kubernetes. + +## What is a Pod? + +A Pod is a group of one or more containers, with shared storage and network resources, and a specification for how to run the containers. + +## Pod Configuration + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: example-pod +spec: + containers: + - name: main-container + image: nginx:latest + ports: + - containerPort: 80 +``` + +## Managing Pods + +### Create a Pod + +Pods are typically created through Deployments rather than directly, but you can create standalone pods for testing purposes. + +### View Pod Status + +```bash +# List all pods +kubectl get pods + +# Get detailed pod information +kubectl describe pod + +# View pod logs +kubectl logs +``` + +## Pod Lifecycle + +1. **Pending** - Pod has been accepted but containers not yet running +2. **Running** - Pod is bound to a node and at least one container is running +3. **Succeeded** - All containers terminated successfully +4. **Failed** - At least one container failed +5. **Unknown** - Pod state cannot be determined + +## Best Practices + +- Use Deployments for production workloads +- Set appropriate resource limits +- Use health checks (liveness and readiness probes) +- Store configuration in ConfigMaps +- Store sensitive data in Secrets diff --git a/user_facing_docs/content/dns/_index.md b/user_facing_docs/content/dns/_index.md new file mode 100644 index 0000000..9e39212 --- /dev/null +++ b/user_facing_docs/content/dns/_index.md @@ -0,0 +1,17 @@ +--- +title: "DNS" +description: "DNS management and configuration" +icon: "globe" +--- + +# DNS + +Manage DNS records and domains for your infrastructure. + +## Available Guides + +- [DNS Records](records) - Record types and management + +## Getting Started + +DNS (Domain Name System) translates domain names to IP addresses. Use this section to configure and manage your DNS settings. diff --git a/user_facing_docs/content/dns/records.md b/user_facing_docs/content/dns/records.md new file mode 100644 index 0000000..020e704 --- /dev/null +++ b/user_facing_docs/content/dns/records.md @@ -0,0 +1,232 @@ +--- +title: "DNS Records" +description: "DNS record types and management" +--- + +# DNS Records + +Learn about different DNS record types and how to manage them. + +## Record Types + +### A Record + +Maps a domain name to an IPv4 address. + +``` +Type: A +Purpose: IPv4 address mapping +Example: example.com -> 192.0.2.1 +``` + +### AAAA Record + +Maps a domain name to an IPv6 address. + +``` +Type: AAAA +Purpose: IPv6 address mapping +Example: example.com -> 2001:db8::1 +``` + +### CNAME Record + +Creates an alias pointing to another domain name. + +``` +Type: CNAME +Purpose: Domain alias +Example: www.example.com -> example.com +Restrictions: Cannot be used for the apex domain (@) +``` + +### MX Record + +Specifies mail servers for receiving email. + +``` +Type: MX +Purpose: Mail server routing +Example: example.com -> mail.example.com +Priority: Lower value = higher priority +``` + +### TXT Record + +Stores arbitrary text data. + +``` +Type: TXT +Purpose: Verification, SPF, DKIM, etc. +Example: "v=spf1 include:_spf.example.com ~all" +``` + +### NS Record + +Delegates a domain to a name server. + +``` +Type: NS +Purpose: Name server delegation +Example: example.com -> ns1.example.com +``` + +### SRV Record + +Specifies a service location. + +``` +Type: SRV +Purpose: Service location +Example: _sip._tcp.example.com -> 10 60 5060 sip.example.com +Format: priority weight port target +``` + +### CAA Record + +Specifies which CAs can issue certificates. + +``` +Type: CAA +Purpose: Certificate authority authorization +Example: example.com -> 0 issue letsencrypt.org +``` + +### PTR Record + +Maps an IP address to a domain name (reverse DNS). + +``` +Type: PTR +Purpose: Reverse DNS lookup +Example: 1.2.3.4.in-addr.arpa -> example.com +``` + +## Creating Records + +### API Request + +```json +POST /api/dns/records +{ + "domain": "example.com", + "type": "A", + "name": "www", + "content": "192.0.2.1", + "ttl": 3600, + "proxied": false +} +``` + +### Response + +```json +{ + "success": true, + "data": { + "id": "record-123", + "domain": "example.com", + "type": "A", + "name": "www", + "content": "192.0.2.1", + "ttl": 3600, + "proxied": false, + "created_at": "2024-01-01T00:00:00Z" + } +} +``` + +## Managing Records + +### Listing Records + +```bash +# List all records for a domain +GET /api/dns/records?domain=example.com +``` + +### Updating Records + +```bash +# Update a record +PUT /api/dns/records/{record_id} +{ + "content": "192.0.2.2", + "ttl": 7200 +} +``` + +### Deleting Records + +```bash +# Delete a record +DELETE /api/dns/records/{record_id} +``` + +## Propagation + +### Understanding Propagation + +DNS changes can take time to propagate globally due to TTL values and caching. + +### Checking Propagation + +```bash +# Check DNS resolution +dig www.example.com + +# Check from specific nameserver +dig @ns1.example.com www.example.com + +# Use online tools +# - https://dnschecker.org +# - https://www.whatsmydns.net +``` + +### TTL Considerations + +- **Low TTL** (300s): Faster propagation, more queries to nameserver +- **High TTL** (86400s): Slower propagation, fewer queries +- **Recommended**: Use 3600s (1 hour) as default + +## Common Configurations + +### Website + +``` +example.com A 192.0.2.1 +www.example.com CNAME example.com +``` + +### Mail Server + +``` +example.com MX 10 mail.example.com +mail.example.com A 192.0.2.2 +example.com TXT "v=spf1 include:_spf.example.com ~all" +_dmarc.example.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com" +``` + +### Load Balancer + +``` +app.example.com A 192.0.2.10 +app.example.com A 192.0.2.11 +app.example.com A 192.0.2.12 +``` + +## Troubleshooting + +### Common Issues + +1. **Record not resolving**: Check TTL and propagation +2. **CNAME conflict**: Cannot have CNAME at apex with other records +3. **MX priority**: Ensure priority values are correct +4. **TXT record length**: Split long records if needed + +### Tools + +- `dig` - Command-line DNS lookup +- `nslookup` - DNS query tool +- `whois` - Domain registration info +- Online DNS lookup tools diff --git a/user_facing_docs/content/networks/_index.md b/user_facing_docs/content/networks/_index.md new file mode 100644 index 0000000..e5d56b1 --- /dev/null +++ b/user_facing_docs/content/networks/_index.md @@ -0,0 +1,18 @@ +--- +title: "Networks" +description: "Network configuration and management" +icon: "network" +--- + +# Networks + +Configure and manage network resources for your infrastructure. + +## Available Guides + +- [Create Network](create) - Creating new networks +- [Ports](ports) - Port configuration and forwarding + +## Getting Started + +Networks provide the connectivity foundation for your workloads. Use this section to set up and manage network resources. diff --git a/user_facing_docs/content/networks/create.md b/user_facing_docs/content/networks/create.md new file mode 100644 index 0000000..b086b10 --- /dev/null +++ b/user_facing_docs/content/networks/create.md @@ -0,0 +1,235 @@ +--- +title: "Create Network" +description: "Creating new network resources" +--- + +# Create Network + +Learn how to create and configure network resources for your infrastructure. + +## Network Types + +### Private Network + +Isolated network internal to your infrastructure. + +```json +{ + "name": "my-private-network", + "type": "private", + "cidr": "10.0.0.0/16", + "subnet": "10.0.1.0/24" +} +``` + +### Public Network + +Network with internet access. + +```json +{ + "name": "my-public-network", + "type": "public", + "cidr": "203.0.113.0/24" +} +``` + +### VPC (Virtual Private Cloud) + +Isolated network with custom routing. + +```json +{ + "name": "my-vpc", + "type": "vpc", + "cidr": "172.16.0.0/16", + "subnets": [ + { + "name": "subnet-a", + "cidr": "172.16.1.0/24", + "availability_zone": "us-east-1a" + }, + { + "name": "subnet-b", + "cidr": "172.16.2.0/24", + "availability_zone": "us-east-1b" + } + ] +} +``` + +## Creating a Network + +### API Request + +```bash +POST /api/networks +Content-Type: application/json + +{ + "name": "production-network", + "description": "Production network for web servers", + "cidr": "10.1.0.0/16", + "gateway": "10.1.0.1", + "dns_servers": ["10.1.0.2", "10.1.0.3"], + "tags": { + "environment": "production", + "team": "platform" + } +} +``` + +### Response + +```json +{ + "success": true, + "data": { + "id": "net-abc123", + "name": "production-network", + "cidr": "10.1.0.0/16", + "gateway": "10.1.0.1", + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } +} +``` + +## Subnet Configuration + +### Creating Subnets + +```json +{ + "network_id": "net-abc123", + "subnets": [ + { + "name": "web-subnet", + "cidr": "10.1.1.0/24", + "gateway": "10.1.1.1", + "available_ips": 251 + }, + { + "name": "app-subnet", + "cidr": "10.1.2.0/24", + "gateway": "10.1.2.1", + "available_ips": 251 + }, + { + "name": "db-subnet", + "cidr": "10.1.3.0/24", + "gateway": "10.1.3.1", + "available_ips": 251 + } + ] +} +``` + +### Subnet Allocation + +- **/24 subnet**: 251 usable IPs +- **/25 subnet**: 125 usable IPs +- **/26 subnet**: 61 usable IPs +- **/28 subnet**: 13 usable IPs + +## Network Security + +### Security Groups + +```json +{ + "name": "web-security-group", + "rules": [ + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "80", + "cidr": "0.0.0.0/0" + }, + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "443", + "cidr": "0.0.0.0/0" + }, + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "22", + "cidr": "10.0.0.0/8" + } + ] +} +``` + +### Network ACLs + +```json +{ + "name": "web-subnet-acl", + "rules": [ + { + "rule_number": 100, + "direction": "ingress", + "protocol": "tcp", + "port_range": "80-80", + "cidr": "0.0.0.0/0", + "action": "allow" + }, + { + "rule_number": 200, + "direction": "egress", + "protocol": "tcp", + "port_range": "1024-65535", + "cidr": "0.0.0.0/0", + "action": "allow" + } + ] +} +``` + +## DHCP and DNS + +### DHCP Options + +```json +{ + "network_id": "net-abc123", + "dhcp_options": { + "domain_name": "example.com", + "domain_name_servers": ["10.1.0.2", "8.8.8.8"], + "ntp_servers": ["10.1.0.2"], + "netbios_name_servers": ["10.1.0.2"] + } +} +``` + +## Network Monitoring + +### View Network Details + +```bash +GET /api/networks/{network_id} +``` + +### List Networks + +```bash +GET /api/networks?status=active +``` + +### View Network Topology + +```bash +GET /api/networks/{network_id}/topology +``` + +## Best Practices + +1. **Plan CIDR ranges** - Avoid overlapping with other networks +2. **Use appropriate subnet sizes** - Don't over-provision +3. **Implement security groups** - Least privilege access +4. **Enable monitoring** - Track network performance +5. **Document network architecture** - Maintain clear diagrams +6. **Use naming conventions** - Consistent naming for easy identification +7. **Regular review** - Audit network security regularly diff --git a/user_facing_docs/content/networks/ports.md b/user_facing_docs/content/networks/ports.md new file mode 100644 index 0000000..b567377 --- /dev/null +++ b/user_facing_docs/content/networks/ports.md @@ -0,0 +1,247 @@ +--- +title: "Ports" +description: "Port configuration and forwarding" +--- + +# Ports + +Configure port access and forwarding for your network resources. + +## Port Concepts + +### Port Numbers + +- **Well-known ports** (0-1023): System services (HTTP: 80, HTTPS: 443, SSH: 22) +- **Registered ports** (1024-49151): User applications +- **Dynamic/private ports** (49152-65535): Temporary connections + +### Common Ports + +| Service | Port | Protocol | +|---------|------|----------| +| HTTP | 80 | TCP | +| HTTPS | 443 | TCP | +| SSH | 22 | TCP | +| FTP | 21 | TCP | +| SMTP | 25 | TCP | +| DNS | 53 | UDP/TCP | +| MySQL | 3306 | TCP | +| PostgreSQL | 5432 | TCP | +| Redis | 6379 | TCP | +| MongoDB | 27017 | TCP | + +## Port Configuration + +### Opening Ports + +```bash +# API request to open a port +POST /api/networks/{network_id}/ports +{ + "port": 8080, + "protocol": "tcp", + "description": "Application web interface", + "source_cidr": "0.0.0.0/0" +} +``` + +### Closing Ports + +```bash +# Close a port +DELETE /api/networks/{network_id}/ports/{port_id} +``` + +### Modifying Port Rules + +```bash +# Update port configuration +PUT /api/networks/{network_id}/ports/{port_id} +{ + "description": "Updated description", + "source_cidr": "10.0.0.0/8" +} +``` + +## Port Forwarding + +### Configure Port Forwarding + +```bash +# Set up port forwarding from external to internal +POST /api/networks/{network_id}/port-forwarding +{ + "external_port": 8080, + "internal_port": 80, + "protocol": "tcp", + "target_ip": "10.1.1.100" +} +``` + +### Port Forwarding Examples + +**HTTP to internal web server:** + +``` +External Port: 8080 -> Internal IP: 10.1.1.10:80 +``` + +**SSH to internal server:** + +``` +External Port: 2222 -> Internal IP: 10.1.1.20:22 +``` + +**Database access:** + +``` +External Port: 3306 -> Internal IP: 10.1.1.30:3306 +``` + +## Security Groups for Ports + +### Create Security Group with Port Rules + +```bash +POST /api/security-groups +{ + "name": "web-server-sg", + "description": "Security group for web servers", + "rules": [ + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "80", + "cidr": "0.0.0.0/0" + }, + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "443", + "cidr": "0.0.0.0/0" + }, + { + "direction": "ingress", + "protocol": "tcp", + "port_range": "22", + "cidr": "10.0.0.0/8" + } + ] +} +``` + +### Port Ranges + +```json +{ + "rules": [ + { + "protocol": "tcp", + "port_range": "8000-9000", + "cidr": "10.0.0.0/8" + } + ] +} +``` + +## Firewall Rules + +### Configure Firewall + +```bash +# Add firewall rule +POST /api/firewall/rules +{ + "network_id": "net-abc123", + "rule": { + "action": "allow", + "direction": "ingress", + "protocol": "tcp", + "port": 443, + "source": "0.0.0.0/0" + } +} +``` + +### Default Policies + +```json +{ + "default_ingress": "deny", + "default_egress": "allow", + "rules": [ + { + "action": "allow", + "direction": "egress", + "protocol": "tcp", + "port": 443, + "destination": "0.0.0.0/0" + }, + { + "action": "allow", + "direction": "egress", + "protocol": "udp", + "port": 53, + "destination": "0.0.0.0/0" + } + ] +} +``` + +## Port Scanning and Testing + +### Test Port Accessibility + +```bash +# Check if port is open +nc -zv example.com 80 + +# Scan port range +nmap -p 1-1000 example.com + +# Check specific port +telnet example.com 22 +``` + +### Local Port Testing + +```bash +# Listen on port +nc -l 8080 + +# Connect to port +nc localhost 8080 +``` + +## Troubleshooting + +### Common Issues + +1. **Port not accessible**: Check security group rules and firewall +2. **Connection timeout**: Verify network routing +3. **Connection refused**: Ensure service is running on target port +4. **Permission denied**: Check port number (below 1024 may require root) + +### Diagnostic Commands + +```bash +# List listening ports +netstat -tuln +ss -tuln + +# Check port usage +lsof -i :8080 + +# Test connectivity +curl -v http://localhost:8080 +``` + +## Best Practices + +1. **Minimize open ports** - Only open necessary ports +2. **Use security groups** - Restrict source IP ranges +3. **Use non-standard ports** - Change defaults for sensitive services +4. **Implement rate limiting** - Protect against brute force +5. **Monitor port activity** - Log access attempts +6. **Regular audits** - Review open ports periodically +7. **Use HTTPS** - Encrypt traffic on web services diff --git a/user_facing_docs/content/projects/_index.md b/user_facing_docs/content/projects/_index.md new file mode 100644 index 0000000..21b0e5a --- /dev/null +++ b/user_facing_docs/content/projects/_index.md @@ -0,0 +1,63 @@ +--- +title: Projects +type: docs +bookToc: true +--- + +# Projects + +Organize and manage your resources within projects. Projects provide logical grouping for workloads, storage, and configurations. + +## What Are Projects? + +Projects are organizational units that group related resources together. They help you manage access control, billing, and resource allocation across different teams or applications. + +## Key Capabilities + +- **Resource Grouping**: Group VMs, containers, volumes, and networks +- **Access Control**: Manage permissions at project level +- **Certificate Authorities**: Each project can have its own CA +- **Isolation**: Separate configurations per project + +## API Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/projects` | POST | Create project | +| `/projects` | GET | List all projects | +| `/projects/` | GET | Get project details | +| `/projects/` | PUT | Update project | +| `/projects/` | DELETE | Delete project | + +## Examples + +### Bash - Create Project + +```bash +curl -X POST "https://api.example.com/projects" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "production-environment", + "description": "Production workloads" + }' +``` + +### Python - List Projects + +```python +response = requests.get( + f"{API_BASE}/projects", + headers=headers +) + +for project in response.json()["data"]["projects"]: + print(f"{project['name']} - {project['id']}") +``` + +## Use Cases + +1. **Team Organization**: Group resources by team +2. **Environment Separation**: Dev, staging, production +3. **Customer Segmentation**: Separate resources per customer +4. **Application Grouping**: Group related microservices diff --git a/user_facing_docs/content/regions/_index.md b/user_facing_docs/content/regions/_index.md new file mode 100644 index 0000000..2864d36 --- /dev/null +++ b/user_facing_docs/content/regions/_index.md @@ -0,0 +1,58 @@ +--- +title: Regions +type: docs +bookToc: true +--- + +# Regions + +Manage geographic regions for your infrastructure. Regions provide geographic distribution and high availability. + +## What Are Regions? + +Regions represent distinct geographic locations where your resources can be deployed. Each region typically contains its own compute, storage, and network infrastructure. + +## Key Capabilities + +- **Geographic Distribution**: Deploy resources in different locations +- **Failover Control**: Pause/resume failover between regions +- **Region Access**: Manage which projects can access which regions +- **High Availability**: Distribute workloads across regions + +## API Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/regions` | POST | Create region | +| `/regions` | GET | List all regions | +| `/regions/` | GET | Get region details | +| `/regions/` | PUT | Update region | +| `/regions/` | DELETE | Delete region | +| `/regions//failover/pause` | POST | Pause failover | +| `/regions//failover/resume` | POST | Resume failover | + +## Examples + +### Bash - List Regions + +```bash +curl -X GET "https://api.example.com/regions" \ + -H "Authorization: Bearer $API_KEY" +``` + +### Python - Pause Failover + +```python +response = requests.post( + f"{API_BASE}/regions/region-uuid-here/failover/pause", + headers=headers +) +print(response.json()) +``` + +## Use Cases + +1. **Geographic Distribution**: Deploy close to users +2. **Disaster Recovery**: Failover between regions +3. **Compliance**: Data residency requirements +4. **Performance**: Low-latency deployments diff --git a/user_facing_docs/content/storage/_index.md b/user_facing_docs/content/storage/_index.md new file mode 100644 index 0000000..05d3b5d --- /dev/null +++ b/user_facing_docs/content/storage/_index.md @@ -0,0 +1,18 @@ +--- +title: "Storage" +description: "Storage management and configuration" +icon: "database" +--- + +# Storage + +Manage storage resources including volumes and attachments. + +## Available Guides + +- [Volumes](volumes) - Create and manage storage volumes +- [Attach/Detach](attach-detach) - Volume attachment operations + +## Getting Started + +Storage provides persistent data management for your workloads. Use this section to create and manage storage resources. diff --git a/user_facing_docs/content/storage/attach-detach.md b/user_facing_docs/content/storage/attach-detach.md new file mode 100644 index 0000000..13e23ea --- /dev/null +++ b/user_facing_docs/content/storage/attach-detach.md @@ -0,0 +1,204 @@ +--- +title: "Attach and Detach" +description: "Volume attachment and detachment operations" +--- + +# Attach and Detach Volumes + +Learn how to attach and detach volumes to compute instances. + +## Attaching Volumes + +### Attach to Instance + +```bash +# API request to attach volume +POST /api/volumes/{volume_id}/attach +{ + "instance_id": "i-abc123", + "device": "/dev/xvdf" +} +``` + +### Response + +```json +{ + "success": true, + "data": { + "attachment_id": "att-xyz789", + "volume_id": "vol-abc123", + "instance_id": "i-abc123", + "device": "/dev/xvdf", + "status": "attaching" + } +} +``` + +### Device Naming Conventions + +| OS | First Volume | Second Volume | Third Volume | +|----|--------------|---------------|--------------| +| Linux | /dev/xvdf | /dev/xvdg | /dev/xvdh | +| Linux | /dev/nvme0n1 | /dev/nvme1n1 | /dev/nvme2n1 | +| Windows | xvdf | xvdg | xvdh | + +## Detaching Volumes + +### Graceful Detach + +```bash +# Detach volume with force option +POST /api/volumes/{volume_id}/detach +{ + "force": false, + "timeout": 300 +} +``` + +### Force Detach + +```bash +# Force detach (use with caution) +POST /api/volumes/{volume_id}/detach +{ + "force": true +} +``` + +**Warning:** Force detach can cause data loss if the volume is in use. + +## Attachment States + +| State | Description | +|-------|-------------| +| attaching | Volume is being attached | +| attached | Volume is successfully attached | +| detaching | Volume is being detached | +| available | Volume is detached and available | + +## Linux: Mounting Volumes + +### After Attachment + +```bash +# Check attached volumes +lsblk + +# Format new volume (first time only) +sudo mkfs -t ext4 /dev/xvdf + +# Create mount point +sudo mkdir /data + +# Mount the volume +sudo mount /dev/xvdf /data + +# Verify mount +df -h +``` + +### Auto-Mount on Boot + +```bash +# Get UUID +sudo blkid /dev/xvdf + +# Add to /etc/fstab +echo "UUID=uuid-here /data ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab + +# Mount all +sudo mount -a +``` + +## Windows: Mounting Volumes + +### After Attachment + +1. Open Disk Management +2. Initialize the disk +3. Create a new volume +4. Assign a drive letter + +### PowerShell + +```powershell +# Get disk number +Get-Disk + +# Initialize disk +Initialize-Disk -Number 1 -PartitionStyle MBR + +# Create partition +New-Partition -DiskNumber 1 -UseMaximumSize -DriveLetter D + +# Format volume +Format-Volume -DriveLetter D -FileSystem NTFS +``` + +## Multi-Attach Volumes + +### Enable Multi-Attach + +```bash +# Create multi-attach enabled volume +POST /api/volumes +{ + "name": "shared-volume", + "type": "block", + "size_gb": 500, + "multi_attach": true +} +``` + +### Attach to Multiple Instances + +```bash +# Attach to first instance +POST /api/volumes/{volume_id}/attach +{ + "instance_id": "i-abc123", + "device": "/dev/xvdf" +} + +# Attach to second instance +POST /api/volumes/{volume_id}/attach +{ + "instance_id": "i-def456", + "device": "/dev/xvdf" +} +``` + +**Note:** Use a cluster-aware file system (e.g., GFS2, OCFS2) for concurrent access. + +## Troubleshooting + +### Attachment Fails + +1. **Instance not running**: Start the instance first +2. **Volume already attached**: Detach from current instance +3. **Region mismatch**: Volume and instance must be in same region +4. **Quota exceeded**: Check volume count limits + +### Detachment Issues + +1. **Volume in use**: Stop services using the volume +2. **Filesystem not unmounted**: Unmount before detaching +3. **Force detaching**: May cause data corruption + +### Performance Issues + +1. **Check IOPS**: Verify volume has adequate performance +2. **Check throughput**: Ensure bandwidth is sufficient +3. **Check latency**: Network volumes may have higher latency + +## Best Practices + +1. **Always unmount before detach** - Prevents data corruption +2. **Stop services first** - Databases, apps using the volume +3. **Use consistent naming** - Easy to identify volumes +4. **Document attachments** - Track which instance uses which volume +5. **Enable multi-attach carefully** - Only for cluster-aware filesystems +6. **Regular backups** - Snapshot before major changes +7. **Monitor usage** - Track disk utilization +8. **Plan for detachment** - Build detachment procedures into your workflow diff --git a/user_facing_docs/content/storage/volumes.md b/user_facing_docs/content/storage/volumes.md new file mode 100644 index 0000000..70764d4 --- /dev/null +++ b/user_facing_docs/content/storage/volumes.md @@ -0,0 +1,208 @@ +--- +title: "Volumes" +description: "Create and manage storage volumes" +--- + +# Volumes + +Create and manage persistent storage volumes for your workloads. + +## Volume Types + +### Block Storage + +High-performance storage for databases and applications. + +```json +{ + "type": "block", + "name": "database-volume", + "size_gb": 100, + "iops": 3000, + "throughput_mbps": 125 +} +``` + +### File Storage + +Shared file storage for multiple instances. + +```json +{ + "type": "file", + "name": "shared-storage", + "size_gb": 500, + "protocol": "nfs", + "share_name": "/shared-data" +} +``` + +### Object Storage + +Scalable storage for unstructured data. + +```json +{ + "type": "object", + "name": "backup-storage", + "storage_class": "standard", + " versioning": true +} +``` + +## Creating Volumes + +### API Request + +```bash +POST /api/volumes +Content-Type: application/json + +{ + "name": "my-volume", + "description": "Primary database storage", + "type": "block", + "size_gb": 100, + "region": "us-east-1", + "tags": { + "environment": "production", + "team": "data" + } +} +``` + +### Response + +```json +{ + "success": true, + "data": { + "id": "vol-abc123", + "name": "my-volume", + "type": "block", + "size_gb": 100, + "status": "available", + "iops": 3000, + "created_at": "2024-01-01T00:00:00Z" + } +} +``` + +## Volume Operations + +### Resize Volume + +```bash +# Increase volume size +PUT /api/volumes/{volume_id} +{ + "size_gb": 200 +} +``` + +**Note:** Volume size can only be increased, not decreased. + +### Create Snapshot + +```bash +# Create a point-in-time snapshot +POST /api/volumes/{volume_id}/snapshots +{ + "name": "backup-2024-01-01", + "description": "Daily backup" +} +``` + +### Copy Snapshot + +```bash +# Copy snapshot to another region +POST /api/snapshots/{snapshot_id}/copy +{ + "target_region": "us-west-2" +} +``` + +### Delete Volume + +```bash +# Delete volume (must be detached first) +DELETE /api/volumes/{volume_id} +``` + +## Volume Performance + +### IOPS Configuration + +```json +{ + "iops": 10000, + "burst_mode": true +} +``` + +### Throughput Configuration + +```json +{ + "throughput_mbps": 250, + "burst_mode": true +} +``` + +## Volume Tags + +```bash +# Add tags +PUT /api/volumes/{volume_id}/tags +{ + "tags": { + "environment": "production", + "department": "engineering", + "backup": "daily" + } +} +``` + +## Monitoring + +### View Volume Metrics + +```bash +GET /api/volumes/{volume_id}/metrics +{ + "metrics": { + "read_iops": 1500, + "write_iops": 800, + "read_throughput_mbps": 45, + "write_throughput_mbps": 30, + "latency_ms": 5 + } +} +``` + +### Set Alarms + +```bash +# Create volume alert +POST /api/alarms +{ + "name": "high-iops", + "metric": "volume.iops", + "threshold": 10000, + "comparison": "greater_than", + "evaluation_periods": 3, + "notification": "alerts@example.com" +} +``` + +## Best Practices + +1. **Choose appropriate size** - Start small, expand as needed +2. **Use SSD for performance** - For I/O intensive workloads +3. **Enable snapshots** - Regular backups are essential +4. **Implement tagging** - Track costs and ownership +5. **Monitor performance** - Watch for bottlenecks +6. **Encrypt sensitive data** - Enable encryption at rest +7. **Plan for growth** - Consider future capacity needs +8. **Test restore procedures** - Verify backup reliability diff --git a/user_facing_docs/content/virtual-data-centers/_index.md b/user_facing_docs/content/virtual-data-centers/_index.md new file mode 100644 index 0000000..45388c2 --- /dev/null +++ b/user_facing_docs/content/virtual-data-centers/_index.md @@ -0,0 +1,68 @@ +--- +title: Virtual Data Centers +type: docs +bookToc: true +--- + +# Virtual Data Centers (VDCs) + +Virtual Data Centers provide isolated infrastructure environments within a region. VDCs contain all your compute, storage, and network resources. + +## What Are VDCs? + +A Virtual Data Center is an isolated environment that acts like a private cloud within the platform. Each VDC has its own networks, volumes, and can host VMs and containers. + +## Key Capabilities + +- **Resource Isolation**: Complete isolation from other VDCs +- **DNS Management**: Manage DNS records for the VDC +- **Workload Hosting**: Deploy VMs and containers +- **Volume Management**: Create and attach storage +- **Network Isolation**: Private network segments + +## API Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/virtual_data_centers` | POST | Create VDC | +| `/virtual_data_centers` | GET | List all VDCs | +| `/virtual_data_centers/` | GET | Get VDC details | +| `/virtual_data_centers/` | PUT | Update VDC | +| `/virtual_data_centers/` | DELETE | Delete VDC | +| `/virtual_data_centers//workloads` | GET | List VDC workloads | +| `/virtual_data_centers//volumes` | GET | List VDC volumes | + +## Examples + +### Bash - Create VDC + +```bash +curl -X POST "https://api.example.com/virtual_data_centers" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "production-vdc", + "region_id": "region-uuid-here" + }' +``` + +### Python - Get VDC with Workloads + +```python +response = requests.get( + f"{API_BASE}/virtual_data_centers/vdc-uuid-here", + headers=headers +) + +vdc = response.json()["data"]["virtual_data_center"] +print(f"VDC: {vdc['name']}") +print(f"Workloads: {len(vdc['workloads'])}") +print(f"Volumes: {len(vdc['volumes'])}") +``` + +## Use Cases + +1. **Environment Isolation**: Separate dev/staging/prod VDCs +2. **Customer Tenancy**: Dedicated VDC per customer +3. **Application Isolation**: VDC per application +4. **Security Compliance**: Isolated environments for sensitive workloads diff --git a/user_facing_docs/content/virtual-machines/_index.md b/user_facing_docs/content/virtual-machines/_index.md new file mode 100644 index 0000000..8f28b0f --- /dev/null +++ b/user_facing_docs/content/virtual-machines/_index.md @@ -0,0 +1,19 @@ +--- +title: "Virtual Machines" +description: "Virtual machine management and configuration" +icon: "server" +--- + +# Virtual Machines + +Deploy and manage virtual machines on your infrastructure. + +## Available Guides + +- [Create VM](create) - Creating new virtual machines +- [Manage VM](manage) - Managing virtual machine resources +- [Lifecycle](lifecycle) - VM lifecycle and operations + +## Getting Started + +Virtual machines provide isolated compute environments. Use this section to create and manage VMs for your workloads. diff --git a/user_facing_docs/content/virtual-machines/create.md b/user_facing_docs/content/virtual-machines/create.md new file mode 100644 index 0000000..d364387 --- /dev/null +++ b/user_facing_docs/content/virtual-machines/create.md @@ -0,0 +1,247 @@ +--- +title: "Create Virtual Machine" +description: "Creating new virtual machines" +--- + +# Create Virtual Machine + +Learn how to create and configure virtual machines for your workloads. + +## VM Specifications + +### Instance Types + +| Type | vCPU | Memory | Use Case | +|------|------|--------|----------| +| small | 1 | 2 GB | Development, testing | +| medium | 2 | 4 GB | Small applications | +| large | 4 | 8 GB | Production apps | +| xlarge | 8 | 16 GB | High-traffic services | +| 2xlarge | 16 | 32 GB | Database servers | +| 4xlarge | 32 | 64 GB | Enterprise workloads | + +### Operating Systems + +- **Ubuntu** - 20.04 LTS, 22.04 LTS +- **Debian** - 11, 12 +- **CentOS** - 7, 8 Stream +- **Rocky Linux** - 8, 9 +- **AlmaLinux** - 8, 9 +- **Windows** - 2019, 2022 + +## Creating a VM + +### API Request + +```bash +POST /api/virtual-machines +Content-Type: application/json + +{ + "name": "web-server-01", + "description": "Production web server", + "instance_type": "large", + "image": "ubuntu-22.04", + "region": "us-east-1", + "key_pair": "my-ssh-key", + "security_groups": ["web-sg"], + "network": { + "subnet_id": "subnet-abc123", + "private_ip": "10.1.1.100" + }, + "storage": { + "root_volume": { + "size_gb": 50, + "type": "ssd" + } + }, + "tags": { + "environment": "production", + "team": "platform" + } +} +``` + +### Response + +```json +{ + "success": true, + "data": { + "id": "vm-abc123", + "name": "web-server-01", + "status": "provisioning", + "instance_type": "large", + "public_ip": null, + "private_ip": "10.1.1.100", + "created_at": "2024-01-01T00:00:00Z" + } +} +``` + +## Network Configuration + +### Private Network Only + +```json +{ + "network": { + "subnet_id": "subnet-abc123", + "private_ip": "10.1.1.100", + "assign_public_ip": false + } +} +``` + +### With Public IP + +```json +{ + "network": { + "subnet_id": "subnet-abc123", + "private_ip": "10.1.1.100", + "assign_public_ip": true + } +} +``` + +### Elastic IP + +```json +{ + "network": { + "subnet_id": "subnet-abc123", + "elastic_ip_id": "eip-xyz789" + } +} +``` + +## Storage Configuration + +### Root Volume + +```json +{ + "storage": { + "root_volume": { + "size_gb": 50, + "type": "ssd", + "encrypted": true + } + } +} +``` + +### Additional Volumes + +```json +{ + "storage": { + "root_volume": { + "size_gb": 50, + "type": "ssd" + }, + "additional_volumes": [ + { + "name": "data", + "size_gb": 100, + "type": "ssd", + "mount_point": "/data" + } + ] + } +} +``` + +## Security Configuration + +### Security Groups + +```json +{ + "security_groups": [ + "web-sg", + "ssh-access" + ] +} +``` + +### SSH Keys + +```json +{ + "key_pair": "my-ssh-key" +} +``` + +**Note:** The SSH key must be created before VM creation. + +## User Data (Initialization Script) + +### Bash (Linux) + +```bash +#!/bin/bash +# Cloud-init script +echo "VM initialized at $(date)" >> /var/log/init.log + +# Install packages +apt-get update +apt-get install -y nginx docker.io + +# Configure services +systemctl enable nginx +systemctl start nginx +``` + +### PowerShell (Windows) + +```powershell +# Cloud-init script +Write-Host "VM initialized at $(Get-Date)" + +# Install features +Install-WindowsFeature -Name Web-Server -IncludeManagementTools + +# Disable IE ESC +Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A7-37EF-4b3f-8CFC-4F3A74704073}" -Name "IsInstalled" -Value 0 +``` + +## Tags and Metadata + +### Resource Tags + +```json +{ + "tags": { + "Name": "web-server-01", + "Environment": "production", + "Team": "platform", + "Project": "website" + } +} +``` + +### Instance Metadata + +```json +{ + "metadata": { + "role": "web-server", + "environment": "production" + } +} +``` + +## Best Practices + +1. **Choose appropriate size** - Match instance type to workload needs +2. **Use SSD storage** - For better I/O performance +3. **Enable encryption** - Protect data at rest +4. **Use security groups** - Restrict network access +5. **Implement SSH keys** - Disable password authentication +6. **Use user data** - Automate initial configuration +7. **Tag resources** - Track costs and ownership +8. **Plan for redundancy** - Consider HA for production +9. **Document configurations** - Keep infrastructure as code +10. **Test before production** - Validate configurations diff --git a/user_facing_docs/content/virtual-machines/lifecycle.md b/user_facing_docs/content/virtual-machines/lifecycle.md new file mode 100644 index 0000000..1a7c2f5 --- /dev/null +++ b/user_facing_docs/content/virtual-machines/lifecycle.md @@ -0,0 +1,291 @@ +--- +title: "VM Lifecycle" +description: "Virtual machine lifecycle and operations" +--- + +# Virtual Machine Lifecycle + +Understand the lifecycle states and operations for virtual machines. + +## Lifecycle States + +### State Diagram + +``` +pending -> provisioning -> running -> stopping -> stopped + | + +-> rebooting -> running + | + +-> terminating -> terminated +``` + +### State Descriptions + +| State | Description | +|-------|-------------| +| **pending** | VM request received, waiting for provisioning | +| **provisioning** | VM resources being allocated | +| **running** | VM is active and accessible | +| **stopping** | VM is being stopped | +| **stopped** | VM is halted | +| **rebooting** | VM is being restarted | +| **terminating** | VM is being deleted | +| **terminated** | VM has been deleted | +| **failed** | VM creation or operation failed | + +## Provisioning Process + +### Step 1: Request Validation + +```json +// API validates the request +{ + "validation": { + "instance_type": "available", + "region": "available", + "quota": "sufficient", + "image": "valid" + } +} +``` + +### Step 2: Resource Allocation + +- Allocate compute resources +- Provision storage volumes +- Configure network interfaces +- Assign IP addresses + +### Step 3: Image Deployment + +- Copy OS image to local storage +- Configure boot parameters +- Apply user data scripts + +### Step 4: VM Start + +- Power on virtual machine +- Initialize OS +- Execute user data +- Report ready status + +## Start Process + +### Pre-Start + +1. Check resource availability +2. Verify network connectivity +3. Validate storage attachments + +### Start Operation + +```bash +# Start VM +POST /api/virtual-machines/{vm_id}/start +``` + +### Post-Start + +1. VM boots up +2. Network interfaces activate +3. Services initialize +4. Status changes to "running" + +## Stop Process + +### Graceful Shutdown + +```bash +# Graceful stop (recommended) +POST /api/virtual-machines/{vm_id}/stop +{ + "force": false, + "timeout": 300 +} +``` + +**Steps:** +1. Signal OS to shut down +2. Services stop gracefully +3. Filesystem syncs +4. VM powers off + +### Force Stop + +```bash +# Immediate stop +POST /api/virtual-machines/{vm_id}/stop +{ + "force": true +} +``` + +**Warning:** May cause data loss if filesystem not synced. + +## Reboot Process + +### Soft Reboot + +```bash +# Reboot via OS +POST /api/virtual-machines/{vm_id}/reboot +{ + "force": false +} +``` + +**Steps:** +1. Signal OS to reboot +2. Services stop gracefully +3. System reboots +4. VM returns to running state + +### Hard Reboot + +```bash +# Force reboot +POST /api/virtual-machines/{vm_id}/reboot +{ + "force": true +} +``` + +**Steps:** +1. Power cycle VM +2. VM boots from initial state +3. May require OS filesystem check + +## Termination Process + +### Pre-Termination Checklist + +- [ ] Back up data +- [ ] Update DNS records +- [ ] Notify stakeholders +- [ ] Document termination reason + +### Termination + +```bash +# Terminate VM (default: deletes with volumes) +DELETE /api/virtual-machines/{vm_id} + +# Preserve volumes +DELETE /api/virtual-machines/{vm_id} +{ + "preserve_volumes": true +} +``` + +### Post-Termination + +1. VM powers off +2. Resources deallocated +3. IP addresses released +4. Volumes deleted (unless preserved) + +## Automatic Operations + +### Scheduled Start/Stop + +```bash +# Configure scheduled operation +POST /api/virtual-machines/{vm_id}/schedules +{ + "start": "0 8 * * 1-5", # 8 AM weekdays + "stop": "0 18 * * 1-5", # 6 PM weekdays + "timezone": "UTC" +} +``` + +### Lifecycle Hooks + +```json +{ + "lifecycle_hooks": { + "pre_provisioning": "hook-1", + "post_provisioning": "hook-2", + "pre_termination": "hook-3" + } +} +``` + +## Cost Optimization + +### Right-Sizing + +1. Monitor resource utilization +2. Adjust instance types +3. Remove unused VMs + +### Scheduling + +- Stop non-production VMs outside business hours +- Use auto-scaling for variable workloads +- Implement scheduling policies + +### Storage Management + +- Remove unused volumes +- Use appropriate storage types +- Implement data retention policies + +## Disaster Recovery + +### Backup Strategy + +| Recovery Point | Frequency | Retention | +|----------------|-----------|-----------| +| Daily snapshots | Daily | 7 days | +| Weekly snapshots | Weekly | 4 weeks | +| Monthly snapshots | Monthly | 12 months | + +### Recovery Procedures + +1. **RTO (Recovery Time Objective)**: 1 hour +2. **RPO (Recovery Point Objective)**: 1 hour +3. **Test recovery** quarterly +4. **Document** recovery steps + +## Troubleshooting Lifecycle Issues + +### VM Stuck in Provisioning + +1. Check resource availability +2. Verify image exists +3. Check quota limits +4. Review logs + +### VM Won't Start + +1. Check resource availability +2. Verify network configuration +3. Check storage attachments +4. Review console output + +### VM Won't Stop + +1. Check for running processes +2. Try force stop +3. Check for hung processes +4. Contact support if persists + +### Termination Fails + +1. Check for dependent resources +2. Force delete if necessary +3. Release stuck resources +4. Contact support + +## Best Practices + +1. **Use proper shutdown** - Graceful stops prevent data loss +2. **Implement schedules** - Auto-stop non-production VMs +3. **Regular backups** - Before major changes +4. **Monitor lifecycle** - Track state transitions +5. **Document procedures** - Recovery steps +6. **Test regularly** - Validate backup restore +7. **Plan for growth** - Capacity planning +8. **Automate operations** - Reduce manual errors +9. **Review regularly** - Audit VM inventory +10. **Cost awareness** - Track resource usage diff --git a/user_facing_docs/content/virtual-machines/manage.md b/user_facing_docs/content/virtual-machines/manage.md new file mode 100644 index 0000000..e8fa96c --- /dev/null +++ b/user_facing_docs/content/virtual-machines/manage.md @@ -0,0 +1,274 @@ +--- +title: "Manage Virtual Machine" +description: "Managing virtual machine resources" +--- + +# Manage Virtual Machine + +Learn how to manage and configure virtual machine resources after creation. + +## VM Operations + +### Start VM + +```bash +# Start a stopped VM +POST /api/virtual-machines/{vm_id}/start +``` + +### Stop VM + +```bash +# Stop VM gracefully +POST /api/virtual-machines/{vm_id}/stop + +# Force stop (immediate) +POST /api/virtual-machines/{vm_id}/stop +{ + "force": true +} +``` + +### Reboot VM + +```bash +# Reboot VM +POST /api/virtual-machines/{vm_id}/reboot + +# Force reboot +POST /api/virtual-machines/{vm_id}/reboot +{ + "force": true +} +``` + +### Terminate VM + +```bash +# Delete VM and associated resources +DELETE /api/virtual-machines/{vm_id} + +# With associated volumes preserved +DELETE /api/virtual-machines/{vm_id} +{ + "preserve_volumes": true +} +``` + +## Resize VM + +### Change Instance Type + +```bash +# Resize VM to larger instance +PUT /api/virtual-machines/{vm_id}/resize +{ + "instance_type": "xlarge" +} +``` + +**Note:** VM must be stopped before resizing. + +### Resize Storage + +```bash +# Expand root volume +PUT /api/virtual-machines/{vm_id}/storage +{ + "root_volume": { + "size_gb": 100 + } +} +``` + +## Access Methods + +### SSH Access (Linux) + +```bash +# Connect via SSH +ssh -i /path/to/key.pem ubuntu@ + +# SSH with custom port +ssh -i /path/to/key.pem -p 2222 ubuntu@ +``` + +### RDP Access (Windows) + +```bash +# Get RDP file +GET /api/virtual-machines/{vm_id}/rdp-file +``` + +### Serial Console + +```bash +# Access serial console +POST /api/virtual-machines/{vm_id}/console +{ + "type": "serial" +} +``` + +### VNC Console + +```bash +# Access VNC console +POST /api/virtual-machines/{vm_id}/console +{ + "type": "vnc" +} +``` + +## Resource Management + +### View VM Details + +```bash +# Get VM information +GET /api/virtual-machines/{vm_id} +``` + +### List VMs + +```bash +# List all VMs +GET /api/virtual-machines + +# Filter by status +GET /api/virtual-machines?status=running + +# Filter by region +GET /api/virtual-machines?region=us-east-1 +``` + +### Update VM + +```bash +# Update VM name and description +PUT /api/virtual-machines/{vm_id} +{ + "name": "web-server-updated", + "description": "Updated description" +} +``` + +## Tag Management + +### Add Tags + +```bash +# Add or update tags +PUT /api/virtual-machines/{vm_id}/tags +{ + "tags": { + "environment": "staging", + "team": "devops" + } +} +``` + +### Remove Tags + +```bash +# Remove specific tags +DELETE /api/virtual-machines/{vm_id}/tags +{ + "tags": ["old-tag"] +} +``` + +## Monitoring + +### Get Metrics + +```bash +# Get VM metrics +GET /api/virtual-machines/{vm_id}/metrics +{ + "metrics": { + "cpu_utilization": 45.2, + "memory_usage": 62.5, + "network_in": 1024, + "network_out": 2048, + "disk_read_iops": 150, + "disk_write_iops": 80 + } +} +``` + +### Set Alarms + +```bash +# Create alarm for CPU usage +POST /api/virtual-machines/{vm_id}/alarms +{ + "name": "high-cpu", + "metric": "cpu_utilization", + "threshold": 80, + "comparison": "greater_than" +} +``` + +## Backup and Recovery + +### Create Snapshot + +```bash +# Create VM snapshot +POST /api/virtual-machines/{vm_id}/snapshots +{ + "name": "backup-before-update", + "description": "Pre-update backup" +} +``` + +### Restore from Snapshot + +```bash +# Create new VM from snapshot +POST /api/virtual-machines/{vm_id}/restore +{ + "snapshot_id": "snap-xyz789", + "name": "restored-vm" +} +``` + +## Troubleshooting + +### View Console Output + +```bash +# Get console logs +GET /api/virtual-machines/{vm_id}/logs +``` + +### Reset SSH Keys + +```bash +# Reset SSH key +PUT /api/virtual-machines/{vm_id}/key-pair +{ + "key_pair": "new-ssh-key" +} +``` + +### View Events + +```bash +# Get VM events +GET /api/virtual-machines/{vm_id}/events +``` + +## Best Practices + +1. **Regular backups** - Create snapshots before changes +2. **Monitor resources** - Set up alerts for thresholds +3. **Use tags** - Organize and track resources +4. **Keep OS updated** - Regular security patches +5. **Implement access controls** - Limit SSH/RDP access +6. **Document changes** - Track VM modifications +7. **Plan for recovery** - Document restore procedures +8. **Optimize costs** - Right-size instances +9. **Use automation** - Script common operations +10. **Regular audits** - Review VM inventory diff --git a/user_facing_docs/hugo.toml b/user_facing_docs/hugo.toml new file mode 100644 index 0000000..ac38457 --- /dev/null +++ b/user_facing_docs/hugo.toml @@ -0,0 +1,46 @@ +baseURL = "/" +languageCode = "en" +title = "User Guide - TheAPI" +theme = "hugo-book" + +[params] + BookTheme = "auto" + BookSearchEnable = true + BookToC = true + BookComments = false + BookRepo = "" + BookEditPath = "" + +[menu] +[[menu.before]] +name = "Home" +url = "/" +weight = 1 +[[menu.before]] +name = "Virtual Machines" +url = "/virtual-machines/" +weight = 2 +[[menu.before]] +name = "Containers" +url = "/containers/" +weight = 3 +[[menu.before]] +name = "Storage" +url = "/storage/" +weight = 4 +[[menu.before]] +name = "Certificates" +url = "/certificates/" +weight = 5 +[[menu.before]] +name = "DNS" +url = "/dns/" +weight = 6 +[[menu.before]] +name = "Networks" +url = "/networks/" +weight = 7 +[[menu.before]] +name = "Cloudflare" +url = "/cloudflare/" +weight = 8 diff --git a/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.content b/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.content new file mode 100644 index 0000000..63f7a65 --- /dev/null +++ b/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.content @@ -0,0 +1 @@ +@charset "UTF-8";:root{--font-size:16px;--font-size-smaller:0.875rem;--font-size-smallest:0.75rem;--body-font-weight:400;--body-background:white;--body-background-tint:transparent;--body-font-color:black;--border-radius:0.25rem}/*!modern-normalize v3.0.1 | MIT License | https://github.com/sindresorhus/modern-normalize*/*,::before,::after{box-sizing:border-box}html{font-family:system-ui,segoe ui,Roboto,Helvetica,Arial,sans-serif,apple color emoji,segoe ui emoji;line-height:1.15;-webkit-text-size-adjust:100%;tab-size:4}body{margin:0}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:ui-monospace,SFMono-Regular,Consolas,liberation mono,Menlo,monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{border-color:initial}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}legend{padding:0}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}.flex{display:flex}.flex.gap{gap:1rem}.flex-auto{flex:auto}.flex-even{flex:1 1}.flex-wrap{flex-wrap:wrap}.justify-start{justify-content:flex-start}.justify-end{justify-content:flex-end}.justify-center{justify-content:center}.justify-between{justify-content:space-between}.align-center{align-items:center}.mx-auto{margin:0 auto}.text-center{text-align:center}.text-left{text-align:left}.text-right{text-align:right}.text-small,small{font-size:.875em}.hidden{display:none}input.toggle{height:0;width:0;overflow:hidden;opacity:0;position:absolute}html{font-size:var(--font-size);scroll-behavior:smooth;touch-action:manipulation;scrollbar-gutter:stable}body{min-width:20rem;color:var(--body-font-color);background:var(--body-background)var(--body-background-tint);font-weight:var(--body-font-weight);text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}h1,h2,h3,h4,h5,h6{font-weight:inherit}a{flex:auto;align-items:center;gap:.5em;text-decoration:none;cursor:default}a[href],a[role=button]{color:var(--color-link);cursor:pointer}:focus-visible,input.toggle:focus-visible+label{outline-style:auto;outline-color:var(--color-link)}nav ul{padding:0;margin:0;list-style:none}nav ul li{position:relative}nav ul a{padding:.5em 0;display:flex;transition:opacity .1s ease-in-out}nav ul a[href]:hover,nav ul a[role=button]:hover{opacity:.5}nav ul ul{padding-inline-start:1.5em}ul.pagination{display:flex;justify-content:center;list-style-type:none;padding-inline-start:0}ul.pagination .page-item a{padding:1rem}.container{max-width:80rem;margin:0 auto}.book-icon{filter:var(--icon-filter)}a .book-icon{height:1em;width:1em}.book-brand{margin-top:0;margin-bottom:1rem}.book-brand img{height:1.5em;width:1.5em}.book-menu{flex:0 0 16rem;font-size:var(--font-size-smaller)}.book-menu .book-menu-content{width:16rem;padding:1rem;position:fixed;top:0;bottom:0;overflow-x:hidden;overflow-y:auto}.book-menu a,.book-menu label{color:inherit;word-wrap:break-word;display:flex}.book-menu a.active{color:var(--color-link)}.book-menu label>img:last-child{height:1em;width:1em;cursor:pointer;align-self:center;transition:transform .1s ease-in-out}.book-menu input.toggle+label+ul{display:none}.book-menu input.toggle:checked+label>img:last-child{transform:rotate(90deg)}.book-menu input.toggle:checked+label+ul{display:block}body[dir=rtl] .book-menu input.toggle+label>img:last-child{transform:rotate(180deg)}body[dir=rtl] .book-menu input.toggle:checked+label>img:last-child{transform:rotate(90deg)}.book-section-flat{margin:1rem 0}.book-section-flat>a,.book-section-flat>span,.book-section-flat>label{font-weight:bolder}.book-section-flat>ul{padding-inline-start:0}.book-page{min-width:20rem;flex-grow:1;padding:1rem}.book-post{margin-bottom:4rem}.book-post .book-post-date img{height:1em;width:1em;margin-inline-end:.5em}.book-post .book-post-content{margin-top:1rem}.book-post .book-post-thumbnail{flex:0 0 34%}.book-post .book-post-thumbnail img{width:100%;aspect-ratio:4/3;object-fit:cover}.book-header{margin-bottom:1rem}.book-header label{line-height:0}.book-header h3{overflow:hidden;text-overflow:ellipsis;margin:0 1rem}.book-layout-landing .book-header{display:block;position:relative;z-index:1}.book-layout-landing .book-header nav>ul{display:flex;gap:1rem;justify-content:end}.book-layout-landing .book-header nav>ul>li{display:block;white-space:nowrap}.book-layout-landing .book-header nav>ul>li>ul{display:none;position:absolute;padding:0}.book-layout-landing .book-header nav>ul>li:hover>ul,.book-layout-landing .book-header nav>ul>li:focus-within>ul{display:block}.book-search{position:relative;margin:.5rem 0}.book-search input{width:100%;padding:.5rem;border:1px solid var(--gray-200);border-radius:var(--border-radius);background:var(--gray-100);color:var(--body-font-color)}.book-search input:required+.book-search-spinner{display:block}.book-search .book-search-spinner{position:absolute;top:0;margin:.5rem;margin-inline-start:calc(100% - 1.5rem);width:1rem;height:1rem;border:1px solid transparent;border-top-color:var(--body-font-color);border-radius:50%;animation:spin 1s ease infinite}@keyframes spin{100%{transform:rotate(360deg)}}.book-search ul a{padding-bottom:0}.book-search small{opacity:.5}.book-toc{flex:0 0 16rem;font-size:var(--font-size-smallest)}.book-toc .book-toc-content{width:16rem;padding:1rem;position:fixed;top:0;bottom:0;overflow-x:hidden;overflow-y:auto}.book-toc a{display:block}.book-toc img{height:1em;width:1em}.book-toc nav>ul>li:first-child{margin-top:0}.book-footer{padding-top:1rem;font-size:var(--font-size-smaller)}.book-footer a{margin:.25rem 0;padding:.25rem 0}.book-comments{margin-top:1rem}.book-copyright{margin-top:1rem}.book-languages{margin-bottom:1rem}.book-languages span{padding:0}.book-languages ul{padding-inline-start:1.5em}.book-menu-content,.book-toc-content{transition:.2s ease-in-out;transition-property:transform,margin,opacity,visibility;will-change:transform,margin,opacity}@media screen and (max-width:56rem){.book-menu{visibility:hidden;margin-inline-start:-16rem;z-index:1}.book-menu .book-menu-content{background:var(--body-background)}.book-toc{display:none}.book-header{display:block}.book-post-container{flex-direction:column-reverse}#menu-control,#toc-control{display:inline}#menu-control:checked~main .book-menu{visibility:initial}#menu-control:checked~main .book-menu .book-menu-content{transform:translateX(16rem);box-shadow:0 0 .5rem rgba(0,0,0,.1)}#menu-control:checked~main .book-page{opacity:.25}#menu-control:checked~main .book-menu-overlay{display:block;position:fixed;top:0;bottom:0;left:0;right:0}#toc-control:checked~main .book-header aside{display:block}body[dir=rtl] #menu-control:checked~main .book-menu .book-menu-content{transform:translateX(-16rem)}}@media screen and (min-width:80rem){.book-page,.book-menu .book-menu-content,.book-toc .book-toc-content{padding:2rem 1rem}}@media print{.book-menu,.book-footer,.book-toc{display:none}.book-header,.book-header aside{display:block}main{display:block!important}}.markdown{line-height:1.6}.markdown>:first-child{margin-top:0}.markdown h1,.markdown h2,.markdown h3,.markdown h4,.markdown h5,.markdown h6{font-weight:inherit;line-height:1;margin-top:1.5em;margin-bottom:1rem}.markdown h1 a.anchor,.markdown h2 a.anchor,.markdown h3 a.anchor,.markdown h4 a.anchor,.markdown h5 a.anchor,.markdown h6 a.anchor{opacity:0;font-size:.75em;margin-inline-start:.25em}.markdown h1:hover a.anchor,.markdown h1 a.anchor:focus-visible,.markdown h2:hover a.anchor,.markdown h2 a.anchor:focus-visible,.markdown h3:hover a.anchor,.markdown h3 a.anchor:focus-visible,.markdown h4:hover a.anchor,.markdown h4 a.anchor:focus-visible,.markdown h5:hover a.anchor,.markdown h5 a.anchor:focus-visible,.markdown h6:hover a.anchor,.markdown h6 a.anchor:focus-visible{opacity:initial;text-decoration:none}.markdown h1{font-size:2rem}.markdown h2{font-size:1.5rem}.markdown h3{font-size:1.25rem}.markdown h4{font-size:1.125rem}.markdown h5{font-size:1rem}.markdown h6{font-size:.875rem}.markdown b,.markdown optgroup,.markdown strong{font-weight:bolder}.markdown a{text-decoration:none}.markdown a[href]:hover{text-decoration:underline}.markdown a[href]:visited{color:var(--color-visited-link)}.markdown img{max-width:100%;height:auto}.markdown code{direction:ltr;unicode-bidi:embed;padding:.125em .25em;background:var(--gray-100);border:1px solid var(--gray-200);border-radius:var(--border-radius);font-size:.875em}.markdown pre{padding:1rem;background:var(--gray-100);border:1px solid var(--gray-200);border-radius:var(--border-radius);overflow-x:auto}.markdown pre:focus{outline-style:auto;outline-color:var(--color-link)}.markdown pre code{padding:0;border:0;background:0 0}.markdown p{word-wrap:break-word}.markdown blockquote{margin:1rem 0;padding:.5rem 1rem .5rem .75rem;border-inline-start:.25rem solid var(--gray-200);border-radius:var(--border-radius)}.markdown blockquote :first-child{margin-top:0}.markdown blockquote :last-child{margin-bottom:0}.markdown table{overflow:auto;display:block;border-spacing:0;border-collapse:collapse;margin-top:1rem;margin-bottom:1rem}.markdown table tr th,.markdown table tr td{padding:.5rem 1rem;border:1px solid var(--gray-200);text-align:start}.markdown table tr:nth-child(2n){background:var(--gray-100)}.markdown hr{height:1px;border:none;background:var(--gray-200)}.markdown ul,.markdown ol{padding-inline-start:2rem;word-wrap:break-word}.markdown dl dt{font-weight:bolder;margin-top:1rem}.markdown dl dd{margin-inline-start:0;margin-bottom:1rem}.markdown .highlight{direction:ltr;unicode-bidi:embed;border-radius:var(--border-radius)}.markdown .highlight table tbody{border:1px solid var(--gray-200)}.markdown .highlight table tr pre{border:0}.markdown .highlight table tr td pre code>span{display:flex}.markdown .highlight table tr td:nth-child(1) pre{margin:0;padding-inline-end:0}.markdown .highlight table tr td:nth-child(2) pre{margin:0;padding-inline-start:0}.markdown details{padding:1rem;margin:1rem 0;border:1px solid var(--gray-200);border-radius:var(--border-radius)}.markdown details summary{line-height:1;padding:1rem;margin:-1rem;cursor:pointer;list-style:none}.markdown details summary::before{content:"›";display:inline-block;margin-inline-end:.5rem;transition:transform .1s ease-in-out}.markdown details[open] summary{margin-bottom:0}.markdown details[open] summary::before{transform:rotate(90deg)}.markdown figure{margin:1rem 0}.markdown figure figcaption{margin-top:1rem}.markdown-inner>:first-child,.markdown .book-steps>ol>li>:first-child,.markdown figure figcaption>:first-child{margin-top:0}.markdown-inner>:last-child,.markdown .book-steps>ol>li>:last-child,.markdown figure figcaption>:last-child{margin-bottom:0}.markdown .book-tabs{margin-top:1rem;margin-bottom:1rem;border:1px solid var(--gray-200);border-radius:var(--border-radius);display:flex;flex-wrap:wrap}.markdown .book-tabs label{display:inline-block;padding:.5rem 1rem;border-bottom:1px transparent;cursor:pointer}.markdown .book-tabs .book-tabs-content{order:999;width:100%;border-top:1px solid var(--gray-100);padding:1rem;display:none}.markdown .book-tabs input[type=radio]:checked+label{border-bottom:1px solid var(--color-link)}.markdown .book-tabs input[type=radio]:checked+label+.book-tabs-content{display:block}.markdown .book-columns{gap:1rem}.markdown .book-columns>div{margin:1rem 0;min-width:13.2rem}.markdown .book-columns>ul{list-style:none;display:flex;padding:0;flex-wrap:wrap;gap:1rem}.markdown .book-columns>ul>li{flex:1 1;min-width:13.2rem}.markdown a.book-btn[href]{display:inline-block;font-size:var(--font-size-smaller);color:var(--color-link);line-height:2rem;padding:0 1rem;border:1px solid var(--color-link);border-radius:var(--border-radius);cursor:pointer}.markdown a.book-btn[href]:hover{text-decoration:none}.markdown .book-hint.note{border-color:var(--color-accent-note);background-color:var(--color-accent-note-tint)}.markdown .book-hint.tip{border-color:var(--color-accent-tip);background-color:var(--color-accent-tip-tint)}.markdown .book-hint.important{border-color:var(--color-accent-important);background-color:var(--color-accent-important-tint)}.markdown .book-hint.warning{border-color:var(--color-accent-warning);background-color:var(--color-accent-warning-tint)}.markdown .book-hint.caution{border-color:var(--color-accent-caution);background-color:var(--color-accent-caution-tint)}.markdown .book-hint.default{border-color:var(--color-accent-default);background-color:var(--color-accent-default-tint)}.markdown .book-hint.info{border-color:var(--color-accent-info);background-color:var(--color-accent-info-tint)}.markdown .book-hint.success{border-color:var(--color-accent-success);background-color:var(--color-accent-success-tint)}.markdown .book-hint.danger{border-color:var(--color-accent-danger);background-color:var(--color-accent-danger-tint)}.markdown .book-badge{display:inline-block;font-size:var(--font-size-smaller);font-weight:var(--body-font-weight);vertical-align:middle;border-radius:var(--border-radius);border:1px solid var(--accent-color);overflow:hidden;text-wrap:nowrap;color:var(--body-font-color)}.markdown .book-badge.note{--accent-color:var(--color-accent-note)}.markdown .book-badge.tip{--accent-color:var(--color-accent-tip)}.markdown .book-badge.important{--accent-color:var(--color-accent-important)}.markdown .book-badge.warning{--accent-color:var(--color-accent-warning)}.markdown .book-badge.caution{--accent-color:var(--color-accent-caution)}.markdown .book-badge.default{--accent-color:var(--color-accent-default)}.markdown .book-badge.info{--accent-color:var(--color-accent-info)}.markdown .book-badge.success{--accent-color:var(--color-accent-success)}.markdown .book-badge.danger{--accent-color:var(--color-accent-danger)}.markdown .book-badge span{display:inline-block;padding:0 .5rem}.markdown .book-badge span.book-badge-value{color:var(--body-background);background-color:var(--accent-color)}.markdown .book-steps{position:relative}.markdown .book-steps>ol{counter-reset:steps;list-style:none;padding-inline-start:1.25rem;margin-top:2rem}.markdown .book-steps>ol>li::before{content:counter(steps);counter-increment:steps;position:absolute;display:flex;justify-content:center;left:.5rem;height:1.5rem;width:1.5rem;padding:.25rem;border-radius:.5rem;white-space:nowrap;line-height:1rem;color:var(--body-background);background:var(--gray-500);outline:.25rem solid var(--body-background)}.markdown .book-steps>ol>li{border-inline-start:1px solid var(--gray-500);padding-inline-start:3rem;padding-bottom:2rem}.markdown .book-steps>ol>li:last-child{border:0}.markdown .book-card{display:block;overflow:hidden;height:100%;border-radius:var(--border-radius);border:1px solid var(--gray-200)}.markdown .book-card>a{display:block;height:100%}.markdown .book-card>a[href],.markdown .book-card>a[href]:visited{color:var(--body-font-color)}.markdown .book-card>a[href]:hover{text-decoration:none;background:var(--gray-100)}.markdown .book-card>a>img,.markdown .book-card>img{width:100%;display:block;aspect-ratio:4/3;object-fit:cover}.markdown .book-card .markdown-inner,.markdown .book-card figure figcaption,.markdown figure .book-card figcaption,.markdown .book-card .book-steps>ol>li{padding:1rem}.markdown .book-image input+img{cursor:zoom-in;transition:transform .2s ease-in-out}.markdown .book-image input:checked+img{position:fixed;top:0;left:0;right:0;bottom:0;background:var(--body-background);object-fit:contain;width:100%;height:100%;z-index:1;cursor:zoom-out;padding:1rem}.markdown .book-asciinema{margin:1rem 0}.markdown .book-hero{min-height:24rem;align-content:center}.markdown .book-hero h1{font-size:3em}.markdown .book-codeblock-filename{background:var(--gray-100);border:1px solid var(--gray-200);border-bottom:0;font-size:var(--font-size-smaller);margin-top:1rem;padding:.25rem .5rem;border-start-start-radius:var(--border-radius);border-start-end-radius:var(--border-radius)}.markdown .book-codeblock-filename a{color:var(--body-font-color)}.markdown .book-codeblock-filename+.highlight pre{margin-top:0;border-start-start-radius:0;border-start-end-radius:0}:root{--body-background:white;--body-background-tint:none;--body-font-color:black;--color-link:#0055bb;--color-visited-link:#5500bb;--icon-filter:none;--gray-100:#f8f9fa;--gray-200:#e9ecef;--gray-500:#adb5bd;--color-accent-default:#64748b;--color-accent-default-tint:rgba(100, 116, 139, 0.1);--color-accent-note:#4486dd;--color-accent-note-tint:rgba(68, 134, 221, 0.1);--color-accent-tip:#3bad3b;--color-accent-tip-tint:rgba(59, 173, 59, 0.1);--color-accent-important:#8144dd;--color-accent-important-tint:rgba(129, 68, 221, 0.1);--color-accent-warning:#f59e42;--color-accent-warning-tint:rgba(245, 158, 66, 0.1);--color-accent-caution:#d84747;--color-accent-caution-tint:rgba(216, 71, 71, 0.1);--color-accent-info:#4486dd;--color-accent-info-tint:rgba(68, 134, 221, 0.1);--color-accent-success:#3bad3b;--color-accent-success-tint:rgba(59, 173, 59, 0.1);--color-accent-danger:#d84747;--color-accent-danger-tint:rgba(216, 71, 71, 0.1)}@media(prefers-color-scheme:dark){:root{--body-background:#343a40;--body-background-tint:none;--body-font-color:#e9ecef;--color-link:#84b2ff;--color-visited-link:#b88dff;--icon-filter:brightness(0) invert(1);--gray-100:#494e54;--gray-200:#5c6165;--gray-500:#999d9f;--color-accent-default:#64748b;--color-accent-default-tint:rgba(100, 116, 139, 0.1);--color-accent-note:#4486dd;--color-accent-note-tint:rgba(68, 134, 221, 0.1);--color-accent-tip:#3bad3b;--color-accent-tip-tint:rgba(59, 173, 59, 0.1);--color-accent-important:#8144dd;--color-accent-important-tint:rgba(129, 68, 221, 0.1);--color-accent-warning:#f59e42;--color-accent-warning-tint:rgba(245, 158, 66, 0.1);--color-accent-caution:#d84747;--color-accent-caution-tint:rgba(216, 71, 71, 0.1);--color-accent-info:#4486dd;--color-accent-info-tint:rgba(68, 134, 221, 0.1);--color-accent-success:#3bad3b;--color-accent-success-tint:rgba(59, 173, 59, 0.1);--color-accent-danger:#d84747;--color-accent-danger-tint:rgba(216, 71, 71, 0.1)}} \ No newline at end of file diff --git a/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.json b/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.json new file mode 100644 index 0000000..2fff0b2 --- /dev/null +++ b/user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.json @@ -0,0 +1 @@ +{"Target":"book.min.6970156cec683193d93c9c4edaf0d56574e4361df2e0c1be4f697ae81c3ba55f.css","MediaType":"text/css","Data":{"Integrity":"sha256-aXAVbOxoMZPZPJxO2vDVZXTkNh3y4MG+T2l66Bw7pV8="}} \ No newline at end of file