Cloud Provider Integration

Shoehorn discovers cloud resources (servers, databases, Kubernetes clusters, object storage) and catalogs them as entities. Currently supports UpCloud, with AWS/Azure/GCP planned.

Overview

Cloud resource discovery runs in the crawler service on a configurable sync interval (default: 15 minutes). Resources are automatically cataloged as entities with rich metadata, pricing, and console links.

Cloud API → Provider → Transformer → Database + Search Index
                                         ↓
                              Entity detail page with specialized cards

Supported Providers

UpCloud

Resource Type	Entity Type	Console Link
Server	`upcloud-server`	hub.upcloud.com/server/{uuid}
Managed Database	`upcloud-db`	hub.upcloud.com/database/{uuid}
Managed Kubernetes	`upcloud-k8s`	hub.upcloud.com/kubernetes/{uuid}
Managed Object Storage	`upcloud-objectstorage`	hub.upcloud.com/object-storage/{uuid}

Configuration

# Enable UpCloud discovery
CLOUD_PROVIDER_UPCLOUD_ENABLED=true

# API token (get from https://hub.upcloud.com/account/api-keys)
UPCLOUD_TOKEN=ucat_your_token_here

# Sync interval (default: 15m, minimum: 1m)
CLOUD_PROVIDER_SYNC_INTERVAL=15m

# Per-provider override (optional)
UPCLOUD_SYNC_INTERVAL=5m

Helm chart (values.yaml):

cloudProviders:
  syncInterval: "15m"
  upcloud:
    enabled: true
    syncInterval: ""   # empty = use global

Token is stored in the integration-credentials secret (key: upcloud_token).

UpCloud Labels

UpCloud resource labels control how entities appear in Shoehorn. Add labels in the UpCloud Hub or via the UpCloud API.

Label → Card Mapping

UpCloud Label	Where it appears	Example Value
`team`	Contacts Card (owner)	`platform`
`owner`	Contacts Card (owner)	`infra-team`
`description`	About Card	`Production API database`
`tags`	About Card (comma-separated)	`critical,tier-1,eu-west`
`links`	Links Card (`name=url` pairs)	`Grafana=https://grafana.io/d/xyz`
`slackChannel`	Slack Card	`platform-alerts`

Example

Apply these labels to an UpCloud database in the UpCloud Hub:

team=platform
description=Production PostgreSQL 16 cluster for the API
tags=critical,tier-1,eu-west
links=Grafana=https://grafana.io/d/db-dashboard,Runbook=https://wiki.internal/db-runbook
slackChannel=db-alerts

Result in Shoehorn:

Contacts Card: Shows “platform” as owner
About Card: Shows description + tags
Links Card: Shows Grafana and Runbook links alongside the auto-generated UpCloud Console link
Slack Card: Shows #db-alerts channel link

Labels as Metadata Badges

Any label NOT in the list above appears as a metadata badge on the entity detail page. For example:

env=production
region=eu-west
cost-center=engineering

These show as key-value badges in the Cloud Summary card.

Case Sensitivity

slackChannel and slackchannel are both supported (UpCloud labels may vary in casing)
All other labels are case-sensitive

Pricing

Monthly pricing is automatically calculated from the UpCloud pricing API.

Resource	Formula
Server	Plan price per hour × 730
Database	Plan price per hour × 730
Kubernetes	Control plane price + sum(node count × node plan price)
Object Storage	Standard tier price

Prices are in EUR. Displayed as monthly cost on entity detail cards.

Search

Cloud entities are fully searchable. Users can search by:

Entity name, description
IP address, hostname
Zone, plan, engine
Label values (e.g., search “production” finds entities with env=production label)
UpCloud UUID

Entity URLs

Cloud entity IDs use colons: upcloud:server:abc123. These work in browser URLs without encoding:

/catalog/entities/upcloud:server:abc123

Adding Support for AWS / Azure / GCP

AWS, Azure, and GCP integrations are on the roadmap. Track progress or open a request at github.com/shoehorn-dev/shoehorn/issues.