Skip to content

set up API versioning machinery for most internal services #8789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Aug 19, 2025
Merged

set up API versioning machinery for most internal services #8789

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
b328417
openapi-manager: explain the warnings a bit more
iliana Aug 6, 2025
44eb1e6
cockroach-admin: versionify
iliana Aug 6, 2025
a994f1f
gateway: versionify
iliana Aug 6, 2025
db0cd8c
clickhouse-admin-api: versionify
iliana Aug 6, 2025
fb70f21
ntp-admin-api: versionify
iliana Aug 6, 2025
14cc112
oximeter-api: versionify
iliana Aug 6, 2025
75a6586
sled-agent-api: versionify
iliana Aug 6, 2025
c1fea36
Merge remote-tracking branch 'origin/main' into iliana/api-versioning
iliana Aug 11, 2025
f89d6f8
oops
iliana Aug 11, 2025
2573caa
merge
iliana Aug 11, 2025
5de0b63
api-version header wip (not yet all of them)
iliana Aug 12, 2025
dc3c90d
finish adding api-version header
iliana Aug 12, 2025
439534b
Merge remote-tracking branch 'origin/main' into iliana/api-versioning
iliana Aug 12, 2025
c6031bc
Merge remote-tracking branch 'origin/main' into iliana/api-versioning
iliana Aug 19, 2025
2e7301d
Revert "gateway: versionify"
iliana Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions clickhouse-admin/api/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,7 @@ dropshot.workspace = true
omicron-common.workspace = true
omicron-uuid-kinds.workspace = true
omicron-workspace-hack.workspace = true
openapi-manager-types.workspace = true
schemars.workspace = true
semver.workspace = true
serde.workspace = true
35 changes: 35 additions & 0 deletions clickhouse-admin/api/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,41 @@ use dropshot::{
HttpResponseUpdatedNoContent, Path, Query, RequestContext, TypedBody,
};
use omicron_common::api::external::Generation;
use openapi_manager_types::{
SupportedVersion, SupportedVersions, api_versions,
};

api_versions!([
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We had talked about versioning the three Clickhouse services separately in separate modules. Did you opt not to?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. I added a note in this block (just below here) suggesting that whoever finds a need to add a new version to these APIs should determine whether all the services should share the same versions, or whether to split them into modules. Although now a couple of days later I'm questioning my choices.

// NOTE: These versions will be used across **all three** APIs defined in
// this file. When we need to add the next version, consider carefully if
// these APIs should be split into separate modules or crates with their
// own versions.

// WHEN CHANGING THE API (part 1 of 2):
//
// +- Pick a new semver and define it in the list below. The list MUST
// | remain sorted, which generally means that your version should go at
// | the very top.
// |
// | Duplicate this line, uncomment the *second* copy, update that copy for
// | your new API version, and leave the first copy commented out as an
// | example for the next person.
// v
// (next_int, IDENT), // NOTE: read the note at the start of this macro!
(1, INITIAL),
]);

// WHEN CHANGING THE API (part 2 of 2):
//
// The call to `api_versions!` above defines constants of type
// `semver::Version` that you can use in your Dropshot API definition to specify
// the version when a particular endpoint was added or removed. For example, if
// you used:
//
// (2, ADD_FOOBAR)
//
// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
// were added or removed.

/// API interface for our clickhouse-admin-keeper server
///
Expand Down
18 changes: 18 additions & 0 deletions clickhouse-admin/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,12 @@ pub async fn start_server_admin_server(
log.new(slog::o!("component" => "dropshot")),
)
.config(server_config.dropshot)
.version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
dropshot::ClientSpecifiesVersionInHeader::new(
omicron_common::api::VERSION_HEADER,
clickhouse_admin_api::VERSION_INITIAL,
),
)))
.start()
.map_err(StartError::InitializeHttpServer)
}
Expand Down Expand Up @@ -105,6 +111,12 @@ pub async fn start_keeper_admin_server(
log.new(slog::o!("component" => "dropshot")),
)
.config(server_config.dropshot)
.version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
dropshot::ClientSpecifiesVersionInHeader::new(
omicron_common::api::VERSION_HEADER,
clickhouse_admin_api::VERSION_INITIAL,
),
)))
.start()
.map_err(StartError::InitializeHttpServer)
}
Expand Down Expand Up @@ -142,6 +154,12 @@ pub async fn start_single_admin_server(
log.new(slog::o!("component" => "dropshot")),
)
.config(server_config.dropshot)
.version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
dropshot::ClientSpecifiesVersionInHeader::new(
omicron_common::api::VERSION_HEADER,
clickhouse_admin_api::VERSION_INITIAL,
),
)))
.start()
.map_err(StartError::InitializeHttpServer)
}
2 changes: 1 addition & 1 deletion clients/clickhouse-admin-keeper-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
//! running in an omicron zone.

