Go bindings for Ceph
Go to file
John Mulligan 560d6ccd2c rbd: properly format the doc comment for Copy2
Signed-off-by: John Mulligan <jmulligan@redhat.com>
2020-03-17 09:15:24 +01:00
.github github: configure a pull request template 2019-12-12 16:17:31 -05:00
cephfs errutil: move errutil pkg into internal subdir 2020-03-10 08:41:44 +01:00
contrib contrib: create a hacky script for comparing api coverage 2020-01-21 08:00:38 +01:00
docs docs: document the release process 2020-02-17 09:44:18 -05:00
internal errutil: move errutil pkg into internal subdir 2020-03-10 08:41:44 +01:00
rados rados: fix test for mon command with input buffer on ceph octopus 2020-03-12 13:33:16 +01:00
rbd rbd: properly format the doc comment for Copy2 2020-03-17 09:15:24 +01:00
testing/containers testing: move ubuntu xenial based Dockerfile to a subdir 2020-03-12 13:33:16 +01:00
.gitignore entrypoint: handle the sub-packages separately 2020-01-20 17:41:15 +01:00
.revive.toml testing: enable exported vars check as warning 2019-12-17 08:30:02 +01:00
.travis.yml travis: enable testing with ceph "octopus" 2020-03-12 13:33:16 +01:00
LICENSE license: add MIT license 2014-11-27 10:53:04 -08:00
Makefile makefile: use ceph based containers by default 2020-03-12 13:33:16 +01:00
README.md readme: update doc link to pkg.go.dev 2020-02-13 07:28:33 +01:00
doc.go go-ceph: fix typo in doc.go 2020-01-28 08:38:59 +01:00
entrypoint.sh entrypoint: enable go vet checking on packages 2020-03-12 09:02:53 +01:00
go.mod go-ceph: publish library as a go module 2020-01-27 17:53:38 +01:00
go.sum go-ceph: publish library as a go module 2020-01-27 17:53:38 +01:00
micro-osd.sh test: update micro-osd.sh to support nautilus 2019-11-04 13:15:30 -05:00
package_test.go ceph: rename package for go files in root dir 2019-12-11 14:44:54 -05:00

README.md

go-ceph - Go bindings for Ceph APIs

Build Status Godoc license

Installation

go get github.com/ceph/go-ceph

The native RADOS library and development headers are expected to be installed.

On debian systems (apt):

libcephfs-dev librbd-dev librados-dev

On rpm based systems (dnf, yum, etc):

libcephfs-devel librbd-devel librados-devel

go-ceph tries to support different Ceph versions. However some functions might only be available in recent versions, and others can be deprecated. In order to work with non-current versions of Ceph, it is required to pass build-tags to on the go commandline. A tag with the named Ceph release will enable/disable certain features of the go-ceph packages, and prevent warnings or compile problems. E.g. build against libcephfs/librados/librbd from Mimic, or run go test against Limunous, use:

go build -tags mimic ....
go test -tags luminous ....

Documentation

Detailed documentation is available at https://pkg.go.dev/github.com/ceph/go-ceph.

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

Development

docker run --rm -it --net=host \
  --device /dev/fuse --cap-add SYS_ADMIN --security-opt apparmor:unconfined \
  -v ${PWD}:/go/src/github.com/ceph/go-ceph:z \
  -v /home/nwatkins/src/ceph/build:/home/nwatkins/src/ceph/build:z \
  -e CEPH_CONF=/home/nwatkins/src/ceph/build/ceph.conf \
  ceph-golang

Run against a vstart.sh cluster without installing Ceph:

export CGO_CPPFLAGS="-I/ceph/src/include"
export CGO_LDFLAGS="-L/ceph/build/lib"
go build

Contributing

Contributions are welcome & greatly appreciated, every little bit helps. Make code changes via Github pull requests:

  • Fork the repo and create a topic branch for every feature/fix. Avoid making changes directly on master branch.
  • All incoming features should be accompanied with tests.
  • Make sure that you run go fmt before submitting a change set. Alternatively the Makefile has a flag for this, so you can call make fmt as well.
  • The integration tests can be run in a docker container, for this run:
make test-docker