Skip to content

Commit

Permalink
Documentation for incoming cephfs config options
Browse files Browse the repository at this point in the history
  • Loading branch information
@MadnessASAP
MadnessASAP committed Dec 10, 2024
1 parent cf36646 commit 586c56a
Show file tree
Hide file tree
Showing 5 changed files with 122 additions and 0 deletions.
39 changes: 39 additions & 0 deletions doc/config_options.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,45 @@ User keys can be used in search.

```

```{config:option} ceph.fsid devices-disk
:required: "no"
:shortdesc: "Ceph File System ID"
:type: "string"
Uniquely identifies the ceph cluster

Overrides ceph.cluster_name
This will usually be retrieved from ceph.conf or the cluster directly
using `ceph-conf` or `ceph` respectively. If these tools are not available
then this will need to be provided.

```

```{config:option} ceph.mon_addr devices-disk
:required: "no"
:shortdesc: "Ceph monitor address(es)"
:type: "string"
Used to establish connection to the ceph cluster.

This will usually be retrieved from ceph.conf or the cluster directly
using `ceph-conf` or `ceph` respectively. If these tools are not available
then this will need to be provided. Can be provided as ip addresses or
hostnames, port is optional

Has the form:
mon1:3300,1.2.3.4:5678,mon2.example.net:6789
```

```{config:option} ceph.user_key devices-disk
:required: "no"
:shortdesc: "Ceph user key"
:type: "string"
Used if authentication with cephx is required.

If needed at all will usually be retrieved using the `ceph-conf` tool.
However if this is not available on the host or the key is not accessible
to those tools then this will need to be provided.
```

```{config:option} ceph.user_name devices-disk
:default: "`admin`"
:required: "no"
Expand Down
4 changes: 4 additions & 0 deletions doc/reference/storage_cephfs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ The `cephfs` driver in Incus supports snapshots if snapshots are enabled on the
## Configuration options

The following configuration options are available for storage pools that use the `cephfs` driver and for storage volumes in these pools.
Usually [`cephfs.fsid`](storage-cephfs-pool-config), [`cephfs.monitor_addrs`](storage-cephfs-pool-config), and [`cephfs.user.key`](storage-cephfs-pool-config) will be automatically discovered using the Ceph admin tool & mount helper. However if those tools are not availble on the host then they will need to be provided.

(storage-cephfs-pool-config)=
### Storage pool configuration
Expand All @@ -64,10 +65,13 @@ Key | Type | Default
`cephfs.create_missing` | bool | `false` | Create the file system and the missing data and metadata OSD pools
`cephfs.data_pool` | string | - | Data OSD pool name to create for the file system
`cephfs.fscache` | bool | `false` | Enable use of kernel `fscache` and `cachefilesd`
`cephfs.fsid` | string | - | Ceph cluster FSID, overrides `cluster_name`. Can usually be inferred.
`cephfs.meta_pool` | string | - | Metadata OSD pool name to create for the file system
`cephfs.mon_addr` | string | - | Ceph mon addresses, usually not required.
`cephfs.osd_pg_num` | string | - | OSD pool `pg_num` to use when creating missing OSD pools
`cephfs.path` | string | `/` | The base path for the CephFS mount
`cephfs.user.name` | string | `admin` | The Ceph user to use
`cephfs.user.key` | string | - | Ceph user key, usually not required.
`source` | string | - | Existing CephFS file system or file system path to use
`volatile.pool.pristine` | string | `true` | Whether the CephFS file system was empty on creation time

