Skip to content

Commit fc535f1

Browse files
skrobulskrobul
committed
docs: add operator guide
1 parent ad25dcd commit fc535f1

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/operator-guide/openstack-ironic-console.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Ironic Graphical Console guide
2+
3+
This guide explains how the Graphical Console feature is implemented for
4+
baremetal nodes.
5+
6+
## Overview
7+
8+
The overall goal of this is to provide the Undercloud users
9+
with an out-of-band, graphical console access to their provisioned nodes. At
10+
the same time, we do not want to give them full access to DRAC / iLo
11+
interfaces, nor do we want to share the access credentials.
12+
13+
Graphical console access feature is realised using several different components
14+
stitched together.
15+
16+
You can see how they all fit together on a diagram in [components](#components) section.
17+
Here is brief explanation of what each component is responsible for:
18+
19+
- **User** is typically interacting with Ironic **API** through the Openstack
20+
**CLI** and uses web **browser** to access the console
21+
- Ironic **Conductor** is responsible for starting the **console containers**
22+
upon user request
23+
- Ironic **Conductor** is also responsible for creating a Kubernetes secret
24+
with the credentials to access the console
25+
- **Console VNC Containers** are like a mini jump host desktops that can run
26+
only one application - a browser with a HTML5 console exposed by the
27+
baremetal nodes BMC. These containers are accessible (internally) through
28+
VNC.
29+
- **ironic-novncproxy** is launched alongside the **Ironic Conductor** and as
30+
the name implies, it proxies users HTTPS traffic. It does that by serving
31+
[noVNC](https://github.com/novnc/noVNC) web application to the user's
32+
browser. The browser then opens websocket connection to the
33+
**ironic-novncproxy** which in turn opens VNC connection to the relevant
34+
**container**.
35+
36+
## Sequence diagram
37+
38+
Below diagram shows the sequence of events that occur during typical session
39+
when the user or operator opens the console.
40+
41+
```mermaid
42+
sequenceDiagram
43+
participant User
44+
participant CLI
45+
participant Browser
46+
participant IronicAPI
47+
participant Conductor
48+
participant NoVNCProxy
49+
participant Container
50+
participant BMC
51+
52+
User->>CLI: baremetal node console enable
53+
CLI->>IronicAPI: REST API call to enable console
54+
IronicAPI->>Conductor: Enable console
55+
Conductor->>Conductor: Create & store time-limited token
56+
Conductor->>Conductor: Start container (virtual X11, browser, VNC server)
57+
58+
User->>CLI: baremetal node console show
59+
CLI->>IronicAPI: REST API call to fetch console URL
60+
IronicAPI-->>User: Returns console URL
61+
User->>Browser: open console page
62+
Browser->>NoVNCProxy: Access console URL
63+
NoVNCProxy->>Browser: Serve NoVNC web assets
64+
65+
Browser->>NoVNCProxy: Initiate WebSocket
66+
NoVNCProxy->>NoVNCProxy: Lookup node & validate token
67+
68+
NoVNCProxy->>Container: VNC connection
69+
Container->>BMC: Connect to DRAC/iLO endpoint
70+
BMC->Container: ""
71+
Container->>NoVNCProxy: ""
72+
NoVNCProxy->>Browser: HTML5 console
73+
```
74+
75+
## Components
76+
77+
A typical deployment will have several components running to provide console functionality.
78+
79+
Please note:
80+
81+
- Each baremetal node console session gets it's own VNC container
82+
- There is a 1:1 coupling between the Ironic conductor and the Ironic NOVNCProxy
83+
84+
```mermaid
85+
flowchart LR
86+
87+
%% --- Nodes / groups ---
88+
subgraph Access
89+
direction TB
90+
U[User]
91+
B[browser]
92+
C[CLI]
93+
GW[API gateway]
94+
end
95+
96+
97+
subgraph Core
98+
direction TB
99+
IA[ironic-api]
100+
N0[ironic-novncproxy-0]
101+
N1[ironic-novncproxy-1]
102+
end
103+
104+
105+
106+
subgraph Conductors
107+
direction TB
108+
C0[ironic-conductor-0]
109+
C1[ironic-conductor-1]
110+
end
111+
112+
subgraph Consoles
113+
direction TB
114+
V0a[console-vnc-0a]
115+
V0b[console-vnc-0b]
116+
V0c[console-vnc-0c]
117+
V0d[console-vnc-0d]
118+
V1a[console-vnc-1a]
119+
V1b[console-vnc-1b]
120+
end
121+
122+
subgraph Servers
123+
direction TB
124+
S0a[srv-0a]
125+
S0b[srv-0b]
126+
S0c[srv-0c]
127+
S0d[srv-0d]
128+
S1a[srv-1a]
129+
S1b[srv-1b]
130+
end
131+
132+
%% -------------------------------------------------------------------
133+
%% IMPORTANT: protocol links are defined FIRST so linkStyle indices match
134+
%% -------------------------------------------------------------------
135+
136+
%% Console containers -> servers (HTTPS) [links 0..5]
137+
V0a -- https --> S0a
138+
V0b --> S0b
139+
V0c --> S0c
140+
V0d --> S0d
141+
V1a --> S1a
142+
V1b --> S1b
143+
144+
145+
146+
%% Conductors -> servers (Redfish) [links 6..11]
147+
C0 --> S0a
148+
C0 --> S0b
149+
C0 --> S0c
150+
C0 --> S0d
151+
C1 --> S1a
152+
C1 -- redfish --> S1b
153+
154+
%% Style HTTPS links (thick + green)
155+
linkStyle 0 stroke-width:4px,stroke:#2e7d32
156+
linkStyle 1 stroke-width:4px,stroke:#2e7d32
157+
linkStyle 2 stroke-width:4px,stroke:#2e7d32
158+
linkStyle 3 stroke-width:4px,stroke:#2e7d32
159+
linkStyle 4 stroke-width:4px,stroke:#2e7d32
160+
linkStyle 5 stroke-width:4px,stroke:#2e7d32
161+
162+
%% Style Redfish links (dashed + blue)
163+
linkStyle 6 stroke-dasharray: 6 4,stroke:#1565c0
164+
linkStyle 7 stroke-dasharray: 6 4,stroke:#1565c0
165+
linkStyle 8 stroke-dasharray: 6 4,stroke:#1565c0
166+
linkStyle 9 stroke-dasharray: 6 4,stroke:#1565c0
167+
linkStyle 10 stroke-dasharray: 6 4,stroke:#1565c0
168+
linkStyle 11 stroke-dasharray: 6 4,stroke:#1565c0
169+
170+
%% --- Everything else (unstyled) ---
171+
U --> C
172+
U --> B
173+
B --> GW
174+
C --> GW
175+
176+
GW -- http --> IA
177+
GW -- https --> N0
178+
GW -- "http(s)? + websocket" --> N1
179+
180+
IA --> C0
181+
IA --> C1
182+
183+
N0 -- vnc --> V0a
184+
N0 -- vnc --> V0b
185+
N0 -- vnc --> V0c
186+
N0 -- vnc --> V0d
187+
188+
N1 -- vnc --> V1a
189+
N1 -- vnc --> V1b
190+
```
191+
192+
## Environment requirements and configuration
193+
194+
Following per-environment configurations must be made to enable graphical
195+
console feature:
196+
197+
1. The baremetal nodes' console_interface must be set to a graphical driver
198+
such as `redfish-graphical`.
199+
2. Ironic must have the relevant drivers enabled in `enabled_console_interfaces`
200+
3. `ironic-novncproxy` must be launched for each of the ironic conductors. At
201+
the time of writing, this is achieved through `extraContainers` because
202+
OpenStack Helm does not have direct support for launching that component. We
203+
plan to contribute that feature to [OSH][3] soon.
204+
4. Each instance of the `ironic-novncproxy` must be exposed to the external
205+
world. This means, we have to create relevant Kubernetes `Service` and
206+
`HTTPRoute` definitions. The `cert-manager` will take care of TLS certificates
207+
and `external-dns` will register the DNS domain.
208+
5. *(Optional)* The RBAC policy may need to be adjusted as the baremetal console,
209+
by default is only accessible to admins.
210+
211+
## Docs
212+
213+
- [ironic VNC config][1] documentation
214+
- [ironic - Graphical Console support][2]
215+
216+
[1]: https://docs.openstack.org/ironic/latest/configuration/config.html#vnc
217+
[2]: https://docs.openstack.org/ironic/latest/install/graphical-console.html
218+
[3]: https://github.com/RSS-Engineering/undercloud-deploy/commit/d7201742ae5e10b9428be17b7418ac1066899214

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ nav:
163163
- operator-guide/openstack-ironic.md
164164
- operator-guide/openstack-ironic-inspection-guide.md
165165
- operator-guide/openstack-ironic-change-boot-interface.md
166+
- operator-guide/openstack-ironic-console.md
166167
- operator-guide/openstack-neutron.md
167168
- operator-guide/openstack-placement.md
168169
- 'Networking':

0 commit comments

Comments
 (0)