Package google.cloud.shell.v1alpha1

Index

CloudShellService

API for interacting with Google Cloud Shell. Each user of Cloud Shell has one environment, which has the ID "default". That 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.

AuthorizeEnvironment

rpc AuthorizeEnvironment(AuthorizeEnvironmentRequest) returns (Empty)

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.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

CreatePublicKey

rpc CreatePublicKey(CreatePublicKeyRequest) returns (PublicKey)

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 format and content already exists, this will return the existing key.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

DeletePublicKey

rpc DeletePublicKey(DeletePublicKeyRequest) returns (Empty)

Removes a public SSH key from an environment. Clients will no longer be able to connect to the environment using the corresponding private key.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

GetEnvironment

rpc GetEnvironment(GetEnvironmentRequest) returns (Environment)

Gets an environment. Returns NOT_FOUND if the environment does not exist.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

StartEnvironment

rpc StartEnvironment(StartEnvironmentRequest) returns (Operation)

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.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

UpdateEnvironment

rpc UpdateEnvironment(UpdateEnvironmentRequest) returns (Environment)

Updates an existing environment.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

AuthorizeEnvironmentRequest

Request message for [AuthorizeEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.AuthorizeEnvironment].

Fields
name

string

Name of the resource that should receive the credentials, for example users/me/environments/default or users/someone@example.com/environments/default.

access_token

string

The OAuth access token that should be sent to the environment.

id_token

string

The OAuth ID token that should be sent to the environment.

expire_time

Timestamp

The time when the credentials expire. If not set, defaults to one hour from when the server received the request.

CloudShellErrorDetails

Cloud-shell specific information that will be included as details in failure responses.

Fields
code

CloudShellErrorCode

Code indicating the specific error the occurred.

CloudShellErrorCode

Set of possible errors returned from API calls.

Enums
CLOUD_SHELL_ERROR_CODE_UNSPECIFIED An unknown error occurred.
IMAGE_UNAVAILABLE The image used by the Cloud Shell environment either does not exist or the user does not have access to it.
CLOUD_SHELL_DISABLED Cloud Shell has been disabled for the user making the request.

CreatePublicKeyRequest

Request message for [CreatePublicKey] [goog.cloud.shell.v1alpha1.CloudShellService.CreatePublicKey].

Fields
parent

string

Parent resource name, e.g. users/me/environments/default.

key

PublicKey

Key that should be added to the environment.

DeletePublicKeyRequest

Request message for [DeletePublicKey] [goog.cloud.shell.v1alpha1.CloudShellService.DeletePublicKey].

Fields
name

string

Name of the resource to be deleted, e.g. users/me/environments/default/publicKeys/my-key.

Environment

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 a single environment with the ID "default".

Fields
name

string

Output only. 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.

id

string

Output only. The environment's identifier, which is always "default".

docker_image

string

Required. Full path to the Docker image used to run this environment, e.g. "gcr.io/dev-con/cloud-devshell:latest".

state

State

Output only. Current execution state of this environment.

ssh_username

string

Output only. Username that clients should use when initiating SSH sessions with the environment.

ssh_host

string

Output only. Host to which clients can connect to initiate SSH sessions with the environment.

ssh_port

int32

Output only. Port to which clients can connect to initiate SSH sessions with the environment.

public_keys[]

PublicKey

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 CreatePublicKey and DeletePublicKey methods.

State

Possible execution states for an environment.

Enums
STATE_UNSPECIFIED The environment's states is unknown.
DISABLED The environment is not running and can't be connected to. Starting the environment will transition it to the STARTING state.
STARTING The environment is being started but is not yet ready to accept connections.
RUNNING 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.

GetEnvironmentRequest

Request message for [GetEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.GetEnvironment].

Fields
name

string

Name of the requested resource, for example users/me/environments/default or users/someone@example.com/environments/default.

PublicKey

A public SSH key, corresponding to a private SSH key held by the client.

Fields
name

string

Output only. Full name of this resource, in the format users/{owner_email}/environments/{environment_id}/publicKeys/{key_id}. {owner_email} is the email address of the user to whom the key belongs. {environment_id} is the identifier of the environment to which the key grants access. {key_id} is the unique identifier of the key. For example, users/someone@example.com/environments/default/publicKeys/myKey.

format

Format

Required. Format of this key's content.

key

bytes

Required. Content of this key.

Format

Supported public key format.

Enums
FORMAT_UNSPECIFIED Unknown format. Do not use.
SSH_DSS ssh-dss key format (see RFC4253).
SSH_RSA ssh-rsa key format (see RFC4253).
ECDSA_SHA2_NISTP256 ecdsa-sha2-nistp256 key format (see RFC5656).
ECDSA_SHA2_NISTP384 ecdsa-sha2-nistp384 key format (see RFC5656).
ECDSA_SHA2_NISTP521 ecdsa-sha2-nistp521 key format (see RFC5656).

StartEnvironmentMetadata

Message included in the metadata field of operations returned from [StartEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.StartEnvironment].

Fields
state

State

Current state of the environment being started.

State

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.

Enums
STATE_UNSPECIFIED The environment's start state is unknown.
STARTING The environment is in the process of being started, but no additional details are available.
UNARCHIVING_DISK 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.
FINISHED Startup is complete and the user should be able to establish an SSH connection to their environment.

StartEnvironmentRequest

Request message for [StartEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.StartEnvironment].

Fields
name

string

Name of the resource that should be started, for example users/me/environments/default or users/someone@example.com/environments/default.

access_token

string

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.

StartEnvironmentResponse

Message included in the response field of operations returned from [StartEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.StartEnvironment] once the operation is complete.

Fields
environment

Environment

Environment that was started.

UpdateEnvironmentRequest

Request message for [UpdateEnvironment] [goog.cloud.shell.v1alpha1.CloudShellService.UpdateEnvironment].

Fields
name

string

Name of the resource to be updated, for example users/me/environments/default or users/someone@example.com/environments/default.

environment

Environment

Environment that should replace the existing environment.

update_mask

FieldMask

Mask specifying which fields in the environment should be updated.