# 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

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

## Installation

```bash
cd provisioning/platform/provisioning-server
cargo build --release
```plaintext

## Configuration

Create `config.toml`:

```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
```plaintext

## Usage

### Starting the Server

```bash
# 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
```plaintext

### Authentication

#### Login

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

Response:

```json
{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}
```plaintext

#### Using Token

```bash
export TOKEN="eyJhbGc..."

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

## 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

```yaml
- 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-4 GB"}'
```plaintext

## Related Documentation

- **API Reference**: [REST API Documentation](../api/rest-api.md)
- **Architecture**: [API Gateway Integration](../architecture/integration-patterns.md)
