Documentation
¶
Overview ¶
Package direct implements DirectSandboxControl, which manages raw EC2 instances as agent execution environments. Multiple agents share one instance without isolation. This is the "D2: EC2 Lightweight Sandbox" shape from the cloud-sandbox-providers shaping doc.
Index ¶
- Variables
- type Config
- type DirectSandboxControl
- func (d *DirectSandboxControl) Capabilities() control.SandboxCapabilities
- func (d *DirectSandboxControl) Close() error
- func (d *DirectSandboxControl) CreateSandbox(ctx context.Context, req control.CreateSandboxRequest) (*control.CreateSandboxResponse, error)
- func (d *DirectSandboxControl) DestroySandbox(ctx context.Context, sandboxID string) error
- func (d *DirectSandboxControl) GetProcessStatus(ctx context.Context, req control.GetProcessStatusRequest) (*control.GetProcessStatusResponse, error)
- func (d *DirectSandboxControl) KillProcess(ctx context.Context, req control.KillProcessRequest) error
- func (d *DirectSandboxControl) LaunchProcess(ctx context.Context, req control.LaunchProcessRequest) (*control.LaunchProcessResponse, error)
- func (d *DirectSandboxControl) PauseSandbox(ctx context.Context, sandboxID string) error
- func (d *DirectSandboxControl) Recover(ctx context.Context) error
- func (d *DirectSandboxControl) ResumeSandbox(ctx context.Context, sandboxID string) error
- type Option
- type SSMAPI
- type UserDataTemplateData
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInstanceNotFound indicates the sandbox ID does not correspond to a // known managed instance. ErrInstanceNotFound = errors.New("direct: instance not found") // ErrProcessNotFound indicates the process ID does not correspond to a // known launched process on the given instance. ErrProcessNotFound = errors.New("direct: process not found") // ErrInstanceNotReady indicates the instance exists but is not in a state // where operations can be performed (e.g., stopped, pending). ErrInstanceNotReady = errors.New("direct: instance not ready") // ErrInstanceReadyTimeout indicates the instance did not reach "running" // state within Config.InstanceReadyTimeout. ErrInstanceReadyTimeout = errors.New("direct: instance ready timeout") // ErrProcessReadyTimeout indicates a launched process did not pass its // health check within Config.ProcessReadyTimeout. ErrProcessReadyTimeout = errors.New("direct: process ready timeout") // responding or not registered. ErrSSMUnavailable = errors.New("direct: ssm agent unavailable") // ErrSSMTimeout indicates an SSM command did not complete within the // allowed time. ErrSSMTimeout = errors.New("direct: ssm command timeout") // ErrProcessLaunchFailed indicates the process launch command failed // (e.g., binary not found, port in use, permission denied). ErrProcessLaunchFailed = errors.New("direct: process launch failed") // ErrResourcesExceedMaximum indicates the requested resources exceed the // largest supported instance type mapping. ErrResourcesExceedMaximum = errors.New("direct: resources exceed maximum supported") // ErrDirectClosed indicates the adapter is shutting down and cannot // accept new CreateSandbox calls. ErrDirectClosed = errors.New("direct: adapter is closed") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// AMIID is the AMI to launch instances from. Should have flexagent pre-installed.
AMIID string
// DefaultInstanceType is the EC2 instance type used when Resources is
// zero-valued (e.g., "t3.medium", "m5.xlarge").
DefaultInstanceType string
// SubnetID is the VPC subnet for instance placement.
SubnetID string
// SecurityGroupIDs are the security groups to attach to instances.
SecurityGroupIDs []string
// InstanceProfileARN is the IAM instance profile for SSM access and
// any AWS API calls from the instance.
InstanceProfileARN string
// KeyPairName is the SSH key pair for SSH fallback (optional; SSM is primary).
KeyPairName string
// RootVolumeSizeGB is the EBS root volume size in GiB (default 50).
RootVolumeSizeGB int
// RootVolumeType is the EBS volume type (default "gp3").
RootVolumeType string
// UserDataTemplate is a Go text/template script executed on instance boot.
// Used to configure workspace directory, install dependencies, etc.
UserDataTemplate string
// Tags are applied to all resources created by this adapter. The adapter
// always adds {"ManagedBy": "flex-agent-runtime", "adapter": "direct"}
// in addition to any user-provided tags.
Tags map[string]string
// IPSelectionMode controls which IP address is used for connectivity.
// Valid values: "public" (default), "private", "auto" (public if
// available, else private).
IPSelectionMode string
// TerminateOnClose controls whether Close() terminates all managed
// instances. When false (default), instances are left running for
// potential recovery after restart.
TerminateOnClose bool
// InstanceReadyTimeout is the maximum time to wait for an instance to
// reach "running" state and SSM registration (default 3 minutes).
InstanceReadyTimeout time.Duration
// ProcessReadyTimeout is the maximum time to wait for a launched process
// to pass its health check (default 30 seconds).
ProcessReadyTimeout time.Duration
}
Config configures the DirectSandboxControl adapter.
type DirectSandboxControl ¶
type DirectSandboxControl struct {
// contains filtered or unexported fields
}
DirectSandboxControl manages raw EC2 instances as agent environments. Multiple agents share one instance without isolation.
Shutdown safety: The closing flag and inflightWg WaitGroup protect against orphaned instances during Close(). CreateSandbox checks closing before starting work. Close() sets closing, then waits on inflightWg for all in-flight CreateSandbox operations to complete before cleanup.
func NewDirectSandboxControl ¶
func NewDirectSandboxControl(provisioner instance.InstanceProvisioner, ssmClient SSMAPI, cfg Config, opts ...Option) (*DirectSandboxControl, error)
NewDirectSandboxControl creates a DirectSandboxControl with the given provisioner, SSM client, and configuration. Constructor-time recovery is fail-fast on ListInstances errors to avoid silently leaking orphaned instances.
func (*DirectSandboxControl) Capabilities ¶
func (d *DirectSandboxControl) Capabilities() control.SandboxCapabilities
Capabilities returns the sandbox provider capabilities for the Direct adapter. Direct does not support snapshots or rollback (no ZFS). Pause is supported via EC2 stop/start, but is lossy -- all processes are killed and only EBS volumes survive.
func (*DirectSandboxControl) Close ¶
func (d *DirectSandboxControl) Close() error
Close shuts down the adapter. It blocks until in-flight CreateSandbox calls finish. If TerminateOnClose is set, managed instances are terminated.
func (*DirectSandboxControl) CreateSandbox ¶
func (d *DirectSandboxControl) CreateSandbox(ctx context.Context, req control.CreateSandboxRequest) (*control.CreateSandboxResponse, error)
CreateSandbox provisions a new EC2 instance and returns it as a sandbox.
func (*DirectSandboxControl) DestroySandbox ¶
func (d *DirectSandboxControl) DestroySandbox(ctx context.Context, sandboxID string) error
DestroySandbox terminates the underlying EC2 instance and removes the sandbox from in-memory tracking.
func (*DirectSandboxControl) GetProcessStatus ¶
func (d *DirectSandboxControl) GetProcessStatus(ctx context.Context, req control.GetProcessStatusRequest) (*control.GetProcessStatusResponse, error)
GetProcessStatus returns the current status of a launched process.
func (*DirectSandboxControl) KillProcess ¶
func (d *DirectSandboxControl) KillProcess(ctx context.Context, req control.KillProcessRequest) error
KillProcess terminates a launched process using SSM.
func (*DirectSandboxControl) LaunchProcess ¶
func (d *DirectSandboxControl) LaunchProcess(ctx context.Context, req control.LaunchProcessRequest) (*control.LaunchProcessResponse, error)
LaunchProcess starts a long-running process inside an existing sandbox using SSM.
func (*DirectSandboxControl) PauseSandbox ¶
func (d *DirectSandboxControl) PauseSandbox(ctx context.Context, sandboxID string) error
PauseSandbox stops the backing EC2 instance. This is a lossy pause: processes do not survive and are marked exited.
func (*DirectSandboxControl) Recover ¶
func (d *DirectSandboxControl) Recover(ctx context.Context) error
Recover rebuilds in-memory instance/process state from cloud inventory.
func (*DirectSandboxControl) ResumeSandbox ¶
func (d *DirectSandboxControl) ResumeSandbox(ctx context.Context, sandboxID string) error
ResumeSandbox starts a previously stopped EC2 instance, waits for cloud and SSM readiness, refreshes IPs, and clears process state.
type Option ¶
type Option func(*DirectSandboxControl)
Option configures a DirectSandboxControl.
func WithLogger ¶
WithLogger sets the structured logger for the adapter.
type SSMAPI ¶
type SSMAPI interface {
SendCommand(ctx context.Context, input *ssm.SendCommandInput, opts ...func(*ssm.Options)) (*ssm.SendCommandOutput, error)
GetCommandInvocation(ctx context.Context, input *ssm.GetCommandInvocationInput, opts ...func(*ssm.Options)) (*ssm.GetCommandInvocationOutput, error)
DescribeInstanceInformation(ctx context.Context, input *ssm.DescribeInstanceInformationInput, opts ...func(*ssm.Options)) (*ssm.DescribeInstanceInformationOutput, error)
}
SSMAPI wraps the subset of SSM SDK methods used by this adapter for remote process management. This is the remaining EC2-specific piece -- instance lifecycle is provider-neutral via InstanceProvisioner. In the future, this could be abstracted behind a RemoteExec interface to support non-AWS providers.
type UserDataTemplateData ¶
type UserDataTemplateData struct {
// SandboxID is a placeholder ("direct:pending"). The actual sandbox ID
// depends on the EC2 instance ID and is not known until after launch.
// Use EC2 instance metadata if the startup script needs self-identification.
SandboxID string
Labels map[string]string // labels from the CreateSandbox request
WorkspaceDir string // workspace directory path (default "/workspace")
}
UserDataTemplateData provides typed fields for UserData template rendering.