UPGRADING.md

# 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](/issues/new) or
[e-mail our support team](mailto:sdk-support@rackspace.com).

* [Authentication](#authentication)
* [Servers](#servers)
  * [List servers](#list-servers)
  * [Get server details](#get-server-details)
  * [Create server](#create-server)
  * [Resize server](#resize-server)
  * [Reboot server](#reboot-server)
  * [Update server](#update-server)
  * [Rebuild server](#rebuild-server)
  * [Change admin password](#change-admin-password)
  * [Delete server](#delete-server)
  * [Rescue server](#rescue-server)
* [Images and flavors](#images-and-flavors)
  * [List images](#list-images)
  * [List flavors](#list-flavors)
  * [Create/delete image](#createdelete-image)
* [Other](#other)
  * [List keypairs](#list-keypairs)
  * [Create/delete keypair](#createdelete-keypair)
  * [List IP addresses](#list-ip-addresses)

# 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:

```go
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:

```go
opts, err := openstack.AuthOptionsFromEnv()
```

Once you have your `AuthOptions` struct, you pass it in to get back a `Provider`,
like so:

```go
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:

```go
// 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:

```go
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

```go
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

```go
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

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

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

## Resize server

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

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

## Reboot server

```go
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

```go
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

```go
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

```go
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:

```go
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

```go
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:

```go
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

```go
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.

```go
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:

```go
response := keypairs.Delete(client, "keypair_id")
```

## List IP addresses

This operation is not currently supported.