Команда: plan

Команда tofu plan создает план выполнения, который позволяет предварительно просмотреть изменения, которые OpenTofu планирует внести в вашу инфраструктуру. По умолчанию при создании плана OpenTofu:

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

Команда plan сама по себе не выполняет предложенные изменения. Вы можете использовать эту команду, чтобы проверить, соответствуют ли предложенные изменения вашим ожиданиям, прежде чем применить их или поделиться ими с командой для более широкой проверки.

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

Если вы используете OpenTofu непосредственно в интерактивном терминале и планируете применить предложенные изменения, вместо этого можно сразу выполнить команду tofu apply. По умолчанию команда «apply» автоматически создает новый план и предлагает вам подтвердить его.

Чтобы сохранить созданный план в файл на диске, который впоследствии можно будет выполнить, передав его команде tofu apply в качестве дополнительного аргумента, можно использовать необязательный параметр -out=FILE. Этот двухэтапный рабочий процесс предназначен главным образом для автоматизированного запуска OpenTofu.

Если выполнить tofu plan без параметра -out=FILE, будет создан предварительный план — описание результатов плана без намерения фактически применить его.

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

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

Использование: tofu plan [options]

Подкоманда plan ищет конфигурацию корневого модуля в текущем рабочем каталоге.

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

В следующих разделах этой страницы описаны различные параметры:

• Режимы планирования: существуют специальные альтернативные режимы планирования, которые можно использовать в отдельных ситуациях, когда ваша цель не сводится к приведению удаленной системы в соответствие с конфигурацией.
• Параметры планирования: помимо специальных режимов планирования, можно задавать и другие параметры, чтобы настроить процесс планирования для особых задач.
  • Выборочное управление ресурсами — это особый параметр планирования, использование которого сопряжено с важными ограничениями.
• Другие параметры: они меняют поведение самой команды планирования, а не настраивают содержимое созданного плана.

Режимы планирования​

В предыдущем разделе описано поведение OpenTofu при планировании по умолчанию: удаленная система приводится в соответствие с изменениями, внесенными в конфигурацию. В OpenTofu есть два альтернативных режима планирования, каждый из которых создает план с другим предполагаемым результатом. Эти параметры доступны как для tofu plan, так и для tofu apply.

• Режим уничтожения: создает план, цель которого — уничтожить все существующие удаленные объекты и оставить состояние OpenTofu пустым. Это аналог выполнения команды tofu destroy. Режим уничтожения может быть полезен, например, для временных сред разработки, в которых управляемые объекты становятся ненужными после завершения задачи разработки.

  Включите режим уничтожения с помощью параметра командной строки -destroy.

• Режим только обновления состояния: создает план, цель которого — только обновить состояние OpenTofu и выходные значения корневого модуля в соответствии с изменениями удаленных объектов, внесенными вне OpenTofu. Это может быть полезно, если вы намеренно изменили один или несколько удаленных объектов за пределами обычного рабочего процесса (например, при реагировании на инцидент) и теперь вам необходимо согласовать записи OpenTofu с этими изменениями.

  Включите режим только обновления состояния с помощью параметра командной строки -refresh-only.

Когда нужно обсудить режим планирования OpenTofu по умолчанию, который используется, если не выбран ни один из альтернативных режимов, мы называем его «обычным режимом». Поскольку эти альтернативные режимы предназначены только для особых ситуаций, в некоторых других документах OpenTofu описан только обычный режим планирования.

Режимы планирования взаимоисключающие: включение любого режима, отличного от режима по умолчанию, отключает «обычный» режим, и одновременно использовать несколько альтернативных режимов нельзя.

Параметры планирования​

Помимо альтернативных режимов планирования, есть несколько параметров, позволяющих изменить поведение планирования. Эти параметры доступны как для tofu plan, так и для tofu apply.

• -refresh=false — отключает поведение по умолчанию, при котором состояние OpenTofu синхронизируется с удаленными объектами перед проверкой изменений конфигурации. Это может ускорить планирование за счет сокращения количества запросов к удаленным API. Однако при задании refresh=false OpenTofu игнорирует внешние изменения, что может привести к неполному или неверному плану. Использовать refresh=false в режиме планирования только для обновления состояния нельзя, поскольку это фактически отключило бы всю операцию планирования.

• -replace=ADDRESS — указывает OpenTofu запланировать замену экземпляра ресурса с указанным адресом. Это полезно, если один или несколько удаленных объектов пришли в негодность и их можно заменить объектами с той же конфигурацией, чтобы придерживаться принципов неизменяемой инфраструктуры. OpenTofu выполнит действие «replace», если для указанного ресурса в обычном случае выполнялось бы действие «update» или не выполнялось бы никаких действий. Чтобы заменить несколько объектов одновременно, укажите этот параметр несколько раз. Нельзя использовать -replace вместе с параметром -destroy.

