Skip to main content
This tutorial walks you through building a complete provider from an empty directory to a deployed, usable resource type. You will create a provider that manages JSON configuration files.

What You’ll Build

A jsonstore provider with a config resource that:
  • Creates JSON configuration files
  • Updates file contents when configuration changes
  • Deletes files on resource removal
  • Exposes file path and content hash as outputs
This example uses local files to keep things simple. The same patterns apply when integrating with cloud APIs, databases, or any external service.

Prerequisites

Before starting, ensure you have:
  • Python 3.13+ installed
  • uv package manager (install instructions)
  • Pragmatiks CLI authenticated (pragma auth login)
Verify your setup:
Expected output:

Step 1: Initialize the Project

Create a new provider project using the CLI:
Expected output:
Install dependencies:
Your project structure:

Step 2: Define the Resource

Replace the example resource with your JSON config resource. Open src/jsonstore_provider/resources/example.py and replace the contents:

Step 3: Register the Resource

Update src/jsonstore_provider/resources/__init__.py to export your resource:
Update src/jsonstore_provider/__init__.py to register the resource with the provider:

Step 4: Write Tests

Testing locally before deployment catches bugs early and speeds up development. Replace tests/test_example.py:
Run the tests:
Expected output:

Step 5: Deploy the Provider

Build and deploy your provider:
Expected output:

Step 6: Create a Resource

Now users can create resources using your provider. Create a file my-config.yaml:
Apply it:
Expected output:
Check the resource status:

Summary

You’ve built a complete provider that:
  1. Defines Config and Outputs schemas with validation
  2. Implements idempotent lifecycle methods (create, update, delete)
  3. Tests locally using ProviderHarness
  4. Deploys to the platform with pragma providers push
The same patterns apply to any integration. Replace the file operations with API calls to cloud services, databases, or internal tools.

Next Steps

Config and Outputs

Design schemas with validation, defaults, and dependencies.

Lifecycle Methods

Deep dive into handlers, subresources, and idempotency.

Testing

Test patterns with ProviderHarness and mocking.

CLI Reference

Full reference for init, sync, push, and deploy commands.