or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/cloud.google.com/go/compute@v1.53.0

docs

clients

disks.mdinstances.mdload-balancing.mdnetworks.mdoperations.mdother-clients.mdregional.mdsecurity.mdstorage.md
index.mdmetadata.mdtypes.md
tile.json

tessl/golang-cloud-google-com--go--compute

tessl install tessl/golang-cloud-google-com--go--compute@1.53.0

Go client library for Google Cloud Compute Engine API providing programmatic access to manage virtual machines, disks, networks, and other compute resources

operations.mddocs/clients/

Operations Management

Operations clients track and manage long-running operations at global, regional, and zonal scopes. Most mutating operations in Google Compute Engine return an Operation object that can be polled for status.

Operation Type

The Operation type represents a long-running operation returned by mutating API calls.

type Operation struct {
    // contains filtered or unexported fields
}

// Done reports whether the long-running operation has completed
func (o *Operation) Done() bool

// Name returns the name of the long-running operation
func (o *Operation) Name() string

// Wait blocks until the operation completes or the context is done
func (o *Operation) Wait(ctx context.Context, opts ...gax.CallOption) error

// Poll checks the current status of the operation without blocking
func (o *Operation) Poll(ctx context.Context, opts ...gax.CallOption) error

Example - Wait for Operation:

import (
    "context"
    "cloud.google.com/go/compute/apiv1/computepb"
)

// Create an instance
insertReq := &computepb.InsertInstanceRequest{
    Project: "my-project",
    Zone:    "us-central1-a",
    InstanceResource: &computepb.Instance{
        // ... instance configuration
    },
}
op, err := instancesClient.Insert(ctx, insertReq)
if err != nil {
    // handle error
}

// Wait for the operation to complete
err = op.Wait(ctx)
if err != nil {
    // operation failed
}
// Instance is now created

Example - Poll Operation Status:

op, err := instancesClient.Start(ctx, startReq)
if err != nil {
    // handle error
}

// Poll without blocking
for !op.Done() {
    err = op.Poll(ctx)
    if err != nil {
        // handle error
    }
    if !op.Done() {
        time.Sleep(2 * time.Second)
    }
}

Global Operations Client

The GlobalOperationsClient manages global operations that are not tied to a specific zone or region.

Client Creation

func NewGlobalOperationsRESTClient(ctx context.Context, opts ...option.ClientOption) (*GlobalOperationsClient, error)

Example:

import (
    "context"
    compute "cloud.google.com/go/compute/apiv1"
)

ctx := context.Background()
client, err := compute.NewGlobalOperationsRESTClient(ctx)
if err != nil {
    // handle error
}
defer client.Close()

Global Operation Operations

