79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
|
# Integration Templates (ADR-015 / federated OCI artifacts)
|
||
|
|
|
||
|
|
Three starting templates for integration. Pick the role you want to play; you
|
||
|
|
can be both a producer and a consumer.
|
||
|
|
|
||
|
|
## Pick the template that matches what you want to do
|
||
|
|
|
||
|
|
| Template | Role | Outcome |
|
||
|
|
|---|---|---|
|
||
|
|
| `domain-producer/` | Define a typed contract for structured data | Push `domains/<participant>/<id>:<version>` to ZOT |
|
||
|
|
| `mode-producer/` | Author an orchestration mode that consumes domains | Push `modes/<participant>/<id>:<version>` to ZOT |
|
||
|
|
| `mode-consumer/` | Adopt someone else's published mode | Cabling file in `infra/<ws>/integrations/` |
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```text
|
||
|
|
domain-producer/
|
||
|
|
contract.ncl.template ← schema (Nickel types) for the structured data
|
||
|
|
example.json.template ← reference instance matching the contract
|
||
|
|
manifest.ncl.template ← DomainArtifact descriptor
|
||
|
|
|
||
|
|
mode-producer/
|
||
|
|
provisioning.ncl.template ← IntegrationMode declaration
|
||
|
|
domains.lock.ncl.template ← pinned versions of consumed domains
|
||
|
|
manifest.ncl.template ← ModeArtifact descriptor
|
||
|
|
|
||
|
|
mode-consumer/
|
||
|
|
cabling.ncl.template ← binds mode params to workspace values
|
||
|
|
```
|
||
|
|
|
||
|
|
## Workflow
|
||
|
|
|
||
|
|
### Producer (one-time per artifact)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. Copy template to your catalog dir
|
||
|
|
cp -r install/resources/templates/integration/domain-producer/ catalog/domains/my-domain/
|
||
|
|
mv catalog/domains/my-domain/contract.ncl.template catalog/domains/my-domain/contract.ncl
|
||
|
|
mv catalog/domains/my-domain/example.json.template catalog/domains/my-domain/example.json
|
||
|
|
mv catalog/domains/my-domain/manifest.ncl.template catalog/domains/my-domain/manifest.ncl
|
||
|
|
|
||
|
|
# 2. Edit the files: replace <placeholders>, define your types
|
||
|
|
|
||
|
|
# 3. Publish
|
||
|
|
ore secrets bootstrap # one-time, vault setup
|
||
|
|
prvng integration domain publish catalog/domains/my-domain <participant>
|
||
|
|
prvng integration domain verify <participant>/my-domain 0.1.0
|
||
|
|
```
|
||
|
|
|
||
|
|
### Consumer (one-time per mode you adopt)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. Subscribe — pulls the mode + its domain dependencies, scaffolds cabling
|
||
|
|
prvng integration subscribe <mode-id> \
|
||
|
|
--mode-file infra/modes/<mode-id>.ncl \
|
||
|
|
--workspace-dir .
|
||
|
|
|
||
|
|
# 2. Edit the generated cabling file
|
||
|
|
$EDITOR infra/<ws>/integrations/<mode-id>.ncl
|
||
|
|
|
||
|
|
# 3. Validate that all bindings resolve
|
||
|
|
prvng integration validate <mode-id> --workspace-dir .
|
||
|
|
|
||
|
|
# 4. Invoke the mode
|
||
|
|
prvng integration invoke <mode-id> --binary <name>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Without templates: minimal viable
|
||
|
|
|
||
|
|
The artifact format is documented in `provisioning/schemas/lib/integration/oci_artifact_format.ncl`.
|
||
|
|
You can write `contract.ncl`, `manifest.ncl`, `provisioning.ncl` from scratch following
|
||
|
|
the type definitions there. Templates only save copy-paste time.
|
||
|
|
|
||
|
|
## See also
|
||
|
|
|
||
|
|
- `reflection/qa.ncl::integration-*` — FAQ with diagrams
|
||
|
|
- `provisioning/schemas/lib/integration/oci_artifact_format.ncl` — types
|
||
|
|
- `prvng integration --help` — command surface
|