metropolis/proto/common/common.proto

// 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";
import "version/spec/spec.proto";

import "osbase/logtree/proto/logtree.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 KubernetesController {
    }
    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;
    KubernetesController kubernetes_controller = 3;
}

// NodeLabels are labels assigned to a node.
//
// Labels are string key/value pairs modeled after the Kubernetes label concept.
// They can be used to assign user-specific metadata to nodes like IDs from other
// systems or geographical location. They are treated like opaque strings by
// Metropolis itself.
//
// Every key and value must be a string between 1 and 63 characters long
// (inclusive). Each character must be a valid ASCII character from the following
// range: a-z, A-Z, 0-9 '-', '_' or '.'. The first character must be a-z, A-Z or
// 0-9. This is close but not exact to DNS label requirements (for example, '.'
// or '_' are generally not valid DNS label parts... but that's a discussion for
// another day).
//
// Keys must not repeat across node labels - that is, NodeLabels must be
// convertable to/from a string/string map in Go. Pair ordering is not preserved,
// but pair order in labels received from Metropolis API calls is stable (however
// it is arbitrary).
//
// A node cannot have more than 128 labels.
message NodeLabels {
    message Pair {
        string key = 1;
        string value = 2;
    }
    repeated Pair pairs = 1;
}

// 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;
    // DECOMMISSIONED: The node has successfully been decommissioned and can be
    // deleted.
    //
    // TODO(q3k): add missing -ING states.
    NODE_STATE_DECOMMISSIONED = 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;
    // version is the Metropolis version that this node is running.
    version.spec.Version version = 4;
    // boot_id is a random value chosen for each kernel start.
    // If this value changes, a new kernel instance is running on the node.
    bytes boot_id = 5;
}

// 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 {
        string id = 3;
        reserved 1;
        message Address {
            string host = 1;
        };
        repeated Address addresses = 2;
    };
    repeated Node nodes = 1;
}


// NodeClusterNetworking carries information about the cluster networking (ie.
// WireGuard mesh) connectivity of a node.
message NodeClusterNetworking {
    message Prefix {
        string cidr = 1;
    }
    // wireguard_pubkey is the base64-encoded public key used by the node.
    string wireguard_pubkey = 1;
    // prefixes are networking routes exported by the node to the cluster networking
    // mesh, and are programmed by other nodes into their wireguard peer config.
    repeated Prefix prefixes = 2;
}

// Filter set when requesting logs for a given DN. This message is equivalent to
// the following GADT enum:
// data LogFilter = WithChildren
//                | OnlyRaw
//                | OnlyLeveled
//                | LeveledWithMinimumSeverity(Severity)
//
// Multiple LogFilters can be chained/combined when requesting logs, as long as
// they do not conflict.
message LogFilter {
    // Entries will be returned not only for the given DN, but all child DNs as
    // well. For instance, if the requested DN is foo, entries logged to foo,
    // foo.bar and foo.bar.baz will all be returned.
    message WithChildren {
    }
    // Only raw logging entries will be returned. Conflicts with OnlyLeveled
    // filters.
    message OnlyRaw {
    }
    // Only leveled logging entries will be returned. Conflicts with OnlyRaw
    // filters.
    message OnlyLeveled {
    }
    // If leveled logs are returned, all entries at severity lower than `minimum`
    // will be discarded.
    message LeveledWithMinimumSeverity {
        osbase.logtree.proto.LeveledLogSeverity minimum = 1;
    }
    oneof filter {
        WithChildren with_children = 1;
        OnlyRaw only_raw = 3;
        OnlyLeveled only_leveled = 4;
        LeveledWithMinimumSeverity leveled_with_minimum_severity = 5;
    }
}

