cf delete-route is confusing

[jchesterpivotal]

Here is a dramatic recreation of one interaction with cf delete-route. We found it to be a little difficult to understand upon a first encounter.

We wanted to delete the route to the bcs app. So:

$ cf routes
Getting routes as admin ...

host   domain               apps
bcs    10.244.0.34.xip.io   bcs

So far so good.

First attempt to delete a route:

$ cf delete-route bcs
FAILED
Domain bcs not found

OK, it talks about "domain" and I see that 10.244.0.34.xip.io is listed under "domain". So:

$ cf delete-route 10.244.0.34.xip.io

Really delete the route 10.244.0.34.xip.io?> yes
Deleting route 10.244.0.34.xip.io...
Unable to delete, route '10.244.0.34.xip.io' does not exist.
Endpoint deprecated

Doesn't exist? Let me check ...

$ cf routes
Getting routes as admin ...

host   domain               apps
bcs    10.244.0.34.xip.io   bcs

Well that didn't work. I guess I'll need to find and read the FM:

$ cf help delete-route
NAME:
   delete-route - Delete a route

USAGE:
   cf delete-route DOMAIN [-n HOSTNAME] [-f]

OPTIONS:
   -f   Force deletion without confirmation
   -n   Hostname

Weird, the brackets on hostname suggest it's optional. Let's try it anyway:

$ cf delete-route 10.244.0.34.xip.io -h bcs
NAME:
   delete-route - Delete a route

USAGE:
   cf delete-route DOMAIN [-n HOSTNAME] [-f]

OPTIONS:
   -f   Force deletion without confirmation
   -n   Hostname

Hm, I'm fully specifying the hostname with an -h and ... oh. It's not aitch. It's en.

I got confused because '-h' and '-n' are very very similar visually. I was expecting single-letter arguments to be mnemonic with the full word ("hostname", not "nostname"). I guess it's for "name"? But the output of cf route clearly calls it "host", the help refers to it as "hostname".

I guess it sees -h as "help", which is why I didn't get the "FAILED Incorrect Usage" message.

So:

$ cf delete-route 10.244.0.34.xip.io -n bcs

Really delete the route bcs.10.244.0.34.xip.io?> yes
Deleting route bcs.10.244.0.34.xip.io...
OK
Endpoint deprecated

I guess "endpoint deprecated" means it's gone. Let me double-check:

$ cf routes
Getting routes as admin ...

host   domain   apps
No routes found

\o/

---

We think some hint text might have helped. Eg:

$ cf delete-route bcs
FAILED
Domain bcs not found
Did you mean:
    cf delete-route 10.244.0.34.xip.io -n bcs

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/81981190.

[Amit-PivotalLabs]

You don't know about nostname? :)

On Monday, November 3, 2014, cf-gitbot notifications@github.com wrote:

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/81981190.

— Reply to this email directly or view it on GitHub https://github.com/cloudfoundry/cli/issues/283#issuecomment-61543955.

[jchesterpivotal]

I hear nostname is part of IPw6

[goehmen]

@jchesterpivotal - What version of the CLI and what CF release are you using? Let's start there and see if we can unwind this experience for you.

[jchesterpivotal]

@goehmen, hi. Thanks for looking into this.

$ cf --version
cf version 6.3.2-217929b-2014-07-24T00:26:56+00:00

$ bosh deployments

+-----------+------------+-------------------------------------------------+
| Name      | Release(s) | Stemcell(s)                                     |
+-----------+------------+-------------------------------------------------+
| cf-warden | cf/191     | bosh-warden-boshlite-ubuntu-trusty-go_agent/389 |
+-----------+------------+-------------------------------------------------+

Deployments total: 1

Cheers,

JC.

[goehmen]

@jchesterpivotal 6.3.2 is about 3 months old now. A CLI upgrade would likely resolve the endpoint deprecation errors you are seeing since you are using latest release.

The -n flag clearly needs to be a required argument. I opened a bug for that https://www.pivotaltracker.com/story/show/81981190

the -h hostname choice is unfortunate but the notion is to reserve -h for help always. At least -n refers to host'N'ame. @Amit-PivotalLabs is a troublemaker. Don't listen to him. It's not nostname, it's nosthame.

[jchesterpivotal]

Just upgraded to the latest stable:

$ cf --version
cf version 6.6.2-0c953cf-2014-10-17T18:10:36+00:00

Behaves the same, except the "Endpoint deprecated".

[goehmen]

I think the issue comes down to the confusion around the -n flag actually being required. I created a story (https://www.pivotaltracker.com/story/show/82001696) to look into making the hostname a required argument rather than an optional flag.

[goehmen]

https://www.pivotaltracker.com/story/show/81981190 now has a 7.0 label so it will get done with the next major release (7.0.0) which will follow on the heels of runtime's API 3.0 work which is underway.

Closing this issue in the mean time. Reopen if the need arises.

[tedhoganacn]

I just encountered this same issue. Googled and I am here. FYI

[SugandhaAgrawal]

Use of cf delete-route --help explains: NAME: delete-route - Delete a route

USAGE: cf delete-route DOMAIN [--hostname HOSTNAME] [--path PATH] [-f]

EXAMPLES: cf delete-route example.com # example.com cf delete-route example.com --hostname myhost # myhost.example.com cf delete-route example.com --hostname myhost --path foo # myhost.example.com/foo

OPTIONS: -f Force deletion without confirmation --hostname, -n Hostname used to identify the route --path Path used to identify the route

So then you have to explicitly mention your domain name and hostname and then it worked for me.

[Malu44]

Has the same issue - but Google is your friend. And here I'm!

[dkoper]

@Malu44 @tedhoganacn

I missed your updates to this issue. @jchesterpivotal described his initial experience encompassing several issues. I understood the major ones were addressed. Can you be specific on "the same issue" you are having, ideally open a new issue detailing it so we get a new story in our tracker to prioritize?

Cheers, Dies Koper CF CLI PM

[tedhogan-zz]

@dkoper the --help still lists the Hostname argument as optional which can be confusing to the inexperienced.

This is what I see when I type cf delete-route --help from VERSION 6.16.1+924508c-2016-02-26: cf delete-route DOMAIN [--hostname HOSTNAME] [--path PATH] [-f]

As a user, I have a route to my app. I want to delete the route to my app. My first thought is "cf delete-route " should work. It doesn't, so I look up the help and it tells me that I need a DOMAIN argument, but that the HOSTNAME (what in my mind I call my app) is optional. So, I Google, end up here and see:

cf delete-route 10.244.0.34.xip.io -n bcs

In the comments and bingo, I get it.

At first glance, I expected the most important argument of that command to be the HOSTNAME and I expected the DOMAIN to be implied and optional. To me, this would be more natural. So, I find the current way that the command is setup to be the opposite from what I would expect.

Hope this helps.