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,517 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
Anoop C S ab45bcd33a cephfs: Add a separate test file for fallocate with mode 0 
There are backports created for fallocate API changes[1] that got merged
recently. Considering the time taken for these backports to get in to
release branches and finally as a released version we create a separate
test file to have more fine grained control over various pre-release CI
jobs with the help of corresponding build tags.

Modification of build tags should go hand-in-hand with the version
detection logic used in file_test.go once a backport is available in
released version.

[1] https://github.com/ceph/ceph/pull/59725

Signed-off-by: Anoop C S <anoopcs@cryptolab.net>
 		2024-11-12 17:19:57 +00:00
.devcontainer
…
.github github: Require squid job to pass in mergify config 2024-10-24 11:56:46 +00:00
cephfs cephfs: Add a separate test file for fallocate with mode 0 2024-11-12 17:19:57 +00:00
common
…
contrib implements: add rados/striper (sub)package support 2024-08-08 14:07:59 +00:00
docs rados: implement rados_getaddrs 2024-10-23 14:25:10 +00:00
internal tests: validate comparing with common cephError 2024-10-14 17:49:08 +00:00
rados rados: implement rados_getaddrs 2024-10-23 14:25:10 +00:00
rbd rbd: replace rbdError by cephError 2024-10-14 17:49:08 +00:00
rgw rgw/admin: add test for bucket creation date 2024-07-22 09:13:10 +00:00
testing/containers containers: work around protobuf package issues 2024-10-23 11:08:02 +00:00
.gitignore gitignore: Add default results directory 2024-06-07 18:55:15 +00:00
.revive.toml
…
LICENSE
…
Makefile Makefile: Use ?= for initial variable definitions(part 2) 2024-07-02 18:50:35 +00:00
README.md docs: update README for release v0.30.0 2024-10-14 13:02:39 +00:00
doc.go
…
entrypoint.sh CI: enable and collect core dumps in tests 2023-11-16 16:26:46 +00:00
go.mod go-ceph: bump golang.org/x/sys from 0.25.0 to 0.26.0 2024-11-02 14:31:09 +00:00
go.sum go-ceph: bump golang.org/x/sys from 0.25.0 to 0.26.0 2024-11-02 14:31:09 +00:00
micro-osd.sh micro-osd.sh: Clarify the suspicion around S3 credentials 2023-12-08 18:42:13 +00: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

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.30.0 pacific, quincy, reef, squid octopus
v0.29.0 pacific, quincy, reef octopus
v0.28.0 pacific, quincy, reef nautilus, octopus
v0.27.0 pacific, quincy, reef nautilus, octopus
v0.26.0 pacific, quincy, reef nautilus, octopus
v0.25.0 pacific, quincy, reef nautilus, octopus
v0.24.0 pacific, quincy, reef nautilus, octopus
v0.23.0 pacific, quincy, reef nautilus, octopus
v0.22.0 pacific, quincy nautilus, octopus
v0.21.0 pacific, quincy nautilus, octopus
v0.20.0 pacific, quincy nautilus, octopus
v0.19.0 pacific, quincy nautilus, octopus
v0.18.0 octopus, pacific, quincy nautilus
v0.17.0 octopus, pacific, quincy nautilus

The 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.

To see what older versions of go-ceph supported refer to the older releases file in the documentation.

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

Getting in Touch

Want to get in touch with the go-ceph team? We're available through a few different channels: