metropolis/proto/api/configuration.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.api;
option go_package = "source.monogon.dev/metropolis/proto/api";

import "metropolis/proto/common/common.proto";
import "osbase/net/proto/net.proto";

// NodeParameters is the data with which a Node is set booted. It contains the
// configuration required for a node to either bootstrap a new cluster, or
// register into an existing one.
// It is serialized into a proto message and supplied to Metropolis in an
// implementation-specific way (currently: either on ESP partition or via qemu
// fw_cfg).
message NodeParameters {
    // ClusterBootstrap configures the node to attempt to create a new cluster
    // from scratch. Further nodes can become part of the cluster by being
    // configured with ClusterRegister, which should contain data retrieved from
    // the newly bootstrapped cluster by its operator.
    message ClusterBootstrap {
        // owner_public_key is a raw Ed25519 public whose corresponding private
        // key can be used to prove ownership of the cluster and retrieve
        // management credentials for the cluster via an AAA.Escrow call.
        bytes owner_public_key = 1;

        reserved 2;

        // If not set, defaults to:
        //   - TPM mode: REQUIRED
        common.ClusterConfiguration initial_cluster_configuration = 3;

        // Labels that the first node will start out with. The given labels must
        // be valid (see NodeLabels for more details). Invalid labels will be
        // discarded.
        metropolis.proto.common.NodeLabels labels = 4;
    }
    // ClusterRegister configures the node to attempt to register into an
    // existing cluster, ie. contact an existing running cluster and become
    // its member.
    message ClusterRegister {
        // cluster_directory is a directory (mapping of names into IP addresses
        // and public keys) of existing nodes in the cluster. It's used as the
        // initial contact point of the already running cluster that the node
        // should register into. It can be retrieved by an operator from
        // a running cluster via Management.GetClusterInfo.
        metropolis.proto.common.ClusterDirectory cluster_directory = 1;
        // register_ticket is the opaque Register Ticket required from a node to
        // begin registering it into a cluster. It can be retrieved by an
        // operator from a running cluster via Management.GetRegisterTicket.
        bytes register_ticket = 2;
        // ca_certificate is the DER-encoded x509 CA of the cluster that the
        // node should expect when contacting nodes in cluster_directory and
        // attempting to register into a cluster. It can be retrieved by
        // an operator from a running cluster via Management.GetClusterInfo.
        bytes ca_certificate = 3;

        // Labels that the new node will start out with. The given labels must
        // be valid (see NodeLabels for more details). Invalid labels will be
        // discarded.
        metropolis.proto.common.NodeLabels labels = 4;
    }
    oneof cluster {
        ClusterBootstrap cluster_bootstrap = 1;
        ClusterRegister cluster_register = 2;
    }

    // Optional network configuration when autoconfiguration is not possible or
    // desirable. If unset, autoconfiguration (ie. DHCP) is used.
    osbase.net.proto.Net network_config = 4;
}