oxidecomputer / oxidecomputer/omicron

openapi-manager is confused when a lockstep API has a version change

Open
#7,871 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
572
Forks
97
Avg merge
2d 12h
Merged PRs (30d)
96

Description

Currently we bump the Nexus external OpenAPI version with each release (as seen in #7870).

When running cargo xtask openapi generate after bumping the version in the openapi-manager crate we end up in a bizarre state:

  Generating OpenAPI documents from API definitions ...
     Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
     Loading blessed OpenAPI documents from git revision "origin/main" path "openapi"
     -------
    Updating 14 OpenAPI documents...
   Unchanged bootstrap-agent (lockstep v0.0.1): Bootstrap Agent API
   Unchanged clickhouse-admin-keeper (lockstep v0.0.1): ClickHouse Cluster Admin Keeper API
   Unchanged clickhouse-admin-server (lockstep v0.0.1): ClickHouse Cluster Admin Server API
   Unchanged clickhouse-admin-single (lockstep v0.0.1): ClickHouse Single-Node Admin Server API
   Unchanged cockroach-admin (lockstep v0.0.1): CockroachDB Cluster Admin API
   Unchanged dns-server (versioned v1.0.0 (blessed)): Internal DNS
   Unchanged dns-server "latest" symlink
   Unchanged gateway (lockstep v0.0.1): Oxide Management Gateway Service API
   Unchanged installinator (lockstep v0.0.1): Installinator API
       Stale nexus (lockstep v20250409.0.0): Oxide Region API
       Fixed updated /home/iliana/git/worktree/tuf-repo-depot/openapi/nexus.json: Updated
   Unchanged nexus-internal (lockstep v0.0.1): Nexus internal API
   Unchanged oximeter (lockstep v0.0.1): Oxide Oximeter API
   Unchanged repo-depot (lockstep v0.0.1): Oxide TUF Repo Depot API
   Unchanged sled-agent (lockstep v0.0.1): Oxide Sled Agent API
   Unchanged wicketd (lockstep v0.0.1): Oxide Technician Port Control Service
       Fixed removed /home/iliana/git/worktree/tuf-repo-depot/openapi/nexus.json
     Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
  Rechecking all local files
found unexpected problem with API nexus version 20250409.0.0 (this is a bug)
         problem: No local OpenAPI document was found for this lockstep API.  This is only expected if you're adding a new lockstep API.  This tool can
                  generate the file for you.
             fix: will rewrite lockstep file nexus.json from generated
failure: ERROR: found problems after successfully fixing everything (this is a BUG!)

The ultimate result of this is that nexus.json is deleted. A workaround for this bug is to simply run the generate command again, as it will then regenerate nexus.json from scratch.

Output of cargo xtask openapi check in the original state:

  Generating OpenAPI documents from API definitions ...
     Loading local OpenAPI documents from "/home/iliana/git/worktree/tuf-repo-depot/openapi" ...
     Loading blessed OpenAPI documents from git revision "origin/main" path "openapi"
     -------
    Checking 14 OpenAPI documents...
       Fresh bootstrap-agent (lockstep v0.0.1): Bootstrap Agent API
       Fresh clickhouse-admin-keeper (lockstep v0.0.1): ClickHouse Cluster Admin Keeper API
       Fresh clickhouse-admin-server (lockstep v0.0.1): ClickHouse Cluster Admin Server API
       Fresh clickhouse-admin-single (lockstep v0.0.1): ClickHouse Single-Node Admin Server API
       Fresh cockroach-admin (lockstep v0.0.1): CockroachDB Cluster Admin API
       Fresh dns-server (versioned v1.0.0 (blessed)): Internal DNS
       Fresh dns-server "latest" symlink
       Fresh gateway (lockstep v0.0.1): Oxide Management Gateway Service API
       Fresh installinator (lockstep v0.0.1): Installinator API
       Stale nexus (lockstep v20250409.0.0): Oxide Region API
         problem: No local OpenAPI document was found for this lockstep API.  This is only expected if you're adding a new lockstep API.  This tool can
                  generate the file for you.
             fix: will rewrite lockstep file nexus.json from generated
       Fresh nexus-internal (lockstep v0.0.1): Nexus internal API
       Fresh oximeter (lockstep v0.0.1): Oxide Oximeter API
       Fresh repo-depot (lockstep v0.0.1): Oxide TUF Repo Depot API
       Fresh sled-agent (lockstep v0.0.1): Oxide Sled Agent API
       Fresh wicketd (lockstep v0.0.1): Oxide Technician Port Control Service

       Other problems not associated with a specific supported API version:
         problem: A local OpenAPI document was found that does not correspond to a supported version of this API: nexus.json.  This is unusual, but it could
                  happen if you're either retiring an older version of this API or if you created this version in this branch and later merged with upstream
                  and had to change your local version number.  In either case, this tool can remove the unused file for you.
             fix: will delete file: nexus.json

        Note API nexus version 20250212.0.0: formerly blessed version has been removed.  This version will no longer be supported!  This will break upgrade
             from software that still uses this version.  If this is unexpected, check the list of supported versions in Rust for a possible mismerge.

     -------
       Stale 14 documents checked: 14 fresh, 1 stale, 0 failed, 1 other problem
             (run cargo xtask openapi generate to update)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the cargo xtask openapi generate and cargo xtask openapi check entry points, then inspect the openapi-manager crate and the openapi/nexus.json handling described in the report. Reproduce the version bump scenario and verify that generation does not delete the local document and that a subsequent check reports the API as fresh.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.