docs: add reference snippets for deployment #1093

edibotopic · 2025-09-25T16:48:12Z

An important use-case for authd is deploying at scale when, for example, an organisation has multiple user machines that need to authenticate with a cloud provider.

This PR adds reference paged with code snippets for remote script execution using Landscape and provisioning with cloud-init.

UDENG-7785

docs/reference/code/readme

docs/reference/landscape-script.md

adombeck

It's really cool that you got this to work, and it's great for testing the command snippets on a local machine.

However, I'm not sure if the spread + multipass approach is a suitable solution for CI, which is arguably the more important use case, to continuously test that the docs are up to date. In the CI, we don't need to fetch and launch a VM, because we're already running on a disposable system of our choice. Downloading a VM image each time in the CI is slow and resource-intensive. So I would prefer a solution which allows us to just execute the command blocks on the current system. Then for running the test on a local machine, we can spin up a VM or container and execute the test in there (which could just be done in a shell script, I don't think we need something like spread for that).

I did a quick search for a tool which extracts code blocks from markdown to execute them, and there are a few, but nothing that seems to be widely used or an obvious ideal candidate, so we might need to do some more research and try things out.

Anyway, I don't consider having tests a blocker to merging the cloud-init and landscape documentation, especially since they do indeed closely correspond to the documentation we already have.

edibotopic · 2025-09-26T11:55:28Z

Thanks @adombeck !

Anyway, I don't consider having tests a blocker to merging the cloud-init and landscape documentation, especially since they do indeed closely correspond to the documentation we already have.

I agree, they do closely align and I don't think that the maintenance burden would be too high for that reason.

not sure if the spread + multipass approach is a suitable solution for CI

Multipass would not be used for the CI, but only for local tests. So, in this current implementation, the question is whether this is useful for local testing.

Here's the spread test Charmcraft uses: https://github.com/canonical/charmcraft/blob/main/spread.yaml and the corresponding workflow: https://github.com/canonical/charmcraft/blob/main/.github/workflows/spread-docs.yaml

I believe they use Multipass for local tests and a Google backend for CI, but I'm not sure. I/we would need to ask one of their engineers how they handle the CI.

I think that spread testing would have some merit, even if only used locally for people handling docs, but especially if we had more test cases across the documentation in future (e.g., multiple brokers with specific configurations).

For now, I'm happy to leave this as an experiment for further research, and push the page with a cloud-init version added.

adombeck · 2025-09-26T12:02:59Z

I believe they use Multipass for local tests and a Google backend for CI, but I'm not sure.

It looks like they configure the local system to support SSH login as root and then tell spread to connect to the localhost via SSH: https://github.com/canonical/charmcraft/blob/860b88ecdbc549954f714865058818b5c4ac344f/spread/.extension#L102-L116

That could also work for us.

I think that spread testing would have some merit, even if only used locally for people handling docs, but especially if we had more test cases across the documentation in future (e.g., multiple brokers with specific configurations).

I agree.

For now, I'm happy to leave this as an experiment for further research, and push the page with a cloud-init version added.

With the approach from Charmcraft for using spread with localhost in the CI, I'm now optimistic that we can do something similar. I still wouldn't block on that, so in my opinion you can go ahead and create a PR for adding the page without tests.

edibotopic · 2025-09-26T12:13:59Z

Thanks @adombeck -- I'll finalise next pulse 👍

* Removes spread testing * Adds tabs for brokers * Adds links * Minor rewriting and restructuring

* Follows Landscape deploy ref closely

edibotopic · 2025-10-01T11:53:08Z

@adombeck --- I'm marking this as ready to review.

I removed the automated testing and refactored into a standard doc, with tabs for the brokers like elsewhere.

I also added an equivalent reference page for cloud init.

adombeck · 2025-10-01T12:03:02Z

@edibotopic could you please also adapt the PR description (which at least by default is used as the merge commit message)?

edibotopic · 2025-10-01T12:04:35Z

could you please also adapt the PR description (which at least by default is used as the merge commit message)?

Yes! I forgot that.

Also, I'm not sure what's going on with the CLA (edit: passed now).

