proxmox/docs/04-configuration/VAULT_MARKETPLACE_INTEGRATION.md

# Vault Marketplace Integration - Complete ✅

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Date:** 2026-01-19  
**Status:** ✅ **INTEGRATION COMPLETE**

---

## Summary

The Vault service has been successfully integrated into the Sankofa Phoenix Marketplace. Users can now provision virtual vaults that run on the existing high-availability Vault cluster.

---

## What Was Created

### 1. Vault Provisioning Service ✅

**File:** `dbis_core/src/core/iru/provisioning/vault-provisioning.service.ts`

- Provisions virtual vaults on the cluster
- Creates isolated namespaces per organization
- Generates AppRole credentials
- Configures policies based on capacity tier
- Manages virtual vault lifecycle

### 2. Vault Service Configuration ✅

**File:** `dbis_core/src/core/iru/deployment/vault-service-config.service.ts`

- Configures virtual vaults after provisioning
- Verifies cluster health
- Validates AppRole authentication
- Confirms path accessibility

### 3. Deployment Orchestrator Integration ✅

**File:** `dbis_core/src/core/iru/deployment/deployment-orchestrator.service.ts`

- Detects Vault offerings
- Skips container provisioning (uses shared cluster)
- Provisions virtual vault
- Stores credentials securely

### 4. Marketplace Seed Script ✅

**File:** `dbis_core/scripts/seed-vault-marketplace-offering.ts`

- Adds Vault offering to marketplace database
- Configures offering details
- Sets pricing and features

### 5. Documentation ✅

**File:** `dbis_core/docs/marketplace/VAULT_MARKETPLACE_SERVICE.md`

- Complete service documentation
- User guide
- API integration examples
- Security considerations

---

## How It Works

### Virtual Vault Concept

Instead of deploying separate Vault instances, users get **virtual vaults** - isolated namespaces within the shared cluster:

```
Vault Cluster (192.168.11.200-202)
├── Organization A
│   └── secret/data/organizations/org-a/vault-1/
├── Organization B
│   └── secret/data/organizations/org-b/vault-1/
└── Organization C
    └── secret/data/organizations/org-c/vault-1/
```

### Provisioning Flow

1. **User subscribes** to Vault service in marketplace
2. **User initiates deployment** from Phoenix Portal
3. **System provisions virtual vault:**
   - Creates unique organization ID
   - Generates vault path
   - Creates AppRole
   - Generates Role ID and Secret ID
   - Configures policies
   - Sets up secret path structure
4. **System verifies** virtual vault is accessible
5. **User receives credentials** via portal
6. **User integrates** with applications using credentials

---

## Setup Instructions

### 1. Add Offering to Marketplace

```bash
cd dbis_core
export VAULT_TOKEN=hvs.PMJcL6HkZnz0unUYZAdfttZY  # Root token for provisioning
npx tsx scripts/seed-vault-marketplace-offering.ts
```

### 2. Verify Offering

```bash
# Check offering was created
curl http://localhost:3000/api/v1/iru/marketplace/offerings | jq '.data[] | select(.offeringId == "VAULT-VIRTUAL-VAULT")'
```

### 3. Test Provisioning

```bash
# Test virtual vault provisioning (requires subscription)
# This would be done through the Phoenix Portal UI
```

---

## Configuration

### Environment Variables

The Vault provisioning service requires:

```bash
VAULT_TOKEN=hvs.PMJcL6HkZnz0unUYZAdfttZY  # Root token for cluster access
# OR
VAULT_ROOT_TOKEN=hvs.PMJcL6HkZnz0unUYZAdfttZY
```

**⚠️ Security Note:** In production, store this token securely (e.g., in Vault itself or secure secret manager).

### Vault Cluster Endpoints

The service is configured to use:
- http://192.168.11.200:8200 (Primary)
- http://192.168.11.201:8200 (Secondary)
- http://192.168.11.202:8200 (Tertiary)

These are hardcoded in `vault-provisioning.service.ts` but can be made configurable.

---

## User Experience

### Marketplace View

Users will see the Vault service in the marketplace with:
- Service name and description
- Features list
- Technical specifications
- Pricing information
- "Request Information" button

### Portal Deployment

After subscription, users can:
1. Navigate to "My Subscriptions"
2. Select Vault service
3. Click "Deploy Virtual Vault"
4. Configure options:
   - Vault name
   - Storage quota
   - Secret quota
   - Policy level
   - Backup enabled
   - Audit logging
