Authoring Templates

Documentation Index

Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Three template flavors

​

Anatomy of a Terraform template

​

Shape A: provisioner-driven (shell pipeline wrapped in HCL)

terraform {
  required_providers {
    tensor9 = { source = "tf-providers.prod-1.tensor9.com/tensor9/tensor9", version = "~> 2.41" }
    null    = { source = "hashicorp/null", version = "~> 3.2" }
  }
}

provider "tensor9" {
  mode = "ops"
}

variable "MOUNT_PREFIX" {
  type        = string
  default     = "/"
  description = "Filesystem path prefix; only mounts under this prefix are reported"
  validation {
    condition     = startswith(var.MOUNT_PREFIX, "/")
    error_message = "MOUNT_PREFIX must be an absolute path beginning with /"
  }
}

resource "tensor9_command" "this" {
  name        = "disk-usage"
  display     = "Disk usage"
  description = "Show human-readable disk usage (df -h) for mounts under MOUNT_PREFIX. Read-only."
  icon        = "disk"
  data_access = ["Storage"]
}

resource "null_resource" "df" {
  triggers = {
    mount_prefix = var.MOUNT_PREFIX
  }
  provisioner "local-exec" {
    command = "df -h | awk 'NR==1 || $6 ~ \"^${var.MOUNT_PREFIX}\"'"
  }
}

​

Shape B: data-source-driven (cloud API queries)

