diff --git a/CHANGELOG.md b/CHANGELOG.md index eeb67416a7..bbf8fd92ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -91,6 +91,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). - /riak/ping - /riak/stats - /servercheck/aadata + - /servers/hostname/:hostName/details - /servers/status - /servers/:id (GET) - /servers/totals diff --git a/docs/source/api/v1/servers_hostname_name_details.rst b/docs/source/api/v1/servers_hostname_name_details.rst index 68b16e44a6..d492109e80 100644 --- a/docs/source/api/v1/servers_hostname_name_details.rst +++ b/docs/source/api/v1/servers_hostname_name_details.rst @@ -18,6 +18,8 @@ ************************************* ``servers/hostname/{{name}}/details`` ************************************* +.. deprecated:: ATCv4 + Use the ``GET`` method of :ref:`to-api-servers-details` with the query parameter ``hostName`` instead. ``GET`` ======= @@ -136,6 +138,12 @@ Response Structure "iloIpAddress": "", "profileDesc": "Edge Cache - Apache Traffic Server", "routerHostName": "" - }} + }, + "alerts": [ + { + "text": "This endpoint is deprecated, please use GET /servers/details with query parameter hostName instead", + "level": "warning" + } + ]} .. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/v2/servers_details.rst b/docs/source/api/v2/servers_details.rst new file mode 100644 index 0000000000..063e63fd68 --- /dev/null +++ b/docs/source/api/v2/servers_details.rst @@ -0,0 +1,168 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _to-api-servers-details: + +******************* +``servers/details`` +******************* +Retrieves details of :ref:`tp-configure-servers`. + + +``GET`` +======= +:Auth. Required: Yes +:Roles Required: None +:Response Type: Array + +.. note:: On top of the response including the response key that is of type array it will also include the keys ``limit``, ``orderby``, and ``size``. + +Request Structure +----------------- +.. table:: Request Query Parameters + + +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +================+========================================+================================================================================================================================================================+ + | hostName | Required if no physLocationID provided | Return only the servers with this (short) hostname. Capitalization of "hostName" is important. | + +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | physLocationID | Required if no hostName provided | Return only servers with this integral, unique identifier for the physical location where the server resides. Capitalization of "physLocationID" is important. | + +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Example + + GET /api/2.0/servers/details?hostName=edge HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + +Response Structure +------------------ +:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given) +:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given) +:response: An array of objects, each of which represents the details of a given :ref:`Server `. + + :cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs + :cdnName: Name of the CDN to which the server belongs + :deliveryservices: An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs + :domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` + :guid: An identifier used to uniquely identify the server + + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + + :hostName: The (short) hostname of the server + :httpsPort: The port on which the server listens for incoming HTTPS connections/requests + :id: An integral, unique identifier for this server + :iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ + :iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ + :iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ + :iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) ` + :iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ + :interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configured on ``interfaceName`` + :interfaceName: The name of the primary network interface used by the server + :ip6Address: The IPv6 address and subnet mask of ``interfaceName`` + :ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` + :ipAddress: The IPv4 address of ``interfaceName`` + :ipGateway: The IPv4 address of the gateway used by ``interfaceName`` + :ipNetmask: The IPv4 subnet mask used by ``interfaceName`` + :offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status + :physLocation: The name of the physical location where the server resides + :profile: The :ref:`profile-name` of the :term:`Profile` used by this server + :profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server + :rack: A string indicating "server rack" location + :routerHostName: The human-readable name of the router responsible for reaching this server + :routerPortName: The human-readable name of the port used by the router responsible for reaching this server + :status: The status of the server + + .. seealso:: :ref:`health-proto` + + :tcpPort: The port on which this server listens for incoming TCP connections + + .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. + + :type: The name of the 'type' of this server + :xmppId: An identifier to be used in XMPP communications with the server - in nearly all cases this will be the same as ``hostName`` + :xmppPasswd: The password used in XMPP communications with the server + +:size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons + +.. code-block:: http + :caption: Response Example + + HTTP/1.1 200 OK + Access-Control-Allow-Credentials: true + Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie + Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE + Access-Control-Allow-Origin: * + Content-Encoding: gzip + Content-Type: application/json + Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 01:27:36 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: HW2F3CEpohNAvNlEDhUfXmtwpEka4dwUWFVUSSjW98aXiv10vI6ysRIcC2P9huabCz5fdHqY3tp0LR4ekwEHqw== + X-Server-Name: traffic_ops_golang/ + Date: Mon, 24 Feb 2020 00:27:36 GMT + Content-Length: 493 + + { + "limit": 1000, + "orderby": "hostName", + "response": [ + { + "cachegroup": "CDN_in_a_Box_Edge", + "cdnName": "CDN-in-a-Box", + "deliveryservices": [ + 1 + ], + "domainName": "infra.ciab.test", + "guid": null, + "hardwareInfo": null, + "hostName": "edge", + "httpsPort": 443, + "id": 5, + "iloIpAddress": "", + "iloIpGateway": "", + "iloIpNetmask": "", + "iloPassword": "", + "iloUsername": "", + "interfaceMtu": 1500, + "interfaceName": "eth0", + "ip6Address": "fc01:9400:1000:8::3", + "ip6Gateway": "fc01:9400:1000:8::1", + "ipAddress": "172.16.239.3", + "ipGateway": "172.16.239.1", + "ipNetmask": "255.255.255.0", + "mgmtIpAddress": "", + "mgmtIpGateway": "", + "mgmtIpNetmask": "", + "offlineReason": "", + "physLocation": "Apachecon North America 2018", + "profile": "ATS_EDGE_TIER_CACHE", + "profileDesc": "Edge Cache - Apache Traffic Server", + "rack": "", + "routerHostName": "", + "routerPortName": "", + "status": "REPORTED", + "tcpPort": 80, + "type": "EDGE", + "xmppId": "edge", + "xmppPasswd": "" + } + ], + "size": 1 + } + +.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/v2/servers_hostname_name_details.rst b/docs/source/api/v2/servers_hostname_name_details.rst deleted file mode 100644 index a4d7622f68..0000000000 --- a/docs/source/api/v2/servers_hostname_name_details.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-servers-hostname-name-details: - -************************************* -``servers/hostname/{{name}}/details`` -************************************* - -``GET`` -======= -Retrieves the details of a server. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------+ - | Name | Description | - +======+====================================================+ - | name | The (short) hostname of the server being inspected | - +------+----------------------------------------------------+ - -Response Structure ------------------- -:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs -:cdnName: Name of the CDN to which the server belongs -:deliveryservices: An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs -:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` -:guid: An identifier used to uniquely identify the server - - .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` - -:hostName: The (short) hostname of the server -:httpsPort: The port on which the server listens for incoming HTTPS connections/requests -:id: An integral, unique identifier for this server -:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ -:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ -:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ -:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) ` -:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ -:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configured on ``interfaceName`` -:interfaceName: The name of the primary network interface used by the server -:ip6Address: The IPv6 address and subnet mask of ``interfaceName`` -:ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status -:physLocation: The name of the physical location where the server resides -:profile: The :ref:`profile-name` of the :term:`Profile` used by this server -:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server -:rack: A string indicating "server rack" location -:routerHostName: The human-readable name of the router responsible for reaching this server -:routerPortName: The human-readable name of the port used by the router responsible for reaching this server -:status: The status of the server - - .. seealso:: :ref:`health-proto` - -:tcpPort: The port on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:type: The name of the 'type' of this server -:xmppId: An identifier to be used in XMPP communications with the server - in nearly all cases this will be the same as ``hostName`` -:xmppPasswd: The password used in XMPP communications with the server - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Mon, 10 Dec 2018 17:11:53 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: ZDeQrG0D7Q3Wy3ZEUT9t21QQ9F9Yc3RR/Qr91n22UniYubdhdKnir3B+LYP5ZKkVg8ByrVPFyx6Nao0iiBTGTQ== - Content-Length: 800 - - { "response": { - "profile": "ATS_EDGE_TIER_CACHE", - "xmppPasswd": "", - "physLocation": "Apachecon North America 2018", - "cachegroup": "CDN_in_a_Box_Edge", - "interfaceName": "eth0", - "id": 9, - "tcpPort": 80, - "httpsPort": 443, - "ipGateway": "172.16.239.1", - "ip6Address": "fc01:9400:1000:8::100", - "xmppId": "edge", - "mgmtIpNetmask": "", - "rack": "", - "mgmtIpGateway": "", - "deliveryservices": [ - 1 - ], - "type": "EDGE", - "iloIpNetmask": "", - "domainName": "infra.ciab.test", - "iloUsername": "", - "status": "REPORTED", - "ipAddress": "172.16.239.100", - "ip6Gateway": "fc01:9400:1000:8::1", - "iloPassword": "", - "guid": null, - "offlineReason": "", - "routerPortName": "", - "ipNetmask": "255.255.255.0", - "mgmtIpAddress": "", - "interfaceMtu": 1500, - "iloIpGateway": "", - "cdnName": "CDN-in-a-Box", - "hostName": "edge", - "iloIpAddress": "", - "profileDesc": "Edge Cache - Apache Traffic Server", - "routerHostName": "" - }} - -.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/traffic_control/clients/python/trafficops/tosession.py b/traffic_control/clients/python/trafficops/tosession.py index 19b5f4666e..9dabbf1abf 100644 --- a/traffic_control/clients/python/trafficops/tosession.py +++ b/traffic_control/clients/python/trafficops/tosession.py @@ -1642,16 +1642,6 @@ def get_server_delivery_services(self, server_id=None): :raises: Union[LoginError, OperationError] """ - @api_request('get', 'servers/hostname/{name}/details', ('2.0',)) - def get_server_details(self, name=None): - """ - Get server details from trafficOps - :ref:`to-api-servers-hostname-name-details` - :param hostname: Server hostname - :rtype: Tuple[Union[Dict[str, Any], List[Dict[str, Any]]], requests.Response] - :raises: Union[LoginError, OperationError] - """ - @api_request('post', 'servercheck', ('2.0',)) def create_servercheck(self, data=None): """ diff --git a/traffic_ops/traffic_ops_golang/routing/routes.go b/traffic_ops/traffic_ops_golang/routing/routes.go index 3141bc7593..9605e1b874 100644 --- a/traffic_ops/traffic_ops_golang/routing/routes.go +++ b/traffic_ops/traffic_ops_golang/routing/routes.go @@ -299,7 +299,6 @@ func Routes(d ServerData) ([]Route, []RawRoute, http.Handler, error) { //Server Details {api.Version{2, 0}, http.MethodGet, `servers/details/?$`, server.GetDetailParamHandler, auth.PrivLevelReadOnly, Authenticated, nil, 2261264714, noPerlBypass}, - {api.Version{2, 0}, http.MethodGet, `servers/hostname/{hostName}/details/?$`, server.GetDetailHandler, auth.PrivLevelReadOnly, Authenticated, nil, 272366128, noPerlBypass}, //Server status {api.Version{2, 0}, http.MethodPut, `servers/{id}/status$`, server.UpdateStatusHandler, auth.PrivLevelOperations, Authenticated, nil, 276663851, noPerlBypass}, diff --git a/traffic_ops/traffic_ops_golang/server/detail.go b/traffic_ops/traffic_ops_golang/server/detail.go index c8c9a52a3c..789b3648cf 100644 --- a/traffic_ops/traffic_ops_golang/server/detail.go +++ b/traffic_ops/traffic_ops_golang/server/detail.go @@ -34,24 +34,26 @@ import ( ) func GetDetailHandler(w http.ResponseWriter, r *http.Request) { + alt := "GET servers/details with query parameters hostName" inf, userErr, sysErr, errCode := api.NewInfo(r, nil, nil) if userErr != nil || sysErr != nil { - api.HandleErr(w, r, inf.Tx.Tx, errCode, userErr, sysErr) + api.HandleDeprecatedErr(w, r, inf.Tx.Tx, errCode, userErr, sysErr, &alt) return } defer inf.Close() servers, err := getDetailServers(inf.Tx.Tx, inf.User, inf.Params["hostName"], -1, "", 0) if err != nil { - api.HandleErr(w, r, inf.Tx.Tx, http.StatusInternalServerError, nil, errors.New("getting detail servers: "+err.Error())) + api.HandleDeprecatedErr(w, r, inf.Tx.Tx, http.StatusInternalServerError, nil, errors.New("getting detail servers: "+err.Error()), &alt) return } if len(servers) == 0 { - api.HandleErr(w, r, inf.Tx.Tx, http.StatusNotFound, nil, nil) + api.HandleDeprecatedErr(w, r, inf.Tx.Tx, http.StatusNotFound, nil, nil, &alt) return } server := servers[0] - api.WriteResp(w, r, server) + alerts := api.CreateDeprecationAlerts(&alt) + api.WriteAlertsObj(w, r, http.StatusOK, alerts, server) } func GetDetailParamHandler(w http.ResponseWriter, r *http.Request) {