go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/deploy/api/modelpb/asset.proto

// Copyright 2022 The LUCI Authors.
//
// 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 deploy.model;

option go_package = "go.chromium.org/luci/deploy/api/modelpb";

import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

import "go.chromium.org/luci/deploy/api/modelpb/actuation.proto";
import "go.chromium.org/luci/deploy/api/modelpb/artifact.proto";
import "go.chromium.org/luci/deploy/api/modelpb/deployment.proto";


// Asset represents a Cloud resource (or a bunch of resources) actuated as
// a single unit.
message Asset {
  // Unique ID of this asset.
  //
  // Defines the asset type (in particular what oneof branch is expected to
  // be populated in AssetState).
  //
  // Matches full resource name of the asset's root resource per Google Cloud
  // API conventions. For now only Appengine services are supported with asset
  // ID being "apps/<app-id>".
  string id = 1;

  // The snapshot of the most recent actuation.
  //
  // This is the most recent actuation. Most of the time it will be an actuation
  // that made SKIP_UPTODATE decision (since most of the time assets are
  // up-to-date).
  //
  // May still be in-flight.
  Actuation last_actuation = 2;

  // The last actuation decision regarding this asset.
  //
  // It is the decision that was made by the `last_actuation` when it started.
  ActuationDecision last_decision = 3;

  // The snapshot of the most recent actuation with ACTUATE_* decision.
  //
  // It is the actuation that changed (or attempted to change) this asset the
  // last time.
  //
  // May still be in-flight.
  Actuation last_actuate_actuation = 4;

  // The last ACTUATE_* actuation decision regarding this asset.
  //
  // It is the decision that was made by the `last_actuate_actuation` when it
  // started.
  ActuationDecision last_actuate_decision = 5;

  // Asset configuration as defined in the IaC repo.
  //
  // It's the configuration consumed the deployment system itself. Actuated
  // resources are configured via `intended_state`.
  AssetConfig config = 6;

  // The intended state of the asset as defined in the IaC repo.
  //
  // It is the intended asset state reported by the actuator during its most
  // recent BeginActuation call. This state is derived purely from the committed
  // configuration. The actuator will try to move the asset into this state.
  //
  // Has its `state` oneof populated according to the asset kind using
  // IntendedState sub-fields. Never contains an erroneous AssetState.
  //
  // May be missing for new assets if they are misconfigured in the IaC repo.
  AssetState intended_state = 7;

  // The last successfully applied intended state.
  //
  // May be different from `intended_state` for assets being actuated right now
  // of for disabled, locked or broken assets.
  //
  // Has its `state` oneof populated according to the asset kind using
  // IntendedState sub-fields. Never contains an erroneous AssetState.
  //
  // May be missing for new assets if they never had successful actuations.
  AssetState applied_state = 8;

  // The actual state of the asset as reported by the actuator most recently.
  //
  // It is the captured asset state reported by the actuator during its most
  // BeginActuation or EndActuation calls. Matches some real most recently
  // observed state of the asset, regardless how this state came to be.
  //
  // Has its `state` oneof populated according to the asset kind using
  // CapturedState sub-fields. Never contains an erroneous AssetState.
  //
  // May be missing for new assets if the actuator fails to capture their state.
  AssetState reported_state = 9;

  // The last state applied by the actuator itself.
  //
  // For up-to-date assets it matches `intended_state` and `reported_state`.
  //
  // If during an actuation cycle the actuator partially updates some resources
  // and then fails, `actuated_state` may be some intermediate state between
  // the intended and the initial pre-actuation states.
  //
  // If some external entity (not the actuator) messes with the asset,
  // `reported_state` may be different from `actuated_state`.
  //
  // Has its `state` oneof populated according to the asset kind using
  // CapturedState sub-fields. Never contains an erroneous AssetState.
  //
  // May be missing for new assets while they are being actuated or if the
  // actuator fails to capture their post-actuation state.
  AssetState actuated_state = 10;

  // Populated if the actuator failed to capture the post-actuation state.
  //
  // If this field is set then `actuated_state` likely doesn't match reality
  // and the next actuation attempt will likely trigger the anti-stomp
  // protection.
  google.rpc.Status post_actuation_status = 11;
}


// AssetHistory captures an actuation decision made by the backend regarding
// some asset along with all data that led to it, as well as the corresponding
// actuation outcome.
message AssetHistory {
  // The parent asset ID.
  string asset_id = 1;
  // Index in the asset's history log, monotonically increasing starting with 1.
  int64 history_id = 2;

  // The decision made by the backend.
  ActuationDecision decision = 3;
  // The snapshot of the associated actuation.
  Actuation actuation = 4;

  // Reported asset configuration as defined in the IaC repo.
  AssetConfig config = 5;
  // Reported intended state of the asset as defined in the IaC repo.
  AssetState intended_state = 6;
  // Reported actual state of the asset (as scanned by the actuator).
  AssetState reported_state = 7;
  // The last successfully applied intended state **prior** to the actuation.
  AssetState last_applied_state = 8;
  // The reported state **after** the actuation, if it was performed.
  AssetState post_actuation_state = 9;
  // Number of consecutive failures prior to this entry (excluding itself).
  int64 prior_consecutive_failures = 10;
}


