// 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.v1beta4;

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/v1beta4/cloud_sql_resources.proto";
import "google/protobuf/timestamp.proto";

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

// 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. This
  // deployment provisions a synchronized green environment (target instance)
  // from a blue production environment (source instance), facilitating updates
  // like major version upgrades on the green instance without impacting the
  // blue instance.
  rpc CreateBlueGreenDeployment(CreateBlueGreenDeploymentRequest)
      returns (Operation) {
    option (google.api.http) = {
      post: "/sql/v1beta4/{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: "/sql/v1beta4/{name=projects/*/locations/*/blueGreenDeployments/*}"
    };
    option (google.api.method_signature) = "name";
  }

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

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

  // Deletes a blue-green deployment, including metadata and underlying
  // resources based on the deployment state. If issued before switchover,
  // this deletes the green instance. If issued after switchover, this deletes
  // the old blue instance (source instance) if the `delete_old_source` field
  // in the request is set to true.
  // All blue-green deployment metadata is permanently deleted.
  // Resources deleted as a result of this operation are no longer accessible
  // and can't be restored.
  rpc DeleteBlueGreenDeployment(DeleteBlueGreenDeploymentRequest)
      returns (Operation) {
    option (google.api.http) = {
      delete: "/sql/v1beta4/{name=projects/*/locations/*/blueGreenDeployments/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// A `BlueGreenDeployment` resource represents a Cloud SQL blue-green deployment
// setup. It orchestrates the lifecycle of creating a synchronized "green"
// environment from a "blue" production environment, performing updates, and
// managing the switchover process to minimize downtime.
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.
  // This enum is not frozen, and new values may be added in the future.
  enum State {
    // The state of the deployment is 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;
  }

  // Deprecated: Use RequestedConfig instead.
  // Configuration specified by the user at creation time for the target (Green)
  // instance.
  message TargetConfig {
    option deprecated = true;

    // Optional. The target database major version for the upgrade.
    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];
  }

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

  // 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;
    }

    // The instance currently serving traffic.
    enum CurrentlyServingTraffic {
      // The instance serving traffic is unknown.
      CURRENTLY_SERVING_TRAFFIC_UNSPECIFIED = 0;

      // The source instance is serving traffic.
      SOURCE = 1;

      // The target instance is serving traffic.
      TARGET = 2;
    }

    // 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];

      // 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 is not frozen, 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;

        // Creating target instance.
        PROVISION = 1;

        // e.g., Major Version Upgrade on Target.
        UPGRADE = 2;

        // Promoting Target, Demoting Source for this pair.
        SWITCHOVER = 3;

        // The task is to delete deployment.
        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];
    }

    // Represents a specific configuration difference between Blue and Green
    // instances.
    message ConfigDiff {
      // Output only. The name of the field that differs, 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];
    }

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

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

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

    // Output only. Deprecated: Indicates which instance (SOURCE or TARGET) in
    // the pair is currently live. Used for internal implementation and
    // deprecated for external use.
    CurrentlyServingTraffic currently_serving_traffic = 4
        [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Tasks performed or being performed on the target instance of
    // this pair.
    repeated DeploymentTask tasks = 5
        [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Describes the list of differences for this pair.
    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
  ];

  // Optional. User-provided description for the deployment.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The time when the deployment was created.
  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. The instance ID of the source instance (the "blue"
  // instance). The value for this field does not include the project ID, for
  // example, `my-instance-id`. This field is immutable.
  string source_instance = 5 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Optional. Immutable. Deprecated: Use requested_config instead.
  // The configuration intended for the target instance(s) when the deployment
  // was created. This field is immutable.
  TargetConfig target_config = 6 [
    deprecated = true,
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. Details about the primary target instance (the "Green"
  // instance) that will be promoted during switchover.
  string switchover_target_instance = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Deprecated: Use deployment_mappings instead.
  // Output only. A list representing the pairs of source and target instances
  // in the deployment.
  repeated SourceTargetPairedNode paired_nodes = 8
      [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides an error message with details on why switchover is
  // not possible.
  string error_detail = 9 [(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 = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Combined list of tasks for all paired nodes.
  DeploymentTasks deployment_tasks = 11
      [(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 = 12 [
    (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.
  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` resource.
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];
}

// 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.
  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];
}

// 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"
    }
  ];
}

// Request message for deleting a `BlueGreenDeployment` resource.
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];
}

// 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;
}