Skip to content

semaphore

Metadata

Field Value
Service semaphore
Purpose Self-hosted Ansible automation UI and job runner
Criticality Tier 2
Owner Platform / Automation owner
Clusters dev, homelab, oci
Namespace semaphore
Exposure internet
Stateful yes
Backup class snapshot
RPO / RTO Daily backup target, 2 to 6 hours to restore
Last reviewed 2026-05-20

1. Service Overview

Semaphore provides a web UI and API for running Ansible automation and storing automation inventory and job state.

Summary

If it fails, automation workflows and operator job execution through this service stop.

Dependencies

Dependency Type Why it matters
MariaDB database Stores job, user, and automation state
Traefik ingress External web UI exposure
Persistent volumes storage Preserve inventory and configuration data

2. Architecture Diagram

[Operator]
  -> [Traefik]
  -> [Semaphore]
  -> [MariaDB]
  -> [PVC-backed config and inventory data]

3. Deployment Specifications

Item Value
Source path semaphore/base and semaphore/overlays/*
Deployment model Kustomize plus Fleet bundle
Namespace semaphore
Workload kind Deployment plus MariaDB workload
Chart or image version See base manifests for current image tags
Config files base/kustomization.yaml, overlays/dev, overlays/homelab, overlays/oci, fleet.yaml

Cluster mapping

Cluster Overlay path Notes
dev semaphore/overlays/dev Development deployment
homelab semaphore/overlays/homelab Main homelab target
oci semaphore/overlays/oci OCI-specific target

4. Configuration Guide

Environment variables

Variable Source Purpose Secret?
Semaphore runtime settings .semaphore.env inputs, manifests, and generated Secrets Application bootstrap, DB access, and encryption keys mixed

ConfigMaps

Resource Path Purpose
Kustomize-managed runtime config semaphore/base and semaphore/overlays/* Overlay-specific application behavior

Secrets management

  • Secret names: generated application and DB secrets in the semaphore namespace
  • Source of truth: overlay .semaphore.env files and generated manifests
  • Rotation trigger: access-key rotation, DB credential rotation, or automation incident response
  • Recovery note: restore all env inputs and generated Secrets before redeploying the overlay

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Semaphore service in the semaphore namespace Cluster workloads namespace RBAC Traefik / Semaphore
External Overlay-specific Semaphore hostname through Traefik Operators Semaphore auth Traefik

6. Operations and Observability

  • Primary health indicators: web UI responsive, MariaDB healthy, and job execution succeeds.
  • Dashboards or alerts: shared platform monitoring and pod health.
  • Log locations: Semaphore and MariaDB pod logs.
  • Known failure modes: missing encryption key, DB startup failure, broken ingress, or stale inventory PVC.

7. Backup and Recovery Notes

  • Backup method: MariaDB backup plus PVC snapshot.
  • Restore prerequisites: restored DB, restored inventory/config data, and generated Secrets.
  • Related runbook: ../runbooks/semaphore.md

8. Release and Change Notes

  • Current deployed app version: see semaphore/base image tags.
  • Current chart version: N/A.
  • Last significant change: repository documentation updated for the current dev, homelab, and oci overlays.
  • Rollback reference: previous overlay revision in Git.