From 897c9ae3d4f35ea8db866beac0530db8b5b1b0bd Mon Sep 17 00:00:00 2001 From: Graham McIntire Date: Mon, 26 Jan 2026 11:26:04 -0600 Subject: [PATCH] add documentation --- README.md | 170 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 47 +++++++++++ docs/resources/device.md | 63 +++++++++++++++ docs/resources/site.md | 43 ++++++++++ 4 files changed, 323 insertions(+) create mode 100644 README.md create mode 100644 docs/index.md create mode 100644 docs/resources/device.md create mode 100644 docs/resources/site.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ce1efd3 --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# TowerOps Terraform Provider + +Terraform provider for managing [TowerOps](https://towerops.io) resources. + +## Requirements + +- [Terraform](https://www.terraform.io/downloads.html) >= 1.0 +- [Go](https://golang.org/doc/install) >= 1.21 (to build the provider) + +## Installation + +```hcl +terraform { + required_providers { + towerops = { + source = "towerops/towerops" + version = "~> 0.1" + } + } +} +``` + +## Authentication + +The provider requires an API token for authentication. Generate a token from the TowerOps web application under Settings → API Tokens. + +```hcl +provider "towerops" { + token = var.towerops_api_token +} +``` + +You can also set the token via environment variable: + +```bash +export TOWEROPS_TOKEN="your-api-token" +``` + +## Resources + +### towerops_site + +Manages a TowerOps site. Sites represent physical locations that contain devices. + +```hcl +resource "towerops_site" "example" { + name = "Main Office" + location = "New York, NY" + snmp_community = "public" +} +``` + +#### Arguments + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `name` | string | Yes | Site name (2-200 characters) | +| `location` | string | No | Physical location or address | +| `snmp_community` | string | No | Default SNMP community string for devices | + +#### Attributes + +| Name | Description | +|------|-------------| +| `id` | Unique identifier (UUID) | +| `inserted_at` | Creation timestamp | + +#### Import + +```bash +terraform import towerops_site.example 550e8400-e29b-41d4-a716-446655440000 +``` + +### towerops_device + +Manages a TowerOps device. Devices represent network equipment at a site. + +```hcl +resource "towerops_device" "router" { + site_id = towerops_site.example.id + name = "Core Router" + ip_address = "192.168.1.1" + + monitoring_enabled = true + snmp_enabled = true + snmp_version = "2c" + snmp_port = 161 +} +``` + +#### Arguments + +| Name | Type | Required | Default | Description | +|------|------|----------|---------|-------------| +| `site_id` | string | Yes | - | ID of the parent site (forces replacement if changed) | +| `name` | string | Yes | - | Device name | +| `ip_address` | string | Yes | - | Device IP address | +| `description` | string | No | - | Device description | +| `monitoring_enabled` | bool | No | `true` | Enable monitoring | +| `snmp_enabled` | bool | No | `true` | Enable SNMP polling | +| `snmp_version` | string | No | `"2c"` | SNMP version (1, 2c, or 3) | +| `snmp_port` | number | No | `161` | SNMP port | + +#### Attributes + +| Name | Description | +|------|-------------| +| `id` | Unique identifier (UUID) | +| `inserted_at` | Creation timestamp | + +#### Import + +```bash +terraform import towerops_device.router 7c9e6679-7425-40de-944b-e07fc1f90ae7 +``` + +## Example + +```hcl +terraform { + required_providers { + towerops = { + source = "towerops/towerops" + version = "~> 0.1" + } + } +} + +variable "towerops_api_token" { + type = string + sensitive = true +} + +provider "towerops" { + token = var.towerops_api_token +} + +resource "towerops_site" "datacenter" { + name = "Primary Datacenter" + location = "Chicago, IL" + snmp_community = "monitoring" +} + +resource "towerops_device" "core_switch" { + site_id = towerops_site.datacenter.id + name = "Core Switch" + ip_address = "10.0.0.1" + description = "Main distribution switch" + + snmp_enabled = true + snmp_version = "2c" +} + +resource "towerops_device" "edge_router" { + site_id = towerops_site.datacenter.id + name = "Edge Router" + ip_address = "10.0.0.2" + + snmp_enabled = true + snmp_version = "3" +} + +output "site_id" { + value = towerops_site.datacenter.id +} +``` + +## License + +MPL-2.0 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7b6541c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,47 @@ +--- +page_title: "TowerOps Provider" +description: |- + The TowerOps provider allows you to manage TowerOps resources such as sites and devices. +--- + +# TowerOps Provider + +The TowerOps provider allows you to manage [TowerOps](https://towerops.io) resources via Terraform. + +## Authentication + +The provider requires an API token for authentication. Generate a token from the TowerOps web application under Settings → API Tokens. The token determines which organization's resources are accessible. + +## Example Usage + +```terraform +terraform { + required_providers { + towerops = { + source = "towerops/towerops" + version = "~> 0.1" + } + } +} + +provider "towerops" { + token = var.towerops_api_token +} + +resource "towerops_site" "example" { + name = "Main Office" + location = "New York, NY" +} + +resource "towerops_device" "router" { + site_id = towerops_site.example.id + name = "Core Router" + ip_address = "192.168.1.1" +} +``` + +## Schema + +### Required + +- `token` (String, Sensitive) - The API token for authenticating with TowerOps. diff --git a/docs/resources/device.md b/docs/resources/device.md new file mode 100644 index 0000000..f872389 --- /dev/null +++ b/docs/resources/device.md @@ -0,0 +1,63 @@ +--- +page_title: "towerops_device Resource - TowerOps" +description: |- + Manages a TowerOps device. +--- + +# towerops_device (Resource) + +Manages a TowerOps device. Devices represent network equipment at a site. + +## Example Usage + +```terraform +resource "towerops_device" "router" { + site_id = towerops_site.example.id + name = "Core Router" + ip_address = "192.168.1.1" + + monitoring_enabled = true + snmp_enabled = true + snmp_version = "2c" + snmp_port = 161 +} +``` + +### Minimal Configuration + +```terraform +resource "towerops_device" "switch" { + site_id = towerops_site.example.id + name = "Access Switch" + ip_address = "192.168.1.2" +} +``` + +## Schema + +### Required + +- `site_id` (String) - The ID of the site this device belongs to. Changing this forces a new resource. +- `name` (String) - The name of the device. +- `ip_address` (String) - The IP address of the device. + +### Optional + +- `description` (String) - A description of the device. +- `monitoring_enabled` (Boolean) - Whether monitoring is enabled for this device. Default: `true`. +- `snmp_enabled` (Boolean) - Whether SNMP polling is enabled for this device. Default: `true`. +- `snmp_version` (String) - The SNMP version to use (`1`, `2c`, or `3`). Default: `"2c"`. +- `snmp_port` (Number) - The SNMP port to use. Default: `161`. + +### Read-Only + +- `id` (String) - The unique identifier of the device. +- `inserted_at` (String) - The timestamp when the device was created. + +## Import + +Devices can be imported using their UUID: + +```shell +terraform import towerops_device.router 7c9e6679-7425-40de-944b-e07fc1f90ae7 +``` diff --git a/docs/resources/site.md b/docs/resources/site.md new file mode 100644 index 0000000..9fb0e65 --- /dev/null +++ b/docs/resources/site.md @@ -0,0 +1,43 @@ +--- +page_title: "towerops_site Resource - TowerOps" +description: |- + Manages a TowerOps site. +--- + +# towerops_site (Resource) + +Manages a TowerOps site. Sites represent physical locations that contain devices. + +## Example Usage + +```terraform +resource "towerops_site" "example" { + name = "Main Office" + location = "New York, NY" + snmp_community = "public" +} +``` + +## Schema + +### Required + +- `name` (String) - The name of the site. Must be between 2 and 200 characters. + +### Optional + +- `location` (String) - The physical location or address of the site. +- `snmp_community` (String, Sensitive) - The default SNMP community string for devices at this site. + +### Read-Only + +- `id` (String) - The unique identifier of the site. +- `inserted_at` (String) - The timestamp when the site was created. + +## Import + +Sites can be imported using their UUID: + +```shell +terraform import towerops_site.example 550e8400-e29b-41d4-a716-446655440000 +```