Skip to content

Commit bb8c9b6

Browse files
akremenetskyakremenetsky
committed
docs(usage): add platform overview, licensing, admin guide and support lifecycle pages
- Add platform-overview, licensing, admin-guide, support-lifecycle documentation in English and Russian - Add build_docs.sh script to build docs artifacts via tox - Register exordos_docs manifest and artifact in exordos.yaml - Update mkdocs.yml navigation with new usage sections Signed-off-by: Anton Kremenetsky <anton.kremenetsky@gmail.com>
1 parent dd7e95c commit bb8c9b6

13 files changed

Lines changed: 911 additions & 0 deletions

‎docs/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ Welcome to Exordos Core!
66

77
**Exordos** is an open-source NoOps platform for managing infrastructure at every level, along with the ecosystem built on top of it.
88

9+
[Platform Overview →](usage/platform-overview.md)
10+
11+
[Usage Options and Licensing →](usage/licensing.md)
12+
13+
[Support, Updates, and Product Development →](usage/support-lifecycle.md)
14+
915
## 📦 Installation
1016

1117
### Linux

‎docs/index.ru.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ title: Exordos Core
66

77
**Exordos** — это open-source NoOps платформа для управления инфраструктурой на всех уровнях, а также экосистема, построенная на её основе.
88

9+
[Обзор платформы →](usage/platform-overview.ru.md)
10+
11+
[Варианты использования и лицензирование →](usage/licensing.ru.md)
12+
13+
[Поддержка, обновления и развитие →](usage/support-lifecycle.ru.md)
14+
915
## 📦 Установка
1016

1117
### Linux

