Skip to content

Commit c743075

Browse files
adk3798adk3798
authored
Merge pull request ceph#55068 from phlogistonjohn/jjm-cephadm-smb-svc-spec
cephadm: add a new SMB service to the mgr module Reviewed-by: Adam King <[email protected]>
2 parents 3b8cc0f + 8bb5fb6 commit c743075

File tree

24 files changed

+1928
-108
lines changed

24 files changed

+1928
-108
lines changed

‎doc/cephadm/services/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ for details on individual services:
1919
monitoring
2020
snmp-gateway
2121
tracing
22+
smb
2223

2324
Service Status
2425
==============

‎doc/cephadm/services/smb.rst‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. _deploy-cephadm-smb-samba:
2+
3+
===========
4+
SMB Service
5+
===========
6+
7+
.. note:: Only the SMB3 protocol is supported.
8+
9+
.. warning::
10+
11+
SMB support is under active development and many features may be
12+
missing or immature. Additionally, a Manager module to automate
13+
SMB clusters and SMB shares is in development. Once that feature
14+
is developed it will be the preferred method for managing
15+
SMB on ceph.
16+
17+
18+
Deploying Samba Containers
19+
==========================
20+
21+
Cephadm deploys `Samba <http://www.samba.org>`_ servers using container images
22+
built by the `samba-container project <http://github.com/samba-in-kubernetes/samba-container>`_.
23+
24+
In order to host SMB Shares with access to CephFS file systems, deploy
25+
Samba Containers with the following command:
26+
27+
.. prompt:: bash #
28+
29+
orch apply smb <cluster_id> <config_uri> [--features ...] [--placement ...] ...
30+
31+
There are a number of additional parameters that the command accepts. See
32+
the Service Specification for a description of these options.
33+
34+
Service Specification
35+
=====================
36+
37+
An SMB Service can be applied using a specification. An example in YAML follows:
38+
39+
.. code-block:: yaml
40+
41+
service_type: smb
42+
service_id: tango
43+
placement:
44+
hosts:
45+
- ceph0
46+
spec:
47+
cluster_id: tango
48+
features:
49+
- domain
50+
config_uri: rados://.smb/tango/scc.toml
51+
custom_dns:
52+
- "192.168.76.204"
53+
join_sources:
54+
- "rados:mon-config-key:smb/config/tango/join1.json"
55+
include_ceph_users:
56+
- client.smb.fs.cluster.tango
57+
58+
The specification can then be applied by running the following command:
59+
60+
.. prompt:: bash #
61+
62+
ceph orch apply -i smb.yaml
63+
64+
65+
Service Spec Options
66+
--------------------
67+
68+
Fields specific to the ``spec`` section of the SMB Service are described below.
69+
70+
cluster_id
71+
A short name identifying the SMB "cluster". In this case a cluster is
72+
simply a management unit of one or more Samba services sharing a common
73+
configuration, and may not provide actual clustering or availability
74+
mechanisms.
75+
76+
features
77+
A list of pre-defined terms enabling specific deployment characteristics.
78+
An empty list is valid. Supported terms:
79+
80+
* ``domain``: Enable domain member mode
81+
82+
config_uri
83+
A string containing a (standard or de-facto) URI that identifies a
84+
configuration source that should be loaded by the samba-container as the
85+
primary configuration file.
86+
Supported URI schemes include ``http:``, ``https:``, ``rados:``, and
87+
``rados:mon-config-key:``.
88+
89+
join_sources
90+
A list of strings with (standard or de-facto) URI values that will
91+
be used to identify where authentication data that will be used to
92+
perform domain joins are located. Each join source is tried in sequence
93+
until one succeeds.
94+
See ``config_uri`` for the supported list of URI schemes.
95+
96+
custom_dns
97+
A list of IP addresses that will be used as the DNS servers for a Samba
98+
container. This features allows Samba Containers to integrate with
99+
Active Directory even if the Ceph host nodes are not tied into the Active
100+
Directory DNS domain(s).
101+
102+
include_ceph_users:
103+
A list of cephx user (aka entity) names that the Samba Containers may use.
104+
The cephx keys for each user in the list will automatically be added to
105+
the keyring in the container.
106+
107+
108+
Configuring an SMB Service
109+
--------------------------
110+
111+
.. warning::
112+
113+
A Manager module for SMB is under active development. Once that module
114+
is available it will be the preferred method for managing Samba on Ceph
115+
in an end-to-end manner. The following discussion is provided for the sake
116+
of completeness and to explain how the software layers interact.
117+
118+
Creating an SMB Service spec is not sufficient for complete operation of a
119+
Samba Container on Ceph. It is important to create valid configurations and
120+
place them in locations that the container can read. The complete specification
121+
of these configurations is out of scope for this document. You can refer to the
122+
`documentation for Samba <https://wiki.samba.org/index.php/Main_Page>`_ as
123+
well as the `samba server container
124+
<https://github.com/samba-in-kubernetes/samba-container/blob/master/docs/server.md>`_
125+
and the `configuation file
126+
<https://github.com/samba-in-kubernetes/sambacc/blob/master/docs/configuration.md>`_
127+
it accepts.
128+
129+
When one has composed a configuration it should be stored in a location
130+
that the Samba Container can access. The recommended approach for running
131+
Samba Containers within Ceph orchestration is to store the configuration
132+
in the Ceph cluster. There are two ways to store the configuration
133+
in ceph:
134+
135+
RADOS
136+
~~~~~
137+
138+
A configuration file can be stored as a RADOS object in a pool
139+
named ``.smb``. Within the pool there should be a namespace named after the
140+
``cluster_id`` value. The URI used to identify this resource should be
141+
constructed like ``rados://.smb/<cluster_id>/<object_name>``. Example:
142+
``rados://.smb/tango/config.json``.
143+
144+
The containers are automatically deployed with cephx keys allowing access to
145+
resources in these pools and namespaces. As long as this scheme is used
146+
no additional configuration to read the object is needed.
147+
148+
To copy a configuration file to a RADOS pool, use the ``rados`` command line
149+
tool. For example:
150+
151+
.. prompt:: bash #
152+
153+
# assuming your config file is /tmp/config.json
154+
rados --pool=.smb --namespace=tango put config.json /tmp/config.json
155+
156+
MON Key/Value Store
157+
~~~~~~~~~~~~~~~~~~~
158+
159+
A configuration file can be stored as a value in the Ceph Monitor Key/Value
160+
store. The key must be named after the cluster like so:
161+
``smb/config/<cluster_id>/<name>``. This results in a URI that can be used to
162+
identify this configuration constructed like
163+
``rados:mon-config-key:smb/config/<cluster_id>/<name>``.
164+
Example: ``rados:mon-config-key:smb/config/tango/config.json``.
165+
166+
The containers are automatically deployed with cephx keys allowing access to
167+
resources with the key-prefix ``smb/config/<cluster_id>/``. As long as this
168+
scheme is used no additional configuration to read the value is needed.
169+
170+
To copy a configuration file into the Key/Value store use the ``ceph config-key
171+
put ...`` tool. For example:
172+
173+
.. prompt:: bash #
174+
175+
# assuming your config file is /tmp/config.json
176+
ceph config-key set smb/config/tango/config.json -i /tmp/config.json
177+
178+
179+
HTTP/HTTPS
180+
~~~~~~~~~~
181+
182+
A configuration file can be stored on an HTTP(S) server and automatically read
183+
by the Samba Container. Managing a configuration file on HTTP(S) is left as an
184+
exercise for the reader.
185+
186+
.. note:: All URI schemes are supported by parameters that accept URIs. Each
187+
scheme has different performance and security characteristics.
188+
189+
190+
Limitations
191+
===========
192+
193+
A non-exhaustive list of important limitations for the SMB service follows:
194+
195+
* DNS is a critical component of Active Directory. If one is configuring the
196+
SMB service for domain membership, either the Ceph host node must be
197+
configured so that it can resolve the Active Directory (AD) domain or the
198+
``custom_dns`` option may be used. In both cases DNS hosts for the AD domain
199+
must still be reachable from whatever network segment the ceph cluster is on.
200+
* Proper clustering/high-availability/"transparent state migration" is not yet
201+
supported. If a placement causes more than service to be created these
202+
services will act independently and may lead to unexpected behavior if clients
203+
access the same files at once.
204+
* Services must bind to TCP port 445. Running multiple SMB services on the same
205+
node is not yet supported and will trigger a port-in-use conflict.

