Команда: 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». Используйте этот параметр несколько раз, чтобы включить значения из нескольких файлов.

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

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

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

Для конфигураций, использующих только локальное состояние 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, поэтому допустимы те же комбинации адресов с индексными компонентами и без них, что и в предыдущем разделе.