Skip to content

Latest commit

 

History

History
252 lines (175 loc) · 9.21 KB

CONTRIBUTING.md

File metadata and controls

252 lines (175 loc) · 9.21 KB
Raw

Contribution Guidelines

Note: This document may not display properly when viewed on https://galaxy.ansible.com/. Therefore, it is recommended to view it on github.com.

1. Introduction

This project provides an Ansible collection for managing the PRIMERGY series, a product of Fsas Technologies Inc.

  • Ansible modules to control nodes via iRMC, the remote management feature of PRIMERGY
  • Ansible roles to set up iRMC devices and Windows Servers based on PRIMERGY's "Environment and setting sheet"
  • Sample playbooks encompassing these modules and roles

This guideline provides information for maintainers and developers of this project.

2. Code of Conduct

This project adheres to the Ansible Community Code of Conduct.

3. Before You Start Developing

3.1 Prerequisites

3.2 Setting Up the Development Environment

  1. The directory structure is critical for running the project as an Ansible collection. Clone the repository as follows:

    $ mkdir -p ~/git/ansible_collections/fujitsu && cd $_
$ git clone https://github.com/fujitsu/fujitsu-ansible-irmc-integration.git primergy && cd $_
$ pwd
# => ~/git/ansible_collections/fujitsu/primergy

    The base path ~/git can be customized, but the repository must be cloned into the ansible_collections/fujitsu/primergy directory hierarchy.

  2. Set up the Python and Ansible execution environment. This project uses Rye to manage Python environments. Install rye as described in https://rye.astral.sh/guide/installation/. Rye automatically downloads and sets up the Python interpreter, so there is no need to prepare a separate Python runtime environment.

    $ rye sync
Initializing new virtualenv in ~/git/ansible_collections/fujitsu/primergy/.venv
Python version: [email protected]
(snipped)
Done!

    Commands installed via Rye can be executed through rye or by activating the virtual environments generated by rye sync.

    # Using Rye
$ rye run python -V
$ rye run ansible --version

# Activating the virtual environments
$ . .venv/bin/activate
$ python -V
$ ansible --version

    If not using Rye, ensure Python 3.10 or later is installed. Create and activate a virtual environments (venv), then install the required libraries:

    $ python -V
Python 3.10.14
$ python -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install -r requirements.lock -r requirements-dev.lock

  3. In the ansible.cfg file, specify the directory where the ansible_collections directory is located.

    [defaults]
collections_path = ~/git

  4. Prepare an inventory.ini file. This file must include the iRMC_group and windows groups with the necessary credentials and parameters for each target node. When managing Windows nodes with Ansible, WinRM connection settings are required.

    [iRMC_group]
<ipaddress-of-iRMC-device> irmc_user=admin irmc_password=<password>

[windows]
<ipaddress-of-windows> ansible_user=Administrator ansible_password=<password>

[iRMC_group:vars]
validate_certificate=false  # Required if SSL server certificates are not registered on the iRMC device.

[windows:vars]
ansible_port=5985
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore

  5. Run connectivity tests:

    • Test the connection to the iRMC device:

      $ ansible localhost -m fujitsu.primergy.irmc_facts -a "irmc_url=192.0.2.1 irmc_username=admin irmc_password=P@ssw0rd! validate_certs=false"
localhost | SUCCESS => {
    "changed": false,
    "facts": {
        "hardware": {
            "ethernetinterfaces": {

    • Test the connection to a Windows Server:

      $ ansible -i inventory.ini windows -m ansible.windows.win_ping
192.0.2.2 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

      If the connection to the Windows Server fails, please configure the firewall settings on the Windows Server:

      New-NetFirewallRule -Name "WinRM HTTP" -DisplayName "Allow WinRM over HTTP" -Enabled True -Direction Inbound -Protocol TCP -LocalPort 5985 -Action Allow

  6. Execute a playbook. Ensure that the inventory file (inventory.ini) includes the target device in the [iRMC_group] section. Run the following command to execute the role that registers a license on the iRMC device:

    ansible-playbook -i inventory.ini ./roles/irmc_set_license/tests/test.yml -e license_keys='["XXX"]' -vvv

    In this example, the license key ("XXX") is intentionally invalid. If you see an error message indicating "Invalid license key", it confirms that the role is functioning correctly.

4. Contribution Process

4.1 Reporting Issues and Bugs

  • Use GitHub Issues (or Bug WorkItems in internal development repository) to report problems or bugs.
  • Include the following information in your report:
    • Overview: A concise description of the problem.
    • Steps to Reproduce: Detailed reproduction steps.
    • Expected Behavior: Description of the expected outcome.
    • Error Messages: Attach error messages if applicable.
    • Environment Information: Python, Ansible versions, OS, and iRMC/BIOS versions.

4.2 Feature Suggestions

  • Use GitHub Issues (or Feature WorkItems in internal development repository) for new features or improvements.
  • Include the following information:
    • Summary: A concise description of the feature or improvement.
    • Purpose: Explain the purpose and problems addressed.

5. Coding Standards

The following coding standards are adopted to improve efficiency and code quality.

5.1 General

  • The overall coding style is defined in .editorconfig.
  • .editorconfig is compatible with EditorConfig, which works with many IDEs and editors.
  • Developers participating in this project are recommended to use tools that support .editorconfig.

5.2 Python

  • Use Ruff for linting. The configuration is defined in pyproject.toml.

  • To check the code, run the following command:

    ruff check ./plugins/filter/email_alert_profile_filters.py

5.3 Ansible

  • Use ansible-lint for static analysis of Ansible code:

    ansible-lint ./roles/irmc_email_alert

  • While some warnings may be challenging to resolve (e.g., due to restrictions on the devices and OSs that can be listed under platforms), address those warnings where possible.

  • The .ansible-lint configuration file allows you to control warnings.

5.4 Application of Coding Standards

  • These verification tools have been applied since July 2024. Older code may still contain warnings.
  • Since the application period is relatively short, there may still be room for adjustment of enabled/disabled rules or threshold values. Optimize these rules through discussions within the team.

6. Testing

6.1 Current State

  • Existing unit tests are placed in the ./tests directory, but they are not sufficiently comprehensive (as of December 2024).

6.2 Future Plans

Separation of Test Targets

  • Separate logic for requests to iRMC devices from other logic.
  • Focus on regression testing for logic unrelated to iRMC to improve maintainability.
  • Increase unit test coverage for the general logic, emphasizing stability.

Leveraging Molecule

  • Please consider using Molecule or similar to structure the testing environment.
  • However, consider the following constraints:
    • Most tests target iRMC device APIs, which are difficult to simulate in virtual environments like Docker.
    • Physical devices are required, and the delegated driver in Molecule must be used for testing.
    • Given the current practice of borrowing iRMC devices for development, incorporating them into long-term regression testing is impractical.
  • Preparing the framework for short-term testing may still be a viable option.

7. Documentation

  • User-facing documentation (manuals and Ansible runtime messages) must be written in English.
  • Documentation visible only to developers (this document and detailed comments in the code) may be written in Japanese.

8. License

GPL-3.0-or-later