Format and structure of a module package

TechPreview since MCC 2.26.0 (17.1.0 and 16.1.0)

A module package for day-2 operations is an archive that contains Ansible playbooks, metadata, and optionally a JSON-validation schema.

Requirements

  • Archive the file with the module package in the GZIP format.

  • Implement all playbooks for Ansible version used by a specific Cluster release of your Container Cloud cluster. For example, in Cluster releases 16.2.0 and 17.2.0, Ansible collection 5.10.0 and Ansible core 2.12.10 are used.

    To verify the Ansible version in a specific Cluster release, refer to Container Cloud Release notes: Cluster releases. Use the Artifacts > System and MCR artifacts section of the corresponding Cluster release. For example, for 17.3.0.

Note

Mirantis recommends implementing each module in modular approach avoiding a single module for everything. This ensures maintainability and readability, as well as improves testing and debugging. For details, refer to Global recommendations for implementation of custom modules.

Archive format

The common structure within a module archive is as follows:

  • main.yaml

    File name of the primary playbook that defines tasks to be executed.

  • metadata.yaml

    Metadata of the module such as name, version, and relevant documentation URLs.

  • schema.json

    Optional. JSON schema for validating module-specific configurations that are restricted values.

Metadata file format

The common structure of metadata.yaml is as follows:

  • name

    Required. Name of the module.

  • version

    Required. Version of the module.

  • docURL

    Optional. URL to the module documentation.

  • description

    Optional. Brief summary of the module, useful if the complete documentation is too detailed.

  • playbook

    Required. Path to the module playbook. Path must be related to the archive root that is directory/playbook.yaml if directory is a directory in the root of the archive.

  • valuesJsonSchema

    Optional. Path to the JSON-validation schema of the module. Path must be related to the archive root that is directory/schema.json if directory is a directory in the root of the archive.

  • deprecates

    Optional. Available since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0). List of modules that are deprecated by the module. For details, see Module deprecation.

  • supportedDistributions

    Optional. Available since Container Cloud 2.28.0 (Cluster releases 17.3.0 and 16.3.0). List of operating system distributions that are supported by the current module. An empty list means support of any distribution by the current module.

Example of metadata.yaml:

name: module-sample
version: 1.0.0
docURL: https://docs.mirantis.com
description: 'Module for sample purposes'
playbook: main.yaml
valuesJsonSchema: schema.json
deprecates:
  - name: another-module-to-deprecate
    version: 0.1.0

JSON-validation schema format

For description of JSON schema and its format, refer to JSON Schema official documentation.

Example of schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "kernel.panic": {"type": "string", "const": "1"}
  }
}

Playbook format

A playbook for a module must follow the rules of a particular Ansible version as mentioned in Requirements.

The only specific requirement for playbook format is to use the values variable that consists of values described in the inventory file.

Note

As hosts are selected in a HostOSConfiguration object, Mirantis recommends using hosts: all in module playbooks.

For example:

- name: <variable-name>
  hosts: all
  become: true
  tasks:
    - name: <value-name>
      module:
        name: "{{ item.key }}"
        value: "{{ item.value }}"
        state: present
        reload: yes
      with_dict: "{{ values }}"

Inventory format

An archive of a module does not require an inventory because the inventory is generated by lcm-controller while processing configurations. The format of the generated inventory is as follows:

all:
  hosts:
    localhost:
      ansible_connection: local
  vars:
    values:
{{- range $key, $value := .Values }}
      {{ $key }}: {{ $value }}
{{- end }}

The .Values parameter contains the values from the provided module configuration of the HostOSConfiguration object. For details, see Container Cloud documentation: HostOSConfiguration custom resource.