Documentation
¶
Overview ¶
Package nomad is a HashiCorp Nomad-backed provider.Provider.
Each ctrlplane Instance maps to one Nomad Job named cp-<instanceID> containing a single TaskGroup with one Task per ServiceSpec. Init services use the prestart lifecycle hook; Sidecars use poststart with sidecar=true; Main services have no lifecycle stanza and run for the group's lifetime. TaskGroup network mode "bridge" gives siblings DNS resolution by service name within the group.
Index ¶
- Variables
- type Config
- type Option
- type Provider
- func (p *Provider) Capabilities() []provider.Capability
- func (p *Provider) Deploy(ctx context.Context, req provider.DeployRequest) (*provider.DeployResult, error)
- func (p *Provider) Deprovision(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Exec(_ context.Context, _ id.ID, _ provider.ExecRequest) (*provider.ExecResult, error)
- func (p *Provider) HealthCheck(ctx context.Context) (*provider.HealthStatus, error)
- func (p *Provider) Info() provider.ProviderInfo
- func (p *Provider) Logs(_ context.Context, _ id.ID, _ provider.LogOptions) (io.ReadCloser, error)
- func (p *Provider) Provision(ctx context.Context, req provider.ProvisionRequest) (*provider.ProvisionResult, error)
- func (p *Provider) Resources(ctx context.Context, instanceID id.ID) (*provider.ResourceUsage, error)
- func (p *Provider) Restart(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Rollback(_ context.Context, _ id.ID, _ id.ID) error
- func (p *Provider) Scale(ctx context.Context, instanceID id.ID, spec provider.ResourceSpec) error
- func (p *Provider) Start(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Status(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
- func (p *Provider) Stop(ctx context.Context, instanceID id.ID) error
Constants ¶
This section is empty.
Variables ¶
var ErrLogsNotImplemented = errors.New("nomad: logs not implemented")
ErrLogsNotImplemented is returned by Logs until per-task log streaming is wired (Nomad's logs API is per-allocation + per-task; doable but deferred).
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Address is the Nomad API endpoint.
Address string `default:"http://localhost:4646" env:"CP_NOMAD_ADDRESS" json:"address,omitempty"`
// Token is the Nomad ACL token for authentication.
Token string `env:"CP_NOMAD_TOKEN" json:"-"`
// Region is the Nomad region to target.
Region string `default:"global" env:"CP_NOMAD_REGION" json:"region"`
// Namespace is the Nomad namespace for job submissions.
Namespace string `default:"default" env:"CP_NOMAD_NAMESPACE" json:"namespace"`
// Datacenter is the Nomad datacenter to schedule into. Empty
// allows Nomad to pick from all known datacenters.
Datacenter string `env:"CP_NOMAD_DATACENTER" json:"datacenter,omitempty"`
}
Config holds configuration for the Nomad provider.
type Option ¶
Option configures a Nomad provider.
func WithConfig ¶
WithConfig applies all non-zero fields from a Config struct. This is useful when loading configuration from files or environment variables.
func WithNamespace ¶
WithNamespace sets the Nomad namespace for job submissions.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is a HashiCorp Nomad infrastructure provider.
func New ¶
New creates a new Nomad provider with the given options. Without any options, sane defaults are used (address: localhost:4646, region: global, namespace: default).
func (*Provider) Capabilities ¶
func (p *Provider) Capabilities() []provider.Capability
Capabilities returns the set of features this provider supports.
func (*Provider) Deploy ¶
func (p *Provider) Deploy(ctx context.Context, req provider.DeployRequest) (*provider.DeployResult, error)
Deploy applies per-service image / env updates by patching the Job spec and re-submitting. Nomad's update stanza handles the rolling rollout; ctrlplane just provides the new desired state.
Phase 3 implementation: fetch the current Job, walk req.Services patching matching tasks (image via task.Config.image; env via task.Env merge), then re-submit. Services not in req.Services keep their current image.
func (*Provider) Deprovision ¶
Deprovision deregisters the Nomad Job (the `purge=true` query parameter wipes it from history so re-provisions don't trip the "job exists" guard).
func (*Provider) Exec ¶
func (p *Provider) Exec(_ context.Context, _ id.ID, _ provider.ExecRequest) (*provider.ExecResult, error)
Exec is not yet implemented — Nomad supports `nomad alloc exec` via WebSocket; pluggable transport for ExecResult round-trips lands when the exec UI feature is added.
func (*Provider) HealthCheck ¶ added in v1.5.1
HealthCheck pings the Nomad agent's /v1/agent/health endpoint and reports reachability. Treats any non-2xx as unhealthy.
func (*Provider) Info ¶
func (p *Provider) Info() provider.ProviderInfo
Info returns metadata about this provider.
func (*Provider) Logs ¶
func (p *Provider) Logs(_ context.Context, _ id.ID, _ provider.LogOptions) (io.ReadCloser, error)
Logs streams logs for one task in the instance's allocation. Phase 3 leaves this stubbed — Nomad's per-task logs API needs an allocation-ID + task-name + frame demuxer; deferred.
func (*Provider) Provision ¶
func (p *Provider) Provision(ctx context.Context, req provider.ProvisionRequest) (*provider.ProvisionResult, error)
Provision submits a Nomad Job built from the request's Services. One Job per Instance with a single TaskGroup containing every service as a Task; Init/Sidecar lifecycle hooks order the rollout.
func (*Provider) Resources ¶
func (p *Provider) Resources(ctx context.Context, instanceID id.ID) (*provider.ResourceUsage, error)
Resources returns a one-shot point-in-time sample of the instance's allocation resource usage via Nomad's HTTP API. See stats.go.
func (*Provider) Restart ¶
Restart triggers a rolling restart by issuing a job-restart RPC. Nomad recreates allocations one at a time honouring the group's update stanza.
func (*Provider) Rollback ¶
Rollback is intentionally a no-op — the deploy.Service builds a new DeployRequest from the prior Release's snapshot and routes it through Deploy. Nomad doesn't need a separate rollback path.
func (*Provider) Start ¶
Start re-submits the Job to Nomad. Use after Stop to re-schedule. Nomad doesn't have a "start a stopped job" verb — re-submit with the same spec is the canonical pattern.
Source Files