Adoption Guide

This guide shows another repo how to adopt Railiance Fabric declarations without reading Railiance Fabric source code.

1. Add The Directory Layout

Create the declaration directories in your repo:

fabric/
  services/
  capabilities/
  interfaces/
  dependencies/
  bindings/

Start with only the files you need. A repo can adopt Fabric with one service and one capability, or with one dependency on a capability provided elsewhere.

2. Declare A Service

Create fabric/services/<repo>-<service>.yaml:

apiVersion: railiance.fabric/v1alpha1
kind: ServiceDeclaration
metadata:
  id: your-repo.your-service
  name: Your Service
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Service README
      path: README.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: What this service does.
  service_type: app-service
  provides_capabilities: []
  exposes_interfaces: []

Use lower-case dotted IDs. Prefer IDs that begin with the owning repo slug.

3. Declare A Provided Capability

Create fabric/capabilities/<repo>-<capability>.yaml:

apiVersion: railiance.fabric/v1alpha1
kind: CapabilityDeclaration
metadata:
  id: your-repo.your-service.runtime-secrets
  name: Runtime secrets
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Capability docs
      path: docs/runtime-secrets.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: What this capability provides.
  capability_type: runtime-secrets
  service_id: your-repo.your-service
  interface_ids:
    - your-repo.your-service.kv-v2
  criticality: high
  data_classification: secret

Pick capability_type from catalog/capability-types.yaml.

4. Declare An Interface

Create fabric/interfaces/<repo>-<interface>.yaml:

apiVersion: railiance.fabric/v1alpha1
kind: InterfaceDeclaration
metadata:
  id: your-repo.your-service.http-api
  name: Your Service HTTP API
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: API docs
      path: docs/api.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: How consumers call this interface.
  interface_type: http-api
  version: v1
  service_id: your-repo.your-service
  capability_ids:
    - your-repo.your-service.some-capability
  auth:
    method: oidc
  data_classification: internal

Pick interface_type from catalog/interface-types.yaml.

5. Declare A Dependency

Create fabric/dependencies/<repo>-<dependency>.yaml:

apiVersion: railiance.fabric/v1alpha1
kind: DependencyDeclaration
metadata:
  id: your-repo.your-service.needs-runtime-secrets
  name: Runtime secrets dependency
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Deployment values
      path: deploy/values.yaml
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  consumer_service_id: your-repo.your-service
  requires:
    capability_type: runtime-secrets
  interface:
    type: openbao-kv-v2-mount
    version_constraint: ">=v1 <v2"
  auth:
    method: kubernetes_service_account
  criticality: high
  data_classification: secret
  fallback:
    mode: none
    description: Service cannot start without runtime secrets.

Active production dependencies should include at least one source link.

6. Add A Binding Only When Needed

Most bindings can be computed by the graph loader from dependency requirements and provider capabilities. Add a BindingAssertion when you need to pin, override, dispute, or document a planned provider:

apiVersion: railiance.fabric/v1alpha1
kind: BindingAssertion
metadata:
  id: your-repo.your-service.runtime-secrets-to-openbao
  name: Runtime secrets binding
  owner: your-repo
  repo: your-repo
  domain: railiance
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  dependency_id: your-repo.your-service.needs-runtime-secrets
  provider_capability_id: railiance-platform.openbao.runtime-secrets
  provider_interface_id: railiance-platform.openbao.kv-v2
  status: compatible
  rationale: This service uses OpenBao KV v2 for runtime secrets.

7. Validate Locally

From the Railiance Fabric repo:

railiance-fabric validate /path/to/your-repo

During early bootstrapping:

PYTHONPATH=. python -m railiance_fabric.cli validate /path/to/your-repo

Useful discovery checks:

railiance-fabric providers runtime-secrets /path/to/your-repo
railiance-fabric consumers runtime-secrets /path/to/your-repo
railiance-fabric unresolved /path/to/your-repo

For multi-repo validation, pass multiple roots:

railiance-fabric validate /path/to/repo-a /path/to/repo-b

8. Export For State Hub

railiance-fabric export --format json /path/to/your-repo

State Hub should ingest that export as a read model. Do not edit declarations in State Hub; change them in the owning repo and re-export.

4.9 KiB Raw Blame History