moco

README

MOCO

MOCO is a Kubernetes operator for MySQL. Its primary function is to manage a cluster of MySQL using binlog-based, semi-synchronous replication.

MOCO is designed for the following properties:

• Durability
  • Do not lose any data under a given degree of faults.
• Availability
  • Keep the MySQL cluster available under a given degree of faults.
• Business Continuity
  • Perform a quick recovery if some failure is occurred.

Features

TBD

Supported MySQL versions

>=8.0.20

Documentation

docs directory contains documents about designs and specifications.

Docker images

Docker images are available on Quay.io

License

MOCO is licensed under MIT license.

Documentation

Index

• Constants
• Variables
• func GetHost(cluster *mocov1alpha1.MySQLCluster, index int) string
• func GetPassword(ctx context.Context, cluster *mocov1alpha1.MySQLCluster, c client.Client, ...) (string, error)
• func GetSecretNameForController(cluster *mocov1alpha1.MySQLCluster) (string, string)
• func UniqueName(cluster *mocov1alpha1.MySQLCluster) string
• type MOCOEvent
  • func (e MOCOEvent) FillVariables(val ...interface{}) *MOCOEvent
• type OperationPhase

Constants

const (
	// RootUser is the name of root user in the MySQL context.
	RootUser = "root"

	// OperatorUser is a name of MOCO operator user in the MySQL context.
	OperatorUser = "moco"

	// OperatorAdminUser is a name of MOCO operator-admin user in the MySQL context.
	// This user is a super user especially for creating and granting privileges to other users.
	OperatorAdminUser = "moco-admin"

	// ReplicationUser is a name of MOCO replicator user in the MySQL context.
	ReplicationUser = "moco-repl"

	// CloneDonorUser is a name of MOCO clone-donor user in the MySQL context.
	CloneDonorUser = "moco-clone-donor"

	// MiscUser is a name of MOCO misc user in the MySQL context.
	MiscUser = "moco-misc"

	// ReadOnlyUser is a name of MOCO predefined human user with wide read-only rights used for manual operation.
	ReadOnlyUser = "moco-readonly"

	// WritableUser is a name of MOCO predefined human user with wide read/write rights used for manual operation.
	WritableUser = "moco-writable"
)

const (
	// MySQLDataPath is a path for MySQL data dir.
	MySQLDataPath = "/var/lib/mysql"

	// MySQLConfPath is a path for MySQL conf dir.
	MySQLConfPath = "/etc/mysql"

	// MySQLConfName is a filename for MySQL conf.
	MySQLConfName = "my.cnf"

	// VarRunPath is a path for variable files which concerns MySQLd.
	VarRunPath = "/var/run/mysqld"

	// VarLogPath is a path for /var/log/mysql.
	VarLogPath = "/var/log/mysql"

	// MySQLErrorLogName is a filename of error log for MySQL.
	MySQLErrorLogName = "mysql.err"

	// MySQLSlowLogName is a filename of slow query log for MySQL.
	MySQLSlowLogName = "mysql.slow"

	// TmpPath is a path for /tmp.
	TmpPath = "/tmp"

	// MyCnfSecretPath is the path for my.cnf formated credentials for CLI
	MyCnfSecretPath = "/mysql-credentials"

	// MySQLConfTemplatePath is
	MySQLConfTemplatePath = "/etc/mysql_template"

	// DonorPasswordPath is the path to donor user passsword file
	DonorPasswordPath = MySQLDataPath + "/donor-password"

	// MiscPasswordPath is the path to misc user passsword file
	MiscPasswordPath = MySQLDataPath + "/misc-password"

	// ReplicationSourceSecretPath is the path to replication source secret file
	ReplicationSourceSecretPath = MySQLDataPath + "/replication-source-secret"

	// InnoDBBufferPoolRatioPercent is the ratio of InnoDB buffer pool size to resource.limits.memory or resource.requests.memory
	// Note that the pool size doesn't set to lower than 128MiB, which is the default innodb_buffer_pool_size value
	InnoDBBufferPoolRatioPercent = 70
)

const (
	// MySQLPort is a port number for MySQL
	MySQLPort = 3306

	// MySQLAdminPort is a port number for MySQL Admin
	MySQLAdminPort = 33062

	// MySQLXPort is a port number for MySQL XProtocol
	MySQLXPort = 33060
)

const (
	// AgentPort is a port number for agent container
	AgentPort = 9080

	// AgentTokenEnvName is a name of the environment variable of agent token.
	AgentTokenEnvName = "MOCO_AGENT_TOKEN"

	// AgentTokenParam is a name of the param of agent token.
	AgentTokenParam = "token"
)

