System package

Extend command launcher's built-in function with system package

What is a system package

System package is like other command launcher packages, with one manifest.mf file in it to describe the commands and contains binaries, scripts, and resources to execute these commands.

The difference is that a system package contains system commands, and it can be only installed from a central repository (not as a dropin package).

You can customize your command launcher by providing a system package. In a system package, you can define system commands as functional hooks to extend command launcher’s built-in functionalities, for example, login and metrics.

Define system package

To specify which package is the system package, use the configuration system_package.

cola config system_package your-system-package-name

An example system package manifest looks like this:

pkgName: system-package-demo
version: 1.0.0
cmds:
    - name: __login__
      type: system
      executable: "{{.PackageDir}}/hooks/login-hook"
    - name: __metrics__
      type: system
      executable: "{{.PackageDir}}/hooks/metrics-hook"
    - name: other-commands
      type: executable
      executable: "{{.PackageDir}}/scripts/other-cmd.sh"

NOTE: The system command will be ignored if the package is not defined as system package.

System commands

To extend command launcher, you need to specify system type command in a system package. The following table lists available system commands:

system command namedescription
__login__calling your IAM system to return login_token
__metrics__collect metrics

System command __login__

The built-in login command will trigger the __login__ system command. It takes two arguments:

  • username
  • password
__login__ [username] [password]

The __login__ system command outputs the credentials to be stored by command launcher in a JSON format. The credentials could be one or many of following items:

credential namedescriptionenvironment variable
usernamethe user nameCOLA_USERNAME
passwordthe passwordCOLA_PASSWORD
auth_tokenthe authentication tokenCOLA_AUTH_TOKEN

For example: the following output tells command launcher to store the username and the auth_token, but not store the password.

{
    "username": "joe",
    "auth_token": "DZ4OfC4vS38!"
}

To use these credentials see Manage resources

System command __metrics__

At the end of each command launcher execution, the __metrics__ system hook will be triggered. The following arguments will be passed to __metrics__ system command in order:

  1. repository/registry name (see remote command)
  2. package name
  3. command group name, or “default” if no group
  4. command name
  5. user partition
  6. command exit code
  7. command execution duration in nano seconds
  8. error message or “nil” if no error
  9. command start timestamp in seconds

Here is an example:

__metrics__ default example cola-example hello 2 0 5000000 nil 1668363339

Note: the __metrics__ hook will be called at the end of each command launcher call, please make sure it ends fast to reduce the footprint