podspec

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package podspec provides utilities for building Kubernetes PodTemplateSpec objects.

This package consolidates pod template building logic used by controllers when constructing Jobs, Deployments, and StatefulSets. It provides a consistent approach to applying:

  • Container configuration (image, resources, probes, security context)
  • Secret artifacts (environment variables, volumes, mounts)
  • Storage configuration (S3, file-based storage env vars)
  • Labels, annotations, and metadata

Pod Template Builder

The Build function constructs a corev1.PodTemplateSpec from a Config struct, applying resolved execution settings consistently across all workload types: 

cfg := podspec.Config{
    ContainerName:  "engram",
    Labels:         labels,
    ResolvedConfig: resolved,
}
template := podspec.Build(cfg)

Secret Artifacts

The BuildSecretArtifacts function converts EngramTemplate secret schemas into Kubernetes primitives that can be attached to pods: 

artifacts := podspec.BuildSecretArtifacts(template.Spec.SecretSchema, secrets)
artifacts.Apply(&podTemplate)

Storage Configuration

The ApplyStorageEnv function wires storage policy settings into pod specs, delegating to the shared runtime storage helpers: 

podspec.ApplyStorageEnv(resolved, &podSpec, &container, timeout)

This package follows Kubernetes controller-runtime conventions and is designed to be used alongside github.com/bubustack/bobrapet/internal/config for configuration resolution.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplySecretArtifacts 

func ApplySecretArtifacts(
	template *catalogv1alpha1.EngramTemplate,
	cfg *config.ResolvedExecutionConfig,
	podSpec *corev1.PodTemplateSpec,
)

ApplySecretArtifacts wires the secret schema artifacts defined by an EngramTemplate into the pod spec.

This function materializes template-defined secrets as Kubernetes volumes, environment variables, and volume mounts, enabling workloads to access sensitive configuration.

Arguments:

  • template: the EngramTemplate containing the secret schema definition.
  • cfg: the resolved execution configuration containing actual secret values.
  • podSpec: the PodTemplateSpec to modify with secret artifacts.

Side Effects:

  • Modifies podSpec.Volumes to include secret-backed volumes.
  • Modifies podSpec.Spec.Containers[0].Env to include secret environment variables.
  • Modifies podSpec.Spec.Containers[0].EnvFrom to include secret references.
  • Modifies podSpec.Spec.Containers[0].VolumeMounts to include volume mounts.

func ApplyStorageEnv 

func ApplyStorageEnv(
	resolved *config.ResolvedExecutionConfig,
	podSpec *corev1.PodSpec,
	container *corev1.Container,
	timeout string,
)

ApplyStorageEnv converts the resolved storage policy into the shared runtime storage config and delegates to core/runtime/storage.ApplyEnv so controllers, connector, and SDK surfaces share the same env/volume wiring.

Arguments:

  • resolved *config.ResolvedExecutionConfig: supplies the storage policy.
  • podSpec *corev1.PodSpec: mutated to include storage volumes when needed.
  • container *corev1.Container: receives storage env vars and mounts.
  • timeout string: formatted timeout string applied to relevant env vars.

func Build 

func Build(cfg Config) corev1.PodTemplateSpec

Build constructs a PodTemplateSpec from the provided configuration.

Behavior:

  • Creates a primary container with image, probes, resources, and security context from ResolvedConfig.
  • Applies labels, annotations, env vars, volumes, and ports from Config.
  • Sets TerminationGracePeriodSeconds if configured.
  • Only sets RestartPolicy if non-empty.

Arguments:

  • cfg Config: the configuration for the pod template.

Returns:

  • corev1.PodTemplateSpec: the constructed pod template.

Notes:

  • Callers are responsible for applying additional domain-specific modifications (e.g., storage env, secret artifacts) after this function returns.

func CloneStringMap 

func CloneStringMap(src map[string]string) map[string]string

CloneStringMap creates a shallow copy of a string map.

Behavior:

  • Returns nil for nil or empty source.
  • Copies all key-value pairs to new map.

Arguments:

  • src map[string]string: source map to clone.

Returns:

  • map[string]string: the cloned map.

func FormatStorageTimeout 

func FormatStorageTimeout(resolved *config.ResolvedExecutionConfig, fallbackSeconds int) string

FormatStorageTimeout converts the resolved storage timeout into a user-friendly duration string.

Behavior:

  • Uses resolved.Storage.TimeoutSeconds when available and positive.
  • Falls back to fallbackSeconds when resolved timeout is unavailable.
  • Returns empty string when no valid timeout is available.

Arguments:

  • resolved *config.ResolvedExecutionConfig: the resolved execution config.
  • fallbackSeconds int: fallback timeout when resolved timeout is unavailable.

Returns:

  • string: formatted duration (e.g., "30s") or empty string.

