Update the OpenCHAMI tutorial to use new fabrica-based services by davidallendj · Pull Request #100 · OpenCHAMI/openchami.org

davidallendj · 2026-06-01T18:02:10Z

Pull Request Template

Thank you for your contribution! Please ensure the following before submitting:

Checklist

My code follows the style guidelines of this project
I have added/updated comments where needed
I have added tests that prove my fix is effective or my feature works
I have run make test (or equivalent) locally and all tests pass
DCO Sign-off: All commits are signed off (git commit -s) with my real name and email
REUSE Compliance:
- Each new/modified source file has SPDX copyright and license headers
- Any non-commentable files include a <filename>.license sidecar
- All referenced licenses are present in the LICENSES/ directory

Description

This PR updates the existing tutorial to replace the old services with the new ones that are being added to the latest release based on OpenCHAMI/release#50. The tutorial already contains a section including boot-service but will now completely replace the BSS sections. In addition, instructions for metadata-service and tokensmith integration is added to replace cloud-init and haproxy/opaal respectively.

This PR is dependent on the following:

Type of Change

Bug fix
New feature
Breaking change
Documentation update

For more info, see Contributing Guidelines.

Signed-off-by: David Allen <davidallendj@gmail.com>

synackd

Thanks for this effort, @davidallendj! I haven't run through this yet, but had a few initial comments based on the content.

synackd · 2026-06-01T18:17:54Z

-export DEMO_ACCESS_TOKEN=$(sudo bash -lc 'gen_access_token')
+export DEMO_ACCESS_TOKEN=$(sudo podman exec tokensmith /bin/sh -c "/usr/local/bin/tokensmith user-token create --audience smd --key-file /tokensmith/data/keys/private.pem --subject 'admin@example.com' --scopes 'admin' --enable-local-user-mint")


Hmm... This is a rather large command. I anticipate that tutorial participants will mention this, so I wonder if we should put a note here saying that normally tokens are obtained through the identity provider, but we are doing this method for simplicity for the tutorial.

The original gen_access_token was a large command as well. The alternative would be to update the gen_access_token function to use the command above.

Looks like it's still being included in the release on PR 50. We can probably reuse that function and include the note here.

We'll just need to make sure the subject is configurable.

Do you mean for the tutorial or in general? If in general, we have want to make a few more of the flags configurable since these are user tokens.

Yeah thinking back now, for the tutorial it is fine but yeah in general. I'm wondering if we want to explain the flags in this command line that generates the token. I imagine participants will be curious (I know I am).

I don't think we should unless we introduce a section going more in-depth about tokensmith/security/JWTs in general and we actively configure the tokens within the tutorial itself, but I think that's a bit unnecessary for the main tutorial. I would rather try to keep the main parts as condensed and relevant to a new user getting all the services up and running and booting a node instead. If we do decide to add a section like that, I think it should be something like with the Slurm tutorial where we can show in more depth how changing the flags can be done in a meaningful way.

I do think that it's fine to point to the tokensmith documentation for more info about the flags here though. In fact, I think that would probably be helpful if referencing this section later.

synackd · 2026-06-01T18:18:19Z

-**Keep this command handy! Tokens expire after an hour.**
+**Keep this command handy! Tokens expire after a short period of time.**


When do tokens expire with the new tokensmith implementation?

I'm not sure, but by default I think it's something like 5 minutes. I don't think it's an hour though unless configured and since tokensmith was changing when I started this, I just put that in its place.

I think it's an hour if the --ttl flag default value is to be believed:

https://github.com/OpenCHAMI/tokensmith/blob/2add7cdd432d2b123af02400a633716df92f0cb1/cmd/tokenservice/user_token.go#L102

That makes sense. I think the 5 mins default was for the bootstrap token and not the user token.

That sounds right. Can we change this back to an hour?

synackd · 2026-06-01T18:21:10Z

-cat << EOF | sudo tee /etc/openchami/data/boot/bss/compute-debug-rocky9.yaml
+cat << EOF | sudo tee /etc/openchami/data/boot/compute-debug-rocky9.json


