Instances Client

func NewInstancesRESTClient(ctx context.Context, opts ...option.ClientOption) (*InstancesClient, error)

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

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

// Close closes the client connection
func (c *InstancesClient) Close() error

// Connection returns the gRPC connection (deprecated)
func (c *InstancesClient) Connection() *grpc.ClientConn

// Get retrieves a specific instance
func (c *InstancesClient) Get(ctx context.Context, req *computepb.GetInstanceRequest, opts ...gax.CallOption) (*computepb.Instance, error)

// List returns an iterator over instances in a zone
func (c *InstancesClient) List(ctx context.Context, req *computepb.ListInstancesRequest, opts ...gax.CallOption) *InstanceIterator

// AggregatedList returns an iterator over instances across all zones
func (c *InstancesClient) AggregatedList(ctx context.Context, req *computepb.AggregatedListInstancesRequest, opts ...gax.CallOption) *InstancesScopedListPairIterator

import "cloud.google.com/go/compute/apiv1/computepb"

req := &computepb.GetInstanceRequest{
    Project:  "my-project",
    Zone:     "us-central1-a",
    Instance: "my-instance",
}
instance, err := client.Get(ctx, req)
if err != nil {
    // handle error
}
fmt.Printf("Instance: %s, Status: %s\n", *instance.Name, *instance.Status)

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

listReq := &computepb.ListInstancesRequest{
    Project: "my-project",
    Zone:    "us-central1-a",
}
it := client.List(ctx, listReq)
for {
    instance, err := it.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        // handle error
    }
    fmt.Printf("Instance: %s\n", *instance.Name)
}

