From d51ce71f269569f272277c4816f1035fffdb0edc Mon Sep 17 00:00:00 2001 From: Dima Chievtaiev Date: Wed, 4 Dec 2024 01:11:53 +0100 Subject: [PATCH 01/16] Updated Adding Custom Tools to Holmes section --- docs/configuration/ai-analysis.rst | 134 ++++++++++++++++++++++++----- 1 file changed, 114 insertions(+), 20 deletions(-) diff --git a/docs/configuration/ai-analysis.rst b/docs/configuration/ai-analysis.rst index ac4d1d605..5aa4ad7a5 100644 --- a/docs/configuration/ai-analysis.rst +++ b/docs/configuration/ai-analysis.rst @@ -306,29 +306,122 @@ Holmes allows you to define custom toolsets that enhance its functionality by en In this guide, we will show how to add a custom toolset to Holmes in your ``generated_values.yaml`` file. +How to define a toolset? +------------------------------------- +A toolset is defined in ``generated_values.yaml``. Each toolset has a unique name and has to contain tools. + .. code-block:: yaml - enableHolmesGPT: true - holmes: - additionalEnvVars: - - name: ROBUSTA_AI - value: "true" - toolsets: - # Name of the toolset (for example "mycompany/internal-tools") - # Used for informational purposes only (e.g. to print the name of the toolset if it can't be loaded) - - name: "resource_explanation" - # List of tools the LLM can use - this is the important part - tools: - # Name is a unique identifier for the tool - - name: "explain_resource" - # The LLM looks at this description when deciding what tools are relevant for each task - description: "Provides detailed explanation of Kubernetes resources using kubectl explain" - # A templated bash command using Jinja2 templates - # The LLM can only control parameters that you expose as template variables like {{ resource_name }} - command: "kubectl explain {{ resource_name }}" + toolsets: + : + enabled: + name: "" + description: "" + docs_url: "" + icon_url: "" + installation_instructions: "" + variables: + : "" + prerequisites: + - command: "" + - env: + - "" + additional_instructions: "" + tools: + - name: "" + description: "" + command: "" + script: "" + parameters: + : + type: "" + description: "" + required: + +Field Descriptions +Toolset Fields + + enabled: (Optional, boolean) Indicates whether the toolset is enabled. Defaults to true. If set to false, the toolset will be disabled. + + name: (Required, string) A unique identifier for the toolset. Used for informational purposes and logging. + + description: (Optional, string) A brief description of the toolset's purpose. Helps users understand what the toolset does. + + docs_url: (Optional, string) A URL pointing to documentation related to the toolset. + + icon_url: (Optional, string) A URL to an icon representing the toolset. + + installation_instructions: (Optional, string) Instructions on how to install prerequisites required by the toolset. + + variables: (Optional, dictionary) A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the $VARIABLE_NAME syntax. + + prerequisites: (Optional, list) A list of conditions that must be met for the toolset to be enabled. Prerequisites can be: + + command: (string) A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. + + env: (list of strings) A list of environment variables that must be set. + + enabled: (boolean) A static prerequisite that can forcibly enable or disable the toolset. + + disabled_reason: (string) Provides a reason why the toolset is disabled if enabled is set to false. + + additional_instructions: (Optional, string) Additional shell commands or processing instructions applied to the output of tools in this toolset. + + tools: (Required, list) A list of tools defined within the toolset. Each tool is an object with its own set of fields. + +Tool Fields + + name: (Required, string) A unique identifier for the tool within the toolset. + + description: (Required, string) A brief description of the tool's purpose. Helps Holmes decide when to use this tool. + + command: (Optional, string) A shell command template that the tool will execute. Can include variables and parameters using Jinja2 syntax ({{ variable_name }}). + + script: (Optional, string) The content of a script that the tool will execute. Use this if your tool requires a multi-line script. + + .. note:: + + Either command or script must be provided, but not both. + + parameters: (Optional, dictionary) Defines the inputs required for the tool. Each parameter has: + + type: (string) The data type of the parameter (e.g., string, integer). + + description: (Optional, string) A description of the parameter. + + required: (Optional, boolean) Indicates whether the parameter is required. Defaults to true. + + user_description: (Optional, string) A templated string shown to the user describing this tool invocation. Not seen by the LLM (Language Model). + + additional_instructions: (Optional, string) Additional shell commands or processing instructions applied to the output of this tool. + +Defining Variables and Parameters + + Variables are defined at the toolset level under variables and can be used in any tool within the toolset. They can reference environment variables using $VARIABLE_NAME. + + Parameters are defined at the tool level under parameters and represent inputs that the user or LLM must provide when invoking the tool. They are used within command or script templates using the {{ parameter_name }} syntax. + +Prerequisites + +Prerequisites determine whether a toolset is enabled based on certain conditions: + + Command Prerequisite: Uses the command key to specify a shell command that must execute successfully. + + .. code-block:: yaml + + prerequisites: - command: "docker version" + + Environment Variable Prerequisite: Uses the env key to specify environment variables that must be set. + + .. code-block:: yaml + + prerequisites: - env: - "API_ENDPOINT" + + Static Prerequisite: Uses the enabled key to forcibly enable or disable the toolset, optionally providing a disabled_reason. + .. code-block:: yaml -``toolsets``: Defines a custom toolset, in this case, a ``resource_explanation``, which allows Holmes to use the ``kubectl explain`` command to provide details about various Kubernetes resources. + prerequisites: - enabled: false disabled_reason: "Toolset is disabled for maintenance." Once you have updated the ``generated_values.yaml`` file, apply the changes by running the Helm upgrade command: @@ -412,7 +505,8 @@ After pushing your custom Docker image, update your ``generated_values.yaml`` to - name: ROBUSTA_AI value: "true" toolsets: - - name: "json_processor" + json_processor: + description: "A toolset for processing JSON data using jq" prerequisites: - command: "jq --version" # Ensure jq is installed tools: From 2e7e9b59650ccf6a037f12fb090bce26ff29c63e Mon Sep 17 00:00:00 2001 From: Dima Chievtaiev Date: Wed, 4 Dec 2024 01:35:30 +0100 Subject: [PATCH 02/16] Updated AI analysis docs format --- docs/configuration/ai-analysis.rst | 863 ++++++++++++++++++++++++++--- 1 file changed, 793 insertions(+), 70 deletions(-) diff --git a/docs/configuration/ai-analysis.rst b/docs/configuration/ai-analysis.rst index 5aa4ad7a5..9e0e5de29 100644 --- a/docs/configuration/ai-analysis.rst +++ b/docs/configuration/ai-analysis.rst @@ -338,90 +338,171 @@ A toolset is defined in ``generated_values.yaml``. Each toolset has a unique nam description: "" required: +Field Descriptions Field Descriptions Toolset Fields - enabled: (Optional, boolean) Indicates whether the toolset is enabled. Defaults to true. If set to false, the toolset will be disabled. - - name: (Required, string) A unique identifier for the toolset. Used for informational purposes and logging. - - description: (Optional, string) A brief description of the toolset's purpose. Helps users understand what the toolset does. - - docs_url: (Optional, string) A URL pointing to documentation related to the toolset. - - icon_url: (Optional, string) A URL to an icon representing the toolset. - - installation_instructions: (Optional, string) Instructions on how to install prerequisites required by the toolset. - - variables: (Optional, dictionary) A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the $VARIABLE_NAME syntax. - - prerequisites: (Optional, list) A list of conditions that must be met for the toolset to be enabled. Prerequisites can be: - - command: (string) A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. - - env: (list of strings) A list of environment variables that must be set. - - enabled: (boolean) A static prerequisite that can forcibly enable or disable the toolset. - - disabled_reason: (string) Provides a reason why the toolset is disabled if enabled is set to false. - - additional_instructions: (Optional, string) Additional shell commands or processing instructions applied to the output of tools in this toolset. - - tools: (Required, list) A list of tools defined within the toolset. Each tool is an object with its own set of fields. - -Tool Fields - - name: (Required, string) A unique identifier for the tool within the toolset. - - description: (Required, string) A brief description of the tool's purpose. Helps Holmes decide when to use this tool. - - command: (Optional, string) A shell command template that the tool will execute. Can include variables and parameters using Jinja2 syntax ({{ variable_name }}). - - script: (Optional, string) The content of a script that the tool will execute. Use this if your tool requires a multi-line script. - - .. note:: - - Either command or script must be provided, but not both. - - parameters: (Optional, dictionary) Defines the inputs required for the tool. Each parameter has: - - type: (string) The data type of the parameter (e.g., string, integer). - - description: (Optional, string) A description of the parameter. - - required: (Optional, boolean) Indicates whether the parameter is required. Defaults to true. - - user_description: (Optional, string) A templated string shown to the user describing this tool invocation. Not seen by the LLM (Language Model). - - additional_instructions: (Optional, string) Additional shell commands or processing instructions applied to the output of this tool. - -Defining Variables and Parameters - - Variables are defined at the toolset level under variables and can be used in any tool within the toolset. They can reference environment variables using $VARIABLE_NAME. - - Parameters are defined at the tool level under parameters and represent inputs that the user or LLM must provide when invoking the tool. They are used within command or script templates using the {{ parameter_name }} syntax. - -Prerequisites +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``enabled`` + - boolean + - Indicates whether the toolset is enabled. Defaults to ``true``. If set to ``false``, the toolset will be disabled. + - No + * - ``name`` + - string + - A unique identifier for the toolset. Used for informational purposes and logging. + - **Yes** + * - ``description`` + - string + - A brief description of the toolset's purpose. Helps users understand what the toolset does. + - No + * - ``docs_url`` + - string + - A URL pointing to documentation related to the toolset. + - No + * - ``icon_url`` + - string + - A URL to an icon representing the toolset. + - No + * - ``installation_instructions`` + - string + - Instructions on how to install prerequisites required by the toolset. + - No + * - ``variables`` + - dictionary + - A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the ``$VARIABLE_NAME`` syntax. + - No + * - ``prerequisites`` + - list + - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands, environment variables, or static conditions. + - No + * - ``additional_instructions`` + - string + - Additional shell commands or processing instructions applied to the output of tools in this toolset. + - No + * - ``tools`` + - list + - A list of tools defined within the toolset. Each tool is an object with its own set of fields. + - **Yes** + +#### Tool Fields + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``name`` + - string + - A unique identifier for the tool within the toolset. + - **Yes** + * - ``description`` + - string + - A brief description of the tool's purpose. Helps Holmes decide when to use this tool. + - **Yes** + * - ``command`` + - string + - A shell command template that the tool will execute. Can include variables and parameters using Jinja2 syntax (``{{ variable_name }}``). + - At least one of ``command`` or ``script`` is required + * - ``script`` + - string + - The content of a script that the tool will execute. Use this if your tool requires a multi-line script. + - At least one of ``command`` or ``script`` is required + * - ``parameters`` + - dictionary + - Defines the inputs required for the tool. Each parameter has its own fields. + - No + * - ``additional_instructions`` + - string + - Additional shell commands or processing instructions applied to the output of this tool. + - No + +#### Parameter Fields (Within ``parameters``) + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``type`` + - string + - The data type of the parameter (e.g., ``string``, ``integer``). + - No (defaults to ``string``) + * - ``description`` + - string + - A description of the parameter. + - No + * - ``required`` + - boolean + - Indicates whether the parameter is required. Defaults to ``true``. + - No + +### Defining Variables and Parameters + +- **Variables** are defined at the toolset level under ``variables`` and can be used in any tool within the toolset. They can reference environment variables using ``$VARIABLE_NAME``. + +- **Parameters** are defined at the tool level under ``parameters`` and represent inputs that the user or LLM must provide when invoking the tool. They are used within ``command`` or ``script`` templates using the ``{{ parameter_name }}`` syntax. + +### Prerequisites Prerequisites determine whether a toolset is enabled based on certain conditions: - Command Prerequisite: Uses the command key to specify a shell command that must execute successfully. +#### Command Prerequisite + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 - .. code-block:: yaml + * - **Key** + - **Type** + - **Description** + - **Required** + * - ``command`` + - string + - A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. + - **Yes** - prerequisites: - command: "docker version" +**Example:** - Environment Variable Prerequisite: Uses the env key to specify environment variables that must be set. +```yaml +prerequisites: + - command: "docker version" +``` - .. code-block:: yaml +#### Environment Variable Prerequisite - prerequisites: - env: - "API_ENDPOINT" +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 - Static Prerequisite: Uses the enabled key to forcibly enable or disable the toolset, optionally providing a disabled_reason. + * - **Key** + - **Type** + - **Description** + - **Required** + * - ``env`` + - list of strings + - A list of environment variables that must be set. + - **Yes** - .. code-block:: yaml +**Example:** - prerequisites: - enabled: false disabled_reason: "Toolset is disabled for maintenance." +```yaml +prerequisites: + - env: + - "API_ENDPOINT" +``` Once you have updated the ``generated_values.yaml`` file, apply the changes by running the Helm upgrade command: @@ -563,3 +644,645 @@ Deploy the updated configuration using Helm: This will grant HolmesGPT the necessary permissions to analyze Argo CD applications and projects. Now you can ask HolmesGPT questions like "What is the current status of all Argo CD applications in the cluster?" and it will be able to answer. + + + + + + + + +Adding Custom Tools to Holmes +============================= + +Holmes allows you to define custom toolsets that enhance its functionality by enabling additional tools to run Kubernetes commands or perform other tasks. This guide explains the structure of a toolset, how to define one, and provides examples demonstrating new features and capabilities. + +Toolset Structure and Fields +---------------------------- + +A toolset is defined using YAML syntax and consists of several key fields that configure its behavior and capabilities. Below is a breakdown of the structure and explanation of each field. + +### Overall Structure + +A toolset is typically defined under the `toolsets` key in your configuration file (e.g., `generated_values.yaml` or a separate YAML file for custom toolsets). Each toolset has a unique name and contains various fields that define its properties, prerequisites, variables, and tools. + +```yaml +toolsets: + : + enabled: + name: "" + description: "" + docs_url: "" + icon_url: "" + installation_instructions: "" + variables: + : "" + prerequisites: + - command: "" + - env: + - "" + - enabled: + disabled_reason: "" + additional_instructions: "" + tools: + - name: "" + description: "" + command: "" + script: "" + parameters: + : + type: "" + description: "" + required: + user_description: "" + additional_instructions: "" +``` + +### Field Descriptions + +#### Toolset Fields + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``enabled`` + - boolean + - Indicates whether the toolset is enabled. Defaults to ``true``. If set to ``false``, the toolset will be disabled. + - No + * - ``name`` + - string + - A unique identifier for the toolset. Used for informational purposes and logging. + - **Yes** + * - ``description`` + - string + - A brief description of the toolset's purpose. Helps users understand what the toolset does. + - No + * - ``docs_url`` + - string + - A URL pointing to documentation related to the toolset. + - No + * - ``icon_url`` + - string + - A URL to an icon representing the toolset. + - No + * - ``installation_instructions`` + - string + - Instructions on how to install prerequisites required by the toolset. + - No + * - ``variables`` + - dictionary + - A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the ``$VARIABLE_NAME`` syntax. + - No + * - ``prerequisites`` + - list + - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands, environment variables, or static conditions. + - No + * - ``additional_instructions`` + - string + - Additional shell commands or processing instructions applied to the output of tools in this toolset. + - No + * - ``tools`` + - list + - A list of tools defined within the toolset. Each tool is an object with its own set of fields. + - **Yes** + +#### Tool Fields + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``name`` + - string + - A unique identifier for the tool within the toolset. + - **Yes** + * - ``description`` + - string + - A brief description of the tool's purpose. Helps Holmes decide when to use this tool. + - **Yes** + * - ``command`` + - string + - A shell command template that the tool will execute. Can include variables and parameters using Jinja2 syntax (``{{ variable_name }}``). + - At least one of ``command`` or ``script`` is required + * - ``script`` + - string + - The content of a script that the tool will execute. Use this if your tool requires a multi-line script. + - At least one of ``command`` or ``script`` is required + * - ``parameters`` + - dictionary + - Defines the inputs required for the tool. Each parameter has its own fields. + - No + * - ``user_description`` + - string + - A templated string shown to the user describing this tool invocation. Not seen by the LLM (Language Model). + - No + * - ``additional_instructions`` + - string + - Additional shell commands or processing instructions applied to the output of this tool. + - No + +#### Parameter Fields (Within ``parameters``) + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + - **Required** + * - ``type`` + - string + - The data type of the parameter (e.g., ``string``, ``integer``). + - No (defaults to ``string``) + * - ``description`` + - string + - A description of the parameter. + - No + * - ``required`` + - boolean + - Indicates whether the parameter is required. Defaults to ``true``. + - No + +### Defining Variables and Parameters + +- **Variables** are defined at the toolset level under ``variables`` and can be used in any tool within the toolset. They can reference environment variables using ``$VARIABLE_NAME``. + +- **Parameters** are defined at the tool level under ``parameters`` and represent inputs that the user or LLM must provide when invoking the tool. They are used within ``command`` or ``script`` templates using the ``{{ parameter_name }}`` syntax. + +### Prerequisites + +Prerequisites determine whether a toolset is enabled based on certain conditions: + +#### Command Prerequisite + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Key** + - **Type** + - **Description** + - **Required** + * - ``command`` + - string + - A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. + - **Yes** + +**Example:** + +```yaml +prerequisites: + - command: "docker version" +``` + +#### Environment Variable Prerequisite + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Key** + - **Type** + - **Description** + - **Required** + * - ``env`` + - list of strings + - A list of environment variables that must be set. + - **Yes** + +**Example:** + +```yaml +prerequisites: + - env: + - "API_ENDPOINT" +``` + +#### Static Prerequisite + +.. list-table:: + :widths: 20 10 60 10 + :header-rows: 1 + + * - **Key** + - **Type** + - **Description** + - **Required** + * - ``enabled`` + - boolean + - A static prerequisite that can forcibly enable or disable the toolset. + - **Yes** + * - ``disabled_reason`` + - string + - Provides a reason why the toolset is disabled if ``enabled`` is set to ``false``. + - No (but recommended if ``enabled`` is ``false``) + +**Example:** + +```yaml +prerequisites: + - enabled: false + disabled_reason: "Toolset is disabled for maintenance." +``` + +### Additional Instructions + +- **Toolset Level**: ``additional_instructions`` at the toolset level apply to the output of all tools within the toolset. + +- **Tool Level**: ``additional_instructions`` at the tool level apply only to the output of that specific tool. + +These instructions can be any shell command or processing step (e.g., using ``jq`` to parse JSON output). + +Examples +-------- + +Now that we've covered the structure and fields of a toolset, let's explore some examples demonstrating how to define custom toolsets with various features and capabilities. + +### Example 1: Managing Docker Containers + +Let's create a toolset that allows Holmes to manage Docker containers by listing images and running containers. + +**Configuration (`generated_values.yaml`):** + +```yaml +enableHolmesGPT: true +holmes: + toolsets: + - name: "docker_tools" + description: "Tools for managing Docker containers" + icon_url: "https://www.docker.com/" + docs_url: "https://docs.docker.com/" + installation_instructions: "Please install Docker on your system." + prerequisites: + - command: "docker version" # Ensures Docker is installed + tools: + - name: "docker_images" + description: "List all Docker images" + command: "docker images" + - name: "docker_ps" + description: "List all running Docker containers" + command: "docker ps" + - name: "docker_ps_all" + description: "List all Docker containers, including stopped ones" + command: "docker ps -a" +``` + +**Explanation:** + +- **Prerequisites**: Checks that Docker is installed by running ``docker version``. + +- **Tools**: + + - **``docker_images``**: Lists all Docker images. + + - **``docker_ps``**: Lists all running Docker containers. + + - **``docker_ps_all``**: Lists all Docker containers, including those that are stopped. + +**Applying the Changes:** + +Run the Helm upgrade command: + +```bash +helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +``` + +### Example 2: Performing HTTP Requests with Variables and Additional Instructions + +This example demonstrates how to use environment variables, parameters, and additional instructions to enhance tool functionality. + +**Configuration (`generated_values.yaml`):** + +```yaml +holmes: + additionalEnvVars: + - name: API_ENDPOINT + value: "https://api.example.com/data" # Replace with your actual API endpoint + toolsets: + - name: "http_tools" + description: "Tools for making HTTP requests using curl" + variables: + test_variable: "HelloWorld" + api_endpoint: "$API_ENDPOINT" + prerequisites: + - env: + - "API_ENDPOINT" + - command: "curl --version" + additional_instructions: "jq -r '.result.data'" + tools: + - name: "curl_example" + description: "Perform an HTTP GET request to the API endpoint using variables" + command: "curl -X GET '{{ api_endpoint }}?query={{ query_param }}' -H 'Custom-Header: {{ test_variable }}'" + parameters: + query_param: + type: "string" + description: "Query parameter to append to the request" + required: true +``` + +**Explanation:** + +- **Variables**: + + - **``test_variable``**: A custom variable with a hardcoded value. + + - **``api_endpoint``**: Uses the ``API_ENDPOINT`` environment variable. + +- **Prerequisites**: + + - Ensures ``API_ENDPOINT`` is set. + + - Checks that ``curl`` is installed. + +- **Additional Instructions**: + + - Uses ``jq`` to process the JSON output from the ``curl`` command. + +- **Tools**: + + - **``curl_example``**: Performs an HTTP GET request, incorporating variables and user-provided parameters. + +**Applying the Changes:** + +Run the Helm upgrade command: + +```bash +helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +``` + +### Example 3: Kubernetes Resource Management + +This example shows how to add tools for managing Kubernetes resources. + +**Configuration (`generated_values.yaml`):** + +```yaml +holmes: + toolsets: + - name: "kubernetes_manager" + description: "Manage Kubernetes resources" + tools: + - name: "get_pods" + description: "Retrieve a list of pods in the specified namespace" + command: "kubectl get pods -n {{ namespace }}" + parameters: + namespace: + type: "string" + description: "The namespace to query" + required: true + - name: "describe_pod" + description: "Describe a specific pod" + command: "kubectl describe pod {{ pod_name }} -n {{ namespace }}" + parameters: + pod_name: + type: "string" + description: "The name of the pod" + required: true + namespace: + type: "string" + description: "The namespace of the pod" + required: true +``` + +**Explanation:** + +- **Tools**: + + - **``get_pods``**: Lists pods in a specified namespace. + + - **``describe_pod``**: Provides details about a specific pod. + +- **Parameters**: Allows dynamic input for ``namespace`` and ``pod_name``. + +**Applying the Changes:** + +Run the Helm upgrade command: + +```bash +helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +``` + +### Example 4: Adding a Tool Requiring a New Binary (`jq` for JSON Processing) + +When a tool requires binaries not present in the base image, you need to create a custom Docker image. + +**Step 1: Create a Custom Docker Image** + +**Dockerfile:** + +```dockerfile +FROM python:3.11-slim + +ENV PYTHONUNBUFFERED=1 +ENV PATH="/venv/bin:$PATH" +ENV PYTHONPATH=$PYTHONPATH:.:/app/holmes + +WORKDIR /app + +COPY . /app + +RUN apt-get update \ + && apt-get install -y --no-install-recommends \ + jq \ + && rm -rf /var/lib/apt/lists/* + +# Install any additional dependencies required by Holmes +RUN pip install --no-cache-dir -r requirements.txt +``` + +**Build and Push the Image:** + +```bash +docker build -t //holmes-custom: . +docker push //holmes-custom: +``` + +**Step 2: Update `generated_values.yaml`** + +```yaml +holmes: + registry: / + image: holmes-custom + imageTag: + toolsets: + - name: "json_processor" + description: "Process JSON data using jq" + prerequisites: + - command: "jq --version" + tools: + - name: "format_json" + description: "Formats JSON input for readability" + command: "echo '{{ json_input }}' | jq '.'" + parameters: + json_input: + type: "string" + description: "The JSON string to format" + required: true +``` + +**Explanation:** + +- **Custom Image**: Configured to use the image built with ``jq`` installed. + +- **Prerequisites**: Checks that ``jq`` is available. + +- **Tools**: + + - **``format_json``**: Uses ``jq`` to format JSON input. + +**Applying the Changes:** + +Deploy the updated configuration: + +```bash +helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +``` + +### Example 5: Using Additional Instructions at the Tool Level + +This example demonstrates how to apply additional processing to the output of a specific tool. + +**Configuration (`generated_values.yaml`):** + +```yaml +holmes: + toolsets: + - name: "log_processor" + description: "Process logs from a service" + tools: + - name: "fetch_logs" + description: "Fetch logs and process them" + command: "kubectl logs {{ pod_name }} -n {{ namespace }}" + parameters: + pod_name: + type: "string" + description: "The name of the pod" + required: true + namespace: + type: "string" + description: "The namespace of the pod" + required: true + additional_instructions: "grep ERROR" +``` + +**Explanation:** + +- **Tool**: + + - **``fetch_logs``**: Fetches logs from a pod. + +- **Additional Instructions**: + + - **At Tool Level**: Applies ``grep ERROR`` to filter logs containing the word "ERROR". + +**Applying the Changes:** + +Run the Helm upgrade command: + +```bash +helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +``` + +Using ConfigMaps to Provide Custom Toolsets +------------------------------------------- + +In Kubernetes environments, you can use ConfigMaps to provide custom toolsets to Holmes without modifying the `generated_values.yaml` file. + +**Step 1: Create a ConfigMap with Your Toolsets** + +Create a file named `custom-toolsets.yaml` with your toolset definitions. + +**Example (`custom-toolsets.yaml`):** + +```yaml +toolsets: + custom_toolset: + name: "custom_toolset" + description: "A custom toolset defined in a ConfigMap" + tools: + - name: "custom_command" + description: "Runs a custom command" + command: "echo 'Hello from custom toolset'" +``` + +Create the ConfigMap: + +```bash +kubectl create configmap custom-toolsets-configmap --from-file=custom-toolsets.yaml +``` + +**Step 2: Mount the ConfigMap in Your Deployment** + +Modify your deployment to include the ConfigMap: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: holmes-deployment +spec: + replicas: 1 + selector: + matchLabels: + app: holmes + template: + metadata: + labels: + app: holmes + spec: + containers: + - name: holmes-container + image: your-holmes-image:latest + volumeMounts: + - name: custom-toolsets-volume + mountPath: "/etc/holmes/config/custom-toolsets.yaml" + subPath: "custom-toolsets.yaml" + volumes: + - name: custom-toolsets-volume + configMap: + name: custom-toolsets-configmap + items: + - key: custom-toolsets.yaml + path: custom-toolsets.yaml +``` + +**Explanation:** + +- **Volume Mounts**: Mounts the `custom-toolsets.yaml` file into the container. + +- **Holmes Configuration**: Holmes will load toolsets from the mounted file. + +**Step 3: Apply the Deployment** + +```bash +kubectl apply -f your-deployment.yaml +``` + +By using ConfigMaps, you can manage custom toolsets separately from your main configuration. + +Conclusion +---------- + +By understanding the structure and fields of a toolset, you can effectively extend Holmes's capabilities to suit your specific needs. The examples provided demonstrate how to: + +- Define toolsets with various features such as variables, parameters, and prerequisites. + +- Use environment variables and additional instructions to enhance tools. + +- Handle tools that require additional binaries by creating custom Docker images. + +- Apply processing instructions at both the toolset and tool levels. + +- Manage custom toolsets using ConfigMaps in Kubernetes environments. + +Feel free to experiment and create your own toolsets to unlock the full potential of Holmes in your environment. If you have any questions or need further assistance, refer to the Holmes documentation or reach out to the community for support. From 4730eca093ee38f9357bfad68df55deff1153323 Mon Sep 17 00:00:00 2001 From: Dima Chievtaiev Date: Thu, 5 Dec 2024 01:37:28 +0100 Subject: [PATCH 03/16] Fixed ai-analysis typos --- docs/configuration/ai-analysis.rst | 661 +---------------------------- 1 file changed, 9 insertions(+), 652 deletions(-) diff --git a/docs/configuration/ai-analysis.rst b/docs/configuration/ai-analysis.rst index 9e0e5de29..cdc68ce6e 100644 --- a/docs/configuration/ai-analysis.rst +++ b/docs/configuration/ai-analysis.rst @@ -338,9 +338,8 @@ A toolset is defined in ``generated_values.yaml``. Each toolset has a unique nam description: "" required: -Field Descriptions -Field Descriptions Toolset Fields +-------------- .. list-table:: :widths: 20 10 60 10 @@ -377,10 +376,15 @@ Toolset Fields * - ``variables`` - dictionary - A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the ``$VARIABLE_NAME`` syntax. + ```yaml + variables: + api_endpoint: "$API_ENDPOINT" + default_timeout: "60" + ``` - No * - ``prerequisites`` - list - - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands, environment variables, or static conditions. + - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands or environment variables. - No * - ``additional_instructions`` - string @@ -391,7 +395,7 @@ Toolset Fields - A list of tools defined within the toolset. Each tool is an object with its own set of fields. - **Yes** -#### Tool Fields + **Tool Fields** .. list-table:: :widths: 20 10 60 10 @@ -426,7 +430,7 @@ Toolset Fields - Additional shell commands or processing instructions applied to the output of this tool. - No -#### Parameter Fields (Within ``parameters``) +**Parameter Fields (Within ``parameters``)** .. list-table:: :widths: 20 10 60 10 @@ -449,11 +453,6 @@ Toolset Fields - Indicates whether the parameter is required. Defaults to ``true``. - No -### Defining Variables and Parameters - -- **Variables** are defined at the toolset level under ``variables`` and can be used in any tool within the toolset. They can reference environment variables using ``$VARIABLE_NAME``. - -- **Parameters** are defined at the tool level under ``parameters`` and represent inputs that the user or LLM must provide when invoking the tool. They are used within ``command`` or ``script`` templates using the ``{{ parameter_name }}`` syntax. ### Prerequisites @@ -644,645 +643,3 @@ Deploy the updated configuration using Helm: This will grant HolmesGPT the necessary permissions to analyze Argo CD applications and projects. Now you can ask HolmesGPT questions like "What is the current status of all Argo CD applications in the cluster?" and it will be able to answer. - - - - - - - - -Adding Custom Tools to Holmes -============================= - -Holmes allows you to define custom toolsets that enhance its functionality by enabling additional tools to run Kubernetes commands or perform other tasks. This guide explains the structure of a toolset, how to define one, and provides examples demonstrating new features and capabilities. - -Toolset Structure and Fields ----------------------------- - -A toolset is defined using YAML syntax and consists of several key fields that configure its behavior and capabilities. Below is a breakdown of the structure and explanation of each field. - -### Overall Structure - -A toolset is typically defined under the `toolsets` key in your configuration file (e.g., `generated_values.yaml` or a separate YAML file for custom toolsets). Each toolset has a unique name and contains various fields that define its properties, prerequisites, variables, and tools. - -```yaml -toolsets: - : - enabled: - name: "" - description: "" - docs_url: "" - icon_url: "" - installation_instructions: "" - variables: - : "" - prerequisites: - - command: "" - - env: - - "" - - enabled: - disabled_reason: "" - additional_instructions: "" - tools: - - name: "" - description: "" - command: "" - script: "" - parameters: - : - type: "" - description: "" - required: - user_description: "" - additional_instructions: "" -``` - -### Field Descriptions - -#### Toolset Fields - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Parameter** - - **Type** - - **Description** - - **Required** - * - ``enabled`` - - boolean - - Indicates whether the toolset is enabled. Defaults to ``true``. If set to ``false``, the toolset will be disabled. - - No - * - ``name`` - - string - - A unique identifier for the toolset. Used for informational purposes and logging. - - **Yes** - * - ``description`` - - string - - A brief description of the toolset's purpose. Helps users understand what the toolset does. - - No - * - ``docs_url`` - - string - - A URL pointing to documentation related to the toolset. - - No - * - ``icon_url`` - - string - - A URL to an icon representing the toolset. - - No - * - ``installation_instructions`` - - string - - Instructions on how to install prerequisites required by the toolset. - - No - * - ``variables`` - - dictionary - - A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the ``$VARIABLE_NAME`` syntax. - - No - * - ``prerequisites`` - - list - - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands, environment variables, or static conditions. - - No - * - ``additional_instructions`` - - string - - Additional shell commands or processing instructions applied to the output of tools in this toolset. - - No - * - ``tools`` - - list - - A list of tools defined within the toolset. Each tool is an object with its own set of fields. - - **Yes** - -#### Tool Fields - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Parameter** - - **Type** - - **Description** - - **Required** - * - ``name`` - - string - - A unique identifier for the tool within the toolset. - - **Yes** - * - ``description`` - - string - - A brief description of the tool's purpose. Helps Holmes decide when to use this tool. - - **Yes** - * - ``command`` - - string - - A shell command template that the tool will execute. Can include variables and parameters using Jinja2 syntax (``{{ variable_name }}``). - - At least one of ``command`` or ``script`` is required - * - ``script`` - - string - - The content of a script that the tool will execute. Use this if your tool requires a multi-line script. - - At least one of ``command`` or ``script`` is required - * - ``parameters`` - - dictionary - - Defines the inputs required for the tool. Each parameter has its own fields. - - No - * - ``user_description`` - - string - - A templated string shown to the user describing this tool invocation. Not seen by the LLM (Language Model). - - No - * - ``additional_instructions`` - - string - - Additional shell commands or processing instructions applied to the output of this tool. - - No - -#### Parameter Fields (Within ``parameters``) - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Parameter** - - **Type** - - **Description** - - **Required** - * - ``type`` - - string - - The data type of the parameter (e.g., ``string``, ``integer``). - - No (defaults to ``string``) - * - ``description`` - - string - - A description of the parameter. - - No - * - ``required`` - - boolean - - Indicates whether the parameter is required. Defaults to ``true``. - - No - -### Defining Variables and Parameters - -- **Variables** are defined at the toolset level under ``variables`` and can be used in any tool within the toolset. They can reference environment variables using ``$VARIABLE_NAME``. - -- **Parameters** are defined at the tool level under ``parameters`` and represent inputs that the user or LLM must provide when invoking the tool. They are used within ``command`` or ``script`` templates using the ``{{ parameter_name }}`` syntax. - -### Prerequisites - -Prerequisites determine whether a toolset is enabled based on certain conditions: - -#### Command Prerequisite - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Key** - - **Type** - - **Description** - - **Required** - * - ``command`` - - string - - A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. - - **Yes** - -**Example:** - -```yaml -prerequisites: - - command: "docker version" -``` - -#### Environment Variable Prerequisite - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Key** - - **Type** - - **Description** - - **Required** - * - ``env`` - - list of strings - - A list of environment variables that must be set. - - **Yes** - -**Example:** - -```yaml -prerequisites: - - env: - - "API_ENDPOINT" -``` - -#### Static Prerequisite - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Key** - - **Type** - - **Description** - - **Required** - * - ``enabled`` - - boolean - - A static prerequisite that can forcibly enable or disable the toolset. - - **Yes** - * - ``disabled_reason`` - - string - - Provides a reason why the toolset is disabled if ``enabled`` is set to ``false``. - - No (but recommended if ``enabled`` is ``false``) - -**Example:** - -```yaml -prerequisites: - - enabled: false - disabled_reason: "Toolset is disabled for maintenance." -``` - -### Additional Instructions - -- **Toolset Level**: ``additional_instructions`` at the toolset level apply to the output of all tools within the toolset. - -- **Tool Level**: ``additional_instructions`` at the tool level apply only to the output of that specific tool. - -These instructions can be any shell command or processing step (e.g., using ``jq`` to parse JSON output). - -Examples --------- - -Now that we've covered the structure and fields of a toolset, let's explore some examples demonstrating how to define custom toolsets with various features and capabilities. - -### Example 1: Managing Docker Containers - -Let's create a toolset that allows Holmes to manage Docker containers by listing images and running containers. - -**Configuration (`generated_values.yaml`):** - -```yaml -enableHolmesGPT: true -holmes: - toolsets: - - name: "docker_tools" - description: "Tools for managing Docker containers" - icon_url: "https://www.docker.com/" - docs_url: "https://docs.docker.com/" - installation_instructions: "Please install Docker on your system." - prerequisites: - - command: "docker version" # Ensures Docker is installed - tools: - - name: "docker_images" - description: "List all Docker images" - command: "docker images" - - name: "docker_ps" - description: "List all running Docker containers" - command: "docker ps" - - name: "docker_ps_all" - description: "List all Docker containers, including stopped ones" - command: "docker ps -a" -``` - -**Explanation:** - -- **Prerequisites**: Checks that Docker is installed by running ``docker version``. - -- **Tools**: - - - **``docker_images``**: Lists all Docker images. - - - **``docker_ps``**: Lists all running Docker containers. - - - **``docker_ps_all``**: Lists all Docker containers, including those that are stopped. - -**Applying the Changes:** - -Run the Helm upgrade command: - -```bash -helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= -``` - -### Example 2: Performing HTTP Requests with Variables and Additional Instructions - -This example demonstrates how to use environment variables, parameters, and additional instructions to enhance tool functionality. - -**Configuration (`generated_values.yaml`):** - -```yaml -holmes: - additionalEnvVars: - - name: API_ENDPOINT - value: "https://api.example.com/data" # Replace with your actual API endpoint - toolsets: - - name: "http_tools" - description: "Tools for making HTTP requests using curl" - variables: - test_variable: "HelloWorld" - api_endpoint: "$API_ENDPOINT" - prerequisites: - - env: - - "API_ENDPOINT" - - command: "curl --version" - additional_instructions: "jq -r '.result.data'" - tools: - - name: "curl_example" - description: "Perform an HTTP GET request to the API endpoint using variables" - command: "curl -X GET '{{ api_endpoint }}?query={{ query_param }}' -H 'Custom-Header: {{ test_variable }}'" - parameters: - query_param: - type: "string" - description: "Query parameter to append to the request" - required: true -``` - -**Explanation:** - -- **Variables**: - - - **``test_variable``**: A custom variable with a hardcoded value. - - - **``api_endpoint``**: Uses the ``API_ENDPOINT`` environment variable. - -- **Prerequisites**: - - - Ensures ``API_ENDPOINT`` is set. - - - Checks that ``curl`` is installed. - -- **Additional Instructions**: - - - Uses ``jq`` to process the JSON output from the ``curl`` command. - -- **Tools**: - - - **``curl_example``**: Performs an HTTP GET request, incorporating variables and user-provided parameters. - -**Applying the Changes:** - -Run the Helm upgrade command: - -```bash -helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= -``` - -### Example 3: Kubernetes Resource Management - -This example shows how to add tools for managing Kubernetes resources. - -**Configuration (`generated_values.yaml`):** - -```yaml -holmes: - toolsets: - - name: "kubernetes_manager" - description: "Manage Kubernetes resources" - tools: - - name: "get_pods" - description: "Retrieve a list of pods in the specified namespace" - command: "kubectl get pods -n {{ namespace }}" - parameters: - namespace: - type: "string" - description: "The namespace to query" - required: true - - name: "describe_pod" - description: "Describe a specific pod" - command: "kubectl describe pod {{ pod_name }} -n {{ namespace }}" - parameters: - pod_name: - type: "string" - description: "The name of the pod" - required: true - namespace: - type: "string" - description: "The namespace of the pod" - required: true -``` - -**Explanation:** - -- **Tools**: - - - **``get_pods``**: Lists pods in a specified namespace. - - - **``describe_pod``**: Provides details about a specific pod. - -- **Parameters**: Allows dynamic input for ``namespace`` and ``pod_name``. - -**Applying the Changes:** - -Run the Helm upgrade command: - -```bash -helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= -``` - -### Example 4: Adding a Tool Requiring a New Binary (`jq` for JSON Processing) - -When a tool requires binaries not present in the base image, you need to create a custom Docker image. - -**Step 1: Create a Custom Docker Image** - -**Dockerfile:** - -```dockerfile -FROM python:3.11-slim - -ENV PYTHONUNBUFFERED=1 -ENV PATH="/venv/bin:$PATH" -ENV PYTHONPATH=$PYTHONPATH:.:/app/holmes - -WORKDIR /app - -COPY . /app - -RUN apt-get update \ - && apt-get install -y --no-install-recommends \ - jq \ - && rm -rf /var/lib/apt/lists/* - -# Install any additional dependencies required by Holmes -RUN pip install --no-cache-dir -r requirements.txt -``` - -**Build and Push the Image:** - -```bash -docker build -t //holmes-custom: . -docker push //holmes-custom: -``` - -**Step 2: Update `generated_values.yaml`** - -```yaml -holmes: - registry: / - image: holmes-custom - imageTag: - toolsets: - - name: "json_processor" - description: "Process JSON data using jq" - prerequisites: - - command: "jq --version" - tools: - - name: "format_json" - description: "Formats JSON input for readability" - command: "echo '{{ json_input }}' | jq '.'" - parameters: - json_input: - type: "string" - description: "The JSON string to format" - required: true -``` - -**Explanation:** - -- **Custom Image**: Configured to use the image built with ``jq`` installed. - -- **Prerequisites**: Checks that ``jq`` is available. - -- **Tools**: - - - **``format_json``**: Uses ``jq`` to format JSON input. - -**Applying the Changes:** - -Deploy the updated configuration: - -```bash -helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= -``` - -### Example 5: Using Additional Instructions at the Tool Level - -This example demonstrates how to apply additional processing to the output of a specific tool. - -**Configuration (`generated_values.yaml`):** - -```yaml -holmes: - toolsets: - - name: "log_processor" - description: "Process logs from a service" - tools: - - name: "fetch_logs" - description: "Fetch logs and process them" - command: "kubectl logs {{ pod_name }} -n {{ namespace }}" - parameters: - pod_name: - type: "string" - description: "The name of the pod" - required: true - namespace: - type: "string" - description: "The namespace of the pod" - required: true - additional_instructions: "grep ERROR" -``` - -**Explanation:** - -- **Tool**: - - - **``fetch_logs``**: Fetches logs from a pod. - -- **Additional Instructions**: - - - **At Tool Level**: Applies ``grep ERROR`` to filter logs containing the word "ERROR". - -**Applying the Changes:** - -Run the Helm upgrade command: - -```bash -helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= -``` - -Using ConfigMaps to Provide Custom Toolsets -------------------------------------------- - -In Kubernetes environments, you can use ConfigMaps to provide custom toolsets to Holmes without modifying the `generated_values.yaml` file. - -**Step 1: Create a ConfigMap with Your Toolsets** - -Create a file named `custom-toolsets.yaml` with your toolset definitions. - -**Example (`custom-toolsets.yaml`):** - -```yaml -toolsets: - custom_toolset: - name: "custom_toolset" - description: "A custom toolset defined in a ConfigMap" - tools: - - name: "custom_command" - description: "Runs a custom command" - command: "echo 'Hello from custom toolset'" -``` - -Create the ConfigMap: - -```bash -kubectl create configmap custom-toolsets-configmap --from-file=custom-toolsets.yaml -``` - -**Step 2: Mount the ConfigMap in Your Deployment** - -Modify your deployment to include the ConfigMap: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: holmes-deployment -spec: - replicas: 1 - selector: - matchLabels: - app: holmes - template: - metadata: - labels: - app: holmes - spec: - containers: - - name: holmes-container - image: your-holmes-image:latest - volumeMounts: - - name: custom-toolsets-volume - mountPath: "/etc/holmes/config/custom-toolsets.yaml" - subPath: "custom-toolsets.yaml" - volumes: - - name: custom-toolsets-volume - configMap: - name: custom-toolsets-configmap - items: - - key: custom-toolsets.yaml - path: custom-toolsets.yaml -``` - -**Explanation:** - -- **Volume Mounts**: Mounts the `custom-toolsets.yaml` file into the container. - -- **Holmes Configuration**: Holmes will load toolsets from the mounted file. - -**Step 3: Apply the Deployment** - -```bash -kubectl apply -f your-deployment.yaml -``` - -By using ConfigMaps, you can manage custom toolsets separately from your main configuration. - -Conclusion ----------- - -By understanding the structure and fields of a toolset, you can effectively extend Holmes's capabilities to suit your specific needs. The examples provided demonstrate how to: - -- Define toolsets with various features such as variables, parameters, and prerequisites. - -- Use environment variables and additional instructions to enhance tools. - -- Handle tools that require additional binaries by creating custom Docker images. - -- Apply processing instructions at both the toolset and tool levels. - -- Manage custom toolsets using ConfigMaps in Kubernetes environments. - -Feel free to experiment and create your own toolsets to unlock the full potential of Holmes in your environment. If you have any questions or need further assistance, refer to the Holmes documentation or reach out to the community for support. From d8d392157c682fd5292b75176c0942c694496da2 Mon Sep 17 00:00:00 2001 From: Dima Chievtaiev Date: Thu, 5 Dec 2024 03:11:03 +0100 Subject: [PATCH 04/16] Updated docs for toolsets integrations --- docs/configuration/ai-analysis.rst | 137 ++++++++++++++++++----------- 1 file changed, 87 insertions(+), 50 deletions(-) diff --git a/docs/configuration/ai-analysis.rst b/docs/configuration/ai-analysis.rst index cdc68ce6e..3bb0e620f 100644 --- a/docs/configuration/ai-analysis.rst +++ b/docs/configuration/ai-analysis.rst @@ -376,15 +376,10 @@ Toolset Fields * - ``variables`` - dictionary - A set of key-value pairs defining variables that can be used within tools and commands. Values can reference environment variables using the ``$VARIABLE_NAME`` syntax. - ```yaml - variables: - api_endpoint: "$API_ENDPOINT" - default_timeout: "60" - ``` - No * - ``prerequisites`` - list - - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands or environment variables. + - A list of conditions that must be met for the toolset to be enabled. Prerequisites can include commands or environment variables, or both. - No * - ``additional_instructions`` - string @@ -430,7 +425,7 @@ Toolset Fields - Additional shell commands or processing instructions applied to the output of this tool. - No -**Parameter Fields (Within ``parameters``)** +**Parameter Fields (Within `parameters`, not required)** .. list-table:: :widths: 20 10 60 10 @@ -454,54 +449,96 @@ Toolset Fields - No -### Prerequisites +Example 1: AWS S3 Management Toolset +------------------------------------ +This toolset enables Holmes to interact with fetch information from github repositories. -Prerequisites determine whether a toolset is enabled based on certain conditions: - -#### Command Prerequisite - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - **Key** - - **Type** - - **Description** - - **Required** - * - ``command`` - - string - - A shell command that must execute successfully (exit code 0) for the prerequisite to be satisfied. - - **Yes** - -**Example:** - -```yaml -prerequisites: - - command: "docker version" -``` - -#### Environment Variable Prerequisite +.. code-block:: yaml + holmes: + toolsets: + - name: "github_tools" + description: "Tools for managing GitHub repositories" + variables: + github_token: "$GITHUB_TOKEN" + prerequisites: + - env: + - "GITHUB_TOKEN" + - command: "curl --version" + tools: + - name: "list_user_repos" + description: "Lists all repositories for a GitHub user" + command: "curl -H 'Authorization: token {{ github_token }}' https://api.github.com/users/{{ username }}/repos" -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 + - name: "show_recent_commits" + description: "Shows the most recent commits for a repository" + command: "cd {{ repo_dir }} && git log -{{number_of_commits}} --oneline" - * - **Key** - - **Type** - - **Description** - - **Required** - * - ``env`` - - list of strings - - A list of environment variables that must be set. - - **Yes** + - name: "get_repo_details" + description: "Fetches details of a specific repository" + command: "curl -H 'Authorization: token {{ github_token }}' https://api.github.com/repos/{{ owner }}/{{ repo }}" + parameters: + owner: + type: "string" + description: "Owner of the repository." + required: true + repo: + type: "string" + description: "Name of the repository." + required: true + + - name: "get_recent_commits" + description: "Fetches the most recent commits for a repository" + command: "curl -H 'Authorization: token {{ github_token }}' https://api.github.com/repos/{{ owner }}/{{ repo }}/commits?per_page={{ limit }} " + +Example 2: Kubernetes Advanced Diagnostics Toolset +-------------------------------------------------- +This toolset provides diagnostics for Kubernetes clusters, helping developers identify and resolve issues. -**Example:** +.. code-block:: yaml + toolsets: + kubernetes/diagnostics: + description: "Advanced diagnostics and troubleshooting tools for Kubernetes clusters" + docs_url: "https://kubernetes.io/docs/home/" + icon_url: "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRPKA-U9m5BxYQDF1O7atMfj9EMMXEoGu4t0Q&s" + prerequisites: + - command: "kubectl version --client" + + tools: + - name: "kubectl_node_health" + description: "Check the health status of all nodes in the cluster." + command: "kubectl get nodes -o wide" + + - name: "kubectl_troubleshoot_pod" + description: "Fetch logs and describe output for a problematic pod." + command: > + echo "Logs:" && + kubectl logs {{ pod_name }} -n {{ namespace }} && + echo "\nDescription:" && + kubectl describe pod {{ pod_name }} -n {{ namespace }} + + - name: "kubectl_check_resource_quota" + description: "Fetch the resource quota for a specific namespace." + command: "kubectl get resourcequota -n {{ namespace }} -o yaml" + + - name: "kubectl_pod_disk_usage" + description: "Check the disk usage of a specific pod." + command: | + kubectl exec -n {{ namespace }} {{ pod_name }} -- du -sh / + + - name: "kubectl_find_evicted_pods" + description: "List all evicted pods in a specific namespace." + command: "kubectl get pods -n {{ namespace }} --field-selector=status.phase=Failed | grep Evicted" + + - name: "kubectl_drain_node" + description: "Drain a node safely by evicting all pods." + command: "kubectl drain {{ node_name }} --ignore-daemonsets --force --delete-emptydir-data" + + - name: "kubectl_pod_restart_count" + description: "Check the restart count for all pods in a namespace." + command: | + kubectl get pods -n {{ namespace }} -o jsonpath="{.items[*].status.containerStatuses[*].restartCount}" \ + | awk '{s+=$1} END {print s}' -```yaml -prerequisites: - - env: - - "API_ENDPOINT" -``` Once you have updated the ``generated_values.yaml`` file, apply the changes by running the Helm upgrade command: From 4269ad152d93fe5933989a7a2872301ac51735c3 Mon Sep 17 00:00:00 2001 From: Dima Chievtaiev Date: Fri, 6 Dec 2024 03:47:08 +0100 Subject: [PATCH 05/16] Updated ai-analysis.rst --- docs/configuration/ai-analysis.rst | 246 +++++++++++++++++++---------- 1 file changed, 163 insertions(+), 83 deletions(-) diff --git a/docs/configuration/ai-analysis.rst b/docs/configuration/ai-analysis.rst index 3bb0e620f..cc9addc94 100644 --- a/docs/configuration/ai-analysis.rst +++ b/docs/configuration/ai-analysis.rst @@ -299,12 +299,48 @@ Advanced - Customizing HolmesGPT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Adding Custom Tools to Holmes +Holmes Toolsets ------------------------------------- -Holmes allows you to define custom toolsets that enhance its functionality by enabling additional tools to run Kubernetes commands or other tasks. +Holmes allows you to define tools that enhance its functionality by enabling additional tools to run Kubernetes commands or other tasks. + +Default Toolsets in Holmes +-------------------------- +Holmes comes with a set of default toolsets that provide tools out-of-the-box. Some of these toolsets are enabled by default such as interacting with Kubernetes resources, or fetching logs and metrics. +Full list can be found `here `_ + +By default, any of the toolsets may be disabled. You can enable or disable them by modifying the ``generated_values.yaml`` file. + +.. code-block:: yaml + enableHolmesGPT: true + holmes: + additionalEnvVars: + - name: ROBUSTA_AI + value: "true" + toolsets: + kubernetes/logs: + enabled: false + +After making changes, apply them using Helm: + +.. code-block:: bash + + helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + + +Additionally, you can overwrite any of the fields in the default toolsets, such as updating the tools, prerequisites, or descriptions, to customize them for your specific needs. +For example: + +.. code-block:: yaml + enableHolmesGPT: true + holmes: + additionalEnvVars: + - name: ROBUSTA_AI + value: "true" + toolsets: + kubernetes/logs: + description: "My custom description for default toolset." -In this guide, we will show how to add a custom toolset to Holmes in your ``generated_values.yaml`` file. How to define a toolset? ------------------------------------- @@ -319,19 +355,22 @@ A toolset is defined in ``generated_values.yaml``. Each toolset has a unique nam description: "" docs_url: "" icon_url: "" + tags: + - installation_instructions: "" variables: : "" prerequisites: - command: "" + expected_output: "" - env: - - "" + - "" additional_instructions: "" tools: - name: "" description: "" - command: "" - script: "" + command: "" + script: "