func StorageServiceAccountAnnotations 

func StorageServiceAccountAnnotations(resolved *config.ResolvedExecutionConfig) map[string]string

StorageServiceAccountAnnotations returns the annotations that should be applied to a controller-managed ServiceAccount so workloads can access their configured storage backend.

These annotations typically contain authentication credentials or configuration needed for storage backends like S3 (e.g., IAM role annotations for IRSA).

Arguments:

  • resolved: the resolved execution configuration containing storage settings.

Returns:

  • map[string]string: annotations to apply to the ServiceAccount, or nil if no storage configuration requires ServiceAccount annotations.

Types

type Config 

type Config struct {
	// ContainerName is the name for the primary container (e.g., "engram", "impulse").
	ContainerName string

	// Labels are applied to the pod metadata.
	Labels map[string]string

	// Annotations are applied to the pod metadata.
	Annotations map[string]string

	// EnvVars are environment variables for the primary container.
	EnvVars []corev1.EnvVar

	// EnvFrom are environment variable sources for the primary container.
	EnvFrom []corev1.EnvFromSource

	// Volumes are pod-level volumes.
	Volumes []corev1.Volume

	// VolumeMounts are mount points for the primary container.
	VolumeMounts []corev1.VolumeMount

	// Ports are container ports to expose.
	Ports []corev1.ContainerPort

	// RestartPolicy overrides the pod restart policy (optional).
	RestartPolicy corev1.RestartPolicy

	// TerminationGracePeriodSec is the pod termination grace period.
	TerminationGracePeriodSec int64

	// ResolvedConfig provides image, resources, probes, and security settings.
	ResolvedConfig *config.ResolvedExecutionConfig
}

Config provides common fields required to build a pod template.

This struct captures all fields shared between StepRun and Impulse pod templates, allowing controllers to pass container name, labels, annotations, and resolved execution configuration through a single struct.

Example usage: 

cfg := podspec.Config{
    ContainerName:             "engram",
    Labels:                    labels,
    Annotations:               annotations,
    EnvVars:                   envVars,
    ResolvedConfig:            resolvedConfig,
    TerminationGracePeriodSec: 30,
}
template := podspec.Build(cfg)

type SecretArtifacts 

type SecretArtifacts struct {
	// EnvVars are individual environment variables referencing secret keys.
	EnvVars []corev1.EnvVar

	// EnvFrom are secret references that inject all keys with a prefix.
	EnvFrom []corev1.EnvFromSource

	// Volumes are secret-backed volumes.
	Volumes []corev1.Volume

	// VolumeMounts are mount points for secret volumes.
	VolumeMounts []corev1.VolumeMount
}

SecretArtifacts captures the Kubernetes objects required to surface secrets inside pods.

This struct collects environment variables, envFrom sources, volumes, and volume mounts that should be added to a pod spec to make secrets available to the container.

func BuildSecretArtifacts 

func BuildSecretArtifacts(
	secretSchema map[string]catalogv1alpha1.SecretDefinition,
	mappings map[string]string,
) SecretArtifacts

BuildSecretArtifacts converts template secret definitions combined with resolved user mappings into Kubernetes primitives that can be attached to a pod.

Behavior:

  • Returns empty SecretArtifacts when mappings or secretSchema is empty.
  • Iterates through user-provided secret mappings.
  • Applies each secret according to its MountType (file, env, or both).

Arguments:

  • secretSchema map[string]catalogv1alpha1.SecretDefinition: template-defined secret definitions.
  • mappings map[string]string: user-provided logical name to actual secret name mappings.

Returns:

  • SecretArtifacts: Kubernetes primitives (EnvVars, EnvFrom, Volumes, VolumeMounts) for the pod.

Example: 

artifacts := podspec.BuildSecretArtifacts(template.Spec.SecretSchema, engram.Spec.Secrets)
artifacts.Apply(&podTemplate)

func (*SecretArtifacts) Apply 

func (a *SecretArtifacts) Apply(podSpec *corev1.PodTemplateSpec)

Apply mutates a PodTemplateSpec by appending secret-related volumes, env vars, and mounts.

Behavior:

  • Appends Volumes to podSpec.Spec.Volumes.
  • Appends EnvVars, EnvFrom, and VolumeMounts to the first container.
  • No-op if artifacts are empty or podSpec has no containers.

Arguments:

  • podSpec *corev1.PodTemplateSpec: the pod template to mutate.

Side Effects:

  • Modifies podSpec.Spec.Volumes.
  • Modifies podSpec.Spec.Containers[0].Env, EnvFrom, and VolumeMounts.

func (*SecretArtifacts) IsEmpty 

func (a *SecretArtifacts) IsEmpty() bool

IsEmpty returns true if the artifacts contain no volumes, env vars, or mounts.

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.