docradle

package module
v0.0.0-...-a295a5f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2020 License: Apache-2.0 Imports: 41 Imported by: 0

README

docradle

Actions Status

Helper tool for Docker container. This tool works as command wrapper and provides the following features:

  • Check environment variables (existence and value check, set default value)
  • Read environment variables from .env file.
  • Check other depending processes
  • Transfer/modify/mask stdout/stderr logs
  • Report CPU/memory usage

Install

Install via Go get
$ go get github.com/future-architect/docradle/...

How to Use

Initialize
$ docradle init

Config file "docradle.json" is generated successfully.

Run with the following command:

$ docradle run your-command options...

Then edit docradle.json.

Execution

To use docradle, run like this:

$ docradle run <command> <args>...
  • "--config, -c": Config file name. Default file name is one of "docradle.json", "docradle.yaml", "docradle.yml", "docradle.cue".
  • "--dryrun, -d": Check only
  • "--dotenv, -e": .env file name to read. Default file name is ".env".

Settings

You can use config file in ".json", ".yaml", ".yml", ".cue". Current recommended format is JSON because you can use data check via JSON schema (on IntelliJ and Visual Studio Code).

Environment Variables

Declare environment variables what your application use.

{
  "env": [
    {
      "$comment": "<your comment>",
      "name":  "TEST",
      "default": "default value",
      "required": true,
      "pattern": "",
      "mask": "auto"
    }
  ]
}
  • name(required): env-var name
  • default(optional): Default value if this env-var is not passed.
  • required(optional): If this value is true and this env-var is not passed, docradle shows error and stop running. Default value is false.
  • pattern(optional): Regexp pattern to check env-var value
  • mask(optional): Hide the value from console log. You can use "auto", "hide", "show". If "auto", docradle decide the name contains the one of the following names:
    • "CREDENTIAL"
    • "PASSWORD"
    • "SECRET"
    • "_TOKEN"
    • "_KEY"
Config Files

Some docker images assumes overwriting config file by using "--volume". And sometimes, overwrite config via environment variables is useful (for example prebuild JavaScript application). This feature is for these capability.

{
  "file": [
    {
      "name": "my-app.json",
      "moveTo": "/opt/config",
      "required": false,
      "default": "/opt/config/config.json",
      "rewrite": [
        {
          "pattern": "$VERSION",
          "replace": "${APP_MODE}"
        }
      ]
    }
  ]
}
  • name(required): File name. This file is search from working directory to root.
  • moveTo(optional): Move the matched file to this directory. It make simplify -v option of Docker.
  • required(optional): If this value is true and this file doesn't exist, docradle shows error and stop running. Default value is false.
  • default(optional): Default file if file not match. This file will be moved to moveTo location.
  • rewrite(optional): Rewriting config file content by using environment variables.

If you make your static web application to aware release/staging mode without rebuilding on runtime and any server APIs, you can use like this:

{
  "pattern": "<body>",
  "replace": "<body><script>var process = { env: \"${ENV}\" };</script>"
}
Dependency Check

Sometimes, docker images run before its dependency. It is a feature to wait that.

{
  "dependsOn": [
    {
      "url": "http://microservice",
      "header": ["Authorization: Bearer 12345"],
      "timeout": 3.0,
      "interval": 1.0
    }
  ]
}
  • url(required): The target to observe. The schema should be one of file, http, https, tcp, tcp4, tcp6, unix.
  • header(optional): If the target is http or https, This header is passed to target server.
  • timeout(optional): Timeout duration (second). If the target server doesn't work within this term, docradle shows error and stop running. Default value is 10 seconds.
  • interval(optional): Interval to access target service. Default value is 1 second.
Stdout/Stderr settings

Docradle is designed to work with application that shows structured log (now only support JSON) to stdout, stderr. And its output is always JSON.

{
  "stdout": {
    "defaultLevel": "info",
    "structured": true,
    "exportConfig": "",
    "exportHost": "",
    "passThrough": true,
    "mask": ["password"],
    "tags": {"tag-key": "tag-value"}
  },
  "stderr": {
    "$comment": "Setting for stderr. It is as same as stdout's config"
  },
  "logLevel":  "info"
}

