JamesBhattarai/3cloud-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Hugo user docs

Browse Source
This commit is contained in:
nexgen_mirrors
2026-01-06 15:43:03 +10:30
parent 52c559e1cd
commit 06989be22e
32 changed files with 3437 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
user_facing_docs/.hugo_build.lock
View File
user_facing_docs/archetypes/default.md
+5
View File
@@ -0,0 +1,5 @@
+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+++
user_facing_docs/config.toml
+46
View File
@@ -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
user_facing_docs/content/_index.md
+99
View File
@@ -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
user_facing_docs/content/certificates/_index.md
+52
View File
@@ -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/<id>` | GET | Get project CA |
| `/certificates/ca/project/<id>` | POST | Create CA for project |
| `/certificates/ca/<id>` | GET | Get CA details |
| `/certificates/ca/<id>` | PUT | Update CA |
| `/certificates/ca/<id>/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/<id>` | GET | List certificates for CA |
| `/certificates/cert/<id>` | GET | Get certificate details |
| `/certificates/cert/<id>` | PUT | Update certificate |
| `/certificates/cert/<id>/revoke` | POST | Revoke certificate |
| `/certificates/cert/<id>/download` | GET | Download cert/key |
| `/certificates/cert/project/<id>` | GET | List project certificates |
| `/certificates/crl/<id>` | GET | Get CRL for CA |
## Related Resources
- [Certificate Authorities](/certificates/ca/) - Create and manage CAs
- [Certificate Issuance](/certificates/issuance/) - Issue and manage certificates
user_facing_docs/content/certificates/ca.md
+79
View File
@@ -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
user_facing_docs/content/certificates/issuance.md
+105
View File
@@ -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
user_facing_docs/content/cloudflare/_index.md
+18
View File
@@ -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.
user_facing_docs/content/cloudflare/dns.md
+232
View File
@@ -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
user_facing_docs/content/cloudflare/tunnels.md
+181
View File
@@ -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: <tunnel-uuid>
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
user_facing_docs/content/containers/_index.md
+19
View File
@@ -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.
user_facing_docs/content/containers/containers.md
+121
View File
@@ -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 <container-name>
# Stop a container
docker stop <container-name>
# Restart a container
docker restart <container-name>
```
### View Container Status
```bash
# List running containers
docker ps
# List all containers (including stopped)
docker ps -a
# View container logs
docker logs <container-name>
# Follow logs in real-time
docker logs -f <container-name>
```
### Inspect Container
```bash
# View detailed container information
docker inspect <container-name>
# View container resources (CPU, memory)
docker stats <container-name>
```
## 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 <container-name>
# Remove container and associated volumes
docker rm -v <container-name>
# Remove all stopped containers
docker container prune
```
user_facing_docs/content/containers/deploy.md
+171
View File
@@ -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
user_facing_docs/content/containers/pods.md
+62
View File
@@ -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 <pod-name>
# View pod logs
kubectl logs <pod-name>
```
## 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
user_facing_docs/content/dns/_index.md
+17
View File
@@ -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.
user_facing_docs/content/dns/records.md
+232
View File
@@ -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
user_facing_docs/content/networks/_index.md
+18
View File
@@ -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.
user_facing_docs/content/networks/create.md
+235
View File
@@ -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
user_facing_docs/content/networks/ports.md
+247
View File
@@ -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
user_facing_docs/content/projects/_index.md
+63
View File
@@ -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/<id>` | GET | Get project details |
| `/projects/<id>` | PUT | Update project |
| `/projects/<id>` | 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
user_facing_docs/content/regions/_index.md
+58
View File
@@ -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/<id>` | GET | Get region details |
| `/regions/<id>` | PUT | Update region |
| `/regions/<id>` | DELETE | Delete region |
| `/regions/<id>/failover/pause` | POST | Pause failover |
| `/regions/<id>/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
user_facing_docs/content/storage/_index.md
+18
View File
@@ -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.
user_facing_docs/content/storage/attach-detach.md
+204
View File
@@ -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
user_facing_docs/content/storage/volumes.md
+208
View File
@@ -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
user_facing_docs/content/virtual-data-centers/_index.md
+68
View File
@@ -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/<id>` | GET | Get VDC details |
| `/virtual_data_centers/<id>` | PUT | Update VDC |
| `/virtual_data_centers/<id>` | DELETE | Delete VDC |
| `/virtual_data_centers/<id>/workloads` | GET | List VDC workloads |
| `/virtual_data_centers/<id>/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
user_facing_docs/content/virtual-machines/_index.md
+19
View File
@@ -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.
user_facing_docs/content/virtual-machines/create.md
+247
View File
@@ -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
user_facing_docs/content/virtual-machines/lifecycle.md
+291
View File
@@ -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
user_facing_docs/content/virtual-machines/manage.md
+274
View File
@@ -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@<vm-ip>
# SSH with custom port
ssh -i /path/to/key.pem -p 2222 ubuntu@<vm-ip>
```
### 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
user_facing_docs/hugo.toml
+46
View File
@@ -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
user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.content
+1
View File
File diff suppressed because one or more lines are too long
user_facing_docs/resources/_gen/assets/book.scss_b807c86e8030af4cdc30edccea379f5f.json
+1
View File
@@ -0,0 +1 @@
{"Target":"book.min.6970156cec683193d93c9c4edaf0d56574e4361df2e0c1be4f697ae81c3ba55f.css","MediaType":"text/css","Data":{"Integrity":"sha256-aXAVbOxoMZPZPJxO2vDVZXTkNh3y4MG+T2l66Bw7pV8="}}