cluster

Documentation

Overview

Package cluster is a generated protocol buffer package.

It is generated from these files:

cockroach/pkg/settings/cluster/cluster_version.proto

It has these top-level messages:

ClusterVersion

Index

• Constants
• Variables
• type ClusterVersion
  • func (*ClusterVersion) Descriptor() ([]byte, []int)
  • func (m *ClusterVersion) Marshal() (dAtA []byte, err error)
  • func (m *ClusterVersion) MarshalTo(dAtA []byte) (int, error)
  • func (*ClusterVersion) ProtoMessage()
  • func (m *ClusterVersion) Reset()
  • func (m *ClusterVersion) Size() (n int)
  • func (m *ClusterVersion) String() string
  • func (m *ClusterVersion) Unmarshal(dAtA []byte) error
• type ExposedClusterVersion
  • func (ecv *ExposedClusterVersion) BootstrapVersion() ClusterVersion
  • func (ecv *ExposedClusterVersion) IsActive(v roachpb.Version) bool
  • func (ecv *ExposedClusterVersion) OnChange(f func(cv ClusterVersion))
  • func (ecv *ExposedClusterVersion) Version() ClusterVersion
• type Settings
  • func MakeClusterSettings(minVersion, serverVersion roachpb.Version) *Settings
  • func MakeTestingClusterSettings() *Settings
  • func (s *Settings) InitializeVersion(cv ClusterVersion) error
  • func (s *Settings) MakeUpdater() settings.Updater

Constants

const BulkIOWriteLimiterBurst = 2 * 1024 * 1024 // 2MB

BulkIOWriteLimiterBurst is the burst for the BulkIOWriteLimiter cluster setting.

Variables

var (
	// BinaryMinimumSupportedVersion is the earliest version of data supported
	// by this binary. If this binary is started using a store that has data
	// marked with an earlier version than BinaryMinimumSupportedVersion, then
	// the binary will exit with an error.
	BinaryMinimumSupportedVersion = VersionBase

	// BinaryServerVersion is the version of this binary.
	BinaryServerVersion = VersionStatsBasedRebalancing
)

var (
	// VersionStatsBasedRebalancing is https://github.com/cockroachdb/cockroach/pull/16878.
	VersionStatsBasedRebalancing = roachpb.Version{Major: 1, Minor: 0, Unstable: 3}

	// VersionSplitHardStateBelowRaft is https://github.com/cockroachdb/cockroach/pull/17051.
	VersionSplitHardStateBelowRaft = roachpb.Version{Major: 1, Minor: 0, Unstable: 2}

	// VersionRaftLogTruncationBelowRaft is https://github.com/cockroachdb/cockroach/pull/16993.
	VersionRaftLogTruncationBelowRaft = roachpb.Version{Major: 1, Minor: 0, Unstable: 1}

	// VersionBase corresponds to any binary older than 1.0-1,
	// though these binaries won't know anything about the mechanism in which
	// this version is used.
	VersionBase = roachpb.Version{Major: 1}
)

List all historical versions here in reverse chronological order, with comments describing what backwards-incompatible features were introduced.

NB: when adding a version, don't forget to bump ServerVersion above (and perhaps MinimumSupportedVersion, if necessary).

var (
	ErrInvalidLengthClusterVersion = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowClusterVersion   = fmt.Errorf("proto: integer overflow")
)

var BulkIOWriteLimit = settings.RegisterByteSizeSetting(
	"kv.bulk_io_write.max_rate",
	"the rate limit (bytes/sec) to use for writes to disk on behalf of bulk io ops",
	math.MaxInt64,
)

BulkIOWriteLimit is defined here because it is used by BulkIOWriteLimiter.

Types

type ClusterVersion

type ClusterVersion struct {
	// The minimum_version required for any node to support. This
	// value must monotonically increase.
	MinimumVersion cockroach_roachpb.Version `protobuf:"bytes,1,opt,name=minimum_version,json=minimumVersion" json:"minimum_version"`
	// The version of functionality in use in the cluster. Unlike
	// minimum_version, use_version may be downgraded, which will
	// disable functionality requiring a higher version. However,
	// some functionality, once in use, can not be discontinued.
	// Support for that functionality is guaranteed by the ratchet
	// of minimum_version.
	UseVersion cockroach_roachpb.Version `protobuf:"bytes,2,opt,name=use_version,json=useVersion" json:"use_version"`
}

func (*ClusterVersion) Descriptor

func (*ClusterVersion) Descriptor() ([]byte, []int)

func (*ClusterVersion) Marshal

func (m *ClusterVersion) Marshal() (dAtA []byte, err error)

