[pdm-devel] [PATCH datacenter-manager] docs: port over sdn and markdown primer and finish web ui section

* [pdm-devel] [PATCH datacenter-manager] docs: port over sdn and markdown primer and finish web ui section
@ 2025-12-03 13:11 Shannon Sterz
  2025-12-03 14:04 ` Thomas Lamprecht
  0 siblings, 1 reply; 2+ messages in thread
From: Shannon Sterz @ 2025-12-03 13:11 UTC (permalink / raw)
  To: pdm-devel

Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
---
 docs/index.rst           |   2 +
 docs/markdown-primer.rst | 179 +++++++++++++++++++++++++++++++++++++++
 docs/sdn-integration.rst |  84 ++++++++++++++++++
 docs/views.rst           |   2 +
 docs/web-ui.rst          | 111 +++++++++++++++++++++++-
 5 files changed, 376 insertions(+), 2 deletions(-)
 create mode 100644 docs/markdown-primer.rst
 create mode 100644 docs/sdn-integration.rst

diff --git a/docs/index.rst b/docs/index.rst
index fd3e31f..8398f57 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,6 +23,7 @@ in the section entitled "GNU Free Documentation License".
    introduction.rst
    installation.rst
    web-ui.rst
+   sdn-integration.rst
    remotes.rst
    views.rst
    access-control.rst
@@ -40,6 +41,7 @@ in the section entitled "GNU Free Documentation License".
    command-syntax.rst
    configuration-files.rst
    roadmap.rst
+   markdown-primer.rst
    GFDL.rst
 
 .. only:: html and devbuild
diff --git a/docs/markdown-primer.rst b/docs/markdown-primer.rst
new file mode 100644
index 0000000..882103d
--- /dev/null
+++ b/docs/markdown-primer.rst
@@ -0,0 +1,179 @@
+.. _markdown-primer:
+
+Markdown Primer
+===============
+
+  "Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
+  you to write using an easy-to-read, easy-to-write plain text format, then
+  convert it to structurally valid XHTML (or HTML)."
+
+  --  John Gruber, https://daringfireball.net/projects/markdown/
+
+
+The "Notes" panel of the `Proxmox Datacenter Manager` web-interface supports
+rendering Markdown text.
+
+Proxmox Backup Server supports CommonMark with most extensions of GFM (GitHub
+Flavoured Markdown), like tables or task-lists.
+
+.. _markdown_basics:
+
+Markdown Basics
+---------------
+
+Note that we only describe the basics here. Please search the web for more
+extensive resources, for example on https://www.markdownguide.org/
+
+Headings
+~~~~~~~~
+
+.. code-block:: md
+
+  # This is a Heading h1
+  ## This is a Heading h2
+  ##### This is a Heading h5
+
+
+Emphasis
+~~~~~~~~
+
+Use ``*text*`` or ``_text_`` for emphasis.
+
+Use ``**text**`` or ``__text__`` for bold, heavy-weight text.
+
+Combinations are also possible, for example:
+
+.. code-block:: md
+
+  _You **can** combine them_
+
+
+Links
+~~~~~
+
+You can use automatic detection of links. For example,
+``https://forum.proxmox.com/`` would transform it into a clickable link.
+
+You can also control the link text, for example:
+
+.. code-block:: md
+
+  Now, [the part in brackets will be the link text](https://forum.proxmox.com/).
+
+Lists
+~~~~~
+
+Unordered Lists
+^^^^^^^^^^^^^^^
+
+Use ``*`` or ``-`` for unordered lists, for example:
+
+.. code-block:: md
+
+  * Item 1
+  * Item 2
+  * Item 2a
+  * Item 2b
+
+
+You can create nested lists by adding indentation.
+
+Ordered Lists
+^^^^^^^^^^^^^
+
+.. code-block:: md
+
+  1. Item 1
+  1. Item 2
+  1. Item 3
+    1. Item 3a
+    1. Item 3b
+
+NOTE: The integer of ordered lists does not need to be correct, they will be numbered automatically.
+
+Task Lists
+^^^^^^^^^^
+
+Task lists use a empty box ``[ ]`` for unfinished tasks and a box with an `X` for finished tasks.
+
+For example:
+
+
+.. code-block:: md
+
+  - [X] First task already done!
+  - [X] Second one too
+  - [ ] This one is still to-do
+  - [ ] So is this one
+
+Tables
+~~~~~~
+
+Tables use the pipe symbol ``|`` to separate columns, and ``-`` to separate the
+table header from the table body. In that separation, you can also set the text
+alignment, making one column left-, center-, or right-aligned.
+
+
+.. code-block:: md
+
+  | Left columns  | Right columns |  Some  | More | Cols.| Centering Works Too
+  | ------------- |--------------:|--------|------|------|:------------------:|
+  | left foo      | right foo     | First  | Row  | Here | >center<           |
+  | left bar      | right bar     | Second | Row  | Here | 12345              |
+  | left baz      | right baz     | Third  | Row  | Here | Test               |
+  | left zab      | right zab     | Fourth | Row  | Here | ☁️☁️☁️              |
+  | left rab      | right rab     | And    | Last | Here | The End            |
+
+Note that you do not need to align the columns nicely with white space, but that makes
+editing tables easier.
+
+Block Quotes
+~~~~~~~~~~~~
+
+You can enter block quotes by prefixing a line with ``>``, similar as in plain-text emails.
+
+.. code-block:: md
+
+  > Markdown is a lightweight markup language with plain-text-formatting syntax,
+  > created in 2004 by John Gruber with Aaron Swartz.
+  >
+  >> Markdown is often used to format readme files, for writing messages in online discussion forums,
+  >> and to create rich text using a plain text editor.
+
+Code and Snippets
+~~~~~~~~~~~~~~~~~
+
+You can use backticks to avoid processing a group of words or paragraphs. This
+is useful for preventing a code or configuration hunk from being mistakenly
+interpreted as markdown.
+
+Inline Code
+^^^^^^^^^^^
+
+Surrounding part of a line with single backticks allows you to write code
+inline, for examples:
+
+.. code-block:: md
+
+  This hosts IP address is `10.0.0.1`.
+
+Entire Blocks of Code
+^^^^^^^^^^^^^^^^^^^^^
+
+For code blocks spanning several lines, you can use triple-backticks to start
+and end such a block, for example:
+
+.. code-block:: md
+
+  ```
+  # This is the network config I want to remember here
+  auto vmbr2
+  iface vmbr2 inet static
+          address 10.0.0.1/24
+          bridge-ports ens20
+          bridge-stp off
+          bridge-fd 0
+          bridge-vlan-aware yes
+          bridge-vids 2-4094
+
+  ```
diff --git a/docs/sdn-integration.rst b/docs/sdn-integration.rst
new file mode 100644
index 0000000..5dcfe37
--- /dev/null
+++ b/docs/sdn-integration.rst
@@ -0,0 +1,84 @@
+.. _sdn-integration:
+
+SDN Integration
+---------------
+
+The Proxmox Datacenter allows managing SDN zones and vnets across multiple remotes and provides an
+overview of the current state of SDN entities.
+
+.. _status_overview:
+
+Status Overview
+~~~~~~~~~~~~~~~
+
+The status overview shows the current status (available / error / unknown) of all zones on all
+remotes. This is equivalent to the status shown in the SDN overview of the Proxmox VE Web UI. A
+summary is also shown on the dashboard, allowing users to quickly identify if there are any
+erroneous SDN zones on any remote.
+
+.. _evpn_integration:
+
+EVPN Integration
+~~~~~~~~~~~~~~~~
+
+The EVPN overview shows an aggregated overview of the contents of EVPN zones / routing table
+instances of all configured clusters.
+
+
+.. note:: Currently, the integration operates under the assumption that EVPN controllers with the
+   same ASN are interconnected and part of the same overlay network. Zones and Vnets with the same
+   ASN:VNI tag will get automatically merged in the overview trees.}}
+
+The EVPN integration respects the ‘Route Target Import’ field of an EVPN zone and assumes any Zones
+/ Vnets with that Route Target are imported as well.
+
+Defintions
+^^^^^^^^^^
+
+Currently, the SDN stack in Proxmox VE uses the terms Zones and VNets, which are specific to the
+Proxmox VE stack. The following defintions try to make the relationship of those entities to the
+more commonly used definitions in RFC 7432 and RFC 9136 clearer:
+
+A EVPN zone represents a routing table instance (identified by its ASN:VNI tag). This is also known
+as an IP-VRF It is associated with a VXLAN VNI (the VRF-VXLAN tag of a zone) and also referred to as
+L3VNI.
+
+A vnet in an EVPN zone represents a bridging table (identified by its ASN:VNI tag). This is also
+known as a MAC-VRF. One IP-VRF can contain multiple MAC-VRFs. Analogous to a EVPN zone it is
+associated with a VXLAN VNI (the tag of a vnet) and also referred to as L2VNI.
+
+Remotes
+'''''''
+
+This view provides an overview of which zones are available on a remote and which vnets it contains.
+It shows the vnets that are locally configured on that remote, as well as the vnets that get
+imported either automatically (due to matching ASN:VNI tags) or manually (due to being specified in
+the ‘Route Target Import’ setting). Vnets that are not local to a remote are shown slightly greyed
+out, so they can be distinguished easily.
+
+It contains the following columns:
+
+*  Name: The name of the remote / zone / vnet
+*  L3VNI: The VRF-VXLAN tag configured in the zone
+*  L2VNI: The tag configured in the vnet
+*  External: Whether this VNet is locally configured or from another remote
+*  Imported: Whether this VNet was manually imported, due to a respective ‘Route Target Import’
+   entry
+
+.. _ip_vrf:
+
+IP-VRF
+''''''
+
+This view provides an overview of all available IP-VRFs and their contents. This view shows only
+VNets that are naturally part of an IP-VRF due to their zone having the same ASN:VNI combination. It
+can be used to see which VNets would get imported when specifying the respective ASN:VNI in the
+‘Route Target Import’ field.
+
+It contains the following columns:
+
+*  Name: The name of the remote / zone / vnet
+*  ASN: The VRF-VXLAN tag configured in the zone
+*  VNI: The L3VNI (for zones) or L2VNI (for vnets)
+*  Zone: The name of the zone that contains the vnet
+*  Remote: The name of the remote that contains the zone (and therefore vnet).
diff --git a/docs/views.rst b/docs/views.rst
index cd3abcf..c46b96a 100644
--- a/docs/views.rst
+++ b/docs/views.rst
@@ -1,3 +1,5 @@
+.. _views:
+
 Views
 =====
 
diff --git a/docs/web-ui.rst b/docs/web-ui.rst
index aaa923a..5ee2b15 100644
--- a/docs/web-ui.rst
+++ b/docs/web-ui.rst
@@ -11,6 +11,11 @@ The web interface can be accessed via https://youripaddress:8443.
 The default login is `root`, and the password is either the one specified during the installation
 process or the password of the root user, in case of installation on top of Debian.
 
+.. note:: Most of the descriptions below will focus on the user interface set to "English", which
+   uses the left-to-right text direction. If you use a language with a text direction from
+   right-to-left, then some elements will appear on the right when the description says "left" and
+   vice versa.
+
 
 Features
 --------
@@ -43,5 +48,107 @@ selected here.
 User Interface Overview
 -----------------------
 
-.. todo::
-   describe basic PDM UI overview with all panels and views listed, see PBS for a basic idea.
+..
+  .. image:: images/screenshots/pdm-gui-dashboard.png
+  :target: _images/pdm-gui-dashboard.png
+  :align: right
+  :alt: Proxmox Datacenter Manager GUI Dashboard
+
+The Proxmox Datacenter Manager graphical interface can be roughly split into three different section:
+
+* **Header**: On the left the header shows the current version information. In the middle a search
+  bar is found that helps you find different remotes and resources. While on the right you can
+  toggle the dark mode of the theme, go to the user documentation, open a list of tasks and open a
+  menu to configure the theme and language that is used as well as log out.
+* **Sidebar**: Below the header on the left the sidebar contains the main menu with the different
+  menu options listed.
+* **Main Panel**: The biggest part of the interface is taken up by the main panel. Its content will
+  change depending on the menu selected in the sidebar. To start, the dashboard will be shown.
+
+Sidebar
+-------
+
+In the sidebar, on the left side of the page, you can see various items relating
+to specific management activities.
+
+Dashboard
+^^^^^^^^^
+
+The dashboard gives an overview of all configured remotes and resources. Including whether remotes
+and their resources are up and running. Allowing you to tell at a glimpse how many VMs and CTs are
+running or stopped across your data center and the state of all configured datastores. Information
+on running tasks, CPU and memory usage, software defined networking (SDN) zones and the subscription
+status is shown as well.
+
+Views
+^^^^^
+
+:ref:`views` essentially allow you to create a custom dashboard. You can create a new view by copying an
+existing view or creating it as an empty view. Then a set of filters can be applied to a view, so it
+will only include information on specific resources or remotes. After creating a new view, select it
+from the sidebar to see what it looks like. From there you can also adjust its layout and widgets.
+
+Notes
+^^^^^
+
+In the notes section you can keep track of information that might be useful to other administrators
+or yourself in the future. To format the notes, :ref:`Markdown <markdown-primer>` can be used. Notes
+are shared across all data center users that have been granted access to them.
+
+Configuration
+^^^^^^^^^^^^^
+
+To configure your Proxmox Datacenter Manager, navigate to the "Configuration" menu. It allows you to
+change the time and timezone, the DNS server and the its network interfaces. A second tab makes the
+WebAuthn Two Factor Authentication (TFA) settings available. There are also several sub-menus:
+
+* **Access Control**: Manage users, API tokens, TFA settings, token and user permissions as well as
+  authentication realms.
+* **Certificates**: Set up custom TLS or automated ACME certificates.
+* **Subscription**: To get proper support and access to the enterprise repository for your Proxmox
+  Datacenter Manager, you can use this menu to check the subscription status.
+
+Administration
+^^^^^^^^^^^^^^
+
+The administration menu can be used to get an overview of the Proxmox Datacenter Manager node
+itself. Through the sub-menu "Shell" you can access the host's shell. Several tabs allow you to
+manage different aspects of the node, such as:
+
+* **Node Status**: See the CPU utilization, memory usage and other metrics of the Proxmox Datacenter
+  Manager. Here you can also access package versions and the system report of your host, as well as
+  reboot or turn of the host.
+* **Updates**: Manage and install updates.
+* **Repositories**: Add, enable and inspect update repositories.
+* **Syslog**: Access the hosts system log.
+* **Tasks**: An overview of all tasks of the host.
+
+SDN
+^^^
+
+This menu provides an overview of all SDN zones across all configured Proxmox VE remotes. The EVPN
+menu can be used to set up EVPN zones across multiple remotes via a single interface. More detailed
+information on how to use Proxmox Datacenter Manager's SDN integration can be found in the
+:ref:`sdn-integration` section.
+
+Remotes
+^^^^^^^
+
+Remotes allows you to configure new remotes as well as manage existing one. The "Remotes" menu
+itself provides different tabs to provide a unified view of your entire data center:
+
+* **Configuration**: Shows a list of configured remotes and some basic information on them. It also
+  allows configuring new remotes.
+* **Tasks**: An overview of all tasks across the entire data center that can be filtered.
+* **Updates**: Allows managing updates and package versions for all remotes.
+* **Firewall**: Shows a list of configured firewall rules and settings for each Proxmox VE remote
+  cluster, its nodes, and guests.
+
+All configured remotes are also listed here in the sidebar. Each menu entry provides a split panel
+that contains the most important information for each remote in an easy to navigate interface.
+
+
+
+
+
+
-- 
2.47.3



_______________________________________________
pdm-devel mailing list
pdm-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pdm-devel

^ permalink raw reply	[flat|nested] 2+ messages in thread