Managing SMB shares by using declarative method

Learn to create, remove, modify, and list SMB shares by using declarative method.

Before you begin

  • Gather information about the domain when using active-directory.
  • Create a domain user to join to active directory (AD).
  • Determine whether you need to use custom_dns setting
  • Know which users to define if you are not using AD.

About this task

This method uses the command ceph smb apply to process resource descriptions specified in YAML or JSON, similar to service specifications for Ceph orchestration with cephadm, by using SMB-specific resource types.

Creating SMB shares

About this task

Learn how to create the SMB shares by using the declarative method.

Procedure

Create an SMB share with the declarative method by setting the resource_type to ceph.smb.share in the specification file. 
resource_type: ceph.smb.share

The name parameter specifies the display name for SMB clients and corresponds to the --share-name flag in imperative commands. If omitted, the share_id is used as the share name.

Share name validation rules:

  • Maximum 64 characters
  • Must start with alphanumeric (a-z, A-Z, 0-9) or underscore (_)
  • May contain alphanumeric, spaces, underscores (_), periods (.), hyphens (-)
  • Pattern: ^[a-zA-Z0-9_][a-zA-Z0-9. _-]{,63}$
For example, 
resource_type: ceph.smb.share
cluster_id: tango
share_id: sp1
name: "Staff Pics"
cephfs:
  volume: cephfs
  path: /pics
  subvolumegroup: smbshares
  subvolume: staff

Modifying SMB shares

About this task

Learn how to modify the SMB shares by using the declarative method.

When you modify an SMB share, you do not create a new resource. Instead, you resubmit the existing resource definition with the same cluster_id and share_id values. The Ceph SMB module treats this submission as an update to the existing SMB share configuration.

Procedure

Modify the SMB share by editing the existing specification file and resubmitting it with the same cluster_id and share_id values.
For example, before modification: 
resource_type: ceph.smb.share
cluster_id: tango
share_id: sp1
name: "Staff Pics"
cephfs:
  volume: cephfs
  path: /pics
  subvolumegroup: smbshares
  subvolume: staff
After modification, the name and CephFS path values are updated: 
resource_type: ceph.smb.share
cluster_id: tango
share_id: sp1
name: "Team Photos"
cephfs:
  volume: cephfs
  path: /team-pics
  subvolumegroup: smbshares
  subvolume: staff

Apply the updated specification file:

ceph smb apply -i updated-share.yaml

The following changes are not supported when you update an existing SMB share:

  • You cannot change the resource type. For example, a resource defined as ceph.smb.share cannot be changed to another resource type by using the same ID.
  • You cannot modify immutable identifiers such as cluster_id and share_id.
  • You cannot modify domain or join configuration after the resource is deployed.
Note: If you need to change an immutable property, delete the existing resource and recreate it with the required configuration.

Removing SMB shares

About this task

Learn how to remove the SMB shares by using the declarative method.

Procedure

Remove the SMB share by setting the intent to removed. 
intent: removed
For example, 
resource_type: ceph.smb.share
cluster_id: tango
share_id: sp2
intent: removed