Docs

Terraform

Two different things people mean by “Terraform and ShellHub”, and they are worth separating.

Reaching a device from a provisioner

Terraform’s remote-exec and file provisioners connect over SSH, and ShellHub’s SSHID is an ordinary SSH username:

connection {
  type        = "ssh"
  host        = "cloud.shellhub.io"
  user        = "[email protected]"
  private_key = file("~/.ssh/id_ed25519")
}

provisioner "remote-exec" {
  inline = [
    "systemctl restart myservice",
  ]
}

The host is always the ShellHub server; the device is identified by user.

The key must already be enrolled. If it is not, the connection parks waiting for a browser approval and Terraform hangs until it times out. Enroll it ahead of time through the API key’s SSH access.

Managing ShellHub itself

ShellHub’s HTTP API is what you would target to manage devices, tags or access policies as code. An API key cannot create a namespace or manage API keys, so those stay a person’s job in the console. See What a key cannot do.

There is no official ShellHub Terraform provider. The options are the generic HTTP provider for simple cases, or null_resource with a local-exec calling the API:

resource "null_resource" "shellhub_tag" {
  provisioner "local-exec" {
    command = <<-EOT
      curl -sf -X POST https://cloud.shellhub.io/api/... \
        -H "X-API-Key: ${var.shellhub_api_key}" \
        -H "Content-Type: application/json" \
        -d '{ ... }'
    EOT
  }
}

Be honest with yourself about that pattern: it has no real state tracking, no drift detection and no meaningful destroy. For anything beyond a couple of resources, a script against the API is clearer than pretending it is declarative.

See API Authentication and the the specification for the endpoints.

Enrolling devices Terraform creates

If Terraform is creating machines that should appear in ShellHub, put the agent in at creation with a provisioning key, through cloud-init or user data:

user_data = <<-EOT
  #!/bin/sh
  curl -sSf https://cloud.shellhub.io/install.sh | \
    PROVISIONING_KEY=${var.shellhub_provisioning_key} \
    sh
EOT

A provisioning key in automatic mode means instances arrive accepted and tagged, with nobody watching a console. That is the pattern worth adopting — it is the one that scales.

Where to go next

esc