const (
	// PodNameEnvName is a name of the environment variable of a pod name.
	PodNameEnvName = "POD_NAME"

	// PodNameFlag is a name of the flag of a pod name.
	PodNameFlag = "pod-name"

	// PodNamespaceEnvName is a name of the environment variable of a pod namespace.
	PodNamespaceEnvName = "POD_NAMESPACE"

	// PodNamespaceFlag is a name of the flag of a pod namespace.
	PodNamespaceFlag = "pod-namespace"

	// PodIPEnvName is a name of the environment variable of a pod IP.
	PodIPEnvName = "POD_IP"

	// PodNameFlag is a name of the flag of a pod IP.
	PodIPFlag = "pod-ip"

	// NodeNameEnvName is a name of the environment variable of a node name where the pod runs.
	NodeNameEnvName = "NODE_NAME"

	// NodeNameFlag is a name of the flag of a node name where the pod runs.
	NodeNameFlag = "node-name"

	// RootPasswordEnvName is a name of the environment variable of a root password.
	RootPasswordEnvName = "ROOT_PASSWORD"

	// OperatorPasswordEnvName is a name of the environment variable of a password for both operator and operator-admin.
	OperatorPasswordEnvName = "OPERATOR_PASSWORD"

	// ReplicationPasswordEnvName is a name of the environment variable of a password for replication user.
	ReplicationPasswordEnvName = "REPLICATION_PASSWORD"

	// ClonePasswordEnvName is a name of the environment variable of a password for donor user.
	ClonePasswordEnvName = "CLONE_DONOR_PASSWORD"

	// MiscPasswordEnvName is a name of the environment variable of a password for the misc user.
	MiscPasswordEnvName = "MISC_PASSWORD"

	// ReadOnlyPasswordEnvName is a name of the environment variable of a password for moco-readonly.
	ReadOnlyPasswordEnvName = "READONLY_PASSWORD"

	// WritablePasswordEnvName is a name of the environment variable of a password for moco-writable.
	WritablePasswordEnvName = "WRITABLE_PASSWORD"
)

env names must correspond to options in entrypoint/init.go

const (
	// RootPasswordKey is a Secret key for root password.
	RootPasswordKey = "ROOT_PASSWORD"

	// OperatorPasswordKey is a Secret key for operator password.
	OperatorPasswordKey = "OPERATOR_PASSWORD"

	// ReplicationPasswordKey is a Secret key for operator replication password.
	ReplicationPasswordKey = "REPLICATION_PASSWORD"

	// CloneDonorPasswordKey is a Secret key for operator donor password.
	CloneDonorPasswordKey = "CLONE_DONOR_PASSWORD"

	// MiscPasswordKey is a Secret key for misc user password.
	MiscPasswordKey = "MISC_PASSWORD"

	// ReadOnlyPasswordKey is a Secret key for moco-readonly user password.
	ReadOnlyPasswordKey = "READONLY_PASSWORD"

	// ReadOnlyPasswordKey is a Secret key for moco-writable user password.
	WritablePasswordKey = "WRITABLE_PASSWORD"

	// RootMyCnfKey is the username and password of root formated as my.cnf
	RootMyCnfKey = RootUser + "-my.cnf"

	// ReadOnlyMyCnfKey is the username and password of moco-readonly formated as my.cnf
	ReadOnlyMyCnfKey = ReadOnlyUser + "-my.cnf"

	// WritableMyCnfKey is the username and password or moco-writable formated as my.cnf
	WritableMyCnfKey = WritableUser + "-my.cnf"

	// ReplicationSourcePrimaryHostKey etc. are Secret key for replication source secret
	ReplicationSourcePrimaryHostKey            = "PRIMARY_HOST"
	ReplicationSourcePrimaryUserKey            = "PRIMARY_USER"
	ReplicationSourcePrimaryPasswordKey        = "PRIMARY_PASSWORD"
	ReplicationSourcePrimaryPortKey            = "PRIMARY_PORT"
	ReplicationSourceCloneUserKey              = "CLONE_USER"
	ReplicationSourceClonePasswordKey          = "CLONE_PASSWORD"
	ReplicationSourceInitAfterCloneUserKey     = "INIT_AFTER_CLONE_USER"
	ReplicationSourceInitAfterClonePasswordKey = "INIT_AFTER_CLONE_PASSWORD"
)

const (
	MyName       = "moco"
	AppName      = "moco-mysql"
	ClusterKey   = "app.kubernetes.io/instance"
	ManagedByKey = "app.kubernetes.io/managed-by"
	AppNameKey   = "app.kubernetes.io/name"

	RoleKey     = "moco.cybozu.com/role"
	PrimaryRole = "primary"
	ReplicaRole = "replica"

	MysqldContainerName = "mysqld"
)

const (
	CloneParamDonorHostName = "donor_hostname"
	CloneParamDonorPort     = "donor_port"
	CloneParamExternal      = "external"
)

