Implement the determinations of RFD 285

[ahl]

This implements the renames described in 285 to the best of my ability. I would appreciate a careful review of the names chosen with an eye towards:

• hierarchy
• singular/plural
• non-CRUD operation naming

Imagine that these names will translate verbatim into the CLI.

The nexus_tags.txt file may be the most concise way to consider this.

[ahl]

@davepacheco thoughts?

[karencfv]

This is looking really great! It makes me so happy to see these changes, thanks for pushing for semantic naming! 🎉

[karencfv]

I was under the impression we were going to change all *_view to *_get? Unless I missed something?

[zephraph]

Not that it necessarily matters one way or the other, but GitHub's CLI uses view and edit. Regardless, it's all an upgrade to what we have today, ha.

[david-crespo]

@karencfv we had agreed on edit -> update but were 50-50 on view vs. get. I guess I slightly prefer get since we might as well match the http method when it's natural to do so.

[ahl]

I actually took the deliberate step not to match the HTTP method because I thought it might be confusing if some matched while others did not. That said: not a strong preference so if someone wants to make a case for one vs. the other that would be clarifying.

[david-crespo]

I can definitely see that side too. It makes you assume things about the semantics that we may not want to imply. Or maybe we actually do because we want these to be spec compliant gets.

[karencfv]

I'm on the fence about this one as well 😅, but I think I'm leaning more towards the use of get. It's a tad more consistent with what people will be used to seeing in SDKs generally. That said, while get appears everywhere, there are also weird inconsistencies everywhere. Like for example, AWS uses some weird combination of "sometimes get, sometimes describe". Both Azure and GCP have the more consistent APIs/SDKs and VMware is all over the place. So , I guess sticking to view isn't a huge deal as long as we don't deviate.

TLDR: I have slight preference for get but not a huge deal if we stick with view :)

[ahl]

I'm going to go with _view. I think of all the things to change in the future, s/_view/_get/ is going to be pretty easy in API/SDK/CLI/etc.

[karencfv]

Maybe unrelated to this PR, but why is the tag "images:global" and not "global_images"?

[ahl]

yeah; let's set that aside? I agree though that it's ... odd

[karencfv]

sounds good!

[ahl]

Maybe we should have a single tag for fleet-wide operations?

[karencfv]

That sounds really good!

[karencfv]

Heya @ahl, I was just trying out this fancy new nexus.json file with oxide.rs and the CLI and it turns out the CLI broke in many more unexpected ways than just the method names 😅. Since the testing isn't complete in both CLI and SDKs. What do you think about merging this PR after the demo? I'm totally OK with breaking all the things after that date. Would it be too annoying to do that?

@zephraph @david-crespo what do you think?

[david-crespo]

This is a big customer-facing improvement across the board besides that, so it’s probably worth spending a couple of hours to see if maybe it’s less of a disaster in the client libs than it seems at first.

How far off is the progenitor branch of Oxide.rs? Presumably it has fewer issues?

[zephraph]

I wish we could just push through with this too, but... I'm not sure we can. Without a larger team effort to tackle this migration @karencfv is right.

There's a lot that would break.

1. The current rust SDK (we could switch, but there's progenitor work that still has to be finished so that's effectively blocked)
2. The proc macro that generates a lot of the CLI
3. The Go SDK

We've got a lot of conditional logic around naming that makes the SDKs pretty fragile to changes like this.

[karencfv]

I already spent quite a bit more than a couple of hours on this unfortunately 😅 Like Justin says a lot would break 😢

There are two major pain points regarding the Rust SDK/CLI

• This proc macro https://github.com/oxidecomputer/cli/blob/main/cli-macro-impl/src/lib.rs . It's highly customised to the previous tags with many conditionals based on the tags unfortunately.
• This types template https://github.com/oxidecomputer/oxide.rs/blob/main/generator/src/types_templates.rs which and Also, the testing coverage is not optimal, so testing does not guarantee that commands will work if we managed to update the CLI on time.

Also, The work with progenitor is quite far from working with the CLI yet, and will not be able to work with the current CLI generator at all.

[karencfv]

There's also the point to consider that given the CLI will change, is it a good use of time to spend that much time updating it?

[david-crespo]

Ok, that is persuasive. Seems like we should do the Progenitor stuff first so this change is less painful. On the Go SDK side since there’s no progenitor maybe we could at least reduce the amount of custom renaming logic first.

[karencfv]

Yep! Adam and I are working on the progenitor stuff now (from both sides of the fence 😄 ). I'm giving this top priority. The Go SDK will wait a bit as the Terraform provider is in demo condition anyway as there are no update endpoints for disks and instances

[ahl]

The latest on the demo is that it may not be for another month. My hope for the demo was to have the API trending towards the state we want it to be in. I'm not clear on when the API/CLI/SDKs may be in the hands of early users, but I expect it will follow close on the heels of the demo. After remote access will come our own robust internal use, documentation, automation, etc. And then product launch.

We will continue to expand and evolve the API. My hope was that by changing its trajectory now there would be less to tidy up later. That is to say: we follow the examples we see so if we can dominate the API with examples we want rather than examples we don't we will follow the positive examples.

