## Installation

If you don't have Terraform installed, follow the [official installation guide](https://learn.hashicorp.com/tutorials/terraform/install-cli) for your operating system.

### Configure Terraform to Use the Rabata Provider

Create a new directory for your Terraform configuration and create a file named `main.tf` with the following content:

```hcl
terraform {
  required_providers {
    rabata = {
      source  = "rabataio/rabata"
      version = "~> 1.0" # Use the latest version available
    }
  }
}

provider "rabata" {
  region     = "us-east-1" # Replace with your preferred region
  access_key = "your-access-key"
  secret_key = "your-secret-key"
}
```

## Authentication

The Rabata provider offers multiple ways to provide credentials for authentication:

### Method 1: Provider Configuration

You can directly specify your credentials in the provider block as shown above. However, it's generally not recommended to hardcode credentials in your Terraform files.

### Method 2: Environment Variables

You can use environment variables to provide your Rabata credentials:

```bash
export RABATA_ACCESS_KEY="your-access-key"
export RABATA_SECRET_KEY="your-secret-key"
export RABATA_REGION="us-east-1"
```

Then, your provider configuration can be simplified:

```hcl
provider "rabata" {}
```

### Method 3: Shared Credentials File

You can also use a shared credentials file, similar to AWS CLI:

```hcl
provider "rabata" {
  shared_credentials_file = "~/.aws/credentials"
  profile                 = "rabata"
}
```

## Creating Your First Resources

### Create a Bucket

To create a bucket in Rabata.io, add the following to your `main.tf` file:

```hcl
resource "rabata_s3_bucket" "example_bucket" {
  bucket = "my-example-bucket"
  acl    = "private"
}
```

### Upload an Object to the Bucket

To upload an object to your bucket:

```hcl
resource "rabata_s3_bucket_object" "example_object" {
  bucket = rabata_s3_bucket.example_bucket.bucket
  key    = "example-object.txt"
  source = "path/to/local/file.txt"
  etag   = filemd5("path/to/local/file.txt")
}
```

## Initialize and Apply

After configuring your Terraform files, initialize the working directory:

```bash
terraform init
```

This will download the Rabata provider plugin. Then, apply your configuration:

```bash
terraform plan
terraform apply
```

Review the planned changes and type `yes` to apply them.

## Advanced Configuration

### Custom Endpoints

If you need to use a custom endpoint for the S3 service:

```hcl
provider "rabata" {
  region     = "us-east-1"
  access_key = "your-access-key"
  secret_key = "your-secret-key"

  endpoints {
    s3 = "https://s3.us-east-1.rabata.io"
  }
}
```

### Path-Style Access

To force path-style addressing (`https://s3.us-east-1.rabata.io/BUCKET/KEY`) instead of virtual-hosted bucket addressing:

```hcl
provider "rabata" {
  region             = "us-east-1"
  access_key         = "your-access-key"
  secret_key         = "your-secret-key"
  s3_force_path_style = true
}
```

## Complete Example

Here's a complete example that creates a bucket, sets up a bucket policy, and uploads an object:

```hcl
terraform {
  required_providers {
    rabata = {
      source  = "rabataio/rabata"
      version = "~> 1.0"
    }
  }
}

provider "rabata" {
  region     = "us-east-1"
  access_key = "your-access-key"
  secret_key = "your-secret-key"
  endpoints {
    s3 = "https://s3.us-east-1.rabata.io"
  }
}

resource "rabata_s3_bucket" "storage_bucket" {
  bucket = "my-storage-bucket"
  acl    = "private"

  tags = {
    Environment = "Production"
    Project     = "Data Storage"
  }
}

resource "rabata_s3_bucket_object" "readme" {
  bucket  = rabata_s3_bucket.storage_bucket.bucket
  key     = "README.md"
  content = "# This is a README file for my bucket"
  content_type = "text/markdown"
}

output "bucket_domain_name" {
  value = rabata_s3_bucket.storage_bucket.bucket_domain_name
}
```

## Next Steps

Now that you've set up your first resources with the Rabata Terraform provider, you can:

- Learn more about [Bucket Management](/docs/buckets/)
- Understand [Access Control](/docs/access-keys/) for your objects
- Explore the [full Rabata Terraform provider documentation](https://registry.terraform.io/providers/rabataio/rabata/latest/docs)

## Troubleshooting

### Common Issues

#### Provider Installation Fails

If you encounter issues during `terraform init`, ensure you have the correct provider source:

```hcl
terraform {
  required_providers {
    rabata = {
      source = "rabataio/rabata"
    }
  }
}
```

#### Authentication Errors

If you receive authentication errors, verify that:
- Your access key and secret key are correct
- You've specified the correct region
- Your credentials have the necessary permissions

#### S3 Endpoint Issues

If you have connectivity issues, try explicitly setting the S3 endpoint:

```hcl
provider "rabata" {
  endpoints {
    s3 = "https://s3.us-east-1.rabata.io"
  }
}
```

## Need Help?

If you need assistance, contact [Rabata.io Support](mailto:support@rabata.io).

<div class="docs-article__actions">
  <a href="/docs/quickstart/aws-cli/" class="btn btn--secondary">AWS Cli Quickstart</a>
  <a href="/docs/quickstart/python/" class="btn btn--secondary">Python Quickstart</a>
</div>