// ClusterConfiguration contains the entirety of the user-configurable behaviour
// of the cluster that is scoped to the entirety of the cluster (vs. per-node
// configuration, which is kept alongside Node).
//
// It can be set initially when a cluster is being bootstrapped (in
// NodeParamaters.ClusterBootstrap), and then can be partially managed by
// management calls to the curator.
message ClusterConfiguration {
    // cluster_domain is the domain name which identifies the cluster.
    // It should be unique, and ideally a public DNS name, but one under
    // .internal works too. The cluster domain is used for different purposes:
    //
    //   - To identify the cluster in clients like metroctl.
    //   - To resolve control plane endpoints with DNS in clients.
    //   - As the SPIFFE trust domain name of the cluster. Every identity
    //     issued by the cluster is rooted under `spiffe://cluster_domain/`.
    //   - As the issuer of OpenID Connect identity tokens. The discovery
    //     document is thus hosted at https://cluster_domain/.well-known/openid-configuration
    string cluster_domain = 4;

    // tpm_mode defines the TPM usage policy for cluster nodes. When nodes
    // register into the cluster (and then join into it) they will report their
    // TPM availability, and in return the cluster will respond whether they
    // should use that TPM or not.
    //
    // If a node is instructed to use its TPM, it will use it to encrypt its part
    // of the disk encryption key when saving it to the EFI system partition.
    // That means that the node will only be able to re-join the cluster if its
    // secure boot configuration doesn't change.
    //
    // If a node is instructed to not use its TPM, it will save its part of the
    // disk encryption key straight onto the EFI system partition without any
    // further encryption. It still needs to connect to a working cluster to
    // retrieve the other part of the key. This means that the configuration is
    // secure vs. offline disk decryption attempts, but not secure if an
    // attacker can connect to a cluster and impersonate the node in order to
    // retrieve the other part of its key.
    enum TPMMode {
        TPM_MODE_INVALID = 0;
        // Nodes need to join with a TPM2.0 device and will be instructed to
        // use it.
        TPM_MODE_REQUIRED = 1;
        // Nodes will be allowed to join regardless of TPM2.0 presence, and will
        // be instructed to use it if they have one.
        TPM_MODE_BEST_EFFORT = 2;
        // Regardless of the node's local TPM presence it will be instructed to
        // not use it.
        TPM_MODE_DISABLED = 3;
    }
    TPMMode tpm_mode = 1;

    // storage_security_policy defines which node storage security settings are
    // accepted by the cluster. Nodes are informed of the cluster policy when
    // registering into the cluster, alongside a cluster-recommended storage
    // security setting. The node then reports its selected node storage setting
    // during its Commit call which the cluster verifies against its policy.
    enum StorageSecurityPolicy {
        STORAGE_SECURITY_POLICY_INVALID = 0;
        // The cluster accepts any storage security.
        STORAGE_SECURITY_POLICY_PERMISSIVE = 1;
        // The cluster accepts any storage security that offers encryption.
        STORAGE_SECURITY_POLICY_NEEDS_ENCRYPTION = 2;
        // The cluster accepts any storage security that offers encryption and
        // authentication.
        STORAGE_SECURITY_POLICY_NEEDS_ENCRYPTION_AND_AUTHENTICATION = 3;
        // The cluster only accepts unencrypted and unauthenticated node storage.
        STORAGE_SECURITY_POLICY_NEEDS_INSECURE = 4;
    }
    StorageSecurityPolicy storage_security_policy = 2;

    message Kubernetes {
        message NodeLabelsToSynchronize {
            // Node labels matching this regexp will be synchronized.
            //
            // For example, the following regex: `^[^/]*foo$` would match:
            //  - foo: bar
            //  - bar-foo: baz
            // But wouldn't match:
            //  - example.com/foo: bar
            //
            // Regexes are compiled using Go's regexp library, and must be anchored (with ^
            // and $) by the user. An invalid regexp matches no label.
            string regexp = 1;
        }

        // Rules to match Node labels that should be synchronized into Kubernetes
        // node labels. A label matching any rule will be synchronized and managed by
        // Metropolis. If a label stops matching a rule (ie., the rules gets modified
        // so it doesn't match some label, or the label gets removed from the Node
        // in Metropolis), the label will also be removed from the Kubernetes node.
        //
        // Users should be careful about not synchronizing labels that will collide
        // with other Kubernetes node labels, as then that node's labels will not be
        // synchronized at all as a safety precaution.
        //
        // Note: there are certain labels that Metropolis will always add to
        // Kubernetes nodes, such as node-role.kubernetes.io/...  . These are not
        // influenced by these rules.
        repeated NodeLabelsToSynchronize node_labels_to_synchronize = 3;
    }
    Kubernetes kubernetes = 3;
}

// NodeTPMUsage describes whether a node has a TPM2.0 and if it is/should be
// actively used to seal secrets before saving them to its EFI system partition.
enum NodeTPMUsage {
    NODE_TPM_USAGE_INVALID = 0;
    // This node has no TPM 2.0.
    NODE_TPM_USAGE_NOT_PRESENT = 1;
    // This node has a TPM 2.0 but the cluster configuration mandates not using
    // it.
    NODE_TPM_USAGE_PRESENT_BUT_UNUSED = 2;
    // This node has a TPM 2.0 and it is being actively used.
    NODE_TPM_USAGE_PRESENT_AND_USED = 3;
}

// NodeStorageSecurity describes how a node encrypts and/or authenticates its
// local storage. In other words, it's a configuration setting for disk
// encryption (ie. via dm-crypt) and disk integrity (ie. via dm-integrity) of
// the Metropolis data partition.
enum NodeStorageSecurity {
    NODE_STORAGE_SECURITY_INVALID = 0;
    // The node has unencrypted and unauthenticated disk storage. Its data
    // partition is a plain XFS partition, and the node's credentials are stored
    // on it directly.
    NODE_STORAGE_SECURITY_INSECURE = 1;
    // The node has encrypted but unauthenticated disk storage. Its data
    // partition is an XFS partition mounted through dm-crypt.
    NODE_STORAGE_SECURITY_ENCRYPTED = 2;
    // The node has encrypted and authenticated storage. Its data
    // partition is an XFS partition mounted through dm-integrity and dm-crypt.
    NODE_STORAGE_SECURITY_AUTHENTICATED_ENCRYPTED = 3;
}