With the arrival of this new major version increment, the unfortunate news is that many breaking changes to existing services have been introduced. The API has been completely rewritten to make the library more extendible and easy-to-use.
Below we've compiled specific upgrade instructions for the various services that existed before. If you have a specific issue that is not addressed below, please submit an issue or e-mail our support team.
One of the major differences that this release introduces is the level of sub-packaging to differentiate between services and providers. You know have the option of authenticating with OpenStack and other providers (like Rackspace).
To authenticate with a vanilla OpenStack installation, you can either specify your credentials like this:
import (
"github.com/rackspace/gophercloud"
"github.com/rackspace/gophercloud/openstack"
)
opts := gophercloud.AuthOptions{
IdentityEndpoint: "https://my-openstack.com:5000/v2.0",
Username: "{username}",
Password: "{password}",
TenantID: "{tenant_id}",
}
Or have them pulled in through environment variables, like this:
opts, err := openstack.AuthOptionsFromEnv()
Once you have your AuthOptions struct, you pass it in to get back a Provider, like so:
provider, err := openstack.AuthenticatedClient(opts)
This provider is the top-level structure that all services are created from.
## Client
Before you can interact with the Compute API, you need to retrieve a gophercloud.ServiceClient client. To do this:
// Define your region, etc. opts := gophercloud.EndpointOpts{Region: "RegionOne"} client, err := openstack.NewComputeV2(provider, opts)
All operations that involve API collections (servers, flavors, images) now use the pagination.Pager interface. This interface represents paginated entities that can be iterated over.
Once you have a Pager, you can then pass a callback function into its EachPage method, and this will allow you to traverse over the collection and execute arbitrary functionality. So, an example with list servers:
import ( "fmt" "github.com/rackspace/gophercloud/pagination" "github.com/rackspace/gophercloud/openstack/compute/v2/servers" ) // We have the option of filtering the server list. If we want the full // collection, leave it as an empty struct opts := servers.ListOpts{Name: "server_1"} // Retrieve a pager (i.e. a paginated collection) pager := servers.List(client, opts) // Define an anonymous function to be executed on each page's iteration err := pager.EachPage(func(page pagination.Page) (bool, error) { serverList, err := servers.ExtractServers(page) // `s' will be a servers.Server struct for _, s := range serverList { fmt.Printf("We have a server. ID=%s, Name=%s", s.ID, s.Name) } })
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers" // Get the HTTP result response := servers.Get(client, "server_id") // Extract a Server struct from the response server, err := response.Extract()
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers" // Define our options opts := servers.CreateOpts{ Name: "new_server", FlavorRef: "flavorID", ImageRef: "imageID", } // Get our response response := servers.Create(client, opts) // Extract server, err := response.Extract()
As with listing servers (see above), you first retrieve a Pager, and then pass in a callback over each page:
import ( "github.com/rackspace/gophercloud/pagination" "github.com/rackspace/gophercloud/openstack/compute/v2/images" ) // We have the option of filtering the image list. If we want the full // collection, leave it as an empty struct opts := images.ListOpts{ChangesSince: "2014-01-01T01:02:03Z", Name: "Ubuntu 12.04"} // Retrieve a pager (i.e. a paginated collection) pager := images.List(client, opts) // Define an anonymous function to be executed on each page's iteration err := pager.EachPage(func(page pagination.Page) (bool, error) { imageList, err := images.ExtractImages(page) for _, i := range imageList { // "i" will be a images.Image } })
import ( "github.com/rackspace/gophercloud/pagination" "github.com/rackspace/gophercloud/openstack/compute/v2/flavors" ) // We have the option of filtering the flavor list. If we want the full // collection, leave it as an empty struct opts := flavors.ListOpts{ChangesSince: "2014-01-01T01:02:03Z", MinRAM: 4} // Retrieve a pager (i.e. a paginated collection) pager := flavors.List(client, opts) // Define an anonymous function to be executed on each page's iteration err := pager.EachPage(func(page pagination.Page) (bool, error) { flavorList, err := networks.ExtractFlavors(page) for _, f := range flavorList { // "f" will be a flavors.Flavor } })
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"
result := servers.ChangeAdminPassword(client, "server_id", "newPassword_&123")
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"
result := servers.Resize(client, "server_id", "new_flavor_id")
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers" // You have a choice of two reboot methods: servers.SoftReboot or servers.HardReboot result := servers.Reboot(client, "server_id", servers.SoftReboot)
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"
opts := servers.UpdateOpts{Name: "new_name"}
server, err := servers.Update(client, "server_id", opts).Extract()
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers" // You have the option of specifying additional options opts := RebuildOpts{ Name: "new_name", AdminPass: "admin_password", ImageID: "image_id", Metadata: map[string]string{"owner": "me"}, } result := servers.Rebuild(client, "server_id", opts) // You can extract a servers.Server struct from the HTTP response server, err := result.Extract()
import "github.com/rackspace/gophercloud/openstack/compute/v2/extensions/keypairs" // Retrieve a pager (i.e. a paginated collection) pager := keypairs.List(client, opts) // Define an anonymous function to be executed on each page's iteration err := pager.EachPage(func(page pagination.Page) (bool, error) { keyList, err := keypairs.ExtractKeyPairs(page) for _, k := range keyList { // "k" will be a keypairs.KeyPair } })
To create a new keypair, you need to specify its name and, optionally, a pregenerated OpenSSH-formatted public key.
import "github.com/rackspace/gophercloud/openstack/compute/v2/extensions/keypairs"
opts := keypairs.CreateOpts{
Name: "new_key",
PublicKey: "...",
}
response := keypairs.Create(client, opts)
key, err := response.Extract()
To delete an existing keypair:
response := keypairs.Delete(client, "keypair_id")
Image management has been shifted to Glance, but unfortunately this service is not supported as of yet. You can, however, list Compute images like so:
import "github.com/rackspace/gophercloud/openstack/compute/v2/images" // Retrieve a pager (i.e. a paginated collection) pager := images.List(client, opts) // Define an anonymous function to be executed on each page's iteration err := pager.EachPage(func(page pagination.Page) (bool, error) { imageList, err := images.ExtractImages(page) for _, i := range imageList { // "i" will be a images.Image } })
import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"
response := servers.Delete(client, "server_id")
The server rescue extension for Compute is not currently supported.
This operation is not currently supported.