mirror of
https://github.com/ceph/ceph
synced 2025-01-12 06:00:46 +00:00
4e897de322
Signed-off-by: John Mulligan <jmulligan@redhat.com>
206 lines
7.4 KiB
ReStructuredText
206 lines
7.4 KiB
ReStructuredText
.. _deploy-cephadm-smb-samba:
|
|
|
|
===========
|
|
SMB Service
|
|
===========
|
|
|
|
.. note:: Only the SMB3 protocol is supported.
|
|
|
|
.. warning::
|
|
|
|
SMB support is under active development and many features may be
|
|
missing or immature. Additionally, a Manager module to automate
|
|
SMB clusters and SMB shares is in development. Once that feature
|
|
is developed it will be the preferred method for managing
|
|
SMB on ceph.
|
|
|
|
|
|
Deploying Samba Containers
|
|
==========================
|
|
|
|
Cephadm deploys `Samba <http://www.samba.org>`_ servers using container images
|
|
built by the `samba-container project <http://github.com/samba-in-kubernetes/samba-container>`_.
|
|
|
|
In order to host SMB Shares with access to CephFS file systems, deploy
|
|
Samba Containers with the following command:
|
|
|
|
.. prompt:: bash #
|
|
|
|
orch apply smb <cluster_id> <config_uri> [--features ...] [--placement ...] ...
|
|
|
|
There are a number of additional parameters that the command accepts. See
|
|
the Service Specification for a description of these options.
|
|
|
|
Service Specification
|
|
=====================
|
|
|
|
An SMB Service can be applied using a specification. An example in YAML follows:
|
|
|
|
.. code-block:: yaml
|
|
|
|
service_type: smb
|
|
service_id: tango
|
|
placement:
|
|
hosts:
|
|
- ceph0
|
|
spec:
|
|
cluster_id: tango
|
|
features:
|
|
- domain
|
|
config_uri: rados://.smb/tango/scc.toml
|
|
custom_dns:
|
|
- "192.168.76.204"
|
|
join_sources:
|
|
- "rados:mon-config-key:smb/config/tango/join1.json"
|
|
include_ceph_users:
|
|
- client.smb.fs.cluster.tango
|
|
|
|
The specification can then be applied by running the following command:
|
|
|
|
.. prompt:: bash #
|
|
|
|
ceph orch apply -i smb.yaml
|
|
|
|
|
|
Service Spec Options
|
|
--------------------
|
|
|
|
Fields specific to the ``spec`` section of the SMB Service are described below.
|
|
|
|
cluster_id
|
|
A short name identifying the SMB "cluster". In this case a cluster is
|
|
simply a management unit of one or more Samba services sharing a common
|
|
configuration, and may not provide actual clustering or availability
|
|
mechanisms.
|
|
|
|
features
|
|
A list of pre-defined terms enabling specific deployment characteristics.
|
|
An empty list is valid. Supported terms:
|
|
|
|
* ``domain``: Enable domain member mode
|
|
|
|
config_uri
|
|
A string containing a (standard or de-facto) URI that identifies a
|
|
configuration source that should be loaded by the samba-container as the
|
|
primary configuration file.
|
|
Supported URI schemes include ``http:``, ``https:``, ``rados:``, and
|
|
``rados:mon-config-key:``.
|
|
|
|
join_sources
|
|
A list of strings with (standard or de-facto) URI values that will
|
|
be used to identify where authentication data that will be used to
|
|
perform domain joins are located. Each join source is tried in sequence
|
|
until one succeeds.
|
|
See ``config_uri`` for the supported list of URI schemes.
|
|
|
|
custom_dns
|
|
A list of IP addresses that will be used as the DNS servers for a Samba
|
|
container. This features allows Samba Containers to integrate with
|
|
Active Directory even if the Ceph host nodes are not tied into the Active
|
|
Directory DNS domain(s).
|
|
|
|
include_ceph_users:
|
|
A list of cephx user (aka entity) names that the Samba Containers may use.
|
|
The cephx keys for each user in the list will automatically be added to
|
|
the keyring in the container.
|
|
|
|
|
|
Configuring an SMB Service
|
|
--------------------------
|
|
|
|
.. warning::
|
|
|
|
A Manager module for SMB is under active development. Once that module
|
|
is available it will be the preferred method for managing Samba on Ceph
|
|
in an end-to-end manner. The following discussion is provided for the sake
|
|
of completeness and to explain how the software layers interact.
|
|
|
|
Creating an SMB Service spec is not sufficient for complete operation of a
|
|
Samba Container on Ceph. It is important to create valid configurations and
|
|
place them in locations that the container can read. The complete specification
|
|
of these configurations is out of scope for this document. You can refer to the
|
|
`documentation for Samba <https://wiki.samba.org/index.php/Main_Page>`_ as
|
|
well as the `samba server container
|
|
<https://github.com/samba-in-kubernetes/samba-container/blob/master/docs/server.md>`_
|
|
and the `configuation file
|
|
<https://github.com/samba-in-kubernetes/sambacc/blob/master/docs/configuration.md>`_
|
|
it accepts.
|
|
|
|
When one has composed a configuration it should be stored in a location
|
|
that the Samba Container can access. The recommended approach for running
|
|
Samba Containers within Ceph orchestration is to store the configuration
|
|
in the Ceph cluster. There are two ways to store the configuration
|
|
in ceph:
|
|
|
|
RADOS
|
|
~~~~~
|
|
|
|
A configuration file can be stored as a RADOS object in a pool
|
|
named ``.smb``. Within the pool there should be a namespace named after the
|
|
``cluster_id`` value. The URI used to identify this resource should be
|
|
constructed like ``rados://.smb/<cluster_id>/<object_name>``. Example:
|
|
``rados://.smb/tango/config.json``.
|
|
|
|
The containers are automatically deployed with cephx keys allowing access to
|
|
resources in these pools and namespaces. As long as this scheme is used
|
|
no additional configuration to read the object is needed.
|
|
|
|
To copy a configuration file to a RADOS pool, use the ``rados`` command line
|
|
tool. For example:
|
|
|
|
.. prompt:: bash #
|
|
|
|
# assuming your config file is /tmp/config.json
|
|
rados --pool=.smb --namespace=tango put config.json /tmp/config.json
|
|
|
|
MON Key/Value Store
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
A configuration file can be stored as a value in the Ceph Monitor Key/Value
|
|
store. The key must be named after the cluster like so:
|
|
``smb/config/<cluster_id>/<name>``. This results in a URI that can be used to
|
|
identify this configuration constructed like
|
|
``rados:mon-config-key:smb/config/<cluster_id>/<name>``.
|
|
Example: ``rados:mon-config-key:smb/config/tango/config.json``.
|
|
|
|
The containers are automatically deployed with cephx keys allowing access to
|
|
resources with the key-prefix ``smb/config/<cluster_id>/``. As long as this
|
|
scheme is used no additional configuration to read the value is needed.
|
|
|
|
To copy a configuration file into the Key/Value store use the ``ceph config-key
|
|
put ...`` tool. For example:
|
|
|
|
.. prompt:: bash #
|
|
|
|
# assuming your config file is /tmp/config.json
|
|
ceph config-key set smb/config/tango/config.json -i /tmp/config.json
|
|
|
|
|
|
HTTP/HTTPS
|
|
~~~~~~~~~~
|
|
|
|
A configuration file can be stored on an HTTP(S) server and automatically read
|
|
by the Samba Container. Managing a configuration file on HTTP(S) is left as an
|
|
exercise for the reader.
|
|
|
|
.. note:: All URI schemes are supported by parameters that accept URIs. Each
|
|
scheme has different performance and security characteristics.
|
|
|
|
|
|
Limitations
|
|
===========
|
|
|
|
A non-exhaustive list of important limitations for the SMB service follows:
|
|
|
|
* DNS is a critical component of Active Directory. If one is configuring the
|
|
SMB service for domain membership, either the Ceph host node must be
|
|
configured so that it can resolve the Active Directory (AD) domain or the
|
|
``custom_dns`` option may be used. In both cases DNS hosts for the AD domain
|
|
must still be reachable from whatever network segment the ceph cluster is on.
|
|
* Proper clustering/high-availability/"transparent state migration" is not yet
|
|
supported. If a placement causes more than service to be created these
|
|
services will act independently and may lead to unexpected behavior if clients
|
|
access the same files at once.
|
|
* Services must bind to TCP port 445. Running multiple SMB services on the same
|
|
node is not yet supported and will trigger a port-in-use conflict.
|