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 name | description |
---|---|
__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 name | description | environment variable |
---|---|---|
username | the user name | COLA_USERNAME |
password | the password | COLA_PASSWORD |
auth_token | the authentication token | COLA_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:
- repository/registry name (see remote command)
- package name
- command group name, or “default” if no group
- command name
- user partition
- command exit code
- command execution duration in nano seconds
- error message or “nil” if no error
- 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