• -exclude=ADDRESS — указывает OpenTofu сосредоточить планирование только на экземплярах ресурсов, не соответствующих указанному исключаемому адресу, а также на ресурсах и модулях, которые от них не зависят.

  Примечание

  Используйте -exclude=ADDRESS только в исключительных случаях, например при устранении последствий ошибок или обходе ограничений OpenTofu. Подробнее см. в разделе Выборочное управление ресурсами.

• -exclude-file=FILENAME — аналог -exclude, но несколько адресов указываются в отдельном файле, а не непосредственно в командной строке.

• -target=ADDRESS — указывает OpenTofu сосредоточить планирование только на экземплярах ресурсов, соответствующих указанному адресу, и на объектах, от которых зависят эти экземпляры.

  Примечание

  Используйте -target=ADDRESS только в исключительных случаях, например при устранении последствий ошибок или обходе ограничений OpenTofu. Подробнее см. в разделе Выборочное управление ресурсами.

• -target-file=FILENAME — аналог -target, но несколько адресов указываются в отдельном файле, а не непосредственно в командной строке.

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

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

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

Входные переменные в командной строке​

Чтобы указать значения входных переменных, объявленных в корневом модуле, можно использовать параметр командной строки -var.

Однако для этого потребуется написать команду, которую смогут корректно разобрать и выбранная вами командная оболочка, и OpenTofu. Это может быть сложно для выражений с большим количеством кавычек и escape-последовательностей. В большинстве случаев мы рекомендуем вместо этого использовать параметр -var-file и записывать фактические значения в отдельный файл, чтобы OpenTofu мог разобрать их напрямую, а не интерпретировать результат разбора командной оболочкой.

При использовании -var в оболочке Unix-подобной системы, например Linux или macOS, мы рекомендуем заключать аргумент параметра в одинарные кавычки ', чтобы оболочка интерпретировала значение буквально:

tofu plan -var 'name=value'

Если в нужном вам значении есть одинарная кавычка, ее также потребуется экранировать для корректной интерпретации оболочкой. Для этого нужно временно завершить последовательность в кавычках, чтобы символ обратной косой черты стал специальным символом экранирования:

tofu plan -var 'name=va'\''lue'

При использовании OpenTofu в Windows мы рекомендуем командную строку Windows (cmd.exe). Передавая OpenTofu значение переменной из командной строки Windows, заключайте аргумент в двойные кавычки ":

tofu plan -var "name=value"

Если нужное вам значение содержит буквальные двойные кавычки, их потребуется экранировать обратной косой чертой:

tofu plan -var "name=va\"lue"

PowerShell в Windows не может корректно передавать буквальные кавычки внешним программам, поэтому мы не рекомендуем использовать OpenTofu в PowerShell под Windows. Вместо этого используйте командную строку Windows.

Подходящий синтаксис для записи значения переменной зависит от ее ограничения типа. Для примитивных типов string, number и bool ожидается прямое строковое значение без специальных знаков препинания, кроме тех, которые требуются вашей оболочке, как показано в примерах выше. Для всех остальных ограничений типа, включая типы list, map и set, а также специальное ключевое слово any, необходимо записать корректное выражение языка OpenTofu, представляющее значение, и добавить необходимые кавычки или символы экранирования, чтобы оболочка передала его OpenTofu без изменений. Например, для ограничения типа list(string):

# Unix-style shell
tofu plan -var 'name=["a", "b", "c"]'

# Windows Command Prompt (do not use PowerShell on Windows)
tofu plan -var "name=[\"a\", \"b\", \"c\"]"

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

Выборочное управление ресурсами​

Для выборочного управления ресурсами, при котором OpenTofu учитывает только часть экземпляров ресурсов, объявленных в конфигурации или отслеживаемых в текущем состоянии, можно использовать параметры -target, -target-file, -exclude и -exclude-file.

При использовании -target или -target-file OpenTofu учитывает только экземпляры ресурсов, соответствующие указанным целевым адресам, и экземпляры ресурсов, от которых они зависят.

При использовании -exclude или -exclude-file OpenTofu, наоборот, учитывает экземпляры ресурсов, не соответствующие указанным адресам, а также все объекты, которые от них зависят.

Положительное выборочное управление с помощью -target и -target-file несовместимо с отрицательным выборочным управлением с помощью -exclude и -exclude-file. В одной команде нельзя одновременно использовать параметры указания целевых объектов и параметры исключения.

Указывайте экземпляры ресурсов, которые нужно включить в выборку, используя синтаксис адреса ресурса. О параметрах -target и -exclude см. в разделе Адреса ресурсов в командной строке. О параметрах -target-file и -exclude-file см. в разделе Адреса ресурсов в файлах выборки.

OpenTofu выбирает экземпляры ресурсов по указанным адресам следующим образом:

• Если указанный адрес определяет один конкретный экземпляр ресурса, OpenTofu выберет только этот экземпляр.

  Для ресурсов, у которых задано count или for_each, адрес экземпляра ресурса должен включать индекс экземпляра, например aws_instance.example[0].

  Некоторые знаки препинания в адресе экземпляра ресурса, например кавычки и квадратные скобки, могут иметь специальное значение для вашей оболочки. Поэтому важно правильно заключать в кавычки или экранировать адреса экземпляров ресурсов, указанные непосредственно в командной строке с параметрами -target или -exclude, как описано в разделе Адреса ресурсов в командной строке.

