Skip to content

Commit 90ba5c0

Browse files
cjh1cjh1
committed
docs: update README
Make the README relevant. Signed-off-by: Chris Harris <cjh@lbl.gov>
1 parent 687d4ee commit 90ba5c0

1 file changed

Lines changed: 137 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 137 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,150 @@
1-
# Console Data Service
1+
# Remote Console
22

3-
The Console Data Service handles recording the current states of which nodes are being monitored by which pods. The service is used by the Console Node and Console Operator projects exclusively to support the required operations of those projects.
3+
Remote Console is an OpenCHAMI service for remote console access.
44

5-
## Related Software
6-
Console Node Service - Responsible for handling direct console node connections, recording console logs, forwarding the log information to SMF and providing interactive console access.
5+
The service is a wrapper around conman which manages console access. The service
6+
generates the appropriate configuation to drive conman. The service
7+
layer keeps conman behind a narrower interface so clients do not need to invoke
8+
conman directly and the implementation will likely evolve over time.
79

8-
Console Operator Service - Handles watching for hardware changes, watches for problems with running Console Node pods and scales the number of Console Node pods based on the number of nodes being monitored.
10+
## History
911

10-
## Build and run the Docker image
11-
The project leverages Docker Compose to simplify operations in development. To build and start the service locally run:
12-
````
13-
./startDevServices.sh
14-
````
12+
This codebase is a combination of ideas and code from the earlier
13+
[Cray-HPE/console-node](https://github.com/Cray-HPE/console-node) and
14+
[Cray-HPE/console-data](https://github.com/Cray-HPE/console-data) services.
15+
These projects split console connection handling, console logging, and console
16+
state tracking across multiple services.
1517

16-
To stop the running service run:
17-
````
18-
./stopDevServices.sh
19-
````
18+
Notable changes since the original import include:
2019

21-
## Testing
22-
The service is integrated with PostgreSQL (deployed in production via the standard Helm service chart and operator). For local testing the project leverages Docker Compose to setup the PostgresSQL dependency and execute the tests.
23-
To build the latest service image from local source and execute the tests locally run:
24-
````
25-
./runIntegrationTest.sh
26-
````
20+
- OpenCHAMI module naming and GitHub/GHCR build automation.
21+
- Splitting functionality into well defined packages each with their own configuration.
22+
Providing better separation of concerns and testability.
23+
- Vendor-agnostic console discovery using Redfish data provided by SMD instead
24+
of HPE-specific node type checks.
25+
- WebSocket console access for interactive sessions and log tail sessions.
26+
- Unit tests for the new internal packages.
27+
- Integration tests using testcontainers, an IPMI simulator, Redfish mocks, and
28+
SSH containers that act as mock consoles.
2729

28-
## Build Helpers
29-
This repo uses some build helpers from the
30-
[cms-meta-tools](https://github.com/Cray-HPE/cms-meta-tools) repo. See that repo for more details.
30+
## Runtime Behavior
3131

32-
## Local Builds
33-
If you wish to perform a local build, you will first need to clone or copy the contents of the
34-
cms-meta-tools repo to `./cms_meta_tools` in the same directory as the `Makefile`. When building
35-
on github, the cloneCMSMetaTools() function clones the cms-meta-tools repo into that directory.
32+
On startup the service:
3633

37-
For a local build, you will also need to manually write the .version, .docker_version (if this repo
38-
builds a docker image), and .chart_version (if this repo builds a helm chart) files. When building
39-
on github, this is done by the setVersionFiles() function.
34+
1. Loads configuration from flags and `RCS_` environment variables.
35+
2. Fetches console-capable nodes from SMD.
36+
3. Retrieves console credentials from secure storage.
37+
4. Writes a generated conman configuration using `scripts/conman.conf.tmpl` template.
38+
5. Runs `conmand`.
39+
6. Serves HTTP health, console inventory, and WebSocket console endpoints.
40+
7. Watches SMD and credential state for changes and restarts or signals conman
41+
when needed.
42+
8. Manages conman log rotation and aggregate console logs.
4043

41-
## Copyright and License
42-
This project is copyrighted by Hewlett Packard Enterprise Development LP and is under the MIT license. See the LICENSE file for details.
44+
## API
4345

44-
When making any modifications to a file that has a Cray/HPE copyright header, that header must be updated to include the current year.
46+
All routes are under `/remote-console`.
4547

46-
When creating any new files in this repo, if they contain source code, they must have the HPE copyright and license text in their header, unless the file is covered under someone else's copyright/license (in which case that should be in the header). For this purpose, source code files include Dockerfiles, Ansible files, RPM spec files, and shell scripts. It does not include Jenkinsfiles, OpenAPI/Swagger specs, or READMEs.
48+
| Route | Description |
49+
| --- | --- |
50+
| `GET /liveness` | Kubernetes-style liveness check. Returns `204` when alive. |
51+
| `GET /readiness` | Kubernetes-style readiness check. Returns `204` when ready. |
52+
| `GET /health` | Returns console count and last hardware update time. |
53+
| `GET /consoles` | Returns the current console inventory. |
54+
| `GET /consoles/{nodeID}` | WebSocket interactive console session. |
55+
| `GET /consoles/{nodeID}?mode=tail` | WebSocket console log tail session. |
4756

48-
When in doubt, provided the file is not covered under someone else's copyright or license, then it does not hurt to add ours to the header.
57+
The console endpoints are protected by JWT middleware when `--jwks-url` is set.
58+
If no JWKS URL is configured, console endpoints are left unprotected and the
59+
service logs a warning.
60+
61+
Tail mode supports:
62+
63+
| Query parameter | Description |
64+
| --- | --- |
65+
| `mode=tail` | Selects console log tail mode instead of interactive mode. |
66+
| `follow=true` | Continues streaming new log lines after existing content. |
67+
| `lines=N` | Sends the last `N` lines before optionally following. |
68+
69+
## Build and Test
70+
71+
Build the container image:
72+
73+
```sh
74+
make image
75+
```
76+
77+
Override the image tag:
78+
79+
```sh
80+
make image DOCKER_VERSION=dev
81+
```
82+
83+
Run lint:
84+
85+
```sh
86+
make lint
87+
```
88+
89+
Run tests:
90+
91+
```sh
92+
make test
93+
```
94+
95+
## Configuration
96+
97+
Configuration is exposed as command-line flags and matching environment
98+
variables. Environment variables use the `RCS_` prefix. Command-line flags take
99+
precedence over environment variables.
100+
101+
| Flag | Environment variable | Default | Description |
102+
| --- | --- | --- | --- |
103+
| `--conman-base-conf-file-path` | `RCS_CONMAN_BASE_CONF_FILE_PATH` | `/app/conman.conf.tmpl` | Path to the base conman configuration template file. |
104+
| `--conman-conf-file-path` | `RCS_CONMAN_CONF_FILE_PATH` | `/app/conman.conf` | Path to the generated conman configuration file. |
105+
| `--conman-logs-path` | `RCS_CONMAN_LOGS_PATH` | `/var/log/conman` | Path to conman log files. |
106+
| `--conman-pid-file-path` | `RCS_CONMAN_PID_FILE_PATH` | `/var/run/conman.pid` | Path to the conman PID file. |
107+
| `--conman-console-scripts-path` | `RCS_CONMAN_CONSOLE_SCRIPTS_PATH` | `/usr/bin` | Path to console helper scripts. |
108+
| `--creds-ssh-console-key-path` | `RCS_CREDS_SSH_CONSOLE_KEY_PATH` | `/app/conman.key` | Path where the SSH private key file for console access is written. |
109+
| `--creds-vault-base-path` | `RCS_CREDS_VAULT_BASE_PATH` | empty | Base path in Vault where credentials are stored. |
110+
| `--creds-vault-role` | `RCS_CREDS_VAULT_ROLE` | empty | Vault role to use when authenticating to Vault. |
111+
| `--creds-local-store-file-path` | `RCS_CREDS_LOCAL_STORE_FILE_PATH` | empty | Path to local secure storage file. |
112+
| `--creds-local-store-key` | `RCS_CREDS_LOCAL_STORE_KEY` | empty | Key to use for local secure storage decryption. |
113+
| `--creds-secure-storage-ssh-keys-path` | `RCS_CREDS_SECURE_STORAGE_SSH_KEYS_PATH` | empty | Path where SSH keys can be found in secure storage. Leave empty to skip SSH key management. |
114+
| `--creds-secure-storage-passwords-path` | `RCS_CREDS_SECURE_STORAGE_PASSWORDS_PATH` | `hms-creds` | Path where console access credentials can be found in secure storage. |
115+
| `--http-listen` | `RCS_HTTP_LISTEN` | `0.0.0.0:26776` | HTTP listen address. |
116+
| `--new-node-lookup` | `RCS_NEW_NODE_LOOKUP` | `120` | Interval in seconds to look for new nodes. |
117+
| `--creds-monitor-interval` | `RCS_CREDS_MONITOR_INTERVAL` | `30` | Interval in seconds to monitor credential updates. |
118+
| `--smd-url` | `RCS_SMD_URL` | `http://cray-smd/` | URL for the SMD service. A trailing slash is added automatically. |
119+
| `--jwks-url` | `RCS_JWKS_URL` | empty | JWKS URL for fetching public keys for JWT validation. |
120+
| `--jwks-fetch-interval` | `RCS_JWKS_FETCH_INTERVAL` | `5` | Interval in seconds to retry fetching JWKS on failure. |
121+
| `--oauth2-client-id` | `RCS_OAUTH2_CLIENT_ID` | empty | OAuth2 client ID for SMD authentication. |
122+
| `--oauth2-client-secret` | `RCS_OAUTH2_CLIENT_SECRET` | empty | OAuth2 client secret for SMD authentication. |
123+
| `--oauth2-token-url` | `RCS_OAUTH2_TOKEN_URL` | empty | OAuth2 token endpoint URL for SMD authentication. |
124+
| `--oauth2-scopes` | `RCS_OAUTH2_SCOPES` | `[]` | OAuth2 scopes for SMD authentication. |
125+
| `--console-logs-file-size` | `RCS_CONSOLE_LOGS_FILE_SIZE` | `5M` | Maximum size of console log files before rotation. |
126+
| `--console-logs-num-rotate` | `RCS_CONSOLE_LOGS_NUM_ROTATE` | `2` | Number of rotated console log files to keep. |
127+
| `--console-logs-backup-path` | `RCS_CONSOLE_LOGS_BACKUP_PATH` | `/var/log/conman.old` | Path to rotated console log files. |
128+
| `--agg-logs-file-size` | `RCS_AGG_LOGS_FILE_SIZE` | `20M` | Maximum size of aggregation log file before rotation. |
129+
| `--agg-logs-num-rotate` | `RCS_AGG_LOGS_NUM_ROTATE` | `1` | Number of rotated aggregation log files to keep. |
130+
| `--agg-logs-path` | `RCS_AGG_LOGS_PATH` | `/tmp/consoleAgg` | Path to aggregation log files. |
131+
| `--log-rotate-enabled` | `RCS_LOG_ROTATE_ENABLED` | `true` | Enable log rotation. |
132+
| `--log-rotate-check-frequency` | `RCS_LOG_ROTATE_CHECK_FREQUENCY` | `600` | Frequency in seconds to check for log rotation. |
133+
| `--log-rotate-file-path` | `RCS_LOG_ROTATE_FILE_PATH` | `/tmp/logrotate.conman` | Path to generated logrotate configuration file. |
134+
| `--log-rotate-state-file-path` | `RCS_LOG_ROTATE_STATE_FILE_PATH` | `/tmp/rot_conman.state` | Path to logrotate state file. |
135+
136+
OAuth2 settings are all-or-nothing. If any OAuth2 field is set, all of
137+
`--oauth2-client-id`, `--oauth2-client-secret`, `--oauth2-token-url`, and
138+
`--oauth2-scopes` must be provided.
139+
140+
Logging is configured separately with these process environment variables:
141+
142+
| Environment variable | Default | Description |
143+
| --- | --- | --- |
144+
| `LOG_LEVEL` | `INFO` | Any level accepted by Go `slog`, such as `DEBUG`, `INFO`, `WARN`, or `ERROR`. |
145+
| `LOG_FORMAT` | `text` | Set to `json` for structured JSON logs. Any other value uses text logs. |
146+
147+
## License
148+
149+
This project is licensed under the MIT license. See [LICENSE](LICENSE) for
150+
details.

0 commit comments

Comments
 (0)