googleapis/google/cloud/run/v2/instance.proto

// 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.run.v2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/launch_stage.proto";
import "google/api/resource.proto";
import "google/api/routing.proto";
import "google/cloud/run/v2/condition.proto";
import "google/cloud/run/v2/container_status.proto";
import "google/cloud/run/v2/k8s.min.proto";
import "google/cloud/run/v2/vendor_settings.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option go_package = "cloud.google.com/go/run/apiv2/runpb;runpb";
option java_multiple_files = true;
option java_package = "com.google.cloud.run.v2";

// The Cloud Run Instances API allows you to manage Cloud Run Instances.
service Instances {
  option (google.api.default_host) = "run.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Creates an Instance.
  rpc CreateInstance(CreateInstanceRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/locations/*}/instances"
      body: "instance"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "projects/*/locations/{location=*}"
      }
    };
    option (google.api.method_signature) = "parent,instance";
    option (google.longrunning.operation_info) = {
      response_type: "Instance"
      metadata_type: "Instance"
    };
  }

  // Deletes a Instance
  rpc DeleteInstance(DeleteInstanceRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v2/{name=projects/*/locations/*/instances/*}"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "projects/*/locations/{location=*}/**"
      }
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "Instance"
      metadata_type: "Instance"
    };
  }

  // Gets a Instance
  rpc GetInstance(GetInstanceRequest) returns (Instance) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/locations/*/instances/*}"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "projects/*/locations/{location=*}/**"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Lists Instances. Results are sorted by creation time, descending.
  rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/locations/*}/instances"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "projects/*/locations/{location=*}"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Stops an Instance.
  rpc StopInstance(StopInstanceRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{name=projects/*/locations/*/instances/*}:stop"
      body: "*"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "Instance"
      metadata_type: "Instance"
    };
  }

  // Starts an Instance.
  rpc StartInstance(StartInstanceRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{name=projects/*/locations/*/instances/*}:start"
      body: "*"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "Instance"
      metadata_type: "Instance"
    };
  }
}

message CreateInstanceRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "run.googleapis.com/Instance"
    }
  ];

  Instance instance = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The unique identifier for the Instance. It must begin with
  // letter, and cannot end with hyphen; must contain fewer than 50 characters.
  // The name of the instance becomes {parent}/instances/{instance_id}.
  string instance_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. Indicates that the request should be validated and default values
  // populated, without persisting the request or creating any resources.
  bool validate_only = 4 [(google.api.field_behavior) = OPTIONAL];
}

message GetInstanceRequest {
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/Instance" }
  ];
}

message DeleteInstanceRequest {
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/Instance" }
  ];

  // Optional. Indicates that the request should be validated without actually
  // deleting any resources.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A system-generated fingerprint for this version of the
  // resource. May be used to detect modification conflict during updates.
  string etag = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for retrieving a list of Instances.
message ListInstancesRequest {
  // Required. The location and project to list resources on.
  // Format: projects/{project}/locations/{location}, where {project} can be
  // project id or number.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "run.googleapis.com/Instance"
    }
  ];

  // Optional. Maximum number of Instances to return in this call.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous call to ListInstances.
  // All other parameters must match.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If true, returns deleted (but unexpired) resources along with
  // active ones.
  bool show_deleted = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message containing a list of Instances.
message ListInstancesResponse {
  // The resulting list of Instances.
  repeated Instance instances = 1;

  // A token indicating there are more items than page_size. Use it in the next
  // ListInstances request to continue.
  string next_page_token = 2;
}

// Request message for deleting an Instance.
message StopInstanceRequest {
  // Required. The name of the Instance to stop.
  // Format:
  // `projects/{project}/locations/{location}/instances/{instance}`,
  // where `{project}` can be project id or number.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/Instance" }
  ];

  // Optional. Indicates that the request should be validated without actually
  // stopping any resources.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A system-generated fingerprint for this version of the resource.
  // This may be used to detect modification conflict during updates.
  string etag = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for starting an Instance.
message StartInstanceRequest {
  // Required. The name of the Instance to stop.
  // Format:
  // `projects/{project}/locations/{location}/instances/{instance}`,
  // where `{project}` can be project id or number.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/Instance" }
  ];

  // Optional. Indicates that the request should be validated without actually
  // stopping any resources.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A system-generated fingerprint for this version of the resource.
  // This may be used to detect modification conflict during updates.
  string etag = 3 [(google.api.field_behavior) = OPTIONAL];
}

// A Cloud Run Instance represents a single group of containers running in a
// region.
message Instance {
  option (google.api.resource) = {
    type: "run.googleapis.com/Instance"
    pattern: "projects/{project}/locations/{location}/instances/{instance}"
    plural: "instances"
    singular: "instance"
  };

  // The fully qualified name of this Instance. In CreateInstanceRequest, this
  // field is ignored, and instead composed from CreateInstanceRequest.parent
  // and CreateInstanceRequest.instance_id.
  //
  // Format:
  // projects/{project}/locations/{location}/instances/{instance_id}
  string name = 1;

  // User-provided description of the Instance. This field currently has a
  // 512-character limit.
  string description = 3;

  // Output only. Server assigned unique identifier for the trigger. The value
  // is a UUID4 string and guaranteed to remain unchanged until the resource is
  // deleted.
  string uid = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A number that monotonically increases every time the user
  // modifies the desired state.
  // Please note that unlike v1, this is an int64 value. As with most Google
  // APIs, its JSON representation will be a `string` instead of an `integer`.
  int64 generation = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  map<string, string> labels = 6;

  map<string, string> annotations = 7;

  // Output only. The creation time.
  google.protobuf.Timestamp create_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The last-modified time.
  google.protobuf.Timestamp update_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The deletion time.
  google.protobuf.Timestamp delete_time = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. For a deleted resource, the time after which it will be
  // permamently deleted.
  google.protobuf.Timestamp expire_time = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Email address of the authenticated creator.
  string creator = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Email address of the last authenticated modifier.
  string last_modifier = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Arbitrary identifier for the API client.
  string client = 14;

  // Arbitrary version identifier for the API client.
  string client_version = 15;

  // The launch stage as defined by [Google Cloud Platform
  //  Launch Stages](https://cloud.google.com/terms/launch-stages).
  //  Cloud Run supports `ALPHA`, `BETA`, and `GA`. If no value is specified, GA
  //  is assumed.
  //  Set the launch stage to a preview stage on input to allow use of preview
  //  features in that stage. On read (or output), describes whether the
  //  resource uses preview features.
  // <p>
  //  For example, if ALPHA is provided as input, but only BETA and GA-level
  //  features are used, this field will be BETA on output.
  google.api.LaunchStage launch_stage = 16;

  // Settings for the Binary Authorization feature.
  BinaryAuthorization binary_authorization = 17;

  // Optional. VPC Access configuration to use for this Revision. For more
  // information, visit
  // https://cloud.google.com/run/docs/configuring/connecting-vpc.
  VpcAccess vpc_access = 18 [(google.api.field_behavior) = OPTIONAL];

  string service_account = 19;

  // Required. Holds the single container that defines the unit of execution for
  // this Instance.
  repeated Container containers = 20 [(google.api.field_behavior) = REQUIRED];

  // A list of Volumes to make available to containers.
  repeated Volume volumes = 21;

  // A reference to a customer managed encryption key (CMEK) to use to encrypt
  // this container image. For more information, go to
  // https://cloud.google.com/run/docs/securing/using-cmek
  string encryption_key = 22 [(google.api.resource_reference) = {
    type: "cloudkms.googleapis.com/CryptoKey"
  }];

  // The action to take if the encryption key is revoked.
  EncryptionKeyRevocationAction encryption_key_revocation_action = 24;

  // If encryption_key_revocation_action is SHUTDOWN, the duration before
  // shutting down all instances. The minimum increment is 1 hour.
  google.protobuf.Duration encryption_key_shutdown_duration = 25;

  // Optional. The node selector for the instance.
  NodeSelector node_selector = 26 [(google.api.field_behavior) = OPTIONAL];

  // Optional. True if GPU zonal redundancy is disabled on this instance.
  optional bool gpu_zonal_redundancy_disabled = 27
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Provides the ingress settings for this Instance. On output,
  // returns the currently observed ingress settings, or
  // INGRESS_TRAFFIC_UNSPECIFIED if no revision is active.
  IngressTraffic ingress = 28 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Disables IAM permission check for run.routes.invoke for callers
  // of this Instance. For more information, visit
  // https://cloud.google.com/run/docs/securing/managing-access#invoker_check.
  bool invoker_iam_disabled = 29 [(google.api.field_behavior) = OPTIONAL];

  // Optional. IAP settings on the Instance.
  bool iap_enabled = 30 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The generation of this Instance currently serving traffic. See
  // comments in `reconciling` for additional information on reconciliation
  // process in Cloud Run. Please note that unlike v1, this is an int64 value.
  // As with most Google APIs, its JSON representation will be a `string`
  // instead of an `integer`.
  int64 observed_generation = 40 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Google Console URI to obtain logs for the Instance.
  string log_uri = 41 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Condition of this Instance, containing its readiness
  // status, and detailed error information in case it did not reach a serving
  // state. See comments in `reconciling` for additional information on
  // reconciliation process in Cloud Run.
  Condition terminal_condition = 42 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Conditions of all other associated sub-resources. They
  // contain additional diagnostics information in case the Instance does not
  // reach its Serving state. See comments in `reconciling` for additional
  // information on reconciliation process in Cloud Run.
  repeated Condition conditions = 43
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Status information for each of the specified containers. The
  // status includes the resolved digest for specified images.
  repeated ContainerStatus container_statuses = 44
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Reserved for future use.
  bool satisfies_pzs = 46 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. All URLs serving traffic for this Instance.
  repeated string urls = 45 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Returns true if the Instance is currently being acted upon by
  // the system to bring it into the desired state.
  //
  // When a new Instance is created, or an existing one is updated, Cloud Run
  // will asynchronously perform all necessary steps to bring the Instance to
  // the desired serving state. This process is called reconciliation. While
  // reconciliation is in process, `observed_generation` will have a transient
  // value that might mismatch the intended state.
  //  Once reconciliation is over (and this field is false), there are two
  // possible outcomes: reconciliation succeeded and the serving state matches
  // the Instance, or there was an error, and reconciliation failed. This state
  // can be found in `terminal_condition.state`.
  bool reconciling = 98 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. A system-generated fingerprint for this version of the
  // resource. May be used to detect modification conflict during updates.
  string etag = 99 [(google.api.field_behavior) = OPTIONAL];
}