Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

plugins/modules/snap: improve documentation #8972

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+27 −9
Open

plugins/modules/snap: improve documentation #8972

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
835f0a7
plugins/modules/snap: improve documentation
locnnil Oct 3, 2024
b1383f6
undo helper setence about finding avaible snaps.
locnnil Oct 3, 2024
a569685
wip: adress reviews
locnnil Oct 4, 2024
fd7623e
fix: revert sentence
locnnil Oct 4, 2024
efed600
feat: improve explanation on snap options
locnnil Oct 4, 2024
b56a412
clean: remove duplicated and leave reference
locnnil Oct 4, 2024
f2be203
feat: add note about priviledge scalation and switch sentence position
locnnil Oct 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 27 additions & 9 deletions plugins/modules/snap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright (c) 2024, Lincoln Wallace (locnnil) <[email protected]>
# Copyright (c) 2021, Alexei Znamensky (russoz) <[email protected]>
# Copyright (c) 2021, Marcus Rickert <[email protected]>
# Copyright (c) 2018, Stanislas Lange (angristan) <[email protected]>
Expand Down Expand Up @@ -29,10 +30,9 @@
name:
description:
- Name of the snaps to be installed.
- Any named snap accepted by the C(snap) command is valid.
- - Any named snap accepted by the C(snap) command is valid.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- - Any named snap accepted by the C(snap) command is valid.
- Any named snap accepted by the C(snap) command is valid.

- >
Notice that snap files might require O(dangerous=true) to ignore the error
"cannot find signatures with metadata for snap".
O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details.
required: true
type: list
elements: str
Expand All @@ -47,10 +47,13 @@
type: str
classic:
description:
- Confinement policy. The classic confinement allows a snap to have
the same level of access to the system as "classic" packages,
like those managed by APT. This option corresponds to the C(--classic) argument.
This option can only be specified if there is a single snap in the task.
- Install a snap that has classic confinement.
- This option corresponds to the C(--classic) argument of the C(snap install) command.
- This level of confinement is permissive, granting full system access,
similar to that of traditionally packaged applications that don't use sandboxing mechanisms.
This option can only be specified when the task involves a single snap.
- See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.

type: bool
required: false
default: false
Expand All @@ -69,18 +72,33 @@
- Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied
to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
only be applied to active snaps.
- Options will only be applied when C(state) is set to V(present).
This is done after the necessary installation
or refresh (upgrade/downgrade) of all the snaps listed in O(name).
- See U(https://snapcraft.io/docs/configuration-in-snaps) for more details snap configuration options.

required: false
type: list
elements: str
version_added: 4.4.0
dangerous:
description:
- Install the given snap file even if there are no pre-acknowledged signatures for it,
meaning it was not verified and could be dangerous.
- Install the snap in dangerous mode, without validating its assertions and signatures.
- This is useful when installing local snaps that are either unsigned or have signatures that haven't been acknowledged.
- When installing locally built C(.snap) SquashFS files or downloading them from
sources other than the Snap Store, it is necessary to install in dangerous mode
with O(dangerous=true) due to the absence of signatures for these snaps.
- See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
type: bool
required: false
default: false
version_added: 7.2.0
notes:
- When performing privileged operations, such as installing snap packages or setting snap options,
it is necessary to escalate privileges by executing these operations as root.
This can be achieved by using V(become: true) in the module.
- For more details on privilege escalation in playbooks,
refer to U(https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html).
Comment on lines +96 to +101
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of things:

  • Privilege escalation is only relevant if the user is non-root.
  • For a non-privileged user, it is needed only when the user hasn't logged in to the snap store (snap login). For example, the user is always logged in when using a pre-built Ubuntu Core image that uses Console Conf. This can be checked with snap whoami.
  • become: true is a task parameter, not module.
  • I combined the bullets because this is all a single note.
Suggested change
notes:
- When performing privileged operations, such as installing snap packages or setting snap options,
it is necessary to escalate privileges by executing these operations as root.
This can be achieved by using V(become: true) in the module.
- For more details on privilege escalation in playbooks,
refer to U(https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html).
notes:
- Privileged operations, such as installing and configuring snaps, require root priviledges.
This is only the case if the user hasn't logged in to the Snap Store.
The privilege can be escalated by setting V(become: true) in the task.
For more details on privilege escalation in playbooks,
refer to U(https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of U(https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html), please use R(the documentation on playbook privilege escalation, playbooks_privilege_escalation). That will generate links to the documentation of the correct Ansible version in the HTML docs.

(Probably better reformulate the whole sentence.)


author:
- Victor Carceler (@vcarceler) <[email protected]>
Expand Down
Loading