‎qa/suites/orch/cephadm/smb/%‎

Whitespace-only changes.

‎qa/suites/orch/cephadm/smb/.qa‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.qa

‎qa/suites/orch/cephadm/smb/0-distro‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.qa/distros/supported-container-hosts

‎qa/suites/orch/cephadm/smb/tasks/.qa‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.qa

‎qa/suites/orch/cephadm/smb/tasks/deploy_smb_basic.yaml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
roles:
3+
# Test is for basic smb deployment & functionality. one node cluster is OK
4+
- - host.a
5+
- mon.a
6+
- mgr.x
7+
- osd.0
8+
- osd.1
9+
- client.0
10+
# Reserve a host for acting as a test client
11+
- - host.b
12+
- cephadm.exclude
13+
tasks:
14+
# TODO: (jjm) I don't think `install` is necessary for this file. Remove?
15+
- install:
16+
- cephadm.configure_samba_client_container:
17+
role: host.b
18+
- cephadm:
19+
- cephadm.shell:
20+
host.a:
21+
- ceph fs volume create cephfs
22+
- cephadm.wait_for_service:
23+
service: mds.cephfs
24+
- cephadm.shell:
25+
host.a:
26+
# create a subvolume so we can verify that we're sharing something
27+
- cmd: ceph fs subvolumegroup create cephfs g1
28+
- cmd: ceph fs subvolume create cephfs sub1 --group-name=g1 --mode=0777
29+
# Create a user access the file system from samba
30+
- cmd: ceph fs authorize cephfs client.smbdata / rw
31+
# Create a rados pool and store the config in it
32+
- cmd: ceph osd pool create .smb --yes-i-really-mean-it
33+
- cmd: ceph osd pool application enable .smb smb
34+
- cmd: rados --pool=.smb --namespace=saserv1 put conf.toml /dev/stdin
35+
stdin: |
36+
samba-container-config = "v0"
37+
[configs.saserv1]
38+
shares = ["share1"]
39+
globals = ["default", "domain"]
40+
instance_name = "SAMBA"
41+
[shares.share1.options]
42+
"vfs objects" = "ceph"
43+
path = "/"
44+
"ceph:config_file" = "/etc/ceph/ceph.conf"
45+
"ceph:user_id" = "smbdata"
46+
"kernel share modes" = "no"
47+
"read only" = "no"
48+
"browseable" = "yes"
49+
[globals.default.options]
50+
"server min protocol" = "SMB2"
51+
"load printers" = "no"
52+
"printing" = "bsd"
53+
"printcap name" = "/dev/null"
54+
"disable spoolss" = "yes"
55+
"guest ok" = "no"
56+
[globals.domain.options]
57+
security = "USER"
58+
workgroup = "STANDALONE1"
59+
[[users.all_entries]]
60+
name = "smbuser1"
61+
password = "insecure321"
62+
- cephadm.apply:
63+
specs:
64+
- service_type: smb
65+
service_id: saserv1
66+
placement:
67+
count: 1
68+
cluster_id: saserv1
69+
config_uri: "rados://.smb/saserv1/conf.toml"
70+
include_ceph_users:
71+
- "client.smbdata"
72+
- cephadm.wait_for_service:
73+
service: smb.saserv1
74+
- cephadm.exec:
75+
host.b:
76+
- sleep 30
77+
- "{{ctx.samba_client_container_cmd|join(' ')}} smbclient -U smbuser1%insecure321 //{{'host.a'|role_to_remote|attr('ip_address')}}/share1 -c ls"

