go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/common/proto/config/service_config.proto

// Copyright 2015 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

// Schemas for config files in services/luci-config config set.
//
// In this file, "string pattern" is an exact string (can't have a colon) or a
// string that starts with "regex:", followed by a regular expression. In case
// of regex, the pattern must match an entire string, as if it was surrounded by
// ^ and $.

syntax = "proto3";

package config;

import "google/protobuf/empty.proto";

option go_package = "go.chromium.org/luci/common/proto/config";


// Use to specify configuration stored in Git repository importable via Gitiles
// API.
message GitilesLocation {
  // URL of the Git repository.
  // Must not end with "/".
  // Must not end with ".git".
  // Must not have "/a/" prefix of a path component.
  //
  // Example:
  //   OK:
  //     https://chromium.googlesource.com/infra/infra
  //   Not OK:
  //     https://chromium.googlesource.com/a/infra/infra
  //     https://chromium.googlesource.com/infra/infra/
  //     https://chromium.googlesource.com/infra/infra.git
  string repo = 1;
  // Ref or commit hash of the Git repository.
  //
  // Must be a fully qualified ref starting with "refs/" or a commit hash.
  //
  // Example:
  //   OK:
  //     refs/heads/branch
  //     refs/heads/infra/config
  //     refs/branch-heads/beta
  //     $a_valid_git_sha
  //   Not OK:
  //     main
  //     HEAD
  //     origin/main
  //     tags/123
  //
  // TODO: crbug/1446839 - Replace this field with a new `committish` field
  // to better reflect the fact that field value can be either refs or
  // revision hash.
  string ref = 2;
  // Path to the directory inside Git repository where configurations are stored.
  // Optional. If not specified, defaults to top-level folder of the git repo.
  // Must not start or end with "/".
  //
  // Example:
  //   OK:
  //     infra/config/generated
  //       (empty string)
  //   NOT OK:
  //     /
  //     /config
  //     infra/config/
  string path = 3;
}

// Used to define project specific identities for LUCI to act on behalf when
// interacting with external systems. This allows projects to use exclusive
// and isolated identities to not be accidentally affected by other projects.
message IdentityConfig {
  // ServiceAccountEmail is the full service account email to use when
  // LUCI acts on behalf of the project.
  //
  // Note: Due to token caching, it takes ~15 minutes for a config change
  // to become effective. Keep this in mind when migrating projects to a
  // new identity.
  string service_account_email = 1;
}

// Location is the source repo location where the configuration stores.
// Currently, it only supports Gitiles repos.
// TODO(crbug.com/1446839): replace Project.gitiles_location field later.
message Location {
  oneof location {
    GitilesLocation gitiles_location = 1;
  }
}

/******************************************************************************/
/* Projects                                                                   */
/******************************************************************************/

// A tenant of a service. Defined in projects.cfg.
message Project {
  reserved 2;
  reserved 'config_location';

  // Globally unique id of the project.
  //
  // The id MUST contain only lowercase alphanumeric characters and hyphens.
  // The id MUST NOT be empty or exceed 30 characters.
  string id = 1;

  // Where to import "projects/<id>" config set from.
  oneof location {
    GitilesLocation gitiles_location = 4;
  }

  // IdentityConfig determines what identities are used when LUCI acts on
  // behalf of the project towards external services.
  IdentityConfig identity_config = 3;

  // The Team `name` of the Team which owns this Project.
  //
  // Note that the same Team may be indicated for multiple different Projects.
  string owned_by = 5;
}

