You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2021/10/25 15:26:11 UTC
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #6281: Federations Redesign
ocket8888 commented on a change in pull request #6281:
URL: https://github.com/apache/trafficcontrol/pull/6281#discussion_r735714661
##########
File path: blueprints/federations.redesign.md
##########
@@ -0,0 +1,546 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you 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.
+-->
+# Federations Redesign
+
+## Problem Description
+Currently, Federations are among the most convoluted and difficult to comprehend
+concepts/objects in Traffic Control. The process to create a Federation - and
+what one even does - is poorly understood by many, and that's reflected by the
+fact that
+[the latest documentation's quick-how-to guide on the subject](https://traffic-control-cdn.readthedocs.io/en/v6.0.0/admin/quick_howto/federations.html)
+still has steps for and screenshots of the Traffic Ops UI that was removed years
+ago.
+
+Part of this is undoubtedly caused by the myriad of Traffic Ops API endpoints
+used to manipulate Federations. Currently, these exist:
+
+- `/cdns/{{name}}/federations`
+- `/cdns/{{name}}/federations/{{ID}}`
+- `/federations/all`
+- `/federations`
+- `/federations/{{ID}}/deliveryservices`
+- `/federations/{{ID}}/deliveryservices/{{dsID}}`
+- `/federation_resolvers`
+- `/federations/{{ID}}/federation_resolvers`
+- `/federations/{{ID}}/users`
+- `/federations/{{ID}}/users/{{userID}}`
+
+## Proposed Change
+The notion of a "Federation" will be reworked into a first-class citizen of the
+ATC data model. Access will be controlled by Tenancy (and Permissions), so the
+only necessary Traffic Ops API endpoint will be `/federations`.
+
+## Data Model Impact
+The proposed model for Federations is as follows:
+
+```typescript
+interface Federation {
+ cname: `${string}.`;
+ description: string;
+ // Only present in responses
+ id?: number;
+ // RFC3339 timestamp string - only present in responses
+ lastUpdated?: Date;
+ resolvers: [string, ...string[]];
+ ttl: number;
+}
+```
+
+Also, Federations will be added as direct properties of Delivery Services in new
+API versions:
+
+```typescript
+type DNSTypeName = "DNS" | "DNS_LIVE" | "DNS_LIVE_NATNL";
+interface DNSDeliveryService extends DeliveryService {
+ type: DNSTypeName;
+ federations: null | [number] | [number, ...number[]];
+}
+interface NonDNSDeliveryService extends DeliveryService {
+ type: Exclude<string, DNSTypeName>;
+ federations: null;
+}
+type NewDeliveryService = NonDNSDeliveryService | DNSDeliveryService;
+```
+
+## Impacted Components
+This primarily affects Traffic Ops and Traffic Portal, but some Traffic Router
+changes will be necessary to support the new API surface.
+
+### Traffic Ops Impact
+
+#### Database Impact
+There should be no necessary changes to database structure, but to ensure valid
+data is stored in the database, the `ip_address` column of the
+`federation_resolver` table should be switched from `text` to `inet`.
+
+#### API Impact
+The following currently existing API endpoints will be removed:
+
+- `/cdns/{{name}}/federations`
+- `/cdns/{{name}}/federations/{{ID}}`
+- `/federations/all`
+- `/federations/{{ID}}/deliveryservices`
+- `/federations/{{ID}}/deliveryservices/{{dsID}}`
+- `/federation_resolvers`
+- `/federations/{{ID}}/federation_resolvers`
+- `/federations/{{ID}}/users`
+- `/federations/{{ID}}/users/{{userID}}`
+
+The following API endpoints contain representations of Delivery Services, and
+will need to be updated to support the new `federations` property:
+
+- `/deliveryservices`
+- `/deliveryservices/{{ID}}`
+- `/deliveryservices/{{ID}}/safe`
+- `/deliveryservice_requests`
+- `/deliveryservice_requests/{{ID}}/assign`
+- `/deliveryservice_requests/{{ID}}/status`
+- `/servers/{{ID}}/deliveryservices`
+- `/cdns/{{name}}/snapshot`
+- `/cdns/{{name}}/snapshot/new`
+
+`/cdns/{{name}}/config/monitoring` contains representations of Delivery
+Services, but since Federations are irrelevant to the operation of Traffic
+Monitor (at the time of this writing), those representations need not be
+updated.
+
+Of these, `/cdns/{{name}}/snapshot` and `/cdns/{{name}}/snapshot/new` are of
+particular note because they contain representations of Delivery Services that
+are not very similar to any of the other representations. In keeping with that,
+they will have different changes than all the others, detailed in
+[Snapshot Endpoints](#snapshots) below.
+
+##### Snapshot Endpoints
+Instead of including the regular array of Federation IDs that most
+representations of Delivery Services will have, Snapshot Delivery Service
+representations will contain a `federations` property that is a set of full
+Federation representations. This allows Federations to be captured by the
+Snapshot process and allows Traffic Router to read them from a Snapshot without
+needing to issue additional HTTP requests to complete its information.
+
+##### `/federations`
+This endpoint will be repurposed from its existing behavior to support the
+behavior described in this section.
+
+###### GET
+Required Permissions: `FEDERATION:READ`
+
+This endpoint will support all standard pagination controls, as well as
+`olderThan` and `newerThan`. It will also provide the following additional query
+string parameters:
+
+- `id` - Returns only the Federation with the given ID.
+- `ttl` - Returns only Federations with this TTL.
+- `cname` - Returns only Federations with `cname`s matching this glob
+- `description` - Returns only Federations with `description`s matching this glob
+
+(globs can use `*` and `%` interchangeably).
+
+This method of this endpoint will not interpret request bodies, and returns a
+`response` that is an array of Federations.
+
+This should require the
+
+###### POST
+Required Permissions: `FEDERATION:READ`, `FEDERATION:CREATE`
+
+This method of this endpoint is responsible for creating new Federations. The
+request body must be a valid Federation, and shouldn't specify `lastUpdated` or
+`id` (although the handler should ignore them if they are present). No query
+string parameters are supported.
+
+The response to requests made using this method to this endpoint will be a
+representation of the created Federation.
+
+###### PUT
+Required Permissions: `FEDERATION:READ`, `FEDERATION:UPDATE`
+
+This method of this endpoint may be used to replace existing Federations with
+new ones specified by a valid Federation in the request body.
+
+This method requires an `id` query string parameter specifying the ID of the
+Federation being replaced.
+
+The response to requests made using this method to this endpoint will be the new
+representation of the modified Federation.
+
+If the Federation is used by any Delivery Services that make use of SSL, a
+warning-level Alert will be issued cautioning the requesting user to ensure that
+the SSL certificates for whatever server to which the Resolver's CNAME directs
+traffic are up-to-date.
+
+###### DELETE
+Required Permissions: `FEDERATION:READ`, `FEDERATION:DELETE`
+
+This method of this endpoint deletes existing Federations.
+
+This method requires an `id` query string parameter specifying the ID of the
+Federation to be deleted.
+
+A 409 Conflict response should be returned when a request is made to delete a
+Federation that is in use by a Delivery Service, refusing to perform the
+requested operation.
+
+The response to request (successfully) made using this method of this endpoint
+will be a representation of the deleted Federation.
+
+#### Client Impact
+Clients at or below API v3 should not need to change. The latest client version
+will change what structures it returns, and will no longer contain methods for
+the endpoints and methods of endpoints that will be removed.
+
+### Traffic Portal Impact
+Traffic Portal's functionality for manipulating Federations will need to be
+overhauled. There will be a new entry under "Services" alongside "Delivery
+Services" and (conditionally) "Delivery Service Requests" titled "Federations".
+This menu item directs users to a page with a standard table for Federations
+just like the tables for every other API object. Within a single Federation's
+page is a form for editing that Federation, a sample of which is shown below.
+
+
+
+Note that Federation Resolvers are manipulated here directly, rather than
+created separately through a different page and then linked using a popup.
+
+To accommodate re-use of Federation Resolvers, the "More" menu for a Federation
+will have two options: "Copy Resolvers From..." and "Clone Resolvers To...".
+These buttons will open dialog boxes that will prompt the user to choose a
+Federation from which to copy Resolvers onto the Federation being edited, and
+to choose one or more Federations to which to copy the Federation being edited's
+Resolvers, respectively. Sample Dialogs for each are shown below.
+
+
+
+
+
+(Note that these feature a "Replace Existing Resolvers?" checkbox, which has
+since been reconsidered and should not actually be included in the UI - instead
+the resolvers should *always* be overwritten)
+
+If desired, the markup used for these samples may be found in
+[Appendix A](#appendix-a).
+
+### Traffic Router Impact
+Traffic Router's Federations polling will need to be stripped out, and instead
+Federation information should be parsed from the CDN Snapshot.
+
+## Documentation Impact
+The documentation for affected endpoints will need to be updated, and a section
+for the new property of Delivery Services will need to be added to the Delivery
+Service overview section. Also, there is a "Quick How-To" guide for setting up
+Federations that currently still references the Traffic Ops UI that hasn't
+existed for years; that needs to be updated either way, but since the changes to
+Federations described in this blueprint include Traffic Portal changes, it would
+be a good time to also update the guide. Assuming it's quickly approved.
+
+## Testing Impact
+The tests for Federation-related endpoints will need to be overhauled to remove
+tests for removed endpoints, and to reflect changes to the updated endpoints.
+
+## Performance Impact
+The changes herein proposed would make Snapshots larger, but would eliminate an
+entire polling thread from Traffic Router. The performance impact to Traffic
+Router is difficult to know without measuring (and I haven't measured, not only
+because that would require actually making the changes to compare), but I would
+guess that Traffic Router will use less resources overall with this tradeoff.
+
+Costs/gains to Traffic Ops and/or Traffic Portal are negligible.
+
+## Security Impact
+None.
+
+## Upgrade Impact
+None.
Review comment:
So, if I'm understanding this right, then any breaking changes to any routes that TR uses would make upgrade impossible? Isn't that the same issue we fixed in Traffic Monitor, and don't we want all components to be backward compatible, so that upgrade order isn't forced?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org