Documentation
¶
Overview ¶
Package configupgrade upgrades configurations targeting our legacy configuration loader (in package "config") to be compatible with and idiomatic for the newer configuration loader (in package "configs").
It works on one module directory at a time, producing new content for each existing .tf file and possibly creating new files as needed. The legacy HCL and HIL parsers are used to read the existing configuration for maximum compatibility with any non-idiomatic constructs that were accepted by those implementations but not accepted by the new HCL parsers.
Unlike the loaders and validators elsewhere in Terraform, this package always generates diagnostics with paths relative to the module directory currently being upgraded, with no intermediate paths. This means that the filenames in these ranges can be used directly as keys into the ModuleSources map that the file was parsed from.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ModuleSources ¶
func LoadModule ¶
func LoadModule(dir string) (ModuleSources, error)
LoadModule looks for Terraform configuration files in the given directory and loads each of them into memory as source code, in preparation for further analysis and conversion.
At this stage the files are not parsed at all. Instead, we just read the raw bytes from the file so that they can be passed into a parser in a separate step.
If the given directory or any of the files cannot be read, an error is returned. It is not safe to proceed with processing in that case because we cannot "see" all of the source code for the configuration.
func (ModuleSources) MaybeAlreadyUpgraded ¶
func (ms ModuleSources) MaybeAlreadyUpgraded() (bool, tfdiags.SourceRange)
MaybeAlreadyUpgraded is a heuristic to see if a given module may have already been upgraded by this package.
The heuristic used is to look for a Terraform Core version constraint in any of the given sources that seems to be requiring a version greater than or equal to v0.12.0. If true is returned then the source range of the found version constraint is returned in case the caller wishes to present it to the user as context for a warning message. The returned range is not meaningful if false is returned.
func (ModuleSources) UnusedFilename ¶
func (ms ModuleSources) UnusedFilename(proposed string) string
UnusedFilename finds a filename that isn't already used by a file in the receiving sources and returns it.
The given "proposed" name is returned verbatim if it isn't already used. Otherwise, the function will try appending incrementing integers to the proposed name until an unused name is found. Callers should propose names that they do not expect to already be in use so that numeric suffixes are only used in rare cases.
The proposed name must end in either ".tf" or ".tf.json" because a ModuleSources only has visibility into such files. This function will panic if given a file whose name does not end with one of these extensions.
A ModuleSources only works on one directory at a time, so the proposed name must not contain any directory separator characters.
type Upgrader ¶
type Upgrader struct {
Providers providers.Resolver
Provisioners map[string]terraform.ProvisionerFactory
}
Upgrader is the main type in this package, containing all of the dependencies that are needed to perform upgrades.
func (*Upgrader) Upgrade ¶
func (u *Upgrader) Upgrade(input ModuleSources) (ModuleSources, tfdiags.Diagnostics)
Upgrade takes some input module sources and produces a new ModuleSources that should be equivalent to the input but use the configuration idioms associated with the new configuration loader.
The result of this function will probably not be accepted by this function, because it will contain constructs that are known only to the new loader.
The result may include additional files that were not present in the input. The result may also include nil entries for filenames that were present in the input, indicating that these files should be deleted. In particular, file renames are represented as a new entry accompanied by a nil entry for the old name.
If the returned diagnostics contains errors, the caller should not write the resulting sources to disk since they will probably be incomplete. If only warnings are present then the files may be written to disk. Most warnings are also represented as "TF-UPGRADE-TODO:" comments in the generated source files so that users can visit them all and decide what to do with them.
Source Files