[localnet] Add support for using existing Docker network (#18079)

Author: banool

crates/aptos/CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to the Aptos CLI will be captured in this file. This project
 
 # Unreleased
 - When using `--bind-to 0.0.0.0`, clients created by the localnet will try to connect at 127.0.0.1, not 0.0.0.0.
+- Add `--docker-network` flag to allow specifying existing Docker network.
 
 ## [7.10.2]
 - Fix backward compatibility issue of enum-based option module

crates/aptos/src/node/local_testnet/docker.rs

@@ -111,6 +111,20 @@ pub async fn pull_docker_image(image_name: &str) -> Result<()> {
 }
 
 /// Create a network. If the network already exists, that's fine, just move on.
+/// Check if a Docker network exists.
+pub async fn network_exists(network_name: &str) -> Result<bool> {
+    let docker = get_docker().await?;
+
+    // Try to inspect the network. If it exists, this will succeed.
+    match docker.inspect_network::<&str>(network_name, None).await {
+        Ok(_) => Ok(true),
+        Err(BollardError::DockerResponseServerError {
+            status_code: 404, ..
+        }) => Ok(false),
+        Err(err) => Err(err.into()),
+    }
+}
+
 pub async fn create_network(network_name: &str) -> Result<()> {
     let docker = get_docker().await?;
 

crates/aptos/src/node/local_testnet/indexer_api.rs

@@ -4,7 +4,7 @@
 use super::{
     docker::{
         delete_container, get_docker, pull_docker_image, setup_docker_logging,
-        StopContainerShutdownStep, CONTAINER_NETWORK_NAME,
+        StopContainerShutdownStep,
     },
     health_checker::HealthChecker,
     traits::{PostHealthyStep, ServiceManager, ShutdownStep},
@@ -70,6 +70,7 @@ pub struct IndexerApiManager {
     prerequisite_health_checkers: HashSet<HealthChecker>,
     test_dir: PathBuf,
     postgres_connection_string: String,
+    docker_network: String,
 }
 
 impl IndexerApiManager {
@@ -79,13 +80,15 @@ impl IndexerApiManager {
         test_dir: PathBuf,
         postgres_connection_string: String,
     ) -> Result<Self> {
+        let (docker_network, _) = args.get_docker_network();
         Ok(Self {
             indexer_api_port: args.indexer_api_args.indexer_api_port,
             existing_hasura_url: args.indexer_api_args.existing_hasura_url.clone(),
             skip_metadata_apply: args.indexer_api_args.skip_metadata_apply,
             prerequisite_health_checkers,
             test_dir,
             postgres_connection_string,
+            docker_network: docker_network.to_string(),
         })
     }
 
@@ -188,7 +191,7 @@ impl ServiceManager for IndexerApiManager {
                 // in the Postgres pre_run steps.
                 (
                     self.postgres_connection_string,
-                    Some(CONTAINER_NETWORK_NAME.to_string()),
+                    Some(self.docker_network.clone()),
                 )
             };
 

crates/aptos/src/node/local_testnet/mod.rs

@@ -105,9 +105,26 @@ pub struct RunLocalnet {
     /// By default, tracing output goes to files. With this set, it goes to stdout.
     #[clap(long, hide = true)]
     log_to_stdout: bool,
+
+    /// If set, use an existing Docker network instead of creating a new one.
+    ///
+    /// When specified, the CLI will verify that this network exists and use it for all
+    /// Docker containers in the localnet. If not specified, a network named
+    /// "aptos-local-testnet-network" will be created automatically.
+    #[clap(long)]
+    docker_network: Option<String>,
 }
 
 impl RunLocalnet {
+    /// Get the Docker network name to use for containers and whether it already exists.
+    /// We assume if the user provided a network name that it exists.
+    pub fn get_docker_network(&self) -> (&str, bool) {
+        match self.docker_network {
+            Some(ref network_name) => (network_name, true),
+            None => (docker::CONTAINER_NETWORK_NAME, false),
+        }
+    }
+
     /// Wait for many services to start up. This prints a message like "X is starting,
     /// please wait..." for each service and then "X is ready. Endpoint: <url>"
     /// when it's ready.
@@ -192,6 +209,29 @@ impl CliCommand<()> for RunLocalnet {
             setup_logging(None);
         }
 
+        if !self.indexer_api_args.with_indexer_api && self.docker_network.is_some() {
+            return Err(CliError::UnexpectedError(
+                "You cannot specify --docker-network without --with-indexer-api, Docker is only used when --with-indexer-api is set.".to_string(),
+            ));
+        }
+
+        // If a custom Docker network is specified, verify that it exists. We only need
+        // to do this if the indexer API is being run, otherwise we don't use Docker.
+        if let Some(ref network_name) = self.docker_network {
+            if !docker::network_exists(network_name).await.map_err(|e| {
+                CliError::UnexpectedError(format!(
+                    "Failed to check if Docker network exists: {}",
+                    e
+                ))
+            })? {
+                return Err(CliError::UnexpectedError(format!(
+                "Docker network '{}' does not exist. Please create it first or omit --docker-network to use the default network.",
+                network_name
+            )));
+            }
+            info!("Using existing Docker network: {}", network_name);
+        }
+
         // Based on the input and global config, get the test directory.
         let test_dir = get_derived_test_dir(&self.test_dir)?;
 

crates/aptos/src/node/local_testnet/postgres.rs

@@ -4,7 +4,7 @@
 use super::{
     docker::{
         create_network, create_volume, delete_container, delete_volume, get_docker,
-        pull_docker_image, setup_docker_logging, StopContainerShutdownStep, CONTAINER_NETWORK_NAME,
+        pull_docker_image, setup_docker_logging, StopContainerShutdownStep,
     },
     health_checker::HealthChecker,
     traits::{ServiceManager, ShutdownStep},
@@ -121,6 +121,8 @@ pub struct PostgresManager {
     args: PostgresArgs,
     test_dir: PathBuf,
     force_restart: bool,
+    docker_network: String,
+    docker_network_already_exists: bool,
 }
 
 impl PostgresManager {
@@ -130,10 +132,13 @@ impl PostgresManager {
         {
             bail!("The postgres database cannot be named postgres if --use-host-postgres is set");
         }
+        let (docker_network, docker_network_already_exists) = args.get_docker_network();
         Ok(Self {
             args: args.postgres_args.clone(),
             test_dir,
             force_restart: args.force_restart,
+            docker_network: docker_network.to_string(),
+            docker_network_already_exists,
         })
     }
 
@@ -192,8 +197,11 @@ impl ServiceManager for PostgresManager {
             // `run_service`.
             pull_docker_image(POSTGRES_IMAGE).await?;
 
-            // Create a network for the containers to talk to each other.
-            create_network(CONTAINER_NETWORK_NAME).await?;
+            // Create a network for the containers to talk to each other if a
+            // pre-existing network was not specified.
+            if !self.docker_network_already_exists {
+                create_network(&self.docker_network).await?;
+            }
         }
 
         Ok(())
@@ -243,7 +251,7 @@ impl ServiceManager for PostgresManager {
             // Bind the container to the network we created in the pre_run. This does
             // not prevent the binary in the container from exposing itself to the host
             // on 127.0.0.1. See more here: https://stackoverflow.com/a/77432636/3846032.
-            network_mode: Some(CONTAINER_NETWORK_NAME.to_string()),
+            network_mode: Some(self.docker_network.clone()),
             port_bindings: Some(hashmap! {
                 POSTGRES_DEFAULT_PORT.to_string() => Some(vec![PortBinding {
                     host_ip: Some("127.0.0.1".to_string()),