Bundle migration to a new contract version

Adelya Zvyagintseva

This article describes the procedure for migrating bundles between contract versions. For each version, a list of changes required to migrate to the new contract version is provided.

Migration to a higher version requires sequential migration of all previous versions.

From the version 1.0 to 2.0

To migrate a bundle from the contract version 1.0 to 2.0, perform the following steps:

  1. Convert the action of the job type, since actions of the job type are not supported starting from the contract version 2.0. To do this:

    • Remove the type property.

    • Define script execution using the scripts parameter by moving the script and script_type parameters to it.

    • Specify the name and display_name attributes for each element in the scripts list.

    Example of an action with contract_version: 1.0:

    ---
  actions:
    check:
      ....
      type: job
      script_type: ansible
      script: ansible/playbooks/cluster/check_mm.yaml
      ....

    Example of an action with contract_version: 2.0:

    ---
  actions:
    check:
      ...
      scripts:
        - name: check
          display_name: Check
          script_type: ansible
          script: ansible/playbooks/cluster/check_mm.yaml

  2. Move the params parameter to the corresponding element of the scripts list. For contract_version: 1.0, the params parameter defined at the action level was inherited and applied to each subjob.

     
    Example of an action with contract_version: 1.0:

    ---
  actions:
    check:
      display_name: Check
      type: task
      scripts:
        - name: check
          display_name: Check
          script_type: ansible
          script: ansible/playbooks/cluster/check_mm.yaml
      params:
        actions:
          - stop

    Example of an action with contract_version: 2.0:

    ---
  actions:
    check:
      display_name: Check
      scripts:
        - name: check
          display_name: Check
          script_type: ansible
          script: ansible/playbooks/cluster/check_mm.yaml
          params:
            actions:
              - stop

  3. Remove the type and log_files properties from the actions section, as they are not supported starting from the contract version 2.0.

     
    Example of an action with contract_version: 1.0:

    ---
  actions:
    check:
      display_name: Check
      type: task
      log_files:
        - check
      scripts:
        - name: check
          display_name: Check
          script_type: ansible
          script: ansible/playbooks/cluster/check_mm.yaml

    Example of an action with contract_version: 2.0:

    ---
  actions:
    check:
      display_name: Check
# legacy attributes to be deleted
#      type: task
#      log_files:
#        - check
      scripts:
        - name: check
          display_name: Check
          script_type: ansible
          script: ansible/playbooks/cluster/check_mm.yaml

  4. Replace the scripts_jinja and config_jinja parameters with scripts_template and config_template by specifying the file path and the type of engine to process the file, since these parameters are not supported starting from the contract version 2.0.

    NOTE
    Make sure that the scripts_template and config_template parameters use stricter validation compared to the deprecated scripts_jinja and config_jinja parameters. Therefore, migrating to the new parameters may require adjustments to the Jinja2 templates.

     
    Example of an action with contract_version: 1.0:

    ---
  actions:
    install:
      display_name: Install
      type: task
      config_jinja: config_jinja/cluster/config.j2
      scripts_jinja: scripts_jinja/cluster/manage_install.j2
      states:
        available:
          - created

    Example of an action with contract_version: 2.0:

    ---
  actions:
    check:
      display_name: Check
      config_template:
        file:
          path: scripts_jinja/cluster/config.j2
        engine:
          type: jinja2
      scripts_template:
        file:
          path: scripts_jinja/cluster/manage_install.j2
        engine:
          type: jinja2
      states:
        available:
          - created

  5. Move the venv property to the object level (for example, a service), since it is not supported at the actions or upgrade level starting from the contract version 2.0.

    NOTE
    Starting from the contract version 2.0, the venv property is required for the cluster and provider objects.

    Example of an action with contract_version: 1.0:

    ---
- type: service
  name: hdfs
  actions:
    start:
      display_name: Start
      venv: 2.9
      ....
      states:
        available:
          - installed

    Example of an action with contract_version: 2.0:

    ---
- type: service
  name: hdfs
  venv: 2.9
  actions:
    start:
      display_name: Start
      ....
      states:
        available:
          - installed

  6. Migrate actions that use Ansible 2.8 (default) as the execution environment to version 2.16. The migration may require updates to existing Ansible playbooks and roles.

    NOTE
    Starting from the contract version 2.0, the venv property does not support the default and 2.8 values.
IMPORTANT

After making changes:

  1. Check that the bundle structure is correct.

  2. Make sure that the configuration is compatible with the contract version 2.0.

  3. Upload the updated bundle to ADCM and ensure that it successfully passes validation.

From the version 2.0 to 2.1

To migrate a bundle from the contract version 2.0 to 2.1, migrate actions that use Ansible 2.9 as the execution environment to the version 2.16. The migration may require updates to existing Ansible playbooks and roles.

NOTE
Starting from the contract version 2.1, the venv property no longer supports the 2.9 value.
Found a mistake? Seleсt text and press Ctrl+Enter to report it