ceph/doc/cephadm/nfs.rst

   1 .. _deploy-cephadm-nfs-ganesha:
   2
   3 ===========
   4 NFS Service
   5 ===========
   6
   7 .. note:: Only the NFSv4 protocol is supported.
   8
   9 The simplest way to manage NFS is via the ``ceph nfs cluster ...``
  10 commands; see :ref:`cephfs-nfs`.  This document covers how to manage the
  11 cephadm services directly, which should only be necessary for unusual NFS
  12 configurations.
  13
  14 Deploying NFS ganesha
  15 =====================
  16
  17 Cephadm deploys NFS Ganesha daemon (or set of daemons).  The configuration for
  18 NFS is stored in the ``nfs-ganesha`` pool and exports are managed via the
  19 ``ceph nfs export ...`` commands and via the dashboard.
  20
  21 To deploy a NFS Ganesha gateway, run the following command:
  22
  23 .. prompt:: bash #
  24
  25     ceph orch apply nfs *<svc_id>* [--port *<port>*] [--placement ...]
  26
  27 For example, to deploy NFS with a service id of *foo* on the default
  28 port 2049 with the default placement of a single daemon:
  29
  30 .. prompt:: bash #
  31
  32    ceph orch apply nfs foo
  33
  34 See :ref:`orchestrator-cli-placement-spec` for the details of the placement
  35 specification.
  36
  37 Service Specification
  38 =====================
  39
  40 Alternatively, an NFS service can be applied using a YAML specification.
  41
  42 .. code-block:: yaml
  43
  44     service_type: nfs
  45     service_id: mynfs
  46     placement:
  47       hosts:
  48         - host1
  49         - host2
  50     spec:
  51       port: 12345
  52
  53 In this example, we run the server on the non-default ``port`` of
  54 12345 (instead of the default 2049) on ``host1`` and ``host2``.
  55
  56 The specification can then be applied by running the following command:
  57
  58 .. prompt:: bash #
  59
  60    ceph orch apply -i nfs.yaml
  61
  62
  63 High-availability NFS
  64 =====================
  65
  66 Deploying an *ingress* service for an existing *nfs* service will provide:
  67
  68 * a stable, virtual IP that can be used to access the NFS server
  69 * fail-over between hosts if there is a host failure
  70 * load distribution across multiple NFS gateways (although this is rarely necessary)
  71
  72 Ingress for NFS can be deployed for an existing NFS service
  73 (``nfs.mynfs`` in this example) with the following specification:
  74
  75 .. code-block:: yaml
  76
  77     service_type: ingress
  78     service_id: nfs.mynfs
  79     placement:
  80       count: 2
  81     spec:
  82       backend_service: nfs.mynfs
  83       frontend_port: 2049
  84       monitor_port: 9000
  85       virtual_ip: 10.0.0.123/24
  86
  87 A few notes:
  88
  89   * The *virtual_ip* must include a CIDR prefix length, as in the
  90     example above.  The virtual IP will normally be configured on the
  91     first identified network interface that has an existing IP in the
  92     same subnet.  You can also specify a *virtual_interface_networks*
  93     property to match against IPs in other networks; see
  94     :ref:`ingress-virtual-ip` for more information.
  95   * The *monitor_port* is used to access the haproxy load status
  96     page.  The user is ``admin`` by default, but can be modified by
  97     via an *admin* property in the spec.  If a password is not
  98     specified via a *password* property in the spec, the auto-generated password
  99     can be found with:
 100
 101     .. prompt:: bash #
 102
 103         ceph config-key get mgr/cephadm/ingress.*{svc_id}*/monitor_password
 104
 105     For example:
 106
 107     .. prompt:: bash #
 108
 109         ceph config-key get mgr/cephadm/ingress.nfs.myfoo/monitor_password
 110
 111   * The backend service (``nfs.mynfs`` in this example) should include
 112     a *port* property that is not 2049 to avoid conflicting with the
 113     ingress service, which could be placed on the same host(s).