Команда: plan

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

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

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

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

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

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

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

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

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

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

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

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

В оставшихся разделах этой страницы описаны различные параметры:

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

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

В предыдущем разделе описано поведение планирования 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 нельзя использовать вместе с параметром -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'

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

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, представляющее значение, и добавить необходимые кавычки или escape-символы, чтобы оболочка передала его 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 = успешно, пустой diff (изменений нет)
  • 1 = ошибка
  • 2 = успешно, непустой diff (есть изменения)

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

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

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

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