Команда: 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.

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