raft

package
v1.6.2 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RPCDistributeCA       uint8 // Leader pushes CAs to followers (exported for use in ca.Manager)
	RPCRequestCA                // Follower requests CAs from leader (exported for use in ca.Manager)
	RPCRequestCertificate       // Follower submits CSRs to leader for signing
	RPCGetStatus                // Query node bootstrap status (for late joiner detection)
)

RPC type constants for message framing

Variables

This section is empty.

Functions

func DeriveEncryptionKey 

func DeriveEncryptionKey(bootstrapToken string) []byte

DeriveEncryptionKey derives AES-256 key from bootstrap token using Argon2id.

func NewBootstrapConfig 

func NewBootstrapConfig(nodeID string) *raft.Config

NewBootstrapConfig creates a Raft configuration optimized for fast bootstrap elections. Parameters are tuned for ephemeral bootstrap ceremony (~60 seconds): - Aggressive timeouts (500ms vs 1s default) for fast leader election - Snapshots disabled (bootstrap too short to need snapshots) - No trailing logs (ephemeral cluster, no log retention needed)

func NewBootstrapSnapshotStore 

func NewBootstrapSnapshotStore() raft.SnapshotStore

NewBootstrapSnapshotStore creates in-memory snapshot store for bootstrap Raft. WARNING: Not actually used during bootstrap (SnapshotThreshold=0 in config), but required by raft.NewRaft() interface.

func NewBootstrapStore 

func NewBootstrapStore() (raft.LogStore, raft.StableStore)

NewBootstrapStore creates in-memory LogStore and StableStore for bootstrap Raft. WARNING: State lost on restart. Only for ephemeral bootstrap ceremony (~60 seconds). After bootstrap completes, Raft shuts down and NATS JetStream handles cluster coordination.

Why in-memory only: - Bootstrap Raft runs for ~60 seconds then shuts down - No persistence needed - on restart, fresh bootstrap from scratch is simpler - Avoids fsync overhead for brief bootstrap window - Prevents stale state confusion during re-bootstrap attempts

Types

type DistributeCARequest 

type DistributeCARequest struct {
	CAs       []ca.RootCA // All three CAs (NATS, API Server, API Client)
	Timestamp time.Time   // For logging/debugging
}

DistributeCARequest is sent by the leader to distribute CAs to all followers

type DistributeCAResponse 

type DistributeCAResponse struct {
	Success bool
	Error   string // Empty if success
}

DistributeCAResponse is the response from followers after receiving CAs

type GetStatusRequest added in v1.6.1 

type GetStatusRequest struct {
	NodeID string // Requester identification
}

GetStatusRequest is sent to check if a node is bootstrapped (for late joiner detection)

type GetStatusResponse added in v1.6.1 

type GetStatusResponse struct {
	IsBootstrapped bool   // Has valid TLS certs on disk
	HasCAKeys      bool   // Can sign certificates (has CA keys in memory or NATS)
	NodeID         string // Responder identification
}

GetStatusResponse indicates the node's bootstrap status

type PSKTransport 

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

PSKTransport implements raft.Transport with AES-256-GCM encryption. All Raft RPCs are encrypted using a key derived from the bootstrap token.

func NewPSKTransport 

func NewPSKTransport(bindAddr string, bootstrapToken string, logger logr.Logger) (*PSKTransport, error)

NewPSKTransport creates a PSK-encrypted transport for Raft bootstrap.

func (*PSKTransport) AppendEntries 

func (t *PSKTransport) AppendEntries(id raft.ServerID, target raft.ServerAddress,
	args *raft.AppendEntriesRequest, resp *raft.AppendEntriesResponse) error

AppendEntries sends an AppendEntries RPC (raft.Transport interface).

func (*PSKTransport) AppendEntriesPipeline 

func (t *PSKTransport) AppendEntriesPipeline(id raft.ServerID, target raft.ServerAddress) (raft.AppendPipeline, error)

AppendEntriesPipeline is not implemented for bootstrap (raft.Transport interface). Pipelining is an optimization for high-throughput log replication, unnecessary for bootstrap.

