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