Edit custom billing

2025-06-16 11:29:48 +00:00 · 2025-06-03 07:33:27 +03:00 · 2025-06-03 07:33:27 +03:00 · eff1f2f21c
commit eff1f2f21c
parent bbd26ef0c0
2 changed files with 201 additions and 86 deletions
--- a/docs/deploying_clearml/enterprise_deploy/custom_billing.md
+++ b/docs/deploying_clearml/enterprise_deploy/custom_billing.md
@ -1,13 +1,13 @@
 ---
-title: Custom Billing Events
+title: Custom Events
 ---

 :::important Enterprise Feature
-Sending custom billing events is available under the ClearML Enterprise plan.
+Sending custom events is available under the ClearML Enterprise plan.
 :::

 ClearML supports sending custom events to selected Kafka topics. Event sending is triggered by API calls and 
-is available only for the companies with the `custom_events` settings set.
+is available only to tenants with the `custom_events` feature configured.

 ## Enabling Custom Events in ClearML Server 

@ -15,61 +15,53 @@ is available only for the companies with the `custom_events` settings set.
 **Precondition**: Customer Kafka for custom events is installed and reachable from the `apiserver`.
 :::

-Set the following environment variables in the ClearML Enterprise helm chart under the `apiserver.extraEnv`:
+Modify the server's `clearml-values.override.yaml` file, then upgrade the chart:

-* Enable custom events:
+```yaml
+apiserver:
+  extraEnvs:
+    # Enable custom events.
+    - name: CLEARML__services__custom_events__enabled
+      value: "true"
+    # Folder where the ClearML Apiserver container can find the custom message templates.
+    - name: CLEARML__services__custom_events__template_folder
+      value: "/mnt/custom_events/templates"
+    # Kafka host configuration for custom events.
+    - name: CLEARML__hosts__kafka__custom_events__host
+      value: "[<KAFKA_HOST_ADDRESS>:<KAFKA_HOST_PORT>]"
+    # Kafka security parameters. Below is the example for SASL plaintext security.
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__security_protocol
+      value: "SASL_PLAINTEXT" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_mechanism
+      value: "SCRAM-SHA-512" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_username
+      value: "<USERNAME>" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_password
+      value: "<PASSWORD>"
+    # Kafka topics names for lifecycle and inventory messages.
+    - name: CLEARML__services__custom_events__channels__main__topics__service_instance_lifecycle
+      value: "lifecycle"
+    - name: CLEARML__services__custom_events__channels__main__topics__service_instance_inventory
+      value: "inventory"
+```

-   ``` 
-   - name: CLEARML__services__custom_events__enabled  
-     value: "true" 
-   ```
-* Mount custom message template files into `/mnt/custom_events/templates` folder in the `apiserver` container and point 
-  the `apiserver` into it:  
+### Configure Per-Tenant Custom Event Fields

-   ```
-   - name: CLEARML__services__custom_events__template_folder  
-     value: "/mnt/custom_events/templates"
-   ``` 
-* Configure the Kafka host for sending events:  
+For each tenant, configure the values required by the message templates using the following API call:

-   ```
-   - name: CLEARML__hosts__kafka__custom_events__host  
-     value: "[<KAFKA host address:port>]"
-   ```   
-   Configure Kafka security parameters. Below is the example for SASL plaintext security:  
+```bash
+curl $APISERVER_URL/system.update_company_custom_events_config -H "Content-Type: application/json" -u $APISERVER_KEY:$APISERVER_SECRET -d'{
+  "company": "<company_id>",
+  "fields": {
+    "service_instance_id": "<value>",
+    "service_instance_name": "<value>",
+    "service_instance_customer_tenant_name": "<value>",
+    "service_instance_customer_space_name": "<value>",
+    "service_instance_customer_space_id": "<value>",
+    "parameters_connection_points": ["<value1>", "<value2>"]
+}}'  
+```