adombeck · 2025-10-01T12:06:25Z

Also, I'm not sure what's going on with the CLA.

The error is "read ETIMEDOUT" which seems like a network issue, so nothing we need to care about.

adombeck · 2025-10-01T12:10:58Z

docs/reference/landscape-deploy.md

+
+```shell
+add-apt-repository -y ppa:ubuntu-enterprise-desktop/authd
+apt update && apt upgrade -y


We don't need apt update after add-apt-repository. It was removed from the other docs in a37558a.

Not sure why we would want apt upgrade here, I don't see that being used anywhere in the docs (even before a37558a). If there's no good reason for it, I would remove that too.

Can remove.

adombeck · 2025-10-01T12:11:19Z

docs/reference/landscape-deploy.md

+
+```shell
+add-apt-repository -y ppa:ubuntu-enterprise-desktop/authd
+apt update && apt upgrade -y


adombeck · 2025-10-01T12:14:32Z

docs/reference/landscape-deploy.md

+```shell
+add-apt-repository -y ppa:ubuntu-enterprise-desktop/authd
+apt update && apt upgrade -y
+apt-get install -y authd gnome-shell yaru-theme-gnome-shell


Why do we only install gnome-shell and yaru-theme-gnome-shell in the Entra ID tab and not in the Google tab?

If we want to install it or not depends on whether the system is Ubuntu Desktop or Ubuntu Server. Maybe you intended to name the tabs "Ubuntu Desktop" and "Ubuntu Server", same as in https://documentation.ubuntu.com/authd/stable-docs/howto/install-authd/#install-authd?

It should be both. Will fix.

docs/reference/landscape-deploy.md

adombeck · 2025-10-01T12:40:17Z

docs/reference/landscape-deploy.md

+add-apt-repository -y ppa:ubuntu-enterprise-desktop/authd
+apt update && apt upgrade -y
+apt-get install -y authd
+snap install authd-google


Most if not all commands on this page require root privileges, so we should probably prefix all of them with sudo, similar to how we do it on the install and configure pages, right?

In Landscape, when deploying the script, the admin can opt for the script to be run as the root user on the client machine.

Ah okay, that changes things. Then indeed we don't need sudo and can use echo >> <file> to write to files.

docs/reference/landscape-deploy.md

adombeck · 2025-10-01T12:51:28Z

docs/reference/landscape-deploy.md

+
+```shell
+sed -i "s|<CLIENT_ID>|$CLIENT_ID|g; s|<ISSUER_ID>|$ISSUER_ID|g" /var/snap/authd-msentraid/current/broker.conf
+echo "ssh_allowed_suffixes = @test.onmicrosoft.com" >> /var/snap/authd-msentraid/current/broker.conf


