1/*
2Package gophercloud provides a multi-vendor interface to OpenStack-compatible
3clouds. The library has a three-level hierarchy: providers, services, and
4resources.
5
6Authenticating with Providers
7
8Provider structs represent the cloud providers that offer and manage a
9collection of services. You will generally want to create one Provider
10client per OpenStack cloud.
11
12Use your OpenStack credentials to create a Provider client.  The
13IdentityEndpoint is typically refered to as "auth_url" or "OS_AUTH_URL" in
14information provided by the cloud operator. Additionally, the cloud may refer to
15TenantID or TenantName as project_id and project_name. Credentials are
16specified like so:
17
18  opts := gophercloud.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
27You may also use the openstack.AuthOptionsFromEnv() helper function. This
28function reads in standard environment variables frequently found in an
29OpenStack `openrc` file. Again note that Gophercloud currently uses "tenant"
30instead of "project".
31
32	opts, err := openstack.AuthOptionsFromEnv()
33	provider, err := openstack.AuthenticatedClient(opts)
34
35Service Clients
36
37Service structs are specific to a provider and handle all of the logic and
38operations for a particular OpenStack service. Examples of services include:
39Compute, Object Storage, Block Storage. In order to define one, you need to
40pass in the parent provider, like so:
41
42  opts := gophercloud.EndpointOpts{Region: "RegionOne"}
43
44  client, err := openstack.NewComputeV2(provider, opts)
45
46Resources
47
48Resource structs are the domain models that services make use of in order
49to work with and represent the state of API resources:
50
51  server, err := servers.Get(client, "{serverId}").Extract()
52
53Intermediate Result structs are returned for API operations, which allow
54generic access to the HTTP headers, response body, and any errors associated
55with the network transaction. To turn a result into a usable resource struct,
56you must call the Extract method which is chained to the response, or an
57Extract 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
65All requests that enumerate a collection return a Pager struct that is used to
66iterate through the results one page at a time. Use the EachPage method on that
67Pager to handle each successive Page in a closure, then use the appropriate
68extraction method from that request's package to interpret that Page as a slice
69of 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
83If you want to obtain the entire collection of pages without doing any
84intermediary 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
89This top-level package contains utility functions and data types that are used
90throughout the provider and service packages. Of particular note for end users
91are the AuthOptions and EndpointOpts structs.
92*/
93package gophercloud
94