// Get retrieves a specific global operation
func (c *GlobalOperationsClient) Get(ctx context.Context, req *computepb.GetGlobalOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

// List returns an iterator over global operations
func (c *GlobalOperationsClient) List(ctx context.Context, req *computepb.ListGlobalOperationsRequest, opts ...gax.CallOption) *OperationIterator

// AggregatedList returns an iterator over operations across all scopes
func (c *GlobalOperationsClient) AggregatedList(ctx context.Context, req *computepb.AggregatedListGlobalOperationsRequest, opts ...gax.CallOption) *OperationsScopedListPairIterator

// Delete deletes a completed global operation
func (c *GlobalOperationsClient) Delete(ctx context.Context, req *computepb.DeleteGlobalOperationRequest, opts ...gax.CallOption) (*computepb.DeleteGlobalOperationResponse, error)

// Wait polls for a global operation to complete
func (c *GlobalOperationsClient) Wait(ctx context.Context, req *computepb.WaitGlobalOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

Example - Get Operation Status:

getReq := &computepb.GetGlobalOperationRequest{
    Project:   "my-project",
    Operation: "operation-1234567890",
}
operation, err := client.Get(ctx, getReq)
if err != nil {
    // handle error
}
fmt.Printf("Operation status: %s\n", *operation.Status)

Example - List Recent Operations:

import "google.golang.org/api/iterator"

listReq := &computepb.ListGlobalOperationsRequest{
    Project: "my-project",
}
it := client.List(ctx, listReq)
for {
    op, err := it.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        // handle error
    }
    fmt.Printf("Operation: %s, Status: %s, Type: %s\n",
        *op.Name, *op.Status, *op.OperationType)
}

Region Operations Client

The RegionOperationsClient manages operations scoped to a specific region.

Client Creation

func NewRegionOperationsRESTClient(ctx context.Context, opts ...option.ClientOption) (*RegionOperationsClient, error)

Region Operation Operations

// Get retrieves a specific regional operation
func (c *RegionOperationsClient) Get(ctx context.Context, req *computepb.GetRegionOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

// List returns an iterator over regional operations
func (c *RegionOperationsClient) List(ctx context.Context, req *computepb.ListRegionOperationsRequest, opts ...gax.CallOption) *OperationIterator

// Delete deletes a completed regional operation
func (c *RegionOperationsClient) Delete(ctx context.Context, req *computepb.DeleteRegionOperationRequest, opts ...gax.CallOption) (*computepb.DeleteRegionOperationResponse, error)

// Wait polls for a regional operation to complete
func (c *RegionOperationsClient) Wait(ctx context.Context, req *computepb.WaitRegionOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

Example - Get Regional Operation:

getReq := &computepb.GetRegionOperationRequest{
    Project:   "my-project",
    Region:    "us-central1",
    Operation: "operation-1234567890",
}
operation, err := client.Get(ctx, getReq)

Zone Operations Client

The ZoneOperationsClient manages operations scoped to a specific zone.

Client Creation

func NewZoneOperationsRESTClient(ctx context.Context, opts ...option.ClientOption) (*ZoneOperationsClient, error)

Zone Operation Operations

// Get retrieves a specific zonal operation
func (c *ZoneOperationsClient) Get(ctx context.Context, req *computepb.GetZoneOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

// List returns an iterator over zonal operations
func (c *ZoneOperationsClient) List(ctx context.Context, req *computepb.ListZoneOperationsRequest, opts ...gax.CallOption) *OperationIterator

// Delete deletes a completed zonal operation
func (c *ZoneOperationsClient) Delete(ctx context.Context, req *computepb.DeleteZoneOperationRequest, opts ...gax.CallOption) (*computepb.DeleteZoneOperationResponse, error)

// Wait polls for a zonal operation to complete
func (c *ZoneOperationsClient) Wait(ctx context.Context, req *computepb.WaitZoneOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

Example - Get Zonal Operation:

getReq := &computepb.GetZoneOperationRequest{
    Project:   "my-project",
    Zone:      "us-central1-a",
    Operation: "operation-1234567890",
}
operation, err := client.Get(ctx, getReq)

Global Organization Operations Client

The GlobalOrganizationOperationsClient manages organization-level global operations.

Client Creation

func NewGlobalOrganizationOperationsRESTClient(ctx context.Context, opts ...option.ClientOption) (*GlobalOrganizationOperationsClient, error)

Global Organization Operation Operations

// Get retrieves a specific global organization operation
func (c *GlobalOrganizationOperationsClient) Get(ctx context.Context, req *computepb.GetGlobalOrganizationOperationRequest, opts ...gax.CallOption) (*computepb.Operation, error)

// List returns an iterator over global organization operations
func (c *GlobalOrganizationOperationsClient) List(ctx context.Context, req *computepb.ListGlobalOrganizationOperationsRequest, opts ...gax.CallOption) *OperationIterator

// Delete deletes a completed global organization operation
func (c *GlobalOrganizationOperationsClient) Delete(ctx context.Context, req *computepb.DeleteGlobalOrganizationOperationRequest, opts ...gax.CallOption) (*computepb.DeleteGlobalOrganizationOperationResponse, error)

Operation Protocol Buffer Type

The computepb.Operation type represents operation metadata:

type Operation struct {
    ClientOperationId *string
    CreationTimestamp *string
    Description       *string
    EndTime           *string
    Error             *Error
    HttpErrorMessage  *string
    HttpErrorStatusCode *int32
    Id                *uint64
    InsertTime        *string
    InstancesBulkInsertOperationMetadata *InstancesBulkInsertOperationMetadata
    Kind              *string
    Name              *string
    OperationGroupId  *string
    OperationType     *string
    Progress          *int32
    Region            *string
    SelfLink          *string
    SetCommonInstanceMetadataOperationMetadata *SetCommonInstanceMetadataOperationMetadata
    StartTime         *string
    Status            *string  // PENDING, RUNNING, DONE
    StatusMessage     *string
    TargetId          *uint64
    TargetLink        *string
    User              *string
    Warnings          []*Warnings
    Zone              *string
}

type Error struct {
    Errors []*ErrorError
}

type ErrorError struct {
    Code         *string
    ErrorDetails []*ErrorErrorErrorDetail
    Location     *string
    Message      *string
}

Operation Status Values

const (
    Operation_PENDING = "PENDING"
    Operation_RUNNING = "RUNNING"
    Operation_DONE    = "DONE"
)

Iterator Type

// OperationIterator manages iteration over Operation results
type OperationIterator struct {
    // Next returns the next result or iterator.Done
    Next() (*computepb.Operation, error)

    // PageInfo supports pagination
    PageInfo() *iterator.PageInfo
}

// OperationsScopedListPairIterator iterates over operations grouped by scope
type OperationsScopedListPairIterator struct {
    // Next returns the next result or iterator.Done
    Next() (OperationsScopedListPair, error)

    // PageInfo supports pagination
    PageInfo() *iterator.PageInfo
}

type OperationsScopedListPair struct {
    Key   string
    Value *computepb.OperationsScopedList
}

Usage Patterns

Pattern 1: Simple Wait

For most use cases, simply wait for the operation to complete:

op, err := client.Insert(ctx, req)
if err != nil {
    return err
}
return op.Wait(ctx)

Pattern 2: Wait with Timeout

Use context timeout to limit wait time:

import "time"

op, err := client.Insert(ctx, req)
if err != nil {
    return err
}

waitCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()

return op.Wait(waitCtx)

Pattern 3: Poll with Progress Updates

Poll the operation and provide progress updates:

op, err := client.Insert(ctx, req)
if err != nil {
    return err
}

for !op.Done() {
    err = op.Poll(ctx)
    if err != nil {
        return err
    }

    if !op.Done() {
        fmt.Printf("Operation %s still in progress...\n", op.Name())
        time.Sleep(2 * time.Second)
    }
}
fmt.Printf("Operation %s completed\n", op.Name())

Pattern 4: Retrieve Operation Details

Get detailed operation information using the operations clients:

// After getting an operation
opName := op.Name()

// Query for detailed status
getReq := &computepb.GetZoneOperationRequest{
    Project:   "my-project",
    Zone:      "us-central1-a",
    Operation: opName,
}
opDetails, err := opsClient.Get(ctx, getReq)
if err != nil {
    return err
}

if opDetails.Error != nil {
    for _, e := range opDetails.Error.Errors {
        fmt.Printf("Error: %s - %s\n", *e.Code, *e.Message)
    }
}

Error Handling

Operations can fail after being initiated. Always check for errors:

op, err := client.Delete(ctx, deleteReq)
if err != nil {
    return fmt.Errorf("failed to initiate delete: %w", err)
}

err = op.Wait(ctx)
if err != nil {
    return fmt.Errorf("delete operation failed: %w", err)
}

Call Options

All operations clients have call options for configuring retry and timeout behavior:

// GlobalOperationsCallOptions contains options for global operations
type GlobalOperationsCallOptions struct {
    AggregatedList []gax.CallOption
    Delete         []gax.CallOption
    Get            []gax.CallOption
    List           []gax.CallOption
    Wait           []gax.CallOption
}

// RegionOperationsCallOptions contains options for regional operations
type RegionOperationsCallOptions struct {
    Delete []gax.CallOption
    Get    []gax.CallOption
    List   []gax.CallOption
    Wait   []gax.CallOption
}

// ZoneOperationsCallOptions contains options for zonal operations
type ZoneOperationsCallOptions struct {
    Delete []gax.CallOption
    Get    []gax.CallOption
    List   []gax.CallOption
    Wait   []gax.CallOption
}