7abe5a239a
In order to simplify the workflow for contributors we'll continue to ask people to run `make api-update` when contributing new APIs. This will record the API in our api-status files. However, it will now use a placeholder value without a real version number. If a PR is filed and is not accepted before the next scheduled release the maintenance team will not have to ask the contributor to update the API versions to correct the numbers. Instead, we need to run the new `make api-fix-versions` rule at least once before a release to replace the placeholder versions with real version numbers. Signed-off-by: John Mulligan <jmulligan@redhat.com> |
||
|---|---|---|
| .devcontainer | ||
| .github | ||
| cephfs | ||
| common | ||
| contrib | ||
| docs | ||
| internal | ||
| rados | ||
| rbd | ||
| rgw | ||
| testing/containers | ||
| .gitignore | ||
| .revive.toml | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| doc.go | ||
| entrypoint.sh | ||
| go.mod | ||
| go.sum | ||
| micro-osd.sh | ||
| package_test.go | ||
README.md
go-ceph - Go bindings for Ceph APIs
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
On MacOS you can use brew to install the libraries:
brew tap mulbc/ceph-client
brew install ceph-client
NOTE: CentOS users may want to use a
CentOS Storage SIG
repository to enable packages for a supported ceph version.
Example: dnf -y install centos-release-ceph-pacific.
(CentOS 7 users should use "yum" rather than "dnf")
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 "pacific" release, use:
go build -tags pacific ....
go test -tags pacific ....
Supported Ceph Versions
| go-ceph version | Supported Ceph Versions | Deprecated Ceph Versions |
|---|---|---|
| v0.16.0 | octopus, pacific† | nautilus |
| v0.15.0 | octopus, pacific | nautilus |
| v0.14.0 | octopus, pacific | nautilus |
| v0.13.0 | octopus, pacific | nautilus |
| v0.12.0 | octopus, pacific | nautilus |
| 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.
† Preliminary support for Ceph Quincy is available in this release. Due to Quincy specific issues in our test suite some APIs can not be tested against Quincy at the moment. Thus, go-ceph should work with Quincy but we are not declaring it fully supported until all APIs can be tested on Quincy.
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 fmtbefore submitting a change set. Alternatively the Makefile has a flag for this, so you can callmake fmtas 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