Using the orcharhino Ansible Collection

1. Introduction to orcharhino Ansible Collection

orcharhino Ansible Collection provides a set of Ansible modules for managing orcharhino. Using the modules, you can automate many aspects of orcharhino management.

1.1. Installing the orcharhino Ansible modules

Modules from the orcharhino Ansible Collection are provided by the ansible-collection-theforeman-foreman package. On your orcharhino Server, the package is installed by default. If you want to execute your playbooks on a different system, you must first install the package that provides them.

Note	You can execute your playbooks on any system that can reach the orcharhino API. This can also be your orcharhino Server itself.

Procedure

Install the ansible-collection-theforeman-foreman package:
```
# dnf install ansible-collection-theforeman-foreman
```

Verification

Display the list of Ansible modules that are now available on your system:
```
# ansible-doc --list theforeman.foreman
```

Next steps

You can now use the installed Ansible modules to execute playbooks.

1.2. Getting help with orcharhino Ansible Collection

Note	To view the built-in documentation, orcharhino Ansible Collection must be installed on your system. For more information, see Installing the orcharhino Ansible modules.

You can view the full built-in documentation for available modules with the following command:

# ansible-doc --list theforeman.foreman

You can view the built-in documentation for a particular module with the following command:

# ansible-doc theforeman.foreman.Module_Name

For example:

# ansible-doc theforeman.foreman.location

2. Creating a playbook with modules from orcharhino Ansible Collection

Ansible modules from the orcharhino Ansible Collection must be able to communicate with the orcharhino API over HTTPS. In your playbooks, include parameters specifying how to authenticate to enable the connection to API.

Important

Do not store sensitive credentials, such as username and password, directly in your playbooks or environment variables. The following examples use Ansible vault to manage sensitive data.

Prerequisites

A user account in orcharhino exists with permissions to perform the action defined in your playbook.
You have access to one of the following types of authentication credentials for that user:
- Username and password
- Username and Personal Access Token
- Kerberos ticket, if your orcharhino Server is configured to use FreeIPA as an external authentication source
A system that you will execute your playbook against. The following examples use localhost.

This system must be able to reach the orcharhino API. You can choose from these options:
- A system that can reach the orcharhino API directly. You can use your orcharhino Server, your orcharhino Proxy Servers, or any other system in your environment.
- A system without a direct connection to the orcharhino API that uses an HTTP proxy to connect to orcharhino.

Procedure

Store your sensitive variables in an encrypted file:
1. Create an Ansible vault. For example, to create a vault named My_Vault.yml:
  $ ansible-vault create My_Vault.yml
2. After the ansible-vault create command opens an editor, provide the required parameters in the key: value format.
  
  If you want to authenticate with orcharhino username and password:
  My_Username: My_Admin_User_Account My_Password: My_Admin_Password My_Server_URL: https://orcharhino.example.com
  If you want to authenticate with orcharhino username and Personal Access Token (PAT):
  My_Username: My_Admin_User_Account My_Password: My_PAT My_Server_URL: https://orcharhino.example.com
  If you want to authenticate with a Kerberos ticket:
  My_Server_URL: https://orcharhino.example.com
3. If you use an HTTP proxy to reach the orcharhino API, store it in the vault too:
  My_HTTP_Proxy: "http://proxy.example.com:8080"
4. Save your changes and close the editor. Ansible encrypts the data in the vault.

Create a playbook file that references the vault file:

Note

The following YAML snippets include the module_defaults keyword to pass vault variables as parameters to all modules from the theforeman.foreman.foreman group that are used in the playbook. Module defaults groups simplify parameter management by enabling you to define common parameters to groups of modules rather than having to pass the parameters to each module individually.

Provide details on how to authenticate to the orcharhino API.

If you are authenticating with orcharhino username and password or PAT, map the username, password, and server_url parameters to the contents of My_Vault.yml:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:

If you are authenticating with a Kerberos ticket, map the server_url parameter to the contents of My_Vault.yml and add use_gssapi: true to enable Kerberos authentication:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      server_url: "{{ My_Server_URL }}"
      use_gssapi: true
  tasks:

If you need to use an HTTP proxy to reach the orcharhino API, set the https_proxy environment variable:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  environment:
    https_proxy: "{{ My_HTTP_Proxy }}"
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:

In the tasks: section, define the tasks that you want your playbook to perform.

