Skip to content

Building Your First Resource

Release Status

pyvider is in pre-release. This tutorial covers stable functionality. Some APIs may change during the pre-release series. See project status for details.

🤖 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.

Welcome! In this tutorial, you'll build your first Terraform resource using pyvider. By the end, you'll have a working file resource that creates, reads, updates, and deletes local files through Terraform.

What You'll Learn:

  • How resources work in Terraform
  • Creating a resource class with pyvider
  • Defining schemas for user configuration
  • Implementing lifecycle methods (CRUD operations)
  • Testing your resource with Terraform

Time to Complete: 15-20 minutes

Prerequisites:

  • Python 3.11+ installed
  • pyvider installed (installation guide)
  • Basic Python knowledge
  • Basic Terraform knowledge

What is a Resource?

A resource in Terraform represents a piece of infrastructure that can be managed (created, updated, deleted). Think of resources as the things you want to manage:

  • A file on disk
  • A server in the cloud
  • A database record
  • An API object

Resources have a lifecycle:

  1. Create - Make something new
  2. Read - Check current state
  3. Update - Modify existing thing
  4. Delete - Remove it

Terraform handles this lifecycle automatically. You just implement the operations!

Step 1: Create Your Provider Package

First, let's create a simple provider package structure:

Bash
1
2
3
4
mkdir -p my_provider/resources
touch my_provider/__init__.py
touch my_provider/resources/__init__.py
touch my_provider/resources/file.py

Your structure should look like:

Text Only
1
2
3
4
5
my_provider/
├── __init__.py
└── resources/
    ├── __init__.py
    └── file.py      # We'll work in this file

Step 2: Define Runtime Types

Open my_provider/resources/file.py and start by defining the data structures.

Resources work with two types of data:

  • Configuration - What the user provides in their Terraform code
  • State - What actually exists (tracked by Terraform)

Let's define these using attrs:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Runtime configuration class (Python type safety)
@attrs.define
class FileConfig:
    """What the user configures."""

    path: str  # Where to create the file
    content: str  # What to write in the file
    mode: str = "644"  # File permissions (optional, defaults to 644)


# Runtime state class (Python type safety)
@attrs.define
class FileState:
    """What Terraform tracks about the file."""

    id: str  # Unique identifier
    path: str  # File path
    content: str  # Current content
    mode: str  # Current permissions
    size: int  # File size in bytes (computed by us)

Why separate Config and State?

  • Config = what user wants
  • State = what currently exists
  • Terraform compares them to know when to update

Step 3: Create the Resource Class

Now let's create the resource class itself:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
@register_resource("file")
class File(BaseResource):
    """Manages a local file."""

    # Link our runtime types
    config_class = FileConfig
    state_class = FileState

    @classmethod
    def get_schema(cls) -> PvsSchema:
        """Define what Terraform users see."""
        return s_resource(
            {
                # User inputs
                "path": a_str(required=True, description="File path"),
                "content": a_str(required=True, description="File content"),
                "mode": a_str(default="644", description="File permissions"),
                # Provider outputs (we compute these)
                "id": a_str(computed=True, description="File ID"),
                "size": a_num(computed=True, description="File size in bytes"),
            }
        )

What's happening here?

  • @register_resource("file") - Registers this as a Terraform resource
  • config_class / state_class - Links our attrs classes
  • get_schema() - Defines what users configure in Terraform HCL

Step 4: Implement Read (Check State)

The read() method checks if the resource still exists and returns its current state:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    async def read(self, ctx: ResourceContext) -> FileState | None:
        """Refresh state from filesystem."""
        # If no existing state, nothing to read
        if not ctx.state:
            return None

        file_path = Path(ctx.state.path)

        # Check if file still exists
        if not file_path.exists():
            return None  # File was deleted outside Terraform

        # File exists! Return current state
        content = file_path.read_text()
        return FileState(
            id=ctx.state.id,
            path=str(file_path),
            content=content,
            mode=ctx.state.mode,
            size=len(content),
        )

Why return None?

  • None tells Terraform "this resource doesn't exist anymore"
  • Terraform will then know to recreate it

Step 5: Implement Create

The _create_apply() method creates a new file:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    async def _create_apply(self, ctx: ResourceContext) -> tuple[FileState | None, None]:
        """Create file."""
        if not ctx.config:
            return None, None

        file_path = Path(ctx.config.path)

        # Write the file
        file_path.write_text(ctx.config.content)

        # Return new state
        return FileState(
            id=str(file_path.absolute()),
            path=str(file_path),
            content=ctx.config.content,
            mode=ctx.config.mode,
            size=len(ctx.config.content),
        ), None

