You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
388 lines
15 KiB
388 lines
15 KiB
// Copyright 2021 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.shell.v1; |
|
|
|
import "google/api/annotations.proto"; |
|
import "google/api/client.proto"; |
|
import "google/api/field_behavior.proto"; |
|
import "google/api/resource.proto"; |
|
import "google/longrunning/operations.proto"; |
|
import "google/protobuf/field_mask.proto"; |
|
import "google/protobuf/timestamp.proto"; |
|
|
|
option go_package = "google.golang.org/genproto/googleapis/cloud/shell/v1;shell"; |
|
option java_multiple_files = true; |
|
option java_outer_classname = "CloudShellProto"; |
|
option java_package = "com.google.cloud.shell.v1"; |
|
|
|
// API for interacting with Google Cloud Shell. Each user of Cloud Shell has at |
|
// least one environment, which has the ID "default". Environment consists of a |
|
// Docker image defining what is installed on the environment and a home |
|
// directory containing the user's data that will remain across sessions. |
|
// Clients use this API to start and fetch information about their environment, |
|
// which can then be used to connect to that environment via a separate SSH |
|
// client. |
|
service CloudShellService { |
|
option (google.api.default_host) = "cloudshell.googleapis.com"; |
|
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; |
|
|
|
// Gets an environment. Returns NOT_FOUND if the environment does not exist. |
|
rpc GetEnvironment(GetEnvironmentRequest) returns (Environment) { |
|
option (google.api.http) = { |
|
get: "/v1/{name=users/*/environments/*}" |
|
}; |
|
option (google.api.method_signature) = "name"; |
|
} |
|
|
|
// Starts an existing environment, allowing clients to connect to it. The |
|
// returned operation will contain an instance of StartEnvironmentMetadata in |
|
// its metadata field. Users can wait for the environment to start by polling |
|
// this operation via GetOperation. Once the environment has finished starting |
|
// and is ready to accept connections, the operation will contain a |
|
// StartEnvironmentResponse in its response field. |
|
rpc StartEnvironment(StartEnvironmentRequest) returns (google.longrunning.Operation) { |
|
option (google.api.http) = { |
|
post: "/v1/{name=users/*/environments/*}:start" |
|
body: "*" |
|
}; |
|
option (google.longrunning.operation_info) = { |
|
response_type: "StartEnvironmentResponse" |
|
metadata_type: "StartEnvironmentMetadata" |
|
}; |
|
} |
|
|
|
// Sends OAuth credentials to a running environment on behalf of a user. When |
|
// this completes, the environment will be authorized to run various Google |
|
// Cloud command line tools without requiring the user to manually |
|
// authenticate. |
|
rpc AuthorizeEnvironment(AuthorizeEnvironmentRequest) returns (google.longrunning.Operation) { |
|
option (google.api.http) = { |
|
post: "/v1/{name=users/*/environments/*}:authorize" |
|
body: "*" |
|
}; |
|
option (google.longrunning.operation_info) = { |
|
response_type: "AuthorizeEnvironmentResponse" |
|
metadata_type: "AuthorizeEnvironmentMetadata" |
|
}; |
|
} |
|
|
|
// Adds a public SSH key to an environment, allowing clients with the |
|
// corresponding private key to connect to that environment via SSH. If a key |
|
// with the same content already exists, this will error with ALREADY_EXISTS. |
|
rpc AddPublicKey(AddPublicKeyRequest) returns (google.longrunning.Operation) { |
|
option (google.api.http) = { |
|
post: "/v1/{environment=users/*/environments/*}:addPublicKey" |
|
body: "*" |
|
}; |
|
option (google.longrunning.operation_info) = { |
|
response_type: "AddPublicKeyResponse" |
|
metadata_type: "AddPublicKeyMetadata" |
|
}; |
|
} |
|
|
|
// Removes a public SSH key from an environment. Clients will no longer be |
|
// able to connect to the environment using the corresponding private key. |
|
// If a key with the same content is not present, this will error with |
|
// NOT_FOUND. |
|
rpc RemovePublicKey(RemovePublicKeyRequest) returns (google.longrunning.Operation) { |
|
option (google.api.http) = { |
|
post: "/v1/{environment=users/*/environments/*}:removePublicKey" |
|
body: "*" |
|
}; |
|
option (google.longrunning.operation_info) = { |
|
response_type: "RemovePublicKeyResponse" |
|
metadata_type: "RemovePublicKeyMetadata" |
|
}; |
|
} |
|
} |
|
|
|
// A Cloud Shell environment, which is defined as the combination of a Docker |
|
// image specifying what is installed on the environment and a home directory |
|
// containing the user's data that will remain across sessions. Each user has |
|
// at least an environment with the ID "default". |
|
message Environment { |
|
option (google.api.resource) = { |
|
type: "cloudshell.googleapis.com/Environment" |
|
pattern: "users/{user}/environments/{environment}" |
|
}; |
|
|
|
// Possible execution states for an environment. |
|
enum State { |
|
// The environment's states is unknown. |
|
STATE_UNSPECIFIED = 0; |
|
|
|
// The environment is not running and can't be connected to. Starting the |
|
// environment will transition it to the PENDING state. |
|
SUSPENDED = 1; |
|
|
|
// The environment is being started but is not yet ready to accept |
|
// connections. |
|
PENDING = 2; |
|
|
|
// The environment is running and ready to accept connections. It will |
|
// automatically transition back to DISABLED after a period of inactivity or |
|
// if another environment is started. |
|
RUNNING = 3; |
|
|
|
// The environment is being deleted and can't be connected to. |
|
DELETING = 4; |
|
} |
|
|
|
// Immutable. Full name of this resource, in the format |
|
// `users/{owner_email}/environments/{environment_id}`. `{owner_email}` is the |
|
// email address of the user to whom this environment belongs, and |
|
// `{environment_id}` is the identifier of this environment. For example, |
|
// `users/someone@example.com/environments/default`. |
|
string name = 1 [(google.api.field_behavior) = IMMUTABLE]; |
|
|
|
// Output only. The environment's identifier, unique among the user's |
|
// environments. |
|
string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Required. Immutable. Full path to the Docker image used to run this environment, e.g. |
|
// "gcr.io/dev-con/cloud-devshell:latest". |
|
string docker_image = 3 [ |
|
(google.api.field_behavior) = REQUIRED, |
|
(google.api.field_behavior) = IMMUTABLE |
|
]; |
|
|
|
// Output only. Current execution state of this environment. |
|
State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Output only. Host to which clients can connect to initiate HTTPS or WSS |
|
// connections with the environment. |
|
string web_host = 12 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Output only. Username that clients should use when initiating SSH sessions |
|
// with the environment. |
|
string ssh_username = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Output only. Host to which clients can connect to initiate SSH sessions |
|
// with the environment. |
|
string ssh_host = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Output only. Port to which clients can connect to initiate SSH sessions |
|
// with the environment. |
|
int32 ssh_port = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
|
|
// Output only. Public keys associated with the environment. Clients can |
|
// connect to this environment via SSH only if they possess a private key |
|
// corresponding to at least one of these public keys. Keys can be added to or |
|
// removed from the environment using the AddPublicKey and RemovePublicKey |
|
// methods. |
|
repeated string public_keys = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; |
|
} |
|
|
|
// Request message for |
|
// [GetEnvironment][google.cloud.shell.v1.CloudShellService.GetEnvironment]. |
|
message GetEnvironmentRequest { |
|
// Required. Name of the requested resource, for example `users/me/environments/default` |
|
// or `users/someone@example.com/environments/default`. |
|
string name = 1 [ |
|
(google.api.field_behavior) = REQUIRED, |
|
(google.api.resource_reference) = { |
|
type: "cloudshell.googleapis.com/Environment" |
|
} |
|
]; |
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [CreateEnvironment][google.cloud.shell.v1.CloudShellService.CreateEnvironment]. |
|
message CreateEnvironmentMetadata { |
|
|
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [DeleteEnvironment][google.cloud.shell.v1.CloudShellService.DeleteEnvironment]. |
|
message DeleteEnvironmentMetadata { |
|
|
|
} |
|
|
|
// Request message for |
|
// [StartEnvironment][google.cloud.shell.v1.CloudShellService.StartEnvironment]. |
|
message StartEnvironmentRequest { |
|
// Name of the resource that should be started, for example |
|
// `users/me/environments/default` or |
|
// `users/someone@example.com/environments/default`. |
|
string name = 1; |
|
|
|
// The initial access token passed to the environment. If this is present and |
|
// valid, the environment will be pre-authenticated with gcloud so that the |
|
// user can run gcloud commands in Cloud Shell without having to log in. This |
|
// code can be updated later by calling AuthorizeEnvironment. |
|
string access_token = 2; |
|
|
|
// Public keys that should be added to the environment before it is started. |
|
repeated string public_keys = 3; |
|
} |
|
|
|
// Request message for |
|
// [AuthorizeEnvironment][google.cloud.shell.v1.CloudShellService.AuthorizeEnvironment]. |
|
message AuthorizeEnvironmentRequest { |
|
// Name of the resource that should receive the credentials, for example |
|
// `users/me/environments/default` or |
|
// `users/someone@example.com/environments/default`. |
|
string name = 1; |
|
|
|
// The OAuth access token that should be sent to the environment. |
|
string access_token = 2; |
|
|
|
// The OAuth ID token that should be sent to the environment. |
|
string id_token = 4; |
|
|
|
// The time when the credentials expire. If not set, defaults to one hour from |
|
// when the server received the request. |
|
google.protobuf.Timestamp expire_time = 3; |
|
} |
|
|
|
// Response message for |
|
// [AuthorizeEnvironment][google.cloud.shell.v1.CloudShellService.AuthorizeEnvironment]. |
|
message AuthorizeEnvironmentResponse { |
|
|
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [AuthorizeEnvironment][google.cloud.shell.v1.CloudShellService.AuthorizeEnvironment]. |
|
message AuthorizeEnvironmentMetadata { |
|
|
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [StartEnvironment][google.cloud.shell.v1.CloudShellService.StartEnvironment]. |
|
message StartEnvironmentMetadata { |
|
// Possible states an environment might transition between during startup. |
|
// These states are not normally actionable by clients, but may be used to |
|
// show a progress message to the user. An environment won't necessarily go |
|
// through all of these states when starting. More states are likely to be |
|
// added in the future. |
|
enum State { |
|
// The environment's start state is unknown. |
|
STATE_UNSPECIFIED = 0; |
|
|
|
// The environment is in the process of being started, but no additional |
|
// details are available. |
|
STARTING = 1; |
|
|
|
// Startup is waiting for the user's disk to be unarchived. This can happen |
|
// when the user returns to Cloud Shell after not having used it for a |
|
// while, and suggests that startup will take longer than normal. |
|
UNARCHIVING_DISK = 2; |
|
|
|
// Startup is waiting for compute resources to be assigned to the |
|
// environment. This should normally happen very quickly, but an environment |
|
// might stay in this state for an extended period of time if the system is |
|
// experiencing heavy load. |
|
AWAITING_COMPUTE_RESOURCES = 4; |
|
|
|
// Startup has completed. If the start operation was successful, the user |
|
// should be able to establish an SSH connection to their environment. |
|
// Otherwise, the operation will contain details of the failure. |
|
FINISHED = 3; |
|
} |
|
|
|
// Current state of the environment being started. |
|
State state = 1; |
|
} |
|
|
|
// Message included in the response field of operations returned from |
|
// [StartEnvironment][google.cloud.shell.v1.CloudShellService.StartEnvironment] |
|
// once the operation is complete. |
|
message StartEnvironmentResponse { |
|
// Environment that was started. |
|
Environment environment = 1; |
|
} |
|
|
|
// Request message for |
|
// [AddPublicKey][google.cloud.shell.v1.CloudShellService.AddPublicKey]. |
|
message AddPublicKeyRequest { |
|
// Environment this key should be added to, e.g. |
|
// `users/me/environments/default`. |
|
string environment = 1; |
|
|
|
// Key that should be added to the environment. Supported formats are |
|
// `ssh-dss` (see RFC4253), `ssh-rsa` (see RFC4253), `ecdsa-sha2-nistp256` |
|
// (see RFC5656), `ecdsa-sha2-nistp384` (see RFC5656) and |
|
// `ecdsa-sha2-nistp521` (see RFC5656). It should be structured as |
|
// <format> <content>, where <content> part is encoded with |
|
// Base64. |
|
string key = 2; |
|
} |
|
|
|
// Response message for |
|
// [AddPublicKey][google.cloud.shell.v1.CloudShellService.AddPublicKey]. |
|
message AddPublicKeyResponse { |
|
// Key that was added to the environment. |
|
string key = 1; |
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [AddPublicKey][google.cloud.shell.v1.CloudShellService.AddPublicKey]. |
|
message AddPublicKeyMetadata { |
|
|
|
} |
|
|
|
// Request message for |
|
// [RemovePublicKey][google.cloud.shell.v1.CloudShellService.RemovePublicKey]. |
|
message RemovePublicKeyRequest { |
|
// Environment this key should be removed from, e.g. |
|
// `users/me/environments/default`. |
|
string environment = 1; |
|
|
|
// Key that should be removed from the environment. |
|
string key = 2; |
|
} |
|
|
|
// Response message for |
|
// [RemovePublicKey][google.cloud.shell.v1.CloudShellService.RemovePublicKey]. |
|
message RemovePublicKeyResponse { |
|
|
|
} |
|
|
|
// Message included in the metadata field of operations returned from |
|
// [RemovePublicKey][google.cloud.shell.v1.CloudShellService.RemovePublicKey]. |
|
message RemovePublicKeyMetadata { |
|
|
|
} |
|
|
|
// Cloud-shell specific information that will be included as details in failure |
|
// responses. |
|
message CloudShellErrorDetails { |
|
// Set of possible errors returned from API calls. |
|
enum CloudShellErrorCode { |
|
// An unknown error occurred. |
|
CLOUD_SHELL_ERROR_CODE_UNSPECIFIED = 0; |
|
|
|
// The image used by the Cloud Shell environment either does not exist or |
|
// the user does not have access to it. |
|
IMAGE_UNAVAILABLE = 1; |
|
|
|
// Cloud Shell has been disabled by an administrator for the user making the |
|
// request. |
|
CLOUD_SHELL_DISABLED = 2; |
|
|
|
// Cloud Shell has been permanently disabled due to a Terms of Service |
|
// violation by the user. |
|
TOS_VIOLATION = 4; |
|
|
|
// The user has exhausted their weekly Cloud Shell quota, and Cloud Shell |
|
// will be disabled until the quota resets. |
|
QUOTA_EXCEEDED = 5; |
|
} |
|
|
|
// Code indicating the specific error the occurred. |
|
CloudShellErrorCode code = 1; |
|
}
|
|
|