I think this was meant to stay YAML, yes? The instructions above use YAML as well.

No, this was supposed to all be in JSON since boot-service takes JSON for the --spec flag. I think I forgot to update the references there and remove the YAML part.

[rocky@openchami-testing boot-service]$ bin/client bootconfiguration create --help Create a new BootConfiguration. Examples: # Create from stdin echo '{"hosts": ["["item1","item2"]"], "macs": ["["item1","item2"]"], "nids": [], "groups": ["["item1","item2"]"], "kernel": "example-value", "initrd": "example-value", "params": "example-value", "priority": 42}' | client bootconfiguration create # Create with --spec flag client bootconfiguration create --spec '{"hosts": ["["item1","item2"]"], "macs": ["["item1","item2"]"], "nids": [], "groups": ["["item1","item2"]"], "kernel": "example-value", "initrd": "example-value", "params": "example-value", "priority": 42}' Spec fields: hosts ([]string) macs ([]string) nids ([]int32) groups ([]string) kernel (string) initrd (string) params (string) priority (int) Usage: client bootconfiguration create [flags] Flags: -h, --help help for create --spec string BootConfiguration specification in JSON format Global Flags: --config string config file (default is $HOME/.boot_service-cli.yaml) -o, --output string output format: table, json, yaml (default "table") --server string boot_service server URL (default "http://localhost:8080") --timeout duration request timeout (default 30s) --token string JWT bearer token -v, --version string API version to request (e.g., v1, v2beta1)

Right, but I noticed we are using ochami to add the boot configs, which supports -F yaml. Am I correct to presume that keeping it JSON is specifically for lines 2519 to 2527 where the boot-service client is optionally used?

Yes, but I think it would be better to change this section a bit. I'm thinking we could have a tabs with a YAML file using just ochami and another tab with JSON using both.

If we can keep it clean and straightforward, I am for it. 🙂

synackd · 2026-06-01T18:21:28Z

+
+{
+  "macs": [
+    "52:54:00:be:ef:01",
+    "52:54:00:be:ef:02",
+    "52:54:00:be:ef:03",
+    "52:54:00:be:ef:04",
+    "52:54:00:be:ef:05"
+  ],
+  "params": "nomodeset ro root=live:${URI_IMG} ip=dhcp overlayroot=tmpfs overlayroot_cfgdisk=disabled apparmor=0 selinux=0 console=ttyS0,115200 ip6=off cloud-init=enabled ds=nocloud-net;s=http://172.16.0.254:8081/cloud-init",
+  "kernel": "${URI_KERNEL}",
+  "initrd": "${URI_INITRAMFS}"
+
+}


Should this be YAML to match the YAML input above?

#100 (comment)

Signed-off-by: David Allen <davidallendj@gmail.com>

synackd

Whoops, looks like I never submitted my review.

I meant these to be instant comments but was reviewing at the same time so the responses are part of the review.

synackd · 2026-06-01T22:07:29Z

-ochami bss service status | jq
+curl https://demo.openchami.cluster:8443/boot-service/health


ochami v0.7.3 has boot service status we can use here.

Great. I was waiting for that change.

synackd · 2026-06-01T22:11:38Z

-export DEMO_ACCESS_TOKEN=$(sudo bash -lc 'gen_access_token')
+export DEMO_ACCESS_TOKEN=$(sudo podman exec tokensmith /bin/sh -c "/usr/local/bin/tokensmith user-token create --audience smd --key-file /tokensmith/data/keys/private.pem --subject 'admin@example.com' --scopes 'admin' --enable-local-user-mint")


We'll just need to make sure the subject is configurable.

synackd · 2026-06-01T22:12:59Z

-**Keep this command handy! Tokens expire after an hour.**
+**Keep this command handy! Tokens expire after a short period of time.**


I think it's an hour if the --ttl flag default value is to be believed:

https://github.com/OpenCHAMI/tokensmith/blob/2add7cdd432d2b123af02400a633716df92f0cb1/cmd/tokenservice/user_token.go#L102

