resources

package
v0.1.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 19, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	GatewayPort        int32 = 8443
	DefaultMetricsPort int32 = 9090
	GatewayPortName          = "gateway"
	MetricsPortName          = "metrics"
)

Named ports used across builders. Stable across versions.

View Source 
const APIServerKeySecretKey = "api_server_key"

APIServerKeySecretKey is the key under the operator-managed gateway-tokens Secret that holds the OpenAI-compatible API server auth key.

View Source 
const InitialDirsKey = "__hermes_initial_dirs__"

InitialDirsKey is the well-known data key holding the newline-separated list of directories to mkdir -p. Stored under a key that cannot collide with any EncodeWorkspacePath output (the "__" prefix is reserved).

View Source 
const MigrationSourceVolumeName = "openclaw-source"

MigrationSourceVolumeName is the volume name the migration init container mounts as the OpenClaw source.

View Source 
const ResticImage = "restic/restic:0.16.4"

ResticImage is the pinned default snapshot-tool image. Mirrors internal/controller.ResticImage (duplicated to keep this package import-cycle free).

Variables

This section is empty.

Functions

func BackupCronJobName 

func BackupCronJobName(inst *hermesv1.HermesInstance) string

BackupCronJobName returns the deterministic name for the periodic backup CronJob.

func BackupPruneCronJobName 

func BackupPruneCronJobName(inst *hermesv1.HermesInstance) string

BackupPruneCronJobName returns the deterministic name for the history-pruning CronJob.

func BoolValue 

func BoolValue(b *bool) bool

BoolValue dereferences a *bool, returning false on nil.

func BoolValueOrDefault 

func BoolValueOrDefault(b *bool, def bool) bool

BoolValueOrDefault dereferences a *bool, returning def on nil.

func BuildAgentRuntimeEnv added in v0.1.18 

func BuildAgentRuntimeEnv(inst *hermesv1.HermesInstance) []corev1.EnvVar

BuildAgentRuntimeEnv returns the environment that drives the upstream s6 hermes-agent image so a HermesInstance comes up as a long-lived gateway with the OpenAI-compatible API server and a /health endpoint on the gateway port:

  • HERMES_HOME points the agent at the persistent /opt/data volume.
  • HERMES_UID/HERMES_GID drive the s6 stage2 privilege drop to a non-root user (the container itself starts as root so s6 can remap + chown the volume).
  • API_SERVER_* enables the gateway's OpenAI-compatible HTTP API and /health on the gateway port. The key authenticates /v1; /health is unauthenticated, which is what the readiness/liveness probes hit.

func BuildBackupCronJob 

func BuildBackupCronJob(inst *hermesv1.HermesInstance) *batchv1.CronJob

BuildBackupCronJob returns the desired periodic backup CronJob. Caller is responsible for setting OwnerReferences and applying via CreateOrUpdate.

func BuildBackupOneShotJob 

func BuildBackupOneShotJob(inst *hermesv1.HermesInstance, opts BackupJobOpts) *batchv1.Job

BuildBackupOneShotJob returns a Job that snapshots the instance PVC to S3. S3 access keys arrive via EnvFrom.SecretRef so they never appear in the PodSpec.

func BuildBackupPruneCronJob 

func BuildBackupPruneCronJob(inst *hermesv1.HermesInstance) *batchv1.CronJob

BuildBackupPruneCronJob returns a daily CronJob that purges old snapshots.

The prune logic:

  • Lists `<prefix><ns>/<name>/*.tar.zst` sorted desc by lex timestamp.
  • Keeps the newest `historyLimit`; deletes the rest.
  • Lists `<prefix><ns>/<name>/failed/*.tar.zst` similarly with `failedHistoryLimit`.

We run restic forget against the same repo using `--keep-last`. Restic's retention is content-aware so this is robust to clock skew.

func BuildConfigMap 

func BuildConfigMap(inst *hermesv1.HermesInstance, resolvedBody string) *corev1.ConfigMap

BuildConfigMap returns the desired ConfigMap holding ~/.hermes/config.yaml.

`resolvedBody` is the body the reconciler has already resolved for the case where spec.config.configMapRef is set. The builder is pure: it does not reach out to the apiserver.

  • Empty resolvedBody + Raw set → use Raw verbatim (YAML-serialised).
  • Empty resolvedBody + Raw unset → emit "{}\n".
  • resolvedBody non-empty + Raw unset → use resolvedBody verbatim.
  • resolvedBody non-empty + Raw set → caller is responsible for merging (use MergeYAMLBodies) and passing the merged result as resolvedBody.

