6c0f2db169
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>
120 lines
6.5 KiB
Markdown
120 lines
6.5 KiB
Markdown
# Platform Hub Architecture
|
|
|
|
## What Is Platform Hub?
|
|
|
|
Platform Hub is Octopus Deploy's mechanism for creating reusable deployment process templates that can be shared across spaces. It enables platform engineering teams to define standard deployment pipelines that project teams consume.
|
|
|
|
## Key Concepts
|
|
|
|
### The Three Layers
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Platform Hub Git Repo │
|
|
│ (e.g., github.com/org/taniwha.platform_hub) │
|
|
│ │
|
|
│ .octopus/process-templates/ │
|
|
│ ├── standard-go-service-deploy.ocl │
|
|
│ ├── python-ml-service-deploy.ocl │
|
|
│ ├── payment-service-deploy.ocl │
|
|
│ └── ... │
|
|
│ │
|
|
│ Defines: steps, parameters, scripts │
|
|
│ Stored in: Git (OCL files) │
|
|
└──────────────────────────┬──────────────────────────────────┘
|
|
│ Octopus reads OCL from Git
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Platform Hub (Octopus Instance) │
|
|
│ │
|
|
│ Publishing & Sharing: │
|
|
│ - Version management (semantic versioning) │
|
|
│ - Space visibility (which spaces can use each template) │
|
|
│ - Stored in: Octopus database (NOT Git) │
|
|
└──────────────────────────┬──────────────────────────────────┘
|
|
│ Projects reference templates
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Project (in any shared space) │
|
|
│ │
|
|
│ deployment_process.ocl: │
|
|
│ process_template "deploy-my-app" { │
|
|
│ process_template_slug = "standard-go-service-deploy" │
|
|
│ version_mask = "1.X" │
|
|
│ parameter "cloud_target" { value = "aws" } │
|
|
│ } │
|
|
│ │
|
|
│ Stored in: Project's Git repo (if CaC) or database │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### What Lives Where
|
|
|
|
| Artifact | Storage | Managed By |
|
|
|----------|---------|------------|
|
|
| Process template OCL (steps, scripts, parameters) | Git repo | Engineers via commits |
|
|
| Template versioning (major.minor.patch) | Octopus database | UI (publish action) |
|
|
| Template sharing (space visibility) | Octopus database | UI only — no API/CLI |
|
|
| Step templates (ActionTemplates) | Octopus database, per-space | API or UI |
|
|
| Project consumption of templates | Project Git repo (CaC) or DB | Engineers or API |
|
|
|
|
### Step Templates vs Process Templates
|
|
|
|
These are **different things** that complement each other:
|
|
|
|
| | Step Templates | Process Templates |
|
|
|---|---|---|
|
|
| **Scope** | Single step (one action) | Multi-step pipeline |
|
|
| **Storage** | Octopus DB, per-space | Git repo (OCL) |
|
|
| **Created via** | API or UI | Git commit |
|
|
| **Referenced by** | `Octopus.Action.Template.Id` | `process_template_slug` |
|
|
| **Cross-space** | No — space-scoped | Yes — via Platform Hub sharing |
|
|
| **Use in process templates** | Cannot reference cross-space | N/A |
|
|
|
|
**Critical:** Process templates in Platform Hub **cannot reference step templates from other spaces**. If you have reusable step templates in Space A, a process template in Platform Hub cannot use them. Instead, process templates must use inline `action_type` definitions.
|
|
|
|
## Git Repo Structure
|
|
|
|
The Platform Hub repo has a fixed structure that Octopus expects:
|
|
|
|
```
|
|
.octopus/
|
|
process-templates/
|
|
template-slug-name.ocl # One file per process template
|
|
another-template.ocl
|
|
README.md # Optional documentation
|
|
```
|
|
|
|
- Files must be in `.octopus/process-templates/`
|
|
- File extension must be `.ocl`
|
|
- The filename becomes the template slug (minus `.ocl`)
|
|
- Octopus reads from the `main` branch (configurable)
|
|
|
|
## Versioning and Updates
|
|
|
|
- Templates use **semantic versioning** (major.minor.patch)
|
|
- Publishing creates a new version
|
|
- Consuming projects use `version_mask` to control updates:
|
|
- `"1.X"` — auto-update on minor/patch, manual upgrade for major
|
|
- `"1.2.X"` — auto-update on patch only
|
|
- `"1.2.3"` — pinned to exact version
|
|
- **Major version bumps** are breaking changes: parameter renames, step removals
|
|
- **Minor/patch** for non-breaking: new optional params, script improvements, bug fixes
|
|
|
|
## Setting Up a New Platform Hub
|
|
|
|
1. Create a Git repo (GitHub, Gitea, etc.)
|
|
2. Create `.octopus/process-templates/` directory
|
|
3. Add OCL files (see [OCL Syntax Reference](ocl-syntax.md))
|
|
4. In Octopus: configure Platform Hub to point at the Git repo
|
|
5. Templates appear in the UI after Octopus reads the repo
|
|
6. Publish each template (UI) to create a version
|
|
7. Share each template with desired spaces (UI)
|
|
|
|
## References
|
|
|
|
- [Process Templates Docs](https://octopus.com/docs/platform-hub/templates/process-templates)
|
|
- [Template Parameters](https://octopus.com/docs/platform-hub/templates/parameters)
|
|
- [Publishing & Sharing](https://octopus.com/docs/platform-hub/templates/publishing-and-sharing)
|
|
- [Best Practices](https://octopus.com/docs/platform-hub/templates/process-templates/best-practices)
|