‎qa/suites/orch/cephadm/smb/tasks/deploy_smb_domain.yaml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
roles:
2+
# Test is for basic smb deployment & functionality. one node cluster is OK
3+
- - host.a
4+
- mon.a
5+
- mgr.x
6+
- osd.0
7+
- osd.1
8+
- client.0
9+
# Reserve a host for acting as a domain controller
10+
- - host.b
11+
- cephadm.exclude
12+
tasks:
13+
- cephadm.deploy_samba_ad_dc:
14+
role: host.b
15+
- cephadm:
16+
17+
- cephadm.shell:
18+
host.a:
19+
- ceph fs volume create cephfs
20+
- cephadm.wait_for_service:
21+
service: mds.cephfs
22+
23+
- cephadm.shell:
24+
host.a:
25+
# create a subvolume so we can verify that we're sharing something
26+
- cmd: ceph fs subvolumegroup create cephfs g1
27+
- cmd: ceph fs subvolume create cephfs sub1 --group-name=g1 --mode=0777
28+
# Create a user access the file system from samba
29+
- cmd: ceph fs authorize cephfs client.smbdata / rw
30+
# Create a rados pool and store the config in it
31+
- cmd: ceph osd pool create .smb --yes-i-really-mean-it
32+
- cmd: ceph osd pool application enable .smb smb
33+
- cmd: rados --pool=.smb --namespace=admem1 put conf.toml /dev/stdin
34+
stdin: |
35+
samba-container-config = "v0"
36+
[configs.admem1]
37+
shares = ["share1"]
38+
globals = ["default", "domain"]
39+
instance_name = "SAMBA"
40+
[shares.share1.options]
41+
"vfs objects" = "ceph"
42+
path = "/"
43+
"ceph:config_file" = "/etc/ceph/ceph.conf"
44+
"ceph:user_id" = "smbdata"
45+
"kernel share modes" = "no"
46+
"read only" = "no"
47+
"browseable" = "yes"
48+
[globals.default.options]
49+
"server min protocol" = "SMB2"
50+
"load printers" = "no"
51+
"printing" = "bsd"
52+
"printcap name" = "/dev/null"
53+
"disable spoolss" = "yes"
54+
"guest ok" = "no"
55+
[globals.domain.options]
56+
security = "ads"
57+
workgroup = "DOMAIN1"
58+
realm = "domain1.sink.test"
59+
"idmap config * : backend" = "autorid"
60+
"idmap config * : range" = "2000-9999999"
61+
# Store the join auth user/pass in the config-key store
62+
- cmd: ceph config-key set smb/config/admem1/join1.json -i -
63+
stdin: |
64+
{"username": "Administrator", "password": "Passw0rd"}
65+
66+
- cephadm.apply:
67+
specs:
68+
- service_type: smb
69+
service_id: admem1
70+
placement:
71+
count: 1
72+
cluster_id: admem1
73+
features:
74+
- domain
75+
config_uri: "rados://.smb/admem1/conf.toml"
76+
custom_dns:
77+
- "{{ctx.samba_ad_dc_ip}}"
78+
join_sources:
79+
- "rados:mon-config-key:smb/config/admem1/join1.json"
80+
include_ceph_users:
81+
- "client.smbdata"
82+
- cephadm.wait_for_service:
83+
service: smb.admem1
84+
85+
- cephadm.exec:
86+
host.b:
87+
- sleep 30
88+
- "{{ctx.samba_client_container_cmd|join(' ')}} smbclient -U DOMAIN1\\\\ckent%1115Rose. //{{'host.a'|role_to_remote|attr('ip_address')}}/share1 -c ls"

0 commit comments

Comments
 (0)