Add Zombienet tutorial (#12)

* add: zombienet initial structure * add: zombienet introduction * fix: adding padding for tabbed elements * fix: updating installation paths * fix: updating native installation as well as adding nix installation steps * fix: adding docker installation steps * fix: removing custom virtual env name * fix: complementing docker docs * fix: nix installation command updated * add: kubernetes req and features * add: podman req and features * add: native provider req and feats * fix: complementing features on native provider * fix: adding cli commands * fix: adding final argument to cli commands * fix: adding flags to cli docs * fix: updating commands table positions * fix: formatting + adding minimal examples for settings and relaychain * fix: adding nodes key to relachain params * fix: adding node_groups subkey to relaychain settings * fix: indent + json example for node_groups clarification * fix: wrapping up para params and adding hrmp channels params * add: testing section * fix: grammar and typos * fix: updating testing section * fix: updating indents on assertions section * fix: updating indents on commands section * fix: updating indents on base-example.json * fix: relaychain-example-node-groups.json indents * fix: redundant explanation on prometheus_prefix param definition * fix: updating visuals on providers * add: tutorials wip * fix: replacing all typos on target _blank * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * fix: zombienet installation paraphrasing * fix: paraphrasing nix installation intro * fix: updating grammar on providers intro * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * fix: paraphrasing overused of 'the following section' * fix: making cli commands explanations more straightforward * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/index.md Co-authored-by: 0xLucca <[email protected]> * fix: clarifying regarding spawn command warning * fic: removing period at the end of note + formatting * fix: adding new nav structure * fix: removing duplicated table * fix: making testing section visible * fix: updating incomplete link * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * fix: updating title for zombienet page * fix: rephrasing zombienet intro * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/testing.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/testing.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/testing.md Co-authored-by: albertov19 <[email protected]> * Update docs/dev-tools/zombienet/overview.md Co-authored-by: albertov19 <[email protected]> * fix: updating dev-tools index description * fix: adding snippets about how to choose an specific provider when spawning a net * fix: adding further explanations on native requirements * fix: adding generic command before explaning cli usage in deep * fix: updating parachain title * fix: updating XCM title * fix: paraphrasing XCM section intro * fix: paraphrasing relay chain configs intro * fix: adding metrics further explanation on testing section * fix: updating testing assertions and commands to improve look and field * fix: paraphrasing some ideas on testing section * fix: paraprasing overview section * fix: adding wip to title * fix: title wording * fix: removing wip label * fix: updating wording on arguments table * fix: updating nav navigation * fix: replacing native provider instances by local * fix: removing wip label on testing page * fix: removing notes and warning inside tabbed sections * fix: breaking down tabbed providers into sections (h4) * fix:: formatting over toml example * fix: removing unnecessary double parenthesis on single parachain definition * fix: removing unnecessary empty spaces * fix: adding termynal output on zombienet minimal example * fix: adding input to termynal element * fix: paraphrasing note to run the network * fix: paraphrasing on #Defining the network section * fix: adding interacting with the network section * fix: finishing minimal example docs * fix: removing extra examples just for now * fix: removing extra tutorials from nav tab JFN * fix: adding index and updating .pages on tutorials folder * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: 0xLucca <[email protected]> * Update docs/dev-tools/zombienet/tutorials/index.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/index.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * fix: removing empty space * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Dawn Kelly <[email protected]> * fix: updating prometheus image on zombienet tutorial * fix: updating minimal test file * fix: adding missing line return * Update docs/dev-tools/zombienet/tutorials/index.md Co-authored-by: Erin Shaben <[email protected]> * Update docs/dev-tools/zombienet/tutorials/index.md Co-authored-by: Erin Shaben <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Erin Shaben <[email protected]> * fix: adding introduction to zombienet tutorial * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Erin Shaben <[email protected]> * fix: replacing word runtime by provider for clarity * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Erin Shaben <[email protected]> * Update docs/dev-tools/zombienet/tutorials/minimal-example.md Co-authored-by: Erin Shaben <[email protected]> * add custom styling to make the terminal table look good (#21) * fix: renaming tutorial to a more accurate name * fix: adding \ to blank instances * fix: updating prometheus screenshot --------- Co-authored-by: 0xLucca <[email protected]> Co-authored-by: albertov19 <[email protected]> Co-authored-by: Dawn Kelly <[email protected]> Co-authored-by: Erin Shaben <[email protected]>
papermoonio · Aug 13, 2024 · 7f4946a · 7f4946a
1 parent 5e59f0b
commit 7f4946a
Show file tree

Hide file tree

Showing 7 changed files with 264 additions and 1 deletion.
diff --git a/docs/dev-tools/zombienet/.pages b/docs/dev-tools/zombienet/.pages
@@ -2,4 +2,5 @@ title: Zombienet
 nav:
 - index.md
 - 'Overview': 'overview.md'
-- 'Testing': 'testing.md'
+- 'Testing': 'testing.md'
+- tutorials
diff --git a/docs/dev-tools/zombienet/overview.md b/docs/dev-tools/zombienet/overview.md
@@ -72,6 +72,12 @@ In order to install Zombienet, there are multiple options available, depending o
     zombienet version
     ```
 
+    So then, you can refer to the `zombienet` executable directly:
+
+    ```bash
+    zombienet version
+    ```
+
 === "Using Nix"
 
     For Nix users, the Zombienet repository provides a [`flake.nix`](https://github.com/paritytech/zombienet/blob/main/flake.nix){target=_blank} file that can be used to install Zombienet. This means that users can easily incorporate Zombienet into their Nix-based projects. 
@@ -143,6 +149,8 @@ provider = "INSERT_PROVIDER"
 ...
 ```
 
+At the moment, Zombienet supports the following providers: `kubernetes`, `podman`, and `native`.
+
 It's important to note that each provider has specific requirements and associated features. The subsequent sections will guide you through the installation process for each provider and the requirements and features each provider offers.
 
 ### Kubernetes

diff --git a/docs/dev-tools/zombienet/tutorials/.pages b/docs/dev-tools/zombienet/tutorials/.pages
@@ -0,0 +1,4 @@
+title: Tutorials
+nav:
+  - 'index.md'
+  - 'Spawn a Basic Network' : 'spawn-a-basic-network.md'
diff --git a/docs/dev-tools/zombienet/tutorials/index.md b/docs/dev-tools/zombienet/tutorials/index.md
@@ -0,0 +1,7 @@
+---
+title: Zombienet Tutorials
+description: A collection of tutorials for how to use the Zombienet testing framework, designed for Polkadot SDK-based blockchains, to spawn and test ephemeral networks.
+template: subsection-index-page.html
+hide:
+  - feedback
+---
diff --git a/docs/dev-tools/zombienet/tutorials/spawn-a-basic-network.md b/docs/dev-tools/zombienet/tutorials/spawn-a-basic-network.md
@@ -0,0 +1,237 @@
+---
+title: Spawn a Basic Network Using Zombienet
+description: This tutorial gets you started with Zombienet by providing a minimal example of how to use Zombienet to spawn a basic network and run a simple test over it.
+---
+
+# Spawn a Basic Network
+
+## Introduction
+
+In this tutorial, you'll learn how to set up a basic network using Zombienet and run a simple test to validate its functionality. The example provided walks you through defining a minimal network configuration, spawning the network, and interacting with the nodes. By the end, you'll clearly understand how to use Zombienet to deploy and test ephemeral blockchain networks, setting the stage for more complex scenarios.
+
+## Prerequisites
+
+To follow this tutorial, first, you need to have Zombienet installed. If you haven't done so, please follow the instructions in the [Installation](../overview.md/#installation){target=\_blank} section.
+
+## Defining the Network
+
+As mentioned in the [Configuration Files](../overview.md/#configuration-files){target=\_blank} section, Zombienet uses a configuration file to define the ephemeral network that will be spawned. To follow this tutorial, create a file named `spawn-a-basic-network.toml` with the following content:
+
+```toml
+[settings]
+timeout = 120
+
+[relaychain]
+
+[[relaychain.nodes]]
+name = "alice"
+validator = true
+
+[[relaychain.nodes]]
+name = "bob"
+validator = true
+
+[[parachains]]
+id = 100
+
+  [parachains.collator]
+  name = "collator01"
+```
+
+This configuration file defines a network with a relaychain with two nodes, `alice` and `bob`, and a parachain with a collator named `collator01`. Also, it sets a timeout of 120 seconds for the network to be ready.
+
+## Running the Network
+
+To spawn the network, run the following command:
+
+```bash
+zombienet -p native spawn spawn-a-basic-network.toml
+```
+
+This command will spawn the network defined in the `spawn-a-basic-network.toml` configuration file. The `-p native` flag specifies that the network will be spawned using the native provider.
+
+If successful, you will see the following output:
+
+<div id="termynal" class="table-termynal" data-termynal>
+    <span data-ty="input"><span class="file-path">zombienet -p native spawn spawn-a-basic-network.toml</span>
+    <table>
+        <thead>
+            <tr>
+                <th colspan="3" align="center">
+                    Network launched 🚀🚀
+                </th>
+            </tr>
+        </thead>
+        <tr>
+            <th class="left-header">Namespace</th>
+            <td>zombie-75a01b93c92d571f6198a67bcb380fcd</td>
+        </tr>
+        <tr>
+            <th class="left-header">Provider</th>
+            <td>native</td>
+        </tr>
+            <tr>
+                <th colspan="3" align="center">
+                Node Information
+                </th>
+            </tr>
+        <tr>
+            <th class="left-header">Name</th>
+            <td>alice</td>
+        </tr>
+        <tr>
+            <th class="left-header">Direct Link</th>
+            <td><a href="https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55308#explorer">https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55308#explorer</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Prometheus Link</th>
+            <td><a href="http://127.0.0.1:55310/metrics">http://127.0.0.1:55310/metrics</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Log Cmd</th>
+            <td>tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-2</td>
+        </tr>
+            <tr>
+                <th colspan="3" align="center">
+                Node Information
+                </th>
+            </tr>
+        <tr>
+            <th class="left-header">Name</th>
+            <td>bob</td>
+        </tr>
+        <tr>
+            <th class="left-header">Direct Link</th>
+            <td><a href="https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:50312#explorer">https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55312#explorer</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Prometheus Link</th>
+            <td><a href="http://127.0.0.1:50634/metrics">http://127.0.0.1:50634/metrics</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Log Cmd</th>
+            <td>tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-2</td>
+        </tr>
+            <tr>
+                <th colspan="3" align="center">
+                Node Information
+                </th>
+            </tr>
+        <tr>
+            <th class="left-header">Name</th>
+            <td>collator01</td>
+        </tr>
+        <tr>
+            <th class="left-header">Direct Link</th>
+            <td><a href="https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55316#explorer">https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55316#explorer</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Prometheus Link</th>
+            <td><a href="http://127.0.0.1:55318/metrics">http://127.0.0.1:55318/metrics</a></td>
+        </tr>
+        <tr>
+            <th class="left-header">Log Cmd</th>
+            <td>tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-2</td>
+        </tr>
+        <tr>
+            <th class="left-header">Parachain ID</th>
+            <td>100</td>
+        </tr>
+        <tr>
+            <th class="left-header">ChainSpec Path</th>
+            <td>/var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-2</td>
+        </tr>
+    </table>
+</div>
+
+!!! note 
+    If the IPs and ports are not explicitly defined in the configuration file, they may change each time the network is started, causing the links provided in the output to differ from the example.
+
+## Interacting with the Spawned Network
+
+### Connecting to the Nodes
+
+After the network is launched, you can interact with it using [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank}. To do so, open your browser and use the provided links listed by the output as `Direct Link`. For instance, in this particular case, as the ports may vary from spawning to spawning, to interact with the `alice` node, open [https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55308#explorer](https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:55308#explorer){target=\_blank} as it is the link provided in the output for the `alice` node. Moreover, you can also do this for the `bob` and `collator01` nodes.
+
+If you want to interact with the nodes more programmatically, you can also use the [Polkadot.js API](https://polkadot.js.org/api/){target=_blank}. For example, the following code snippet shows how to connect to the `alice` node using the Polkadot.js API and log some information about the chain and node:
+
+```typescript
+import { ApiPromise, WsProvider } from '@polkadot/api';
+
+async function main() {
+  const wsProvider = new WsProvider('ws://127.0.0.1:55308');
+    const api = await ApiPromise.create({ provider: wsProvider });
+
+    // Retrieve the chain & node information via rpc calls
+    const [chain, nodeName, nodeVersion] = await Promise.all([
+        api.rpc.system.chain(),
+        api.rpc.system.name(),
+        api.rpc.system.version()
+    ]);
+
+    console.log(`You are connected to chain ${chain} using ${nodeName} v${nodeVersion}`);
+}
+
+main().catch(console.error).finally(() => process.exit());
+```
+
+Either way allows you to interact easily with the network and its nodes.
+
+### Checking Metrics
+
+You can also check the metrics of the nodes by accessing the provided links listed by the output as `Prometheus Link`. [Prometheus](https://prometheus.io/){target=_blank} is a monitoring and alerting toolkit that collects metrics from the nodes. By accessing the provided links, you can see the metrics of the nodes in a web interface. So, for example, the following image shows the Prometheus metrics for Bob’s node from the Zombienet test:
+
+![Prometheus metrics for Bob’s node from the Zombienet test](/polkadot-ecosystem-docs-draft/images/dev-tools/zombienet/tutorials/zombienet-tutorials-1.webp)
+
+### Checking Logs
+
+To check the nodes’ logs, you can use the provided command listed by the output as 'Log Cmd'. For instance, to check the logs of the `alice` node, you can open a new terminal and run the following command:
+
+```bash
+tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-SEzfCidQ1za4/alice.log
+```
+
+After running this command, you will see the logs of the `alice` node in real-time, which can be useful for debugging purposes. The logs of the `bob` and `collator01` nodes can be checked similarly.
+
+## Running a Test
+
+To run a test against the spawned network, you can use the [Zombienet DSL](../testing.md) to define the test scenario. For example, you can create a file named `spawn-a-basic-network-test.zndsl` with the following content:
+
+```toml
+Description: Test the basic functionality of the network (minimal example)
+Network: ./spawn-a-basic-network.toml
+Creds: config
+
+alice: is up
+alice: parachain 100 is registered within 225 seconds
+alice: parachain 100 block height is at least 10 within 250 seconds
+
+bob: is up
+bob: parachain 100 is registered within 225 seconds
+bob: parachain 100 block height is at least 10 within 250 seconds
+
+# metrics
+alice: reports node_roles is 4
+alice: reports sub_libp2p_is_major_syncing is 0
+
+bob: reports node_roles is 4
+
+collator01: reports node_roles is 4
+```
+
+This test scenario checks to verify the following:
+
+- the nodes are running
+- the parachain with ID 100 is registered within a certain timeframe (255 seconds in this example)
+- the parachain block height is at least a certain number within a timeframe (in this case, 10 within 255 seconds)
+- the nodes report metrics 
+
+However, you can define any test scenario following the [Zombienet DSL](../testing.md) syntax.
+
+To run the test, execute the following command:
+
+```bash
+zombienet -p native test spawn-a-basic-network-test.zndsl
+```
+
+This command will execute the test scenario defined in the `spawn-a-basic-network-test.zndsl` file on the network. If successful, the terminal will display the test output, indicating whether the test passed or failed.
diff --git a/docs/images/dev-tools/zombienet/tutorials/zombienet-tutorials-1.webp b/docs/images/dev-tools/zombienet/tutorials/zombienet-tutorials-1.webp
diff --git a/material-overrides/assets/stylesheets/terminal.css b/material-overrides/assets/stylesheets/terminal.css
@@ -65,3 +65,9 @@
 [data-ty][data-ty-prompt]:before {
     content: attr(data-ty-prompt);
 }
+
+.md-typeset .table-termynal .md-typeset__table table th.left-header {
+    background-color: unset;
+    border-bottom: .05rem solid var(--md-typeset-table-color);
+    border-right: .05rem solid var(--md-typeset-table-color);
+}