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

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

2. Verify Offering

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

3. Test Provisioning

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

---

Configuration

Environment Variables

The Vault provisioning service requires:

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

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

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