github.com/criteo/command-launcher@v0.0.0-20230407142452-fb616f546e98/gh-pages/content/en/docs/overview/system-package.md (about)

     1  ---
     2  title: "System package"
     3  description: "Extend command launcher's built-in function with system package"
     4  lead: "Extend command launcher's built-in function with system package"
     5  date: 2022-10-02T21:36:35+02:00
     6  lastmod: 2022-11-13T21:36:35+02:00
     7  draft: false
     8  images: []
     9  menu:
    10    docs:
    11      parent: "overview"
    12      identifier: "system-package-d940a4460a129d45a4ae1158e21b2130"
    13  weight: 800
    14  toc: true
    15  ---
    16  
    17  ## What is a system package
    18  
    19  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.
    20  
    21  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).
    22  
    23  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.
    24  
    25  ## Define system package
    26  
    27  To specify which package is the system package, use the configuration `system_package`.
    28  
    29  ```shell
    30  cola config system_package your-system-package-name
    31  ```
    32  
    33  An example system package manifest looks like this:
    34  
    35  ```yaml
    36  pkgName: system-package-demo
    37  version: 1.0.0
    38  cmds:
    39      - name: __login__
    40        type: system
    41        executable: "{{.PackageDir}}/hooks/login-hook"
    42      - name: __metrics__
    43        type: system
    44        executable: "{{.PackageDir}}/hooks/metrics-hook"
    45      - name: other-commands
    46        type: executable
    47        executable: "{{.PackageDir}}/scripts/other-cmd.sh"
    48  
    49  ```
    50  
    51  > NOTE: The system command will be ignored if the package is not defined as system package.
    52  
    53  ## System commands
    54  
    55  To extend command launcher, you need to specify `system` type command in a system package.
    56   The following table lists available system commands:
    57  
    58  | system command name | description                                     |
    59  |---------------------|-------------------------------------------------|
    60  | \_\_login\_\_       | calling your IAM system to return `login_token` |
    61  | \_\_metrics\_\_     | collect metrics                                 |
    62  
    63  ### System command \_\_login\_\_
    64  
    65  The built-in `login` command will trigger the `__login__` system command. It takes two arguments:
    66  
    67  - username
    68  - password
    69  
    70  ```shell
    71  __login__ [username] [password]
    72  ```
    73  
    74  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:
    75  
    76  | credential name | description              | environment variable |
    77  |-----------------|--------------------------|----------------------|
    78  | username        | the user name            | COLA_USERNAME        |
    79  | password        | the password             | COLA_PASSWORD        |
    80  | auth_token      | the authentication token | COLA_AUTH_TOKEN      |
    81  
    82  For example: the following output tells command launcher to store the `username` and the `auth_token`, but not store the `password`.
    83  
    84  ```json
    85  {
    86      "username": "joe",
    87      "auth_token": "DZ4OfC4vS38!"
    88  }
    89  ```
    90  
    91  To use these credentials see [Manage resources](../resources)
    92  
    93  ### System command \_\_metrics\_\_
    94  
    95  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:
    96  
    97  1. repository/registry name (see remote command)
    98  2. package name
    99  3. command group name, or "default" if no group
   100  4. command name
   101  5. user partition
   102  6. command exit code
   103  7. command execution duration in nano seconds
   104  8. error message or "nil" if no error
   105  9. command start timestamp in seconds
   106  
   107  Here is an example:
   108  
   109  ```shell
   110  __metrics__ default example cola-example hello 2 0 5000000 nil 1668363339
   111  ```
   112  
   113  > 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