5. Click "Deploy"
6. Wait ~30 minutes for provisioning
7. Receive credentials via portal

### Credentials Delivery

Users receive:
- **API Endpoint:** http://192.168.11.200:8200
- **Role ID:** Unique identifier
- **Secret ID:** Unique secret (one-time display)
- **Vault Path:** `secret/data/organizations/{org-id}/{vault-name}/`

**⚠️ Important:** Secret IDs should be displayed once and stored securely by the user.

---

## Security Considerations

### Credential Storage

- **Role IDs:** Stored in database (not sensitive)
- **Secret IDs:** Stored encrypted in deployment metadata
- **Root Token:** Stored in environment variable (should be in secure vault)

### Access Control

- Each virtual vault has isolated path
- Policies prevent cross-organization access
- AppRole credentials are unique per vault
- Token TTL: 1 hour (configurable)

### Recommendations

1. **Encrypt Secret IDs:** Store Secret IDs encrypted in database
2. **Rotate Root Token:** Use separate provisioning token
3. **Audit Logging:** Enable for all virtual vaults
4. **Monitor Access:** Track all API access
5. **Regular Backups:** Ensure daily backups are working

---

## Testing

### Test Virtual Vault Provisioning

```typescript
import { vaultProvisioningService } from '@/core/iru/provisioning/vault-provisioning.service';

const result = await vaultProvisioningService.provisionVirtualVault({
  subscriptionId: 'SUB-TEST-001',
  organizationName: 'Test Organization',
  vaultName: 'test-vault',
  capacityTier: 3,
  deploymentConfig: {
    policyLevel: 'standard',
    backupEnabled: true,
    auditLogging: true,
  },
});

console.log('Virtual Vault Provisioned:', result);
```

### Test Service Configuration

```typescript
import { vaultServiceConfigService } from '@/core/iru/deployment/vault-service-config.service';

const result = await vaultServiceConfigService.configureVaultService({
  vaultId: 'vault-test-org-1234567890',
  vaultPath: 'secret/data/organizations/test-org/test-vault',
  roleId: 'role-id-here',
  secretId: 'secret-id-here',
  apiEndpoint: 'http://192.168.11.200:8200',
  organizationId: 'test-org',
  subscriptionId: 'SUB-TEST-001',
});

console.log('Configuration Result:', result);
```

---

## Troubleshooting

### Provisioning Fails

**Issue:** Virtual vault provisioning fails

**Solutions:**
1. Check Vault cluster is accessible
2. Verify root token is valid
3. Check cluster is unsealed
4. Review logs for specific errors

### Authentication Fails

**Issue:** AppRole authentication doesn't work

**Solutions:**
1. Verify Role ID and Secret ID are correct
2. Check AppRole is enabled on cluster
3. Verify policy is attached to role
4. Check token TTL hasn't expired

### Path Not Accessible

**Issue:** Cannot access virtual vault path

**Solutions:**
1. Verify path exists
2. Check policy allows access
3. Verify AppRole has correct permissions
4. Check vault path format is correct

---

## Next Steps

### Immediate

1. ✅ **Seed Offering:** Run seed script to add to marketplace
2. ⏳ **Test Provisioning:** Test virtual vault creation
3. ⏳ **Update Portal UI:** Add Vault deployment UI
4. ⏳ **Documentation:** Create user-facing documentation

### Short-term

1. **Encrypt Secret IDs:** Implement encryption for stored credentials
2. **Monitoring:** Add virtual vault monitoring
3. **Quota Management:** Implement storage/secret quotas
4. **Billing Integration:** Connect to billing system

### Long-term

1. **Multi-Region:** Support multi-region virtual vaults
2. **Advanced Policies:** More granular policy options
3. **Secret Rotation:** Automated secret rotation
4. **Compliance Reporting:** Generate compliance reports

---

## Related Files

### Core Services
- `dbis_core/src/core/iru/provisioning/vault-provisioning.service.ts`
- `dbis_core/src/core/iru/deployment/vault-service-config.service.ts`
- `dbis_core/src/core/iru/deployment/deployment-orchestrator.service.ts`

### Scripts
- `dbis_core/scripts/seed-vault-marketplace-offering.ts`

### Documentation
- `dbis_core/docs/marketplace/VAULT_MARKETPLACE_SERVICE.md`
- `docs/04-configuration/PHOENIX_VAULT_INTEGRATION_GUIDE.md`

---

**Status:** ✅ **INTEGRATION COMPLETE**  
**Last Updated:** 2026-01-19