Terraform Provider

The Shoehorn Terraform provider lets you manage Shoehorn resources as code. Use it for catalog entities, teams, tenant settings, integrations, Kubernetes agents, governance actions, Forge resources, and marketplace installations.

The provider is API-only. Deploy Shoehorn itself with Helm, then manage the platform state with Terraform.

Install the Provider

Use the Terraform Registry provider source:

terraform {
  required_providers {
    shoehorn = {
      source  = "shoehorn-dev/shoehorn"
      version = "~> 0.1"
    }
  }
}

Configure the Provider

provider "shoehorn" {
  host    = "https://shoehorn.example.com"
  api_key = var.shoehorn_api_key
  timeout = 30
}

You can also provide credentials through environment variables:

SHOEHORN_HOST
SHOEHORN_API_KEY

Use a service API key with the scopes required for the resources you manage.

Quick Example

resource "shoehorn_team" "platform" {
  name        = "Platform Engineering"
  slug        = "platform-team"
  description = "Owns shared developer infrastructure"
}

resource "shoehorn_entity" "portal" {
  service_id       = "developer-portal"
  name             = "Developer Portal"
  type             = "service"
  entity_lifecycle = "production"
  owner            = shoehorn_team.platform.slug
  description      = "Internal developer portal"
  tags             = ["platform", "internal"]
}

resource "shoehorn_k8s_agent" "prod" {
  cluster_id = "prod-us-east-1"
  name       = "Production US East 1"
}

Supported Resources

Resource	Purpose
`shoehorn_entity`	Catalog entities
`shoehorn_team`	Teams and metadata
`shoehorn_feature_flag`	Tenant feature flags
`shoehorn_tenant_settings`	Branding, hidden pages, Forge settings
`shoehorn_integration`	External integrations
`shoehorn_api_key`	Service API keys
`shoehorn_user_role`	User RBAC assignments
`shoehorn_group_role_mapping`	IdP group to role mappings
`shoehorn_k8s_agent`	Cluster registration and agent tokens
`shoehorn_platform_policy`	Configure seeded platform policies
`shoehorn_governance_action`	Governance action items
`shoehorn_forge_mold`	Forge mold definitions
`shoehorn_forge_approval_policy`	Forge approval chains
`shoehorn_marketplace_installation`	Marketplace addon lifecycle

Supported Data Sources

Data Source	Purpose
`shoehorn_entities`	List and filter entities
`shoehorn_teams`	List teams
`shoehorn_feature_flags`	List feature flags
`shoehorn_integrations`	List integrations
`shoehorn_api_keys`	List API keys without returning secrets
`shoehorn_k8s_agents`	List registered K8s agents
`shoehorn_platform_policies`	List platform policies
`shoehorn_users`	List users
`shoehorn_groups`	List groups and group-role assignments
`shoehorn_governance_actions`	List governance actions with filters
`shoehorn_forge_molds`	List Forge molds
`shoehorn_marketplace_items`	List marketplace catalog items
`shoehorn_gitops_resources`	Read GitOps resources discovered from clusters

Common Patterns

Manage Teams and Ownership

resource "shoehorn_team" "payments" {
  name        = "Payments"
  slug        = "payments-team"
  description = "Payments and billing team"
}

resource "shoehorn_entity" "payment_api" {
  service_id       = "payment-api"
  name             = "Payment API"
  type             = "service"
  entity_lifecycle = "production"
  owner            = shoehorn_team.payments.slug
}

Manage Tenant Branding

resource "shoehorn_tenant_settings" "main" {
  platform_name   = "Acme Portal"
  highlight_color = "#0f766e"
  hidden_pages    = ["insights"]

  forge = {
    allowed_orgs = ["acme-platform", "acme-services"]
    default_org  = "acme-platform"
  }
}

Read GitOps Resources

data "shoehorn_gitops_resources" "argocd" {
  tool = "argocd"
}

API Key Scope Guidance

The provider uses the same API and RBAC model as the UI and CLI. In practice:

Use read-only scopes for data sources.
Add write scopes for any managed resources.
Use admin-capable keys for tenant settings, policies, API keys, or organization-wide automation.

If you are unsure, create a dedicated service API key for Terraform and start with the narrowest set of scopes needed for your plan.

Notes

shoehorn_entity uses entity_lifecycle instead of lifecycle because lifecycle is reserved by Terraform.
API keys and K8s agent tokens are only returned on creation. Treat Terraform state as sensitive.
shoehorn_platform_policy manages configuration for existing platform policies. The provider does not create or delete the default policy set.
GitOps resources are read-only today. They are discovered from connected clusters.