- 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 user 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 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 allocated 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