From cc74138f8a5a5433d797eeb1ae06fea34990bcf9 Mon Sep 17 00:00:00 2001 From: gluax <16431709+gluax@users.noreply.github.com> Date: Sun, 25 Aug 2024 15:13:58 -0700 Subject: [PATCH 1/7] refactor: non optional agent id, cli env for agent endpoint --- Cargo.toml | 2 +- crates/snops-agent/src/cli.rs | 11 +++++------ crates/snops/src/server/mod.rs | 2 +- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 2bbf6c66..7c22e4f0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -53,7 +53,7 @@ bincode = "1.3" bytes = "1.6" checkpoint = { path = "./crates/checkpoint" } chrono = { version = "0.4", features = ["now"], default-features = false } -clap = { version = "4.5", features = ["derive"] } +clap = { version = "4.5", features = ["derive", "env"] } clap_complete = { version = "4.5" } clap_mangen = { version = "0.2" } clap-markdown = "0.1" diff --git a/crates/snops-agent/src/cli.rs b/crates/snops-agent/src/cli.rs index 57681511..d45ac250 100644 --- a/crates/snops-agent/src/cli.rs +++ b/crates/snops-agent/src/cli.rs @@ -18,12 +18,13 @@ pub const ENV_ENDPOINT_DEFAULT: &str = "127.0.0.1:1234"; #[derive(Debug, Parser)] pub struct Cli { - #[arg(long)] + #[arg(long, env = ENV_ENDPOINT)] /// Control plane endpoint address (IP, or wss://host, http://host) pub endpoint: Option, + /// Agent ID, used to identify the agent in the network. #[arg(long)] - pub id: Option, + pub id: AgentId, /// Locally provided private key file, used for envs where private keys are /// locally provided @@ -31,6 +32,7 @@ pub struct Cli { #[clap(long = "private-key-file")] pub private_key_file: Option, + /// Labels to attach to the agent, used for filtering and grouping. #[arg(long, value_delimiter = ',', num_args = 1..)] pub labels: Option>, @@ -103,15 +105,12 @@ impl Cli { .endpoint .as_ref() .cloned() - .or_else(|| env::var(ENV_ENDPOINT).ok()) .unwrap_or(ENV_ENDPOINT_DEFAULT.to_owned()); let mut query = format!("/agent?mode={}", u8::from(self.modes)); // add &id= - if let Some(id) = self.id { - query.push_str(&format!("&id={}", id)); - } + query.push_str(&format!("&id={}", self.id)); // add local pk flag if let Some(file) = self.private_key_file.as_ref() { diff --git a/crates/snops/src/server/mod.rs b/crates/snops/src/server/mod.rs index ee34dc42..a7629374 100644 --- a/crates/snops/src/server/mod.rs +++ b/crates/snops/src/server/mod.rs @@ -209,7 +209,7 @@ async fn handle_socket( // unwrap safety: this agent was just `mark_connected` with a valid client let client = agent.rpc().cloned().unwrap(); - // drop agent ref to allow for mutable borrow in handhake requests + // drop agent ref to allow for mutable borrow in handshake requests drop(agent); tokio::spawn(async move { From d466ac247ae731d68d47cd3f560e3f270fb50ada Mon Sep 17 00:00:00 2001 From: gluax <16431709+gluax@users.noreply.github.com> Date: Sun, 25 Aug 2024 15:14:27 -0700 Subject: [PATCH 2/7] docs(wip): running readme updated, agent running in depth guide --- snops_book/architecture/README.md | 2 +- snops_book/glossary/IDs.md | 0 snops_book/user_guide/running/AGENT.md | 112 ++++++++++++++++++++++++ snops_book/user_guide/running/README.md | 20 ++++- 4 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 snops_book/glossary/IDs.md diff --git a/snops_book/architecture/README.md b/snops_book/architecture/README.md index 295e3eed..50f01915 100644 --- a/snops_book/architecture/README.md +++ b/snops_book/architecture/README.md @@ -1,6 +1,6 @@ # Architecture -A snops "instance" is composed of multiple parts: +A `snops` "instance" is composed of multiple parts: - A Control Plane - Agents diff --git a/snops_book/glossary/IDs.md b/snops_book/glossary/IDs.md new file mode 100644 index 00000000..e69de29b diff --git a/snops_book/user_guide/running/AGENT.md b/snops_book/user_guide/running/AGENT.md index 874dfe78..3f2081b2 100644 --- a/snops_book/user_guide/running/AGENT.md +++ b/snops_book/user_guide/running/AGENT.md @@ -1,3 +1,115 @@ # Agent +The binary has several options you can run mess with at launch and some are required that we will go over here. + +However, for a more in depth information you can read about the CLI options [here](../clis/SNOPS_AGENT.md). + +## Running the Agent + +The `agent` can be run on the same machine as the control plane or a separate one. + +Depending on the [environment](../envs/README.md) you specified, you will need the number agents listed in it, unless they are external. + +## How it works + +The `agent` once running will connect to the control plane. If the control plane goes/offline or isn't online yet that's okay! The `agent` will continuously try to reconnect to the control plane endpoint provided. + +For running `snarkOS` the `agent` will download that binary from the `control plane`. + +## Updating + +You don't have to worry about updating the individual agents. + +The control plane will serve the updated `agent` binary to them once there is an update. + +## Startup Options + +The options for starting up an `agent`. + +### _endpoint_ + +Is a optional argument that can be provided via the CLI or the `SNOPS_ENDPOINT` environment variable. + +> NOTE: If both the CLI flag and the ENV variable are present, the ENV variable takes precedence over the CLI flag. + +If not provided it will default to `127.0.0.1:1234`. + +This is the endpoint of the `Control Plane`. + +If you want it to be a secure connection please specify `https://` or `wss://` at the beginning of the endpoint or it will default to `http` and `ws`. + +### _id_ + +The field where you can give this agent a specific ID, so it is identifiable within the `snops` ecosystem. + +### _labels_ + +Optional comma separated list of labels you can apply to the agent, which are used for filtering and grouping. + +### private-key-file + +An optional private key file. If provided is used when starting `snarkOS`. + +### path + +Optional path to the directory containing the stored data and configuration for the agent. + +By default it is `snops-data` local to where the agent was run from. + +### external + TODO + +### internal + +TODO + +### bind_addr + +The optional address to bind to when running. + +Defaults to `0.0.0.0`. + +### node + +Optional port for the `snarkOS` node server to run on. + +Defaults to `4130`. + +### bft + +Optional port for the `snarkOS` BFT to run on. + +Defaults to `5000`. + +### rest + +Optional port for the `snarkOS` REST API to run on. + +Defaults to `3030`. + +### metrics + +Optional port for the `snarkOS` metrics to run on. + +Defaults to `9000`. + +### validator + +Enables `validator` mode as an option for the agent's `snarkOS` node. + +### prover + +Enables `prover` mode as an option for the agent's `snarkOS` node. + +### client + +Enables `client` mode as an option for the agent's `snarkOS` node. + +### compute + +Enables `compute` mode as an option for the agent to be able to run transactions fired from within `snops`. + +### quiet + +Run the agent in quiet mode which prevents `snarkOS` node output. \ No newline at end of file diff --git a/snops_book/user_guide/running/README.md b/snops_book/user_guide/running/README.md index eddc761e..77a32e27 100644 --- a/snops_book/user_guide/running/README.md +++ b/snops_book/user_guide/running/README.md @@ -1,6 +1,22 @@ # Running -TODO move to appropiate place and update +This section is dedicated to running the different components of `snops`. + +To run an [environment](../envs/README.md) with snops it requires having two elements deployed, and 3 binaries compiled/built. + +The two binaries that need to be deployed are: +- [The Control Plane](./CONTROL_PLANE.md) +- [Agent(s)](./AGENT.md) + - You will likely want more than one instance of an agent. + +The last binary that needs to be compiled is the `snarkos-aot` binary, that wraps around [snarkOS](https://github.com/AleoNet/snarkOS) importing it as a library. + +Additionally you can enable [metrics and logging](./METRICS_AND_LOGGING.md), to better track all information in `snops`: +- Logs from control plane. +- Logs from the agents. +- Metrics and logs from `snarkOS`. + + - +