codegen

README

MikroTik code generation

This tool allows generating MikroTik resources for API client and Terraform resources based on Mikrotik struct definition.

MikroTik client resource

To generate new MikroTik resource definition, simply run

$ go run ./cmd/mikrotik-codegen mikrotik -name BridgeVlan -commandBase "/interface/bridge/vlan"

where

name - a name of MikroTik resource to generate.

commandBase - base path to craft commands for CRUD operations.

It is also possible to pre-fill list of fields using either -inspect-definition-file argument

$ go run ./cmd/mikrotik-codegen mikrotik -name BridgeVlan -commandBase "/interface/bridge/vlan" -inspect-definition-file ./inspect_vlan.txt

or -query-definition flag (requires valid credentials in evironment)

$ go run ./cmd/mikrotik-codegen mikrotik -name BridgeVlan -commandBase "/interface/bridge/vlan" -query-definition

For details, see Experimental section.

Terraform resource

Just add a codegen tag key to struct fields:

type MikrotikResource struct{
	Id             string   `mikrotik:".id"             codegen:"id,mikrotikID,deleteID"`
	Name           string   `mikrotik:"name"            codegen:"name,required,terraformID"`
	Enabled        bool     `mikrotik:"enabled"         codegen:"enabled"`
	Items          []string `mikrotik:"items"           codegen:"items,elemType=string"`
	UpdatedAt      string   `mikrotik:"updated_at"      codegen:"updated_at,computed"`
	Unused         int      `mikrotik:"unused"          codegen:"-"`
	NotImplemented int      `mikrotik:"not_implemented" codegen:"not_implemented,omit"`
	Comment        string   `mikrotik:"comment"         codegen:"comment"`
}

and run:

$ go run ./cmd/mikrotik-codegen terraform -src client/resource.go -struct MikrotikResource > mikrotik/resource_new.go

Supported options

Name	Description
terraformID	Use this field during Read and Import resource
mikrotikID	This field is MikroTik ID field, usually .id
deleteID	Terraform resource will use this field to delete resource
required	Mark field as required in resource schema
optional	Mark field as optional in resource schema
computed	Mark field as computed in resource schema
elemType	Explicitly set element type for List or Set attributes. Usage elemType=int
omit	Skip this field from code generation process

Experimental

This section contains documentation for experimental and non-stable features.

Generate Mikrotik resource using /console/inspect definition

Modern RouterOS versions (>7.x) provide new /console/inspect command to query hierarchy or syntax of particular command.

For example, /console/inspect path=interface,list request=child prints parent-child relationship of the command:

Columns: TYPE, NAME, NODE-TYPE
TYPE   NAME     NODE-TYPE
self   list     dir
child  add      cmd
child  comment  cmd
child  edit     cmd
child  export   cmd
child  find     cmd
child  get      cmd
child  member   dir
child  print    cmd
child  remove   cmd
child  reset    cmd
child  set      cmd

while /console/inspect path=interface,list request=syntax gives another set of attributes:

Columns: TYPE, SYMBOL, SYMBOL-TYPE, NESTED, NONORM, TEXT
TYPE    SYMBOL   SYMBOL-TYPE  NESTED  NONORM  TEXT
syntax           collection        0  yes
syntax  ..       explanation       1  no      go up to interface
syntax  add      explanation       1  no      Create a new item
syntax  comment  explanation       1  no      Set comment for items
syntax  edit     explanation       1  no
syntax  export   explanation       1  no      Print or save an export script that can be used to restore configuration
syntax  find     explanation       1  no      Find items by value
syntax  get      explanation       1  no      Gets value of item's property
syntax  member   explanation       1  no
syntax  print    explanation       1  no      Print values of item properties
syntax  remove   explanation       1  no      Remove item
syntax  reset    explanation       1  no
syntax  set      explanation       1  no      Change item properties

Using that information, it is possible to query (even recursively) information about all menu items and sub-commands, starting from the root / command.

:Warning: Since this feature is recent, trying to call it with our client package sometimes results in terminal crush.

Using definition in file

For this case, one needs:

1. Machine-readable data about available fields
2. Pass this data as -inspect-definition-file argument.

To get resource definition, run the following command on remote system:

$ :put [/console/inspect  path=interface,list,add request=child as-value]

which produces:

name=add;node-type=cmd;type=self;name=comment;node-type=arg;type=child;name=copy-from;node-type=arg;type=child;name=exclude;node-type=arg;type=child;name=include;node-type=arg;type=child;name=name;node-type=arg;type=child

If you have ssh access to the Mikrotik, the following command will produce the same string:

$ ssh -o Port=XXXX -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null admin@board ":put [/console inspect as-value request=child path=interface,list,add]" > inspect_definition.txt

After getting the definition file, just generate Mikrotik resource as usual with extra flag:

