Getting Started

Learn how to get started with Firestoned - from building your first API with firestone to exploring the Kubernetes-native DNS utilities

Getting Started with Firestoned

Welcome to the Firestoned ecosystem! This guide will walk you through everything you need to know to build API-driven infrastructure, starting with firestone - the core API specification generator.

What You’ll Learn

Ecosystem Overview

Firestoned is a toolkit for building API-driven infrastructure, centered around firestone - an innovative API specification generator. The ecosystem demonstrates infrastructure-as-code principles through practical Kubernetes-native DNS management utilities.

Components

Core: API Generation

  • firestone: The heart of Firestoned. Generates OpenAPI/AsyncAPI specifications and CLI tools from JSON Schema resource definitions. Define your resources once, generate everything else automatically.
  • firestone-lib: Shared library powering firestone. Provides reusable components for spec generation, validation, and transformation.

Utilities: Kubernetes-Native DNS Management

These components demonstrate the power of API-driven infrastructure by implementing declarative DNS management:

  • bindy: Kubernetes operator managing BIND9 DNS through Custom Resource Definitions (CRDs). Demonstrates how to build infrastructure operators with declarative APIs.
  • bindcar: REST API sidecar for BIND9 zone management. Its OpenAPI spec is generated using firestone, showing the API generation workflow in action.
  • zonewarden: Kubernetes controller for automatic service-to-DNS synchronization. Shows how to build automation that bridges Kubernetes services with external systems.

How It Works Together

The DNS utilities showcase a complete implementation of API-driven infrastructure management:

Visualization

graph TB
    subgraph "Development"
        firestone[firestone<br/>API Generator]
    end

    subgraph "Kubernetes Cluster"
        kubectl[kubectl apply]
        crds[DNS CRDs<br/>Zones & Records]
        bindy[bindy<br/>DNS Operator]
        zonewarden[zonewarden<br/>Service Watcher]
        svc[Kubernetes Services]
    end

    subgraph "DNS Infrastructure"
        bindcar[bindcar<br/>REST API]
        bind9[BIND9<br/>DNS Server]
    end

    firestone -.API Spec.-> bindcar
    kubectl --> crds
    crds --> bindy
    svc --> zonewarden
    zonewarden --> bindy
    bindy --> bindcar
    bindcar --> bind9

    style bindy fill:#0066cc,color:#fff
    style bindcar fill:#0066cc,color:#fff
    style zonewarden fill:#0066cc,color:#fff
    style firestone fill:#ff6b35,color:#fff

Example Workflow: DNS Management

This workflow demonstrates how the utilities work together for DNS infrastructure:

  1. API Definition (Development Time): Use firestone to generate the OpenAPI specification for bindcar’s REST API from JSON Schema resource definitions.
  2. Declarative Management: Define desired DNS state by creating Kubernetes CRDs (e.g., kubectl apply -f zone.yaml).
  3. Operator Reconciliation: The bindy operator detects new CRDs and prepares API calls.
  4. Automated Discovery: zonewarden watches Kubernetes Services and automatically creates DNS records for them.
  5. API Execution: bindy calls the bindcar REST API to update the DNS server.
  6. DNS Updates: bindcar translates API calls into BIND9 rndc commands.

This demonstrates a fully declarative, GitOps-friendly approach to infrastructure management using APIs generated by firestone.

Quick Start

Build your first API with firestone in 5 minutes:

Step 1: Install firestone

# Install using poetry (note: package is 'firestoned', import as 'firestone')
poetry add firestoned

# Verify installation
poetry run firestone --version

Step 2: Define Your Resource

Create a file book-resource.yaml that defines a simple book management API:

name: book
description: Book resource for library management API
version: 1.0
version_in_path: false

methods:
  resource: [get, post]
  instance: [get, put, delete]

schema:
  type: array
  key:
    name: book_id
    schema:
      type: string
      description: Unique identifier for the book
  items:
    type: object
    properties:
      title:
        type: string
        description: Book title
      author:
        type: string
        description: Book author
      isbn:
        type: string
        description: ISBN number
      published_year:
        type: integer
        description: Year of publication
    required: [title, author, isbn]

Step 3: Generate OpenAPI Specification

# Generate OpenAPI spec
firestone generate \
    --title 'Library Management API' \
    --description 'RESTful API for managing library books' \
    --resources book-resource.yaml \
    openapi > library-api.yaml

# Optional: Generate with Swagger UI server
firestone generate \
    --title 'Library Management API' \
    --resources book-resource.yaml \
    openapi --ui-server

Step 4: Generate Client Code and CLI

# Generate Python client using openapi-generator
openapi-generator generate \
    -i library-api.yaml \
    -g python \
    -o library-client/

# Generate a Python Click-based CLI
firestone generate \
    --title 'Library CLI' \
    --resources book-resource.yaml \
    cli \
    --pkg library_cli \
    --client-pkg library_client > library_cli.py

Congratulations! 🎉 You’ve just built a complete API specification, client library, and CLI tool from a single resource definition.

Next Steps

Master firestone

Explore advanced features of the API generator:

Explore firestone-lib

Build custom generators and tools:

See It In Action: DNS Utilities

See how firestone powers real-world infrastructure:

Common Patterns

Pattern 1: API-First Resource Design

Define infrastructure resources using JSON Schema, generate everything else:

# resource.yaml - Your single source of truth
name: server
description: Server management resource
schema:
  type: array
  key:
    name: server_id
  items:
    type: object
    properties:
      hostname:
        type: string
      ip_address:
        type: string
      status:
        type: string
        enum: [active, maintenance, offline]

Then generate:

  • OpenAPI spec: firestone generate --resources resource.yaml openapi
  • CLI tool: firestone generate --resources resource.yaml cli
  • Client libraries using openapi-generator

Pattern 2: GitOps Infrastructure Management

Store resource definitions and generated specs in Git for full infrastructure-as-code:

# Repository structure
infrastructure/
├── resources/
│   ├── server.yaml
│   ├── network.yaml
│   └── storage.yaml
├── generated/
│   ├── openapi/
│   └── cli/
└── deployments/
    ├── production/
    └── staging/

Pattern 3: Kubernetes Operator Integration

Use firestone-generated APIs in Kubernetes operators (like the DNS utilities):

  • Define API resources with JSON Schema
  • Generate OpenAPI specs with firestone
  • Build operators that consume the generated APIs
  • Deploy declaratively with kubectl

Troubleshooting

Installation Issues

If poetry add firestoned fails:

# Ensure you have Python 3.9+
python --version

# Ensure poetry is installed
poetry --version

# If poetry is not installed, install it
curl -sSL https://install.python-poetry.org | python3 -

# Install with verbose output
poetry add -vvv firestoned

Generation Errors

If OpenAPI generation fails, validate your resource schema:

# Enable debug logging
firestone --debug generate --resources resource.yaml openapi

# Check for JSON Schema validation errors
# Ensure required fields are present: name, description, schema

Import vs Package Name

Remember: Install as firestoned, import as firestone:

poetry add firestoned  # Package name on PyPI

import firestone  # Module name in Python

Need Help?

Last modified December 9, 2025: Initial commmit of website (fac9cba)