// Insert creates a new instance
func (c *InstancesClient) Insert(ctx context.Context, req *computepb.InsertInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Delete deletes an instance
func (c *InstancesClient) Delete(ctx context.Context, req *computepb.DeleteInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Update updates an instance (full replacement)
func (c *InstancesClient) Update(ctx context.Context, req *computepb.UpdateInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Patch partially updates an instance
func (c *InstancesClient) Patch(ctx context.Context, req *computepb.PatchInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// AddResourcePolicies adds resource policies to an instance for scheduling live migrations
func (c *InstancesClient) AddResourcePolicies(ctx context.Context, req *computepb.AddResourcePoliciesInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// RemoveResourcePolicies removes resource policies from an instance
func (c *InstancesClient) RemoveResourcePolicies(ctx context.Context, req *computepb.RemoveResourcePoliciesInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// ListReferrers retrieves a list of resources that refer to this VM instance
func (c *InstancesClient) ListReferrers(ctx context.Context, req *computepb.ListReferrersInstancesRequest, opts ...gax.CallOption) *ReferenceIterator

// Start starts a stopped instance
func (c *InstancesClient) Start(ctx context.Context, req *computepb.StartInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// StartWithEncryptionKey starts a stopped instance with customer-supplied encryption key
func (c *InstancesClient) StartWithEncryptionKey(ctx context.Context, req *computepb.StartWithEncryptionKeyInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Stop stops a running instance (graceful shutdown)
func (c *InstancesClient) Stop(ctx context.Context, req *computepb.StopInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Reset performs a hard reset of an instance
func (c *InstancesClient) Reset(ctx context.Context, req *computepb.ResetInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Suspend suspends a running instance
func (c *InstancesClient) Suspend(ctx context.Context, req *computepb.SuspendInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// Resume resumes a suspended instance
func (c *InstancesClient) Resume(ctx context.Context, req *computepb.ResumeInstanceRequest, opts ...gax.CallOption) (*Operation, error)

import "google.golang.org/protobuf/proto"

insertReq := &computepb.InsertInstanceRequest{
    Project: "my-project",
    Zone:    "us-central1-a",
    InstanceResource: &computepb.Instance{
        Name:        proto.String("new-instance"),
        MachineType: proto.String("zones/us-central1-a/machineTypes/n1-standard-1"),
        Disks: []*computepb.AttachedDisk{
            {
                Boot:       proto.Bool(true),
                AutoDelete: proto.Bool(true),
                InitializeParams: &computepb.AttachedDiskInitializeParams{
                    SourceImage: proto.String("projects/debian-cloud/global/images/family/debian-11"),
                    DiskSizeGb:  proto.Int64(10),
                },
            },
        },
        NetworkInterfaces: []*computepb.NetworkInterface{
            {
                Network: proto.String("global/networks/default"),
                AccessConfigs: []*computepb.AccessConfig{
                    {
                        Name: proto.String("External NAT"),
                        Type: proto.String("ONE_TO_ONE_NAT"),
                    },
                },
            },
        },
    },
}
op, err := client.Insert(ctx, insertReq)
if err != nil {
    // handle error
}
// Wait for instance creation to complete
err = op.Wait(ctx)

// AttachDisk attaches a persistent disk to an instance
func (c *InstancesClient) AttachDisk(ctx context.Context, req *computepb.AttachDiskInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// DetachDisk detaches a persistent disk from an instance
func (c *InstancesClient) DetachDisk(ctx context.Context, req *computepb.DetachDiskInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetDiskAutoDelete sets the auto-delete flag for a disk
func (c *InstancesClient) SetDiskAutoDelete(ctx context.Context, req *computepb.SetDiskAutoDeleteInstanceRequest, opts ...gax.CallOption) (*Operation, error)

attachReq := &computepb.AttachDiskInstanceRequest{
    Project:  "my-project",
    Zone:     "us-central1-a",
    Instance: "my-instance",
    AttachedDiskResource: &computepb.AttachedDisk{
        Source:     proto.String("projects/my-project/zones/us-central1-a/disks/my-disk"),
        Mode:       proto.String("READ_WRITE"),
        AutoDelete: proto.Bool(false),
    },
}
op, err := client.AttachDisk(ctx, attachReq)
if err != nil {
    // handle error
}
err = op.Wait(ctx)

// AddAccessConfig adds an external IP address to an instance
func (c *InstancesClient) AddAccessConfig(ctx context.Context, req *computepb.AddAccessConfigInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// DeleteAccessConfig removes an external IP address from an instance
func (c *InstancesClient) DeleteAccessConfig(ctx context.Context, req *computepb.DeleteAccessConfigInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// UpdateAccessConfig updates an access configuration
func (c *InstancesClient) UpdateAccessConfig(ctx context.Context, req *computepb.UpdateAccessConfigInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// AddNetworkInterface adds a network interface to an instance
func (c *InstancesClient) AddNetworkInterface(ctx context.Context, req *computepb.AddNetworkInterfaceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// RemoveNetworkInterface removes a network interface from an instance
func (c *InstancesClient) RemoveNetworkInterface(ctx context.Context, req *computepb.RemoveNetworkInterfaceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// DeleteNetworkInterface deletes a network interface from an instance
func (c *InstancesClient) DeleteNetworkInterface(ctx context.Context, req *computepb.DeleteNetworkInterfaceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// UpdateNetworkInterface updates network interface properties
func (c *InstancesClient) UpdateNetworkInterface(ctx context.Context, req *computepb.UpdateNetworkInterfaceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetLabels sets or updates resource labels
func (c *InstancesClient) SetLabels(ctx context.Context, req *computepb.SetLabelsInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetMachineType changes the machine type of a stopped instance
func (c *InstancesClient) SetMachineType(ctx context.Context, req *computepb.SetMachineTypeInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetMetadata sets or updates instance metadata
func (c *InstancesClient) SetMetadata(ctx context.Context, req *computepb.SetMetadataInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetMinCpuPlatform sets the minimum CPU platform
func (c *InstancesClient) SetMinCpuPlatform(ctx context.Context, req *computepb.SetMinCpuPlatformInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetScheduling updates scheduling options
func (c *InstancesClient) SetScheduling(ctx context.Context, req *computepb.SetSchedulingInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetServiceAccount changes the service account and scopes
func (c *InstancesClient) SetServiceAccount(ctx context.Context, req *computepb.SetServiceAccountInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetTags sets network tags for an instance
func (c *InstancesClient) SetTags(ctx context.Context, req *computepb.SetTagsInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetDeletionProtection enables or disables deletion protection
func (c *InstancesClient) SetDeletionProtection(ctx context.Context, req *computepb.SetDeletionProtectionInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetName sets the instance name
func (c *InstancesClient) SetName(ctx context.Context, req *computepb.SetNameInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetMachineResources changes the number and/or type of accelerator for a stopped instance
func (c *InstancesClient) SetMachineResources(ctx context.Context, req *computepb.SetMachineResourcesInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SetSecurityPolicy sets the Google Cloud Armor security policy for an instance
func (c *InstancesClient) SetSecurityPolicy(ctx context.Context, req *computepb.SetSecurityPolicyInstanceRequest, opts ...gax.CallOption) (*Operation, error)

setLabelsReq := &computepb.SetLabelsInstanceRequest{
    Project:  "my-project",
    Zone:     "us-central1-a",
    Instance: "my-instance",
    InstancesSetLabelsRequestResource: &computepb.InstancesSetLabelsRequest{
        Labels: map[string]string{
            "environment": "production",
            "team":        "backend",
        },
        LabelFingerprint: instance.LabelFingerprint,
    },
}
op, err := client.SetLabels(ctx, setLabelsReq)

// GetShieldedInstanceIdentity retrieves the Shielded Instance identity
func (c *InstancesClient) GetShieldedInstanceIdentity(ctx context.Context, req *computepb.GetShieldedInstanceIdentityInstanceRequest, opts ...gax.CallOption) (*computepb.ShieldedInstanceIdentity, error)

// SetShieldedInstanceIntegrityPolicy updates the Shielded VM integrity policy
func (c *InstancesClient) SetShieldedInstanceIntegrityPolicy(ctx context.Context, req *computepb.SetShieldedInstanceIntegrityPolicyInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// UpdateShieldedInstanceConfig updates Shielded VM configuration
func (c *InstancesClient) UpdateShieldedInstanceConfig(ctx context.Context, req *computepb.UpdateShieldedInstanceConfigInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// UpdateDisplayDevice updates the display device configuration
func (c *InstancesClient) UpdateDisplayDevice(ctx context.Context, req *computepb.UpdateDisplayDeviceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// GetSerialPortOutput retrieves serial port output (console logs)
func (c *InstancesClient) GetSerialPortOutput(ctx context.Context, req *computepb.GetSerialPortOutputInstanceRequest, opts ...gax.CallOption) (*computepb.SerialPortOutput, error)

// GetScreenshot captures a screenshot of the instance display
func (c *InstancesClient) GetScreenshot(ctx context.Context, req *computepb.GetScreenshotInstanceRequest, opts ...gax.CallOption) (*computepb.Screenshot, error)

// GetGuestAttributes retrieves guest attributes set by the guest OS
func (c *InstancesClient) GetGuestAttributes(ctx context.Context, req *computepb.GetGuestAttributesInstanceRequest, opts ...gax.CallOption) (*computepb.GuestAttributes, error)

// SendDiagnosticInterrupt sends a diagnostic interrupt to the instance
func (c *InstancesClient) SendDiagnosticInterrupt(ctx context.Context, req *computepb.SendDiagnosticInterruptInstanceRequest, opts ...gax.CallOption) (*computepb.SendDiagnosticInterruptInstanceResponse, error)

// GetEffectiveFirewalls lists firewall rules applied to an instance
func (c *InstancesClient) GetEffectiveFirewalls(ctx context.Context, req *computepb.GetEffectiveFirewallsInstanceRequest, opts ...gax.CallOption) (*computepb.InstancesGetEffectiveFirewallsResponse, error)

// BulkInsert creates multiple instances in a single operation
func (c *InstancesClient) BulkInsert(ctx context.Context, req *computepb.BulkInsertInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// SimulateMaintenanceEvent simulates a host maintenance event
func (c *InstancesClient) SimulateMaintenanceEvent(ctx context.Context, req *computepb.SimulateMaintenanceEventInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// PerformMaintenance triggers maintenance on an instance
func (c *InstancesClient) PerformMaintenance(ctx context.Context, req *computepb.PerformMaintenanceInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// ReportHostAsFaulty marks the host as faulty and attempts to restart the instance on a new host
func (c *InstancesClient) ReportHostAsFaulty(ctx context.Context, req *computepb.ReportHostAsFaultyInstanceRequest, opts ...gax.CallOption) (*Operation, error)

// GetIamPolicy retrieves the IAM policy for an instance
func (c *InstancesClient) GetIamPolicy(ctx context.Context, req *computepb.GetIamPolicyInstanceRequest, opts ...gax.CallOption) (*computepb.Policy, error)

// SetIamPolicy sets the IAM policy for an instance
func (c *InstancesClient) SetIamPolicy(ctx context.Context, req *computepb.SetIamPolicyInstanceRequest, opts ...gax.CallOption) (*computepb.Policy, error)

// TestIamPermissions tests IAM permissions for an instance
func (c *InstancesClient) TestIamPermissions(ctx context.Context, req *computepb.TestIamPermissionsInstanceRequest, opts ...gax.CallOption) (*computepb.TestPermissionsResponse, error)

// InstancesCallOptions contains options for configuring retry and timeout behavior
type InstancesCallOptions struct {
    AddAccessConfig                       []gax.CallOption
    AddNetworkInterface                   []gax.CallOption
    AddResourcePolicies                   []gax.CallOption
    AggregatedList                        []gax.CallOption
    AttachDisk                            []gax.CallOption
    BulkInsert                            []gax.CallOption
    Delete                                []gax.CallOption
    DeleteAccessConfig                    []gax.CallOption
    DetachDisk                            []gax.CallOption
    Get                                   []gax.CallOption
    GetEffectiveFirewalls                 []gax.CallOption
    GetGuestAttributes                    []gax.CallOption
    GetIamPolicy                          []gax.CallOption
    GetScreenshot                         []gax.CallOption
    GetSerialPortOutput                   []gax.CallOption
    GetShieldedInstanceIdentity           []gax.CallOption
    Insert                                []gax.CallOption
    List                                  []gax.CallOption
    ListReferrers                         []gax.CallOption
    Patch                                 []gax.CallOption
    PerformMaintenance                    []gax.CallOption
    RemoveNetworkInterface                []gax.CallOption
    RemoveResourcePolicies                []gax.CallOption
    Reset                                 []gax.CallOption
    Resume                                []gax.CallOption
    SendDiagnosticInterrupt               []gax.CallOption
    SetDeletionProtection                 []gax.CallOption
    SetDiskAutoDelete                     []gax.CallOption
    SetIamPolicy                          []gax.CallOption
    SetLabels                             []gax.CallOption
    SetMachineResources                   []gax.CallOption
    SetMachineType                        []gax.CallOption
    SetMetadata                           []gax.CallOption
    SetMinCpuPlatform                     []gax.CallOption
    SetName                               []gax.CallOption
    SetScheduling                         []gax.CallOption
    SetSecurityPolicy                     []gax.CallOption
    SetServiceAccount                     []gax.CallOption
    SetShieldedInstanceIntegrityPolicy    []gax.CallOption
    SetTags                               []gax.CallOption
    SimulateMaintenanceEvent              []gax.CallOption
    Start                                 []gax.CallOption
    StartWithEncryptionKey                []gax.CallOption
    Stop                                  []gax.CallOption
    Suspend                               []gax.CallOption
    TestIamPermissions                    []gax.CallOption
    Update                                []gax.CallOption
    UpdateAccessConfig                    []gax.CallOption
    UpdateDisplayDevice                   []gax.CallOption
    UpdateNetworkInterface                []gax.CallOption
    UpdateShieldedInstanceConfig          []gax.CallOption
}

// Customize timeout for Get operation
client.CallOptions.Get = []gax.CallOption{
    gax.WithTimeout(30 * time.Second),
}

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

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

// InstancesScopedListPairIterator iterates over instances grouped by scope
type InstancesScopedListPairIterator struct {
    // Next returns the next result or iterator.Done
    Next() (InstancesScopedListPair, error)

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

// InstancesScopedListPair represents a scope (zone) and its instances
type InstancesScopedListPair struct {
    Key   string
    Value *computepb.InstancesScopedList
}

// GetInstanceRequest retrieves a single instance
type GetInstanceRequest struct {
    Instance string  // Instance name
    Project  string  // Project ID
    Zone     string  // Zone name
}

// ListInstancesRequest lists instances in a zone
type ListInstancesRequest struct {
    Filter       *string  // Optional filter expression
    MaxResults   *uint32  // Maximum results per page
    OrderBy      *string  // Sort order
    PageToken    *string  // Pagination token
    Project      string   // Project ID
    Zone         string   // Zone name
}

// InsertInstanceRequest creates a new instance
type InsertInstanceRequest struct {
    InstanceResource *Instance  // Instance specification
    Project          string     // Project ID
    RequestId        *string    // Optional idempotency token
    SourceInstance   *string    // Optional source instance template
    SourceMachineImage *string  // Optional source machine image
    Zone             string     // Zone name
}

// DeleteInstanceRequest deletes an instance
type DeleteInstanceRequest struct {
    Instance  string   // Instance name
    Project   string   // Project ID
    RequestId *string  // Optional idempotency token
    Zone      string   // Zone name
}

// StartInstanceRequest starts a stopped instance
type StartInstanceRequest struct {
    Instance  string   // Instance name
    Project   string   // Project ID
    RequestId *string  // Optional idempotency token
    Zone      string   // Zone name
}

// StopInstanceRequest stops a running instance
type StopInstanceRequest struct {
    DiscardLocalSsd *bool    // Discard local SSD data
    Instance        string   // Instance name
    Project         string   // Project ID
    RequestId       *string  // Optional idempotency token
    Zone            string   // Zone name
}