func BuildGatewayConfigFragments 

func BuildGatewayConfigFragments(inst *hermesv1.HermesInstance) map[string]any

BuildGatewayConfigFragments returns the typed Go shape of the `gateways:` sub-tree of config.yaml. configmap.go merges this under the user's raw config.

func BuildGatewayEgressEndpoints 

func BuildGatewayEgressEndpoints(inst *hermesv1.HermesInstance) []string

BuildGatewayEgressEndpoints returns upstream hosts each enabled gateway needs.

func BuildGatewayEnv 

func BuildGatewayEnv(inst *hermesv1.HermesInstance) []corev1.EnvVar

BuildGatewayEnv returns explicit per-gateway env vars.

func BuildGatewayEnvFrom 

func BuildGatewayEnvFrom(inst *hermesv1.HermesInstance) []corev1.EnvFromSource

BuildGatewayEnvFrom returns whole-Secret envFrom entries. Reserved for gateways that use a single Secret with multiple keys (e.g. WhatsApp).

func BuildGatewayTokenSecret 

func BuildGatewayTokenSecret(inst *hermesv1.HermesInstance) *corev1.Secret

BuildGatewayTokenSecret returns the operator-owned per-instance Secret. It is a pure builder: the value of the API server key (APIServerKeySecretKey) is filled in and preserved by the reconciler, not here, so the builder stays deterministic. Plan 3 will additionally populate gateway-token bytes resolved from spec.gateways.*.tokenSecretRef.

func BuildGrafanaDashboardInstance added in v0.1.12 

func BuildGrafanaDashboardInstance(inst *hermesv1.HermesInstance) *corev1.ConfigMap

BuildGrafanaDashboardInstance creates a ConfigMap containing the per-instance dashboard.

func BuildGrafanaDashboardOperator added in v0.1.12 

func BuildGrafanaDashboardOperator(inst *hermesv1.HermesInstance) *corev1.ConfigMap

BuildGrafanaDashboardOperator creates a ConfigMap containing the operator overview dashboard.

func BuildHPA 

func BuildHPA(inst *hermesv1.HermesInstance) *autoscalingv2.HorizontalPodAutoscaler

BuildHPA constructs the desired HorizontalPodAutoscaler. Scale target is the StatefulSet built by BuildStatefulSet (same name).

func BuildHTTPRoute added in v0.1.12 

func BuildHTTPRoute(inst *hermesv1.HermesInstance) *unstructured.Unstructured

BuildHTTPRoute constructs the desired Gateway API HTTPRoute as an unstructured object. It mirrors the Ingress builder: a single prefix rule routing to the agent Service. Returns nil when no HTTPRoute is requested.

func BuildHonchoConsumerEnv 

func BuildHonchoConsumerEnv(inst *hermesv1.HermesInstance) []corev1.EnvVar

BuildHonchoConsumerEnv returns env vars added to the hermes container.

func BuildHonchoDeployment 

func BuildHonchoDeployment(inst *hermesv1.HermesInstance) *appsv1.Deployment

BuildHonchoDeployment returns the Honcho Deployment.

func BuildHonchoNetworkPolicy 

func BuildHonchoNetworkPolicy(inst *hermesv1.HermesInstance) *networkingv1.NetworkPolicy

BuildHonchoNetworkPolicy returns the NetworkPolicy that scopes the Honcho companion: ingress only from the parent hermes pod, egress denied entirely. Returns nil when honcho is not enabled.

func BuildHonchoPVC 

func BuildHonchoPVC(inst *hermesv1.HermesInstance) *corev1.PersistentVolumeClaim

BuildHonchoPVC returns the Honcho data PVC (5Gi default).

func BuildHonchoService 

func BuildHonchoService(inst *hermesv1.HermesInstance) *corev1.Service

BuildHonchoService returns a ClusterIP Service.

func BuildIngress 

func BuildIngress(inst *hermesv1.HermesInstance) *networkingv1.Ingress

BuildIngress constructs the desired Ingress. User annotations always win on key conflict with operator-supplied defaults.

func BuildMigrationInitContainer 

func BuildMigrationInitContainer(inst *hermesv1.HermesInstance) *corev1.Container

BuildMigrationInitContainer returns the init container that imports an OpenClaw instance into the hermes PVC. Returns nil when migration is not configured or already completed.

func BuildNetworkPolicy 

func BuildNetworkPolicy(inst *hermesv1.HermesInstance) *networkingv1.NetworkPolicy

BuildNetworkPolicy returns a default-deny baseline plus selective allow rules.

func BuildPDB 

