docs: improve documentation with guides, tutorials and examples

README.md

@@ -1,12 +1,55 @@
-# Terraform Provider Tsuru [![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/tsuru/terraform-provider-tsuru?label=release)](https://github.com/tsuru/terraform-provider-tsuru/releases) [![license](https://img.shields.io/github/license/tsuru/terraform-provider-tsuru.svg)]()
+# Terraform Provider Tsuru - Improved Documentation
 
-- Usage
-  - [Provider Documentation](https://registry.terraform.io/providers/tsuru/tsuru/latest/docs)
-  - [Tsuru Documentation](https://docs.tsuru.io/)
+Better docs for the terraform-provider-tsuru with practical examples, migration guides, detailed resource documentation, and step-by-step tutorials.
 
-The tsuru provider for Terraform is a plugin that enables lifecycle management of Tsuru resources. This provider is under early development by Tsuru Team.
+## Quick Links
 
-## Requirements
+**New to Terraform + Tsuru?** Start with [Getting Started](tutorials/01-getting-started.md)
+
+**Migrating from manual management?** Read the [Migration Guide](guides/migration-guide.md)
+
+**Need a reference?** Check the [Resource Documentation](resources/)
+
+## Tutorials
+
+| Tutorial | What you'll learn | Time |
+|----------|-------------------|------|
+| [Getting Started](tutorials/01-getting-started.md) | Initial setup and first app | 15 min |
+| [Managing Apps](tutorials/02-managing-apps.md) | Environment variables, CNAMEs, autoscaling | 20 min |
+| [Jobs](tutorials/03-jobs.md) | Scheduled and manual jobs | 15 min |
+| [Infrastructure](tutorials/04-infrastructure.md) | Clusters, pools, and plans | 25 min |
+
+## Examples
+
+Ready-to-use examples for common scenarios:
+
+- [Complete Web App](examples/complete-web-app/) - App with env vars, CNAME, and autoscaling
+- [Scheduled Job](examples/scheduled-job/) - Job with cron schedule
+- [Cluster Setup](examples/cluster-setup/) - Cluster and pool configuration
+
+## Resource Documentation
+
+Detailed docs for key resources:
+
+- [tsuru_app](resources/app.md) - Application management
+- [tsuru_cluster](resources/cluster.md) - Kubernetes cluster configuration
+
+## Migration Guide
+
+Moving from manual Tsuru management to Terraform? The [Migration Guide](guides/migration-guide.md) covers:
+
+- Migration strategies (big bang vs gradual)
+- Using `terraform import`
+- Import order and validation
+- Rollback procedures
+
+## Contributing
+
+Found an issue or want to add more examples? Contributions welcome.
+
+## Additional Resources
+
+- [Official Provider Docs](https://registry.terraform.io/providers/tsuru/tsuru/latest/docs)
+- [Tsuru Documentation](https://docs.tsuru.io/)
+- [Provider Repository](https://github.com/tsuru/terraform-provider-tsuru)
 
--	[Terraform](https://www.terraform.io/downloads.html) 1.4.4
--	[Go](https://golang.org/doc/install) 1.21.0 (to build the provider plugin)

examples/cluster-setup/README.md

@@ -0,0 +1,19 @@
+# Cluster Setup Example
+
+This example shows how to add a Kubernetes cluster to Tsuru and associate it with a pool.
+
+## Usage
+
+```bash
+terraform init
+terraform apply
+```
+
+After applying, you'll have a new cluster `my-k8s-cluster` connected to the pool `my-pool`.
+
+## Resources used
+
+- `tsuru_cluster` - Kubernetes cluster
+- `tsuru_pool` - Resource pool
+- `tsuru_cluster_pool` - Cluster-pool association
+

examples/cluster-setup/main.tf

@@ -0,0 +1,22 @@
+resource "tsuru_cluster" "k8s_cluster" {
+  name        = "my-k8s-cluster"
+  provisioner = "kubernetes"
+  crio        = true
+
+  kube_config {
+    cluster {
+      server = "https://my-k8s-cluster.example.com"
+    }
+  }
+}
+
+resource "tsuru_pool" "my_pool" {
+  name        = "my-pool"
+  provisioner = "kubernetes"
+}
+
+resource "tsuru_cluster_pool" "cluster_pool_attachment" {
+  cluster = tsuru_cluster.k8s_cluster.name
+  pool    = tsuru_pool.my_pool.name
+}
+

examples/complete-web-app/README.md

@@ -0,0 +1,24 @@
+# Complete Web Application Example
+
+This example shows how to set up a production-ready web application on Tsuru with environment variables, custom domain, and autoscaling.
+
+## What's included
+
+This configuration creates an app with environment variables for database and cache connections, adds a custom CNAME, and configures autoscaling based on CPU usage and business hours.
+
+## Usage
+
+```bash
+terraform init
+terraform apply
+```
+
+After applying, your app will be available at `www.complete-web-app.com` with automatic scaling between 2-5 units based on CPU load, maintaining at least 3 units during weekday business hours (8am-8pm).
+
+## Resources used
+
+- `tsuru_app` - Base application
+- `tsuru_app_env` - Environment variables
+- `tsuru_app_cname` - Custom domain
+- `tsuru_app_autoscale` - Scaling configuration
+

examples/complete-web-app/main.tf

@@ -0,0 +1,57 @@
+resource "tsuru_app" "web_app" {
+  name        = "complete-web-app"
+  description = "Complete web application example"
+  plan        = "c0.1m0.2"
+  pool        = "staging"
+  platform    = "python"
+  team_owner  = "admin"
+  tags        = ["terraform", "example", "web"]
+
+  metadata {
+    labels = {
+      "app"       = "web-app"
+      "component" = "frontend"
+    }
+    annotations = {
+      "owner" = "team-alpha"
+    }
+  }
+
+  restart_on_update = true
+}
+
+resource "tsuru_app_env" "app_env" {
+  app = tsuru_app.web_app.name
+
+  environment_variables = {
+    "DATABASE_URL" = "postgres://user:password@host:port/dbname"
+    "CACHE_URL"    = "redis://host:port"
+  }
+
+  no_restart = false
+}
+
+resource "tsuru_app_cname" "app_cname" {
+  app   = tsuru_app.web_app.name
+  cname = "www.complete-web-app.com"
+}
+
+resource "tsuru_app_autoscale" "app_autoscale" {
+  app = tsuru_app.web_app.name
+
+  min_units = 2
+  max_units = 5
+
+  cpu {
+    target = "80%"
+  }
+
+  schedules = [
+    {
+      start        = "0 8 * * 1-5"
+      end          = "0 20 * * 1-5"
+      min_replicas = 3
+    }
+  ]
+}
+

examples/scheduled-job/README.md

@@ -0,0 +1,23 @@
+# Scheduled Job Example
+
+This example demonstrates how to create and deploy a scheduled job that runs every hour.
+
+## Usage
+
+```bash
+terraform init
+terraform apply
+```
+
+The job will run automatically every hour. You can check its execution logs with:
+
+```bash
+tsuru job info -j my-scheduled-job
+tsuru job log -j my-scheduled-job
+```
+
+## Resources used
+
+- `tsuru_job` - Job definition with schedule
+- `tsuru_job_deploy` - Job deployment
+

examples/scheduled-job/main.tf

@@ -0,0 +1,19 @@
+resource "tsuru_job" "scheduled_job" {
+  name        = "my-scheduled-job"
+  description = "Scheduled job example"
+  pool        = "staging"
+  team_owner  = "admin"
+
+  container {
+    image   = "ubuntu:latest"
+    command = ["echo", "Hello from Tsuru Job!"]
+  }
+
+  schedule = "@every 1h"
+}
+
+resource "tsuru_job_deploy" "job_deploy" {
+  job   = tsuru_job.scheduled_job.name
+  image = "ubuntu:latest"
+}
+

guides/migration-guide.md

@@ -0,0 +1,102 @@
+# Migration Guide
+
+Moving from manual Tsuru management to Terraform gives you version control, automation, and reproducibility for your infrastructure.
+
+## Before you start
+
+Take inventory of your current Tsuru resources. List everything you have:
+
+```bash
+tsuru app list
+tsuru service instance list
+tsuru pool list
+tsuru cluster list
+tsuru job list
+```
+
+Save this output - you'll need it to write your Terraform configs.
+
+## Migration strategies
+
+**Big Bang**
+Import everything at once. Faster but riskier. Best for small environments or non-production.
+
+**Gradual**
+Import resources in phases. Safer for production. Start with one team or a few non-critical apps.
+
+## How terraform import works
+
+Terraform import brings existing resources under Terraform management without recreating them. You need to:
+
+1. Write the resource definition in your `.tf` file
+2. Run `terraform import` to link it to the real resource
+3. Run `terraform plan` to verify everything matches
+
+### Example: Importing an app
+
+First, write the resource definition:
+
+```terraform
+resource "tsuru_app" "my_app" {
+  name        = "my-app"
+  description = "Imported app"
+  plan        = "c0.1m0.2"
+  pool        = "staging"
+  platform    = "python"
+  team_owner  = "admin"
+}
+```
+
+Then import it:
+
+```bash
+terraform import tsuru_app.my_app "my-app"
+```
+
+Check if it worked:
+
+```bash
+terraform plan
+```
+
+If you see changes, your definition doesn't match reality. Adjust it until `terraform plan` shows no changes.
+
+## Import order
+
+Follow this sequence to avoid dependency issues:
+
+1. Clusters and pools
+2. Apps and their resources (env vars, CNAMEs, autoscale)
+3. Services and bindings
+4. Jobs
+
+## Validation
+
+After each import:
+
+- Run `terraform plan` - should show zero changes
+- Test the app/service to make sure it still works
+- Commit your code
+
+## Rollback
+
+If something breaks:
+
+- Revert to the previous git commit
+- Run `terraform apply` to restore the old state
+- Or remove the resource from Terraform with `terraform state rm`
+
+## Checklist
+
+- [ ] Inventory all Tsuru resources
+- [ ] Choose migration strategy
+- [ ] Set up Terraform with tsuru provider
+- [ ] Write resource definitions
+- [ ] Import clusters and pools
+- [ ] Import apps and related resources
+- [ ] Import services
+- [ ] Import jobs
+- [ ] Validate with `terraform plan` after each step
+- [ ] Test apps functionality
+- [ ] Backup `terraform.tfstate`
+