Return value explained:

  • First element: New state to track
  • Second element: Private data (advanced, we don't need it)

Step 6: Implement Update

The _update_apply() method modifies an existing file:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    async def _update_apply(self, ctx: ResourceContext) -> tuple[FileState | None, None]:
        """Update file."""
        if not ctx.config or not ctx.state:
            return None, None

        file_path = Path(ctx.state.path)

        # Update the file content
        file_path.write_text(ctx.config.content)

        # Return updated state
        return FileState(
            id=ctx.state.id,
            path=ctx.state.path,
            content=ctx.config.content,
            mode=ctx.config.mode,
            size=len(ctx.config.content),
        ), None

Step 7: Implement Delete

The _delete_apply() method removes the file:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    async def _delete_apply(self, ctx: ResourceContext) -> None:
        """Delete file."""
        if not ctx.state:
            return

        file_path = Path(ctx.state.path)

        # Delete file if it exists
        if file_path.exists():
            file_path.unlink()

Let's add configuration validation to prevent bad inputs:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    async def _validate_config(self, config: FileConfig) -> list[str]:
        """Validate configuration."""
        errors = []

        # Prevent path traversal attacks
        if ".." in config.path:
            errors.append("Path cannot contain '..'")

        # Validate file mode format
        if not config.mode.isdigit() or len(config.mode) != 3:
            errors.append("Mode must be 3 digits (e.g., '644')")

        return errors

Complete Code

Here's your complete file.py:

Python
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
"""
Complete file resource example with validation.

This snippet demonstrates a full-featured resource implementation including:
- Runtime type definitions with attrs
- Schema definition with validation
- All CRUD operations (create, read, update, delete)
- Configuration validation

Used in: tutorials, guides
"""

from pathlib import Path

import attrs

from pyvider.resources import BaseResource, register_resource
from pyvider.resources.context import ResourceContext
from pyvider.schema import PvsSchema, a_num, a_str, s_resource


# Runtime configuration class (Python type safety)
@attrs.define
class FileConfig:
    """What the user configures."""

    path: str  # Where to create the file
    content: str  # What to write in the file
    mode: str = "644"  # File permissions (optional, defaults to 644)


# Runtime state class (Python type safety)
@attrs.define
class FileState:
    """What Terraform tracks about the file."""

    id: str  # Unique identifier
    path: str  # File path
    content: str  # Current content
    mode: str  # Current permissions
    size: int  # File size in bytes (computed by us)




@register_resource("file")
class File(BaseResource):
    """Manages a local file."""

    # Link our runtime types
    config_class = FileConfig
    state_class = FileState

    @classmethod
    def get_schema(cls) -> PvsSchema:
        """Define what Terraform users see."""
        return s_resource(
            {
                # User inputs
                "path": a_str(required=True, description="File path"),
                "content": a_str(required=True, description="File content"),
                "mode": a_str(default="644", description="File permissions"),
                # Provider outputs (we compute these)
                "id": a_str(computed=True, description="File ID"),
                "size": a_num(computed=True, description="File size in bytes"),
            }
        )


    async def _validate_config(self, config: FileConfig) -> list[str]:
        """Validate configuration."""
        errors = []

        # Prevent path traversal attacks
        if ".." in config.path:
            errors.append("Path cannot contain '..'")

        # Validate file mode format
        if not config.mode.isdigit() or len(config.mode) != 3:
            errors.append("Mode must be 3 digits (e.g., '644')")

        return errors


    async def read(self, ctx: ResourceContext) -> FileState | None:
        """Refresh state from filesystem."""
        # If no existing state, nothing to read
        if not ctx.state:
            return None

        file_path = Path(ctx.state.path)

        # Check if file still exists
        if not file_path.exists():
            return None  # File was deleted outside Terraform

        # File exists! Return current state
        content = file_path.read_text()
        return FileState(
            id=ctx.state.id,
            path=str(file_path),
            content=content,
            mode=ctx.state.mode,
            size=len(content),
        )


    async def _create_apply(self, ctx: ResourceContext) -> tuple[FileState | None, None]:
        """Create file."""
        if not ctx.config:
            return None, None

        file_path = Path(ctx.config.path)

        # Write the file
        file_path.write_text(ctx.config.content)

        # Return new state
        return FileState(
            id=str(file_path.absolute()),
            path=str(file_path),
            content=ctx.config.content,
            mode=ctx.config.mode,
            size=len(ctx.config.content),
        ), None


    async def _update_apply(self, ctx: ResourceContext) -> tuple[FileState | None, None]:
        """Update file."""
        if not ctx.config or not ctx.state:
            return None, None

        file_path = Path(ctx.state.path)

        # Update the file content
        file_path.write_text(ctx.config.content)

        # Return updated state
        return FileState(
            id=ctx.state.id,
            path=ctx.state.path,
            content=ctx.config.content,
            mode=ctx.config.mode,
            size=len(ctx.config.content),
        ), None


    async def _delete_apply(self, ctx: ResourceContext) -> None:
        """Delete file."""
        if not ctx.state:
            return

        file_path = Path(ctx.state.path)

        # Delete file if it exists
        if file_path.exists():
            file_path.unlink()

Step 9: Test with Terraform

Create a Terraform configuration file test.tf:

Terraform
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
terraform {
  required_providers {
    local = {
      source = "mycompany/local"
    }
  }
}

resource "local_file" "greeting" {
  path    = "hello.txt"
  content = "Hello from Terraform!"
  mode    = "644"
}

output "file_size" {
  value = local_file.greeting.size
}

Run it:

Bash
1
2
3
terraform init
terraform plan
terraform apply

You should see:

  • terraform plan shows the file will be created
  • terraform apply creates hello.txt
  • The output shows the file size

Try modifying the content and running terraform apply again to see updates!

What You've Learned

Congratulations! You've built your first pyvider resource. You now understand:

✅ Resource Lifecycle - Create, read, update, delete operations ✅ Schema Definition - Defining what users configure ✅ Runtime Types - Separating config from state ✅ Validation - Preventing bad configurations ✅ Testing - Using Terraform to test your resource

Next Steps

Now that you understand the basics, explore:

Troubleshooting

Q: My resource isn't being registered

Make sure you're calling register_resource() as a decorator and importing the module.

Q: Validation errors aren't showing

Check that _validate_config() is async and returns a list of strings.

Q: State isn't being tracked

Ensure you're returning FileState objects from _create_apply() and _update_apply().

For more help, see Troubleshooting Guide.