func BuildPDB(inst *hermesv1.HermesInstance) *policyv1.PodDisruptionBudget

BuildPDB constructs the desired PodDisruptionBudget. When both MinAvailable and MaxUnavailable are set, MinAvailable wins (k8s forbids both: the validating webhook rejects the spec). When neither is set, MaxUnavailable=1.

func BuildPVC 

func BuildPVC(inst *hermesv1.HermesInstance) *corev1.PersistentVolumeClaim

BuildPVC returns the desired PersistentVolumeClaim. PVCs are immutable after creation (k8s rule); callers must only create, never update.

func BuildPrometheusRule 

func BuildPrometheusRule(inst *hermesv1.HermesInstance) *unstructured.Unstructured

BuildPrometheusRule emits a PrometheusRule containing the operator-default alerts plus any spec.observability.prometheusRule.additionalRules.

func BuildRestoreInitContainer 

func BuildRestoreInitContainer(inst *hermesv1.HermesInstance) *corev1.Container

BuildRestoreInitContainer returns the init container that restores a snapshot into the PVC. Returns nil when no restore is requested or one already finished.

func BuildRole 

func BuildRole(inst *hermesv1.HermesInstance) *rbacv1.Role

BuildRole returns the per-instance Role. Base ruleset: read own ConfigMap + own gateway-token Secret. When selfConfigure.enabled is true, additional verbs are added on hermesinstances and hermesselfconfigs.

func BuildRoleBinding 

func BuildRoleBinding(inst *hermesv1.HermesInstance) *rbacv1.RoleBinding

BuildRoleBinding binds the per-instance SA to the per-instance Role.

func BuildRuntimeInitContainers 

func BuildRuntimeInitContainers(inst *hermesv1.HermesInstance) []corev1.Container

