session

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package session holds per-command Kubernetes and Helm client state.

Session carries the global CLI options (kubeconfig, namespace, spec path, etc.) and travels through context.Context so every command shares one configured environment per invocation. Construct one with New, attach it via WithContext, and retrieve it in handlers through FromContext.

To access cluster resources, call Session.Target with the target environment name. It eagerly resolves the Kubernetes context from the spec's environment field and returns a Cluster that lazily constructs the Helm and Kubernetes clients. This two-phase model makes it a compile-time error to request a cluster client without first resolving which cluster to use.

Index

Constants

View Source 
const (
	// DefaultTimeout is the default timeout for Helm operations.
	DefaultTimeout = 10 * time.Minute

	// DefaultStorageDriver is the default Helm storage driver.
	DefaultStorageDriver = "secret"

	// DefaultNamespace is used when no namespace is specified.
	DefaultNamespace = "default"
)

Session defaults.

View Source 
const (
	// HelmStorageDriverSecret uses Kubernetes secrets for Helm storage.
	HelmStorageDriverSecret = "secret"

	// HelmStorageDriverConfigMap uses Kubernetes ConfigMaps for Helm storage.
	HelmStorageDriverConfigMap = "configmap"

	// HelmStorageDriverMemory uses in-memory storage for Helm (testing only).
	HelmStorageDriverMemory = "memory"

	// HelmTimeoutMin is the minimum allowed timeout for Helm operations.
	HelmTimeoutMin = 30 * time.Second

	// HelmTimeoutMax is the maximum allowed timeout for Helm operations.
	HelmTimeoutMax = 60 * time.Minute
)

Helm storage driver constants.

View Source 
const (
	// KubeConfigEnvVar is the environment variable for kubeconfig path.
	KubeConfigEnvVar = "KUBECONFIG"

	// NamespaceEnvVar is the environment variable for default namespace.
	NamespaceEnvVar = "DPY_NAMESPACE"

	// DebugEnvVar is the environment variable for enabling debug mode.
	DebugEnvVar = "DPY_DEBUG"
)

Environment variables consulted by the session package.

Variables

This section is empty.

Functions

func GetValidStorageDrivers 

func GetValidStorageDrivers() []string

GetValidStorageDrivers returns a list of valid storage drivers.

func ValidateStorageDriver 

func ValidateStorageDriver(driver string) bool

ValidateStorageDriver reports whether the storage driver is valid.

func ValidateTimeout 

func ValidateTimeout(timeout time.Duration) bool

ValidateTimeout reports whether timeout is within acceptable bounds.

func WithContext 

func WithContext(ctx context.Context, sess *Session) context.Context

WithContext returns a new context carrying sess.

Types

type Cluster 

type Cluster struct {
	*Session
	// contains filtered or unexported fields
}

Cluster is a resolved target: it embeds the base Session and adds a confirmed Kubernetes context plus lazily-initialized Helm and Kubernetes clients. Obtain one via Session.Target.

func (*Cluster) Context added in v0.4.0 

func (cl *Cluster) Context() string

Context returns the resolved Kubernetes context for this cluster target. An empty string means the default context from the active kubeconfig is used.

func (*Cluster) ContextFallback added in v0.4.0 

func (cl *Cluster) ContextFallback() (bool, string)

ContextFallback reports whether the target follows the kubeconfig current-context, and that context's name.

func (*Cluster) Helm 

func (cl *Cluster) Helm() (HelmClient, error)

Helm returns a memoized Helm client targeted at the resolved cluster.

func (*Cluster) Kubernetes 

func (cl *Cluster) Kubernetes() (kubernetes.Interface, error)

Kubernetes returns a memoized Kubernetes clientset targeted at the resolved cluster.

func (*Cluster) Namespace 

func (cl *Cluster) Namespace() string

Namespace returns the configured namespace, or "default" if none is set.

func (*Cluster) RESTConfig 

func (cl *Cluster) RESTConfig() (*rest.Config, error)

RESTConfig returns a Kubernetes REST config for the resolved cluster.

type CommandPolicy added in v0.4.0 

type CommandPolicy int

CommandPolicy controls how the session handles missing platform files. 