‎docs/usage/admin-guide.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Admin Guide
2+
3+
This guide is for administrators of a local Exordos Core installation. It covers host preparation, platform deployment, access configuration, and basic operating tasks.
4+
5+
## Scope
6+
7+
The guide describes a local installation on a single Ubuntu Linux 24.04 or 26.04 host using QEMU/KVM and libvirt. This environment is intended for development, testing, and functional verification of the platform.
8+
9+
## Prerequisites
10+
11+
The deployment requires:
12+
13+
- a host machine running Ubuntu Linux 24.04 or 26.04;
14+
- permissions to install system packages and configure virtualization: QEMU version 8.2 or later and libvirt version 10.0 or later;
15+
- access to the Exordos repository to install the CLI and download an image;
16+
- an administrator SSH key for access to the primary node;
17+
- a host machine with at least 4 CPU cores, 8 GB of RAM, and 50 GB of free disk space for the primary virtual machine and managed Nodes.
18+
19+
## Install Exordos CLI
20+
21+
Install Exordos CLI:
22+
23+
```bash
24+
curl -fsSL https://repo.exordos.com/install.sh | sh
25+
```
26+
27+
Review available commands and bootstrap options:
28+
29+
```bash
30+
exordos --help
31+
exordos bootstrap --help
32+
```
33+
34+
## Prepare the host
35+
36+
Install QEMU/KVM version 8.2 or later, libvirt version 10.0 or later, and image utilities:
37+
38+
```bash
39+
sudo apt update
40+
sudo apt install qemu-kvm qemu-utils libvirt-daemon-system libvirt-dev mkisofs -y
41+
```
42+
43+
Add the user that runs the CLI to the `libvirt` and `kvm` groups:
44+
45+
```bash
46+
sudo adduser $USER libvirt
47+
sudo adduser $USER kvm
48+
```
49+
50+
Log out and log in again after changing group membership.
51+
52+
Initialize the host as a hypervisor with superuser privileges:
53+
54+
```bash
55+
sudo exordos compute hypervisors init
56+
```
57+
58+
Review initialization options:
59+
60+
```bash
61+
exordos compute hypervisors init --help
62+
```
63+
64+
## Deploy the platform
65+
66+
Bootstrap Exordos Core:
67+
68+
```bash
69+
exordos bootstrap -i <version-or-image> -f -m core --ssh-public-key /path/to/public/key
70+
```
71+
72+
The `<version-or-image>` argument accepts a path to a local image or a platform version from the repository. Examples:
73+
74+
```bash
75+
exordos bootstrap -i /path/to/exordos-core.raw -m core
76+
```
77+
78+
```bash
79+
exordos bootstrap -i <version> -m core
80+
```
81+
82+
For example, to install version `0.2.1`:
83+
84+
```bash
85+
exordos bootstrap -i 0.2.1 -m core
86+
```
87+
88+
Key bootstrap options:
89+
90+
| Option | Description |
91+
| --- | --- |
92+
| `--profile` | Installation profile: `develop`, `small`, `medium`, `large`, or `legacy`. |
93+
| `--cidr` | Platform primary network CIDR. Default: `10.20.0.0/22`. |
94+
| `--core-ip` | Primary virtual machine IP address. By default, the second address from `--cidr` is used. |
95+
| `--admin-password` | Administrator password for the HTTP API. Generated automatically when omitted. |
96+
| `--save-admin-password-file` | Saves the HTTP API administrator password to a file. |
97+
| `--ssh-public-key` | Path to a public SSH key for access to the primary virtual machine. |
98+
| `--hyper-connection-uri` | URI for a remote libvirt hypervisor connection. |
99+
| `--hyper-storage-pool` | libvirt storage pool for virtual machine disks. |
100+
101+
After `bootstrap` completes successfully, the platform creates and starts the primary virtual machine, and the command prints the administrator login and password for the HTTP API. When `--save-admin-password-file` is set, the API password is saved to the specified file. On an error, the command prints an error message and exits with a non-zero status.
102+
103+
Store generated API administrator credentials in a secure location. Do not expose passwords in logs, manifests, or source-control systems.
104+
105+
### API administrator credentials
106+
107+
`bootstrap` creates a separate administrator login and password for each local installation to access the HTTP API. There are no permanent shared credentials. Use the login and password printed by `bootstrap` or saved using `--save-admin-password-file`.
108+
109+
Access to the primary virtual machine uses the SSH key whose public part was supplied with the `--ssh-public-key` bootstrap option; API login and password are not used for SSH.
110+
111+
For a reproducible deployment, provide the API password explicitly:
112+
113+
```bash
114+
exordos bootstrap -i <version> -m core --admin-password <admin-password>
115+
```
116+
117+
Do not publish actual installation API credentials in public documentation.
118+
119+
## Configure access
120+
121+
### SSH access
122+
123+
Connect to the primary virtual machine. Use the private part of the SSH key whose public part was supplied with the `--ssh-public-key` bootstrap option:
124+
125+
```bash
126+
ssh ubuntu@<core-ip>
127+
```
128+
129+
For the default bootstrap network `10.20.0.0/22`, the primary virtual machine address is `10.20.0.2`. The HTTP API administrator login and password are not used for SSH.
130+
131+
### Configure CLI
132+
133+
Register the platform endpoint and administrator context. For `<ADMIN_USERNAME>` and `<ADMIN_PASSWORD>`, use the HTTP API credentials created by `bootstrap`:
134+
135+
```bash
136+
exordos settings set-realm local --endpoint http://<core-ip>:11010 --current
137+
exordos settings set-context local --name admin -u <ADMIN_USERNAME> -p <ADMIN_PASSWORD> --current
138+
```
139+
140+
Verify the connection:
141+
142+
```bash
143+
exordos compute hypervisors list
144+
exordos elements list
145+
```
146+
147+
### HTTP API access
148+
149+
Use the API administrator login and password created by `bootstrap` to obtain an `access_token` from IAM before calling the HTTP API. See [Local Deployment](local_deployment.md) for a complete request example. Send the resulting token as a Bearer token in subsequent requests.
150+
151+
## Verify startup and command responses
152+
153+
After configuring the CLI, perform the following checks in order:
154+
155+
| Command | Purpose and expected result |
156+
| --- | --- |
157+
| `exordos realms list` | Lists local realms. The `local` realm must be present. |
158+
| `exordos compute hypervisors list` | Lists registered hypervisors. The prepared hypervisor must be present. |
159+
| `exordos compute nodes list` | Lists Nodes. After bootstrap, the platform primary Node is available. |
160+
| `exordos elements list` | Lists installed elements. |
161+
| `exordos em resources list` | Lists element resources and their states. |
162+
163+
The `exordos elements list` and `exordos em resources list` commands support `--filters key=value`, `--fields <field>`, `--output table|json|html|yaml`, `--watch`, and `--interval <seconds>`. The default output format is a table. With `--watch`, the CLI repeatedly requests data at the specified interval.
164+
165+
## Basic operations
166+
167+
### Monitor resources
168+
169+
Use the following commands to inspect compute resources:
170+
171+
```bash
172+
exordos compute hypervisors list
173+
exordos compute nodes list
174+
```
175+
176+
Inspect element resources with:
177+
178+
```bash
179+
exordos em resources list
180+
exordos em resources show <uuid>
181+
```
182+
183+
A resource progresses through `NEW → IN_PROGRESS → ACTIVE`. The `IN_PROGRESS` state means that the platform is still reconciling the resource to its desired state.
184+
185+
### Manage elements
186+
187+
List installed elements:
188+
189+
```bash
190+
exordos elements list
191+
```
192+
193+
Install an element:
194+
195+
```bash
196+
exordos elements install <element-name>
197+
```
198+
199+
See the [Manifest Reference](../em/manifest.md) for the element manifest and resource model.
200+
201+
### Configurations and secrets
202+
203+
Deliver configuration and confidential data with Config and Secret resources. Do not store passwords, keys, or certificates in plain text in manifests, command logs, or source repositories.
204+
205+
## Troubleshooting
206+
207+
If a resource does not leave `IN_PROGRESS`, inspect the resource, Node, and hypervisor first:
208+
209+
```bash
210+
exordos em resources show <uuid>
211+
exordos compute nodes list
212+
exordos compute hypervisors list
213+
```
214+
215+
See [Troubleshooting](troubleshooting.md) for common resource, configuration, and bootstrap script issues.
216+
217+
## Terminate the installation
218+
219+
To terminate a local installation in a controlled way, delete its local realm:
220+
221+
```bash
222+
exordos realms delete local
223+
```
224+
225+
The command deletes the local realm and terminates the local instance. Use it only to finish a test or expert environment. To start a new instance, create the installation again with `exordos bootstrap`.
226+
227+
## Updating
228+
229+
Updates are performed per element. Exordos Core is also an element and is updated with the standard command:
230+
231+
```bash
232+
exordos elements update core
233+
```
234+
235+
Before updating, retain the installed element version, network configuration, and access credentials. Test the update procedure in a separate local installation and verify the rollback strategy before updating a production environment.
236+
237+
## Related documentation
238+
239+
- [Platform Overview](platform-overview.md)
240+
- [Local Deployment](local_deployment.md)
241+
- [Troubleshooting](troubleshooting.md)
242+
- [Support, Updates, and Product Development](support-lifecycle.md)
243+
- [Security Guide](security.md)
244+
- [Manifest Reference](../em/manifest.md)

0 commit comments

Comments
 (0)