func (*PSKTransport) Close 

func (t *PSKTransport) Close() error

Close shuts down the transport gracefully.

func (*PSKTransport) Consumer 

func (t *PSKTransport) Consumer() <-chan raft.RPC

Consumer returns channel for incoming RPCs (raft.Transport interface).

func (*PSKTransport) DecodePeer 

func (t *PSKTransport) DecodePeer(buf []byte) raft.ServerAddress

DecodePeer decodes peer from address book (raft.Transport interface).

func (*PSKTransport) EncodePeer 

func (t *PSKTransport) EncodePeer(id raft.ServerID, addr raft.ServerAddress) []byte

EncodePeer encodes peer for address book (raft.Transport interface).

func (*PSKTransport) InstallSnapshot 

func (t *PSKTransport) InstallSnapshot(id raft.ServerID, target raft.ServerAddress,
	args *raft.InstallSnapshotRequest, resp *raft.InstallSnapshotResponse,
	data io.Reader) error

InstallSnapshot sends an InstallSnapshot RPC (raft.Transport interface).

func (*PSKTransport) LocalAddr 

func (t *PSKTransport) LocalAddr() raft.ServerAddress

LocalAddr returns the local address (raft.Transport interface).

func (*PSKTransport) RequestVote 

func (t *PSKTransport) RequestVote(id raft.ServerID, target raft.ServerAddress,
	args *raft.RequestVoteRequest, resp *raft.RequestVoteResponse) error

RequestVote sends a RequestVote RPC (raft.Transport interface).

func (*PSKTransport) SendCustomRPC 

func (t *PSKTransport) SendCustomRPC(rpcType uint8, target string, req interface{}, resp interface{}) error

SendCustomRPC sends a custom RPC message to target node. Used for CA distribution outside of standard Raft consensus protocol.

func (*PSKTransport) SendGetStatus added in v1.6.1 

func (t *PSKTransport) SendGetStatus(target raft.ServerAddress, req *GetStatusRequest) (*GetStatusResponse, error)

SendGetStatus sends a GetStatus RPC to a peer to check their bootstrap status. Used by late joiners to detect if peers are already bootstrapped.

func (*PSKTransport) SendRequestCA added in v1.6.1 

func (t *PSKTransport) SendRequestCA(target raft.ServerAddress, req *RequestCARequest) (*RequestCAResponse, error)

SendRequestCA sends a RequestCA RPC to a peer to get CA certificates. Used by late joiners to get CAs from an already-bootstrapped node.

func (*PSKTransport) SendRequestCertificate 

func (t *PSKTransport) SendRequestCertificate(target raft.ServerAddress, req *RequestCertificateRequest) (*RequestCertificateResponse, error)

SendRequestCertificate sends a certificate request to the leader for signing. Uses existing sendRPC infrastructure with retry logic.

func (*PSKTransport) SetCAKeyStorage added in v1.6.1 

func (t *PSKTransport) SetCAKeyStorage(storage ca.CAKeyStorage)

SetCAKeyStorage sets the NATS KV storage for CA private keys. This enables lazy loading of CA keys for late joiner certificate signing.

func (*PSKTransport) SetCAManager 

func (t *PSKTransport) SetCAManager(mgr *ca.Manager)

SetCAManager sets the CA manager for certificate signing. Called by bootstrap coordinator after CA generation completes on the leader.

func (*PSKTransport) SetCAReceiverCallback 

func (t *PSKTransport) SetCAReceiverCallback(callback func(cas []ca.RootCA, encryptedJWTKey []byte) error)

SetCAReceiverCallback sets callback to be invoked when CAs and JWT key are received via RPC.

func (*PSKTransport) SetCertDir added in v1.6.1 

func (t *PSKTransport) SetCertDir(dir string)

SetCertDir sets the directory containing CA certificates for late joiner requests.

func (*PSKTransport) SetHeartbeatHandler 

func (t *PSKTransport) SetHeartbeatHandler(cb func(raft.RPC))

SetHeartbeatHandler sets heartbeat callback (raft.Transport interface).

func (*PSKTransport) SetJWTKeyPath added in v1.6.1 