synackd · 2026-06-01T22:14:53Z


 ```bash
-ochami bss boot params set -f yaml -d @/etc/openchami/data/boot/bss/compute-debug-rocky9.yaml
+sudo ochami config --system cluster set demo boot-service.uri: /boot-service


Did having the colon after boot-service.uri work for you? I don't think that is supposed to be there.

Interesting...I thought it was since I don't get an error when running that.

Hmm, wonder if that is a koanf thing. I assume ochami config --system cluster show demo cluster.boot-service.uri shows /boot-service?

It does, but I think that was set beforehand. I tried deleting that and trying again and this is what I see.

[rocky@openchami-testing ~]$ sudo ochami config --system cluster set demo boot-service.uri: /boot-service [rocky@openchami-testing ~]$ ochami config --system cluster show demo cluster.boot-service.uri [rocky@openchami-testing ~]$ sudo ochami config --system cluster set demo boot-service.uri /boot-service [rocky@openchami-testing ~]$ ochami config --system cluster show demo cluster.boot-service.uri

I double-checked the config and it doesn't look like the config file is being updated either for either command variant.

log: format: rfc3339 level: debug timeout: 30s default-cluster: demo clusters: - name: demo cluster: uri: https://demo.openchami.cluster:8443 enable-auth: true

Here's the ochami version:

[rocky@openchami-testing ~]$ ochami version Version: 0.7.3 Tag: v0.7.3 Branch: HEAD Commit: f07bc1e13e8673ad69cc79091208288ea2510364 Git State: clean Date: 2026-05-13T22:16:44Z Go: go1.26.3 Compiler: gc Build Host: runnervmeorf1 Build User: runner

synackd · 2026-06-01T22:19:44Z

-cat << EOF | sudo tee /etc/openchami/data/boot/bss/compute-debug-rocky9.yaml
+cat << EOF | sudo tee /etc/openchami/data/boot/compute-debug-rocky9.json


Right, but I noticed we are using ochami to add the boot configs, which supports -F yaml. Am I correct to presume that keeping it JSON is specifically for lines 2519 to 2527 where the boot-service client is optionally used?

Signed-off-by: David Allen <davidallendj@gmail.com>

davidallendj added the documentation Improvements or additions to documentation label Jun 1, 2026

docs: initial update to tutorial with changes to services

08154d8

Signed-off-by: David Allen <davidallendj@gmail.com>

davidallendj force-pushed the allend/update-tutorial-with-new-services branch from fc69bed to 08154d8 Compare June 1, 2026 18:03

davidallendj marked this pull request as draft June 1, 2026 18:03

synackd requested changes Jun 1, 2026

View reviewed changes

fix: address PR changes and remove BSS section

db37645

Signed-off-by: David Allen <davidallendj@gmail.com>

synackd reviewed Jun 3, 2026

View reviewed changes

docs: minor changes and reorganized section 2.5.1

272f8be

Signed-off-by: David Allen <davidallendj@gmail.com>

		export DEMO_ACCESS_TOKEN=$(sudo bash -lc 'gen_access_token')
		export DEMO_ACCESS_TOKEN=$(sudo podman exec tokensmith /bin/sh -c "/usr/local/bin/tokensmith user-token create --audience smd --key-file /tokensmith/data/keys/private.pem --subject 'admin@example.com' --scopes 'admin' --enable-local-user-mint")

		Keep this command handy! Tokens expire after an hour.
		Keep this command handy! Tokens expire after a short period of time.

		cat << EOF \| sudo tee /etc/openchami/data/boot/bss/compute-debug-rocky9.yaml
		cat << EOF \| sudo tee /etc/openchami/data/boot/compute-debug-rocky9.json

		ochami bss service status \| jq
		curl https://demo.openchami.cluster:8443/boot-service/health

Conversation

davidallendj commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Template

Checklist

Description

Type of Change

Uh oh!

synackd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidallendj Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidallendj Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidallendj Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

synackd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidallendj commented Jun 1, 2026 •

edited

Loading

davidallendj Jun 3, 2026 •

edited

Loading

davidallendj Jun 1, 2026 •

edited

Loading

davidallendj Jun 1, 2026 •

edited

Loading