Implement per-route options in the CF CLI

[maxmoehl]

What's the user value of this feature request?

Allow users to manage per-route options via the CLI instead of having to talk to the API directly.

Who is the functionality for?

Users of the per-route features.

How often will this functionality be used by the user?

Unknown.

Who else is affected by the change?

The change is not breaking and optional.

Is your feature request related to a problem? Please describe.

No.

Describe the solution you'd like

Implement the RFC specification.

Specifically I propose that we add a new command update-route which allows updates to the route resource. This should be implemented in a generic way to not require a change in the CLI when adding a new per-route feature. I have something like this in mind:

$ cf update-route -h
NAME:
   update-route - Update an existing route.

USAGE:
   cf update-route DOMAIN [--hostname HOSTNAME] [--path PATH] [--option OPTION=VALUE] [--remove-option OPTION]

EXAMPLES:
   cf update-route example.com -o lb_algo=round-robin
   cf update-route example.com -o lb_algo=least-connections
   cf update-route example.com -r lb_algo

OPTIONS:
   --hostname, -n      Hostname for the HTTP route (required for shared domains)
   --path              Path for the HTTP route
   --option -o         Set the value of a per-route option, key-value pairs, repeat to set multiple options
   --remove-option -r  Unset a previously set option

SEE ALSO:
   create-route, map-route, routes, unmap-route

Plus a link to the documentation describing the currently implemented options, probably we could link directly to the API spec which has to list the available options.

Describe alternatives you've considered

We could implement each field as a separate flag but that would require users to update the CLI to use new per-route options.

Additional context

• RFC0027 Generic Per-Route Features
• Tracking Issue

[peanball]

There are some questions / topics that need decisions:

Do we use cf update-route as new command, or cf map-route as existing command?

Options should be able to be set in both of those.

That said, the options should be set in various commands anyway. From the existing commands:

• create-route
• map-route

Additionally, we could add update-route to update general parameters about the route.

The options don't need to be available on unmap-route, as there we just identify the route to unmap.

User Interface in the CLI

The CLI shows route information in various places.

cf routes - shows the routes

Here we could add a list of the options to the output.

The format could either be a pretty-printed list, e.g. {"options":"loadbalaning":"round-robin","session-cookie":"JSESSIONID"} could become:

$ cf routes
Getting routes for org my-org / space somespace as [email protected]...

space            host      domain                      port   path         protocol   app-protocol   apps          service instance      route options
some-space       the       app.cf.example.com                              http       http2          the-app                             loadbalancing: round-robin, session-cookie: JSESSIONID

Or we could use a JSON output, e.g. {"loadbalancing":"round-robin","session-cookie":"JSESSIONID"}:

$ cf routes
Getting routes for org my-org / space somespace as [email protected]...
   
space            host      domain                      port   path         protocol   app-protocol   apps          service instance      route options
some-space       the       app.cf.example.com                              http       http2          the-app                             {"loadbalancing":"round-robin","session_cookie":"JSESSIONID"}

cf app - shows detailed information for the app, including routes

The output could be as follows:

Showing health and status for app theapp in org my-org / space somespace as [email protected]...

name:              theapp
requested state:   started
routes:            the.app.cf.example.com {lb_algo: round-robin, session_cookie: JSESSIONID}, 
last uploaded:     Fri 09 Aug 08:31:51 CEST 2024
stack:             cflinuxfs4
buildpacks:
	name           version   detect output   buildpack name
	go_buildpack   1.10.19   go              go

type:           web
sidecars:
instances:      1/1
memory usage:   32M
     state     since                  cpu    memory        disk            logging              cpu entitlement   details
#0   running   2024-12-03T07:50:12Z   2.0%   8.3M of 32M   16.5M of 100M   17B/s of unlimited   103.9%

cf apps - shows a list of routes

Each of the apps displayed in cf apps a list of routes displayed. My proposal is to omit per-route options here.

Alternatively, an appreviated form could be considered:

$ cf apps
Getting apps in org my-org / space somespace as [email protected]...

name                requested state   processes   routes
the                 started           web:1/1     the.app.cf.example.com {lb: round-robin, session-cookie: JSESSIONID}

