Command Line Interface (CLI) for Managing Extensions

This library provides a set of commands to manage extensions. Below you will find instructions on how to install and use the commands provided by this library.

Installation

To install the local version of the package, run the following command:

npm install .

To install the package from the npm registry, use the following command:

npm install @coralogix/extensions-cli

Usage

Import Extensions

👉 The import command can only run inside the CX cluster. This requires the extensionsApiUrl parameter, which is the internal URL of the extensions-api service.

Importing the extensions will make them available for deployment in the selected Coralogix environment. Run the following command to import extensions:

cx-extensions import -p <extensionsPath> -u <extensionsApiUrl> 

Environment variable EXTENSIONS_GRPC_API_URL can be used as an alternative way to specify the extensionsApiUrl parameter value. Environment variables RETRY_ATTEMPTS and RETRY_DELAY can be used to configure the retry mechanism in case of a failure during the import process. By default, the import process will retry 3 times with a delay of 5 seconds between retries.

You can configure the extension import process either by providing command-line arguments or by using a JSON configuration file.
The schema for the configuration file is detailed below.
    
```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "extension-import-config-schema",
  "title": "Extension import configuration schema",
  "description": "Configuration schema for importing extensions",
  "type": "object",
  "properties": {
    "extensionsPath": {
      "type": "string",
      "description": "Path to the folder containing the extensions."
    },
    "extensionsApiUrl": {
      "type": "string",
      "description": "URL of the Coralogix extensions API."
    },
    "retryAttempts": {
      "type": "integer",
      "description": "Number of retry attempts in case of failure.",
      "default": 3
    },
    "retryDelay": {
      "type": "integer",
      "description": "Delay between retry attempts in milliseconds.",
      "default": 5000
    }
  },
  "required": ["extensionsPath", "extensionsApiUrl"]
}

To use import configuration file, run the following command:

cx-extensions import -c <configPath>

You may also override configuration file values by providing command-line arguments.

Use -d dryRun flag to dry run the import process without actually importing the extensions.

Extensions Preview

👉 Note, execution of this command requires the user to have the following permission: extensions:UpdateConfig

Extensions can be deployed in a preview mode visible only to specific users. This previewed extension can be deployed, updated, and uninstalled through the UI. The command output will display the URL for the extension preview.

To make the extension preview version visible in the environment add ?includeTestingRevision to the Extension Page URL (e.g., /#/extensions/Okta?includeTestingRevision).

Preview version will have -testing postfix, so it’s easy to identify it.

Just note that it’s allowed to have only one extension preview per extension ID. Clean up the preview in order to initialise another one. Run the following command to preview extensions:

cx-extensions preview -u <apiUrl> -w <webAppUrl> -t <token> -o <teamId> -p <extensionsPath>

Preview can be also configured using a configuration file. The schema for the configuration file is detailed below.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "testing-config-schema",
  "title": "Extension testing configuration schema",
  "description": "The schema for configuration needed for testing extensions",
  "type": "object",
  "properties": {
    "apiUrl": {
      "type": "string",
      "description": "URL of the Coralogix gRPC API Gateway for the environment."
    },
    "webAppUrl": {
      "type": "string",
      "description": "URL of the Coralogix web-app."
    },
    "token": {
      "type": "string",
      "description": "Bearer token taken from the web-app."
    },
    "teamId": {
      "type": "string",
      "description": "Team ID"
    },
    "extensionDirectoryNames": {
      "type": "array",
      "description": "Directories to the specific extensions to apply the testing actions on."
    },
    "extensionsPath": {
      "type": "string",
      "description": "Path to the folder containing the extensions."
    }
  },
  "required": ["apiUrl", "token", "teamId", "extensionDirectoryNames", "extensionsPath"]
}

Extensions Preview Cleanup

👉 Note, execution of this command requires the user to have the following permission: extensions:UpdateConfig

Cleanup the previewed extensions. This will remove the previewed extensions. Run the following command to clean up previewed extensions:

cx-extensions cleanup -u <apiUrl> -t <token> -o <teamId> -p <extensionsPath>

Cleanup can be also configured using a configuration file. The schema for the configuration file is the same as for the preview.

Extension Testing

👉 Note, execution of this command requires the user to have the following permission: extensions:UpdateConfig

Test extensions before importing. This will initialise the extensions preview, deploy the extensions, and perform cleanup. Run the following command to test extensions:

cx-extensions test -u <apiUrl> -t <token> -o <teamId> -p <extensionsPath>

Test can be also configured using a configuration file. The schema for the configuration file is the same as for the preview.

Extensions Validation

Validate extensions before importing. This would parse the extensions package, check for duplicates, and perform some basic validations. Use it as an initial validation stage. If this stage is successful, importing with dryRun mode can be used for a more complete validation.

Run the following command to validate extensions:

cx-extensions validate -p <extensionsPath>

Export Extensions Structure

Run the following command to export the structure of the extensions to a json file:

cx-extensions export-structure -p <extensionsPath>

Generate Kibana Dashboard YML

Run the following command to generate yml file out of ndjson for Kibana dashboard:

cx-extensions  dashboard-yml -f <ndjsonFile> -o <ymlOutputFile>

Important Note

All the testing commands have apiUrl and token parameters, as they use endpoints exposed publicly. In contrast, the import command can only run inside the cluster. This requires the extensionsApiUrl parameter, which is the internal URL of the extensions-api service.

• To get apiUrl value, open the Coralogix web app in Chrome Developer Tools, navigate to the Application tab, and copy the value of the grpcServiceGatewayUrl property.

• extensionsApiUrl value should be the following http://extensions-api.{namespace}.svc.cluster.local:9090

Setting Up Extensions Content Repository

1. Initialise a New Git Repository.
2. Inside your repository, create a folder named extensions (or any other name) to contain the extension packages.
3. The structure of the extensions folder should be the following: example.
4. Create a new NPM project (if you haven't already):

   npm init 

5. [Optional] Enforce consistent extension packages format.
   • Install Husky, lint-staged, and Prettier as development dependencies. This will ensure your extension packages are well formatted.

     npm install husky lint-staged prettier --save-dev

   • Add .prettierrc file to the repository with the following content:

      {
         "printWidth": 140,
         "tabWidth": 2,
         "useTabs": false,
         "semi": true,
         "singleQuote": true,
         "quoteProps": "preserve",
         "trailingComma": "all",
         "bracketSpacing": true,
         "requirePragma": false,
         "insertPragma": false,
         "proseWrap": "preserve",
         "htmlWhitespaceSensitivity": "ignore",
         "endOfLine": "lf"
      }

   • Configure lint-staged for Prettier. For this add the following configuration to your package.json:

   "lint-staged": {
      "*.{json,yml,yaml}": "prettier --write"
    }

   • Add a prepare script in your package.json to automate the Husky setup and run automatic checks before commits:

   "scripts": {
      ...
      "prepare": "husky"
    }

6. Install @coralogix/extensions-cli as a dependency:

   npm install @coralogix/extensions-cli

7. Copy schemas from the extensions-cli package for your convenience, so you can reference them from the extensions. For this you may install shx by running the next command: npm install shx --save-dev and add the following scripts to your package.json:

   "scripts": {
     ...
     "copy:schemas": "shx cp -r node_modules/@coralogix/extensions-cli/dist/schemas .",
     "postinstall": "npm run copy:schemas"
   }

8. Set up EXTENSIONS_GRPC_API_URL environment variable per environment.
9. [Optional] Add test script for extensions validation to your package.json:

   "scripts": {
    ...
    "test": "npx cx-extensions validate -p extensions"
   }

   You may run this script as part of a CI pipeline to validate extensions.
10. In the root of your repository, create a Dockerfile with the following content:

    # Replace { node:18 } with your preferred Node.js 18 image
    FROM { node:18 } AS builder
        
    WORKDIR /app
    ADD --chown=1001:1001 package.json package-lock.json .prettierrc .prettierignore /app/
    ADD --chown=1001:1001 extensions/ /app/extensions/
        
    RUN npm ci 
            
    # Replace { node:18 } with your preferred Node.js 18 image
    FROM { node:18 } AS builder
        
    WORKDIR /app
        
    COPY --chown=1001:1001 --from=builder /app/node_modules ./node_modules
    COPY --chown=1001:1001 --from=builder /app/package.json ./package.json
    COPY --chown=1001:1001 --from=builder /app/extensions/ ./extensions
        
    CMD ["npx", "cx-extensions", "import", "-p", "extensions"]

11. Example of complete package.json file

{
  "name": "{ name of your project }",
  "version": "1.0.0",
  "description": "Content repository for Coralogix extensions",
  "scripts": {
    "prepare": "husky install",
    "preinstall": "shx cp -n testing-config.template.json testing-config.json | true",
    "copy:schemas": "shx cp -r node_modules/@coralogix/extensions-cli/dist/schemas .",
    "postinstall": "npm run copy:schemas",
    "prettier:check": "prettier --check .",
    "test": "npx cx-extensions validate -p packages"
  },
  "repository": {
    "type": "git",
    "url": "{ url to your repository }"
  },
  "keywords": [],
  "author": "",
  "license": "{ license }",
  "dependencies": {
    "@coralogix/extensions-cli": "^1.0.4"
  },
  "devDependencies": {
    "husky": "^9.0.11",
    "lint-staged": "^15.2.5",
    "prettier": "^3.3.0",
    "shx": "^0.3.4"
  },
  "lint-staged": {
    "*.{json,yml,yaml}": "prettier --write"
  }
}