If application output is not JSON or structured option is false, Docradle captures it and outputs like this:

# Application output
hello

# docradle output
{"level": "info", "message": "hello", time":1579946400}
  • stdout/stderr.defaultLevel(optional): If log level(level key in output JSON) is not included in output, This output level is used. Default value for stdout is "info", for stderr is "error".
  • stdout/stderr.structured(optional): If it is true, docradle try to parse console output as JSON. Default value is true.
  • stdout/stderr.exportConfig(optional/experimental): Transfer log output to external server. It accepts the following systems:
    • fluentd://(tagnames): Fluentd
    • kafka://(topic): Kafka
  • stdout/stderr.exportHost(optional/experimental): It is the host name of the above systems.
  • stdout/stderr.passThrough(optional): If it is true, docradle dump log output to its stdout/stderr too. Default value is true.
  • stdout/stderr.mask(optional): If output JSON contains one of this key, The value would be masked.
  • stdout/stderr.tags(optional): This JSON contents would be added to output log.
  • logLevel(optional): Log filtering option. Default value is "info".

License

Apache 2

  • Dockerize

    The feature "dependsOn" is inspired by Dockerize.

Documentation

Index

Constants

View Source 
const (
	StdOut LogType = iota + 1
	StdErr

	LogLevelKey       = "level"
	LogDocradleLogKey = "docradle-log"
)

Variables

This section is empty.

Functions

func CheckEnv 

func CheckEnv(c *Config, osEnvs, dotEnvs []string, includeNoSpec bool) (results []EnvCheckResult, envs *EnvVar)

CheckEnv checks environment variables

func DumpCommand 

func DumpCommand(stdout io.Writer, command string, args []string, dryRun bool)

func Exec 

func Exec(stdout, stderr io.Writer, config *Config, command string, args []string, envvar *EnvVar) error

Exec executes command

func Generate 

func Generate(stdout io.Writer, format string) error

func ParseAndVerifyConfig 

func ParseAndVerifyConfig(workingDir string, stdout, stderr io.Writer, configFlag, dotEnvFlag string) (*Config, *EnvVar, error)

ParseAndVerifyConfig reads and verify configs

It dumps config status and error message to stdout, stderr

func SearchFiles 

func SearchFiles(patterns, cwd string) ([]string, error)

SearchFiles searches filepathes to match pattern

Types

type Config 

type Config struct {
	Env           []Env
	Stdout        LogConfig
	Stderr        LogConfig
	DashboardPort int
	DelvePort     int
	Files         []File
	DependsOn     []DependsOn
	Process       Process
	HealthCheck   HealthCheck
	LogLevel      string
}

Config stores all config about execution environment

func ReadConfig 

func ReadConfig(filePath string, reader io.Reader) (*Config, error)

ReadConfig reads config

type DependsOn 

type DependsOn struct {
	URL      *url.URL
	Headers  [][2]string
	Timeout  time.Duration
	Interval time.Duration
}

type DependsOnCheckResult 

type DependsOnCheckResult struct {
	// contains filtered or unexported fields
}

DependsOnCheckResult is a collection of dependency check

func WaitForDependencies 

func WaitForDependencies(ctx context.Context, dependsOns []DependsOn) (result []DependsOnCheckResult)

func (DependsOnCheckResult) Error 

func (r DependsOnCheckResult) Error() error

func (DependsOnCheckResult) String 

func (r DependsOnCheckResult) String() string

type Env 

type Env struct {
	Name     string `json:"name"`
	Default  string `json:"default"`
	Required bool   `json:"required"`
	Pattern  string `json:"pattern"`
	Mask     string `json:"mask"`
}

type EnvCheckResult 

type EnvCheckResult struct {
	// contains filtered or unexported fields
}

EnvCheckResult is a collection of envvar check

func (EnvCheckResult) Error 

func (c EnvCheckResult) Error() error

func (EnvCheckResult) String 

func (c EnvCheckResult) String() string

type EnvVar 

type EnvVar struct {
	// contains filtered or unexported fields
}

func NewEnvVar 

func NewEnvVar() *EnvVar

func (EnvVar) EnvsForExec 

func (e EnvVar) EnvsForExec() (result []string)

func (EnvVar) Expand 

func (e EnvVar) Expand(value string) string

func (EnvVar) FindSuggest 

func (e EnvVar) FindSuggest(missingKey string) (result []string)

func (EnvVar) Get 

func (e EnvVar) Get(key string) (string, string, source, bool)

func (*EnvVar) Import 

func (e *EnvVar) Import(src source, envs []string)

func (*EnvVar) Register 

func (e *EnvVar) Register(src source, key, value string) int

type File 

type File struct {
	Name     string
	Required bool
	MoveTo   string
	Default  string
	Rewrites []Rewrite
}

type FileCheckResult 

type FileCheckResult struct {
	// contains filtered or unexported fields
}

FileCheckResult contains file check result

func ProcessFiles 

func ProcessFiles(config *Config, cwd string, envs *EnvVar) (results []FileCheckResult)

ProcessFiles checks file existing test, upcate contents and so on.

func (FileCheckResult) String 

func (c FileCheckResult) String() string

type HealthCheck 

type HealthCheck struct {
	URL           string  `json:"url"`
	Interval      float64 `json:"interval"`
	Port          int     `json:"port"`
	StatsInterval float64 `json:"statsInterval"`
}

type LogConfig 

type LogConfig struct {
	Structured   bool
	DefaultLevel string
	ExportConfig string
	ExportHost   string
	PassThrough  bool
	Mask         []string
	Tags         map[string]string
}

type LogOutput 

type LogOutput struct {
	Text  string
	Error bool
}

type LogOutputs 

type LogOutputs []LogOutput

func DumpAndSummaryDependsOnResult 

func DumpAndSummaryDependsOnResult(results []DependsOnCheckResult) LogOutputs

DumpAndSummaryDependsOnResult dumps depends-on check result

func DumpAndSummaryEnvResult 

func DumpAndSummaryEnvResult(results []EnvCheckResult) LogOutputs

DumpAndSummaryEnvResult dumps environment variable check result

func DumpAndSummaryFileResult 

func DumpAndSummaryFileResult(results []FileCheckResult) LogOutputs

func (LogOutputs) Dump 

func (l LogOutputs) Dump(errorOnly bool) bool

func (LogOutputs) HasError 

func (l LogOutputs) HasError() bool

type LogType 

type LogType int

func (LogType) String 

func (l LogType) String() string

type Logger 

type Logger struct {
	// contains filtered or unexported fields
}

func NewLogger 

func NewLogger(ctx context.Context, logType LogType, writer io.Writer, logLevelLabel string, logConfig LogConfig, envvar *EnvVar) (*Logger, error)

func (*Logger) Close 

func (l *Logger) Close()

func (*Logger) StartOutput 

func (l *Logger) StartOutput(eg *errgroup.Group, reader io.ReadCloser)

func (*Logger) Write 

func (l *Logger) Write(line string)

func (*Logger) WriteMap 

func (l *Logger) WriteMap(log map[string]interface{})

func (*Logger) WriteMetrics 

func (l *Logger) WriteMetrics(memUsage uint64, memPercent float32, cpuPercent float64)

func (*Logger) WriteProcessResult 

func (l *Logger) WriteProcessResult(exitAt time.Time, status string, wallClock, user, sys time.Duration)

func (*Logger) WriteProcessStart 

func (l *Logger) WriteProcessStart(startAt time.Time, pid int, dir, cmd string, args []string)

type Process 

type Process struct {
	NoticeExitHTTP   string `json:"noticeExitHttp"`
	NoticeExitSlack  string `json:"noticeExitSlack"`
	NoticeExitPubSub string `json:"noticeExitPubSub"`
	Rerun            bool   `json:"rerun"`
	LogBucket        string `json:"logBucket"`
}

type Rewrite 

type Rewrite struct {
	Pattern string `json:"pattern"`
	Replace string `json:"replace"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
docradle

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.