Getting Started¶

Welcome to the Provide Foundry! This guide will get you up and running with all the tools you need to build Terraform providers, package applications, and manage your development workflow.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Prerequisites¶

Before you start, ensure you have:

Python 3.11 or higher
Git for version control
A Unix-like environment (macOS, Linux, or WSL on Windows)

Python Version

The Provide Foundry uses modern Python features and requires 3.11+. We recommend using UV to manage Python versions with uv python install 3.11.

Quick Setup¶

The fastest way to get started is to set up the entire foundry using our unified workspace:

# Clone the workspace repository
git clone https://github.com/provide-io/provide-workspace.git
cd provide-workspace

# Set up the unified development environment
uv sync --extra all --extra dev
source .venv/bin/activate

This single command:

✅ Installs UV package manager (if needed)
✅ Creates a unified virtual environment
✅ Installs all 13 foundry packages in editable mode
✅ Includes all development tools (ruff, mypy, pytest, etc.)
✅ Sets up proper dependency resolution between packages

Verification

Verify your setup by running:

python -c "import provide, pyvider; print('✅ Foundry ready!')"

Your First Terraform Provider¶

Let's create a simple Terraform provider to see the framework in action:

1. Create a New Provider¶

my_provider.py

from pyvider.providers import register_provider, BaseProvider
from pyvider.resources import register_resource, BaseResource
from pyvider.schema import Attribute

@register_provider("hello")
class HelloProvider(BaseProvider):
    """A simple greeting provider."""

    # Provider configuration
    api_key: str = Attribute(
        description="API key for authentication",
        sensitive=True,
        required=True
    )

@register_resource("greeting")
class Greeting(BaseResource):
    """A greeting resource."""

    # Resource schema
    name: str = Attribute(
        description="Name to greet",
        required=True
    )

    message: str = Attribute(
        description="The greeting message",
        computed=True
    )

    # Lifecycle methods
    def create(self, config):
        """Create a new greeting."""
        message = f"Hello, {config.name}!"
        return {
            "id": f"greeting-{config.name.lower()}",
            "name": config.name,
            "message": message
        }

    def read(self, config, state):
        """Read an existing greeting."""
        return state  # Static resource, return as-is

    def update(self, config, state):
        """Update a greeting."""
        message = f"Hello, {config.name}!"
        return {
            **state,
            "name": config.name,
            "message": message
        }

    def delete(self, config, state):
        """Delete a greeting."""
        # Nothing to clean up for this example
        pass

2. Package Your Provider¶

Use flavorpack to create a self-contained executable:

# Create a package manifest
cat > provider.toml << EOF
[package]
name = "terraform-provider-hello"
entry_point = "my_provider:main"

[build]
dependencies = [
    "pyvider",
    "pyvider-components"
]
EOF

# Build the provider
flavor pack --manifest provider.toml --output terraform-provider-hello

3. Use Your Provider¶

Create a Terraform configuration:

main.tf

terraform {
  required_providers {
    hello = {
      source = "local/example/hello"
      version = "1.0.0"
    }
  }
}

provider "hello" {
  api_key = "secret-key"
}

resource "hello_greeting" "example" {
  name = "World"
}

output "greeting_message" {
  value = hello_greeting.example.message
}

Run Terraform:

# Initialize Terraform
terraform init

# Apply the configuration
terraform apply

Expected output:

greeting_message = "Hello, World!"

Development Workflow¶

Project Structure¶

A typical provide.io project follows this structure:

my-provider/
├── pyproject.toml          # Package configuration
├── src/
│   └── my_provider/        # Provider source code
│       ├── __init__.py
│       ├── provider.py     # Provider definition
│       ├── resources/      # Resource implementations
│       └── data_sources/   # Data source implementations
├── tests/                  # Test suite
├── docs/                   # Documentation
├── examples/               # Example configurations
└── README.md               # Project overview

Development Commands¶

Common development tasks using the foundry tools:

# Code quality
ruff format .               # Format code
ruff check .                # Lint code
mypy src/                   # Type checking

# Testing
pytest                      # Run tests
pytest --cov               # Run with coverage
pytest -m "not slow"       # Skip slow tests

# Documentation
plating render              # Generate provider docs
mkdocs serve               # Serve docs locally

# Environment management
wrknv sync                 # Sync environment
uv sync      # Activate environment

# Packaging
flavor pack                # Create executable package
flavor verify package.psp # Verify package integrity

Git Workflow¶

Use supsrc for automated Git workflow management:

# Start automated Git watching
supsrc watch

# Configure automatic commits
supsrc config set auto_commit true
supsrc config set commit_interval 300  # 5 minutes

Key Concepts¶

1. Foundation Layer¶

Everything builds on provide-foundation, which provides:

Structured Logging: Beautiful, emoji-enhanced logs
Error Handling: Rich error context and handling
Configuration: Type-safe configuration management

from provide.foundation import logger

log = logger.get_logger(__name__)
log.info("Application started", version="1.0.0")

2. Type Safety¶

The foundry emphasizes type safety throughout:

from pyvider.schema import a_str, a_num, a_bool
from attrs import define

# Type-safe configuration with schema
@define
class Config:
    name: str  # Type hints for IDE support
    port: int
    enabled: bool = True

    @classmethod
    def get_schema(cls):
        """Define schema using factory functions."""
        return {
            "name": a_str(required=True),
            "port": a_num(required=True),
            "enabled": a_bool(default=True)
        }

3. Testing¶

Use provide-testkit for comprehensive testing:

import pytest
from provide.testkit import temp_directory, mock_server

def test_provider_creation(temp_directory):
    """Test provider functionality."""
    # Test implementation
    pass

@pytest.mark.asyncio
async def test_async_operation(mock_server):
    """Test async operations."""
    # Async test implementation
    pass

4. Documentation¶

Generate documentation automatically with plating:

# Generate provider documentation
plating render --provider my_provider --output docs/

# Serve documentation
mkdocs serve -f docs/mkdocs.yml

Next Steps¶

Now that you have the foundry set up, explore these guides:

Building Providers

Learn to create comprehensive Terraform providers with resources, data sources, and functions.
Packaging Applications

Use flavorpack to create self-contained, portable executable packages.
Testing Strategy

Implement comprehensive testing with unit, integration, and conformance tests.
Documentation

Generate beautiful documentation for your providers and tools.

Getting Help¶

If you run into issues:

Check the documentation: Each package has comprehensive docs
Search issues: Look for existing solutions on GitHub
Ask questions: Use GitHub Discussions for help
Report bugs: Create detailed issue reports

Examples Repository¶

Explore complete examples in the examples repository:

Simple providers
Complex multi-resource providers
Integration with external APIs
Testing strategies
Documentation examples

Happy building! 🚀