terraform {
  required_providers {
    tensor9 = { source = "tf-providers.prod-1.tensor9.com/tensor9/tensor9", version = "~> 2.41" }
    aws     = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

provider "tensor9" {
  mode = "ops"
}

variable "REGION" {
  type        = string
  default     = "us-east-1"
  description = "AWS region for the provider"
}

provider "aws" {
  region = var.REGION
}

resource "tensor9_command" "this" {
  name        = "list-public-s3-buckets"
  display     = "List public S3 buckets"
  description = "Diagnostic: list S3 buckets whose ACL grants READ or WRITE to AllUsers / AuthenticatedUsers. Read-only."
  icon        = "search"
  data_access = ["Infrastructure"]
}

data "aws_s3_buckets" "all" {}
data "aws_s3_bucket_acl" "by_bucket" {
  for_each = toset(data.aws_s3_buckets.all.buckets[*].name)
  bucket   = each.value
}

locals {
  public_buckets = [/* ... filtering logic ... */]
}

output "public_buckets" {
  value = local.public_buckets
}

​

Three things doing real work in either shape

​

Source of truth: HCL bytes are canonical

​

Outputs are surfaced verbatim; sensitive = true does not redact

​

Variables

tensor9 ops command create \
  --appName my-app \
  --customerName acme-corp \
  --template linux-disk-usage \
  --vars MOUNT_PREFIX=/var/lib/myapp \
  --commandName check-myapp-disk \
  --reason "investigating disk pressure"

​

Data access tags

​

Side-effect tags

resource "tensor9_command" "this" {
  name         = "drain-node"
  display      = "Drain node"
  description  = "Cordon the node and evict its pods so it can be safely terminated."
  icon         = "server"
  data_access  = ["Infrastructure"]
  side_effects = ["node-drain", "pod-evictions"]
}

​

Permission tiers

​

Versioning

terraform {
  required_providers {
    tensor9    = { source = "tf-providers.prod-1.tensor9.com/tensor9/tensor9", version = "~> 2.41" }
    null       = { source = "hashicorp/null", version = "~> 3.2" }
    aws        = { source = "hashicorp/aws", version = "~> 5.0" }
    kubernetes = { source = "hashicorp/kubernetes", version = "~> 2.20" }
  }
}

​

Execution model

​

Per-execution working directory

1. Appliance creates a unique tempdir.
2. Writes the template’s HCL to main.tf in that tempdir.
3. Runs tofu init -input=false (downloads providers; consults public registry and tf-providers.prod-1.tensor9.com).
4. Runs tofu apply -auto-approve -input=false -no-color -refresh=false.
5. Runs tofu output -json.
6. Captures local-exec stdout (if any) and the JSON output (if any).
7. Deletes the tempdir.

​

Network requirements for tofu init

• registry.opentofu.org (or the equivalent Terraform registry your external provider sources resolve through), to fetch hashicorp/aws, hashicorp/null, hashicorp/kubernetes, etc.
• tf-providers.prod-1.tensor9.com, to fetch the tensor9 provider.

​

What this implies for what you can write

• Every resource block looks like a fresh Create to Terraform on every execution. There is no prior state to compute drift against. For naturally-stateful resources (aws_iam_user, aws_iam_access_key.old_disabled that depends on something imported), the apply will attempt to create from scratch and fail with EntityAlreadyExists. The right strategy depends on the resource: AWS APIs vary, and there is no single workaround. Examples that work in practice:
  • RunInstances and CreateSnapshot accept idempotency tokens.
  • kubernetes_annotations is an upsert against an existing object.
  • aws s3 cp honors conditional headers (--if-none-match).
  • CreateUser requires a check-then-create via null_resource + local-exec shelling out to aws iam get-user first.
  • cmdlib’s aws/snapshot-ebs-volume.tensor9.tf and aws/rotate-iam-access-key.tensor9.tf are good reference patterns. The general rule: assume your apply runs against an empty state, and design the body to either upsert correctly or to no-op cleanly when the resource already exists.
• -refresh=false is set deliberately. The appliance does not call provider read APIs to verify state before computing the diff (there’s no prior state to refresh). Three consequences worth designing for:
  1. No drift detection. A kubernetes_annotations (or similar) resource just calls the upsert; it does not first check whether the upstream object already has the value. This is the right model for at-least-once upserts; it does not give you compare-and-set semantics.
  2. No transactional rollback across resources. If a null_resource runs a multi-step local-exec that succeeds halfway and then fails, the next execution starts from an empty state again. Partial-mutation rollback is the template author’s responsibility: design idempotent steps or use a single all-or-nothing local-exec.
  3. data blocks still run every invocation. They’re the only refresh-equivalent and they hit the cloud API on every command, not just when something changes. Bill accordingly.
  The general rule: every mutating template is at-least-once. Assume you’ll re-execute on partial failure and design the body to either upsert correctly or to no-op cleanly when the resource already exists.
• Your customer at review time sees the template’s HCL, not a tofu plan. Plans depend on data-source results which can only run after the appliance is authorized to do so. Customers are reviewing “what this template will do” plus the declared data_access and side_effects, not a fully-resolved diff. For a for_each over a data source, the cardinality is not visible at review time; bound the blast radius via data_access and side_effects declarations rather than relying on review to catch fan-out.
• timestamp() in triggers is not necessary. Because state is empty every run, null_resource will Create on every execution regardless of triggers. The cargo-cult run_at = timestamp() pattern adds nothing here. Use timestamp() only when you need a timestamp value at execution time (e.g. kubectl.kubernetes.io/restartedAt = timestamp() for K8s rolling restart annotations, or timeadd(timestamp(), "-${N}h") for date-window filtering).

​

Appliance runtime environment

​

Direct-create alternative

tensor9 ops template create \
  --appName my-app \
  --file ./my-template.json

{
  "name": "disk-usage",
  "displayName": "Disk usage",
  "description": "Show human-readable disk usage (df -h). Read-only.",
  "spec": {
    "kind": "Tf",
    "hcl": "terraform {\n  required_providers { ... }\n}\n\n..."
  },
  "dataAccess": ["Storage"],
  "sideEffects": [],
  "variables": [
    {
      "name": "MOUNT_PREFIX",
      "default": "/",
      "description": "Filesystem path prefix",
      "pattern": "^/.*"
    }
  ]
}

​

HCL ↔ JSON field name mapping

​

Listing and retrieving templates

# List all templates this app exposes
tensor9 ops template list --appName my-app

# Inspect a single template in full
tensor9 ops template retrieve --appName my-app --templateId <id>

​

Related

• Git template sources: how a folder of templates becomes a re-syncable source.
• Submitting and tracking ops commands: how customers see a command and release output.
• Pre-approvals: how to let customers approve a template once and let you run it many times.