// Represents a group of humans who are responsible for one or more LUCI
// projects.
//
// LUCI system maintainers will use the contact addresses associated with
// this Team in order to contact that group of humans about maintenance actions
// which this Team needs to perform in order to keep current with LUCI.
//
// We recommend subscribing to the following mailing lists as well:
//   * luci-announce@ - Announcements of new LUCI functionality.
//   * luci-outages@ - Announcements of LUCI system outages/downtime.
//   * luci-releases@ - (noisy) Announcements of new LUCI service deployments.
//
// We also recommend directing LUCI questions/discussion to:
//   * go/luci-users-chat - Chatroom open to all users of LUCI. Good place to
//     ask/answer questions about the use of LUCI services.
//   * go/luci-dev-chat - Chatroom for developing LUCI services, or
//     systems which tightly interact with LUCI services.
//   * luci-eng@ - Email list for LUCI related questions.
//
// Bugs should be filed to:
//   * go/bug-a-trooper - General bug reports related to the operation of
//     specific builders/machines which happen to run in LUCI. This is a general
//     Chrome-area bug and will be triaged (usually within 24h).
//   * go/luci-bug - Bug reports/feature requests for LUCI services.
//   * go/luci-trooper-bug - Bug reports against LUCI services which
//     need quick attention from a trooper.
//   * oncall/chrome-ops-foundation - Oncall rotation for ChOps Foundation
//     (primary responders for LUCI service outages). It's a good idea to check
//     go/luci-users-chat and luci-outages@ too.
//
// For some migrations, LUCI system maintainers may need to send CLs against
// your project's configuration. The best way to enable this is to maintain an
// OWNERS file in your project configuration repo, otherwise we'll have to start
// guessing at reviewers :).
//
// To allow LUCI system maintainers to send CLs, please ensure that eng@ has the
// ability to read+send CLs to your configuration repo. If we're unable to send
// a CL (e.g. the repo is super-secret), we'll instead send an email for you to
// apply the change yourself.
message Team {
  // The name of this team; Used for the Project.team field, but also may
  // be used in e.g. email as the addressee for maintenance messages, like:
  //
  //   Hello ${Team.name} LUCI maintainers,
  //
  // Examples:
  //   GOOD: "ChOps Foundation"
  //   BAD:  "cft"
  string name = 1;

  // One or more contact emails for this team.
  //
  // ALL of these email addresses will be used by the LUCI system owners to
  // contact the team with maintenance requests/deprecation notices. For
  // example, if some LUCI functionality is deprecated and needs to be migrated,
  // then an email would be sent to all contacts listed in this field.
  //
  // We recommend setting this to your team's dev-group email.
  repeated string maintenance_contact = 2;

  // One or more fallback emails for this team.
  //
  // If the LUCI system owners attempt to contact the team via
  // `maintenance_contact` and there's no response, these emails will be
  // CC'd in increasing order until we get in contact with someone.
  //
  // If the LUCI system owners cannot contact anyone in `maintenance_contact` or
  // in `escalation_contact`, we may need to disable the associated LUCI
  // project(s).
  //
  // We recommend setting this to one or two individual people who are
  // responsible for your team's LUCI integration, and finally a
  // wider email group (or groups) than those in maintenance_contact.
  repeated string escalation_contact = 3;
}

// Schema of projects.cfg file. Represents LUCI tenants registry.
message ProjectsCfg {
  // All projects served by this instance of LUCI.
  repeated Project projects = 1;

  // All teams which own projects.
  repeated Team teams = 2;
}

/******************************************************************************/
/* Services                                                                   */
/******************************************************************************/

// Describes one LUCI service.
message Service {
  reserved 3;
  reserved 'config_location';

  message JWTAuth {
    // Value for the 'aud' field in the JSON Web Token claim.
    string audience = 1;
  }

  // Globally unique id of the service. Required.
  // Used in "services/<service_id>" config set name.
  string id = 1;
  // Email addresses of responsible and point-of-contacts for the service.
  repeated string owners = 2;
  // An HTTPS endpoint that returns JSON-encoded ServiceDynamicMetadata in body.
  //
  // TODO: crbug/1232565 - Deprecate this field in favor of `hostname`
  // after the new LUCI Config service has launched.
  string metadata_url = 4;
  // The hostname of the service.
  //
  // LUCI Config will call this host to interact with `config.Consumer`
  // prpc Service.
  string hostname = 7;
  // A list of identities that have access to this service's configs.
  // of:
  // * "group:<group>", where group is defined on auth server.
  // * "<email>"
  // * "<kind>:<value>" (for non-email identities)
  //
  // If not specified, only admins and trusted services have access.
  repeated string access = 5;
  // If set, use JWT auth in requests to services. This is usually used for
  // Cloud Endpoints v2 support.
  JWTAuth jwt_auth = 6;
}

