// Copyright 2026 Google LLC
//
// 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 google.cloud.sql.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/sql/v1/cloud_sql_resources.proto";
import "google/protobuf/timestamp.proto";

option go_package = "cloud.google.com/go/sql/apiv1/sqlpb;sqlpb";
option java_multiple_files = true;
option java_outer_classname = "CloudSqlBlueGreenDeploymentsProto";
option java_package = "com.google.cloud.sql.v1";

// Service for managing blue-green deployments.
service BlueGreenDeploymentsService {
  option (google.api.default_host) = "sqladmin.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/sqlservice.admin";

  // Creates a blue-green deployment under a given project and location.
  rpc CreateBlueGreenDeployment(CreateBlueGreenDeploymentRequest)
      returns (Operation) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*}/blueGreenDeployments"
      body: "blue_green_deployment"
    };
    option (google.api.method_signature) =
        "parent,blue_green_deployment,blue_green_deployment_id";
  }

  // Retrieves a blue-green deployment resource under a given project and
  // location.
  rpc GetBlueGreenDeployment(GetBlueGreenDeploymentRequest)
      returns (BlueGreenDeployment) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/blueGreenDeployments/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Switches over to green instance for a blue-green deployment.
  rpc SwitchoverBlueGreenDeployment(SwitchoverBlueGreenDeploymentRequest)
      returns (Operation) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/locations/*/blueGreenDeployments/*}:switchover"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists blue-green deployments under a given project.
  rpc ListBlueGreenDeployments(ListBlueGreenDeploymentsRequest)
      returns (ListBlueGreenDeploymentsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*/locations/*}/blueGreenDeployments"
    };
    option (google.api.method_signature) = "parent";
  }

  // Deletes a blue-green deployment.
  rpc DeleteBlueGreenDeployment(DeleteBlueGreenDeploymentRequest)
      returns (Operation) {
    option (google.api.http) = {
      delete: "/v1/{name=projects/*/locations/*/blueGreenDeployments/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// A `BlueGreenDeployment` resource represents a Cloud SQL blue-green deployment
// setup.
message BlueGreenDeployment {
  option (google.api.resource) = {
    type: "sqladmin.googleapis.com/BlueGreenDeployment"
    pattern: "projects/{project}/locations/{location}/blueGreenDeployments/{blue_green_deployment}"
    plural: "blueGreenDeployments"
    singular: "blueGreenDeployment"
  };

  // The state of the blue-green deployment.
  enum State {
    // The default value. This value is used if the state is omitted or unknown.
    STATE_UNSPECIFIED = 0;

    // The deployment is being provisioned.
    PROVISIONING = 1;

    // The deployment is ready for switchover.
    SWITCHOVER_READY = 2;

    // The deployment is not ready for switchover.
    SWITCHOVER_NOT_READY = 3;

    // The deployment is in the process of switching over.
    SWITCHOVER_IN_PROGRESS = 4;

    // The deployment has completed switchover.
    SWITCHOVER_COMPLETED = 5;

    // The deployment is being deleted.
    DELETING = 6;
  }

  // Configuration specified by the user at creation time for the target (green)
  // instance.
  message RequestedConfig {
    // Optional. The target database major version for the upgrade. For example,
    // `MYSQL_8_0` or `POSTGRES_15`.
    string database_version = 1 [(google.api.field_behavior) = OPTIONAL];
  }

  // Combined list of tasks for all paired nodes in the deployment.
  message DeploymentTasks {
    // Output only. Tasks performed or being performed on the paired nodes
    // of the deployment at a consolidated level.
    repeated SourceTargetPairedNode.DeploymentTask task = 1
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Represents a pairing of a source instance node and a target instance node.
  message SourceTargetPairedNode {
    // The state of a pair of source and target instances in deployment (paired
    // node).
    enum State {
      // The state of the paired node is unknown.
      STATE_UNSPECIFIED = 0;

      // The paired node is being provisioned.
      PROVISIONING = 1;

      // The paired node is provisioned.
      PROVISIONED = 2;

      // The paired node is upgrading.
      UPGRADING = 3;

      // The paired node is upgraded.
      UPGRADED = 4;

      // Upgrade failed on the paired node.
      UPGRADE_FAILED = 5;

      // Switchover is in progress.
      SWITCHOVER_IN_PROGRESS = 6;

      // Switchover failed on the paired node.
      SWITCHOVER_FAILED = 7;

      // Switchover completed successfully.
      SWITCHOVER_SUCCEEDED = 8;

      // The paired node is being deleted.
      DELETING = 11;
    }

    // Represents a specific configuration difference between blue and green
    // instances.
    message ConfigDiff {
      // Output only. The name of the field that differs in the blue and green
      // instances, fully-qualified. Example: `settings.tier`
      string field = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The value on the source instance.
      string source_value = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The value on the target instance.
      string target_value = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Details about an instance within the deployment.
    message NodeInfo {
      // Output only. The full resource name of the instance.
      // Format: projects/{project}/instances/{instance}
      string instance = 1 [
        (google.api.field_behavior) = OUTPUT_ONLY,
        (google.api.resource_reference) = {
          type: "sqladmin.googleapis.com/Instance"
        }
      ];

      // Output only. The instance connection name.
      string connection = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The unique DNS name for this instance.
      string dns = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The list of IP addresses for this instance.
      repeated IpMapping ip_mappings = 4
          [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Represents a task executed as part of the deployment on a target
    // instance.
    message DeploymentTask {
      // The type of the task.
      // This enum type `Type` is prone to change, and new values may be added
      // in the future.
      enum Type {
        // The default value. This value is used if the type is omitted.
        TYPE_UNSPECIFIED = 0;

        // Provisions the green environment, which includes creating the target
        // instance.
        PROVISION = 1;

        // Upgrades the green environment, for example, performing a major
        // version upgrade on the target instance.
        UPGRADE = 2;

        // Promotes the target instance and then demotes the source instance for
        // this pair.
        SWITCHOVER = 3;

        // Deletes the blue-green deployment, including underlying resources.
        DELETE = 4;

        // Post-switchover operations, including cleaning up resources of the
        // old instance, taking final backups, and updating metadata.
        POST_SWITCHOVER_OPERATIONS = 5;
      }

      // The state of the task.
      // This enum is not frozen, and new values may be added in the future.
      enum State {
        // The state of the task is unknown.
        STATE_UNSPECIFIED = 0;

        // The task is pending.
        PENDING = 1;

        // The task is running.
        RUNNING = 2;

        // The task has succeeded.
        SUCCEEDED = 3;

        // The task has failed.
        FAILED = 4;
      }

      // Output only. The type of the task.
      Type type = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The current state of the task.
      State state = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. Task start time.
      google.protobuf.Timestamp start_time = 3
          [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. Task end time (if completed).
      google.protobuf.Timestamp end_time = 4
          [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. Optional error details if the task state is `FAILED`.
      string error_message = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Output only. Specifies the resource name of the source instance in this
    // pair.
    NodeInfo source = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Specifies details of the corresponding target instance in
    // this pair.
    NodeInfo target = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Specifies the current state of this specific source-target
    // pair.
    State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Describes the list of differences for the
    // `SourceTargetPairedNode`.
    repeated ConfigDiff diffs = 100 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Output only. Identifier. The full resource name of the deployment.
  // Format:
  // projects/{project}/locations/{location}/blueGreenDeployments/{deployment_id}
  string name = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IDENTIFIER,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];

  // Optional. User-provided description for the deployment.
  // The description can be up to 255 characters long.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The time when the deployment was created.
  // Example: `2024-01-01T00:00:00Z`
  google.protobuf.Timestamp create_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The current state of the blue-green deployment.
  State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Immutable. Required on create, and immutable. The full resource
  // name of the source instance (the "blue" instance). Format:
  // projects/{project}/instances/{instance}
  string source_instance = 5 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/Instance"
    }
  ];

  // Output only. The full resource name of the primary target instance (the
  // "green" instance) that will be promoted during switchover. This field is
  // always populated once the deployment is created. Format:
  // projects/{project}/instances/{instance}
  string switchover_target_instance = 6 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/Instance"
    }
  ];

  // Output only. Provides details on why switchover is not possible.
  // This field is empty unless a switchover attempt failed or the state is
  // `SWITCHOVER_NOT_READY`.
  // Example: "The target database version does not match the source instance
  // database version."
  string error_detail = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A list representing the pairs of source and target instances
  // in the deployment.
  repeated SourceTargetPairedNode deployment_mappings = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Combined list of tasks for all paired nodes.
  DeploymentTasks deployment_tasks = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Immutable. Optional on create, and immutable. The configuration
  // intended for the target instance(s) when the deployment was created.
  RequestedConfig requested_config = 10 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IMMUTABLE
  ];
}

// The request message for creating a `BlueGreenDeployment` resource.
message CreateBlueGreenDeploymentRequest {
  // Required. The parent resource where this blue-green deployment will be
  // created. Format: projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];

  // Required. The ID to use for the blue-green deployment, which will become
  // the final component of the deployment's resource name. The ID must be
  // unique within the given project and location and between 2-63 characters.
  string blue_green_deployment_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The `BlueGreenDeployment` resource to create.
  BlueGreenDeployment blue_green_deployment = 3
      [(google.api.field_behavior) = REQUIRED];
}

// The request message for getting a BlueGreenDeployment.
message GetBlueGreenDeploymentRequest {
  // The view of a `BlueGreenDeployment` resource.
  enum BlueGreenDeploymentView {
    // Blue-green deployment view enumeration. This allows the caller to specify
    // what view they query. If unspecified
    // (BLUE_GREEN_DEPLOYMENT_VIEW_UNSPECIFIED), the behavior is the same as
    // BASIC.
    BLUE_GREEN_DEPLOYMENT_VIEW_UNSPECIFIED = 0;

    // Includes basic metadata about the blue-green deployment.
    // `BASIC` is the default view.
    BASIC = 1;

    // Includes basic metadata and configuration differences between source and
    // target instances (`database_version`, `tier`, `edition`,
    // `availability_type`, `data_disk_size_gb`, and `data_disk_type`).
    DETAILED = 2;
  }

  // Required. The name of the blue-green deployment to retrieve.
  // Format:
  // projects/{project}/locations/{location}/blueGreenDeployments/{blue_green_deployment}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];

  // Optional. Specifies whether to return the basic or detailed view of the
  // resource in the response.
  BlueGreenDeploymentView view = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for switching over a `BlueGreenDeployment` resource.
message SwitchoverBlueGreenDeploymentRequest {
  // Required. The name of the blue-green deployment to switch over.
  // Format:
  // projects/{project}/locations/{location}/blueGreenDeployments/{blue_green_deployment}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];
}

// The request message for listing blue-green deployment resources.
message ListBlueGreenDeploymentsRequest {
  // Required. The parent resource whose blue-green deployments are to be
  // listed. Format: projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];

  // Optional. The maximum number of deployments to return. The service may
  // return fewer deployments than this value. If unspecified, at most 500
  // deployments are returned. The maximum value is 1000; values above 1000
  // are treated as 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListBlueGreenDeployments`
  // call. Provide this to retrieve the subsequent page.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A filter expression that filters the results.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A comma-separated list of fields to order the results by.
  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for listing blue-green deployment resources.
message ListBlueGreenDeploymentsResponse {
  // The list of blue-green deployment resources.
  repeated BlueGreenDeployment blue_green_deployments = 1;

  // A token to retrieve the next page of results, or empty if there are no
  // more results.
  string next_page_token = 2;
}

// Request message for deleting a BlueGreenDeployment.
message DeleteBlueGreenDeploymentRequest {
  // Required. The name of the blue-green deployment to delete.
  // Format:
  // projects/{project}/locations/{location}/blueGreenDeployments/{blue_green_deployment}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "sqladmin.googleapis.com/BlueGreenDeployment"
    }
  ];

  // Optional. If set to true, and the switchover is complete, this deletes the
  // old source instance along with the deployment.
  bool delete_old_source = 2 [(google.api.field_behavior) = OPTIONAL];
}