tflint

Documentation

Overview

Package tflint contains implementations and interfaces for plugin developers.

Each rule can use the RPC client that satisfies the Runner interface as an argument. Through this client, developers can get attributes, blocks, and resources to be analyzed and send issues to TFLint.

All rules must be implemented to satisfy the Rule interface and a plugin must serve the RuleSet that bundles the rules.

Index

• Constants
• type Config
• type Error
  • func (e Error) Error() string
• type Rule
• type RuleConfig
• type RuleSet
  • func (r *RuleSet) ApplyConfig(config *Config)
  • func (r *RuleSet) Check(runner Runner) error
  • func (r *RuleSet) RuleNames() []string
  • func (r *RuleSet) RuleSetName() string
  • func (r *RuleSet) RuleSetVersion() string
• type Runner

Constants

const (
	// EvaluationError is an error when interpolation failed (unexpected)
	EvaluationError string = "E:Evaluation"
	// UnknownValueError is an error when an unknown value is referenced
	UnknownValueError string = "W:UnknownValue"
	// NullValueError is an error when null value is referenced
	NullValueError string = "W:NullValue"
	// TypeConversionError is an error when type conversion of cty.Value failed
	TypeConversionError string = "E:TypeConversion"
	// TypeMismatchError is an error when a type of cty.Value is not as expected
	TypeMismatchError string = "E:TypeMismatch"
	// UnevaluableError is an error when a received expression has unevaluable references.
	UnevaluableError string = "W:Unevaluable"
	// UnexpectedAttributeError is an error when handle unexpected attributes (e.g. block)
	UnexpectedAttributeError string = "E:UnexpectedAttribute"
	// ExternalAPIError is an error when calling the external API (e.g. AWS SDK)
	ExternalAPIError string = "E:ExternalAPI"
	// ContextError is pseudo error code for propagating runtime context.
	ContextError string = "I:Context"

	// FatalLevel is a recorverable error, it cause panic
	FatalLevel string = "Fatal"
	// ErrorLevel is a user-level error, it display and feedback error information
	ErrorLevel string = "Error"
	// WarningLevel is a user-level warning. Although it is an error, it has no effect on execution.
	WarningLevel string = "Warning"
)

List of error types and levels in an application error. It's possible to get this error from a plugin, but the basic error handling is hidden inside the plugin system, so you usually don't have to worry about it.

const (
	// ERROR is possible errors
	ERROR = "Error"
	// WARNING doesn't cause problem immediately, but not good
	WARNING = "Warning"
	// NOTICE is not important, it's mentioned
	NOTICE = "Notice"
)

List of issue severity levels. The rules implemented by a plugin can be set to any severity.

Types

type Config

type Config struct {
	Rules             map[string]*RuleConfig
	DisabledByDefault bool
}

Config is a TFLint configuration applied to the plugin. Currently, it is not expected that each plugin will reference this directly.

type Error

type Error struct {
	Code    string
	Level   string
	Message string
	Cause   error
}

Error is an application error object. It has own error code for processing according to the type of error.

func (Error) Error

func (e Error) Error() string

Error shows error message. This must be implemented for error interface.

type Rule

type Rule interface {
	// Name will be displayed with a message of an issue and will be the identifier used to control
	// the behavior of this rule in the configuration file etc.
	// Therefore, it is expected that this will not duplicate the rule names provided by other plugins.
	Name() string

	// Enabled indicates whether the rule is enabled by default.
	Enabled() bool

	// Severity indicates the severity of the rule.
	Severity() string

	// Link allows you to add a reference link to the rule.
	Link() string

	// Check is the entrypoint of the rule. You can fetch Terraform configurations and send issues via Runner.
	Check(Runner) error
}

Rule is the interface that the plugin's rules should satisfy.

type RuleConfig

type RuleConfig struct {
	Name    string
	Enabled bool
}

RuleConfig is a TFLint's rule configuration.

type RuleSet

type RuleSet struct {
	Name    string
	Version string
	Rules   []Rule
}

RuleSet is a list of rules that a plugin should provide.

func (*RuleSet) ApplyConfig

func (r *RuleSet) ApplyConfig(config *Config)

ApplyConfig reflects the plugin configuration in the ruleset. Currently used only to enable/disable rules.

func (*RuleSet) Check

func (r *RuleSet) Check(runner Runner) error

Check runs inspection for each rule by applying Runner.

func (*RuleSet) RuleNames

func (r *RuleSet) RuleNames() []string

RuleNames is a list of rule names provided by the plugin.

func (*RuleSet) RuleSetName

func (r *RuleSet) RuleSetName() string

RuleSetName is the name of the ruleset. Generally, this is synonymous with the name of the plugin.

func (*RuleSet) RuleSetVersion

func (r *RuleSet) RuleSetVersion() string

RuleSetVersion is the version of the plugin.

type Runner

type Runner interface {
	// WalkResourceAttributes visits attributes with the passed function.
	// You must pass a resource type as the first argument and an attribute name as the second argument.
	WalkResourceAttributes(string, string, func(*hcl.Attribute) error) error

	// WalkResourceBlocks visits blocks with the passed function.
	// You must pass a resource type as the first argument and a block type as the second argument.
	// This API currently does not support labeled blocks.
	WalkResourceBlocks(string, string, func(*hcl.Block) error) error

	// WalkResources visits resources with the passed function.
	// You must pass a resource type as the first argument.
	WalkResources(string, func(*configs.Resource) error) error

	// WalkModuleCalls visits module calls with the passed function.
	WalkModuleCalls(func(*configs.ModuleCall) error) error

	// Backend returns the backend configuration, if any.
	Backend() (*configs.Backend, error)

	// Config returns the Terraform configuration.
	// This object contains almost all accessible data structures from plugins.
	Config() (*configs.Config, error)

	// EvaluateExpr evaluates the passed expression and reflects the result in ret.
	// Since this function returns an application error, it is expected to use the EnsureNoError
	// to determine whether to continue processing.
	EvaluateExpr(expr hcl.Expression, ret interface{}) error

	// EvaluateExprType is like EvaluateExpr, but also accepts a known cty.Type to pass to EvalExpr
	EvaluateExprType(expr hcl.Expression, ret interface{}, wantType cty.Type) error

	// EmitIssue sends an issue with an expression to TFLint. You need to pass the message of the issue and the expression.
	EmitIssueOnExpr(rule Rule, message string, expr hcl.Expression) error

	// EmitIssue sends an issue to TFLint. You need to pass the message of the issue and the range.
	// You should use EmitIssueOnExpr if you want to emit an issue for an expression.
	// This API provides a lower level interface.
	EmitIssue(rule Rule, message string, location hcl.Range) error

	// EnsureNoError is a helper for error handling. Depending on the type of error generated by EvaluateExpr,
	// determine whether to exit, skip, or continue. If it is continued, the passed function will be executed.
	EnsureNoError(error, func() error) error
}

Runner acts as a client for each plugin to query the host process about the Terraform configurations.