-   ```
-   - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__security_protocol  
-     value: "SASL_PLAINTEXT"   
-   - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_mechanism  
-     value: "SCRAM-SHA-512"   
-   - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_username  
-     value: "<username>"   
-   - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_password  
-     value: "<password>"
-   ```
-* Define Kafka topics for lifecycle and inventory messages:  
-
-   ```
-   - name: CLEARML__services__custom_events__channels__main__topics__service_instance_lifecycle  
-     value: "lifecycle"  
-   - name: CLEARML__services__custom_events__channels__main__topics__service_instance_inventory  
-     value: "inventory"
-   ```
-* For the desired companies set up the custom events properties required by the event message templates: 
-
-   ```
-   curl $APISERVER_URL/system.update_company_custom_events_config -H "Content-Type: application/json" -u $APISERVER_KEY:$APISERVER_SECRET -d'{  
-     "company": "<company_id>",  
-     "fields": {  
-       "service_instance_id": "<value>",  
-       "service_instance_name": "<value>",  
-       "service_instance_customer_tenant_name": "<value>",  
-       "service_instance_customer_space_name": "<value>",  
-       "service_instance_customer_space_id": "<value>",
-       "parameters_connection_points": ["<value1>", "<value2>"]
-   }}'  
-   ```

 ## Sending Custom Events to the API Server

@ -77,46 +69,54 @@ Set the following environment variables in the ClearML Enterprise helm chart und
 **Precondition:** Dedicated custom-events Redis instance installed and reachable from all the custom events deployments.
 :::

-Environment lifecycle events are sent directly by the `apiserver`. Other event types are emitted by the following helm charts:
+Environment lifecycle events are sent directly by the ClearML `apiserver`. Other event types are emitted by the following 
+services (Helm charts in Kubernetes):

-* `clearml-pods-monitor-exporter` - Monitors running pods and sends container lifecycle events (should run one per cluster with a unique identifier, a UUID is required for the installation):  

-   ```
-   # -- Universal Unique string to identify Pods Monitor instances across worker clusters. It cannot be empty. 
-   # Uniqueness is required across different cluster installations to preserve the reported data status.
-   podsMonitorUUID: "<Unique ID>"
-   # Interval
-   checkIntervalSeconds: 60
-   ``` 
+* `clearml-pods-monitor-exporter` - Monitors running pods (tasks) and sends lifecycle events.  Should run one per cluster 
+  with a unique identifier (a UUID is required for the installation):  
+
 * `clearml-pods-inventory` - Periodically sends inventory events about running pods.

-   ```
-   # Cron schedule - https://crontab.guru/  
-   cronJob:  
-     schedule: "@daily" 
-   ``` 
-* `clearml-company-inventory` - Monitors Clearml companies and sends environment inventory events.  
+* `clearml-company-inventory` - Monitors ClearML companies and sends environment inventory events.  

-   ```
-   # Cron schedule - https://crontab.guru/
-   cronJob:  
-     schedule: "@daily"  
-   ```
+### Install custom-events

-For every script chart add the below configuration to enable redis access and connection to the `apiserver`:
+The `clearml-custom-events` is the Kubernetes "Custom Events" umbrella Helm chart for ClearML. It includes custom-events 
+components and dependencies (Redis) to kick-start the installation.

-```
-clearml:  
-  apiServerUrlReference: "<APISERVER_URL>"
-  apiServerKey: "<APISERVER_KEY>"
-  apiServerSecret: "<APISERVER_SECRET>"
-redisConnection:
-  host: "<REDIS_HOST>"  
-  port: <REDIS_PORT>  
-  password: "<REDIS_PWD>"
+#### Prepare Values
+
+Create a `clearml-custom-events-values.override.yaml` file with the following content (make sure to replace the `<PLACEHOLDERS>`):
+
+```yaml
+global:
+  imageCredentials:
+    password: "<CLEARML_DOCKERHUB_TOKEN>"
+  clearml:
+    apiServerUrlReference: "<CLEARML_APISERVER_URL>"
+    apiServerKey: "<ACCESSKEY>"
+    apiServerSecret: "<SECRETKEY>"
+
+clearml-pods-monitor-exporter:
+  checkIntervalSeconds: 60
+  # -- *REQUIRED* Universal Unique string to identify Pods Monitor instances across worker clusters. Cannot be empty.
+  # Uniqueness is required across different clusters installations to preserve the reported data status.
+  podsMonitorUUID: ""
+
+clearml-pods-inventory:
+  cronJob:
+    schedule: "@daily"
+
+clearml-company-inventory:
+  cronJob:
+    schedule: "@daily"
 ```

-See all other available options to customize the `custom-events` charts by running: 
-```
-helm show readme allegroai-enterprise/<CHART_NAME>
+#### Install
+
+Install the Custom Events umbrella chart:
+
+```bash
+helm install clearml-custom-events clearml-enterprise/clearml-custom-events -f clearml-custom-events-values.override.yaml
 ```
