From ad3077560474880255126b5f57b48c3606826936 Mon Sep 17 00:00:00 2001 From: sdairs Date: Tue, 17 Nov 2026 17:07:22 +0000 Subject: [PATCH] feat(cli): manage Postgres AWS private endpoints Adds `cloud postgres private-endpoint get|create|update|delete` (Beta). `update` reads the endpoint and merges `--add-vpc-endpoint`, `--remove-vpc-endpoint`, `--add-region` and `--remove-region` into the current lists, because the API replaces each list it is sent in full; it sends only the lists that change. Removing something absent warns, as `cloud service update` does. `delete` prints the endpoint it read first, as `cloud postgres delete` does. Fixes #1485 Co-Authored-By: Claude Opus 5.5 --- .../clickhousectl/src/cloud/postgres/cli.rs | 231 ++++++++- .../src/cloud/postgres/client.rs | 84 +++- .../clickhousectl/src/cloud/postgres/mod.rs | 78 ++- .../src/cloud/postgres/private_endpoint.rs | 472 ++++++++++++++++++ crates/clickhousectl/tests/cloud/postgres.rs | 149 ++++++ docs/guides/managed-postgres.md | 18 + 6 files changed, 1023 insertions(+), 9 deletions(-) create mode 100644 crates/clickhousectl/src/cloud/postgres/private_endpoint.rs diff --git a/crates/clickhousectl/src/cloud/postgres/cli.rs b/crates/clickhousectl/src/cloud/postgres/cli.rs index 9ca15ea5..05ca70c1 100644 --- a/crates/clickhousectl/src/cloud/postgres/cli.rs +++ b/crates/clickhousectl/src/cloud/postgres/cli.rs @@ -5,14 +5,15 @@ use super::observability::{ parse_known_postgres_logs_sort_order, parse_postgres_log_severity, parse_postgres_window_datetime, }; +use super::private_endpoint::parse_vpc_endpoint; use crate::cloud::shared::{NameSelector, SourceSelector, parse_datetime}; use clap::builder::NonEmptyStringValueParser; use clap::builder::TypedValueParser; use clap::{ArgGroup, Subcommand}; use clickhouse_cloud_api::models::{ PgHaType, PgProvider, PgVersion, PostgresIpAccessListEntry, PostgresLogsGetListSeverity, - PostgresLogsGetListSortorder, SlowQueryPatternsGetListSortby, - SlowQueryPatternsGetListSortorder, + PostgresLogsGetListSortorder, PostgresPrivateEndpointVpcEndpoint, + SlowQueryPatternsGetListSortby, SlowQueryPatternsGetListSortorder, }; use std::path::PathBuf; @@ -315,6 +316,19 @@ CONTEXT FOR AGENTS: #[command(subcommand)] Backup(PostgresBackupCommands), + /// Manage the Postgres AWS private endpoint (Beta) + #[command( + name = "private-endpoint", + subcommand, + after_help = "\ +CONTEXT FOR AGENTS: + AWS Postgres services only, in organizations with private endpoints enabled. + Typical flow: `create`, poll `get` until state=available (5 to 10 minutes), create an AWS + VPC endpoint for endpointServiceName, then `update --add-vpc-endpoint `. + Connect through privateHostname from an approved VPC endpoint." + )] + PrivateEndpoint(PrivateEndpointCommands), + /// Restore a Postgres service to a point in time #[command(after_help = "\ CONTEXT FOR AGENTS: @@ -498,6 +512,93 @@ CONTEXT FOR AGENTS: }, } +#[derive(Subcommand)] +pub enum PrivateEndpointCommands { + /// Get the private endpoint of a Postgres service (Beta) + Get { + /// Postgres service ID (from `cloud postgres list`) + #[command(flatten)] + postgres_id: NameSelector, + }, + /// Create the private endpoint of a Postgres service (Beta) + Create { + /// Postgres service ID (from `cloud postgres list`) + #[command(flatten)] + postgres_id: NameSelector, + /// AWS region, other than the service's, that may connect (repeatable) + /// + /// Requires cross-region private endpoints for the organization. + #[arg( + long = "supported-region", + value_name = "REGION", + value_parser = NonEmptyStringValueParser::new() + )] + supported_region: Vec, + }, + /// Approve VPC endpoints or change supported regions (Beta) + #[command( + group(ArgGroup::new("private_endpoint_change").required(true).multiple(true).args([ + "add_vpc_endpoint", "remove_vpc_endpoint", "add_region", "remove_region" + ])), + after_help = "\ +CONTEXT FOR AGENTS: + Other approvals and regions are kept. Removing one that is not listed exits 0 with a + warning on stderr. Removed VPC endpoints can no longer connect." + )] + Update { + /// Postgres service ID (from `cloud postgres list`) + #[command(flatten)] + postgres_id: NameSelector, + /// VPC endpoint to approve (repeatable) + #[arg( + long = "add-vpc-endpoint", + value_name = "VPCE_ID[=DESCRIPTION]", + value_parser = parse_vpc_endpoint + )] + add_vpc_endpoint: Vec, + /// Approved VPC endpoint to remove (repeatable) + #[arg( + long = "remove-vpc-endpoint", + value_name = "VPCE_ID", + value_parser = NonEmptyStringValueParser::new() + )] + remove_vpc_endpoint: Vec, + /// AWS region to allow connections from (repeatable) + #[arg( + long = "add-region", + value_name = "REGION", + value_parser = NonEmptyStringValueParser::new() + )] + add_region: Vec, + /// Supported region to remove (repeatable) + #[arg( + long = "remove-region", + value_name = "REGION", + value_parser = NonEmptyStringValueParser::new() + )] + remove_region: Vec, + }, + /// Delete the private endpoint of a Postgres service (Beta) + #[command(after_help = "\ +CONTEXT FOR AGENTS: + Connections through approved VPC endpoints stop working; `create` makes a new endpoint + service with a new endpointServiceName, so VPC endpoints must be recreated.")] + Delete { + /// Postgres service ID (from `cloud postgres list`) + #[command(flatten)] + postgres_id: NameSelector, + }, +} + +impl PrivateEndpointCommands { + fn is_write(&self) -> bool { + match self { + Self::Get { .. } => false, + Self::Create { .. } | Self::Update { .. } | Self::Delete { .. } => true, + } + } +} + #[derive(Subcommand)] pub enum PrometheusCommands { /// Get metrics for one Postgres service @@ -662,6 +763,7 @@ impl PostgresCommands { PostgresCommands::SlowQueries(command) => command.is_write(), PostgresCommands::Prometheus(command) => command.is_write(), PostgresCommands::Backup(PostgresBackupCommands::List { .. }) => false, + PostgresCommands::PrivateEndpoint(command) => command.is_write(), PostgresCommands::Certs(CertsCommands::Get { .. }) => false, PostgresCommands::Config(ConfigCommands::Get { .. }) => false, @@ -2396,4 +2498,129 @@ mod tests { panic!("expected organization prometheus"); }; } + + const PRIVATE_ENDPOINT: [&str; 4] = ["clickhousectl", "cloud", "postgres", "private-endpoint"]; + + fn private_endpoint_args<'a>(rest: &[&'a str]) -> Vec<&'a str> { + PRIVATE_ENDPOINT + .iter() + .copied() + .chain(rest.iter().copied()) + .collect() + } + + #[test] + fn private_endpoint_reads_and_writes_are_classified() { + for (rest, write) in [ + (&["get", "pg-1"][..], false), + (&["create", "pg-1"][..], true), + (&["update", "pg-1", "--add-region", "us-west-2"][..], true), + (&["delete", "--name", "db"][..], true), + ] { + let command = parse_postgres(&private_endpoint_args(rest)); + assert_eq!(command.is_write(), write, "{rest:?}"); + } + } + + #[test] + fn private_endpoint_create_repeats_supported_regions() { + let command = parse_postgres(&private_endpoint_args(&[ + "create", + "pg-1", + "--supported-region", + "us-west-2", + "--supported-region", + "eu-west-1", + ])); + let PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Create { + supported_region, + .. + }) = command + else { + panic!("expected private-endpoint create"); + }; + assert_eq!(supported_region, ["us-west-2", "eu-west-1"]); + } + + #[test] + fn private_endpoint_update_needs_a_change_and_parses_every_list_flag() { + let error = Cli::try_parse_from(private_endpoint_args(&["update", "pg-1"])) + .err() + .unwrap(); + assert_eq!( + error.kind(), + clap::error::ErrorKind::MissingRequiredArgument + ); + + let command = parse_postgres(&private_endpoint_args(&[ + "update", + "pg-1", + "--add-vpc-endpoint", + "vpce-0123456789abcdef0=Production VPC", + "--add-vpc-endpoint", + "vpce-0123456789abcdef1", + "--remove-vpc-endpoint", + "vpce-0123456789abcdef2", + "--add-region", + "us-west-2", + "--remove-region", + "eu-west-1", + ])); + let PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Update { + add_vpc_endpoint, + remove_vpc_endpoint, + add_region, + remove_region, + .. + }) = command + else { + panic!("expected private-endpoint update"); + }; + assert_eq!( + add_vpc_endpoint, + [ + PostgresPrivateEndpointVpcEndpoint { + vpc_endpoint_id: "vpce-0123456789abcdef0".into(), + description: Some("Production VPC".into()), + }, + PostgresPrivateEndpointVpcEndpoint { + vpc_endpoint_id: "vpce-0123456789abcdef1".into(), + description: None, + }, + ] + ); + assert_eq!(remove_vpc_endpoint, ["vpce-0123456789abcdef2"]); + assert_eq!(add_region, ["us-west-2"]); + assert_eq!(remove_region, ["eu-west-1"]); + } + + #[test] + fn private_endpoint_update_checks_added_but_not_removed_vpc_endpoint_ids() { + let error = Cli::try_parse_from(private_endpoint_args(&[ + "update", + "pg-1", + "--add-vpc-endpoint", + "vpce-NOTHEX", + ])) + .err() + .unwrap(); + assert_eq!(error.kind(), clap::error::ErrorKind::ValueValidation); + assert!(error.to_string().contains("vpce-NOTHEX")); + + // A stored ID must stay removable whatever its format (#611). + let command = parse_postgres(&private_endpoint_args(&[ + "update", + "pg-1", + "--remove-vpc-endpoint", + "vpce-NOTHEX", + ])); + let PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Update { + remove_vpc_endpoint, + .. + }) = command + else { + panic!("expected private-endpoint update"); + }; + assert_eq!(remove_vpc_endpoint, ["vpce-NOTHEX"]); + } } diff --git a/crates/clickhousectl/src/cloud/postgres/client.rs b/crates/clickhousectl/src/cloud/postgres/client.rs index de650e26..29be7dde 100644 --- a/crates/clickhousectl/src/cloud/postgres/client.rs +++ b/crates/clickhousectl/src/cloud/postgres/client.rs @@ -7,11 +7,12 @@ use crate::cloud::client::{ use clickhouse_cloud_api::RunPostgresQueryRequest; use clickhouse_cloud_api::models::{ PostgresInstanceConfig, PostgresInstanceConfigResponse, PostgresInstanceUpdateConfigResponse, - PostgresLogEntry, PostgresMetrics, PostgresService, PostgresServiceListItem, - PostgresServicePasswordResource, PostgresServicePatchRequest, PostgresServicePostRequest, - PostgresServiceReadReplicaRequest, PostgresServiceRestoreRequest, PostgresServiceSetPassword, - PostgresServiceSetState, PostgresServiceSetStateCommand, PostgresSlowQueryPattern, - PostgresSlowQueryPatternDetail, + PostgresLogEntry, PostgresMetrics, PostgresPrivateEndpoint, + PostgresPrivateEndpointPatchRequest, PostgresPrivateEndpointPostRequest, PostgresService, + PostgresServiceListItem, PostgresServicePasswordResource, PostgresServicePatchRequest, + PostgresServicePostRequest, PostgresServiceReadReplicaRequest, PostgresServiceRestoreRequest, + PostgresServiceSetPassword, PostgresServiceSetState, PostgresServiceSetStateCommand, + PostgresSlowQueryPattern, PostgresSlowQueryPatternDetail, }; impl CloudClient { @@ -483,4 +484,77 @@ impl CloudClient { .await?; Self::unwrap_response(response) } + + /// Get the private endpoint service of a Postgres service. + pub(super) async fn get_postgres_private_endpoint( + &self, + org_id: &str, + postgres_id: &str, + ) -> CloudResult { + let response = self + .convert_postgres_by_id_result( + self.api() + .postgres_private_endpoint_get(org_id, postgres_id) + .await, + org_id, + postgres_id, + ) + .await?; + Self::unwrap_response(response) + } + + /// Create the private endpoint service of a Postgres service. + pub(super) async fn create_postgres_private_endpoint( + &self, + org_id: &str, + postgres_id: &str, + request: &PostgresPrivateEndpointPostRequest, + ) -> CloudResult { + let response = self + .convert_postgres_by_id_result( + self.api() + .postgres_private_endpoint_post(org_id, postgres_id, request) + .await, + org_id, + postgres_id, + ) + .await?; + Self::unwrap_response(response) + } + + /// Replace the approved VPC endpoints or supported regions it is given. + pub(super) async fn update_postgres_private_endpoint( + &self, + org_id: &str, + postgres_id: &str, + request: &PostgresPrivateEndpointPatchRequest, + ) -> CloudResult { + let response = self + .convert_postgres_by_id_result( + self.api() + .postgres_private_endpoint_patch(org_id, postgres_id, request) + .await, + org_id, + postgres_id, + ) + .await?; + Self::unwrap_response(response) + } + + /// Delete the private endpoint service of a Postgres service. + pub(super) async fn delete_postgres_private_endpoint( + &self, + org_id: &str, + postgres_id: &str, + ) -> CloudResult<()> { + self.convert_postgres_by_id_result( + self.api() + .postgres_private_endpoint_delete(org_id, postgres_id) + .await, + org_id, + postgres_id, + ) + .await?; + Ok(()) + } } diff --git a/crates/clickhousectl/src/cloud/postgres/mod.rs b/crates/clickhousectl/src/cloud/postgres/mod.rs index 80289d7e..5c2be7f6 100644 --- a/crates/clickhousectl/src/cloud/postgres/mod.rs +++ b/crates/clickhousectl/src/cloud/postgres/mod.rs @@ -3,6 +3,7 @@ mod client; mod config; mod lifecycle; mod observability; +mod private_endpoint; mod query; mod topology; @@ -111,6 +112,44 @@ pub(super) const PERMISSIONS: &[Permission] = &[ Conditional::flag("name", &[&op::POSTGRES_SERVICE_GET_LIST]), CONFIRM_POSTGRES_SERVICE, ]), + Permission::api( + "postgres private-endpoint get", + &[&op::POSTGRES_PRIVATE_ENDPOINT_GET], + ) + .when(&[ + Conditional::flag("name", &[&op::POSTGRES_SERVICE_GET_LIST]), + CONFIRM_POSTGRES_SERVICE, + ]), + Permission::api( + "postgres private-endpoint create", + &[&op::POSTGRES_PRIVATE_ENDPOINT_POST], + ) + .when(&[ + Conditional::flag("name", &[&op::POSTGRES_SERVICE_GET_LIST]), + CONFIRM_POSTGRES_SERVICE, + ]), + Permission::api( + "postgres private-endpoint update", + &[ + &op::POSTGRES_PRIVATE_ENDPOINT_GET, + &op::POSTGRES_PRIVATE_ENDPOINT_PATCH, + ], + ) + .when(&[ + Conditional::flag("name", &[&op::POSTGRES_SERVICE_GET_LIST]), + CONFIRM_POSTGRES_SERVICE, + ]), + Permission::api( + "postgres private-endpoint delete", + &[ + &op::POSTGRES_PRIVATE_ENDPOINT_GET, + &op::POSTGRES_PRIVATE_ENDPOINT_DELETE, + ], + ) + .when(&[ + Conditional::flag("name", &[&op::POSTGRES_SERVICE_GET_LIST]), + CONFIRM_POSTGRES_SERVICE, + ]), Permission::api("postgres restore", &[&op::POSTGRES_INSTANCE_RESTORE]).when(&[ Conditional::flag("source-name", &[&op::POSTGRES_SERVICE_GET_LIST]), Conditional::new("Reading access rules", &[&op::POSTGRES_SERVICE_GET]), @@ -137,8 +176,8 @@ pub(super) const PERMISSIONS: &[Permission] = &[ ]; pub use cli::{ - CertsCommands, ConfigCommands, PostgresBackupCommands, PostgresCommands, PrometheusCommands, - ReadReplicaCommands, SlowQueryCommands, + CertsCommands, ConfigCommands, PostgresBackupCommands, PostgresCommands, + PrivateEndpointCommands, PrometheusCommands, ReadReplicaCommands, SlowQueryCommands, }; use crate::cloud::client::{CloudClient, Result as CloudResult}; @@ -155,6 +194,10 @@ use observability::{ postgres_logs, postgres_metrics, postgres_prometheus_org, postgres_prometheus_service, postgres_slow_queries_list, postgres_slow_query_get, }; +use private_endpoint::{ + PrivateEndpointUpdate, private_endpoint_create, private_endpoint_delete, private_endpoint_get, + private_endpoint_update, +}; use query::postgres_query; use topology::{ PostgresReadReplicaOptions, PostgresRestoreOptions, PostgresRoleCommand, @@ -441,6 +484,37 @@ pub async fn run(client: &CloudClient, command: PostgresCommands, json: bool) -> let postgres_id = postgres_id.resolve(client, NamedResource::Postgres).await?; postgres_backup_list(client, &postgres_id, cursor.as_deref(), limit, json).await } + PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Get { postgres_id }) => { + let postgres_id = postgres_id.resolve(client, NamedResource::Postgres).await?; + private_endpoint_get(client, &postgres_id, json).await + } + PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Create { + postgres_id, + supported_region, + }) => { + let postgres_id = postgres_id.resolve(client, NamedResource::Postgres).await?; + private_endpoint_create(client, &postgres_id, &supported_region, json).await + } + PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Update { + postgres_id, + add_vpc_endpoint, + remove_vpc_endpoint, + add_region, + remove_region, + }) => { + let postgres_id = postgres_id.resolve(client, NamedResource::Postgres).await?; + let update = PrivateEndpointUpdate { + add_vpc_endpoint: &add_vpc_endpoint, + remove_vpc_endpoint: &remove_vpc_endpoint, + add_region: &add_region, + remove_region: &remove_region, + }; + private_endpoint_update(client, &postgres_id, update, json).await + } + PostgresCommands::PrivateEndpoint(PrivateEndpointCommands::Delete { postgres_id }) => { + let postgres_id = postgres_id.resolve(client, NamedResource::Postgres).await?; + private_endpoint_delete(client, &postgres_id, json).await + } PostgresCommands::Restore { postgres_id, name, diff --git a/crates/clickhousectl/src/cloud/postgres/private_endpoint.rs b/crates/clickhousectl/src/cloud/postgres/private_endpoint.rs new file mode 100644 index 00000000..5b8d97f3 --- /dev/null +++ b/crates/clickhousectl/src/cloud/postgres/private_endpoint.rs @@ -0,0 +1,472 @@ +//! `cloud postgres private-endpoint`: the AWS private endpoint service of a +//! Postgres service. + +use crate::cloud::client::{CloudClient, CloudError, Result as CloudResult}; +use crate::cloud::output::print_human; +use crate::cloud::shared::resolve_org_id; +use clickhouse_cloud_api::models::{ + PostgresPrivateEndpoint, PostgresPrivateEndpointPatchRequest, + PostgresPrivateEndpointPostRequest, PostgresPrivateEndpointVpcEndpoint, +}; + +/// Parse `VPCE_ID[=DESCRIPTION]` for `--add-vpc-endpoint`. +pub(super) fn parse_vpc_endpoint( + value: &str, +) -> Result { + let (id, description) = value + .split_once('=') + .map_or((value, None), |(id, description)| (id, Some(description))); + let id = parse_vpc_endpoint_id(id)?; + if description.is_some_and(|description| description.chars().count() > 255) { + return Err("description must be at most 255 characters".into()); + } + Ok(PostgresPrivateEndpointVpcEndpoint { + vpc_endpoint_id: id, + description: description.map(str::to_string), + }) +} + +/// Parse an AWS VPC endpoint ID: `vpce-` and 17 lowercase hex digits. +fn parse_vpc_endpoint_id(value: &str) -> Result { + let valid = value.strip_prefix("vpce-").is_some_and(|hex| { + hex.len() == 17 + && hex + .bytes() + .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)) + }); + if valid { + Ok(value.to_string()) + } else { + Err("expected a VPC endpoint ID: vpce- and 17 lowercase hex digits".into()) + } +} + +pub(super) fn build_private_endpoint_create_request( + supported_regions: &[String], +) -> PostgresPrivateEndpointPostRequest { + PostgresPrivateEndpointPostRequest { + supported_regions: (!supported_regions.is_empty()).then(|| supported_regions.to_vec()), + } +} + +/// Changes requested by `private-endpoint update`, applied to the current lists. +pub(super) struct PrivateEndpointUpdate<'a> { + pub add_vpc_endpoint: &'a [PostgresPrivateEndpointVpcEndpoint], + pub remove_vpc_endpoint: &'a [String], + pub add_region: &'a [String], + pub remove_region: &'a [String], +} + +/// The patch for `private-endpoint update`, plus a warning for each removal +/// that matched nothing. +#[derive(Debug)] +pub(super) struct PrivateEndpointPatch { + pub request: PostgresPrivateEndpointPatchRequest, + pub warnings: Vec, +} + +/// Merge the requested changes into `current` and return a patch that sends only +/// the lists that change, because each list sent replaces the stored one in full. +/// +/// Removals apply before additions. As with `cloud service update`, removing an +/// entry that is not there is idempotent: it adds a warning instead of failing, +/// so a typo stays visible. Adding an approved VPC endpoint again updates its +/// description when one is given. +pub(super) fn build_private_endpoint_update_request( + current: &PostgresPrivateEndpoint, + update: &PrivateEndpointUpdate<'_>, +) -> CloudResult { + let mut request = PostgresPrivateEndpointPatchRequest::default(); + let mut warnings = Vec::new(); + + if !update.add_vpc_endpoint.is_empty() || !update.remove_vpc_endpoint.is_empty() { + let mut endpoints = current + .allowed_vpc_endpoints + .clone() + .unwrap_or_default() + .into_iter() + .map(PostgresPrivateEndpointVpcEndpoint::try_from) + .collect::, _>>() + .map_err(|missing| { + CloudError::new(format!( + "private endpoint response has an approved VPC endpoint without {}; \ + the list cannot be written back safely", + missing.fields().join(", ") + )) + })?; + for id in update.remove_vpc_endpoint { + let before = endpoints.len(); + endpoints.retain(|endpoint| &endpoint.vpc_endpoint_id != id); + if endpoints.len() == before { + warnings.push(format!( + "--remove-vpc-endpoint {id} did not match any approved VPC endpoint; nothing was removed" + )); + } + } + for added in update.add_vpc_endpoint { + match endpoints + .iter_mut() + .find(|endpoint| endpoint.vpc_endpoint_id == added.vpc_endpoint_id) + { + Some(existing) => { + if added.description.is_some() { + existing.description = added.description.clone(); + } + } + None => endpoints.push(added.clone()), + } + } + request.allowed_vpc_endpoints = Some(endpoints); + } + + if !update.add_region.is_empty() || !update.remove_region.is_empty() { + let mut regions = current.supported_regions.clone().unwrap_or_default(); + for region in update.remove_region { + let before = regions.len(); + regions.retain(|existing| existing != region); + if regions.len() == before { + warnings.push(format!( + "--remove-region {region} did not match any supported region; nothing was removed" + )); + } + } + for region in update.add_region { + if !regions.contains(region) { + regions.push(region.clone()); + } + } + request.supported_regions = Some(regions); + } + + Ok(PrivateEndpointPatch { request, warnings }) +} + +fn print_endpoint(endpoint: &PostgresPrivateEndpoint, json: bool) -> CloudResult<()> { + if json { + println!("{}", serde_json::to_string_pretty(endpoint)?); + } else { + print_human(endpoint)?; + } + Ok(()) +} + +pub(super) async fn private_endpoint_get( + client: &CloudClient, + postgres_id: &str, + json: bool, +) -> CloudResult<()> { + let org_id = resolve_org_id(client).await?; + let endpoint = client + .get_postgres_private_endpoint(&org_id, postgres_id) + .await?; + print_endpoint(&endpoint, json) +} + +pub(super) async fn private_endpoint_create( + client: &CloudClient, + postgres_id: &str, + supported_regions: &[String], + json: bool, +) -> CloudResult<()> { + let org_id = resolve_org_id(client).await?; + let request = build_private_endpoint_create_request(supported_regions); + let endpoint = client + .create_postgres_private_endpoint(&org_id, postgres_id, &request) + .await?; + print_endpoint(&endpoint, json)?; + if !json { + println!( + "Next: clickhousectl cloud postgres private-endpoint get {postgres_id} \ + (wait for state=available, about 5 to 10 minutes)" + ); + } + Ok(()) +} + +pub(super) async fn private_endpoint_update( + client: &CloudClient, + postgres_id: &str, + update: PrivateEndpointUpdate<'_>, + json: bool, +) -> CloudResult<()> { + let org_id = resolve_org_id(client).await?; + let current = client + .get_postgres_private_endpoint(&org_id, postgres_id) + .await?; + let patch = build_private_endpoint_update_request(¤t, &update)?; + for warning in &patch.warnings { + eprintln!("Warning: {warning}"); + } + let endpoint = client + .update_postgres_private_endpoint(&org_id, postgres_id, &patch.request) + .await?; + print_endpoint(&endpoint, json) +} + +pub(super) async fn private_endpoint_delete( + client: &CloudClient, + postgres_id: &str, + json: bool, +) -> CloudResult<()> { + let org_id = resolve_org_id(client).await?; + // The delete response has no `result`; print the endpoint read beforehand, + // as `cloud postgres delete` does for the service. + let endpoint = client + .get_postgres_private_endpoint(&org_id, postgres_id) + .await?; + client + .delete_postgres_private_endpoint(&org_id, postgres_id) + .await?; + if json { + println!("{}", serde_json::to_string_pretty(&endpoint)?); + } else { + println!("Private endpoint of Postgres service {postgres_id} deleted"); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use clickhouse_cloud_api::models::PostgresPrivateEndpointVpcEndpointResponse; + + const VPCE_A: &str = "vpce-0123456789abcdef0"; + const VPCE_B: &str = "vpce-0123456789abcdef1"; + + fn vpce(id: &str, description: Option<&str>) -> PostgresPrivateEndpointVpcEndpoint { + PostgresPrivateEndpointVpcEndpoint { + vpc_endpoint_id: id.into(), + description: description.map(str::to_string), + } + } + + fn current() -> PostgresPrivateEndpoint { + PostgresPrivateEndpoint { + allowed_vpc_endpoints: Some(vec![PostgresPrivateEndpointVpcEndpointResponse { + vpc_endpoint_id: Some(VPCE_A.into()), + description: Some("prod".into()), + }]), + supported_regions: Some(vec!["us-west-2".into()]), + ..Default::default() + } + } + + fn no_change() -> PrivateEndpointUpdate<'static> { + PrivateEndpointUpdate { + add_vpc_endpoint: &[], + remove_vpc_endpoint: &[], + add_region: &[], + remove_region: &[], + } + } + + #[test] + fn vpc_endpoint_parser_accepts_id_and_optional_description() { + assert_eq!(parse_vpc_endpoint(VPCE_A).unwrap(), vpce(VPCE_A, None)); + assert_eq!( + parse_vpc_endpoint(&format!("{VPCE_A}=Production VPC")).unwrap(), + vpce(VPCE_A, Some("Production VPC")) + ); + assert_eq!( + parse_vpc_endpoint(&format!("{VPCE_A}=")).unwrap(), + vpce(VPCE_A, Some("")) + ); + for invalid in [ + "vpce-0123456789ABCDEF0", + "vpce-0123456789abcdef", + "vpce-0123456789abcdef00", + "0123456789abcdef0", + "", + ] { + assert!(parse_vpc_endpoint(invalid).is_err(), "{invalid}"); + } + assert!(parse_vpc_endpoint(&format!("{VPCE_A}={}", "x".repeat(256))).is_err()); + assert!(parse_vpc_endpoint(&format!("{VPCE_A}={}", "x".repeat(255))).is_ok()); + } + + #[test] + fn create_request_omits_regions_unless_given() { + assert_eq!( + build_private_endpoint_create_request(&[]).supported_regions, + None + ); + assert_eq!( + build_private_endpoint_create_request(&["us-west-2".into(), "eu-west-1".into()]) + .supported_regions, + Some(vec!["us-west-2".into(), "eu-west-1".into()]) + ); + } + + #[test] + fn update_sends_only_the_lists_that_change() { + let add = [vpce(VPCE_B, None)]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + add_vpc_endpoint: &add, + ..no_change() + }, + ) + .unwrap() + .request; + // The existing approval and its description are written back. + assert_eq!( + request.allowed_vpc_endpoints, + Some(vec![vpce(VPCE_A, Some("prod")), vpce(VPCE_B, None)]) + ); + assert_eq!(request.supported_regions, None); + + let regions = ["eu-west-1".to_string()]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + add_region: ®ions, + ..no_change() + }, + ) + .unwrap() + .request; + assert_eq!(request.allowed_vpc_endpoints, None); + assert_eq!( + request.supported_regions, + Some(vec!["us-west-2".into(), "eu-west-1".into()]) + ); + } + + #[test] + fn update_removes_before_adding_and_can_empty_a_list() { + let remove = [VPCE_A.to_string()]; + let remove_region = ["us-west-2".to_string()]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + remove_vpc_endpoint: &remove, + remove_region: &remove_region, + ..no_change() + }, + ) + .unwrap() + .request; + assert_eq!(request.allowed_vpc_endpoints, Some(vec![])); + assert_eq!(request.supported_regions, Some(vec![])); + + // Removing and re-adding replaces the description with the new one. + let add = [vpce(VPCE_A, None)]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + add_vpc_endpoint: &add, + remove_vpc_endpoint: &remove, + ..no_change() + }, + ) + .unwrap() + .request; + assert_eq!( + request.allowed_vpc_endpoints, + Some(vec![vpce(VPCE_A, None)]) + ); + } + + #[test] + fn update_re_adding_an_approval_keeps_or_replaces_its_description() { + let keep = [vpce(VPCE_A, None)]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + add_vpc_endpoint: &keep, + ..no_change() + }, + ) + .unwrap() + .request; + assert_eq!( + request.allowed_vpc_endpoints, + Some(vec![vpce(VPCE_A, Some("prod"))]) + ); + + let relabel = [vpce(VPCE_A, Some("staging"))]; + let request = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + add_vpc_endpoint: &relabel, + ..no_change() + }, + ) + .unwrap() + .request; + assert_eq!( + request.allowed_vpc_endpoints, + Some(vec![vpce(VPCE_A, Some("staging"))]) + ); + } + + #[test] + fn update_warns_when_a_removal_matches_nothing() { + let remove = [VPCE_B.to_string()]; + let remove_region = ["ap-south-1".to_string()]; + let patch = build_private_endpoint_update_request( + ¤t(), + &PrivateEndpointUpdate { + remove_vpc_endpoint: &remove, + remove_region: &remove_region, + ..no_change() + }, + ) + .unwrap(); + // The unchanged lists are still sent, so the request stays idempotent. + assert_eq!( + patch.request.allowed_vpc_endpoints, + Some(vec![vpce(VPCE_A, Some("prod"))]) + ); + assert_eq!( + patch.request.supported_regions, + Some(vec!["us-west-2".into()]) + ); + assert_eq!(patch.warnings.len(), 2); + assert!( + patch.warnings[0].contains("--remove-vpc-endpoint") + && patch.warnings[0].contains(VPCE_B) + ); + assert!( + patch.warnings[1].contains("--remove-region") + && patch.warnings[1].contains("ap-south-1") + ); + } + + #[test] + fn update_refuses_to_write_back_an_approval_without_an_id() { + let mut current = current(); + current.allowed_vpc_endpoints = Some(vec![PostgresPrivateEndpointVpcEndpointResponse { + vpc_endpoint_id: None, + description: Some("mystery".into()), + }]); + let add = [vpce(VPCE_B, None)]; + let error = build_private_endpoint_update_request( + ¤t, + &PrivateEndpointUpdate { + add_vpc_endpoint: &add, + ..no_change() + }, + ) + .unwrap_err(); + assert!(!matches!( + error.kind, + crate::cloud::client::CloudErrorKind::Usage + )); + assert!(error.message.contains("vpcEndpointId")); + + // Region-only changes never touch the approval list. + let regions = ["eu-west-1".to_string()]; + assert!( + build_private_endpoint_update_request( + ¤t, + &PrivateEndpointUpdate { + add_region: ®ions, + ..no_change() + }, + ) + .is_ok() + ); + } +} diff --git a/crates/clickhousectl/tests/cloud/postgres.rs b/crates/clickhousectl/tests/cloud/postgres.rs index 291269e5..1b6115b5 100644 --- a/crates/clickhousectl/tests/cloud/postgres.rs +++ b/crates/clickhousectl/tests/cloud/postgres.rs @@ -3162,3 +3162,152 @@ async fn postgres_backup_list_sends_pagination_and_renders_json_and_table() { assert!(stdout.contains(expected), "missing {expected}: {stdout}"); } } + +// ── Postgres private endpoint (issue #1485) ─────────────────────────────── + +const PG_PRIVATE_ENDPOINT_PATH: &str = "/v1/organizations/org-1/postgres/pg-1/privateEndpoint"; + +fn private_endpoint_envelope(result: Value) -> ResponseTemplate { + ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "status": 200, "requestId": "stub-pg-private-endpoint", "result": result + })) +} + +fn approved_endpoint() -> Value { + serde_json::json!({ + "id": "ps-1", + "state": "available", + "endpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0", + "supportedRegions": ["us-west-2"], + "allowedVpcEndpoints": [ + {"vpcEndpointId": "vpce-0123456789abcdef0", "description": "prod"} + ] + }) +} + +#[tokio::test] +async fn postgres_private_endpoint_create_sends_regions() { + let mock = MockServer::start().await; + Mock::given(method("POST")) + .and(path(PG_PRIVATE_ENDPOINT_PATH)) + .and(body_json( + serde_json::json!({"supportedRegions": ["us-west-2"]}), + )) + .respond_with(private_endpoint_envelope( + serde_json::json!({"id": "ps-1", "state": "creating"}), + )) + .expect(1) + .mount(&mock) + .await; + + let output = invoke_cli_with_cloud_credentials( + &mock, + &[ + "postgres", + "private-endpoint", + "create", + "pg-1", + "--supported-region", + "us-west-2", + "--org-id", + "org-1", + ], + ); + assert_success(&output); + let endpoint: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(endpoint["state"], "creating"); +} + +/// The PATCH replaces each list in full, so update reads the endpoint first and +/// writes back the approvals it keeps; regions it was not asked to change are +/// not sent. +#[tokio::test] +async fn postgres_private_endpoint_update_merges_into_the_current_approvals() { + let mock = MockServer::start().await; + Mock::given(method("GET")) + .and(path(PG_PRIVATE_ENDPOINT_PATH)) + .respond_with(private_endpoint_envelope(approved_endpoint())) + .expect(1) + .mount(&mock) + .await; + Mock::given(method("PATCH")) + .and(path(PG_PRIVATE_ENDPOINT_PATH)) + .and(body_json(serde_json::json!({ + "allowedVpcEndpoints": [ + {"vpcEndpointId": "vpce-0123456789abcdef0", "description": "prod"}, + {"vpcEndpointId": "vpce-0123456789abcdef1", "description": "staging"} + ] + }))) + .respond_with(private_endpoint_envelope(approved_endpoint())) + .expect(1) + .mount(&mock) + .await; + + let output = invoke_cli_with_cloud_credentials( + &mock, + &[ + "postgres", + "private-endpoint", + "update", + "pg-1", + "--add-vpc-endpoint", + "vpce-0123456789abcdef1=staging", + "--remove-vpc-endpoint", + "vpce-00000000000000000", + "--org-id", + "org-1", + ], + ); + assert_success(&output); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(stderr.contains("vpce-00000000000000000"), "{stderr}"); + assert_eq!( + received_request_shape(&mock).await, + vec![ + ("GET".to_string(), PG_PRIVATE_ENDPOINT_PATH.to_string()), + ("PATCH".to_string(), PG_PRIVATE_ENDPOINT_PATH.to_string()), + ] + ); +} + +/// Delete returns no `result`, so the command prints the endpoint it read first. +#[tokio::test] +async fn postgres_private_endpoint_delete_prints_the_deleted_endpoint() { + let mock = MockServer::start().await; + Mock::given(method("GET")) + .and(path(PG_PRIVATE_ENDPOINT_PATH)) + .respond_with(private_endpoint_envelope(approved_endpoint())) + .expect(1) + .mount(&mock) + .await; + Mock::given(method("DELETE")) + .and(path(PG_PRIVATE_ENDPOINT_PATH)) + .respond_with(successful_delete_response( + "stub-pg-private-endpoint-delete", + )) + .expect(1) + .mount(&mock) + .await; + + let output = invoke_cli_with_cloud_credentials( + &mock, + &[ + "postgres", + "private-endpoint", + "delete", + "pg-1", + "--org-id", + "org-1", + ], + ); + assert_success(&output); + let endpoint: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(endpoint["id"], "ps-1"); + assert_eq!( + received_request_shape(&mock).await, + vec![ + ("GET".to_string(), PG_PRIVATE_ENDPOINT_PATH.to_string()), + ("DELETE".to_string(), PG_PRIVATE_ENDPOINT_PATH.to_string()), + ] + ); +} diff --git a/docs/guides/managed-postgres.md b/docs/guides/managed-postgres.md index 23532cf1..eb96b249 100644 --- a/docs/guides/managed-postgres.md +++ b/docs/guides/managed-postgres.md @@ -46,6 +46,24 @@ clickhousectl cloud postgres update \ A rule update can partially succeed. After a failure, run `get` and compare the rules before retrying, so a retry does not repeat a change that already applied. +## Connect privately over AWS PrivateLink (Beta) + +An AWS Postgres service can have a private endpoint service, in organizations with private endpoints enabled. Creating it takes about 5 to 10 minutes; `get` shows `state: creating` until it is `available` and then shows `endpointServiceName`: + +```bash +clickhousectl cloud postgres private-endpoint create +clickhousectl cloud postgres private-endpoint get +``` + +Create an interface VPC endpoint in your AWS account with `endpointServiceName` as its service name. **It cannot connect until you approve its ID.** Then connect to `privateHostname` from that VPC: + +```bash +clickhousectl cloud postgres private-endpoint update \ + --add-vpc-endpoint 'vpce-0123456789abcdef0=Production VPC' +``` + +`--remove-vpc-endpoint ` revokes an approval, and `--add-region`/`--remove-region` change the other AWS regions that may connect, which needs cross-region private endpoints. Each flag changes only what it names; the other approvals and regions stay. `private-endpoint delete` stops every connection through it, and a new endpoint service has a new name, so VPC endpoints must be recreated. + ## Run read-only SQL with OAuth This route needs no database password or local `psql`, but accepts **only OAuth**. Remove higher-priority key flags, project credentials, environment variables, and `.env` key values before logging in. Clearing the credentials file does not delete keys in the organization; see [authentication](../reference/authentication.md).