func (t *PSKTransport) SetJWTKeyPath(path string)

SetJWTKeyPath sets the path to the encrypted JWT signing key file.

func (*PSKTransport) SetNodeID added in v1.6.1 

func (t *PSKTransport) SetNodeID(nodeID string)

SetNodeID sets the node identifier used in status responses.

func (*PSKTransport) SetStatusCallback added in v1.6.1 

func (t *PSKTransport) SetStatusCallback(callback func() GetStatusResponse)

SetStatusCallback sets the callback that returns this node's bootstrap status. Used by RPCGetStatus handler to report IsBootstrapped and HasCAKeys status.

func (*PSKTransport) TimeoutNow 

func (t *PSKTransport) TimeoutNow(id raft.ServerID, target raft.ServerAddress,
	args *raft.TimeoutNowRequest, resp *raft.TimeoutNowResponse) error

TimeoutNow is not implemented for bootstrap (raft.Transport interface).

type RaftManager 

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

RaftManager manages a bootstrap-only Raft instance for leader election during TLS bootstrap. After leader election and CA generation, this manager shuts down and NATS handles ongoing cluster coordination.

func NewRaftManager 

func NewRaftManager(nodeID string, transport raft.Transport, logger logr.Logger) *RaftManager

NewRaftManager creates a new RaftManager for bootstrap-only leader election. The transport parameter will be a PSKTransport created in Plan 02.

func (*RaftManager) IsLeader 

func (m *RaftManager) IsLeader() bool

IsLeader returns true if this node is the current Raft leader.

func (*RaftManager) LeaderAddr 

func (m *RaftManager) LeaderAddr() string

LeaderAddr returns the address of the current Raft leader. Returns empty string if no leader is elected or Raft is not started.

func (*RaftManager) Peers 

func (m *RaftManager) Peers() []string

Peers returns the list of peer addresses (Raft port) passed to Start(). Used by bootstrap manager for CA distribution.

func (*RaftManager) Shutdown 

func (m *RaftManager) Shutdown() error

Shutdown gracefully stops the Raft instance without leaving the cluster. This is critical: leaving cluster would clear peer state, breaking re-bootstrap detection. Per Phase 15 context, we do NOT call RemoveServer (preserves bootstrap state).

func (*RaftManager) Start 

func (m *RaftManager) Start(ctx context.Context, peers []string) error

Start initializes and starts the Raft instance with the given peer list. This bootstraps an ephemeral in-memory cluster for leader election. Context timeout should be at least 30 seconds to allow for election.

func (*RaftManager) Transport 

func (m *RaftManager) Transport() raft.Transport

Transport returns the Raft transport for CA distribution. Used by bootstrap manager to pass transport to CA manager.

func (*RaftManager) WaitForStableLeadership 

func (m *RaftManager) WaitForStableLeadership(ctx context.Context) error

WaitForStableLeadership blocks until this node has been the stable leader for 10 seconds. This prevents split-brain CA generation if leadership changes during the CA generation process.

Returns error if: - Raft not started - Not currently leader - Leadership lost during stability window - Context cancelled

type RequestCARequest 

type RequestCARequest struct {
	NodeID string // Requester identification
}

RequestCARequest is sent by a follower to request CAs from the leader

type RequestCAResponse 

type RequestCAResponse struct {
	CAs             []ca.RootCA // All three CAs
	EncryptedJWTKey []byte      // JWT signing key encrypted with bootstrap token
	Error           string      // Empty if success
}

RequestCAResponse is the leader's response containing CAs

type RequestCertificateRequest 

type RequestCertificateRequest struct {
	NodeID string                        // Node identifier (hostname)
	CSRs   map[ca.CertificateType][]byte // PEM-encoded CSRs (NATS, API Server, API Client)
}

RequestCertificateRequest is sent by a follower to request certificate signing

type RequestCertificateResponse 

type RequestCertificateResponse struct {
	Certificates map[ca.CertificateType][]byte // PEM-encoded signed certificates
	Error        string                        // Empty if success
}

RequestCertificateResponse is the leader's response with signed certificates

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.