// Asset configuration as defined in the IaC repo.
message AssetConfig {
  // True to actuate the asset, false to leave it alone.
  bool enable_automation = 1;
  // How many inactive GAE versions to keep.
  int32 inactive_versions_to_keep = 2;
}


// A snapshot of the intended or captured state of an asset.
//
// Also contains information about the actuator and the deployment at the time
// the state was captured. This is useful for the historical log of states.
message AssetState {
  // When this state was captured.
  google.protobuf.Timestamp timestamp = 1;
  // The deployment configuration at the time the state was captured.
  Deployment deployment = 2;
  // The actuator that performed the capture.
  ActuatorInfo actuator = 3;
  // Error details if the asset state could not be captured.
  google.rpc.Status status = 4;

  // The intended or captured state of the asset if `status` is OK.
  oneof state {
    // For assets with ID "apps/<app-id>".
    AppengineState appengine = 10;
  }
}


// Intended or captured state of an Appengine service.
message AppengineState {
  // A list of services (sorted by name) with intended or captured state.
  message Service {
    // Name of the service e.g. "default".
    string name = 1;

    // A list of service versions sorted by name.
    message Version {
      // Name of the version e.g. "11120-9f81d82".
      string name = 1;

      // State which is defined in the config and which can't be easily captured
      // using Cloud APIs.
      //
      // This field is populated in `intended_state`.
      message IntendedState {
        // The artifact (GAE tarball) that should be running there.
        ArtifactID artifact = 1;
        // Path to the service YAML within the tarball.
        string yaml_path = 2;
        // Vars passed to `gaedeploy` for substitution in the YAML.
        map<string, string> luci_vars = 3;
      }
      IntendedState intended_state = 2;

      // State which is captured using Cloud APIs and which can't be defined
      // in the config (at least not directly).
      //
      // This field is populated in `reported_state` and `actuated_state`.
      //
      // See https://cloud.google.com/appengine/docs/admin-api/reference/rpc/google.appengine.v1#google.appengine.v1.Version
      message CapturedState {
        // E.g. "F4".
        string instance_class = 1;
        // E.g. "standard".
        string env = 2;
        // E.g. "go116"
        string runtime = 3;
        // Some runtimes have channels.
        string runtime_channel = 4;
        // Some runtimes have API versions.
        string runtime_api_version = 5;
        // Email of who uploaded this version.
        string created_by = 6;
        // When it was uploaded.
        google.protobuf.Timestamp create_time = 7;
        // Serving URL of this version specifically.
        string version_url = 8;
      }
      CapturedState captured_state = 3;
    }
    repeated Version versions = 2;

    // Traffic splitting method.
    enum TrafficSplitting {
      TRAFFIC_SPLITTING_UNSPECIFIED = 0;

      COOKIE = 1;
      IP     = 2;
      RANDOM = 3;
    }
    TrafficSplitting traffic_splitting = 3;

    // Traffic allocation as a map from version name to [0, 1000].
    map<string, int32> traffic_allocation = 4;
  }
  repeated Service services = 1;

  // State which is defined in the config and which can't be easily captured
  // using Cloud APIs.
  //
  // This field is populated in `intended_state`.
  message IntendedState {
    // The list of deployable YAMLs (such as "cron.yaml").
    message DeployableYaml {
      // The artifact (GAE tarball) with the YAML.
      ArtifactID artifact = 1;
      // Path to the YAML within the tarball.
      string yaml_path = 2;
    }
    repeated DeployableYaml deployable_yamls = 1;
  }
  IntendedState intended_state = 2;

  // State which is captured using Cloud APIs and which can't be defined
  // in the config (at least not directly).
  //
  // This field is populated in `reported_state` and `actuated_state`.
  //
  // See https://cloud.google.com/appengine/docs/admin-api/reference/rpc/google.appengine.v1#google.appengine.v1.Application
  message CapturedState {
    // E.g. "us-central".
    string location_id = 1;
    // Default service hostname.
    string default_hostname = 2;

    // What kind of a database is associated with the app.
    enum DatabaseType {
      DATABASE_TYPE_UNSPECIFIED = 0;

      CLOUD_DATASTORE               = 1;
      CLOUD_FIRESTORE               = 2;
      CLOUD_DATASTORE_COMPATIBILITY = 3;
    }
    DatabaseType database_type = 3;
  }
  CapturedState captured_state = 3;
}