set up API versioning machinery for most internal services (#8789)

Part of #8727 (the easy ones)

Author: iliana

Cargo.lock

@@ -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

clickhouse-admin/api/Cargo.toml

@@ -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!([
+    // 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
 ///

clickhouse-admin/api/src/lib.rs

@@ -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)
 }
@@ -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)
 }
@@ -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)
 }

clickhouse-admin/src/lib.rs

@@ -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| {

clients/clickhouse-admin-keeper-client/src/lib.rs

@@ -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| {

clients/clickhouse-admin-server-client/src/lib.rs

@@ -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| {

clients/clickhouse-admin-single-client/src/lib.rs

@@ -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| {

clients/cockroach-admin-client/src/lib.rs

@@ -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| {

clients/ntp-admin-client/src/lib.rs

@@ -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| {