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.18 and 8.0.20

Supported Kubernetes version

1.20 and 1.19

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 GetMyCnfSecretName(clusterName string) string
• func GetPassword(ctx context.Context, cluster *mocov1alpha1.MySQLCluster, c client.Client, ...) (string, error)
• func GetPodName(clusterName string, index int) string
• func GetRootPasswordSecretName(clusterName string) string
• func GetSecretNameForController(cluster *mocov1alpha1.MySQLCluster) (string, string)
• func GetServiceAccountName(clusterName 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 (
	// MOCOBinaryPath is a path for MOCO's binary dir.
	MOCOBinaryPath = "/moco-bin"

	// 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"

	// MySQLFilesPath is a path for /var/lib/mysql-files.
	MySQLFilesPath = "/var/lib/mysql-files"

	// 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.4.0"
)

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 GetMyCnfSecretName

func GetMyCnfSecretName(clusterName string) string

GetMyCnfSecretName returns the name of the myCnf secret.

func GetPassword

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

GetPassword gets a password from secret

func GetPodName

func GetPodName(clusterName string, index int) string

GetPodName returns the pod name in the cluster.

func GetRootPasswordSecretName

func GetRootPasswordSecretName(clusterName string) string

GetRootPasswordSecretName returns the name of the root password secret.

func GetSecretNameForController

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

GetSecretNameForController returns the namespace and Secret name of the cluster

func GetServiceAccountName

func GetServiceAccountName(clusterName string) string

GetServiceAccountName returns the name of service account for mysql pod.

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