BuildRuntimeInitContainers returns the ordered init containers required by spec.runtime. Order: init-apt → init-uv → init-pip. Each container mounts the full data volume (no subPath, lesson openclaw #450).

func BuildRuntimeVolumeMounts 

func BuildRuntimeVolumeMounts(inst *hermesv1.HermesInstance) []corev1.VolumeMount

BuildRuntimeVolumeMounts returns the additional mounts for the main hermes container.

func BuildRuntimeVolumes 

func BuildRuntimeVolumes(inst *hermesv1.HermesInstance) []corev1.Volume

BuildRuntimeVolumes returns additional Volumes beyond data PVC + config CM.

func BuildService 

func BuildService(inst *hermesv1.HermesInstance) *corev1.Service

BuildService constructs the desired Service. Honors spec.networking.service (Type, ClusterIP, Ports, Annotations, LoadBalancerClass, ExternalTrafficPolicy); appends a "metrics" port automatically when spec.observability.metrics.enabled.

func BuildServiceAccount 

func BuildServiceAccount(inst *hermesv1.HermesInstance) *corev1.ServiceAccount

BuildServiceAccount returns the per-instance SA. AutomountServiceAccountToken is false unless spec.selfConfigure.enabled is true.

func BuildServiceMonitor 

func BuildServiceMonitor(inst *hermesv1.HermesInstance) *unstructured.Unstructured

BuildServiceMonitor returns an unstructured ServiceMonitor. Scheme on the endpoint follows spec.observability.metrics.secure (lesson #435/#440).

func BuildSnapshotJob 

func BuildSnapshotJob(inst *hermesv1.HermesInstance, profileID, data string, when time.Time) *batchv1.Job

BuildSnapshotJob constructs a one-shot Job that writes a profile snapshot to /data/snapshots/<profileID>/<timestamp>.json on the Honcho PVC. Name is deterministic: `<inst>-snapshot-<profileID>-<YYYYMMDDHHMMSS>`.

func BuildStatefulSet 

func BuildStatefulSet(inst *hermesv1.HermesInstance, extraInits []corev1.Container) *appsv1.StatefulSet

BuildStatefulSet constructs the desired StatefulSet. Every k8s server-side default is set explicitly to avoid metadata.generation thrash on reconcile. extraInits is prepended before operator-managed init containers so that restore/migration runs BEFORE runtime-init touches the PVC.

func BuildTailscaleServeConfig added in v0.1.14 

func BuildTailscaleServeConfig(_ *hermesv1.HermesInstance) string

BuildTailscaleServeConfig renders the Tailscale Serve config JSON that fronts the local hermes gateway (127.0.0.1:<GatewayPort>) on tailnet :443.

Spec.Tailscale.Mode is intentionally not read here: the CRD enum admits only "serve", so every enabled instance gets this serve mapping. Note that Mode can also be "" (CRD defaulting only materializes when the tailscale key is present, and unit tests build specs directly); "" must behave like "serve". If a second mode is ever added to the enum, this function is where the behavior must branch.

func BuildTailscaleSidecar added in v0.1.14 

func BuildTailscaleSidecar(inst *hermesv1.HermesInstance) *corev1.Container

BuildTailscaleSidecar builds the operator-managed tailscale sidecar container, or nil when tailscale is disabled.

func BuildWorkspaceConfigMap 

func BuildWorkspaceConfigMap(inst *hermesv1.HermesInstance) *corev1.ConfigMap

BuildWorkspaceConfigMap creates the ConfigMap holding spec.workspace.initialFiles (path-encoded into ConfigMap data keys) and spec.workspace.initialDirs (under a single newline-separated key).

func ConfigMapName 

func ConfigMapName(inst *hermesv1.HermesInstance) string

ConfigMapName returns the deterministic ConfigMap name for the rendered config.

func DecodeWorkspacePath 

func DecodeWorkspacePath(key string) string

DecodeWorkspacePath is the inverse of EncodeWorkspacePath.

func EncodeWorkspacePath 

func EncodeWorkspacePath(path string) string

EncodeWorkspacePath turns "a/b/c.md" into "a__b__c.md". This is the canonical encoding shared with Plan 3's runtime-init decoder and Plan 4's HermesSelfConfig SSA writer.

func ExtraEgressRules 

func ExtraEgressRules(inst *hermesv1.HermesInstance) []networkingv1.NetworkPolicyEgressRule

ExtraEgressRules returns the per-instance egress rules driven by spec.gateways and spec.profileStore. Plan 2's base default-deny baseline opens DNS + TCP/443 already; these rules add (1) explicit per-gateway endpoints (still TCP/443 but documented per gateway) and (2) egress to the Honcho sibling pod on TCP/8000 when ProfileStore.Honcho is enabled.

func GatewayTokenSecretName 

func GatewayTokenSecretName(inst *hermesv1.HermesInstance) string

GatewayTokenSecretName returns the deterministic name for the operator-owned gateway-tokens Secret.

func GenerateAPIServerKey added in v0.1.18 

func GenerateAPIServerKey() (string, error)

GenerateAPIServerKey returns a cryptographically random key for the agent's OpenAI-compatible API server. The reconciler generates this once on Secret creation and preserves it across reconciles (see reconcileSecret), so it never thrashes and is never derivable from public object metadata.

func GrafanaDashboardEnabled added in v0.1.12 

func GrafanaDashboardEnabled(inst *hermesv1.HermesInstance) bool

GrafanaDashboardEnabled reports whether Grafana dashboard ConfigMaps should be emitted for this instance.

func GrafanaDashboardInstanceName added in v0.1.12 

func GrafanaDashboardInstanceName(inst *hermesv1.HermesInstance) string

GrafanaDashboardInstanceName returns the name of the per-instance dashboard ConfigMap.

func GrafanaDashboardOperatorName added in v0.1.12 

func GrafanaDashboardOperatorName(inst *hermesv1.HermesInstance) string

GrafanaDashboardOperatorName returns the name of the operator overview dashboard ConfigMap.

func HPAName 

func HPAName(inst *hermesv1.HermesInstance) string

HPAName returns the deterministic HPA name.

func HTTPRouteGVK added in v0.1.12 

func HTTPRouteGVK() schema.GroupVersionKind

HTTPRouteGVK is the Gateway API GroupVersionKind we emit. We build it as an unstructured object to avoid taking a dependency on sigs.k8s.io/gateway-api; the CRDs must be installed in the cluster for the route to take effect.

func HTTPRouteName added in v0.1.12 

func HTTPRouteName(inst *hermesv1.HermesInstance) string

HTTPRouteName returns the deterministic HTTPRoute name.

func HonchoDeploymentName 

func HonchoDeploymentName(inst *hermesv1.HermesInstance) string

HonchoDeploymentName, HonchoServiceName, HonchoPVCName return deterministic resource names. The PVC name is locked because Plan 4 Task 11 hard-codes `<inst>-honcho-data`.

func HonchoLabels 

func HonchoLabels(inst *hermesv1.HermesInstance) map[string]string

HonchoLabels returns labels for the Honcho sub-stack.

func HonchoPVCName 

func HonchoPVCName(inst *hermesv1.HermesInstance) string

func HonchoServiceName 

func HonchoServiceName(inst *hermesv1.HermesInstance) string

func IngressName 

func IngressName(inst *hermesv1.HermesInstance) string

IngressName returns the deterministic Ingress name.

func IsHPAEnabled 

func IsHPAEnabled(inst *hermesv1.HermesInstance) bool

IsHPAEnabled returns true when spec.availability.horizontalPodAutoscaler.enabled is true.

func LabelsForInstance 

func LabelsForInstance(inst *hermesv1.HermesInstance) map[string]string

LabelsForInstance returns the standard recommended labels for resources owned by a HermesInstance. Plans 2+ may add more.

func MergePreservingForeign 

func MergePreservingForeign(existing, desired map[string]string, operatorPrefix string) map[string]string

MergePreservingForeign merges desired into existing, overwriting keys that start with the operator prefix and preserving all other keys. Lesson from openclaw-operator #446/#447.

func MergeYAMLBodies 

func MergeYAMLBodies(base, overlay string) (string, error)

MergeYAMLBodies performs a YAML deep-merge of `overlay` (JSON or YAML) onto `base` (YAML). Overlay wins on conflict. Used when spec.config.mergeMode=merge.

func NetworkPolicyName 

func NetworkPolicyName(inst *hermesv1.HermesInstance) string

NetworkPolicyName returns the deterministic NetworkPolicy name.

func PDBName 

func PDBName(inst *hermesv1.HermesInstance) string

PDBName returns the deterministic PDB name.

func PVCName 

func PVCName(inst *hermesv1.HermesInstance) string

PVCName returns the deterministic PVC name for a HermesInstance.

func PrometheusRuleGVK 

func PrometheusRuleGVK() schema.GroupVersionKind

PrometheusRuleGVK is the GroupVersionKind emitted.

func PrometheusRuleName 

func PrometheusRuleName(inst *hermesv1.HermesInstance) string

PrometheusRuleName returns the deterministic name.

func Ptr 

func Ptr[T any](v T) *T

Ptr returns a pointer to v. Use only for short-lived literals.

func RoleBindingName 

func RoleBindingName(inst *hermesv1.HermesInstance) string

RoleBindingName returns the deterministic RoleBinding name.

func RoleName 

func RoleName(inst *hermesv1.HermesInstance) string

RoleName returns the deterministic Role name.

func SelectorLabels 

func SelectorLabels(inst *hermesv1.HermesInstance) map[string]string

SelectorLabels returns the immutable subset of LabelsForInstance suitable for Selector fields on Service/Deployment/StatefulSet. Selectors are immutable in k8s; the operator-managed-by label may evolve across versions, so we exclude it from selectors.

func ServiceAccountName 

func ServiceAccountName(inst *hermesv1.HermesInstance) string

ServiceAccountName returns the deterministic name of the operator-created ServiceAccount. Distinct from ServiceAccountNameFor (which honors the spec.security.rbac.serviceAccountName override and tells the pod which SA to use).

func ServiceAccountNameFor 

func ServiceAccountNameFor(inst *hermesv1.HermesInstance) string

ServiceAccountNameFor returns the ServiceAccount the agent pod should use: the spec.security.rbac.serviceAccountName override when set, else the operator-created SA which has the same name as the instance.

func ServiceMonitorGVK 

func ServiceMonitorGVK() schema.GroupVersionKind

ServiceMonitorGVK is the GroupVersionKind we emit.

func ServiceMonitorName 

func ServiceMonitorName(inst *hermesv1.HermesInstance) string

ServiceMonitorName returns the deterministic name.

func ServiceName 

func ServiceName(inst *hermesv1.HermesInstance) string

ServiceName returns the deterministic Service name.

func StatefulSetName 

func StatefulSetName(inst *hermesv1.HermesInstance) string

StatefulSetName returns the deterministic name.

func WorkspaceConfigMapName 

func WorkspaceConfigMapName(inst *hermesv1.HermesInstance) string

WorkspaceConfigMapName returns the deterministic name.

Types

type BackupJobOpts 

type BackupJobOpts struct {
	Name        string // Deterministic Job name (e.g. "<inst>-backup-final")
	SnapshotKey string // Full S3 key the snapshot will be written to
	Kind        string // "onDelete" | "preUpdate" | "scheduled": recorded as a label
}

BackupJobOpts captures the inputs the controller passes to the builder.

type IngressProvider 

type IngressProvider string

IngressProvider is the detected ingress controller flavour. 

const (
	IngressProviderNginx   IngressProvider = "nginx"
	IngressProviderTraefik IngressProvider = "traefik"
	IngressProviderUnknown IngressProvider = "unknown"
)

func DetectIngressProvider 

func DetectIngressProvider(className *string) IngressProvider

DetectIngressProvider classifies the className by substring match.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.