const (
	// PolicyLenient allows proceeding with a warning when the platform file
	// is absent. Used for read-only commands (logs, status, list, shell).
	PolicyLenient CommandPolicy = iota
	// PolicyStrict requires a resolvable platform file for commands that
	// modify cluster state (deploy, delete). The caller must gate on this
	// before contacting the cluster.
	PolicyStrict
)

type HelmClient 

type HelmClient interface {
	// IsReachable checks whether the configured Kubernetes cluster is reachable.
	IsReachable() error

	// InstallApp installs or upgrades an application using Helm. When resolved
	// is non-nil, TLS and hostname values are sourced from it rather than the
	// raw spec. postRenderer, when non-nil, is applied to the rendered
	// manifests before they are sent to the cluster.
	InstallApp(ctx context.Context, manifest *spec.Spec, environment string, dryRun bool, resolved *spec.ResolvedSpec, postRenderer postrenderer.PostRenderer) error

	// RenderManifests renders the chart for manifest/environment client-side,
	// without mutating the cluster or Helm's release history. The caller must
	// run the returned cleanup func once done with the result's ChartPath.
	// postRenderer, when non-nil, is applied to the rendered manifests.
	RenderManifests(ctx context.Context, manifest *spec.Spec, environment string, resolved *spec.ResolvedSpec, postRenderer postrenderer.PostRenderer) (*render.RenderResult, func(), error)

	// RenderOffline renders the chart for manifest/environment as a fresh
	// install, without any Kubernetes API access. The caller must run the
	// returned cleanup func once done with the result's ChartPath.
	// postRenderer, when non-nil, is applied to the rendered manifests.
	RenderOffline(ctx context.Context, manifest *spec.Spec, environment string, resolved *spec.ResolvedSpec, postRenderer postrenderer.PostRenderer) (*render.RenderResult, func(), error)

	// DeleteRelease uninstalls a Helm release. When wait is true the call
	// blocks until all resources are fully removed using the legacy polling
	// strategy with foreground cascade deletion.
	DeleteRelease(ctx context.Context, project, environment string, wait bool) error

	// GetRelease retrieves information about a specific release.
	GetRelease(ctx context.Context, project, environment string) (*v1.Release, error)

	// ListReleases returns a list of releases matching the given selector.
	ListReleases(ctx context.Context, selector labels.Selector) ([]*v1.Release, error)

	// GetReleaseHistory returns the history of a specific release.
	GetReleaseHistory(ctx context.Context, project, environment string) ([]*v1.Release, error)

	// RollbackRelease rolls back a release to a previous revision.
	RollbackRelease(ctx context.Context, releaseName string, revision int, timeout time.Duration) error
}

HelmClient is kept in this package so WithHelmFactory tests can inject a mock implementation without importing the concrete helm package. Render methods return render.RenderResult for the same reason.

type Option 

type Option func(*Session)

Option is a functional option for configuring a Session.

func WithCommandPolicy added in v0.4.0 

func WithCommandPolicy(policy CommandPolicy) Option

WithCommandPolicy sets the platform-missing policy for this session. Destructive commands (deploy, delete) should use PolicyStrict; read-only commands (logs, status, list, shell) should use PolicyLenient.

func WithDebug 

func WithDebug(keep bool) Option

WithDebug controls whether to keep temporary chart directories.

func WithExtraKubeconfigPaths 

func WithExtraKubeconfigPaths(paths ...string) Option

WithExtraKubeconfigPaths appends additional kubeconfig file paths to the clientcmd loading-rules Precedence list, making contexts from those files available without polluting the user's default kubeconfig. Missing files are silently skipped by client-go. An explicit --kubeconfig flag still takes priority because it sets ExplicitPath, which causes Precedence to be ignored.

func WithHelmFactory 

func WithHelmFactory(factory func(*Session) (HelmClient, error)) Option

WithHelmFactory sets a custom Helm client factory, primarily for testing.

func WithKubeContext 

func WithKubeContext(kubeContext string) Option

WithKubeContext sets the Kubernetes context, overriding the kubeconfig's current context. An empty value leaves the current context in effect.

func WithKubeconfig 