progenitor::generate_api!(
spec = "../../openapi/clickhouse-admin-keeper.json",
spec = "../../openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/clickhouse-admin-server-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
//! running in an omicron zone.

progenitor::generate_api!(
spec = "../../openapi/clickhouse-admin-server.json",
spec = "../../openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/clickhouse-admin-single-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
//! ClickHouse database.

progenitor::generate_api!(
spec = "../../openapi/clickhouse-admin-single.json",
spec = "../../openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/cockroach-admin-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
//! Interface for making API requests to an Omicron CockroachDB admin server

progenitor::generate_api!(
spec = "../../openapi/cockroach-admin.json",
spec = "../../openapi/cockroach-admin/cockroach-admin-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/gateway-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ use types::ComponentFirmwareHashStatus;
// call into each other. Since `gateway` is a lower-level service and never
// calls into Nexus, the current scheme is okay.)
progenitor::generate_api!(
spec = "../../openapi/gateway.json",
spec = "../../openapi/gateway/gateway-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/ntp-admin-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
//! Interface for making API requests to an Omicron NTP admin server

progenitor::generate_api!(
spec = "../../openapi/ntp-admin.json",
spec = "../../openapi/ntp-admin/ntp-admin-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/oximeter-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
//! Interface for API requests to an Oximeter metric collection server

progenitor::generate_api!(
spec = "../../openapi/oximeter.json",
spec = "../../openapi/oximeter/oximeter-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 1 addition & 1 deletion clients/sled-agent-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ use uuid::Uuid;
pub use propolis_client::{CrucibleOpts, VolumeConstructionRequest};

progenitor::generate_api!(
spec = "../../openapi/sled-agent.json",
spec = "../../openapi/sled-agent/sled-agent-latest.json",
interface = Positional,
inner_type = slog::Logger,
pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
Expand Down
2 changes: 2 additions & 0 deletions cockroach-admin/api/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,7 @@ http.workspace = true
omicron-common.workspace = true
omicron-uuid-kinds.workspace = true
omicron-workspace-hack.workspace = true
openapi-manager-types.workspace = true
schemars.workspace = true
semver.workspace = true
serde.workspace = true
30 changes: 30 additions & 0 deletions cockroach-admin/api/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,39 @@ use dropshot::{
TypedBody,
};
use omicron_uuid_kinds::OmicronZoneUuid;
use openapi_manager_types::{
SupportedVersion, SupportedVersions, api_versions,
};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

api_versions!([
// WHEN CHANGING THE API (part 1 of 2):
//
// +- Pick a new semver and define it in the list below. The list MUST
// | remain sorted, which generally means that your version should go at
// | the very top.
// |
// | Duplicate this line, uncomment the *second* copy, update that copy for
// | your new API version, and leave the first copy commented out as an
// | example for the next person.
// v
// (next_int, IDENT),
(1, INITIAL),
]);

// WHEN CHANGING THE API (part 2 of 2):
//
// The call to `api_versions!` above defines constants of type
// `semver::Version` that you can use in your Dropshot API definition to specify
// the version when a particular endpoint was added or removed. For example, if
// you used:
//
// (2, ADD_FOOBAR)
//
// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
// were added or removed.

#[dropshot::api_description]
pub trait CockroachAdminApi {
type Context;
Expand Down
6 changes: 6 additions & 0 deletions cockroach-admin/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,12 @@ pub async fn start_server(
log.new(slog::o!("component" => "dropshot")),
)
.config(server_config.dropshot)
.version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
dropshot::ClientSpecifiesVersionInHeader::new(
omicron_common::api::VERSION_HEADER,
cockroach_admin_api::VERSION_INITIAL,
),
)))
.start()
.map_err(StartError::InitializeHttpServer)
}
4 changes: 4 additions & 0 deletions common/src/api/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,7 @@

pub mod external;
pub mod internal;

/// API versioning header name used across Omicron APIs.
pub const VERSION_HEADER: http::HeaderName =
http::HeaderName::from_static("api-version");
30 changes: 22 additions & 8 deletions dev-tools/openapi-manager/src/omicron.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "ClickHouse Cluster Admin Keeper API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
clickhouse_admin_api::supported_versions(),
),
description: "API for interacting with the Oxide \
control plane's ClickHouse cluster keepers",
boundary: ApiBoundary::Internal,
Expand All @@ -47,7 +49,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "ClickHouse Cluster Admin Server API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
clickhouse_admin_api::supported_versions(),
),
description: "API for interacting with the Oxide \
control plane's ClickHouse cluster replica servers",
boundary: ApiBoundary::Internal,
Expand All @@ -58,7 +62,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "ClickHouse Single-Node Admin Server API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
clickhouse_admin_api::supported_versions(),
),
description: "API for interacting with the Oxide \
control plane's single-node ClickHouse database",
boundary: ApiBoundary::Internal,
Expand All @@ -69,7 +75,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "CockroachDB Cluster Admin API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
cockroach_admin_api::supported_versions(),
),
description: "API for interacting with the Oxide \
control plane's CockroachDB cluster",
boundary: ApiBoundary::Internal,
Expand All @@ -90,7 +98,7 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "Oxide Management Gateway Service API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(gateway_api::supported_versions()),
description: "API for interacting with the Oxide \
control plane's gateway service",
boundary: ApiBoundary::Internal,
Expand Down Expand Up @@ -130,7 +138,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "NTP Admin API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
ntp_admin_api::supported_versions(),
),
description: "API for interacting with NTP",
boundary: ApiBoundary::Internal,
api_description: ntp_admin_api_mod::stub_api_description,
Expand All @@ -139,7 +149,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "Oxide Oximeter API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
oximeter_api::supported_versions(),
),
description: "API for interacting with oximeter",
boundary: ApiBoundary::Internal,
api_description: oximeter_api_mod::stub_api_description,
Expand All @@ -157,7 +169,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
},
ManagedApiConfig {
title: "Oxide Sled Agent API",
versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
versions: Versions::new_versioned(
sled_agent_api::supported_versions(),
),
description: "API for interacting with individual sleds",
boundary: ApiBoundary::Internal,
api_description: sled_agent_api_mod::stub_api_description,
Expand Down
Loading
Loading