From 91f35e1f5355bb4d1c9e7be4a943d564483f4e13 Mon Sep 17 00:00:00 2001 From: Paul Cuzner Date: Fri, 12 Nov 2021 16:17:52 +1300 Subject: [PATCH] mgr/cephadm: Updated docs for snmp-gateway support Updated docs to show snmp-gateway usage. docs provide guidance on SNMP versions supported and show CLI and yaml deployment examples. Signed-off-by: Paul Cuzner --- doc/cephadm/services/index.rst | 27 ++-- doc/cephadm/services/snmp-gateway.rst | 171 ++++++++++++++++++++++++++ doc/mgr/orchestrator.rst | 13 +- 3 files changed, 197 insertions(+), 14 deletions(-) create mode 100644 doc/cephadm/services/snmp-gateway.rst diff --git a/doc/cephadm/services/index.rst b/doc/cephadm/services/index.rst index f34180eb24fc6..3f08bf583bfce 100644 --- a/doc/cephadm/services/index.rst +++ b/doc/cephadm/services/index.rst @@ -17,6 +17,7 @@ for details on individual services: iscsi custom-container monitoring + snmp-gateway Service Status ============== @@ -25,8 +26,8 @@ Service Status To see the status of one of the services running in the Ceph cluster, do the following: -#. Use the command line to print a list of services. -#. Locate the service whose status you want to check. +#. Use the command line to print a list of services. +#. Locate the service whose status you want to check. #. Print the status of the service. The following command prints a list of services known to the orchestrator. To @@ -78,7 +79,7 @@ system name: .. prompt:: bash # ceph orch ps --daemon_type osd --daemon_id 0 - + .. _orchestrator-cli-service-spec: Service Specification @@ -147,7 +148,7 @@ the Services Specification, we suggest exporting the running Service Specificati following these instructions: .. prompt:: bash # - + ceph orch ls --service-name rgw.. --export > rgw...yaml ceph orch ls --service-type mgr --export > mgr.yaml ceph orch ls --export > cluster.yaml @@ -515,12 +516,12 @@ Deploying a daemon on a host manually .. note:: This workflow has a very limited use case and should only be used - in rare circumstances. + in rare circumstances. To manually deploy a daemon on a host, follow these steps: -Modify the service spec for a service by getting the -existing spec, adding ``unmanaged: true``, and applying the modified spec. +Modify the service spec for a service by getting the +existing spec, adding ``unmanaged: true``, and applying the modified spec. Then manually deploy the daemon using the following: @@ -534,12 +535,12 @@ For example : ceph orch daemon add mgr --placement=my_host -.. note:: +.. note:: - Removing ``unmanaged: true`` from the service spec will + Removing ``unmanaged: true`` from the service spec will enable the reconciliation loop for this service and will potentially lead to the removal of the daemon, depending - on the placement spec. + on the placement spec. Removing a daemon from a host manually -------------------------------------- @@ -556,13 +557,13 @@ For example: ceph orch daemon rm mgr.my_host.xyzxyz -.. note:: +.. note:: For managed services (``unmanaged=False``), cephadm will automatically deploy a new daemon a few seconds later. See also -------- - -* See :ref:`cephadm-osd-declarative` for special handling of unmanaged OSDs. + +* See :ref:`cephadm-osd-declarative` for special handling of unmanaged OSDs. * See also :ref:`cephadm-pause` diff --git a/doc/cephadm/services/snmp-gateway.rst b/doc/cephadm/services/snmp-gateway.rst new file mode 100644 index 0000000000000..f927fdfd0a388 --- /dev/null +++ b/doc/cephadm/services/snmp-gateway.rst @@ -0,0 +1,171 @@ +==================== +SNMP Gateway Service +==================== + +SNMP_ is still a widely used protocol, to monitor distributed systems and devices across a variety of hardware +and software platforms. Ceph's SNMP integration focuses on forwarding alerts from it's Prometheus Alertmanager +cluster to a gateway daemon. The gateway daemon, transforms the alert into an SNMP Notification and sends +it on to a designated SNMP management platform. The gateway daemon is from the snmp_notifier_ project, +which provides SNMP V2c and V3 support (authentication and encryption). + +Ceph's SNMP gateway service deploys one instance of the gateway by default. You may increase this +by providing placement information. However, bear in mind that if you enable multiple SNMP gateway daemons, +your SNMP management platform will receive multiple notifications for the same event. + +.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol +.. _snmp_notifier: https://github.com/maxwo/snmp_notifier + +Compatibility +============= +The table below shows the SNMP versions that are supported by the gateway implementation + +================ =========== =============================================== + SNMP Version Supported Notes +================ =========== =============================================== + V1 ❌ Not supported by snmp_notifier + V2c ✔ + V3 authNoPriv ✔ uses username/password authentication, without + encryption (NoPriv = no privacy) + V3 authPriv ✔ uses username/password authentication with + encryption to the SNMP management platform +================ =========== =============================================== + + +Deploying an SNMP Gateway +========================= +Both SNMP V2c and V3 provide credentials support. In the case of V2c, this is just the community string - but for V3 +environments you must provide additional authentication information. These credentials are not supported on the command +line when deploying the service. Instead, you must create the service using a credentials file (in yaml format), or +specify the complete service definition in a yaml file. + +Command format +-------------- + +.. prompt:: bash # + + ceph orch apply snmp-gateway [] [] [] [] [] ... + + +Usage Notes + +- you must supply the ``--snmp-version`` parameter +- the ``--destination`` parameter must be of the format hostname:port (no default) +- you may omit ``--port``. It defaults to 9464 +- the ``--engine-id`` is a unique identifier for the device (in hex) and required for SNMP v3 only. + Suggested value: 8000C53F where the fsid is from your cluster, without the '-' symbols +- for SNMP V3, the ``--auth-protocol`` setting defaults to **SHA** +- for SNMP V3, with encryption you must define the ``--privacy-protocol`` +- you **must** provide a -i to pass the secrets/passwords to the orchestrator + +Deployment Examples +=================== + +SNMP V2c +-------- +Here's an example for V2c, showing CLI and service based deployments + +.. prompt:: bash # + + ceph orch apply snmp-gateway --port 9464 --snmp_version=V2c --destination=192.168.122.73:162 -i ./snmp_creds.yaml + +with a credentials file that contains; + +.. code-block:: yaml + + --- + snmp_community: public + +Alternatively, you can create a yaml definition for the gateway and apply it from a single file + +.. prompt:: bash # + + ceph orch apply -i snmp-gateway.yml + +with the file containing the following configuration + +.. code-block:: yaml + + service_type: snmp-gateway + service_name: snmp-gateway + placement: + count: 1 + spec: + credentials: + snmp_community: public + port: 9464 + snmp_destination: 192.168.122.73:162 + snmp_version: V2c + + +SNMP V3 (authNoPriv) +-------------------- +Deploying an snmp-gateway service supporting SNMP V3 with authentication only, would look like this; + +.. prompt:: bash # + + ceph orch apply snmp-gateway --snmp-version=V3 --engine-id=800C53F000000 --destination=192.168.122.1:162 -i ./snmpv3_creds.yml + +with a credentials file as; + +.. code-block:: yaml + + --- + snmp_v3_auth_username: myuser + snmp_v3_auth_password: mypassword + +or as a service configuration file + +.. code-block:: yaml + + service_type: snmp-gateway + service_name: snmp-gateway + placement: + count: 1 + spec: + credentials: + snmp_v3_auth_password: mypassword + snmp_v3_auth_username: myuser + engine_id: 800C53F000000 + port: 9464 + snmp_destination: 192.168.122.1:162 + snmp_version: V3 + + +SNMP V3 (authPriv) +------------------ + +Defining an SNMP V3 gateway service that implements authentication and privacy (encryption), requires two additional values + +.. prompt:: bash # + + ceph orch apply snmp-gateway --snmp-version=V3 --engine-id=800C53F000000 --destination=192.168.122.1:162 --privacy-protocol=AES -i ./snmpv3_creds.yml + +with a credentials file as; + +.. code-block:: yaml + + --- + snmp_v3_auth_username: myuser + snmp_v3_auth_password: mypassword + snmp_v3_priv_password: mysecret + + +.. note:: + + The credentials are stored on the host, restricted to the root user and passed to the snmp_notifier daemon as + an environment file (``--env-file``), to limit exposure. + + +AlertManager Integration +======================== +When an SNMP gateway service is deployed or updated, the Prometheus Alertmanager configuration is automatically updated to forward any +alert that has an OID_ label to the SNMP gateway daemon for processing. + +.. _OID: https://en.wikipedia.org/wiki/Object_identifier + +Implementing the MIB +====================== +To make sense of the SNMP Notification/Trap, you'll need to apply the MIB to your SNMP management platform. The MIB (CEPH-MIB.txt) can +downloaded from the main Ceph repo_ + +.. _repo: https://github.com/ceph/ceph/tree/master/monitoring/snmp diff --git a/doc/mgr/orchestrator.rst b/doc/mgr/orchestrator.rst index ca35126bc2415..2f20667f20c11 100644 --- a/doc/mgr/orchestrator.rst +++ b/doc/mgr/orchestrator.rst @@ -157,11 +157,19 @@ This is an overview of the current implementation status of the orchestrators. apply nfs ✔ ✔ apply osd ✔ ✔ apply rbd-mirror ✔ ✔ - apply rgw ✔ ✔ + apply cephfs-mirror ⚪ ✔ + apply grafana ⚪ ✔ + apply prometheus ❌ ✔ + apply alertmanager ❌ ✔ + apply node-exporter ❌ ✔ + apply rgw ✔ ✔ apply container ⚪ ✔ + apply snmp-gateway ❌ ✔ host add ⚪ ✔ host ls ✔ ✔ host rm ⚪ ✔ + host maintenance enter ❌ ✔ + host maintenance exit ❌ ✔ daemon status ⚪ ✔ daemon {stop,start,...} ⚪ ✔ device {ident,fault}-(on,off} ⚪ ✔ @@ -171,7 +179,10 @@ This is an overview of the current implementation status of the orchestrators. nfs add ⚪ ✔ rbd-mirror add ⚪ ✔ rgw add ⚪ ✔ + ls ✔ ✔ ps ✔ ✔ + status ✔ ✔ + upgrade ❌ ✔ =================================== ====== ========= where -- 2.39.5