go-ceph/docs/hints.md

API Hints & Quick How-Tos

Below you'll find some brief sections that show how some of the API calls in go-ceph work together. This is not meant to cover every possible use case but are recorded here as a quick way to get familiar with these calls.

rados Package

Connecting to a cluster

Connect to a Ceph cluster using a configuration file located in the default search paths.

conn, _ := rados.NewConn()
conn.ReadDefaultConfigFile()
conn.Connect()

A connection can be shutdown by calling the Shutdown method on the connection object (e.g. conn.Shutdown()). There are also other methods for configuring the connection. Specific configuration options can be set:

conn.SetConfigOption("log_file", "/dev/null")

and command line options can also be used using the ParseCmdLineArgs method.

args := []string{ "--mon-host", "1.1.1.1" }
err := conn.ParseCmdLineArgs(args)

For other configuration options see the full documentation.

Object I/O

Object in RADOS can be written to and read from with through an interface very similar to a standard file I/O interface:

// open a pool handle
ioctx, err := conn.OpenIOContext("mypool")

// write some data
bytesIn := []byte("input data")
err = ioctx.Write("obj", bytesIn, 0)

// read the data back out
bytesOut := make([]byte, len(bytesIn))
_, err := ioctx.Read("obj", bytesOut, 0)

if !bytes.Equal(bytesIn, bytesOut) {
    fmt.Println("Output is not input!")
}

Pool maintenance

The list of pools in a cluster can be retrieved using the ListPools method on the connection object. On a new cluster the following code snippet:

pools, _ := conn.ListPools()
fmt.Println(pools)

will produce the output [data metadata rbd], along with any other pools that might exist in your cluster. Pools can also be created and destroyed. The following creates a new, empty pool with default settings.

conn.MakePool("new_pool")

Deleting a pool is also easy. Call DeletePool(name string) on a connection object to delete a pool with the given name. The following will delete the pool named new_pool and remove all of the pool's data.

conn.DeletePool("new_pool")

Error Handling

As typical of Go codebases, a large number of functions in go-ceph return errors. Some of these errors are based on non-exported types. This is deliberate choice. However, much of the relevant data these types can contain are available. One does not have to resort to the somewhat brittle approach of converting errors to strings and matching on (parts of) said string.

In some cases the errors returned by calls are considered "sentinel" errors. These errors can be matched to exported values in the package using the errors.Is function from the Go standard library.

Example:

// we want to delete a pool, but oops, conn is disconnected
err := conn.DeletePool("foo")
if err != nil {
    if errors.Is(err, rados.ErrNotConnected) {
        // ... do something specific when not connected ...
    } else {
        // ... handle generic error ...
    }
}

Example:

err := rgw.MyAPICall()
if err != nil {
    if errors.Is(err, rgw.ErrInvalidAccessKey) {
       // ... do something specific to access errors ...
    } else if errors.Is(err, rgw.ErrNoSuchUser) {
       // ... do something specific to user not existing ...
    } else {
       // ... handle generic error ...
    }
}

In other cases the returned error doesn't match a specific error value but rather is implemented by a type that may carry additional data. Specifically, many errors in go-ceph implement an ErrorCode() int method. If this is the case you can use ErrorCode to access a numeric error code provided by calls to Ceph. Note that the error codes returned by Ceph often match unix/linux errnos - but the exact meaning of the values returned by ErrorCode() are determined by the Ceph APIs and go-ceph is just making them accessible.

Example:

type errorWithCode interface {
    ErrorCode() int
}

err := rados.SomeRadosFunc()
if err != nil {
    var ec errorWithCode
    if errors.As(err, &ec) {
        errCode := ec.ErrorCode()
        // ... do something with errCode ...
    } else {
        // ... handle generic error ...
    }
}

Note that Go allows type definitions inline so you can even write:

err := rados.SomeRadosFunc()
if err != nil {
    var ec interface { ErrorCode() int }
    if errors.As(err, &ec) {
        errCode := ec.ErrorCode()
        // ... do something with errCode ...
    } else {
        // ... handle generic error ...
    }
}

Newer packages in go-ceph generally prefer to latter approach to avoid creating lots of sentinels that are only used rarely.