Skip to content

Latest commit

 

History

History
338 lines (245 loc) · 8.75 KB

UPGRADING.md

File metadata and controls

338 lines (245 loc) · 8.75 KB
Raw

Upgrading to v1.0.0

With the arrival of this new major version increment, the unfortunate news is that breaking changes have been introduced to existing services. The API has been completely rewritten from the ground up to make the library more extensible, maintainable and easy-to-use.

Below we've compiled 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.

Authentication

One of the major differences that this release introduces is the level of sub-packaging to differentiate between services and providers. You now 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.

Servers

Before you can interact with the Compute API, you need to retrieve a gophercloud.ServiceClient. To do this:

// Define your region, etc.
opts := gophercloud.EndpointOpts{Region: "RegionOne"}

client, err := openstack.NewComputeV2(provider, opts)

List servers

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 or nil
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)
  }
})

Get server details

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()

Create server

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()

Change admin password

import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"

result := servers.ChangeAdminPassword(client, "server_id", "newPassword_&123")

Resize server

import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"

result := servers.Resize(client, "server_id", "new_flavor_id")

Reboot server

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)

Update server

import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"

opts := servers.UpdateOpts{Name: "new_name"}

server, err := servers.Update(client, "server_id", opts).Extract()

Rebuild server

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()

Delete server

import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"

response := servers.Delete(client, "server_id")

Rescue server

The server rescue extension for Compute is not currently supported.

Images and flavors

List images

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 an images.Image
  }
})

List flavors

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
  }
})

Create/delete image

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 an images.Image
  }
})

Other

List keypairs

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
  }
})

Create/delete keypairs

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")

List IP addresses

This operation is not currently supported.