// Machine-generated service metadata, exposed by a service endpoint.
// Typically implemented by config component, embedded in an app:
// see appengine/components/components/config/endpoint.py
//
// If you add a field here, also add it to ServiceDynamicMetadata in endpoint.py
message ServiceDynamicMetadata {
  // Format version. Supported versions: 1.0.
  string version = 1;
  // What configs this service can validate and how to validate them.
  Validator validation = 2;
  // True if the server recognizes "Content-Encoding: gzip" in requests.
  bool supports_gzip_compression = 3;
}

// Schema of services.cfg
message ServicesCfg {
  // A list of all LUCI services. Should be sorted by id.
  repeated Service services = 1;
}

/******************************************************************************/
/* Misc                                                                       */
/******************************************************************************/


// Schema of acl.cfg file.
// Next tag: 13.
message AclCfg {
  reserved 3, 4, 5, 6, 12;
  reserved 'config_get_by_hash_group';
  reserved 'admin_group';
  reserved 'validation_group';
  reserved 'reimport_group';
  reserved 'legacy_project_access_group';

  // Name of the group that has global access to all "projects/*" config sets.
  //
  // Should contain only members that really need read access to multiple
  // projects. Access to an individual project can be granted through
  // "role/configs.reader" role in the "@root" realm of the project.
  string project_access_group = 2;

  // Name of the group that can call validation API for any accessible project.
  //
  // Should contain only members that really need to use validation API in
  // multiple projects. Permission to validate an individual project can be
  // granted through "role/configs.developer" role in the "@root" realm of
  // the project.
  string project_validation_group = 8;

  // Name of the group that can call reimport API for any accessible project.
  //
  // Should contain only members that really need to use reimport API in
  // multiple projects. Permission to reimport an individual project can be
  // granted through "role/configs.developer" role in the "@root" realm of
  // the project.
  string project_reimport_group = 9;

  // Name of the group that has global access to all "services/*" config sets.
  //
  // Should contain only members that really need read access to multiple
  // services. Access to an individual service can be granted via "access" field
  // in its entry in services.cfg config.
  string service_access_group = 7;

  // Name of the group that can call validation API for any accessible service.
  string service_validation_group = 10;

  // Name of the group that can call reimport API for any accessible service.
  string service_reimport_group = 11;
}

// Schema for import.cfg. It specified how to import configuration files from
// external sources.
message ImportCfg {

  message Gitiles {
    // Request timeout in seconds when requesting commit log.
    int32 fetch_log_deadline = 1;
    // Request timeout in seconds when requesting directory archive.
    int32 fetch_archive_deadline = 2;
    // DEPRECATED, ignored. TODO(nodir): remove.
    // Default ref for project configs.
    string project_config_default_ref = 3;
    // DEPRECATED, ignored. TODO(nodir): remove.
    // Default directory for project configs.
    string project_config_default_path = 4;
    // Default directory for ref configs.
    string ref_config_default_path = 5;
  }

  // Configuration of import from Gitiles repositories.
  Gitiles gitiles = 1;
}

// Schema of schemas.cfg
message SchemasCfg {
  message Schema {
    // Name of schema.
    // For service configs, "<config_set>:<path>"
    // For project configs, "projects:<path>"
    // For ref configs, "projects/refs:<path>"
    string name = 1;
    // URL to the schema definition, e.g. to a .proto file in a repository.
    string url = 2;
  }
  // List of known schemas. They are available at /schemas/<name> as a short
  // mutable link.
  repeated Schema schemas = 1;
}

/******************************************************************************/
/* Validation                                                                 */
/******************************************************************************/

// Defines a pattern of a config identity. Both config_set and path must
// match.
message ConfigPattern {
  // A string pattern for config_set.
  //
  // If the pattern string starts with "regex:", everything after the prefix
  // will be treated as regular expression to match the config set. The
  // regular expression will be auto-anchored with "^" at the beginning and "$"
  // at the end if not already.
  //
  // If the pattern string starts with "exact:" or "text:", everything after the
  // prefix should be exactly the same as the config set to match the pattern.
  //
  // If the pattern string doesn't start with any of the above prefixes, it will
  // be used as exact match just like "exact:" and "text:" prefixes.
  //
  // Note that LUCI Config will only send the service configs that belongs to
  /// the service defined in `Service` or validation, even though the
  // config_set pattern here can declare a much broader range (e.g.
  // `regex:services/.+` that matches all services).
  string config_set = 1;
  // A string pattern for config file path.
  //
  // The pattern syntax is the same as `config_set`
  string path = 2;
}