const (
	ReplicaRunConnect     = "Yes"
	ReplicaNotRun         = "No"
	ReplicaRunNotConnect  = "Connecting"
	CloneStatusNotStarted = "Not Started"
	CloneStatusInProgress = "In Progress"
	CloneStatusCompleted  = "Completed"
	CloneStatusFailed     = "Failed"
)

const (
	PhaseInitializing    = OperationPhase("initializing")
	PhaseWaitRelayLog    = OperationPhase("wait-relay-log")
	PhaseRestoreInstance = OperationPhase("restoring-instance")
	PhaseCompleted       = OperationPhase("completed")
)

const (
	// InitializedClusterIndexField is an index name for Initialized MySQL Clusters
	InitializedClusterIndexField = ".status.conditions.type.initialized"
)

const (
	// Version is the MOCO version
	Version = "0.3.1"
)

Variables

var (
	// ErrConstraintsViolation is returned when the constraints violation occurs
	ErrConstraintsViolation = errors.New("constraints violation occurs")
	// ErrConstraintsRecovered is returned when the constrains recovered but once violated
	ErrConstraintsRecovered = errors.New("constrains recovered but once violated")
	// ErrCannotCompareGTIDs is returned if GTID comparison returns error
	ErrCannotCompareGTIDs = errors.New("cannot compare gtids")
)

var (
	EventInitializationSucceeded = MOCOEvent{
		corev1.EventTypeNormal,
		"Initialization Succeeded",
		"Initialization phase finished successfully.",
	}
	EventInitializationFailed = MOCOEvent{
		corev1.EventTypeWarning,
		"Initialization Failed",
		"Initialization phase failed. err=%s",
	}
	EventWaitingAllInstancesAvailable = MOCOEvent{
		corev1.EventTypeNormal,
		"Waiting All Instances Available",
		"Waiting for all instances to become connected from MOCO. unavailable=%v",
	}
	EventViolationOccurred = MOCOEvent{
		corev1.EventTypeWarning,
		"Violation Occurred",
		"Constraint violation occurred. Please resolve via manual operation. err=%v",
	}
	EventWatingRelayLogExecution = MOCOEvent{
		corev1.EventTypeNormal,
		"Waiting Relay Log Execution",
		"Waiting relay log execution on replica instance(s).",
	}
	EventWaitingCloneFromExternal = MOCOEvent{
		corev1.EventTypeNormal,
		"Waiting External Clone",
		"Waiting for the intermediate primary to clone from the external primary",
	}
	EventRestoringReplicaInstances = MOCOEvent{
		corev1.EventTypeNormal,
		"Restoring Replica Instance(s)",
		"Restoring replica instance(s) by cloning with primary instance.",
	}
	EventPrimaryChanged = MOCOEvent{
		corev1.EventTypeNormal,
		"Primary Changed",
		"Primary instance was changed from %s to %s because of failover or switchover.",
	}
	EventIntermediatePrimaryConfigured = MOCOEvent{
		corev1.EventTypeNormal, "Intermediate Primary Configured",
		"Intermediate primary instance was configured with host=%s",
	}
	EventIntermediatePrimaryUnset = MOCOEvent{
		corev1.EventTypeNormal, "Intermediate Primary Unset",
		"Intermediate primary instance was unset.",
	}
	EventClusteringCompletedSynced = MOCOEvent{
		corev1.EventTypeNormal,
		"Clustering Completed and Synced",
		"Clustering are completed. All instances are synced.",
	}
	EventClusteringCompletedNotSynced = MOCOEvent{
		corev1.EventTypeWarning,
		"Clustering Completed but Not Synced",
		"Clustering are completed. Some instance(s) are not synced. out_of_sync=%v",
	}
)

var AllOperationPhases = []OperationPhase{
	PhaseInitializing,
	PhaseWaitRelayLog,
	PhaseRestoreInstance,
	PhaseCompleted,
}

Functions

func GetHost

func GetHost(cluster *mocov1alpha1.MySQLCluster, index int) string

GetHost returns host url of the given cluster and instance

func GetPassword

func GetPassword(ctx context.Context, cluster *mocov1alpha1.MySQLCluster, c client.Client, passwordKey string) (string, error)

GetPassword gets a password from secret

func GetSecretNameForController

func GetSecretNameForController(cluster *mocov1alpha1.MySQLCluster) (string, string)

GetSecretNameForController returns the namespace and Secret name of the cluster

func UniqueName

func UniqueName(cluster *mocov1alpha1.MySQLCluster) string

UniqueName returns unique name of the cluster

Types

type MOCOEvent

type MOCOEvent struct {
	Type    string
	Reason  string
	Message string
}

func (MOCOEvent) FillVariables

func (e MOCOEvent) FillVariables(val ...interface{}) *MOCOEvent

type OperationPhase

type OperationPhase string