Команда: 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 обычно должна быть рассчитана на работу без дополнительных специальных параметров.

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

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

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

В предыдущем разделе описано поведение 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. Это может быть сложно для выражений с большим количеством кавычек и управляющих последовательностей. В большинстве случаев мы рекомендуем вместо этого использовать параметр -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\"]"

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

Выбор целевых ресурсов​

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

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

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