• Если указанный адрес определяет ресурс целиком, OpenTofu выберет все его экземпляры. Для ресурсов, у которых задано count или for_each, это означает выбор всех индексов экземпляров, связанных с этим ресурсом в данный момент. У ресурсов с одним экземпляром (без count и for_each) адрес ресурса и адрес экземпляра ресурса совпадают, поэтому этот случай к ним не относится.

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

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

Вместо выборочного управления отдельными частями очень больших конфигураций рекомендуется разбивать их на несколько небольших конфигураций, которые можно применять независимо друг от друга. Используйте источники данных, чтобы получать сведения о ресурсах, объявленных в других конфигурациях. Это позволяет разбить сложную архитектуру системы на более удобные для управления части, которые можно обновлять независимо.

Другие параметры​

У команды tofu plan также есть другие параметры, относящиеся к вводу и выводу команды планирования, а не к настройке типа создаваемого OpenTofu плана. Эти параметры не обязательно доступны и для tofu apply, если иное не указано в документации к этой команде.

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

• -compact-warnings — выводит предупреждения в компактном виде, содержащем только сводные сообщения, за исключением случаев, когда предупреждения сопровождаются хотя бы одной ошибкой и их текст может служить полезным контекстом для ошибок.

• -consolidate-warnings=false — если OpenTofu выдает предупреждения, объединение сообщений выполняться не будет. Будут перечислены все расположения для всех предупреждений. Включено по умолчанию.

• -consolidate-errors — если OpenTofu выдает ошибки, попытаться объединить похожие сообщения в один элемент.

• -detailed-exitcode — возвращает подробный код завершения команды. При указании этого аргумента коды завершения и их значения меняются, чтобы предоставить более подробные сведения о содержимом созданного плана:

  • 0 = Выполнено успешно, различий нет (изменений нет)
  • 1 = Ошибка
  • 2 = Выполнено успешно, есть различия (имеются изменения)

• -generate-config-out=PATH — (экспериментальный параметр) Если в конфигурации присутствуют блоки import, указывает OpenTofu создавать HCL для всех импортированных ресурсов, которых еще нет в конфигурации. Конфигурация записывается в новый файл по указанному пути PATH. Такой файл не должен существовать заранее, иначе OpenTofu выдаст ошибку. Если планирование завершится с другой ошибкой, OpenTofu все равно может попытаться записать конфигурацию.

• -input=false — отключает поведение OpenTofu по умолчанию, при котором запрашивается ввод значений входных переменных корневого модуля, которым еще не присвоены значения. Этот параметр особенно полезен при запуске OpenTofu в автоматизированных системах без интерактивного взаимодействия.

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

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

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

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

• -no-color — отключает последовательности форматирования терминала в выводе. Используйте этот параметр, если OpenTofu запускается в среде, где вывод отображается системой, не поддерживающей форматирование терминала.

• -concise — отключает сообщения о ходе выполнения в выводе.

• -out=FILENAME — записывает созданный план в файл с указанным именем в непрозрачном формате. Впоследствии этот файл можно передать команде tofu apply для выполнения запланированных изменений, а также некоторым другим командам OpenTofu, поддерживающим сохраненные файлы планов.

  OpenTofu допускает любое имя файла плана, но обычно его называют tfplan. Не используйте в имени файла расширение, которое OpenTofu распознает как формат другого файла. Если вы используете расширение .tf или .tofu, OpenTofu попытается интерпретировать файл как исходный файл конфигурации, что приведет к синтаксическим ошибкам при последующем выполнении команд.

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

• -parallelism=n — ограничивает количество параллельных операций, выполняемых при обходе графа OpenTofu. По умолчанию — 10.

• -state=statefile — устаревший параметр, используемый только локальным сервером. Подробнее см. в документации локального сервера.

• -show-sensitive — если указан, конфиденциальные значения не будут скрываться в выводе интерфейса.

• -json — выводит данные в машиночитаемом формате JSON, подходящем для интеграции с текстовыми редакторами и другими автоматизированными системами.

• -deprecation — задает тип отображаемых предупреждений. Допустимые значения: «module:all», «module:local», «module:none». По умолчанию: «module:all». При выборе «module:all» OpenTofu отображает предупреждения об устаревании для всех модулей. При выборе «module:local» предупреждения отображаются только для модулей, импортированных по относительному пути. При выборе «module:none» все предупреждения об устаревании отбрасываются.

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

Указание другого каталога конфигурации​

Если ваш рабочий процесс требует переопределения каталога корневого модуля, вместо этого используйте глобальный параметр -chdir. Он работает со всеми командами и обеспечивает единообразный поиск OpenTofu в указанном каталоге всех файлов, которые обычно считываются или записываются в текущем рабочем каталоге.