I am confused why I cannot see a route that I'm told is unavailable.

[jchesterpivotal]

Using cf version 6.20.0+25b1961-2016-06-29

What Happens

So I try to push an app:

cf push example-app

And I am told I can't, because the route is taken:

Using route example-app.local.pcfdev.io
       Binding example-app.local.pcfdev.io to app_using_angular...
       FAILED
       The route example-app.local.pcfdev.io is already in use.
       TIP: Change the hostname with -n HOSTNAME or use --random-route to generate a new route and then push again.

Huh, that's weird. Just a few minutes ago I'd used cf delete example-app to clear the way.

Let me just check!

$ cf routes
Getting routes for org pivotal / space integration as admin ...

space   host   domain   port   path   type   apps   service
No routes found

Um ... what? Where's the route?

After some searching, it turns out that the route is in another organization. I can't see that route from where I am. I just keep getting told "no, you can't use it". On a scale from 1 to "Jacquesrant", this rates increasingly higher on each iteration.

Luckily one of my colleagues has seen this before and does this:

$ cf target

API endpoint:   https://api.local.pcfdev.io (API version: 2.58.0)
User:           admin
Org:            org-which-does-not-contain-the-route-but-is-nevertheless-blocked-from-acquiring-it
Space:        a-space

And then does this:

$ cf target -o org-which-happens-to-be-holding-on-the-route

API endpoint:   https://api.local.pcfdev.io (API version: 2.58.0)
User:           admin
Org:            org-which-happens-to-be-holding-on-the-route
Space:        another-space

And then:

$ cf delete-orphaned-routes

Really delete orphaned routes?>> y
Getting routes as admin ...

Deleting route example-app.local.pcfdev.io...
OK

And now we're clear to reuse example-app.

What I Wish Had Happened:

Using route example-app.local.pcfdev.io
       Binding example-app.local.pcfdev.io to app_using_angular...
       FAILED
       The route example-app.local.pcfdev.io is not available for binding because it has been used by another organization.
       TIP: Change the hostname with -n HOSTNAME or use --random-route to generate a new route and then push again.

The change is to say that the route was taken by a different org.

While it would be convenient to know which org is holding the route, this would leave folk open to enumeration attacks intended to find who owns what routes.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/132116249

The labels on this github issue will be updated when the story is started.

[dkoper]

@SocalNick @shalako Can you confirm that with the following API's error response, we can safely change the current CLI message of "The route is already in use." by something like "The route is already in use in another org."?

PUT /v2/apps/ff4f92d6-4157-456c-a62d-d5ead73d953a/routes/9304d6b0-a180-470f-a306-1aacd156950c HTTP/1.1
...

HTTP/1.1 400 Bad Request
...
{
  "code": 1002,
  "description": "Invalid relation: The requested route relation is invalid: 9304d6b0-a180-470f-a306-1aacd156950c",
  "error_code": "CF-InvalidRelation"
}

[shalako]

The constraint is that app and route must exist in the same space (can be in the same org or another; doesn't matter).

I don't think that the current API response is helpful. Better would be The app cannot be mapped to the route because they are not in the same space.

If the CLI passed through the API response I have suggested, it would be more meaningful than the current CLI UX. The current response ...is already in use is misleading, as it doesn't matter whether a route is in use but that it was created in another space; the route could be mapped to an app or not. A more helpful response might be: The route example.cf.com cannot be mapped to an app in space foo because it has been reserved in another space.

[jchesterpivotal]

I'm less fussed about wording. The point is that I had no idea what the heck was going on. It was a very frustrating morning.

[SocalNick]

@jchesterpivotal would this wording have told you what was going on: https://www.pivotaltracker.com/story/show/138649897

[jchesterpivotal]

Not really. I already know that "the route is not in this space", that's exactly what drove me to despair.

What I need to know is why.

[SocalNick]

@jchesterpivotal so would it help if the error was:

The app cannot be mapped to this route because the route is not in this space. Apps must be mapped to routes in the same space

[jchesterpivotal]

Not really. I would still type cf routes, get an empty route table and be confused. If the route is reserved by someone else, that's what explains the outcome. Knowing or not knowing who holds it would be a secondary consideration.

[SocalNick]

@jchesterpivotal why would you type cf routes when we told you that the route is not in the current space?

[jchesterpivotal]

Because I'm not a CLI developer. I have a fuzzy model of how CF works. I might, for example, expect to be told which space or org it belonged to.

But mostly because I am lazy, in both the negative sense and positive sense. I hate thinking, I reserve it for leisure activities.

[SocalNick]

@jchesterpivotal I don't think we are going to provide which space and org the route belongs to in an error message. As an API server, we don't want to spend extra time looking things up for 4xx client errors.

Unless you have a suggested error message, I'll use what I mentioned above.

[jchesterpivotal]

I'm not asking to know who owns it. In fact, it's a bad idea; that information could be considered sensitive, as it can leak information.

I just want the clearest message I can about why it's unavailable.

Without knowing how the API works in depth, is there a scenario in which a route can exist without being owned?

Because if a route is always owned, you don't need to look up the owner to tell me someone else took it. You can infer that from its unavailability.

My original request is not based on a hypothetical. This really happened to me. I wasted an entire morning because I am not willing or able to mentally model every single component in Cloud Foundry all the time. The message I suggested would've entirely avoided the question.

[SocalNick]

For everyone else on this thread, @jchesterpivotal and I had an offline conversation. I've captured an alternative error message in the story and will work with @zrob, the incoming CAPI PM, on the exact wording.

[dkoper]

Thanks Nick!
Once the new wording has been finalised, we'll look at updating the CLI to use the same message.