Команда: 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. Поэтому допустимы те же сочетания адресов с компонентами индекса и без них, которые описаны в предыдущем разделе.