There could also be an extra flag to show this additional information, as it takes up significant screen space.

Long vs. short option names

For the one option implemented there are currently multple names:

• internal: lb_algo,
• manifest and CC API responses: loadbalancing-algorithm

This could be unified to lb or loadbalancing. The "algorithm" is implied.

This could also be an opportunity to unify those properties across the Cloud Controller, CLI and Gorouter.

edit: ✅ agreed to call it loadbalancing.

Also pinging @tcdowney @beyhan @stephanme who took part in the discussion and @Gerg who was also mentioned and discussed in cloudfoundry/capi-release#482

[maxmoehl]

Do we use cf update-route as new command, or cf map-route as existing command?

I just noticed that you can't change the app protocol via the CLI on a route that is mapped to an application. I was only able to do so by un-mapping the route and re-mapping it again which could be an issue if you want to make such a change without causing downtime. So I'm very much in favour of introducing update-route.

cf routes - shows the routes

I would prefer the pretty-print version, it seems more readable to me.

cf apps - shows a list of routes

Each of the apps displayed in cf apps a list of routes displayed. My proposal is to omit per-route options here.

Agree.

This could also be an opportunity to unify those properties across the Cloud Controller, CLI and Gorouter.

If you want to unify them make sure to raise this on cloudfoundry/capi-release#482 / cloudfoundry/cloud_controller_ng#4080 because once those are in there isn't going to be any change on them in the CC API and changes in the other components will also be more complicated.

[peanball]

@maxmoehl

I just noticed that you can't change the app protocol via the CLI on a route that is mapped to an application. I was only able to do so by un-mapping the route and re-mapping it again which could be an issue if you want to make such a change without causing downtime.

is this an inherent limitation, or could this be something that is just added to map-route, in addition to setting the options?

Thanks! Raised the point about naming unification in cloudfoundry/capi-release#482.

[maxmoehl]

I just noticed that you can't change the app protocol via the CLI on a route that is mapped to an application. I was only able to do so by un-mapping the route and re-mapping it again which could be an issue if you want to make such a change without causing downtime.

is this an inherent limitation, or could this be something that is just added to map-route, in addition to setting the options?

I don't know. When I tried changing the protocol via map-route all I got was this:

$ cf map-route harald-test cfapps.eu12.hana.ondemand.com --hostname fooooo --app-protocol http2
Mapping route fooooo.cfapps.eu12.hana.ondemand.com to app harald-test with protocol http2 in org CFN_cf-routing / space harald as <redacted>...
App 'harald-test' is already mapped to route 'fooooo.cfapps.eu12.hana.ondemand.com'. Nothing has been updated.
OK

And the protocol stays the same, changing that behaviour would probably be considered breaking.

[peanball]

that said, we would want to be able to set options when mapping a route initially, right?

Maybe we can then add a hint to the message you show that points at "use cf update-route to modify existing routes in place", or something like that.

[Dariquest]

To be conform with all the code guidelines and naming conventions for the code and json templates, we should take "load-balancing" instead of "loadbalancing". My proposal would be:

{"options":"load-balancing":"round-robin","session-cookie":"JSESSIONID"}

We would have a german flair naming it "loadbalancing". E.g. session-cookies should also be named sessioncookie then, not only in the code, but also in json "sessioncookie" instead of "session_cookie". One more example:

type ServiceInstanceSummary struct {
	LastOperation LastOperationSummary `json:"last_operation"`
	ServicePlan   ServicePlanSummary   `json:"service_plan"`
}

[peanball]

The point of loadbalancing was to avoid the punctuation mismatch between lb_algo and loadbalancing-algo, as well as the special handling of - in ruby identifiers.

Shortening it was another reason. The shorter the better for the UI. But I also don't want another layer of mapping.

The load balancing algorithm option is also the first one now, possibly setting the tone for future options. The name for "cookie name for sticky session IDs" in my examples is an (admittedly lazy) example that I haven't thought about much. It could very well be session or something.

My concern was mostly to keep the options straight between CLI, manifest and API, as we're exposing such internals directly to the user.

I want to avoid mapping of the same concept to different names depending where you are.

That also means for me: the constraint of showing it in the CLI in a compact fashion while remaining understandable informs the name.