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 BuiltinRuleSet
  • func (r *BuiltinRuleSet) ApplyCommonConfig(config *Config)
  • func (r *BuiltinRuleSet) ApplyConfig(config *Config) error
  • func (r *BuiltinRuleSet) Check(runner Runner) error
  • func (r *BuiltinRuleSet) RuleNames() []string
  • func (r *BuiltinRuleSet) RuleSetName() string
  • func (r *BuiltinRuleSet) RuleSetVersion() string
• type Config
• type Error
  • func (e Error) Error() string
• type MarshalledConfig
  • func (c *MarshalledConfig) Unmarshal() (*Config, error)
• type Rule
• type RuleConfig
• type RuleSet
• 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 BuiltinRuleSet

type BuiltinRuleSet struct {
	Name    string
	Version string
	Rules   []Rule

	EnabledRules []Rule
}

BuiltinRuleSet is the basis of the ruleset. Plugins can serve this ruleset directly. You can serve a custom ruleset by embedding this ruleset if you need special extensions.

func (*BuiltinRuleSet) ApplyCommonConfig

func (r *BuiltinRuleSet) ApplyCommonConfig(config *Config)

ApplyCommonConfig reflects common configurations regardless of plugins.

func (*BuiltinRuleSet) ApplyConfig

func (r *BuiltinRuleSet) ApplyConfig(config *Config) error

ApplyConfig reflects the configuration to the ruleset. By default, this only applies common configurations.

func (*BuiltinRuleSet) Check

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

Check runs inspection for each rule by applying Runner.

func (*BuiltinRuleSet) RuleNames

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

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

func (*BuiltinRuleSet) RuleSetName

func (r *BuiltinRuleSet) RuleSetName() string

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

func (*BuiltinRuleSet) RuleSetVersion

func (r *BuiltinRuleSet) RuleSetVersion() string

RuleSetVersion is the version of the plugin.

type Config

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

Config is a TFLint configuration applied to the plugin. The Body contains the contents declared in the "plugin" block.

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 MarshalledConfig

type MarshalledConfig struct {
	Rules             map[string]*RuleConfig
	DisabledByDefault bool
	BodyBytes         []byte
	BodyRange         hcl.Range
}

MarshalledConfig is an intermediate representation of Config for communicating over RPC

func (*MarshalledConfig) Unmarshal

func (c *MarshalledConfig) Unmarshal() (*Config, error)

Unmarshal converts intermediate representations into the Config object.

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 interface {
	// RuleSetName is the name of the ruleset. This method is not expected to be overridden.
	RuleSetName() string

	// RuleSetVersion is the version of the plugin. This method is not expected to be overridden.
	RuleSetVersion() string

	// RuleNames is a list of rule names provided by the plugin. This method is not expected to be overridden.
	RuleNames() []string

	// ApplyConfig reflects the configuration to the ruleset.
	// Custom rulesets can override this method to reflect the plugin's own configuration.
	// In that case, don't forget to call ApplyCommonConfig.
	ApplyConfig(*Config) error

	// Check runs inspection for each rule by applying Runner.
	// This is a entrypoint for all inspections and can be used as a hook to inject a custom runner.
	Check(Runner) error
}

RuleSet is a list of rules that a plugin should provide. Normally, plugins can use BuiltinRuleSet directly, but you can also use custom rulesets that satisfy this interface.

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)

	// File returns the hcl.File object.
	// This is low level API for accessing information such as comments and syntax.
	// When accessing resources, expressions, etc, it is recommended to use high-level APIs.
	File(string) (*hcl.File, error)

	// RootProvider returns the provider configuration in the root module.
	// It can be used by child modules to access the credentials defined in the root module.
	RootProvider(name string) (*configs.Provider, error)

	// DecodeRuleConfig fetches the rule's configuration and reflects the result in ret.
	DecodeRuleConfig(name string, ret interface{}) error

	// EvaluateExpr evaluates the passed expression and reflects the result in ret.
	// If you want to ensure the type of ret, you can pass the type as the 3rd argument.
	// If you pass nil as the type, it will be inferred from the type of 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{}, wantType *cty.Type) error

	// EvaluateExprOnRootCtx is the equivalent of EvaluateExpr method in the context of the root module.
	// Its main use is to evaluate the provider block obtained by the RootProvider method.
	EvaluateExprOnRootCtx(expr hcl.Expression, ret interface{}, wantType *cty.Type) error

	// IsNullExpr checks whether the passed expression is null or not.
	// This returns an error when the passed expression is invalid, occurs evaluation errors, etc.
	IsNullExpr(expr hcl.Expression) (bool, 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.