func (*ClusterVersion) MarshalTo

func (m *ClusterVersion) MarshalTo(dAtA []byte) (int, error)

func (*ClusterVersion) ProtoMessage

func (*ClusterVersion) ProtoMessage()

func (*ClusterVersion) Reset

func (m *ClusterVersion) Reset()

func (*ClusterVersion) Size

func (m *ClusterVersion) Size() (n int)

func (*ClusterVersion) String

func (m *ClusterVersion) String() string

func (*ClusterVersion) Unmarshal

func (m *ClusterVersion) Unmarshal(dAtA []byte) error

type ExposedClusterVersion

type ExposedClusterVersion struct {
	MinSupportedVersion roachpb.Version
	ServerVersion       roachpb.Version
	// contains filtered or unexported fields
}

An ExposedClusterVersion exposes a cluster-wide minimum version which is assumed to be supported by all nodes. This in turn allows features which are incompatible with older versions to be used safely.

func (*ExposedClusterVersion) BootstrapVersion

func (ecv *ExposedClusterVersion) BootstrapVersion() ClusterVersion

BootstrapVersion returns the version a newly initialized cluster should have.

func (*ExposedClusterVersion) IsActive

func (ecv *ExposedClusterVersion) IsActive(v roachpb.Version) bool

IsActive returns true if the features of the supplied version are active at the running version.

func (*ExposedClusterVersion) OnChange

func (ecv *ExposedClusterVersion) OnChange(f func(cv ClusterVersion))

OnChange registers (a single) callback that will be invoked whenever the cluster version changes. The new cluster version will only become "visible" after the callback has returned.

The callback can be set at most once.

func (*ExposedClusterVersion) Version

func (ecv *ExposedClusterVersion) Version() ClusterVersion

Version returns the minimum cluster version the caller may assume is in effect. It must not be called until the setting has been initialized.

type Settings

type Settings struct {
	SV settings.Values

	// Manual defaults to false. If set, lets this ClusterSetting's MakeUpdater
	// method return a dummy updater that simply throws away all values. This is
	// for use in tests for which manual control is desired.
	Manual atomic.Value // bool

	Version ExposedClusterVersion

	Tracer             *tracing.Tracer
	BulkIOWriteLimiter *rate.Limiter

	Initialized bool
}

Settings is the collection of cluster settings. For a running CockroachDB node, there is a single instance of ClusterSetting which is shared across all of its components.

The Version setting deserves an individual explanantion. During the node startup sequence, an initial version (persisted to the engines) is read and passed to InitializeVersion(). It is only after that that the Version field of this struct is ready for use (i.e. Version() and IsActive() can be called). In turn, the node usually registers itself as a callback to be notified of any further updates to the setting, which are then persisted.

This dance is necessary because we cannot determine a safe default value for the version setting without looking at what's been persisted: The setting specifies the minimum binary version we have to expect to be in a mixed cluster with. We can't assume this binary's MinimumSupportedVersion as we could've started up earlier and enabled features that are not actually compatible with that version; we can't assume it's our binary's ServerVersion as that would enable features that may trip up older versions running in the same cluster. Hence, only once we get word of the "safe" version to use can we allow moving parts that actually need to know what's going on.

Additionally, whenever the version changes, we want to persist that update to wherever the caller to InitializeVersion() got the initial version from (typically a collection of `engine.Engine`s), which the caller will do by registering itself via `(*Setting).Version.OnChange()`, which is invoked *before* exposing the new version to callers of `IsActive()` and `Version()`.

For testing or one-off situations in which a ClusterSetting is needed, but cluster settings don't play a crucial role, MakeTestingClusterSetting() is provided; it is pre-initialized to the binary's ServerVersion.

func MakeClusterSettings

func MakeClusterSettings(minVersion, serverVersion roachpb.Version) *Settings

MakeClusterSettings makes a new ClusterSettings object for the given minimum supported and server version, respectively.

func MakeTestingClusterSettings

func MakeTestingClusterSettings() *Settings

MakeTestingClusterSettings returns a Settings object that has had its version initialized to BootstrapVersion().

func (*Settings) InitializeVersion

func (s *Settings) InitializeVersion(cv ClusterVersion) error

InitializeVersion initializes the Version field of this setting. Before this method has been called, usage of the Version field is illegal and leads to a fatal error.

func (*Settings) MakeUpdater

func (s *Settings) MakeUpdater() settings.Updater

MakeUpdater returns a new Updater, pre-alloced to the registry size. Note that if the Setting has the Manual flag set, this Updater simply ignores all updates.