Documentation
¶
Overview ¶
Package k8s contains the SDK's controller-runtime client helpers for StoryRun, StepRun, and Impulse operations.
Consumers using these helpers need Kubernetes authentication plus RBAC that matches the methods they call. The common SDK paths require at least:
- StoryRun launch and lookup: `storytriggers` `create`/`get` and `storyruns` `get`
- StoryRun stop/status updates: `storyruns` `get` and `storyruns/status` `patch`
- StepRun status updates: `stepruns` `get` and `stepruns/status` `patch`
- Impulse trigger counters: `impulses` `get` and `impulses/status` `patch`
Additional controller or application features may require broader read access, but the list above covers the baseline SDK operations exposed by this package.
Index ¶
- func ComposeDNS1123Name(parts ...string) string
- func GetConfig() (*rest.Config, error)
- func ResolvePodNamespace() string
- func TriggerTokenFromContext(ctx context.Context) string
- func WithTriggerToken(ctx context.Context, token string) context.Context
- type Client
- func (c *Client) GetNamespace() string
- func (c *Client) PatchStepRunStatus(ctx context.Context, stepRunName string, patchData runsv1alpha1.StepRunStatus) error
- func (c *Client) StopStoryRun(ctx context.Context, storyRunName, namespace string) error
- func (c *Client) TriggerStory(ctx context.Context, storyName string, storyNamespace string, ...) (*runsv1alpha1.StoryRun, error)
- func (c *Client) UpdateImpulseTriggerStats(ctx context.Context, impulseName string, namespace string, ...) error
- type MockClient
- func (m *MockClient) GetNamespace() string
- func (m *MockClient) PatchStepRunStatus(ctx context.Context, stepRunName string, patchData runsv1alpha1.StepRunStatus) error
- func (m *MockClient) StopStoryRun(ctx context.Context, storyRunName, namespace string) error
- func (m *MockClient) TriggerStory(ctx context.Context, storyName string, storyNamespace string, ...) (*runsv1alpha1.StoryRun, error)
- type TriggerStatsDelta
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComposeDNS1123Name ¶ added in v0.1.2
ComposeDNS1123Name builds a DNS-1123 compliant name from provided parts. It preserves readability when possible and appends a hash suffix when needed.
func GetConfig ¶
GetConfig creates a new Kubernetes REST config, applying SDK-specific defaults and environment variable overrides. This function is exposed to allow consumers to create their own clients with the same settings.
func ResolvePodNamespace ¶
func ResolvePodNamespace() string
ResolvePodNamespace exposes the environment-based namespace resolution used by the SDK. This avoids requiring a Kubernetes client when only the namespace is needed.
func TriggerTokenFromContext ¶ added in v0.1.2
TriggerTokenFromContext returns the trigger token stored in the context, if any.
func WithTriggerToken ¶ added in v0.1.2
WithTriggerToken attaches an idempotency token used by TriggerStory to derive a stable trigger-delivery identity for StoryTrigger requests. Nil contexts are accepted; when a non-empty token is provided, the helper falls back to context.Background() so token attachment stays panic-free.
Types ¶
type Client ¶
Client is a wrapper around the controller-runtime Kubernetes client that provides SDK-specific functionality for interacting with bobrapet resources.
func NewClientForConfig ¶ added in v0.1.2
NewClientForConfig creates a new Kubernetes client for the given config.
func SharedClient ¶ added in v0.1.2
SharedClient returns a process-wide singleton Kubernetes client. Unlike NewClient, it does not allocate a new HTTP transport on every call. Initialization is retried on each call until it succeeds, so transient API-server unavailability does not permanently break the SDK.
func (*Client) GetNamespace ¶
GetNamespace returns the Kubernetes namespace that the client is configured to use.
func (*Client) PatchStepRunStatus ¶
func (c *Client) PatchStepRunStatus( ctx context.Context, stepRunName string, patchData runsv1alpha1.StepRunStatus, ) error
PatchStepRunStatus updates the StepRun status with retry-on-conflict logic. This prevents lost updates when the controller patches status simultaneously. Uses exponential backoff with jitter to prevent "thundering herd" problems. Callers need RBAC for `stepruns` `get` and `stepruns/status` `patch`.
func (*Client) StopStoryRun ¶ added in v0.1.2
StopStoryRun requests graceful cancellation for the specified StoryRun. If namespace is empty, the client's namespace is used. Callers need RBAC for `storyruns` `get` and `storyruns` `patch`. Returns sdkerrors.ErrNotFound when the StoryRun does not exist.
func (*Client) TriggerStory ¶
func (c *Client) TriggerStory( ctx context.Context, storyName string, storyNamespace string, inputs map[string]any, ) (*runsv1alpha1.StoryRun, error)
TriggerStory submits a StoryTrigger request for the configured Story and waits for the controller to resolve it into a StoryRun. Callers need RBAC for `storytriggers` `create`/`get` and `storyruns` `get`.
func (*Client) UpdateImpulseTriggerStats ¶ added in v0.1.2
func (c *Client) UpdateImpulseTriggerStats( ctx context.Context, impulseName string, namespace string, delta TriggerStatsDelta, ) error
UpdateImpulseTriggerStats applies the provided delta to the impulse status counters. Callers need RBAC for `impulses` `get` and `impulses/status` `patch`. Uses retry-on-conflict to avoid lost updates when the controller patches the same Impulse status concurrently.
type MockClient ¶
MockClient is a mock implementation of the ClientInterface for testing.
func (*MockClient) GetNamespace ¶
func (m *MockClient) GetNamespace() string
GetNamespace returns the mocked namespace value for testing.
func (*MockClient) PatchStepRunStatus ¶
func (m *MockClient) PatchStepRunStatus( ctx context.Context, stepRunName string, patchData runsv1alpha1.StepRunStatus, ) error
PatchStepRunStatus mocks the PatchStepRunStatus method for testing.
func (*MockClient) StopStoryRun ¶ added in v0.1.2
func (m *MockClient) StopStoryRun(ctx context.Context, storyRunName, namespace string) error
StopStoryRun mocks the StopStoryRun method for testing.
func (*MockClient) TriggerStory ¶
func (m *MockClient) TriggerStory( ctx context.Context, storyName string, storyNamespace string, inputs map[string]any, ) (*runsv1alpha1.StoryRun, error)
TriggerStory mocks the TriggerStory method for testing.
type TriggerStatsDelta ¶ added in v0.1.2
type TriggerStatsDelta struct {
// TriggersReceived increments the total number of trigger attempts observed by the impulse.
TriggersReceived int64
// StoriesLaunched increments the total number of StoryRuns successfully created.
StoriesLaunched int64
// FailedTriggers increments the total number of trigger attempts that failed before launch.
FailedTriggers int64
// ThrottledTriggers increments the total number of triggers rejected by throttling policy.
ThrottledTriggers int64
// LastTrigger records when the most recent trigger attempt was received.
LastTrigger time.Time
// LastSuccess records when the most recent successful StoryRun launch completed.
LastSuccess *time.Time
// LastThrottled records when the most recent trigger was throttled.
LastThrottled *time.Time
}
TriggerStatsDelta describes the per-trigger counters to apply to an Impulse status.