metropolis/proto/common/common.proto - monogon - Gitiles

 // Copyright 2020 The Monogon Project Authors.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 syntax = "proto3";
 package metropolis.proto.common;
 option go_package = "source.monogon.dev/metropolis/proto/common";

 import "google/protobuf/timestamp.proto";

 // NodeRoles are the possible roles that a Metropolis Node should run within the
 // cluster. These are configured by the cluster and can be retrieved through the
 // Curator.
 //
 // Fields contained within each individual are publicly available, so while they
 // can be used to carry required data to start up services for a given role,
 // this must not be confidential/private data.
 message NodeRoles {
     message KubernetesWorker {
     }
     message ConsensusMember {
         // ca_certificate is a DER-encoded x509 certificate of the etcd
         // cluster's CA. The member must use this certificate to verify the
         // identity of the cluster it's connecting to.
         bytes ca_certificate = 1;
         // pper_certificate is a DER-encoded x509 certificate of this node's
         // etcd peer listener. The member must serve member traffic using this
         // certificate. The private key corresponding to this certificate is
         // the same as the node's primary private keypair.
         bytes peer_certificate = 2;
         // initial_crl is a certificate revocation list that the etcd member
         // should be started with. After startup, the member will maintain its
         // own CRL by updating it from its primary storage location, and etcd
         // value.
         //
         // TODO(q3k): don't pass this here, instead pass this over an etcd
         // watcher and curator.Watch.
         bytes initial_crl = 3;
         message Peer {
             string Name = 1;
             string URL = 2;
         }
         repeated Peer peers = 4;
     }
     KubernetesWorker kubernetes_worker = 1;
     ConsensusMember consensus_member = 2;
 }

 // NodeState is the state of a Metropolis node from the point of view of the
 // cluster it is a part of (or intending to be a part of).
 enum NodeState {
     NODE_STATE_INVALID = 0;

     // NEW: the node has established a first contact with the cluster and
     // intends to register into it. The node's identity has not been verified
     // and no hardware attestation of the new node was performed.
     // The node has generated a CUK/NUK and set up storage encrypted with the
     // combination of both keys.
     // The node has generated a private/public keypair, and that keypair has
     // been used to contact the already running Cluster.
     NODE_STATE_NEW = 1;
     // STANDBY: the node has successfully passed identity and hardware
     // attestation checks as defined by the cluster policy. The node still isn't
     // part of the cluster, as it itself might perform checks against the
     // running Cluster.
     NODE_STATE_STANDBY = 2;
     // UP: the node has passed all preconditions for STANDBY and has also
     // performed a commit into the cluster by exchanging its CUK for a
     // certificate issued by the cluster.
     // The node is now ready to serve, and its certificate can be used to
     // authenticate its identity cryptographically.
     NODE_STATE_UP = 3;
     // DISOWNED: the node has been rejected or decommissioned by the cluster.
     // Any further contact from the node to the cluster will be rejected.
     NODE_STATE_DISOWNED = 4;
 };

 // ClusterState is the state of the cluster from the point of view of a node.
 // Different subsystems can watch this state and depend on it for behaviour
 // (eg. start serving when HOME, maybe self-fence on SPLIT, etc.).
 enum ClusterState {
     CLUSTER_STATE_INVALID = 0;

     // UNKNOWN: the node has not yet determined the existence of a cluster it
     // should join or start. This is a transient, initial state that should only
     // manifest during boot.
     CLUSTER_STATE_UNKNOWN = 1;
     // FOREIGN: the node is attempting to register into an already existing
     // cluster with which it managed to make preliminary contact, but which the
     // cluster has not yet fully productionized (eg. the node is still being
     // hardware attested, or the operator needs to confirm the
     // registration of this node).
     CLUSTER_STATE_FOREIGN = 2;
     // TRUSTED: the node is attempting to register into an already registered
     // cluster, and has been trusted by it. The node is now attempting to fully
     // commit to registering into the cluster.
     CLUSTER_STATE_TRUSTED = 3;
     // HOME: the node is part of this cluster. This is the bulk of time in which
     // this node will spend its time.
     CLUSTER_STATE_HOME = 4;
     // DISOWNING: the node has been disowned (ie., removed) by the cluster, and
     // that it will not be ever part of any cluster again, and  that it will be
     // decommissioned by the operator.
     CLUSTER_STATE_DISOWNING = 5;
     // SPLIT:the node would usually be Home in a cluster, but has been split
     // from the consensus of the cluster. This can happen for nodes running
     // consensus when consensus is lost (eg. when there is no quorum or this
     // node has been netsplit), and for other nodes if they have lost network
     // connectivity to the consensus nodes. Clients should make their own
     // decision what action to perform in this state, depending on the level of
     // consistency required and whether it makes sense for the node to fence its
     // services off.
     CLUSTER_STATE_SPLIT = 6;
 }

 // NodeStatus contains all fields self-reported by nodes. This data is
 // inherently less trusted than other data available about a node, as it can be
 // updated to any value by each node individually, including compromised nodes.
 message NodeStatus {
     // external_address is the IP address that the node expects management,
     // cluster and user traffic to arrive at (ie. the address on which it is
     // listening for gRPC, and role-specific services like etcd and
     // Kubernetes).
     string external_address = 1;
     // running_curator contains information about the curator service running
     // on this node, or is nil if the service is not running.
     message RunningCurator {
         // port is the TCP port on which the curator is listening.
         int32 port = 1;
     }
     RunningCurator running_curator = 3;
     // timestamp is an epoch number associated with the last status update.
     // It's set with a nanosecond granularity.
     google.protobuf.Timestamp timestamp = 2;
 }

 // The Cluster Directory is information about the network addressing of nodes
 // in a cluster. It is a serialized snapshot of some of the state within the
 // etcd cluster, and can be used by external processes (like a node Registering
 // into the cluster) to know how to reach this cluster over the network. It can
 // be thought of as a phonebook, or a static name/address configuration that
 // could live in /etc/hosts.
 //
 // The directory explicitly doesn't carry any information about the cluster's
 // identity or security - these should be configured and checked by higher
 // level configuration and processes. The directory can be stored and
 // transmitted in cleartext and without an integrity checks (like saved to the
 // EFI system partition across reboots) and any malicious change to it will
 // cause no more than a denial of service against the consumer of this
 // directory. This is because all nodes contacted must present a valid cluster
 // identity/certificate before they are trusted by the consumers of this
 // directory.
 message ClusterDirectory {
     message Node {
         bytes public_key = 1;
         message Address {
             string host = 1;
         };
         repeated Address addresses = 2;
     };
     repeated Node nodes = 1;
 }
	// Copyright 2020 The Monogon Project Authors.
	//
	// SPDX-License-Identifier: Apache-2.0
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	syntax = "proto3";
	package metropolis.proto.common;
	option go_package = "source.monogon.dev/metropolis/proto/common";

	import "google/protobuf/timestamp.proto";

	// NodeRoles are the possible roles that a Metropolis Node should run within the
	// cluster. These are configured by the cluster and can be retrieved through the
	// Curator.
	//
	// Fields contained within each individual are publicly available, so while they
	// can be used to carry required data to start up services for a given role,
	// this must not be confidential/private data.
	message NodeRoles {
	message KubernetesWorker {
	}
	message ConsensusMember {
	// ca_certificate is a DER-encoded x509 certificate of the etcd
	// cluster's CA. The member must use this certificate to verify the
	// identity of the cluster it's connecting to.
	bytes ca_certificate = 1;
	// pper_certificate is a DER-encoded x509 certificate of this node's
	// etcd peer listener. The member must serve member traffic using this
	// certificate. The private key corresponding to this certificate is
	// the same as the node's primary private keypair.
	bytes peer_certificate = 2;
	// initial_crl is a certificate revocation list that the etcd member
	// should be started with. After startup, the member will maintain its
	// own CRL by updating it from its primary storage location, and etcd
	// value.
	//
	// TODO(q3k): don't pass this here, instead pass this over an etcd
	// watcher and curator.Watch.
	bytes initial_crl = 3;
	message Peer {
	string Name = 1;
	string URL = 2;
	}
	repeated Peer peers = 4;
	}
	KubernetesWorker kubernetes_worker = 1;
	ConsensusMember consensus_member = 2;
	}

	// NodeState is the state of a Metropolis node from the point of view of the
	// cluster it is a part of (or intending to be a part of).
	enum NodeState {
	NODE_STATE_INVALID = 0;

	// NEW: the node has established a first contact with the cluster and
	// intends to register into it. The node's identity has not been verified
	// and no hardware attestation of the new node was performed.
	// The node has generated a CUK/NUK and set up storage encrypted with the
	// combination of both keys.
	// The node has generated a private/public keypair, and that keypair has
	// been used to contact the already running Cluster.
	NODE_STATE_NEW = 1;
	// STANDBY: the node has successfully passed identity and hardware
	// attestation checks as defined by the cluster policy. The node still isn't
	// part of the cluster, as it itself might perform checks against the
	// running Cluster.
	NODE_STATE_STANDBY = 2;
	// UP: the node has passed all preconditions for STANDBY and has also
	// performed a commit into the cluster by exchanging its CUK for a
	// certificate issued by the cluster.
	// The node is now ready to serve, and its certificate can be used to
	// authenticate its identity cryptographically.
	NODE_STATE_UP = 3;
	// DISOWNED: the node has been rejected or decommissioned by the cluster.
	// Any further contact from the node to the cluster will be rejected.
	NODE_STATE_DISOWNED = 4;
	};

	// ClusterState is the state of the cluster from the point of view of a node.
	// Different subsystems can watch this state and depend on it for behaviour
	// (eg. start serving when HOME, maybe self-fence on SPLIT, etc.).
	enum ClusterState {
	CLUSTER_STATE_INVALID = 0;

	// UNKNOWN: the node has not yet determined the existence of a cluster it
	// should join or start. This is a transient, initial state that should only
	// manifest during boot.
	CLUSTER_STATE_UNKNOWN = 1;
	// FOREIGN: the node is attempting to register into an already existing
	// cluster with which it managed to make preliminary contact, but which the
	// cluster has not yet fully productionized (eg. the node is still being
	// hardware attested, or the operator needs to confirm the
	// registration of this node).
	CLUSTER_STATE_FOREIGN = 2;
	// TRUSTED: the node is attempting to register into an already registered
	// cluster, and has been trusted by it. The node is now attempting to fully
	// commit to registering into the cluster.
	CLUSTER_STATE_TRUSTED = 3;
	// HOME: the node is part of this cluster. This is the bulk of time in which
	// this node will spend its time.
	CLUSTER_STATE_HOME = 4;
	// DISOWNING: the node has been disowned (ie., removed) by the cluster, and
	// that it will not be ever part of any cluster again, and that it will be
	// decommissioned by the operator.
	CLUSTER_STATE_DISOWNING = 5;
	// SPLIT:the node would usually be Home in a cluster, but has been split
	// from the consensus of the cluster. This can happen for nodes running
	// consensus when consensus is lost (eg. when there is no quorum or this
	// node has been netsplit), and for other nodes if they have lost network
	// connectivity to the consensus nodes. Clients should make their own
	// decision what action to perform in this state, depending on the level of
	// consistency required and whether it makes sense for the node to fence its
	// services off.
	CLUSTER_STATE_SPLIT = 6;
	}

	// NodeStatus contains all fields self-reported by nodes. This data is
	// inherently less trusted than other data available about a node, as it can be
	// updated to any value by each node individually, including compromised nodes.
	message NodeStatus {
	// external_address is the IP address that the node expects management,
	// cluster and user traffic to arrive at (ie. the address on which it is
	// listening for gRPC, and role-specific services like etcd and
	// Kubernetes).
	string external_address = 1;
	// running_curator contains information about the curator service running
	// on this node, or is nil if the service is not running.
	message RunningCurator {
	// port is the TCP port on which the curator is listening.
	int32 port = 1;
	}
	RunningCurator running_curator = 3;
	// timestamp is an epoch number associated with the last status update.
	// It's set with a nanosecond granularity.
	google.protobuf.Timestamp timestamp = 2;
	}

	// The Cluster Directory is information about the network addressing of nodes
	// in a cluster. It is a serialized snapshot of some of the state within the
	// etcd cluster, and can be used by external processes (like a node Registering
	// into the cluster) to know how to reach this cluster over the network. It can
	// be thought of as a phonebook, or a static name/address configuration that
	// could live in /etc/hosts.
	//
	// The directory explicitly doesn't carry any information about the cluster's
	// identity or security - these should be configured and checked by higher
	// level configuration and processes. The directory can be stored and
	// transmitted in cleartext and without an integrity checks (like saved to the
	// EFI system partition across reboots) and any malicious change to it will
	// cause no more than a denial of service against the consumer of this
	// directory. This is because all nodes contacted must present a valid cluster
	// identity/certificate before they are trusted by the consumers of this
	// directory.
	message ClusterDirectory {
	message Node {
	bytes public_key = 1;
	message Address {
	string host = 1;
	};
	repeated Address addresses = 2;
	};
	repeated Node nodes = 1;
	}