Unless the user pastes this snippet into a root shell, we will have to use tee to write to the config file (sudo echo >> <file> doesn't work because the file redirection is not affected by sudo):

Suggested change

echo "ssh_allowed_suffixes = @test.onmicrosoft.com" >> /var/snap/authd-msentraid/current/broker.conf

sudo tee -a /var/snap/authd-msentraid/current/broker.conf > /dev/null <<EOF

ssh_allowed_suffixes = @test.on-microsoft.com

EOF

We could also use sed to insert the line below the existing #ssh_allowed_suffixes = [...] line:

Suggested change

echo "ssh_allowed_suffixes = @test.onmicrosoft.com" >> /var/snap/authd-msentraid/current/broker.conf

sudo sed -i '/^#ssh_allowed_suffixes/ a ssh_allowed_suffixes = @test.onmicrosoft.com' /var/snap/authd-msentraid/current/broker.conf

When deploying the scripts using Landscape, I think it would be done remotely by an admin via a root shell on the client machine.

I think I have a brief note about running as root at the end, but it might be beneficial to mention it at the start for context.

We just don't want to devote too much space to documenting the Landscape behemoth.

The note at the end is also fine, whichever you prefer.

docs/reference/landscape-deploy.md

Co-authored-by: adombeck <[email protected]>

docs/reference/landscape-deploy.md

Co-authored-by: adombeck <[email protected]>

adombeck · 2025-10-01T13:41:38Z

docs/reference/cloud-init-deploy.md

+{% set ISSUER_ID = '<your_issuer_id>' %}
+{% set CLIENT_ID = '<your_client_id>' %}


I don't think this is valid YAML. is it some special cloud-init syntax?

Yes. It's jinja I believe. That's why I didn't set the highlighter to YAML.

Cloud configs with cloud-init support Jinja templating, although it requires a pre-amble. I could add that or reference the docs.

Alternatively, and perhaps more simply, we could just insert the placeholders in the main YAML content.

adombeck · 2025-10-01T13:44:31Z

docs/reference/cloud-init-deploy.md

+  - sed -i 's|<CLIENT_ID>|{{ CLIENT_ID }}|g; s|<ISSUER_ID>|{{ ISSUER_ID }}|g' /var/snap/authd-msentraid/current/broker.conf
+  - echo 'ssh_allowed_suffixes = @test.onmicrosoft.com' >> /var/snap/authd-msentraid/current/broker.conf
+  - sed -i 's/^\(LOGIN_TIMEOUT\t\t\)[0-9]\+/\1360/' /etc/login.defs
+  - mkdir -p /etc/authd/brokers.d/
+  - cp /snap/authd-msentraid/current/conf/authd/msentraid.conf /etc/authd/brokers.d/
+  - snap restart authd-msentraid
+  - systemctl restart authd
+  - snap restart authd-msentraid
+  - systemctl restart ssh


Same changes as on the landscape page:

Suggested change

- sed -i 's|<CLIENT_ID>|{{ CLIENT_ID }}|g; s|<ISSUER_ID>|{{ ISSUER_ID }}|g' /var/snap/authd-msentraid/current/broker.conf

- echo 'ssh_allowed_suffixes = @test.onmicrosoft.com' >> /var/snap/authd-msentraid/current/broker.conf

- sed -i 's/^\(LOGIN_TIMEOUT\t\t\)[0-9]\+/\1360/' /etc/login.defs

- mkdir -p /etc/authd/brokers.d/

- cp /snap/authd-msentraid/current/conf/authd/msentraid.conf /etc/authd/brokers.d/

- snap restart authd-msentraid

- systemctl restart authd

- snap restart authd-msentraid

- systemctl restart ssh

- sed -i 's|<CLIENT_ID>|{{ CLIENT_ID }}|g; s|<ISSUER_ID>|{{ ISSUER_ID }}|g' /var/snap/authd-msentraid/current/broker.conf

- echo 'ssh_allowed_suffixes = @example.onmicrosoft.com' >> /var/snap/authd-msentraid/current/broker.conf

- sed -i 's/^\(LOGIN_TIMEOUT\t\t\)[0-9]\+/\1360/' /etc/login.defs

- mkdir -p /etc/authd/brokers.d/

- cp /snap/authd-msentraid/current/conf/authd/msentraid.conf /etc/authd/brokers.d/

- snap restart authd-msentraid

- systemctl restart authd ssh

3v1n0 · 2025-10-02T13:39:17Z

docs/reference/cloud-init-deploy.md

+  - gnome-shell # only needed for GDM login
+  - yaru-theme-gnome-shell # only needed for GDM login


Maybe we can just drop those, if cloud-init (or we force) to do a apt dist-upgrade that's enough to them get them all if they're runnig in a desktop, so we can omit them IMHO

And even from other docs I think we should not mention them, just to dist-upgrade maybe.

3v1n0 · 2025-10-02T22:56:39Z

docs/reference/cloud-init-deploy.md

+      UsePAM yes
+      KbdInteractiveAuthentication yes


Maybe here we can suggest that they can use

Match *@domain.ext UsePAM yes KbdInteractiveAuthentication yes

To ensure that the configuration applies only to the specific user

adombeck reviewed Sep 26, 2025

View reviewed changes

docs/reference/code/readme Outdated Show resolved Hide resolved

adombeck reviewed Sep 26, 2025

View reviewed changes

docs/reference/landscape-script.md Outdated Show resolved Hide resolved

adombeck reviewed Sep 26, 2025

View reviewed changes

docs/reference/landscape-script.md Outdated Show resolved Hide resolved

adombeck reviewed Sep 26, 2025

View reviewed changes

docs/reference/landscape-script.md Outdated Show resolved Hide resolved

adombeck reviewed Sep 26, 2025

View reviewed changes

edibotopic added 2 commits October 1, 2025 12:45

add doc on deployment script

b01e382

refactor Landscape deploy reference following review

b50bdc5

* Removes spread testing * Adds tabs for brokers * Adds links * Minor rewriting and restructuring

edibotopic force-pushed the docs-testable-deploy-snippets branch from cca3f8a to 26f3711 Compare October 1, 2025 11:46

add cloud init deploy reference

bc7d0ee

* Follows Landscape deploy ref closely

edibotopic force-pushed the docs-testable-deploy-snippets branch from 26f3711 to bc7d0ee Compare October 1, 2025 11:49

edibotopic marked this pull request as ready for review October 1, 2025 11:53

edibotopic requested a review from a team as a code owner October 1, 2025 11:53

edibotopic requested a review from adombeck October 1, 2025 11:53

edibotopic changed the title ~~docs: testable deploy snippets~~ docs: add reference snippets for deployment Oct 1, 2025

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Show resolved Hide resolved

edibotopic and others added 5 commits October 1, 2025 13:57

change Google suffix

364e1c7

Co-authored-by: adombeck <[email protected]>

more consistent suffix naming

06c4e44

Co-authored-by: adombeck <[email protected]>

condense restart commands

7cdfa0d

Co-authored-by: adombeck <[email protected]>

remove whitespace

18c8d75

Co-authored-by: adombeck <[email protected]>

condense more commands (squash)

3a54655

Co-authored-by: adombeck <[email protected]>

adombeck reviewed Oct 1, 2025

View reviewed changes

docs/reference/landscape-deploy.md Outdated Show resolved Hide resolved

remove redundant touch command

7a2b680

Co-authored-by: adombeck <[email protected]>

adombeck reviewed Oct 1, 2025

View reviewed changes

3v1n0 reviewed Oct 2, 2025

View reviewed changes

-echo "ssh_allowed_suffixes = @test.onmicrosoft.com" >> /var/snap/authd-msentraid/current/broker.conf
+sudo tee -a /var/snap/authd-msentraid/current/broker.conf > /dev/null <<EOF
+ssh_allowed_suffixes = @test.on-microsoft.com
+EOF

	echo "ssh_allowed_suffixes = @test.onmicrosoft.com" >> /var/snap/authd-msentraid/current/broker.conf
	sudo sed -i '/^#ssh_allowed_suffixes/ a ssh_allowed_suffixes = @test.onmicrosoft.com' /var/snap/authd-msentraid/current/broker.conf

		{% set ISSUER_ID = '<your_issuer_id>' %}
		{% set CLIENT_ID = '<your_client_id>' %}

		- gnome-shell # only needed for GDM login
		- yaru-theme-gnome-shell # only needed for GDM login

docs: add reference snippets for deployment #1093

Are you sure you want to change the base?

docs: add reference snippets for deployment #1093

Uh oh!

Conversation

edibotopic commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adombeck left a comment

Choose a reason for hiding this comment

Uh oh!

edibotopic commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Sep 26, 2025

Uh oh!

edibotopic commented Sep 26, 2025

Uh oh!

edibotopic commented Oct 1, 2025

Uh oh!

adombeck commented Oct 1, 2025

Uh oh!

edibotopic commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Oct 1, 2025

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!

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!

Uh oh!

Uh oh!

Uh oh!

adombeck Oct 1, 2025 • 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edibotopic Oct 1, 2025 • 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!

edibotopic commented Sep 25, 2025 •

edited

Loading

edibotopic commented Sep 26, 2025 •

edited

Loading

edibotopic commented Oct 1, 2025 •

edited

Loading

adombeck Oct 1, 2025 •

edited

Loading

edibotopic Oct 1, 2025 •

edited

Loading