cephfs admin: deprecate the New function

The New function created a rados connection object but did not expose it
via a public api, making it impossible to deterministically sever / clean up
the connection. This commit assumes that the patch will be merged prior
to the go-ceph v0.21 release so that we can plan to remove the function
three versions later (v0.24).  I chose three versions so that it is one
release longer than our typical stabilization period as this function
has been around for a while.

Signed-off-by: John Mulligan <jmulligan@redhat.com>

cephfs/admin/fsadmin.go

@@ -21,6 +21,9 @@ type FSAdmin struct {
 // configuration file. If more customization is needed, create a
 // *rados.Conn as you see fit and use NewFromConn to use that
 // connection with these administrative functions.
+//
+// Deprecated: Use NewFromConn instead of New. The New function does not expose
+// the rados connection and therefore can not be deterministically cleaned up.
 func New() (*FSAdmin, error) {
 	conn, err := rados.NewConn()
 	if err != nil {

docs/api-status.json

@@ -345,10 +345,6 @@
         "name": "FSAdmin.CancelClone",
         "comment": "CancelClone stops the background processes that populate a clone.\nCancelClone does not delete the clone.\n\nSimilar To:\n ceph fs clone cancel <volume> --group_name=<group> <clone>\n"
       },
-      {
-        "name": "New",
-        "comment": "New creates an FSAdmin automatically based on the default ceph\nconfiguration file. If more customization is needed, create a\n*rados.Conn as you see fit and use NewFromConn to use that\nconnection with these administrative functions.\n"
-      },
       {
         "name": "NewFromConn",
         "comment": "NewFromConn creates an FSAdmin management object from a preexisting\nrados connection. The existing connection can be rados.Conn or any\ntype implementing the RadosCommander interface. This may be useful\nif the calling layer needs to inject additional logging, error handling,\nfault injection, etc.\n"
@@ -516,7 +512,14 @@
         "became_stable_version": "v0.18.0"
       }
     ],
-    "deprecated_api": [],
+    "deprecated_api": [
+      {
+        "name": "New",
+        "comment": "New creates an FSAdmin automatically based on the default ceph\nconfiguration file. If more customization is needed, create a\n*rados.Conn as you see fit and use NewFromConn to use that\nconnection with these administrative functions.\n\nDeprecated: Use NewFromConn instead of New. The New function does not expose\nthe rados connection and therefore can not be deterministically cleaned up.\n",
+        "deprecated_in_version": "v0.21.0",
+        "expected_remove_version": "v0.24.0"
+      }
+    ],
     "preview_api": [
       {
         "name": "FSAdmin.GetMetadata",
@@ -2102,4 +2105,4 @@
       }
     ]
   }
-}
+}

docs/api-status.md

@@ -31,6 +31,12 @@ FSAdmin.PinSubVolume | v0.21.0 | v0.23.0 |
 FSAdmin.PinSubVolumeGroup | v0.21.0 | v0.23.0 | 
 FSAdmin.FetchVolumeInfo | v0.21.0 | v0.23.0 | 
 
+### Deprecated APIs
+
+Name | Deprecated in Version | Expected Removal Version | 
+---- | --------------------- | ------------------------ | 
+New | v0.21.0 | v0.24.0 | 
+
 ## Package: rados
 
 No Preview/Deprecated APIs found. All APIs are considered stable.