Expand Down
44 changes: 44 additions & 0 deletions internal/server/device/disk.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,38 @@ func (d *disk) validateConfig(instConf instance.ConfigReader) error {
// shortdesc: The cluster name of the Ceph cluster (required for Ceph or CephFS sources)
"ceph.cluster_name": validate.IsAny,

// gendoc:generate(entity=devices, group=disk, key=ceph.fsid)
// Uniquely identifies the ceph cluster
//
// Overrides ceph.cluster_name
// This will usually be retrieved from ceph.conf or the cluster directly
// using `ceph-conf` or `ceph` respectively. If these tools are not available
// then this will need to be provided.
//
// ---
// type: string
// required: no
// shortdesc: Ceph File System ID
"ceph.fsid": validate.Optional(validate.IsUUID),

// gendoc:generate(entity=devices, group=disk, key=ceph.mon_addr)
// Used to establish connection to the ceph cluster.
//
// This will usually be retrieved from ceph.conf or the cluster directly
// using `ceph-conf` or `ceph` respectively. If these tools are not available
// then this will need to be provided. Can be provided as ip addresses or
// hostnames, port is optional
//
// Has the form:
// mon1:3300,1.2.3.4:5678,mon2.example.net:6789
// ---
// type: string
// required: no
// shortdesc: Ceph monitor address(es)
"ceph.mon_addr": validate.Optional(
validate.IsListOf(validate.IsListenAddress(true, false, false)),
),

// gendoc:generate(entity=devices, group=disk, key=ceph.user_name)
//
// ---
Expand All @@ -309,6 +341,18 @@ func (d *disk) validateConfig(instConf instance.ConfigReader) error {
// shortdesc: The user name of the Ceph cluster (required for Ceph or CephFS sources)
"ceph.user_name": validate.IsAny,

// gendoc:generate(entity=devices, group=disk, key=ceph.user_key)
// Used if authentication with cephx is required.
//
// If needed at all will usually be retrieved using the `ceph-conf` tool.
// However if this is not available on the host or the key is not accessible
// to those tools then this will need to be provided.
// ---
// type: string
// required: no
// shortdesc: Ceph user key
"ceph.user_key": validate.IsAny,

// gendoc:generate(entity=devices, group=disk, key=boot.priority)
//
// ---
Expand Down
32 changes: 32 additions & 0 deletions internal/server/metadata/configuration.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,30 @@
"type": "string"
}
},
{
"ceph.fsid": {
"longdesc": "Uniquely identifies the ceph cluster\n\nOverrides ceph.cluster_name\nThis will usually be retrieved from ceph.conf or the cluster directly\nusing `ceph-conf` or `ceph` respectively. If these tools are not available\nthen this will need to be provided.\n",
"required": "no",
"shortdesc": "Ceph File System ID",
"type": "string"
}
},
{
"ceph.mon_addr": {
"longdesc": "Used to establish connection to the ceph cluster.\n\nThis will usually be retrieved from ceph.conf or the cluster directly\nusing `ceph-conf` or `ceph` respectively. If these tools are not available\nthen this will need to be provided. Can be provided as ip addresses or\nhostnames, port is optional\n\nHas the form:\nmon1:3300,1.2.3.4:5678,mon2.example.net:6789",
"required": "no",
"shortdesc": "Ceph monitor address(es)",
"type": "string"
}
},
{
"ceph.user_key": {
"longdesc": "Used if authentication with cephx is required.\n\nIf needed at all will usually be retrieved using the `ceph-conf` tool.\nHowever if this is not available on the host or the key is not accessible\nto those tools then this will need to be provided.",
"required": "no",
"shortdesc": "Ceph user key",
"type": "string"
}
},
{
"ceph.user_name": {
"default": "`admin`",
Expand All @@ -77,6 +101,14 @@
"type": "string"
}
},
{
"ceph.user_key": {
"required": "no",
"type": "string",
"shortdesc": "Ceph user key",
"longdesc": "Usually inferred using Ceph client tools on the host."
}
},
{
"initial.*": {
"longdesc": "",
Expand Down
3 changes: 3 additions & 0 deletions internal/server/storage/drivers/driver_cephfs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -387,9 +387,12 @@ func (d *cephfs) Delete(op *operations.Operation) error {
func (d *cephfs) Validate(config map[string]string) error {
rules := map[string]func(value string) error{
"cephfs.cluster_name": validate.IsAny,
"cephfs.fsid": validate.Optional(validate.IsUUID),
"cephfs.mon_addr": validate.Optional(validate.IsListOf(validate.IsListenAddress(true, false, false))),
"cephfs.fscache": validate.Optional(validate.IsBool),
"cephfs.path": validate.IsAny,
"cephfs.user.name": validate.IsAny,
"cephfs.user.secret": validate.Optional(validate.IsAny),
"cephfs.create_missing": validate.Optional(validate.IsBool),
"cephfs.osd_pg_num": validate.Optional(validate.IsInt64),
"cephfs.meta_pool": validate.IsAny,
Expand Down

0 comments on commit 586c56a

Please sign in to comment.