provider-ceph-rbd-namespace

provider-ceph-rbd-namespace is a Crossplane provider that manages Ceph RBD (RADOS Block Device) namespaces and scoped Ceph auth users via the Ceph REST API.

Features

• RBD Namespace Lifecycle: Create, observe, and delete Ceph RBD namespaces in any Ceph block pool.
• Ceph Client User & Auth Provisioning: Automatically generates a dedicated Ceph user (using the cluster name from ProviderConfig) with least-privilege profile rbd capabilities restricted to the specific pool and namespace.
• Connection Secret Publishing: Publishes userID and userKey (auth key) to a Kubernetes Secret consumed directly by the Ceph-CSI Operator and StorageClass.
• Ceph REST API Authentication: Manages authentication and session tokens against Ceph REST / Dashboard endpoints.
• Forgejo CI/CD & OCI Packaging: Self-contained build pipeline for generating Crossplane .xpkg packages and controller container images hosted on git.tokentechnology.net.

Getting Started

Prerequisites

• Go 1.24+
• Docker or Podman
• pre-commit
• Kubernetes cluster with Crossplane v1.16+

Development & Pre-Commit Setup

This repository uses pre-commit to maintain code quality, formatting, schema generation cleanliness, and to enforce commit message standards.

To install the hooks into your local git repository:

pre-commit install --hook-type pre-commit --hook-type commit-msg

You can run the checks manually across all files at any time:

pre-commit run --all-files

Conventional Commits & Semantic Versioning

All commit messages must follow the Conventional Commits specification:

<type>(<scope>): <short summary>

[optional body]

[optional footer(s)]

How Automated Releases Work

When changes are merged into the main branch, the Forgejo Actions release pipeline automatically inspects the commit history since the last release tag to determine the next Semantic Version (vX.Y.Z):

Commit Type	SemVer Component	Description / Effect
feat:	Minor (0.X.0)	Introduces new functionality or resources
fix:	Patch (0.0.X)	Bug fixes, patch-level corrections
perf:, refactor:	Patch (0.0.X)	Performance or internal improvements
BREAKING CHANGE: or feat!: / fix!:	Major (X.0.0)	Breaking changes to API schemas or behavior
docs:, chore:, ci:, test:	No release bump	Non-release metadata or documentation changes

The pipeline then:

1. Tags the commit with the calculated version (e.g. v0.2.0).
2. Builds and pushes the controller container image and Crossplane .xpkg package tagged with both v0.2.0 and latest.
3. Publishes a Forgejo release attaching the compiled .xpkg artifact.

Example

# 1. Start on a development feature branch
git checkout -b feat/add-quota-support

# 2. Make changes and commit using conventional commit syntax
git commit -m "feat(rbd): add namespace quota support"

# 3. Open a Pull Request targeting main (runs CI validation)
# 4. Once merged to main, the CI automatically tags v0.2.0 (if prior was v0.1.0),
#    pushes :v0.2.0 and :latest images, and creates the Forgejo release.

Building Locally

# Verify code generation and check for schema drift
make check-clean

# Run unit tests
make test

# Build controller binary
make build

# Build container image
make docker-build

# Build Crossplane .xpkg package
make xpkg-build

Cluster Installation

To install the provider onto a Crossplane-enabled Kubernetes cluster, apply the Provider resource:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-ceph-rbd-namespace
spec:
  package: git.tokentechnology.net/crossplane-contrib/provider-ceph-rbd-namespace:latest

(See examples/install/provider.yaml)

Quick Usage Example

1. Create Provider Credentials & ProviderConfig:

   apiVersion: v1
   kind: Secret
   metadata:
     name: ceph-creds
     namespace: crossplane-system
   type: Opaque
   stringData:
     username: "admin"
     password: "secretpassword"
   ---
   apiVersion: ceph.tokentechnology.net/v1alpha1
   kind: ProviderConfig
   metadata:
     name: default
   spec:
     clusterName: "ceph"
     endpoint: "https://ceph-dashboard.storage.svc:8443"
     insecureSkipTLSVerify: true
     credentials:
       - source: Secret
         secretRef:
           namespace: crossplane-system
           name: ceph-creds
   

2. Create an RBD Namespace:

   apiVersion: ceph.tokentechnology.net/v1alpha1
   kind: RBDNamespace
   metadata:
     name: tenant-a-rbd
   spec:
     forProvider:
       poolName: replicapool
       namespaceName: tenant-a
     providerConfigRef:
       name: default
     writeConnectionSecretToRef:
       name: tenant-a-csi-rbd-secret
       namespace: ceph-csi-operator-system
   

Upon creation, the controller:

• Creates the tenant-a namespace in the replicapool pool.
• Creates Ceph user client.csi-rbd-ceph-tenant-a with capabilities:
  • mon: profile rbd
  • osd: profile rbd pool=replicapool namespace=tenant-a
  • mgr: profile rbd pool=replicapool
• Emits userID and userKey into the Secret tenant-a-csi-rbd-secret in namespace ceph-csi-operator-system for use by Ceph-CSI operator StorageClasses.

Composite Resource Architecture

For information on composing this provider with Ceph-CSI Operator resources (ClientProfile, StorageClass) using provider-kubernetes, see docs/composite-resource-notes.md.