func WithKubeconfig(kubeconfig string) Option

WithKubeconfig sets the kubeconfig file path.

func WithKubernetesFactory 

func WithKubernetesFactory(factory func(*Session) (kubernetes.Interface, error)) Option

WithKubernetesFactory sets a custom Kubernetes client factory, primarily for testing.

func WithNamespace 

func WithNamespace(namespace string) Option

WithNamespace sets the Kubernetes namespace.

func WithPlatformFile added in v0.4.0 

func WithPlatformFile(path string) Option

WithPlatformFile sets an explicit platform file path, overriding both the DEPLOYAH_PLATFORM_FILE environment variable and the same-directory default.

func WithSpecPath 

func WithSpecPath(specPath string) Option

WithSpecPath sets the spec file path.

func WithStorageDriver 

func WithStorageDriver(driver string) Option

WithStorageDriver sets the Helm storage driver (default: "secret").

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the timeout for Helm operations.

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session holds per-invocation configuration and lazily loads the spec. It is created once in the root pre-run hook and travels through context.Context so every command shares one configured environment.

To access Helm or Kubernetes clients, call Session.Target first.

func FromContext 

func FromContext(ctx context.Context) *Session

FromContext extracts the Session from ctx, or nil if absent.

func New 

func New(options ...Option) *Session

New constructs a Session with the given functional options.

func (*Session) Close 

func (s *Session) Close() error

Close releases memoized resources held by the session.

func (*Session) CommandPolicy added in v0.4.0 

func (s *Session) CommandPolicy() CommandPolicy

CommandPolicy returns the configured platform-missing policy.

func (*Session) CurrentKubeContext added in v0.4.0 

func (s *Session) CurrentKubeContext() string

CurrentKubeContext returns the current-context name from the active kubeconfig resolution (explicit --kubeconfig path, deployah-managed extra paths, then KUBECONFIG/~/.kube/config), ignoring any --context override. Returns an empty string when no kubeconfig is readable.

func (*Session) DebugKeepTempChart 

func (s *Session) DebugKeepTempChart() bool

DebugKeepTempChart reports whether temporary chart directories should be kept.

func (*Session) KubeContext added in v0.4.0 

func (s *Session) KubeContext() string

KubeContext returns the explicit kube context override, or empty string if none was set. An empty string means the cluster context comes from the platform file or kubeconfig default.

func (*Session) ParseManifest added in v0.4.0 

func (s *Session) ParseManifest() (*spec.Spec, error)

ParseManifest reads and partially validates the spec (apiVersion + environments only, no envsubst, no defaults). It is intended for commands that need the raw manifest structure without environment-specific processing (e.g. validate manifest-only mode, resolve offline mode).

func (*Session) Platform added in v0.4.0 

func (s *Session) Platform() (*spec.PlatformConfig, error)

Platform loads and memoizes the platform configuration. It resolves the platform file path from (in order of precedence):

  1. An explicit path set via WithPlatformFile.
  2. The DEPLOYAH_PLATFORM_FILE environment variable.
  3. The same directory as the spec file (deployah.platform.yaml).

When no platform file is found, Platform returns (nil, nil). Only when a path is found but fails to load does it return an error.

func (*Session) Spec 

func (s *Session) Spec(ctx context.Context, environment string) (*spec.Spec, error)

Spec loads the spec for the configured path and environment. Each call loads from disk because the result depends on the environment argument (envsubst selects different env files per environment). The platform config, when present, supplies the environment registry.

func (*Session) SpecPath added in v0.4.0 

func (s *Session) SpecPath() string

SpecPath returns the configured spec file path.

func (*Session) Target 

func (s *Session) Target(ctx context.Context, env string) (*Cluster, error)

Target resolves the Kubernetes context for env and returns a Cluster from which Helm and Kubernetes clients can be obtained.

Precedence for the kubeContext used by the returned Cluster:

  1. The global --context flag (already stored in s.kubeContext).
  2. The platform file's context for env (via [PlatformEnvContext]).
  3. The default context from the active kubeconfig (empty string).

func (*Session) Timeout 

func (s *Session) Timeout() time.Duration

Timeout returns the configured timeout for Helm operations.

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.