$ go run ./cmd/mikrotik-codegen mikrotik -name InterfaceList -commandBase "/interface/list" -inspect-definition-file ./inspect_definition.txt

and all fields for the struct will be created.

Note, that we used interface,list,add as argument to path. The terminal equivalent would be /interface/list/add (not sure why it works that way, you can check forum topic)

The reason we used add command and not /interface/list menu itself, is that we need only args (fields) of add command - not information about possible commands for /interface/list

Query resource definition automatically

To use this method, current environment must contain valid credentials.

$ go run cmd/mikrotik-codegen/main.go mikrotik -commandBase /ip/dhcp-server -name DhcpServer -query-definition

Documentation

Index

• Constants
• Variables
• func GenerateMikrotikResource(resourceName, commandBasePath string, ...) error
• func GenerateMikrotikResourceTest(resourceName string, s *Struct, w io.Writer) error
• func GenerateResource(s *Struct, w io.Writer) error
• func GenerateResourceTest(s *Struct, w io.Writer) error
• func SourceFormatHook(p []byte) ([]byte, error)
• type Field
• type SourceWriteHookFunc
• type Struct
  • func ParseFile(filename string, startLine int, structName string) (*Struct, error)
• type Type

Constants

const (
	// List of declaration identifiers from ast package while parsing the source code
	AstVarTypeString = "string"
	AstVarTypeInt    = "int"
	AstVarTypeBool   = "bool"
)

Variables

var (
	// Handle custom types from the client package
	AstVarTypeMikrotikList     = reflect.TypeOf(types.MikrotikList{}).Name()
	AstVarTypeMikrotikIntList  = reflect.TypeOf(types.MikrotikIntList{}).Name()
	AstVarTypeMikrotikDuration = reflect.TypeOf(types.MikrotikDuration(0)).Name()
)

Functions

func GenerateMikrotikResource

func GenerateMikrotikResource(resourceName, commandBasePath string,
	consoleCommandDefinition consoleinspected.ConsoleItem,
	w io.Writer) error

func GenerateMikrotikResourceTest

func GenerateMikrotikResourceTest(resourceName string, s *Struct, w io.Writer) error

func GenerateResource

func GenerateResource(s *Struct, w io.Writer) error

GenerateResource generates Terraform resource and writes it to specified output

func GenerateResourceTest

func GenerateResourceTest(s *Struct, w io.Writer) error

GenerateResourceTest generates Terraform resource acceptance test and writes it to specified output

func SourceFormatHook

func SourceFormatHook(p []byte) ([]byte, error)

SourceFormatHook formats code using Go's formatter

Types

type Field

type Field struct {
	// OriginalName is an original field name without chnages.
	OriginalName string

	// Name is a field name defined by struct tag.
	Name string

	// Required marks field as `required` in Terraform definition.
	Required bool

	// Optional marks field as `optional` in Terraform definition.
	Optional bool

	// Computed marks field as `computed` in Terraform definition.
	Computed bool

	// Type holds a field type.
	Type string

	// ElemType holds an element type if field type is List or Set
	ElemType string
}

Field holds information about particular field in parsed struct.

type SourceWriteHookFunc

type SourceWriteHookFunc func([]byte) ([]byte, error)

SourceWriteHookFunc defines a hook func to mutate source before writing to destination

type Struct

type Struct struct {
	// Name is a of parsed struct.
	Name string

	// MikrotikIDField is a field name which holds MikroTik resource ID.
	MikrotikIDField string

	// TerraformIDField holds a field name which will be used as Terraform resource ID.
	TerraformIDField string

	// DeleteField holds a field name to use when deleting resource on MikroTik system.
	DeleteField string

	// Fields is a collection of field definitions in the parsed struct.
	Fields []*Field
}

Struct holds information about parsed struct.

func ParseFile

func ParseFile(filename string, startLine int, structName string) (*Struct, error)

ParseFile parses a .go file with struct declaration.

This functions searches for struct definition `structName` and parses it. If `structName` is empty, function stops at first struct definition in the file right after `startLine`.

type Type

type Type interface {
	// Type returns a type name as string.
	// It must be stable for the same type.
	Name() string

	// Is checks whether two types are the same.
	Is(Type) bool
}

Type represents Terraform field type to use for particular MikroTik field.

var (
	StringType      Type = basetype{/* contains filtered or unexported fields */}
	Int64Type       Type = basetype{/* contains filtered or unexported fields */}
	ListType        Type = basetype{/* contains filtered or unexported fields */}
	SetType         Type = basetype{/* contains filtered or unexported fields */}
	BoolType        Type = basetype{/* contains filtered or unexported fields */}
	StringSliceType Type = basetype{/* contains filtered or unexported fields */}
	IntSliceType    Type = basetype{/* contains filtered or unexported fields */}
	UnknownType     Type = basetype{/* contains filtered or unexported fields */}
)