Artemis > For Administrators > Beaker driver

Beaker driver

Beaker

Credentials

When Beaker access is protected by authentication, driver can be configured to include credentials when talking to its backend.

Specification

username: <string>
password: <string>

Example

username: a-beaker-username
password: corresponding-password

Beaker groups

To avoid provisioning machines owned by particular Beaker groups, driver can be configured to avoid them.

Specification

avoid-groups:
  - group-1
  - group-2
  ...

Example

avoid-groups:
  # While our Beaker account has access to these groups, don't provision machines owned by them.
  - special-gpus
  - laptops

Each provisioning Beaker job would then contain two sets of elements to implement this behavior:

<group op="!=" value="$groupname"/> to instruct Beaker to avoid this group,
<hostname op="!=" value="$hostname"/> to instruct Beaker to avoid machines owned by these groups.

The list of machines owned by each group is cached, updated periodically by querying Beaker API.

Tip:

It is possible to configure multiple pools for the same set of Beaker credentials, each with different avoid-groups list. For example:

# pool #1
avoid-groups:
  - laptops

# pool #2
avoid-groups:
  - generic-group-owning-machines-not-owned-by-any-other-group

This way, common guest requests can be routed to pool #1, while requests in the need of a special laptop HW would be routed to pool #2.

Beaker hostnames

To avoid provisioning particular machines, driver can be configured to avoid them.

Specification

avoid-hostnames:
  - hostname-1
  - hostname-2
  ...

Example

avoid-hostnames:
  # The following machines are not to be used for day-to-day jobs.
  - some.valuable.machine.com
  # This is a special laptop we do not want to use at all.
  - big-boss.foo.com

Each provisioning Beaker job would then contain a set of <hostname/> elements to instruct Beaker to avoid the listed machines.

Tip:

It is possible to configure multiple pools for the same set of Beaker credentials, each with different avoid-hostnames list. For example:

# pool #1
avoid-hostnames:
  - fancy1.foo.com
  - fancy2.foo.com

# pool #2
avoid-hostnames:
  # Can use fancyN machines, but...
  - not-so-fancy1.foo.com
  - not-so-fancy2.foo.com

Beaker pools

A pool can be pinned to use only a specific subset of Beaker machines by requesting them to belong to one or more Beaker pools.

Specification

pools:
  - poolname-1
  - poolname: poolname-2
  - poolname: poolname-3
    system-type: system-type-1
  ...

Example

pools:
  # Provision machines belonging to the following Beaker pools.
  - some-pool
  - another-pool
  - poolname: yet-another-pool
  # Same but with this pool, we need to use different system type for provisioning.
  - poolname: custom-laptops
    system-type: Laptop

Each provisioning Beaker job would then contain a set of <pool/> elements, with <system_type/> as needed, to instruct Beaker to pick only machines from specified pools.

Tip:

It is possible to configure multiple pools for the same set of Beaker credentials, each with different pools list. For example:

# pool #1
pools:
  - some-pool

# pool #2
pools:
  - some-pool
  # Can use fancy machines as well!
  - pool-with-very-fancy-machines

Distro variants

A compose can be mapped to a particular distro variant, Server, Workstation or any other offered by the distro. By default, no specific variant is requested from Beaker.

Specification

- 'compose1':          'distro1'
- 'compose1-Variant1': 'distro1;variant=Variant1'
- 'compose1-Variant2': 'distro1;variant=Variant2'

Example

# Basic mapping for Fedora Rawhide, Beaker will pick the default variant for us.
- 'Fedora-Rawhide': 'Fedora-Rawhide'
# For users interested in a particular variant, prepare composes with precise mapping.
- 'Fedora-Rawhide-Server': 'Fedora-Rawhide;variant=Server'
- 'Fedora-Rawhide-Everything': 'Fedora-Rawhide;variant=Everything'

When variant key is specified in the right-hand side of the image mapping, it is propagated to Beaker job via distro_variant element, to instruct Beaker to provide the given distro variant. Without the variant key, no distro_variant element is emitted.

AVC denials during installation

AVC denials during installation are a common issue that may appear in early development phases of development of new OS version. Beaker would mark an affected job as "failed", and, by default, Artemis would terminate the job and retry. failed-avc-result-patterns and ignore-avc-on-compose-pattern keys lets maintainers to detect such situations and specify composes for which a Beaker job may failed because of AVC denials and be still accepted.

Specification

failed-avc-result-patterns:
  - <pattern1>
  - <pattern2>
  ...
ignore-avc-on-compose-pattern: <pattern>

Example

# All jobs where `/distribution/check-install` task fails because of AVC denials would be considered.
failed-avc-result-patterns:
  - "/distribution/check-install:Fail:Completed:/10_avc_check:Fail"

# AVC denials appear when installing new Fedora 55, they will be fixed next week.
# For now, let users test their components.
ignore-avc-on-compose-pattern: "(?i)fedora-55"

failed-avc-result-patterns specifies a list of patterns. If all of them match at least one task result, the job would be then checked against ignore-avc-on-compose-pattern pattern. failed-avc-result-patterns patterns are matched against a combination of task result fields: task name, task result, task status, phase name and phase result. Phase name and phase result may be empty strings if Beaker XML does not specify them.

For example, task results as reported in Beaker job result XML:

<task name="/distribution/check-install" result="Fail" status="Completed">
  <result path="/distribution/check-install" result="Pass"/>
  <result path="/10_avc_check" result="Fail"/>
  <result path="/distribution/check-install/Sysinfo" result="Pass"/>

<task name="/distribution/reservesys" result="New" status="Running" >
  <result path="/distribution/reservesys" result="Pass" />

would be converted into the following lines:

/distribution/check-install:Fail:Completed:/distribution/check-install:Pass
/distribution/check-install:Fail:Completed:/10_avc_check:Fail
/distribution/check-install:Fail:Completed:/distribution/check-install/Sysinfo:Pass
/distribution/reservesys:New:Running:/distribution/reservesys:Pass

Installation method

With the help of installation-method-map key, it is possible to specify a custom installation method in the case of need. The key holds a mapping between regular expressions, matching compose/distro, and corresponding methods. If the compose/distro of a request matches one of the patterns, its method is added to Beaker job XML.

Patterns are matched against a combination of multiple guest request properties: request compose and architecture, and corresponding Beaker distro and optionally its variant, if set. All four components are separated with a colon, :. For example, a guest request for Fedora 55 on x86_64, mapped to Fedora-55-20240522.0 distro, would yield the following string for patterns to match: Fedora-55:x86_64:Fedora-55-20240522.0:Server.

Specification

installation-method-map:
  <pattern>: <string>
  <pattern>: <string>
  ...

Example

# There is a bug in Fedora 55 installation that requires HTTP method to be used.
installation-method-map:
  "(?i)^fedora-55.*": "http"