cmd/bpa-operator/vendor/github.com/gophercloud/gophercloud/doc.go

   1 /*
   2 Package gophercloud 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         It is now recommended to use the `clientconfig` package found at
  13         https://github.com/gophercloud/utils/tree/master/openstack/clientconfig
  14         for all authentication purposes.
  15
  16         The below documentation is still relevant. clientconfig simply implements
  17         the below and presents it in an easier and more flexible way.
  18
  19 Use your OpenStack credentials to create a Provider client.  The
  20 IdentityEndpoint is typically refered to as "auth_url" or "OS_AUTH_URL" in
  21 information provided by the cloud operator. Additionally, the cloud may refer to
  22 TenantID or TenantName as project_id and project_name. Credentials are
  23 specified like so:
  24
  25         opts := gophercloud.AuthOptions{
  26                 IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
  27                 Username: "{username}",
  28                 Password: "{password}",
  29                 TenantID: "{tenant_id}",
  30         }
  31
  32         provider, err := openstack.AuthenticatedClient(opts)
  33
  34 You can authenticate with a token by doing:
  35
  36         opts := gophercloud.AuthOptions{
  37                 IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
  38                 TokenID:  "{token_id}",
  39                 TenantID: "{tenant_id}",
  40         }
  41
  42         provider, err := openstack.AuthenticatedClient(opts)
  43
  44 You may also use the openstack.AuthOptionsFromEnv() helper function. This
  45 function reads in standard environment variables frequently found in an
  46 OpenStack `openrc` file. Again note that Gophercloud currently uses "tenant"
  47 instead of "project".
  48
  49         opts, err := openstack.AuthOptionsFromEnv()
  50         provider, err := openstack.AuthenticatedClient(opts)
  51
  52 Service Clients
  53
  54 Service structs are specific to a provider and handle all of the logic and
  55 operations for a particular OpenStack service. Examples of services include:
  56 Compute, Object Storage, Block Storage. In order to define one, you need to
  57 pass in the parent provider, like so:
  58
  59         opts := gophercloud.EndpointOpts{Region: "RegionOne"}
  60
  61         client, err := openstack.NewComputeV2(provider, opts)
  62
  63 Resources
  64
  65 Resource structs are the domain models that services make use of in order
  66 to work with and represent the state of API resources:
  67
  68         server, err := servers.Get(client, "{serverId}").Extract()
  69
  70 Intermediate Result structs are returned for API operations, which allow
  71 generic access to the HTTP headers, response body, and any errors associated
  72 with the network transaction. To turn a result into a usable resource struct,
  73 you must call the Extract method which is chained to the response, or an
  74 Extract function from an applicable extension:
  75
  76         result := servers.Get(client, "{serverId}")
  77
  78         // Attempt to extract the disk configuration from the OS-DCF disk config
  79         // extension:
  80         config, err := diskconfig.ExtractGet(result)
  81
  82 All requests that enumerate a collection return a Pager struct that is used to
  83 iterate through the results one page at a time. Use the EachPage method on that
  84 Pager to handle each successive Page in a closure, then use the appropriate
  85 extraction method from that request's package to interpret that Page as a slice
  86 of results:
  87
  88         err := servers.List(client, nil).EachPage(func (page pagination.Page) (bool, error) {
  89                 s, err := servers.ExtractServers(page)
  90                 if err != nil {
  91                         return false, err
  92                 }
  93
  94                 // Handle the []servers.Server slice.
  95
  96                 // Return "false" or an error to prematurely stop fetching new pages.
  97                 return true, nil
  98         })
  99
 100 If you want to obtain the entire collection of pages without doing any
 101 intermediary processing on each page, you can use the AllPages method:
 102
 103         allPages, err := servers.List(client, nil).AllPages()
 104         allServers, err := servers.ExtractServers(allPages)
 105
 106 This top-level package contains utility functions and data types that are used
 107 throughout the provider and service packages. Of particular note for end users
 108 are the AuthOptions and EndpointOpts structs.
 109 */
 110 package gophercloud