- how is router configuration visualized from a user perspective - how is router configuration visualized from an admin perspective - how is a user notified of a route binding and final dns - how does a user request default dns name vs custom dns name - router fronting with DNS, how are entries created ## Description As an application administrator, I would like my routes to be configured with shards so they can grow beyond a single active/active or active/passive setup. I should be able to configure many routers to allocate user requested routes to and be able to visualize the configuration. ## Use Cases The following use cases should be satisfied by this proposal: 1. Configure routers as OpenShift resources and let the platform keep the specified configuration running 1. Create a single, unsharded router 1. Create multiple routers with shards corresponding to a resource label 1. Allow any router to run in an HA configuration 1. User requests default route for application 1. User requests custom route for application 1. Create DNS (or other front end entry points) for routers ## Existing Artifacts 1. Routing: https://github.com/pweil-/origin/blob/master/docs/routing.md 1. HA Routing: https://github.com/pweil-/origin/blob/master/docs/routing.md#running-ha-routers 1. DNS Round Robin: https://github.com/pweil-/origin/blob/master/docs/routing.md#dns-round-robin ## Configuring Routers Administering routers as a top level object allows administrators to use custom commands specific to routers. This provides a more use friendly mechanism of configuration and customizing routers. However, this also introduces more code for an object that will likely be dealt with as a pod anyway. Routers should be a low touch configuration item that do not require many custom commands for daily administration. Pros: - Configuration lives in etcd, just like any other resource - Shards are configured via custom commands and `json` syntax - Routers are known to OpenShift; the system ensures the proper configuration is running - Custom administration syntax - Deal with routers as infra - The system knows about routers for route route binding and visualization with no extra effort Cons: - More divergent from Kubernetes codebase initially, though we may be able to generalize parts of this approach to sharding to other resources and controllers which allow sharding ## Route Scheduling Route scheduling is the process of assigning a `Route` record to a specific `Router` and setting up DNS for routes. We will treat the problem of route scheduling similarly to the problem of pod scheduling. There will be a new state reconciler to schedule Routes after they are created and a new field to express route binding status in the `Route` resource. ### Proposed Implementation #### The `Router` Resource There should be a new OpenShift resource called `Router`. Its fields include: 1. `Name`: the router's name 2. `Description`: a description of the Router 3. `DNS`: the public DNS name of the Router 3. `Label`: the label that associates resources (Endpoints, Routes, Services) with this router #### Changes to the `Route` resource The `Route` resource should have a new field added: type Route { // other fields not shown Status RouteStatus } type RouteStatus struct { Phase RoutePhase DNS string } type RoutePhase string const ( RoutePhaseNew RoutePhase = "new" RoutePhaseScheduled RoutePhase = "scheduled" ) The `RouteStatus` type represents the overall status of a `Route`. The `RoutePhase` type represents the phase of a route; it can be valued `new` or `scheduled`. #### Changes to the `Route` REST API The `Route` REST API will be changed to validate that: 1. The `DNS` and `Phase` fields of a `Route` are not set during create 2. The value of `DNS` and `Phase` fields do not change during update 3. The `RouteDNS` represents the final DNS name that will be used for the requested route. For example if the user requests the route `test` for their app in namespace `myapp` they will be allocted to a shard and given a name in the form of `myapp-test.shard1.v3.rhcloud.com`. This field may only change during router allocation or reallocation and is only changed by the system. If the user owns their own domain then this field will be populated from `Route.Host` and remain unchanged during allocation. #### The `RouteBinding` Resource The `RouteBinding` resource describes the association of a `Route` with a `Router`. Its fields are: 1. `RouteNamespace`: The namespace of the route being scheduled 2. `RouteName`: The name of the route being scheduled 3. `DNS`: The DNS of the router serving the route The `RouteBinding` REST API will be the only path that is allowed to update the values of the `DNS` and `Phase` fields. The REST API will apply the route binding to the `Route` record during `Create`. #### The `RouteScheduler` state reconciler We will introduce `RouteScheduler`, a state reconciler that watches the `Route` resource and schedules new routes. The route scheduler will use a pluggable sheduling strategy, allowing users to author their own strategies. Our initial strategy implementation will be a simple round-robin strategy. The `RouteScheduler` processes `Route` resources as follows: 1. The `RouteScheduler` watches for newly created (and thus unscheduled) `Route`s and periodically list the unscheduled `Route`s to retry 2. The scheduler passes unscheduled `Route` records to the `RouteSchedulerStrategy` interface 3. If the scheduling strategy is able to schedule the route, the scheduler creates a `RouteBinding` for the route and router by calling the `RouteBinding` REST API 4. The `RouteBinding` REST API `Create` call applies the route binding to the `Route`'s status field, setting the `DNS` and `Phase` fields 5. The `Router` instance the `Route` is scheduled to receives an update event for the route and applies it to the router backend configuration Errors scheduling routes are assumed to be transient and actionable by administrators. The scheduling will continue reprocessing a `Route` until route binding succeeds. #### The `RouteSchedulerStrategy` interface The `RouteSchedulerStrategy` expresses something that can allocate routes amongst the available routers: type RouteSchedulerStrategy interface { func Schedule(*routeapi.Route) (*routerapi.Router, error) } ## User Requests a Route Requesting a route is a multi-step process that includes the initial user request, router allocation, and router configuration. OpenShift does not provide DNS services for users who own their own domain, users who own their own domain should point their domain name to the allocated shard(s) for resolution. When requesting a route the user has two options. 1. Requesting a specific route name in `Route.Host`: This indicates that the user owns the domain. The system should not manipulate the requested name but should ensure uniqueness against the existing routes. 2. Requesting a route with no name specified in `Route.Host`: This indicates that the user would like to have system provided DNS. The `RouteScheduler` will create a name in the format of `<namespace>-<Host>.<shard>.v3.rhcloud.com` and populate the `DNS` field of the route upon completion. ## DNS OpenShift will not provide custom DNS to clients. System provided DNS will be achieved by using a DNS plugin or manual setup that is aware of the configured router shards. The DNS implementation will be set up with a wild card DNS zone for each router shard. Below is an example of the zone files of a router configuration with two shards. If a plugin infrastructure is created it will be able to watch the `router` configuration to determine the correct zone files to set up with wildcard entries. shard1.zone: $ORIGIN shard1.v3.rhcloud.com. @ IN SOA . shard1.v3.rhcloud.com. ( 2009092001 ; Serial 604800 ; Refresh 86400 ; Retry 1206900 ; Expire 300 ) ; Negative Cache TTL IN NS ns1.v3.rhcloud.com. ns1 IN A 127.0.0.1 * IN A 10.245.2.2 ; active/active DNS round robin IN A 10.245.2.3 ; active/active DNS round robin shard2.zone: $ORIGIN shard2.v3.rhcloud.com. @ IN SOA . shard2.v3.rhcloud.com. ( 2009092001 ; Serial 604800 ; Refresh 86400 ; Retry 1206900 ; Expire 300 ) ; Negative Cache TTL IN NS ns1.v3.rhcloud.com. ns1 IN A 127.0.0.1 * IN A 10.245.2.4 ; active/active DNS round robin IN A 10.245.2.5 ; active/active DNS round robin