Skip to main content

Migration Helper

Agent includes 3 commands to help migrate from existing OpenTofu state to Entigo Infralib modules: migrate-config, migrate-plan and migrate-validate.

Config command requires a OpenTofu v4 state file. Plan and validate commands require the state file and an OpenTofu plan file. Infralib state and plan files can be obtained from the bucket used by agent. It's possible to combine the approval type reject with run command argument steps to generate plan files without applying them for the chosen steps. Plan files need to be manually converted into JSON format by using OpenTofu.

First generate an import configuration with migrate-config. Modify the generated lines to remove any resources that don't need migrating. If needed, split any config items into source and destination blocks. That's only necessary if source and destination don't have any matching fields from name, module and indexes.

Using the import config, generate OpenTofu import commands with the migrate-plan command. After executing the commands, run the pipelines with the approval type reject to generate a new plan. Optionally, use the migrate-validate command to validate the new plan along with the new state.

Migration Commands​

migrate-config​

Outputs a list of resources with instance indexes based on the state file that are not matched by the provided import file. More info in Migration Helper.

OPTIONS:

  • logging - logging level (debug | info | warn | error) (default: info) [$LOGGING]
  • state-file - path to the previous OpenTofu state file [$STATE_FILE]
  • import-file - optional, path to the import file [$IMPORT_FILE]

Example

bin/ei-agent migrate-config --state-file=state-file.json

migrate-plan​

Generates import and rm OpenTofu commands based on the input files. Warning! Always check the import and rm commands before executing them. More info in Migration Helper.

OPTIONS:

  • logging - logging level (debug | info | warn | error) (default: info) [$LOGGING]
  • state-file - path to the previous OpenTofu state file [$STATE_FILE]
  • plan-file - path to the OpenTofu plan file [$PLAN_FILE]
  • import-file - path to the import file [$IMPORT_FILE]
  • types-file - optional, path for type identifications file [$TYPES_FILE]

Example

bin/ei-agent migrate-plan --state-file=state-file.json --plan-file=plan.json --import-file=import-file.yaml

migrate-validate​

Validate an OpenTofu plan file based on the import config and infralib OpenTofu state. Outputs 3 types of warnings:

  1. If plan wants to create or remove a resource that should be in the infralib state file.
  2. If plan wants to create or remove a resource that has the same type as the type in the import file.
  3. If plan wants to change a value of a resource.

More info in Migration Helper.

OPTIONS:

  • logging - logging level (debug | info | warn | error) (default: info) [$LOGGING]
  • state-file - path to the new OpenTofu state file [$STATE_FILE]
  • plan-file - path to the OpenTofu plan file [$PLAN_FILE]
  • import-file - path to the import file [$IMPORT_FILE]

Example

bin/ei-agent migrate-plan --state-file=state-file.json --import-file=import-file.yaml

Import File​

Import configuration file is used to tell the migration commands which type of resources should be migrated.

import:
  - type: string
    name: string
    module: string
    index_keys: []int | []string
    source:
      module: string
      name: string
      index_key: int | string
      index_keys: []int | []string
    destination:
      module: string
      name: string
      index_key: int | string
      index_keys: []int | []string
  • type - type of the resource to import
  • name - optional, overwrites source and destination names
  • module - optional, overwrites source and destination modules
  • index_keys - optional, overwrites source and destination index_keys
  • source - source is a resource from the previous state file
  • destination - destination is a resource from the plan file
    • module - optional, module name of the resource
    • name - optional, name of the resource
    • index_key - optional, index key of the resource instance
    • index_keys - optional, index keys of the resource instance

If module and name are empty then agent will try to find the resource from the state/plan file based on the type. If there are more than 1 resource with that type then a warning is printed. Agent will generate import commands for all resources of that type.

Index key and index keys are mutually exclusive. Index keys can be used to map instances in different order to the new state. If index hasn't been set, then agent will use keys from state resource instances.

Plan command generates import commands for the destination resources and rm commands for the source resources.

Type Identifications File​

Type identifications file is used to map a resource type to an identification used by OpenTofu for the import command. Agent will replace any placeholder {} values with values from the resource instance attributes. Default file is located in migrate/types.yaml.

typeIdentifications:
  - identification: string
    listSeparator: string
    types: []string
  • identification - identification used by OpenTofu for the import command, e.g "{id}"
  • listSeparator - optional, separator for identification values that are lists, default /
  • types - list of resource types that use the identification