Provisioning API Server

A comprehensive REST API server for remote provisioning operations, enabling thin clients and CI/CD pipeline integration.

Source: provisioning/platform/provisioning-server/

Features

• Comprehensive REST API: Complete provisioning operations via HTTP
• JWT Authentication: Secure token-based authentication
• RBAC System: Role-based access control (Admin, Operator, Developer, Viewer)
• Async Operations: Long-running tasks with status tracking
• Nushell Integration: Direct execution of provisioning CLI commands
• Audit Logging: Complete operation tracking for compliance
• Metrics: Prometheus-compatible metrics endpoint
• CORS Support: Configurable cross-origin resource sharing
• Health Checks: Built-in health and readiness endpoints

Architecture

┌─────────────────┐
│  REST Client    │
│  (curl, CI/CD)  │
└────────┬────────┘
         │ HTTPS/JWT
         ▼
┌─────────────────┐
│  API Gateway    │
│  - Routes       │
│  - Auth         │
│  - RBAC         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Async Task Mgr  │
│ - Queue         │
│  - Status       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Nushell Exec    │
│ - CLI wrapper   │
│ - Timeout       │
└─────────────────┘

Installation

cd provisioning/platform/provisioning-server
cargo build --release

Configuration

Create config.toml:

[server]
host = "0.0.0.0"
port = 8083
cors_enabled = true

[auth]
jwt_secret = "your-secret-key-here"
token_expiry_hours = 24
refresh_token_expiry_hours = 168

[provisioning]
cli_path = "/usr/local/bin/provisioning"
timeout_seconds = 300
max_concurrent_operations = 10

[logging]
level = "info"
json_format = false

Usage

Starting the Server

# Using config file
provisioning-server --config config.toml

# Custom settings
provisioning-server \
  --host 0.0.0.0 \
  --port 8083 \
  --jwt-secret "my-secret" \
  --cli-path "/usr/local/bin/provisioning" \
  --log-level debug

Authentication

Login

curl -X POST http://localhost:8083/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

Response:

{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}

Using Token

export TOKEN="eyJhbGc..."

curl -X GET http://localhost:8083/v1/servers \
  -H "Authorization: Bearer $TOKEN"

API Endpoints

Authentication

• POST /v1/auth/login - User login
• POST /v1/auth/refresh - Refresh access token

Servers

• GET /v1/servers - List all servers
• POST /v1/servers/create - Create new server
• DELETE /v1/servers/{id} - Delete server
• GET /v1/servers/{id}/status - Get server status

Taskservs

• GET /v1/taskservs - List all taskservs
• POST /v1/taskservs/create - Create taskserv
• DELETE /v1/taskservs/{id} - Delete taskserv
• GET /v1/taskservs/{id}/status - Get taskserv status

Workflows

• POST /v1/workflows/submit - Submit workflow
• GET /v1/workflows/{id} - Get workflow details
• GET /v1/workflows/{id}/status - Get workflow status
• POST /v1/workflows/{id}/cancel - Cancel workflow

Operations

• GET /v1/operations - List all operations
• GET /v1/operations/{id} - Get operation status
• POST /v1/operations/{id}/cancel - Cancel operation

System

• GET /health - Health check (no auth required)
• GET /v1/version - Version information
• GET /v1/metrics - Prometheus metrics

RBAC Roles

Admin Role

Full system access including all operations, workspace management, and system administration.

Operator Role

Infrastructure operations including create/delete servers, taskservs, clusters, and workflow management.

Developer Role

Read access plus SSH to servers, view workflows and operations.

Viewer Role

Read-only access to all resources and status information.

Security Best Practices

1. Change Default Credentials: Update all default usernames/passwords
2. Use Strong JWT Secret: Generate secure random string (32+ characters)
3. Enable TLS: Use HTTPS in production
4. Restrict CORS: Configure specific allowed origins
5. Enable mTLS: For client certificate authentication
6. Regular Token Rotation: Implement token refresh strategy
7. Audit Logging: Enable audit logs for compliance

CI/CD Integration

GitHub Actions

- name: Deploy Infrastructure
  run: |
    TOKEN=$(curl -X POST https://api.example.com/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{"username":"${{ secrets.API_USER }}","password":"${{ secrets.API_PASS }}"}' \
      | jq -r '.token')
    
    curl -X POST https://api.example.com/v1/servers/create \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"workspace": "production", "provider": "upcloud", "plan": "2xCPU-4GB"}'

Related Documentation

• API Reference: REST API Documentation
• Architecture: API Gateway Integration