--- a/docs/deploying_clearml/enterprise_deploy/extra_configs/custom_events.md
+++ b/docs/deploying_clearml/enterprise_deploy/extra_configs/custom_events.md
@ -0,0 +1,115 @@
+---
+title: Custom Events
+---
+
+ClearML Enterprise supports sending custom events to selected Kafka topics. These events are triggered by API calls 
+and are only available to tenants with the `custom_events` feature configured.
+
+
+## Prerequisites
+
+* A Kafka instance must be deployed and reachable from the ClearML `apiserver`
+
+## Enabling Custom Events on the Server
+
+To enable custom evens, edit ClearML Server' `clearml-values.override.yaml` file adding the following:
+
+```yaml
+apiserver:
+  extraEnvs:
+    # Enable custom events.
+    - name: CLEARML__services__custom_events__enabled
+      value: "true"
+    # Folder where the ClearML Apiserver container can find the custom message templates.
+    - name: CLEARML__services__custom_events__template_folder
+      value: "/mnt/custom_events/templates"
+    # Kafka host configuration for custom events.
+    - name: CLEARML__hosts__kafka__custom_events__host
+      value: "[<KAFKA_HOST_ADDRESS>:<KAFKA_HOST_PORT>]"
+    # Kafka security parameters. Below is the example for SASL plaintext security.
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__security_protocol
+      value: "SASL_PLAINTEXT" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_mechanism
+      value: "SCRAM-SHA-512" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_username
+      value: "<USERNAME>" 
+    - name: CLEARML__SECURE__KAFKA__CUSTOM_EVENTS__sasl_plain_password
+      value: "<PASSWORD>"
+    # Kafka topics names for lifecycle and inventory messages.
+    - name: CLEARML__services__custom_events__channels__main__topics__service_instance_lifecycle
+      value: "lifecycle"
+    - name: CLEARML__services__custom_events__channels__main__topics__service_instance_inventory
+      value: "inventory"
+```
+
+After editing the configuration, upgrade the Helm chart to apply the changes.
+
+## Enabling Custom Events for Tenants
+
+
+Each tenant must be explicitly configured to use custom events. Use the following API call to set up the custom events 
+properties required by the event message templates:
+
+```bash
+curl $APISERVER_URL/system.update_company_custom_events_config -H "Content-Type: application/json" -u $APISERVER_KEY:$APISERVER_SECRET -d'{
+  "company": "<company_id>",
+  "fields": {
+    "service_instance_id": "<value>",
+    "service_instance_name": "<value>",
+    "service_instance_customer_tenant_name": "<value>",
+    "service_instance_customer_space_name": "<value>",
+    "service_instance_customer_space_id": "<value>",
+    "parameters_connection_points": ["<value1>", "<value2>"]
+}}'  
+```
+
+## Event Emitters
+
+ClearML services that send custom events include:
+
+* `apiserver` — Sends environment lifecycle events.
+* `clearml-pods-monitor-exporter` - Monitors running Pods (Tasks) and sends lifecycle events. Should run one per cluster 
+  with a unique identifier (an explicit UUID is required for the installation).
+* `clearml-pods-inventory` - Sends periodic inventory events about active Pods.
+* `clearml-company-inventory` - Monitors ClearML tenants and emits environment-level inventory events.
+
+## Install custom-events
+
+The `clearml-custom-events` Helm chart bundles all custom event services and their dependencies (e.g., Redis). It serves 
+as the umbrella chart for custom event functionality.
+
+### Prepare Values
+
+Create a `clearml-custom-events-values.override.yaml` file with the following content (make sure to replace `<PLACEHOLDERS>`):
+
+```yaml
+global:
+  imageCredentials:
+    password: "<CLEARML_DOCKERHUB_TOKEN>"
+  clearml:
+    apiServerUrlReference: "<CLEARML_APISERVER_URL>"
+    apiServerKey: "<ACCESSKEY>"
+    apiServerSecret: "<SECRETKEY>"
+
+clearml-pods-monitor-exporter:
+  checkIntervalSeconds: 60
+  # -- *REQUIRED* Universal Unique string to identify Pods Monitor instances across worker clusters. Cannot be empty.
+  # Uniqueness is required across different clusters installations to preserve the reported data status.
+  podsMonitorUUID: ""
+
+clearml-pods-inventory:
+  cronJob:
+    schedule: "@daily"
+
+clearml-company-inventory:
+  cronJob:
+    schedule: "@daily"
+```
+
+### Install
+
+Install the Custom Events chart:
+
+```bash
+helm install clearml-custom-events clearml-enterprise/clearml-custom-events -f clearml-custom-events-values.override.yaml
+```