curator

Documentation

Overview

package curator implements the Curator, a service responsible for management of the Metropolis cluster that it is running on.

The Curator is implemented as a leader-elected service. Instances of the service are running colocated with all nodes that run a consensus (etcd) server.

Each instance listens on all network interfaces, for requests both from the code running on the same node, for traffic from other nodes (eg. ones that do not run an instance of the Curator) and from external users.

The curator leader keeps its state fully in etcd. Followers forward all requests to the active leader.

This file contains common implementation related to filtering of protobuf messages with Common Expression Language.

Index

• Constants
• func BootstrapNodeFinish(ctx context.Context, etcd client.Namespaced, node *Node, ownerKey []byte, ...) (caCertBytes, nodeCertBytes []byte, err error)
• type Cluster
  • func ClusterConfigurationFromInitial(icc *cpb.ClusterConfiguration) (*Cluster, error)
  • func DefaultClusterConfiguration() *Cluster
  • func (c *Cluster) NodeShouldUseTPM(available bool) (bool, error)
  • func (c *Cluster) NodeStorageSecurity() (security cpb.NodeStorageSecurity, err error)
  • func (c *Cluster) NodeTPMUsage(have bool) (usage cpb.NodeTPMUsage, err error)
  • func (c *Cluster) ValidateNodeStorage(ns cpb.NodeStorageSecurity) error
• type Config
• type Node
  • func NewNodeForBootstrap(cuk, pubkey, jpub []byte, tpmUsage cpb.NodeTPMUsage) Node
  • func (n *Node) DisableConsensusMember()
  • func (n *Node) DisableKubernetesController()
  • func (n *Node) DisableKubernetesWorker()
  • func (n *Node) EnableConsensusMember(jc *consensus.JoinCluster)
  • func (n *Node) EnableKubernetesController()
  • func (n *Node) EnableKubernetesWorker()
  • func (n *Node) ID() string
  • func (n *Node) KubernetesController() *NodeRoleKubernetesController
  • func (n *Node) KubernetesWorker() *NodeRoleKubernetesWorker
  • func (n *Node) String() string
• type NodeRoleConsensusMember
• type NodeRoleConsensusMemberPeer
• type NodeRoleKubernetesController
• type NodeRoleKubernetesWorker
• type Service
  • func New(cfg Config) *Service
  • func (s *Service) Run(ctx context.Context) error

Constants

const (

	// HeartbeatPeriod is the duration between consecutive heartbeat update
	// messages sent by the node.
	HeartbeatInterval = time.Second * 5

	// HeartbeatTimeout is the duration after which a node is considered to be
	// timing out, given no recent heartbeat updates were received by the leader.
	HeartbeatTimeout = HeartbeatInterval * 2
)

Functions

func BootstrapNodeFinish

func BootstrapNodeFinish(ctx context.Context, etcd client.Namespaced, node *Node, ownerKey []byte, cluster *Cluster) (caCertBytes, nodeCertBytes []byte, err error)

BootstrapFinish saves the given Node and initial cluster owner pubkey into etcd, without regard for any other cluster state and directly using a given etcd client.

This is ran by the cluster bootstrap workflow to finish bootstrapping a cluster - afterwards, this cluster will be ready to serve.

This must only be used by the cluster bootstrap logic. It is idempotent, thus can be called repeatedly in case of intermittent failures in the bootstrap logic.

Types

type Cluster

type Cluster struct {
	TPMMode               cpb.ClusterConfiguration_TPMMode
	StorageSecurityPolicy cpb.ClusterConfiguration_StorageSecurityPolicy
}

Cluster is the cluster's configuration, as (un)marshaled to/from common.ClusterConfiguration.

func ClusterConfigurationFromInitial

func ClusterConfigurationFromInitial(icc *cpb.ClusterConfiguration) (*Cluster, error)

ClusterConfigurationFromInitial converts a user-provided initial cluster configuration proto into a Cluster, checking that the provided values are valid.

func DefaultClusterConfiguration

func DefaultClusterConfiguration() *Cluster

DefaultClusterConfiguration is the default cluster configuration for a newly bootstrapped cluster if no initial cluster configuration was specified by the user.

func (*Cluster) NodeShouldUseTPM

func (c *Cluster) NodeShouldUseTPM(available bool) (bool, error)

NodeShouldUseTPM returns whether a node should use a TPM or not for this Cluster and a given node's TPM availability.

A user-facing error is returned if the combination of local cluster policy and node TPM availability is invalid.

func (*Cluster) NodeStorageSecurity

func (c *Cluster) NodeStorageSecurity() (security cpb.NodeStorageSecurity, err error)

NodeStorageSecurity returns the recommended NodeStorageSecurity for nodes joining the cluster.

func (*Cluster) NodeTPMUsage