// Describes what configuration can be validated and how to validate them.
message Validator {
  // A list of configuration patterns that this validator can validate.
  repeated ConfigPattern patterns = 1;
  // URL of a validation endpoint. The config service will send an HTTP POST
  // request to the endpoint, where body is JSON-encoded
  // ValidationRequestMessage. The endpoint is expected to respond with
  // HTTP status 200 and JSON-encoded ValidationResponseMessage.
  string url = 2;
}

// This message is used only in JSON form. It is sent as request body to an
// external validation endpoint in order to validate a config.
message ValidationRequestMessage {
  // Config set of the config file to validate.
  string config_set = 1;
  // Path of the config file to validate.
  string path = 2;
  // Contents of the file.
  bytes content = 3;
}

// This message is used only in JSON form. It is expected from an external
// validation endpoint that validates a config.
message ValidationResponseMessage {
  // Severity of a validation response message. In JSON encoded as a string.
  enum Severity {
    UNKNOWN = 0;
    DEBUG = 10;
    INFO = 20;
    WARNING = 30;
    ERROR = 40;
    CRITICAL = 50;
  }
  // A message that explains why a config is valid or not.
  message Message {
    // Path of the config file that has an error.
    string path = 1;
    // If an error, a config is considered invalid. Defaults to INFO.
    Severity severity = 2;
    // Textual representation of the message.
    string text = 3;
  }
  // Errors, warnings and other information found during validation.
  // If at least one error is found, the config is considered invalid.
  repeated Message messages = 1;
}


/******************************************************************************/
/* Service                                                                    */
/******************************************************************************/

// Consumer can be implemented by the registered service that consumes config.
//
// The service should be registered in `ServicesCfg`. It is currently for a
// service declaring configs of interest and validate those configs.
service Consumer {
  // GetMetadata returns the service metadata.
  rpc GetMetadata(google.protobuf.Empty) returns(ServiceMetadata) {}
  // ValidateConfigs validates the provided configs within a config set.
  rpc ValidateConfigs(ValidateConfigsRequest) returns (ValidationResult) {};
}

// ServiceMetadata describes the metadata of a service.
message ServiceMetadata {
  // Patterns of config files that the service is "interested in".
  //
  // Interested means the service can validate config files on config files
  // changes.
  repeated ConfigPattern config_patterns = 1;
}

// ValidateConfigsRequest is the request to ValidateConfigs rpc.
message ValidateConfigsRequest {
  message Files {
    repeated File files = 1;
  }
  // File represents a config file to validate.
  message File {
    // path of the config file relative to root config directory.
    string path = 1;
    oneof content {
      // RawContent is the raw byte content of the config file.
      bytes raw_content = 2;
      // SignedURL is a GCS singed url to download full config content.
      //
      // The service SHOULD provide "Accept-Encoding: gzip" header to minimize
      // the data on the wire and the service should also be able to
      // handle the uncompressed data based on the presence of
      // "Content-Encoding" header.
      // The signed url will expire shortly. Currently LUCI Config sets the
      // expiration time to 10 min.
      string signed_url = 3;
    }
  }
  // Config set of the config files to validate.
  string config_set = 1;
  // Config files to validate.
  Files files = 2;
}

// ValidationResult is the result of validating configs.
message ValidationResult {
  // Severity of a validation response message.
  enum Severity {
    UNKNOWN = 0;
    DEBUG = 10;
    INFO = 20;
    WARNING = 30;
    ERROR = 40;
    CRITICAL = 50;
  }
  // A message that explains why a config is valid or not.
  message Message {
    // Path of the config file that has an error.
    string path = 1;
    // If an error, a config is considered invalid. Defaults to INFO.
    Severity severity = 2;
    // Textual representation of the message.
    string text = 3;
  }
  // Errors, warnings and other information found during validation.
  // If at least one error is found, the config is considered invalid.
  repeated Message messages = 1;
}