Команда: state mv

Основная функция состояния OpenTofu — отслеживать связи между адресами экземпляров ресурсов в вашей конфигурации и удалёнными объектами, которые они представляют. Обычно OpenTofu автоматически обновляет состояние в ответ на действия, выполняемые при применении плана, например удаляет связь с удалённым объектом, который был удалён.

Вы можете использовать tofu state mv в менее распространённой ситуации, когда хотите сохранить существующий удалённый объект, но отслеживать его под другим адресом экземпляра ресурса в OpenTofu — например, если вы переименовали блок ресурса или переместили его в другой модуль конфигурации.

Использование​

Использование: tofu state mv [options] SOURCE DESTINATION

OpenTofu найдёт в текущем состоянии экземпляр ресурса, ресурс или модуль, соответствующий указанному адресу, и, если поиск будет успешным, перенесёт удалённые объекты, связанные с источником, чтобы вместо этого отслеживать их по адресу назначения.

Адреса источника и назначения должны соответствовать синтаксису адресов ресурсов и относиться к объектам одного типа: можно переместить только экземпляр ресурса в другой экземпляр ресурса, целый экземпляр модуля — в другой целый экземпляр модуля и т. д. Кроме того, ресурс или экземпляр ресурса можно переместить только по новому адресу с тем же типом ресурса.

Чаще всего tofu state mv используют после переименования блока ресурса в конфигурации или перемещения блока ресурса в дочерний модуль, если нужно сохранить существующий объект, но отслеживать его под новым именем. По умолчанию OpenTofu воспринимает перемещение или переименование конфигурации ресурса как запрос на удаление старого объекта и создание нового по новому адресу. Поэтому tofu state mv позволяет переопределить такую интерпретацию, заранее связав существующий объект с новым адресом в OpenTofu.

Эта команда также принимает следующие параметры:

• -dry-run — выводит все экземпляры ресурсов, соответствующие указанному адресу, но не выполняет фактическое «забывание» ни одного из них.

• -lock=false — не блокирует состояние на время операции. Это опасно, если другие пользователи могут одновременно выполнять команды в том же рабочем пространстве.

• -lock-timeout=DURATION — если блокировка не отключена с помощью -lock=false, указывает OpenTofu повторять попытки получения блокировки в течение заданного времени, прежде чем вернуть ошибку. Длительность задаётся числом и буквой единицы времени, например «3s» — три секунды.

• -var 'NAME=VALUE' — задаёт значение одной входной переменной, объявленной в корневом модуле конфигурации. Используйте этот параметр несколько раз, чтобы задать значения нескольких переменных. Дополнительные сведения см. в разделе Входные переменные в командной строке.

• -var-file=FILENAME — задаёт значения нескольких входных переменных, объявленных в корневом модуле конфигурации, используя определения из файла «tfvars». Используйте этот параметр несколько раз, чтобы загрузить значения из нескольких файлов.

• -json — включает вывод машиночитаемого JSON-интерфейса.

• -json-into=out.json — формирует такой же вывод, как -json, но перенаправляет его в файл. Это позволяет одновременно сохранять машиночитаемые и удобочитаемые журналы.

Помимо параметров -var и -var-file, есть несколько других способов задать значения входных переменных корневого модуля. Дополнительные сведения см. в разделе Задание значений переменных корневого модуля.

В конфигурациях, использующих только бэкенд cloud или бэкенд remote, команда tofu state mv также принимает параметр -ignore-remote-version.

Устаревшие параметры -backup и -backup-out применяются только к локальному файлу состояния. Чтобы использовать параметры -backup и -backup-out, конфигурации с бэкендом remote должны указать локальный файл состояния с помощью параметра -state.

Только для конфигураций, использующих локальное состояние local, команда tofu state mv также принимает устаревшие параметры -state, -state-out, -backup и -backup-out.

Пример: переименование ресурса​

Переименование ресурса подразумевает изменение конфигурации, например, следующим образом:

-resource "packet_device" "worker" {
+resource "packet_device" "helper" {
   # ...
 }

Чтобы сообщить OpenTofu, что новый ресурс «helper» следует считать переименованным старым ресурсом «worker», сопоставьте приведённое выше изменение конфигурации со следующей командой:

tofu state mv packet_device.worker packet_device.helper

Пример: перемещение ресурса в модуль​

Если изначально ресурс был объявлен в корневом модуле, но теперь вы хотите перенести его в дочерний модуль, переместите блок resource в конфигурацию дочернего модуля, удалите исходный блок из корневого модуля, а затем выполните следующую команду, чтобы сообщить OpenTofu о перемещении:

tofu state mv packet_device.worker module.worker.packet_device.worker

В приведённом выше примере у нового ресурса то же имя, но другой адрес модуля. При желании можно одновременно изменить имя ресурса, если новая организация модулей предполагает другую схему именования:

tofu state mv packet_device.worker module.worker.packet_device.main

Пример: перемещение модуля в другой модуль​

Также можно перенести целый модуль в дочерний модуль. В конфигурации переместите блок module, представляющий модуль, в другой модуль, а затем сопоставьте это изменение с такой командой:

tofu state mv module.app module.parent.module.app

Пример: перемещение определённого экземпляра ресурса с помощью count​

Ресурс, определённый с помощью метааргумента count, имеет несколько экземпляров, каждый из которых идентифицируется целым числом. Чтобы выбрать определённый экземпляр, укажите в адресе явный индекс:

$ tofu state mv 'packet_device.worker[0]' 'packet_device.helper[0]'

У ресурса, который не использует count или for_each, есть только один экземпляр, адрес которого совпадает с адресом самого ресурса. Поэтому можно перемещать ресурс с адреса без индекса на адрес с индексом и наоборот, если используемый тип адреса соответствует тому, применяется ли к каждому ресурсу соответствующая конфигурация и каким образом:

$ tofu state mv 'packet_device.main' 'packet_device.all[0]'

В некоторых оболочках квадратные скобки ([, ]) имеют особое значение, поэтому может потребоваться заключить адрес в кавычки или экранировать его, чтобы передать OpenTofu без изменений. В примерах выше показан типичный синтаксис заключения в кавычки для оболочек в стиле Unix.

Пример: перемещение ресурса, настроенного с помощью for_each​

Ресурс, определённый с помощью метааргумента for_each, имеет несколько экземпляров, каждый из которых идентифицируется строкой. Чтобы выбрать определённый экземпляр, укажите в адресе явный ключ.

Однако синтаксис строк предусматривает кавычки, а символ кавычки часто имеет особое значение в командных оболочках. Поэтому необходимо использовать подходящий синтаксис заключения в кавычки и/или экранирования для используемой оболочки. Например:

Оболочки в стиле Unix, например в Linux или macOS:

tofu state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'

Командная строка Windows (cmd.exe):

tofu state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]

PowerShell:

tofu state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'

Если не учитывать использование строк вместо целых чисел в качестве ключей экземпляров, работа с ресурсами for_each аналогична работе с ресурсами count. Поэтому, как описано в предыдущем разделе, допустимы те же сочетания адресов с компонентами индекса и без них.