func (c *Cluster) NodeTPMUsage(have bool) (usage cpb.NodeTPMUsage, err error)

NodeTPMUsage returns the NodeTPMUsage (whether a node should use a TPM or not plus information whether it has a TPM in the first place) for this Cluster and a given node's TPM availability.

A user-facing error is returned if the combination of local cluster policy and node TPM availability is invalid.

func (*Cluster) ValidateNodeStorage

func (c *Cluster) ValidateNodeStorage(ns cpb.NodeStorageSecurity) error

ValidateNodeStorage checks the given NodeStorageSecurity and returns a gRPC status if the security setting is not compliant with the cluster node storage policy.

type Config

type Config struct {
	// NodeCredentials are the identity credentials for the node that is running
	// this curator.
	NodeCredentials *identity.NodeCredentials
	Consensus       consensus.ServiceHandle
	// LeaderTTL is the timeout on the lease used to perform leader election.
	// Any active leader must continue updating its lease at least this often,
	// or the lease (and leadership) will be lost.
	// Lower values allow for faster failovers. Higher values allow for higher
	// resiliency against short network partitions.
	// A value less or equal to zero will default to 60 seconds.
	LeaderTTL time.Duration
}

Config is the configuration of the curator.

type Node

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

Node is a Metropolis cluster member. A node is a virtual or physical machine running Metropolis. This object represents a node only as part of a cluster. A machine running Metropolis that is not yet (attempting to be) part of a cluster is not considered a Node.

This object is used internally within the curator code. Curator clients do not have access to this object and instead rely on protobuf representations of objects from the Curator gRPC API. An exception is the cluster bootstrap code which needs to bring up a new curator from scratch alongside the rest of the cluster.

func NewNodeForBootstrap

func NewNodeForBootstrap(cuk, pubkey, jpub []byte, tpmUsage cpb.NodeTPMUsage) Node

NewNodeForBootstrap creates a brand new node without regard for any other cluster state.

This can only be used by the cluster bootstrap logic.

func (*Node) DisableConsensusMember

func (n *Node) DisableConsensusMember()

func (*Node) DisableKubernetesController

func (n *Node) DisableKubernetesController()

func (*Node) DisableKubernetesWorker

func (n *Node) DisableKubernetesWorker()

func (*Node) EnableConsensusMember

func (n *Node) EnableConsensusMember(jc *consensus.JoinCluster)

func (*Node) EnableKubernetesController

func (n *Node) EnableKubernetesController()

func (*Node) EnableKubernetesWorker

func (n *Node) EnableKubernetesWorker()

func (*Node) ID

func (n *Node) ID() string

ID returns the name of this node. See NodeID for more information.

func (*Node) KubernetesController

func (n *Node) KubernetesController() *NodeRoleKubernetesController

func (*Node) KubernetesWorker

func (n *Node) KubernetesWorker() *NodeRoleKubernetesWorker

KubernetesWorker returns a copy of the NodeRoleKubernetesWorker struct if the Node is a kubernetes worker, otherwise nil.

func (*Node) String

func (n *Node) String() string

type NodeRoleConsensusMember

type NodeRoleConsensusMember struct {
	// CACertificate, PeerCertificate are the X509 certificates to be used by the
	// node's etcd member to serve peer traffic.
	CACertificate, PeerCertificate *x509.Certificate
	// CRL is an initial certificate revocation list that the etcd member should
	// start with.
	//
	// TODO(q3k): don't store this in etcd like that, instead have the node retrieve
	// an initial CRL using gRPC/Curator.Watch.
	CRL *pki.CRL

	// Peers are a list of etcd members that the node's etcd member should attempt
	// to connect to.
	//
	// TODO(q3k): don't store this in etcd like that, instead have this be
	// dynamically generated at time of retrieval.
	Peers []NodeRoleConsensusMemberPeer
}

NodeRoleConsensusMember defines that the Node should be running a consensus/etcd instance.

type NodeRoleConsensusMemberPeer

type NodeRoleConsensusMemberPeer struct {
	// Name is the name of the etcd member, equal to the Metropolis node's ID that
	// the etcd member is running on.
	Name string
	// URL is a https://host:port string that can be passed to etcd on startup.
	URL string
}

NodeRoleConsensusMemberPeer is a name/URL pair pointing to an etcd member's peer listener.

type NodeRoleKubernetesController

type NodeRoleKubernetesController struct {
}

NodeRoleKubernetesController defines that the Node should be running the Kubernetes control plane.

type NodeRoleKubernetesWorker

type NodeRoleKubernetesWorker struct {
}

NodeRoleKubernetesWorker defines that the Node should be running the Kubernetes data plane.

type Service

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

Service is the Curator service. See the package-level documentation for more information.

func New

func New(cfg Config) *Service

New creates a new curator Service.

func (*Service) Run

func (s *Service) Run(ctx context.Context) error