github.com/huaweicloud/golangsdk@v0.0.0-20210831081626-d823fe11ceba/doc.go (about)

     1  /*
     2  Package golangsdk provides a multi-vendor interface to OpenStack-compatible
     3  clouds. The library has a three-level hierarchy: providers, services, and
     4  resources.
     5  
     6  Authenticating with Providers
     7  
     8  Provider structs represent the cloud providers that offer and manage a
     9  collection of services. You will generally want to create one Provider
    10  client per OpenStack cloud.
    11  
    12  Use your OpenStack credentials to create a Provider client.  The
    13  IdentityEndpoint is typically refered to as "auth_url" or "OS_AUTH_URL" in
    14  information provided by the cloud operator. Additionally, the cloud may refer to
    15  TenantID or TenantName as project_id and project_name. Credentials are
    16  specified like so:
    17  
    18    opts := golangsdk.AuthOptions{
    19      IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
    20      Username: "{username}",
    21      Password: "{password}",
    22      TenantID: "{tenant_id}",
    23    }
    24  
    25    provider, err := openstack.AuthenticatedClient(opts)
    26  
    27  You may also use the openstack.AuthOptionsFromEnv() helper function. This
    28  function reads in standard environment variables frequently found in an
    29  OpenStack `openrc` file. Again note that Gophercloud currently uses "tenant"
    30  instead of "project".
    31  
    32  	opts, err := openstack.AuthOptionsFromEnv()
    33  	provider, err := openstack.AuthenticatedClient(opts)
    34  
    35  Service Clients
    36  
    37  Service structs are specific to a provider and handle all of the logic and
    38  operations for a particular OpenStack service. Examples of services include:
    39  Compute, Object Storage, Block Storage. In order to define one, you need to
    40  pass in the parent provider, like so:
    41  
    42    opts := golangsdk.EndpointOpts{Region: "RegionOne"}
    43  
    44    client := openstack.NewComputeV2(provider, opts)
    45  
    46  Resources
    47  
    48  Resource structs are the domain models that services make use of in order
    49  to work with and represent the state of API resources:
    50  
    51    server, err := servers.Get(client, "{serverId}").Extract()
    52  
    53  Intermediate Result structs are returned for API operations, which allow
    54  generic access to the HTTP headers, response body, and any errors associated
    55  with the network transaction. To turn a result into a usable resource struct,
    56  you must call the Extract method which is chained to the response, or an
    57  Extract function from an applicable extension:
    58  
    59    result := servers.Get(client, "{serverId}")
    60  
    61    // Attempt to extract the disk configuration from the OS-DCF disk config
    62    // extension:
    63    config, err := diskconfig.ExtractGet(result)
    64  
    65  All requests that enumerate a collection return a Pager struct that is used to
    66  iterate through the results one page at a time. Use the EachPage method on that
    67  Pager to handle each successive Page in a closure, then use the appropriate
    68  extraction method from that request's package to interpret that Page as a slice
    69  of results:
    70  
    71    err := servers.List(client, nil).EachPage(func (page pagination.Page) (bool, error) {
    72      s, err := servers.ExtractServers(page)
    73      if err != nil {
    74        return false, err
    75      }
    76  
    77      // Handle the []servers.Server slice.
    78  
    79      // Return "false" or an error to prematurely stop fetching new pages.
    80      return true, nil
    81    })
    82  
    83  If you want to obtain the entire collection of pages without doing any
    84  intermediary processing on each page, you can use the AllPages method:
    85  
    86  	allPages, err := servers.List(client, nil).AllPages()
    87  	allServers, err := servers.ExtractServers(allPages)
    88  
    89  This top-level package contains utility functions and data types that are used
    90  throughout the provider and service packages. Of particular note for end users
    91  are the AuthOptions and EndpointOpts structs.
    92  
    93  An example retry backoff function, which respects the 429 HTTP response code:
    94  
    95  	endpoint := "http://localhost:5000"
    96  	provider, err := openstack.NewClient(endpoint)
    97  	if err != nil {
    98  		panic(err)
    99  	}
   100  	provider.MaxBackoffRetries = 3 // max three retries
   101  	provider.RetryBackoffFunc = func(ctx context.Context, respErr *ErrUnexpectedResponseCode, e error, retries uint) error {
   102  		minutes := math.Pow(2, float64(retries))
   103  		if minutes > 30 { // won't wait more than 30 minutes
   104  			minutes = 30
   105  		}
   106  
   107  		sleep := time.Duration(minutes) * time.Minute
   108  
   109  		if ctx != nil {
   110  			select {
   111  			case <-time.After(sleep):
   112  			case <-ctx.Done():
   113  				return e
   114  			}
   115  		} else {
   116  			time.Sleep(sleep)
   117  		}
   118  
   119  		return nil
   120  	}
   121  
   122  */
   123  package golangsdk