In short, I think we need to find a path forward. Here's a simple kludge: I can extract from this PR a one-to-one list of operationId name changes. oxide.rs and others can pump nexus.json through sed to get the old names. Omicron can move forward and we can make progress with progenitor and the CLI.

To be clear, there are going to be aspects of this that suck and it's going to be brittle. But I think the alternative may be to incur more change and more risk later in the product development lifecycle. I'd suggest interested parties meet tomorrow afternoon PT/morning NZ to discuss.

[karencfv]

Happy to catch up in my morning, but just want to comment that I'm perfectly fine with:

In short, I think we need to find a path forward. Here's a simple kludge: I can extract from this PR a one-to-one list of operationId name changes. oxide.rs and others can pump nexus.json through sed to get the old names. Omicron can move forward and we can make progress with progenitor and the CLI.

I'd really hate to stop this work from moving along, and this seems like a reasonable temporary solution while the new SDK/CLI is up and running :)

[zephraph]

@ahl, yep, that sounds like a solid path forward.

[ahl]

Here is the list of renames (old new). I'm going to wait for a final 👍 from @karencfv this afternoon before merging.

hardware_racks_get rack_list
hardware_racks_get_rack rack_view
hardware_sleds_get sled_list
hardware_sleds_get_sled sled_view
images_get image_global_list
images_post image_global_create
images_delete_image image_global_delete
images_get_image image_global_view
ip_pools_get ip_pool_list
ip_pools_post ip_pool_create
ip_pools_delete_ip_pool ip_pool_delete
ip_pools_get_ip_pool ip_pool_view
ip_pools_put_ip_pool ip_pool_update
ip_pool_ranges_get ip_pool_range_list
ip_pool_ranges_add ip_pool_range_add
ip_pool_ranges_delete ip_pool_range_remove
organizations_get organization_list
organizations_post organization_create
organizations_delete_organization organization_delete
organizations_get_organization organization_view
organizations_put_organization organization_update
organization_get_policy organization_policy_view
organization_put_policy organization_policy_update
organization_projects_get project_list
organization_projects_post project_create
organization_projects_delete_project project_delete
organization_projects_get_project project_view
organization_projects_put_project project_update
project_disks_get disk_list
project_disks_post disk_create
project_disks_delete_disk disk_delete
project_disks_get_disk disk_view
project_images_get image_list
project_images_post image_create
project_images_delete_image image_delete
project_images_get_image image_view
project_instances_get instance_list
project_instances_post instance_create
project_instances_delete_instance instance_delete
project_instances_get_instance instance_view
instance_disks_get instance_disk_list
instance_disks_attach instance_disk_attach
instance_disks_detach instance_disk_detach
project_instances_migrate_instance instance_migrate
instance_network_interfaces_get instance_network_interface_list
instance_network_interfaces_post instance_network_interface_create
instance_network_interfaces_get_interface instance_network_interface_view
instance_network_interfaces_put_interface instance_network_interface_update
instance_network_interfaces_delete_interface instance_network_interface_delete
project_instances_instance_reboot instance_reboot
project_instances_instance_serial_get instance_serial_console
project_instances_instance_start instance_start
project_instances_instance_stop instance_stop
organization_projects_get_project_policy project_policy_view
organization_projects_put_project_policy project_policy_update
project_snapshots_get snapshot_list
project_snapshots_post snapshot_create
project_snapshots_delete_snapshot snapshot_delete
project_snapshots_get_snapshot snapshot_view
project_vpcs_get vpc_list
project_vpcs_post vpc_create
project_vpcs_delete_vpc vpc_delete
project_vpcs_get_vpc vpc_view
project_vpcs_put_vpc vpc_update
vpc_firewall_rules_get vpc_firewall_rules_view
vpc_firewall_rules_put vpc_firewall_rules_update
vpc_routers_get vpc_router_list
vpc_routers_post vpc_router_create
vpc_routers_delete_router vpc_router_delete
vpc_routers_get_router vpc_router_view
vpc_routers_put_router vpc_router_update
routers_routes_get vpc_router_route_list
routers_routes_post vpc_router_route_create
routers_routes_delete_route vpc_router_route_delete
routers_routes_get_route vpc_router_route_view
routers_routes_put_route vpc_router_route_update
vpc_subnets_get vpc_subnet_list
vpc_subnets_post vpc_subnet_create
vpc_subnets_delete_subnet vpc_subnet_delete
vpc_subnets_get_subnet vpc_subnet_view
vpc_subnets_put_subnet vpc_subnet_update
subnet_network_interfaces_get vpc_subnet_list_network_interfaces
policy_get policy_view
policy_put policy_update
roles_get role_list
roles_get_role role_view
sagas_get saga_list
sagas_get_saga saga_view
sshkeys_get session_sshkey_list
sshkeys_post session_sshkey_create
sshkeys_delete_key session_sshkey_delete
sshkeys_get_key session_sshkey_view
silos_get silo_list
silos_post silo_create
silos_delete_silo silo_delete
silos_get_silo silo_view
silos_get_identity_providers silo_identity_provider_list
silos_get_silo_policy silo_policy_view
silos_put_silo_policy silo_policy_update
silo_saml_idp_create silo_identity_provider_view
silo_saml_idp_fetch silo_identity_provider_create
silo_users_get user_list

[karencfv]

Thanks @ahl !! That list will keep the CLI alive until we have the new SDK