Команда: 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 нельзя использовать вместе с параметром -destroy.

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

  Примечание

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

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

  Примечание

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

• -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 требуется непосредственное строковое значение без специальных знаков препинания, кроме тех, которые необходимы для вашей оболочки, как показано в примерах выше. Для всех остальных ограничений типов, включая типы списков, отображений и множеств, а также специальное ключевое слово 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 или -exclude, чтобы ограничить внимание OpenTofu подмножеством ресурсов. Параметр -target ограничивает внимание OpenTofu ресурсами и модулями, на которые он непосредственно нацелен, а также их зависимостями. Параметр -exclude ограничивает внимание OpenTofu ресурсами и модулями, которые не исключены напрямую и не зависят от исключенных ресурсов или модулей.

Для выбора нескольких ресурсов и модулей можно использовать несколько флагов -target, а для исключения нескольких ресурсов и модулей — несколько флагов -exclude. Нельзя одновременно использовать флаги -target и -exclude.

Для указания ограничения можно использовать синтаксис адреса ресурса. OpenTofu интерпретирует адрес ресурса следующим образом:

• Если указанный адрес идентифицирует конкретный экземпляр ресурса, OpenTofu выберет только этот экземпляр. Для ресурсов, у которых заданы count или for_each, адрес экземпляра ресурса должен содержать индекс экземпляра, например aws_instance.example[0].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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