Validate the playbook syntax:
```
$ ansible-playbook --syntax-check --ask-vault-pass My_Playbook.yml
```
Note that this command only validates the syntax. It does not protect against a valid but incorrect configuration.

Run the playbook:

$ ansible-playbook --ask-vault-pass My_Playbook.yml

Example 1. Example Ansible playbook: Ensure that domain new.example.com exists in orcharhino

The theforeman.foreman.domain module can create, update, and delete domains. This example playbook uses theforeman.foreman.domain to ensure that a domain named new.example.com exists and is managed by orcharhino. For additional examples, see Example playbooks based on modules from orcharhino Ansible Collection.

- name: Domain management
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:
    - name: Ensure domain new.example.com exists
      theforeman.foreman.domain:
        name: new.example.com

The settings specified in the example playbook include the following:

vars_files: The name of the vault file that stores the variables My_Username, My_Password, and My_Server_URL.
module_defaults: The module defaults group that maps the variables from the vault file to the username, password, and server_url module parameters.
name: The name of the domain that you want to ensure exists in orcharhino.

For more information, see the Ansible module documentation with ansible-doc theforeman.foreman.domain.

Additional resources

For information about using Ansible vault, see Protecting sensitive data with Ansible vault in Ansible Community Documentation.
For information about using module defaults, see Module defaults in Ansible Community Documentation.

3. Example playbooks based on modules from orcharhino Ansible Collection

All playbooks based on modules from orcharhino Ansible Collection must include parameters detailing how to connect to the orcharhino API. The following examples use Ansible vault and module defaults group to provide these parameters, and they authenticate using a username and password. For more information, see Creating a playbook with modules from orcharhino Ansible Collection.

Additional resources

Use the ansible-doc --list theforeman.foreman command to display the orcharhino Ansible modules installed on your system.

3.1. Playbook example: Enable repositories and create a content view

This example playbook uses the following modules:

theforeman.foreman.repository_set
theforeman.foreman.content_view

The playbook ensures repositories are enabled and a content view that contains these repositories exists.

Before you run this playbook, ensure that you have uploaded a manifest and can access the Red Hat CDN.

- name: Ensure RHEL 9 repositories are enabled and a content view exists
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:
    - name: Ensure RHEL 9 BaseOS repositories are enabled
      theforeman.foreman.repository_set:
        name: "Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)"
        organization: "Default Organization"
        product: "Red Hat Enterprise Linux for x86_64"
        repositories:
        - releasever: "9"
        state: enabled
    - name: Ensure RHEL 9 AppStream repositories are enabled
      theforeman.foreman.repository_set:
        name: "Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)"
        organization: "Default Organization"
        product: "Red Hat Enterprise Linux for x86_64"
        repositories:
        - releasever: "9"
        state: enabled
    - name: Ensure a content view for RHEL 9 repositories exists
      theforeman.foreman.content_view:
        name: "RHEL 9 content view"
        organization: "Default Organization"
        repositories:
          - name: "Red Hat Enterprise Linux 9 for x86_64 - BaseOS RPMs 9"
            product: "Red Hat Enterprise Linux for x86_64"
          - name: "Red Hat Enterprise Linux 9 for x86_64 - AppStream RPMs 9"
            product: "Red Hat Enterprise Linux for x86_64"

For more information, see the Ansible module documentation with the following commands:

ansible-doc theforeman.foreman.repository_sync
ansible-doc theforeman.foreman.content_view

3.2. Playbook example: Synchronize repositories and publish a content view

This example playbook uses the following modules:

theforeman.foreman.repository_sync
theforeman.foreman.content_view_version

The playbook synchronizes repositories and publishes the content view that includes them.

Before you run this playbook, ensure that you have enabled the required repositories and created a content view. For an example playbook that ensures this, see Playbook example: Enable repositories and create a content view.

- name: Ensure RHEL 9 repositories are synced and content view is published
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:
    - name: Sync RHEL repositories
      theforeman.foreman.repository_sync:
        product: "Red Hat Enterprise Linux for x86_64"
        organization: "Default Organization"
    - name: Publish RHEL 9 content view
      theforeman.foreman.content_view_version:
        content_view: "RHEL 9 content view"
        organization: "Default Organization"

For more information, see the Ansible module documentation with the following commands:

ansible-doc theforeman.foreman.repository_sync
ansible-doc theforeman.foreman.content_view_version