RepoMirrors
/
go-ceph
mirror of https://github.com/ceph/go-ceph
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Go bindings for Ceph
1,008 Commits 5 Branches 29 Tags 3.6 MiB
Go 95.4%
Python 2%
Shell 1.5%
Makefile 0.9%
Dockerfile 0.2%
Go to file
John Mulligan ee90ae5906 entrypoint: default to running tests with 'ceph_preview' build tag 
As this script is the heart of our ci and we generally want to test all
of go-ceph in our ci, we default to enabling ceph_preview build tag. If
we need to test only non-preview functions one can set "NO_PREVIEW" env
var to skip setting the build tag.

Signed-off-by: John Mulligan <jmulligan@redhat.com>
 		2021-09-22 11:42:22 +00:00
.devcontainer devcontainer: add option to start ceph nodes for tests 2021-07-19 17:07:42 -04:00
.github workflows: simplify ci runs using new make targets 2021-08-31 17:51:58 +02:00
cephfs cephfs: add missing cephfs API components: function ceph_version 2021-09-13 15:51:10 +00:00
common/commands common commands: add new sub-package for common interface types 2021-06-01 11:06:19 +00:00
contrib implements: naming conventions: remove underscores from c stub vars 2021-09-13 15:13:53 +00:00
docs docs: add a API stability document 2021-08-25 16:51:26 +00:00
internal cutil: fix race condition in ptrguard tests 2021-08-12 10:02:40 -04:00
rados rados: remove unused constant 2021-09-16 13:47:56 +00:00
rbd rbd: change instance_ids to instanceIDs 2021-09-13 15:13:53 +00:00
rgw rgw admin: import testify suite as tsuite 2021-09-13 15:13:53 +00:00
testing/containers containers: update go version 2021-09-02 13:53:09 +00:00
.gitignore makefile: expand test-multi-container into multiple test-containers-* rules 2021-08-25 15:15:48 +00:00
.revive.toml revive: enable additional rules 2021-09-13 15:13:53 +00:00
LICENSE
…
Makefile makefile: add a variable for passing additional container build options 2021-09-02 13:53:09 +00:00
README.md readme: document v0.11.0 and the ceph versions it supports 2021-08-10 13:47:16 -04:00
doc.go doc: note the new "common/" subdir to the doc.go file 2021-06-01 11:06:19 +00:00
entrypoint.sh entrypoint: default to running tests with 'ceph_preview' build tag 2021-09-22 11:42:22 +00:00
go.mod rgwadmin: add support for RadosGW Admin Ops API 2021-05-31 17:45:31 +02:00
go.sum rgwadmin: add support for RadosGW Admin Ops API 2021-05-31 17:45:31 +02:00
micro-osd.sh micro-osd.sh: set up a cephfs mirroring daemon 2021-08-03 07:25:28 +00:00
package_test.go ceph: remove use of boolean literal in expression 2020-04-09 13:11:05 -04:00

README.md

go-ceph - Go bindings for Ceph APIs

Godoc license

Introduction

The go-ceph project is a collection of API bindings that support the use of native Ceph APIs, which are C language functions, in Go. These bindings make use of Go's cgo feature. There are three main Go sub-packages that make up go-ceph:

  • rados - exports functionality from Ceph's librados
  • rbd - exports functionality from Ceph's librbd
  • cephfs - exports functionality from Ceph's libcephfs
  • rgw/admin - interact with radosgw admin ops API

We aim to provide comprehensive support for the Ceph APIs over time. This includes both I/O related functions and management functions. If your project makes use of Ceph command line tools and is written in Go, you may be able to switch away from shelling out to the CLI and to these native function calls.

Installation

The code in go-ceph is purely a library module. Typically, one will import go-ceph in another Go based project. When building the code the native RADOS, RBD, & CephFS library and development headers are expected to be installed.

On debian based systems (apt) these may be:

libcephfs-dev librbd-dev librados-dev

On rpm based systems (dnf, yum, etc) these may be:

libcephfs-devel librbd-devel librados-devel

To quickly test if one can build with go-ceph on your system, run:

go get github.com/ceph/go-ceph

Once compiled, code using go-ceph is expected to dynamically link to the Ceph libraries. These libraries must be available on the system where the go based binaries will be run. Our use of cgo and ceph libraries does not allow for fully static binaries.

go-ceph tries to support different Ceph versions. However some functions might only be available in recent versions, and others may be deprecated. In order to work with non-current versions of Ceph, it is required to pass build-tags to the go command line. A tag with the named Ceph release will enable/disable certain features of the go-ceph packages, and prevent warnings or compile problems. For example, to ensure you select the library features that match the "nautilus" release, use:

go build -tags nautilus ....
go test -tags nautilus ....

Supported Ceph Versions

go-ceph version Supported Ceph Versions Deprecated Ceph Versions
v0.11.0 nautilus, octopus, pacific
v0.10.0 nautilus, octopus, pacific
v0.9.0 nautilus, octopus
v0.8.0 nautilus, octopus
v0.7.0 nautilus, octopus
v0.6.0 nautilus, octopus mimic
v0.5.0 nautilus, octopus luminous, mimic
v0.4.0 luminous, mimic, nautilus, octopus
v0.3.0 luminous, mimic, nautilus, octopus
v0.2.0 luminous, mimic, nautilus
(pre release) luminous, mimic (see note)

These tags affect what is supported at compile time. What version of the Ceph cluster the client libraries support, and vice versa, is determined entirely by what version of the Ceph C libraries go-ceph is compiled with.

NOTE: Prior to 2020 the project did not make versioned releases. The ability to compile with a particular Ceph version before go-ceph v0.2.0 is not guaranteed.

Documentation

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

Some API Hints and How-Tos are also available to quickly introduce how some of API calls work together.

Development

docker run --rm -it --net=host \
  --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

Interactive "Office Hours"

The maintenance team plans to be available regularly for questions, comments, pings, etc for about an hour twice a week. The current schedule is:

  • 2:00pm EDT (currently 18:00 UTC) Mondays
  • 9:00am EDT (currently 13:00 UTC) Thursdays

We will use the #ceph-devel IRC channel