Add Octopus Deploy Platform Hub knowledge base
New files: - PLATFORMHUB.md: index for Platform Hub guidance - platformhub/architecture.md: Git→PlatformHub→Projects model - platformhub/ocl-syntax.md: complete OCL reference for templates - platformhub/process-template-patterns.md: 5 proven patterns - platformhub/gotchas.md: every error hit and how to fix it - platformhub/api-reference.md: API vs UI capabilities - best-practices/octopus-process-templates.md: consolidated best practices Learned from building PlatformHub-Demo (30 microservices, 3 clouds). Key discoveries: step templates are space-scoped (can't cross-reference), worker_pool parameter is mandatory, publishing/sharing is UI-only. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
138
platformhub/process-template-patterns.md
Normal file
138
platformhub/process-template-patterns.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Process Template Patterns
|
||||
|
||||
Proven patterns for different deployment types, extracted from the PlatformHub-Demo project (30 microservices, 3 clouds, 8 teams).
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **One template per deployment pattern**, not per cloud or per service. Use parameters to vary behaviour.
|
||||
2. **Parameters for everything that varies** between consuming projects: cloud target, language, database type, target tags.
|
||||
3. **Sensible defaults** on parameters to reduce friction — consuming projects only override what differs.
|
||||
4. **Every template needs a `worker_pool` parameter** (type `WorkerPool`) — this is mandatory.
|
||||
5. **Inline scripts, not step template references** — process templates can't see step templates in other spaces.
|
||||
|
||||
## Template Catalogue
|
||||
|
||||
### Standard Go Service Deploy
|
||||
|
||||
**Use for:** Go microservices without special compliance or database requirements.
|
||||
**Steps:** Unit tests → Security scan → Container image scan → Helm deploy → Monitoring
|
||||
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `worker_pool`
|
||||
**Services example:** listing-service, search-service, category-service, config-service, order-service
|
||||
|
||||
Key characteristics:
|
||||
- Go test output with race detection and coverage
|
||||
- Semgrep SAST + Trivy SCA
|
||||
- Distroless base image scan + SBOM generation
|
||||
- Helm upgrade with cluster mapping by cloud target
|
||||
- Prometheus ServiceMonitor + Grafana dashboard + SLO alerting
|
||||
|
||||
### Python ML Service Deploy
|
||||
|
||||
**Use for:** Python services, especially ML/data pipeline services with model dependencies.
|
||||
**Steps:** Unit tests → Integration tests → Security scan → Container image scan → Helm deploy → Monitoring
|
||||
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `worker_pool`
|
||||
**Services example:** recommendation-service, fraud-service, moderation-service, ml-platform, analytics-pipeline
|
||||
|
||||
Key characteristics:
|
||||
- pytest with coverage table
|
||||
- Docker-compose integration tests (model validation, data pipeline tests)
|
||||
- Python-specific SAST (Semgrep + Bandit) + SCA (Safety + pip-audit)
|
||||
- GPU resource requests in Helm deploy
|
||||
- ML-specific monitoring: inference latency, model drift, batch queue depth
|
||||
|
||||
### Payment Service Deploy
|
||||
|
||||
**Use for:** Payment-path services requiring PCI-DSS compliance and zero-downtime deployment.
|
||||
**Steps:** Unit tests → Security scan → Container image scan → PCI-DSS check → Blue-green deploy → Monitoring → Rollback check
|
||||
**Parameters:** `target_tags`, `cloud_target` (default: aws), `worker_pool`
|
||||
**Services example:** payment-gateway, wallet-service, ledger-service, payout-service, escrow-service
|
||||
|
||||
Key characteristics:
|
||||
- Enhanced security scan with Gitleaks secret detection
|
||||
- 6-check PCI-DSS compliance gate (image signature, SBOM, secrets, TLS, network policy, audit logging)
|
||||
- Blue-green deployment with canary traffic phases (10% → 100%)
|
||||
- 4-nines SLO (99.99%), payment-specific alerting (circuit breaker, refund rate)
|
||||
- Post-deploy health validation with automatic rollback decision
|
||||
|
||||
### Database Service Deploy
|
||||
|
||||
**Use for:** Services with database dependencies requiring schema migrations.
|
||||
**Steps:** Unit tests → Security scan → Database migration → Container image scan → Helm deploy → Monitoring
|
||||
**Parameters:** `target_tags`, `cloud_target` (default: gcp), `database_type` (default: postgres), `language` (default: go), `worker_pool`
|
||||
**Services example:** user-service, ledger-service, order-service (any service with a DB)
|
||||
|
||||
Key characteristics:
|
||||
- Language-aware unit tests (Go/Python/Node switch)
|
||||
- SQL injection-focused security rules
|
||||
- Pre-migration snapshot with cloud-appropriate tooling (pg_dump, mysqldump, mongodump)
|
||||
- Versioned migration with per-migration timing
|
||||
- Post-migration validation (schema version, constraint check, data integrity)
|
||||
- DB-specific monitoring: connection pool, slow queries, migration version mismatch
|
||||
|
||||
### Node.js Service Deploy
|
||||
|
||||
**Use for:** Node.js services including API gateways, messaging, and notification services.
|
||||
**Steps:** Unit tests → Security scan → Container image scan → Helm deploy → Feature flag seeding → Monitoring
|
||||
**Parameters:** `target_tags`, `cloud_target` (default: azure), `worker_pool`
|
||||
**Services example:** messaging-service, notification-service, api-gateway
|
||||
|
||||
Key characteristics:
|
||||
- Jest-style test output with coverage table
|
||||
- npm audit + Trivy SCA
|
||||
- Feature flag seeding with environment-aware rollout percentages
|
||||
- Cloud-specific secrets manager integration (Azure Key Vault / AWS SM / GCP SM)
|
||||
- Node.js-specific monitoring: event loop lag, heap usage, WebSocket connections
|
||||
|
||||
## How Projects Consume Templates
|
||||
|
||||
In a project's `deployment_process.ocl`:
|
||||
|
||||
```hcl
|
||||
process_template "deploy-listing-service" {
|
||||
name = "Deploy Listing Service"
|
||||
process_template_slug = "standard-go-service-deploy"
|
||||
version_mask = "1.X" # Auto-update minor/patch
|
||||
|
||||
parameter "target_tags" {
|
||||
value = "gke-marketplace"
|
||||
}
|
||||
|
||||
parameter "cloud_target" {
|
||||
value = "gcp"
|
||||
}
|
||||
|
||||
parameter "worker_pool" {
|
||||
value = "WorkerPools-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Choosing the Right Template
|
||||
|
||||
```
|
||||
Does the service handle payments or financial data?
|
||||
└── YES → Payment Service Deploy
|
||||
|
||||
Does the service have database migrations?
|
||||
└── YES → Database Service Deploy
|
||||
|
||||
Is the service Python-based (ML, data, analytics)?
|
||||
└── YES → Python ML Service Deploy
|
||||
|
||||
Is the service Node.js-based?
|
||||
└── YES → Node.js Service Deploy
|
||||
|
||||
Default → Standard Go Service Deploy
|
||||
```
|
||||
|
||||
## Template-to-Service Mapping (PlatformHub-Demo)
|
||||
|
||||
| Template | Services |
|
||||
|----------|----------|
|
||||
| Standard Go Service | listing, search, search-indexer, category, media, config, event-bus, shipping, observability-collector, reporting, review, dispute |
|
||||
| Python ML Service | recommendation, fraud, moderation, ml-platform, analytics-pipeline |
|
||||
| Payment Service | payment-gateway, wallet, ledger, payout, escrow, kyc |
|
||||
| Database Service | user, auth, user-activity, order (overlay with others) |
|
||||
| Node.js Service | messaging, notification, api-gateway |
|
||||
|
||||
Note: Some services (like `order-service`) could use either Standard Go or Database Service depending on whether DB migrations are part of the deployment process.
|
||||
Reference in New Issue
Block a user