diff --git a/content/documentation/admin/architecture/workers.ru.md b/content/documentation/admin/architecture/workers.ru.md index 194240a8..1df02532 100644 --- a/content/documentation/admin/architecture/workers.ru.md +++ b/content/documentation/admin/architecture/workers.ru.md @@ -29,7 +29,7 @@ weight: 20 ## Мониторинг -Для мониторинга работы воркеров и очереди задач доступен виджет [«Очередь задач»](../../widgets/types/#очередь-задач), который отображает: +Для мониторинга работы воркеров и очереди задач доступен виджет [«Очередь задач»](../widgets/generic/task-queue/), который отображает: - Размер очереди (общее количество задач). - Количество ожидающих задач. diff --git a/content/documentation/admin/datasets.ru.md b/content/documentation/admin/datasets.ru.md index 65f19f44..c602bf02 100644 --- a/content/documentation/admin/datasets.ru.md +++ b/content/documentation/admin/datasets.ru.md @@ -158,7 +158,7 @@ menuTitle: Наборы данных 1. Заполните учётные данные «Vault токен». 1. Подключите внешний сервис «Vault» к действиям, виджетам или источникам данных, которые обращаются к API Vault. -После этого запросы через внешний сервис будут использовать токен из учётных данных пользователя. Например, внешний сервис можно подключить к виджету [«Vault. Секреты»](../widgets/types/#vault-секреты) для просмотра секретов в KV v2. +После этого запросы через внешний сервис будут использовать токен из учётных данных пользователя. Например, внешний сервис можно подключить к виджету [«Vault. Секреты»](../widgets/generic/vault/) для просмотра секретов в KV v2. ### Deckhouse managed PostgreSQL diff --git a/content/documentation/admin/external-services.md b/content/documentation/admin/external-services.md new file mode 100644 index 00000000..001e5e02 --- /dev/null +++ b/content/documentation/admin/external-services.md @@ -0,0 +1,409 @@ +--- +title: External services +menuTitle: External services +description: Configure authentication for external infrastructure services used by platform objects. +--- + +External services configure authentication for external infrastructure systems such as GitLab, Kubernetes, and DefectDojo. + +Configure external services under "Administration" → "External services". + +## Configuration + +An external service has the following parameters: + +| Parameter | Description | +|-----------|-------------| +| "Name" | External service name displayed in the interface | +| "Identifier" | Unique human-readable identifier (slug) | +| "Owner" | User responsible for the external service | +| "Owner team" | Team that owns the external service | +| "URL" | Base URL for requests to the external service | +| "Credentials" | Available credentials, such as tokens, that can be included in requests | +| "Headers" | HTTP headers automatically added to requests | +| "Disable SSL verification" | Disables verification of the external service's SSL certificate, for example when using self-signed certificates. Instead, add the required certificates to [trusted certificates](../trusted-certificates/) | +| "System credential" | Credential used for scheduled jobs such as data source synchronization and status checks | + +## Using external services + +External services can be connected to the following platform objects: + +- actions; +- widgets; +- data sources; +- entity status checks. + +Connect a service on the "Authorization" tab in the settings of the corresponding object. + +Each object can explicitly override parameters configured for the external service. For example, if an external service contains an authentication token but an action requires different credentials, specify alternative values. Only the specified parameter is overridden; all other values come from the external service configuration. + +## Object-specific behavior + +### Actions + +- Multiple external services can be connected to one action. +- One service can be selected as the default. +- The "System credential" parameter is not used for actions. +- When running an action, you can select the external service to use. If you do not select a service, the default service is used. If no default is configured, the first external service in the list is used. + +### Widgets + +- Multiple external services can be connected to one widget. +- One service can be selected as the default. +- A future release will allow users to change the service while viewing a widget. +- The "System credential" parameter is not used for widgets. + +### Data sources + +- Only one external service can be connected. +- If the service has a system credential, it is used by default during synchronization. + +### Status checks + +- One external service can be assigned to a status check. +- If the service has a system credential, it is used for automatic checks. + +## Authorization headers for external services + +When configuring an external service, specify the HTTP headers required for authentication. The following sections list supported external services, authentication methods, and required headers. + +{{< alert level="info" >}} +The examples below show possible authentication methods for each service. Some services may support other methods. The platform supports any method that can be passed through HTTP headers. +{{< /alert >}} + +### CodeScoring + +Authentication type: API token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `` | + +Example: + +```sh +Authorization: +``` + +### ClickHouse + +Authentication type: Basic Authentication or the `X-ClickHouse-User` and `X-ClickHouse-Key` headers. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | +| `X-ClickHouse-User` | `` | +| `X-ClickHouse-Key` | `` | + +Basic Authentication example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +Example using ClickHouse headers: + +```sh +X-ClickHouse-User: +X-ClickHouse-Key: +``` + +### DefectDojo + +Authentication type: API v2 key token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Token ` | + +Example: + +```sh +Authorization: Token +``` + +### Bitbucket + +Authentication type: bearer token (personal access token). + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +### Docker Registry + +Authentication type: Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### GitLab + +Authentication type: personal access token or project access token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Private-Token` | `` | + +Example: + +```sh +Private-Token: +``` + +For instructions on creating a GitLab token, refer to the [GitLab authentication documentation](https://docs.gitlab.com/api/rest/authentication/). + +### GitHub + +Authentication type: personal access token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +Create the token in GitHub under "Settings" → "Developer settings" → "Personal access tokens". + +### Harbor + +Authentication type: Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### Jenkins + +Authentication type: Basic Authentication (username and password). + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string, where: + - `username` is the Jenkins username. + - `password` is the user's password. +1. Encode the string in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### Jira + +Authentication type: Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### Kaiten + +Authentication type: API token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +### Kubernetes + +Authentication type: bearer token (service account token or user token). + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +### Nexus + +Authentication type: Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### OpenSearch + +Authentication type: Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Basic ` | + +Example: + +1. Create the `username:password` string. +1. Encode it in Base64: `echo -n "username:password" | base64`. +1. Add the header: + +```sh +Authorization: Basic +``` + +### Prometheus + +Authentication type: bearer token or Basic Authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` or `Basic ` | + +Bearer token example: + +```sh +Authorization: Bearer +``` + +Basic Authentication example: + +```sh +Authorization: Basic +``` + +### SonarQube + +Authentication type: bearer token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +### Svacer + +Authentication type: bearer token. + +Headers: + +| Header | Value format | +|--------|--------------| +| `Authorization` | `Bearer ` | + +Example: + +```sh +Authorization: Bearer +``` + +### Vault + +Authentication type: token authentication. + +Headers: + +| Header | Value format | +|--------|--------------| +| `X-Vault-Token` | `` | + +Example: + +```sh +X-Vault-Token: +``` diff --git a/content/documentation/admin/healthchecks/_index.md b/content/documentation/admin/healthchecks/_index.md new file mode 100644 index 00000000..caa74369 --- /dev/null +++ b/content/documentation/admin/healthchecks/_index.md @@ -0,0 +1,4 @@ +--- +title: Health checks +weight: 60 +--- diff --git a/content/documentation/admin/healthchecks/overview.md b/content/documentation/admin/healthchecks/overview.md new file mode 100644 index 00000000..ce964178 --- /dev/null +++ b/content/documentation/admin/healthchecks/overview.md @@ -0,0 +1,38 @@ +--- +title: Overview +weight: 10 +--- + +For each resource, you can configure any number of rules that determine the status of its entities. The `Condition` field determines whether: + +- all rules must pass (`AllOf`); +- at least one rule must pass (`AnyOf`). + +{{< alert level="info" >}} +If at least one check returns an error, the entity status is set to `error`, regardless of the other check results and the condition. +{{< /alert >}} + +## Schedule + +The check scheduler runs every minute. For each rule, you can specify a five-field cron expression in the **Schedule** field. The rule then runs only at the specified times. If the field is empty, the rule runs every time the scheduler starts (once a minute). + +Example: `0 * * * *` runs the check at the beginning of every hour. + +If a rule is not scheduled to run at the current time, its latest check result is used to calculate the entity status. + +Logs for the latest checks are available under **Health checks** in the resource menu. + +## Entity statuses + +An entity can have one of four statuses: + +- `healthy` — rules are configured, and the entity parameters satisfy them; +- `unhealthy` — rules are configured, but the entity parameters do not satisfy them; +- `unknown` — no rules are configured, or the check cannot run; +- `error` — an error occurred while at least one rule was running. + +Click an entity status badge to open a table with rule results and additional information. The table shows only rules that have run at least once. + +{{< alert level="info" >}} +The `ENTITY_UPDATED` event is generated only when the entity status changes. +{{< /alert >}} diff --git a/content/documentation/admin/healthchecks/types.md b/content/documentation/admin/healthchecks/types.md new file mode 100644 index 00000000..53ac1003 --- /dev/null +++ b/content/documentation/admin/healthchecks/types.md @@ -0,0 +1,281 @@ +--- +title: Health check types +--- + +## Property + +A `Property` rule checks whether a specific entity parameter matches a template expression. + +The rule configuration contains one parameter: an expression written in [Go template syntax](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax). + +Expression examples: + +- `{{ eq .entity.properties.lifecycle "deployed" }}` — the `lifecycle` property must equal `"deployed"`; +- `{{ lt .entity.properties.vulnerabilities 10 }}` — the `vulnerabilities` property must be less than `10`. + +## Prometheus + +A Prometheus rule checks whether a specified metric meets a configured threshold. The configuration contains a PromQL query that must return a Scalar or a single-value Vector. + +Templating is supported. For example: + +```go +avg(ingress_nginx_detail_request_seconds_sum{location="/{{ .entity.slug }}"}) +``` + +In this example, the entity identifier replaces `{{ .entity.slug }}`. + +### Configuration parameters + +| Name | Description | Allowed values | +|-----------|------------------------------------------------------------|-----------------------------------------| +| Query | PromQL query for a Prometheus metric | | +| Operator | Comparison operator applied to the query result and threshold | Equal, NotEqual, LessThan, GreaterThan | +| Threshold | Threshold compared with the query result | | + +{{< alert level="info" >}} +Each entity check sends a separate request to Prometheus. Account for this when planning system load. +{{< /alert >}} + +### Authorization + +Authorization is configured in the [Prometheus external service](../external-services/#prometheus) section. + +## GitLab Pipeline + +A `GitlabPipeline` rule checks whether the latest GitLab pipeline for the selected Ref (branch or tag) has the configured status. + +All text fields support templating. For example, specify the following expression in the `Ref` field: + +```go +{{ .entity.properties.mainBranch }} +``` + +During the check, the value of the checked entity's `mainBranch` parameter replaces the expression. + +### Configuration parameters + +| Name | Description | Allowed values | +|------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| +| Project ID | GitLab project ID | | +| Ref | Branch or tag whose latest pipeline is checked | | +| Status | Pipeline status considered successful | created, waiting_for_resource, preparing, pending, running, success, failed, canceled, skipped, manual, scheduled | + +{{< alert level="info" >}} +Each entity check sends a separate request to GitLab. Account for this when planning system load. +{{< /alert >}} + +### Authorization + +Authorization is configured in the [GitLab external service](../external-services/#gitlab) section. + +## DefectDojo Findings + +A `DefectDojoFindings` rule checks the number of active vulnerabilities at each severity level for a specified DefectDojo product. + +The check uses the conditions in the `conditions` block. For each severity, you can specify the expected number of vulnerabilities and a comparison operator, for example, Critical < 5. + +All text fields support templating. For example, you can insert the product name from the entity parameters: + +```go +{{ .entity.properties.defectdojo_product_key }} +``` + +### Configuration parameters + +| Name | Description | Allowed values | +|--------------|---------------------------------------------------------------|----------------| +| Product name | Product identifier in DefectDojo | | +| Conditions | Conditions for comparing vulnerability counts by severity | | + +#### Conditions + +Each condition is an object in the following form: + +```yaml +conditions: + - severity: Critical + operator: "<" + value: "5" + - severity: High + operator: "<=" + value: "10" +``` + +| Field | Description | Allowed values | +|----------|-----------------------------------|-------------------------------------------| +| Severity | Severity level | Total, Critical, High, Medium, Low, Info | +| Operator | Comparison operator | ==, !=, <, <=, >, >= | +| Value | Target value for the comparison | | + +### Authorization + +Authorization is configured in the [DefectDojo external service](../external-services/#defectdojo) section. + +## CodeScoring Vulnerabilities + +A `CodeScoringVulnerabilities` rule checks the number of vulnerabilities at each severity level for a specified CodeScoring project. + +The check uses the conditions in the `conditions` block. For each severity, you can specify the expected number of vulnerabilities and a comparison operator. Both CVSS2 and CVSS3 metrics are supported. + +All text fields support templating. For example, you can insert the project ID from the entity parameters: + +```go +{{ .entity.properties.codescoring_project_id }} +``` + +### Configuration parameters + +| Name | Description | Allowed values | +|------------|---------------------------------------------------------------|----------------| +| Project ID | Project identifier in CodeScoring | | +| Conditions | Conditions for comparing vulnerability counts by severity | | + +#### Conditions + +Each condition is an object in the following format: + +```yaml +conditions: + - severity: CRITICAL + operator: "<" + value: "5" + cvss: "cvss3" + - severity: HIGH + operator: "<=" + value: "10" + cvss: "cvss2" +``` + +| Field | Description | Allowed values | +|----------|---------------------------------|-----------------------------------------------------------------------------------------| +| Severity | Severity level | CVSS3: CRITICAL, HIGH, MEDIUM, LOW, NONE, UNKNOWN. CVSS2: HIGH, MEDIUM, LOW, NONE | +| Operator | Comparison operator | ==, !=, <, <=, >, >= | +| Value | Target value for the comparison | | +| CVSS | CVSS metric version | cvss2, cvss3 | + +### Authorization + +Authorization is configured in the [CodeScoring external service](../external-services/#codescoring) section. + +## SonarQube Metrics + +A `SonarqubeMetrics` rule checks SonarQube project metrics against configured conditions. + +The check calls the SonarQube REST API endpoint `/api/measures/component` and compares current metric values with the expected values specified under **Conditions**. + +All text fields support templating. For example, you can insert the component key from the entity parameters: + +```go +{{ .entity.properties.sonarqube_project_key }} +``` + +### Configuration parameters + +| Name | Required | Description | Allowed values | +|-------------|----------|------------------------------------------|----------------| +| Project key | Yes | Project identifier in SonarQube | | +| Branch | No | Project branch from which metrics are read | | +| Conditions | Yes | Conditions for comparing SonarQube metrics | | + +#### Conditions + +Each condition is an object in the following form: + +```yaml +conditions: + - metric: coverage + operator: "<" + value: "5" + - metric: bugs + operator: "<=" + value: "10" +``` + +| Field | Description | Allowed values | +|----------|------------------------------------------------------|-----------------------------------------------------| +| Metric | SonarQube metric specified by its metric key | See the metric list in the official SonarQube documentation | +| Operator | Comparison operator | ==, !=, <, <=, >, >= | +| Value | Target value for the comparison | | + +See the [list of available metrics](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition) for the current SonarQube version. + +### Authorization + +Authorization is configured in the [SonarQube external service](../external-services/#sonarqube) section. + +## SonarQube Quality Gate + +A `SonarqubeQualityGate` rule checks the Quality Gate status of a SonarQube project. The check calls the SonarQube REST API endpoint `/api/qualitygates/project_status`. + +The rule returns `true` (passes) if the project Quality Gate has the `OK` status. It returns `false` (fails) for all other statuses: `WARN`, `ERROR`, or `NONE`. + +All text fields support templating. For example, you can insert the project key from the entity parameters: + +```go +{{ .entity.properties.sonarqube_project_key }} +``` + +### Configuration parameters + +| Name | Required | Description | Allowed values | +|-------------|----------|----------------------------------------------------------------------------------------------|----------------| +| Project key | Yes | Project identifier in SonarQube | | +| Branch | No | Project branch whose Quality Gate is checked. If omitted, the main branch is checked | | + +{{< alert level="info" >}} +Each entity check sends a separate request to SonarQube. Account for this when planning system load. +{{< /alert >}} + +### Authorization + +Authorization is configured in the [SonarQube external service](../external-services/#sonarqube) section. + +## URL + +A `URL` rule checks the availability of an HTTP or HTTPS endpoint. It sends a request with the configured parameters and evaluates the result against one or more Go template conditions. Conditions can check the response code, headers, response body, and entity parameters. + +All string fields (URL, request body, and headers) support templating with entity data (`.entity`), for example, `{{ .entity.slug }}`. + +### Configuration parameters + +| Name | Required | Description | Examples | +|---------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | Yes | Full request URL | `https://example.com` | +| Method | No | HTTP request method | GET, POST | +| Query | No | Query value added to the outgoing request | | +| Save details | No | If enabled, the check table stores and displays the response body and status (code and headers). If disabled, it shows only the condition, result, and error | | +| Conditions | No | Go template expressions used to evaluate the response | See below | +| Multiple conditions | No | `AllOf` requires all conditions to pass; `AnyOf` requires at least one | AllOf, AnyOf | +| Request body | No | Request body in YAML format. After template substitution, it is converted to JSON and sent | | + +If no conditions are specified, the response code is checked against `200` by default: `{{ eq .status.code 200 }}`. + +### Conditions + +Conditions can use: + +- `.status` — response data: `.status.code` (HTTP code), `.status.status` (status string), `.status.headers` (headers), and `.status.contentLength`. `.status.headers` is a map of header names to value arrays, with names in lowercase. Example: access the first header value with `{{ index (index .status.headers "content-type") 0 }}`; iterate over values with `{{ range index .status.headers "set-cookie" }}...{{ end }}`. +- `.response` — response body with converted types (for a JSON response). +- `.entity` — parameters of the checked entity. + +Condition examples: + +```go +{{ eq .status.code 200 }} +{{ eq (index (index .status.headers "content-type") 0) "application/json" }} +{{ gt .status.contentLength 0 }} +``` + +### Request body example + +Specify the **Request body** field in YAML format. For example: + +```yaml +id: "{{ .entity.id }}" +name: "{{ .entity.name }}" +``` + +### Result evaluation + +The check passes when all conditions pass in `AllOf` mode or at least one passes in `AnyOf` mode. If evaluating a condition returns an error—for example, the response is not JSON but the condition uses `.response`—the check returns an error. diff --git a/content/documentation/admin/security/audit-logs.md b/content/documentation/admin/security/audit-logs.md new file mode 100644 index 00000000..0c8d62e7 --- /dev/null +++ b/content/documentation/admin/security/audit-logs.md @@ -0,0 +1,65 @@ +--- +title: Audit logs +description: Audit log contents, storage, filtering, retention, and CSV export in DDP. +weight: 40 +--- + +Audit logs record all operations that users perform through the Deckhouse Development Platform (DDP) API. The logs are stored in a PostgreSQL database and support auditing of user activity. + +## Components + +The following components create and store audit logs: + +- DDP Backend creates audit log entries. +- PostgreSQL stores the data. + +## Audit log contents + +Each HTTP request except `GET` creates an audit log entry with the following fields: + +- "Email" — email address of the user who made the request. +- "IP" — client IP address. +- "Request body" — HTTP request body. +- "Path" — requested API path. +- "Method" — request HTTP method (`POST`, `PUT`, `DELETE`, or `PATCH`). +- "Status" — response HTTP status code. +- "Date" — request date. + +## How it works + +DDP Backend automatically creates audit logs through request-processing middleware for all HTTP requests except `GET`. + +To reduce database load, entries are buffered with the following settings: + +- Batch size — 40 entries. +- Write interval — 20 seconds. +- In-memory buffer size — 4 entries. + +## Storage + +Audit logs are stored in the PostgreSQL `audit_logs` table. The table is partitioned by day based on the `timestamp` field. + +The table structure is maintained automatically. Every day at `00:00` server time, the system prepares space for logs for the next 7 days. + +Logs are retained indefinitely and old entries are not deleted automatically. To control retention, configure external tools, such as cron jobs or database cleanup scripts, to delete old log partitions automatically. + +## Viewing logs + +Audit logs are available in the web interface under "Administration" → "Audit". You can filter logs by the following fields: + +- Period, including start and end date and time. +- User email. +- IP address. +- Path. +- Request method. +- Response status. + +## Exporting to CSV + +The audit log page provides a "Download .csv" button. Export is available only with permission to read audit logs. + +The file includes all entries that match the current filters and sorting. Export does not run if more than 100,000 events match. + +## Configuration + +Audit logging is enabled by default and requires no additional configuration. To control log retention, configure automatic deletion of old database partitions. diff --git a/content/documentation/admin/security/encryption-key-rotation.md b/content/documentation/admin/security/encryption-key-rotation.md new file mode 100644 index 00000000..c3d6c5d2 --- /dev/null +++ b/content/documentation/admin/security/encryption-key-rotation.md @@ -0,0 +1,59 @@ +--- +title: Encryption key rotation +description: Safely re-encrypt stored credentials and replace the DDP Backend encryption key. +weight: 35 +--- + +Deckhouse Development Platform (DDP) lets you securely replace the encryption key (`security.secretKey`) without losing credentials or other encrypted values. The operation runs from the web interface and re-encrypts all data stored with the current key. + +## Reasons to rotate the key + +Rotate the encryption key when you need to replace `security.secretKey` in the DDP Backend configuration, for example, to comply with a security policy or after the key has been compromised. + +{{< alert level="warning" >}} +Do not change `security.secretKey` in the configuration or restart the backend before re-encryption finishes in the web interface. Otherwise, the stored values will become unavailable. +{{< /alert >}} + +## Access permissions + +Key rotation requires the global `rotate:encryption-key` permission. + +## Data that is re-encrypted + +The operation affects the following data categories: + +- "User credentials" — values in PostgreSQL for credential types that use the "Database" storage. +- "AI provider credentials" — personal credentials for AI integrations. +- "Temporary action responses" — encrypted temporary responses in action execution records. +- "Vault secrets" — credential values stored in HashiCorp Vault or Deckhouse Stronghold. +- "Vault configuration" — the AppRole Role ID and AppRole Secret ID in the Vault integration settings. + +## Procedure + +1. Go to "Administration" → "Credentials". +1. Click "Rotate encryption key". +1. In the "Old encryption key" field, enter the current key from the DDP configuration (`security.secretKey`). +1. In the "New encryption key" field, enter the new key. It must meet the same requirements as during initial setup: + - The key must be 16, 24, or 32 bytes long. + - The key may contain only printable ASCII characters. + - The key must not consist of a single repeated character. +1. Click "Re-encrypt". +1. Wait for the operation to finish and check the results table. For each category, the table shows the number of successfully re-encrypted, skipped, and failed records. +1. Set `security.secretKey` in the DDP Backend configuration to the new key. +1. Restart DDP Backend. + +{{< alert level="info" >}} +After re-encryption, credentials remain unavailable until you specify the new key in the backend configuration and restart the service. +{{< /alert >}} + +## Operation results + +The results table shows three counters for each data category: + +- "Successful" — records re-encrypted with the new key. +- "Skipped" — records already accessible with the new key, for example, records re-encrypted earlier. +- "Failed" — records that could not be re-encrypted, usually because the old key is incorrect or the data is corrupted. + +The "Total" row shows totals across all categories. + +If the "Failed" column contains non-zero values, do not update the backend configuration until you resolve the errors. Verify the old key and repeat the operation. diff --git a/content/documentation/admin/security/encryption-key-rotation.ru.md b/content/documentation/admin/security/encryption-key-rotation.ru.md index a686c7c7..37558e5a 100644 --- a/content/documentation/admin/security/encryption-key-rotation.ru.md +++ b/content/documentation/admin/security/encryption-key-rotation.ru.md @@ -3,7 +3,7 @@ title: Ротация ключа шифрования weight: 35 --- -Deckhouse Data Platform (DDP) позволяет безопасно сменить ключ шифрования (`security.secretKey`) без потери учётных данных и других зашифрованных значений. Операция выполняется из веб-интерфейса и перешифровывает все данные, которые хранятся с использованием текущего ключа. +Deckhouse Development Platform (DDP) позволяет безопасно сменить ключ шифрования (`security.secretKey`) без потери учётных данных и других зашифрованных значений. Операция выполняется из веб-интерфейса и перешифровывает все данные, которые хранятся с использованием текущего ключа. ## Основания для ротации ключа diff --git a/content/documentation/admin/security/impersonation.md b/content/documentation/admin/security/impersonation.md new file mode 100644 index 00000000..1e5c7ea1 --- /dev/null +++ b/content/documentation/admin/security/impersonation.md @@ -0,0 +1,51 @@ +--- +title: Impersonation +description: Start, end, restrict, and audit temporary sessions performed as another DDP user. +weight: 25 +--- + +DDP supports impersonation: a user with the global `impersonate:users` permission can temporarily use the web interface as another user. + +{{< alert level="info" >}} +Impersonation is available only for browser sign-in through a Dex session. API tokens are not supported. +{{< /alert >}} + +## Starting and ending impersonation + +1. Go to "Administration" → "Users". +1. In the target user's row, click "Sign in as this user". +1. The platform switches the session to the selected user. A "Signed in as: …" banner at the bottom of the screen shows the time remaining before the session ends automatically. +1. To end impersonation early, click "End session" in the banner. + +The "Sign in as this user" button is unavailable for blocked users and your own account. + +## Security restrictions + +Impersonation does not start in the following cases: + +- The selected user is blocked. +- The selected user is the user who is already signed in. +- The selected user is a super administrator, but the operator is not a super administrator. +- The selected user already has the global `impersonate:users` permission, unless the operator is a super administrator. + +## Session lifetime + +An impersonation session has a limited lifetime: + +- The session lasts 30 minutes. +- The session ends automatically when it expires. +- The web interface displays a countdown until automatic termination. + +If the user does not end impersonation manually, the platform ends it automatically when the session expires. + +## Audit + +For HTTP requests included in audit logs (`POST`, `PUT`, `DELETE`, and `PATCH`), the "Email" field identifies the operator and target user in the format `operator@example.com [as target@example.com]`. + +This format lets you determine the following from an audit log entry: + +- Who initiated the request. +- Whose identity the session used to perform the operation. +- The HTTP method, path, and response status. + +`GET` requests are not recorded in audit logs. For details, see [Audit logs](../audit-logs/). diff --git a/content/documentation/admin/security/rbac.md b/content/documentation/admin/security/rbac.md new file mode 100644 index 00000000..149e2dc5 --- /dev/null +++ b/content/documentation/admin/security/rbac.md @@ -0,0 +1,505 @@ +--- +title: Role model +description: Roles, permissions, bindings, ownership, and access control in Deckhouse Development Platform. +weight: 20 +--- + +The Deckhouse Development Platform (DDP) role model defines which actions users can perform in the platform and which objects they can access. The model controls access to the API and web interface at both the platform and individual object levels. + +The role model is implemented in DDP Backend and uses a PostgreSQL database to store roles, permissions, and their relationships. + +## Role model components + +The role model consists of the following components: + +* A permission corresponds to a specific action in DDP. +* A role combines a set of permissions. +* A role binding associates a role with users or teams. + +Each DDP object has its own permissions, roles, and role bindings. Global roles, permissions, and role bindings allow operations at the platform level. + +{{< alert level="info" >}} +Without the required permissions, a user cannot perform operations in the platform. The system checks permissions for every operation. +{{< /alert >}} + +## Object types and permissions + +### Global permissions + +Global permissions apply across the platform and grant access to all objects of a specific type. + +Resources: +- `create:resources` — create resources. +- `read:resources` — view resources. +- `update:resources` — edit resources. +- `update:resources-order` — change the order and grouping of resources in the catalog. +- `delete:resources` — delete resources. + +Entities: +- `create:entities` — create entities. +- `read:entities` — view entities. +- `update:entities` — edit entities. +- `delete:entities` — delete entities. + +Data sources: +- `create:datasources` — create data sources. +- `read:datasources` — view data sources. +- `update:datasources` — edit data sources. +- `sync:datasources` — synchronize data sources. +- `delete:datasources` — delete data sources. + +Actions: +- `create:actions` — create actions. +- `read:actions` — view actions. +- `update:actions` — edit actions. +- `run:actions` — run actions. +- `delete:actions` — delete actions. + +Automations: +- `create:automations` — create automations. +- `read:automations` — view automations. +- `update:automations` — edit automations. +- `delete:automations` — delete automations. + +Workflows: +- `create:workflows` — create workflows. +- `read:workflows` — view workflows. +- `update:workflows` — edit workflows. +- `delete:workflows` — delete workflows. + +Webhooks: +- `create:webhooks` — create webhooks. +- `read:webhooks` — view webhooks. +- `update:webhooks` — edit webhooks. +- `delete:webhooks` — delete webhooks. + +Widgets: +- `create:widgets` — create widgets. +- `read:widgets` — view widgets. +- `update:widgets` — edit widgets. +- `run:widget-actions` — run widget actions. +- `delete:widgets` — delete widgets. + +Dashboards: +- `create:dashboards` — create dashboards. +- `read:dashboards` — view dashboards. +- `update:dashboards` — edit dashboards. +- `delete:dashboards` — delete dashboards. + +MCP: +- `read:mcp-servers` — view connected MCP servers. +- `edit:mcp-servers` — connect, edit, synchronize the catalog of, and delete MCP servers. +- `read:mcp-collections` — view MCP collections. +- `edit:mcp-collections` — create, edit, and delete MCP collections. +- `read:mcp-tools` — view custom MCP tools. +- `edit:mcp-tools` — create, edit, and delete custom MCP tools. + +External services: +- `create:external-services` — create external services. +- `read:external-services` — view external services. +- `update:external-services` — edit external services. +- `delete:external-services` — delete external services. + +Trusted certificates: +- `create:trusted-certificates` — add trusted certificates. +- `read:trusted-certificates` — view trusted certificates. +- `update:trusted-certificates` — edit trusted certificates. +- `delete:trusted-certificates` — delete trusted certificates. + +Processes: +- `create:processes` — create processes. +- `read:processes` — view processes. +- `update:processes` — edit processes. +- `delete:processes` — delete processes. + +Teams: +- `create:teams` — create teams. +- `update:teams` — edit teams. +- `delete:teams` — delete teams. +- `update:team-variables` — edit team variables. +- `edit:team-filter-rules` — configure group filtering rules during synchronization from Dex. + +Icons: +- `create:icons` — create icons. +- `delete:icons` — delete icons. + +User credential types: +- `edit:user-access-credentials-types` — create, edit, and delete credential types; configure the Vault integration, including viewing and changing the configuration and testing the connection. +- `rotate:encryption-key` — rotate the encryption key. For details, see [Encryption key rotation](../encryption-key-rotation/). + +Users: +- `edit:users` — create, block, unblock, and delete users. +- `impersonate:users` — start and end user impersonation. For details, see [Impersonation](../impersonation/). + +{{< alert level="info" >}} +The `update:team-variables` permission allows users to edit variables only for teams of which they are members. Even a super administrator cannot change variables for a team to which they do not belong. +{{< /alert >}} + +#### Page view permissions + +Permissions with the `view:` prefix control access to sections of the platform interface: + +- `view:admin-page` — access the "Administration" section. +- `view:self-service-page` — access the "Self-Service" section. +- `view:ai-page` — access the "AI" section. + +{{< alert level="info" >}} +Without the corresponding `view:` permission, a user cannot see a section in the navigation menu even if they have other permissions for objects in that section. +{{< /alert >}} + +### Object-level permissions + +Each object type has permissions that apply only to a specific object. + +For resources: +- `read:resource` — view a specific resource. +- `update:resource` — edit a specific resource. +- `delete:resource` — delete a specific resource. +- `create:entities` — create resource entities. +- `read:entities` — view resource entities. +- `update:entities` — edit resource entities. +- `delete:entities` — delete resource entities. +- `run:actions` — run actions for resource entities. +- `control:processes` — control processes for resource entities. +- `edit:role-bindings` — edit role bindings for the resource. + +For entities: +- `read:entity` — view a specific entity. +- `update:entity` — edit a specific entity. +- `delete:entity` — delete a specific entity. +- `run:actions` — run actions for the entity. +- `control:processes` — control processes for the entity. +- `edit:role-bindings` — edit role bindings for the entity. + +#### MCP collections + +For MCP collections: +- `use:mcp-collections` — call collection tools in the AI assistant and through the platform MCP server. +- `edit:role-bindings` — edit role bindings for the collection. + +For other objects, including actions, automations, processes, webhooks, widgets, dashboards, and external services: +- `read:[object-type]` — view the object. +- `update:[object-type]` — edit the object. +- `delete:[object-type]` — delete the object. +- `edit:role-bindings` — edit role bindings for the object. + +## Permission check hierarchy + +The role model is hierarchical. When processing a request, DDP Backend checks access rights in a specific order. For example, to determine whether a user can edit a specific entity, the backend performs the following checks: + +### 1. Super administrator + +- Check whether the user is a super administrator. If so, stop further checks. + +### 2. Global roles + +- Read the user's group membership from the JWT. +- Find global roles for the user and their groups through global role bindings. +- Check permissions in the global roles. If any global role bound to the user or their team contains `update:entities`, the user can edit any entity in DDP, and no further checks are performed. + +### 3. Resource roles + +- Find resource roles for the user and their groups through role bindings for the specific resource. +- Check permissions in the resource roles. If any resource role bound to the user or their team contains `update:entities`, the user can edit any entity of that resource, and no further checks are performed. + +### 4. Entity roles + +- Find entity roles for the user and their groups through role bindings for the specific entity. +- Check permissions in the entity roles. If any entity role bound to the user or their team contains `update:entity`, the user can edit that entity. + +### 5. Object ownership when ownerIsAdmin is enabled + +- Check whether the user owns the object. +- Check whether the user belongs to the team that owns the object. +- If the user owns the object or belongs to its owner team, grant the user all administrator permissions for the object. + +If the required permission is not found at any level, the action is denied. + +{{< alert level="info" >}} +Ownership is checked only when `ownerIsAdmin` is enabled in the platform configuration. For details, see [Object ownership](#object-ownership). +{{< /alert >}} + +## Object ownership + +Object ownership allows users and teams to own specific system objects and automatically receive all administrator permissions for those objects. + +An object owner is a user or team assigned as the owner of a specific object. + +### Effect of ownership on access rights + +When `ownerIsAdmin` is enabled, an object owner receives all administrator permissions for that object. The owner can: + +- View, edit, and delete the object. +- Manage role bindings and access for other users. +- Perform any action available to an object administrator. + +### OwnerAsAdmin option + +The `ownerIsAdmin` option controls access rights for object owners. + +- "Enabled (`true`)" — object owners receive full administrator permissions for their objects. +- "Disabled (`false`)" — object owners receive no automatic permissions; roles alone control access. + +{{< alert level="info" >}} +A platform administrator must configure `ownerIsAdmin` in the configuration file. The option is disabled by default. +{{< /alert >}} + +### Automatic owner assignment on creation + +When a user creates an object, such as an action, data source, widget, or resource, the platform automatically assigns the current user as its owner. The owner can be reassigned, or the object can be created without an owner. + +### Ownership examples + +#### Resource ownership + +When a user creates a resource, they automatically become its owner. If `ownerIsAdmin` is enabled, the user receives all administrator permissions for that resource, including: +- Managing resource entities. +- Configuring role bindings. +- Editing and deleting the resource. + +#### Entity ownership + +When a user creates an entity, they become its owner and can: +- View and edit the entity. +- Manage role bindings for the entity. +- Delete the entity. + +#### Owner team + +If a team owns an object and `ownerIsAdmin` is enabled, all team members receive administrator permissions for the object. + +## Default role + +The platform allows one global role to be set as the default. Its permissions apply to all authenticated users. Configure the default role under "Administration" → "Access control" by using the switch in the "Roles" table. + +Only a global role can be set as the default. + +## Teams + +Teams group users and allow roles to be assigned collectively. A user can belong to multiple teams, and their permissions are combined from all teams of which they are a member. + +{{< alert level="info" >}} +Teams and team membership are synchronized from the external authentication system, Dex. Teams cannot be managed through the DDP interface. +{{< /alert >}} + +## Configuring roles and managing access + +### Creating a role + +1. Go to "Administration" → "Access control". +1. Select the "Roles" tab. +1. Click "Create role". +1. Complete the form: + - Name — unique role name. + - Description — role purpose. + - Object type — select the scope of the role: + - `Global` — global permissions. + - `Resources` — resource-level permissions. + - `Entities` — entity-level permissions. + - `Actions` — action-level permissions. + - Other object types. + - Permissions — select the required permissions. +1. Click "Save". + +### Assigning a role to users + +1. Go to "Administration" → "Access control". +1. Select the "Role bindings" tab. +1. Click "Create role binding". +1. Complete the form: + - Name — role binding name. + - Description — role binding purpose. + - Role — select the role. + - Object — select a specific object if the role is not global. + - Users — add the users to whom the role is assigned. + - Teams — add the teams to which the role is assigned. +1. Click "Save". + +### Configuring the default role + +1. Go to "Administration" → "Access control". +1. Select the "Roles" tab. +1. Find the global role to set as the default. +1. Enable the "Default role" switch. +1. Confirm the action. + +{{< alert level="info" >}} +Only a global role can be the default. +{{< /alert >}} + +### Editing roles + +1. Go to "Administration" → "Access control". +1. Select the "Roles" tab. +1. Find the required role and click "Edit". +1. Make the required changes: + - Change the name or description. + - Add or remove permissions. +1. Click "Save". + +### Editing role bindings + +1. Go to "Administration" → "Access control". +1. Select the "Role bindings" tab. +1. Find the required role binding and click "Edit". +1. Make the required changes: + - Change the name or description. + - Add or remove users. + - Add or remove teams. +1. Click "Save". + +### Deleting roles and bindings + +1. Go to the corresponding section. +1. Find the required role or binding. +1. Click "Delete". +1. Confirm the deletion. + +{{< alert level="info" >}} +Deleting a role also deletes all associated role bindings. +{{< /alert >}} + +### Viewing permissions for a user or team + +#### For a user + +1. Go to "Administration" → "Users". +1. Open the target user's profile. +1. Select the "Permissions" tab. +1. Review: + - Global permissions. + - Object-level permissions. + - Roles assigned to the user. + - Teams of which the user is a member. + +#### For a team + +1. Go to "Administration" → "Teams". +1. Open the target team's profile. +1. Select the "Permissions" tab. +1. Review: + - The team's global permissions. + - Object-level permissions. + - Roles assigned to the team. + - Users who belong to the team. + +{{< alert level="info" >}} +Team membership is synchronized from the external authentication system, Dex. +{{< /alert >}} + +### Role presets + +The platform provides role presets for common access scenarios. + +#### Global presets + +##### "Admin" preset + +- Type: `Global`. +- Permissions: all global permissions. +- Purpose: system administrators. + +##### "Viewer" preset + +- Type: `Global`. +- Permissions: + - `read:actions`, `read:automations`, `read:dashboards`. + - `read:datasources`, `read:entities`, `read:external-services`. + - `read:processes`, `read:resource-relations`, `read:resources`. + - `read:seeds`, `read:system-alerts`, `read:trusted-certificates`, `read:webhooks`. + - `read:widgets`, `read:workflows`. + - `read:audit-logs`, `view:admin-page`, `view:self-service-page`. +- Purpose: users with read-only access. + +##### "Developer" preset + +- Type: `Global`. +- Permissions: + - `read:actions`, `read:dashboards`, `read:external-services`. + - `read:processes`, `read:widgets`, `read:workflows`. + - `run:actions`, `run:widget-actions`, `control:processes`. + - `update:team-variables`. +- Purpose: developers who need to view information and run actions but do not need to create, edit, or delete objects. Developers see only entities to which role bindings at the resource or entity level grant them access. + +##### "Platform engineer" preset + +- Type: `Global`. +- Permissions: full access to the catalog and the "Self-Service" page. +- Purpose: engineers who configure the platform, including processes, data sources, and dashboards. + +#### Process presets + +##### "Process admin" preset + +- Type: `Processes`. +- Permissions: `delete:process`, `edit:role-bindings`, `read:process`, `update:process`. +- Purpose: process administrators. + +##### "Process viewer" preset + +- Type: `Processes`. +- Permissions: `read:process`. +- Purpose: users with permission to view processes. + +#### Resource presets + +##### "Resource admin" preset + +- Type: `Resources`. +- Permissions: all resource permissions. +- Purpose: administrators of specific resources. + +#### Using presets + +1. Go to "Administration" → "Access control". +1. Select the "Roles" tab. +1. Click "Create role". +1. Select an object type. +1. Under "Presets", click the required preset. +1. Configure the role: + - Change the name and description if necessary. + - Add or remove permissions. +1. Click "Save". + +### Role configuration examples + +#### "System administrator" role + +- Type: `Global`. +- Permissions: all global permissions. Use the "Admin" preset. +- Assignment: super administrators. + +#### "Resource administrator" role + +- Type: `Resources`. +- Permissions: all resource permissions. Use the "Resource admin" preset. +- Assignment: a specific resource and the "Administrators" team. + +#### "Process operator" role + +- Type: `Processes`. +- Permissions: `delete:process`, `edit:role-bindings`, `read:process`, `update:process`. Use the "Process admin" preset. +- Assignment: the "Process operators" team. + +## Best practices + +### Creating roles + +1. Determine the access level: decide whether you need a global role or a role for a specific object. +1. Select the required permissions according to the principle of least privilege. +1. Create the role in the corresponding administration section. +1. Assign the role to users or teams through role bindings. + +### Managing access + +1. Use teams to manage access for groups. +1. Use default roles to grant basic permissions to all users. +1. Follow the hierarchy: use global roles for broad access and object roles for specific access. +1. Regularly review assigned roles and bindings. + +### Security + +1. Apply the principle of least privilege: grant only the required permissions. +1. Audit regularly: review assigned roles and their use. +1. Use teams instead of individual assignments to simplify management. +1. Document roles with descriptions that explain their purpose. diff --git a/content/documentation/admin/trusted-certificates.md b/content/documentation/admin/trusted-certificates.md new file mode 100644 index 00000000..b848eb27 --- /dev/null +++ b/content/documentation/admin/trusted-certificates.md @@ -0,0 +1,63 @@ +--- +title: Trusted certificates +menuTitle: Trusted certificates +description: Add certificates for secure HTTPS connections from Deckhouse Development Platform to external services. +--- + +Trusted certificates allow you to upload root and intermediate certificate authority (CA) certificates or server certificates to Deckhouse Development Platform (DDP). The platform uses them for TLS/SSL verification when connecting to external services over HTTPS, for example when accessing external service APIs from data sources and widgets. + +This mechanism provides secure connections to services that use self-signed or corporate certificates without disabling SSL verification. + +{{< alert level="info" >}} +Add certificates for Dex, PostgreSQL, and Redis through the module configuration. DDP connects to these internal services before enabling the trusted certificate mechanism. +{{< /alert >}} + +Configure trusted certificates under "Administration" → "Trusted certificates". + +## Configuration + +Specify the following parameters when adding a trusted certificate: + +| Parameter | Description | +|-----------|-------------| +| "Name" | Certificate name displayed in the interface, for example "Corporate CA" | +| "Certificate (PEM)" | Certificate content in PEM format. Required when creating the certificate | + +Specify the certificate in PEM format: + +```sh +-----BEGIN CERTIFICATE----- +MIIDXTCCAkWgAwIBAgIJAKL... +... +-----END CERTIFICATE----- +``` + +After you save the certificate, its card displays data extracted from the PEM content, including the subject, issuer, validity period, and alternative names. + +When editing a certificate, the "Certificate (PEM)" field is hidden. For security, the API does not return the saved value. To update a certificate, create a new record and delete the old one if necessary. + +## Usage + +Uploaded trusted certificates are automatically added to the root certificate pool used by DDP Backend for outgoing HTTPS requests. This pool is used for: + +- requests to external services from actions, widgets, data sources, and status checks; +- requests to infrastructure system APIs such as GitLab, Kubernetes, Vault, and Prometheus. + +If an external service uses a certificate issued by your own or a corporate CA, add the corresponding root or intermediate certificate under "Trusted certificates". The platform then trusts the connection without disabling SSL verification. + +{{< alert level="info" >}} +Instead of disabling SSL verification for an external service with the "Disable SSL verification" option, add the required certificates as trusted. This preserves authentication and connection security. +{{< /alert >}} + +Changes to the trusted certificate list, including additions, updates, and deletions, apply to new outgoing connections without restarting DDP. + +## Access permissions + +Trusted certificate management is controlled by the following global permissions: + +- `read:trusted-certificates` — view the certificate list and details; +- `create:trusted-certificates` — add certificates; +- `update:trusted-certificates` — edit the name of an existing certificate; +- `delete:trusted-certificates` — delete certificates. + +For details about the role model, refer to the [RBAC documentation](../security/rbac/). diff --git a/content/documentation/admin/widgets/_index.md b/content/documentation/admin/widgets/_index.md new file mode 100644 index 00000000..c0154ca8 --- /dev/null +++ b/content/documentation/admin/widgets/_index.md @@ -0,0 +1,5 @@ +--- +title: Widgets +description: Data visualization components for dashboards and entity pages +weight: 50 +--- diff --git a/content/documentation/admin/widgets/_index.ru.md b/content/documentation/admin/widgets/_index.ru.md index 8d4d4c85..81ea0529 100644 --- a/content/documentation/admin/widgets/_index.ru.md +++ b/content/documentation/admin/widgets/_index.ru.md @@ -1,4 +1,5 @@ --- title: Виджеты +description: Компоненты визуализации данных для дашбордов и страниц сущностей weight: 50 --- diff --git a/content/documentation/admin/widgets/ai/_index.md b/content/documentation/admin/widgets/ai/_index.md new file mode 100644 index 00000000..a3dc2f67 --- /dev/null +++ b/content/documentation/admin/widgets/ai/_index.md @@ -0,0 +1,5 @@ +--- +title: AI +description: Widgets powered by connected artificial intelligence providers +weight: 20 +--- diff --git a/content/documentation/admin/widgets/ai/_index.ru.md b/content/documentation/admin/widgets/ai/_index.ru.md new file mode 100644 index 00000000..a097d479 --- /dev/null +++ b/content/documentation/admin/widgets/ai/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: AI +description: Виджеты на базе подключённых провайдеров искусственного интеллекта +weight: 20 +--- diff --git a/content/documentation/admin/widgets/ai/chat.md b/content/documentation/admin/widgets/ai/chat.md new file mode 100644 index 00000000..98fccba9 --- /dev/null +++ b/content/documentation/admin/widgets/ai/chat.md @@ -0,0 +1,41 @@ +--- +title: AI chat +description: Configuration and usage of the language-model chat widget +weight: 10 +--- + +The AI chat widget sends requests to a language model through the selected AI provider. You can configure general instructions (the Global prompt) and a set of quick-question buttons (Quick questions). + +## Configuration + +| Name | Required | Description | +| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Global prompt | No | General instructions for each request. The widget combines them with the prompt of the selected quick question before sending it | +| Quick questions | Yes | A set of buttons with labels and prompt text (up to 20). Add at least one question for the widget to work correctly | + +Configure the following fields for each quick question: + +| Name | Required | Description | +| ------------- | -------- | ------------------------------------------------------------------------------------------------- | +| Question name | Yes | A short label displayed in the widget's bottom panel and in the chat | +| Prompt | Yes | Instructions sent to the model when the user selects the button. Go templating is supported | + +When writing a prompt, explicitly specify the names of the Model Context Protocol (MCP) tools that the model must call to prepare the response. + +Example prompt for a quick question: + +```text +1. Call the MCP tool get_external_data for the external service "Deckhouse Code" and retrieve pipelines for the project with ID {{ .entity.properties.deckhouse_code_id }}. +2. Display a table with the 10 latest pipelines. +``` + +## Using the widget + +To use the widget, add at least one [AI provider](../../../../user/ai-assistant/#connecting-an-ai-provider). + +The chat does not retain history: + +- It displays only one response to the most recent question. +- The response is not retained when the user navigates to another page or refreshes the page. + +Before sending a question, the user can customize the prompt by selecting **Send with prompt changes** from the question button menu. diff --git a/content/documentation/admin/widgets/ai/chat.ru.md b/content/documentation/admin/widgets/ai/chat.ru.md new file mode 100644 index 00000000..b14523bd --- /dev/null +++ b/content/documentation/admin/widgets/ai/chat.ru.md @@ -0,0 +1,41 @@ +--- +title: AI-чат +description: Настройка и использование виджета чата с языковой моделью +weight: 10 +--- + +Виджет «AI-чат» позволяет отправлять запросы к языковой модели через выбранный AI-провайдер: задаются общие инструкции («Глобальный промпт») и набор кнопок быстрых вопросов («Быстрые вопросы»). + +## Конфигурация + +| Название | Обязательность | Описание | +| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Глобальный промпт | Нет | Общие инструкции к каждому запросу; при отправке объединяются с промптом выбранной кнопки быстрого вопроса | +| Быстрые вопросы | Да | Набор кнопок с подписью и текстом промпта (до 20); для корректной работы виджета добавьте хотя бы один вопрос | + +Для каждого быстрого вопроса задайте следующие поля: + +| Название | Обязательность | Описание | +| ---------------- | -------------- | ------------------------------------------------------------------------------------------- | +| Название вопроса | Да | Короткая подпись, отображаемая на нижней панели виджета и в чате | +| Промпт | Да | Инструкция для модели при нажатии на эту кнопку; допускается использование Go-шаблонизации | + +При заполнении промпта явно укажите названия инструментов Model Context Protocol (MCP), которые должна вызвать модель при подготовке ответа. + +Пример промпта для быстрого вопроса: + +```text +1. Вызови MCP tool get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. +2. Выведи таблицу с последними 10 пайплайнами. +``` + +## Использование виджета + +Для использования виджета добавьте хотя бы один [AI-провайдера](../../../../user/ai-assistant/#подключение-ai-провайдера). + +У чата не предусмотрена история: + +- Выводится только один ответ на последний заданный вопрос. +- Ответ не сохраняется при переходе на другую страницу или при обновлении страницы. + +Перед отправкой вопроса измените промпт, выбрав пункт «Отправить с изменением промпта» в выпадающем меню кнопки вопроса. diff --git a/content/documentation/admin/widgets/bitbucket/_index.md b/content/documentation/admin/widgets/bitbucket/_index.md new file mode 100644 index 00000000..8691b1dc --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/_index.md @@ -0,0 +1,5 @@ +--- +title: Bitbucket +description: Bitbucket widgets for viewing and managing repository data. +weight: 30 +--- diff --git a/content/documentation/admin/widgets/bitbucket/_index.ru.md b/content/documentation/admin/widgets/bitbucket/_index.ru.md new file mode 100644 index 00000000..a430bac8 --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Bitbucket +description: Виджеты Bitbucket для просмотра данных репозиториев и управления ими. +weight: 30 +--- diff --git a/content/documentation/admin/widgets/bitbucket/pull-requests.md b/content/documentation/admin/widgets/bitbucket/pull-requests.md new file mode 100644 index 00000000..e5e4db03 --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/pull-requests.md @@ -0,0 +1,46 @@ +--- +title: Bitbucket. Pull Requests +description: Configuration, status filtering, and actions for Bitbucket pull requests. +weight: 10 +--- + +The widget displays Bitbucket Pull Request (PR) data and provides actions for managing PRs. + +## Configuration + +| Name | Required | Description | Example | +| ------------- | -------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| Project key | Yes | The part of the repository URL immediately after `/projects/` | For `https:///projects/MYTEAM/repos/backend`, specify `MYTEAM` | +| Repository ID | Yes | The part of the repository URL immediately after `/repos/` | For `https:///projects/MYTEAM/repos/backend`, specify `backend` | + +where: +- `` — the hostname of the Bitbucket server. + +## Filtering by status + +The widget can filter displayed Pull Requests by status. Select one of the following statuses in the widget request settings: + +- **Open** — displays only open PRs. +- **Merged** — displays only merged PRs. +- **Declined** — displays only declined PRs. +- **All** — displays PRs in any status. + +By default, the widget displays only open PRs. + +## Additional widget features + +When actions are enabled in the settings, the widget provides the following Pull Request actions: + +- **Merge** — merges an open Pull Request. This action is available only for open PRs. +- **Close** — declines a Pull Request. +- **View changes** — displays the diff for a Pull Request. +- **Comments** — displays and adds comments to a PR. +- **Create PR** — creates a Pull Request with a source branch, target branch, reviewers, title, and description. + +{{< alert level="info" >}} +Pull Request actions require the corresponding permissions in the Bitbucket repository. +{{< /alert >}} + +## Authentication + +Authentication is described in [External services](../../external-services/#bitbucket). diff --git a/content/documentation/admin/widgets/bitbucket/pull-requests.ru.md b/content/documentation/admin/widgets/bitbucket/pull-requests.ru.md new file mode 100644 index 00000000..c2c3416d --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/pull-requests.ru.md @@ -0,0 +1,46 @@ +--- +title: Bitbucket. Запросы на слияние +description: Настройка, фильтрация по статусу и действия с запросами на слияние в Bitbucket. +weight: 10 +--- + +Виджет позволяет отображать данные о запросах на слияние (PR) в Bitbucket и выполнять действия с ними. + +## Конфигурация + +| Название | Обязательность | Описание | Пример | +| ------------------------- | -------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- | +| Ключ проекта | Да | Часть URL репозитория, которая идёт сразу после `/projects/` | Для `https:///projects/MYTEAM/repos/backend` укажите `MYTEAM` | +| Идентификатор репозитория | Да | Часть URL репозитория, которая идёт сразу после `/repos/` | Для `https:///projects/MYTEAM/repos/backend` укажите `backend` | + +где: +- `` — имя хоста сервера Bitbucket. + +## Фильтрация по статусу + +Виджет позволяет фильтровать отображаемые запросы на слияние по статусу. В настройках запроса виджета можно выбрать один из следующих статусов: + +- «Открыт» — показывает только открытые PR. +- «Слит» — показывает только слитые PR. +- «Отклонён» — показывает только отклонённые PR. +- «Все» — показывает PR в любом статусе. + +По умолчанию отображаются только открытые PR. + +## Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет выполнять следующие действия с запросами на слияние: + +- «Слить» — слияние открытого запроса на слияние (доступно только для открытых PR). +- «Закрыть» — отклонение запроса на слияние. +- «Просмотр изменений» — сравнение изменений в запросе на слияние. +- «Комментарии» — просмотр и добавление комментариев к PR. +- «Создать PR» — создание нового запроса на слияние с указанием исходной и целевой ветки, рецензентов, названия и описания. + +{{< alert level="info" >}} +Для выполнения действий с PR требуются соответствующие права доступа в репозитории Bitbucket. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#bitbucket). diff --git a/content/documentation/admin/widgets/bitbucket/tags.md b/content/documentation/admin/widgets/bitbucket/tags.md new file mode 100644 index 00000000..35f7aa61 --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/tags.md @@ -0,0 +1,40 @@ +--- +title: Bitbucket. Tags +description: Display and creation settings for tags in a Bitbucket repository. +weight: 20 +--- + +The widget displays data about tags in a Bitbucket repository. + +## Configuration + +| Name | Required | Description | Example | +| ----------- | -------- | -------------------------------------------------------------- | ---------------------------------------------------------- | +| Project key | Yes | The part of the repository URL immediately after `/projects/` | For `https:///projects/MYTEAM/repos/backend`, specify `MYTEAM` | +| Repository | Yes | The part of the repository URL immediately after `/repos/` | For `https:///projects/MYTEAM/repos/backend`, specify `backend` | + +where: +- `` — the hostname of the Bitbucket server. + +## Displayed data + +For each repository tag, the widget displays the tag name and commit details, +including the hash, message, author, creation date, and a link to the commit in Bitbucket. + +## Additional widget features + +### Creating tags + +The widget can create tags in Bitbucket directly from Deckhouse Development Platform (DDP). + +#### Configuration + +| Name | Required | Description | +| ----------- | -------- | ---------------------------------------------------------------------------- | +| Name | Yes | The name of the tag to create | +| Create from | Yes | The branch or existing tag from which to create the new tag. Select it from the list | +| Description | No | The description of the tag to create | + +## Authentication + +Authentication is described in [External services](../../external-services/#bitbucket). diff --git a/content/documentation/admin/widgets/bitbucket/tags.ru.md b/content/documentation/admin/widgets/bitbucket/tags.ru.md new file mode 100644 index 00000000..0099a68b --- /dev/null +++ b/content/documentation/admin/widgets/bitbucket/tags.ru.md @@ -0,0 +1,40 @@ +--- +title: Bitbucket. Теги +description: Просмотр и создание тегов репозитория с помощью виджета Bitbucket. +weight: 20 +--- + +Виджет позволяет отображать данные о тегах репозитория в Bitbucket. + +## Конфигурация + +| Название | Обязательность | Описание | Пример | +| ------------ | -------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- | +| Ключ проекта | Да | Часть URL репозитория, которая идёт сразу после `/projects/` | Для `https:///projects/MYTEAM/repos/backend` укажите `MYTEAM` | +| Репозиторий | Да | Часть URL репозитория, которая идёт сразу после `/repos/` | Для `https:///projects/MYTEAM/repos/backend` укажите `backend` | + +где: +- `` — имя хоста сервера Bitbucket. + +## Отображаемые данные + +Для каждого тега репозитория виджет отображает название и сведения о коммите: +хеш, сообщение, автора, дату создания и ссылку на коммит в Bitbucket. + +## Дополнительные возможности виджета + +### Создание тегов + +Виджет позволяет создавать теги в Bitbucket напрямую из Deckhouse Development Platform (DDP). + +#### Конфигурация + +| Название | Обязательность | Описание | +| ---------- | -------------- | ---------------------------------------------------------------------------------- | +| Название | Да | Название создаваемого тега | +| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег (выбирается из списка) | +| Описание | Нет | Описание создаваемого тега | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#bitbucket). diff --git a/content/documentation/admin/widgets/clickhouse/_index.md b/content/documentation/admin/widgets/clickhouse/_index.md new file mode 100644 index 00000000..f67663f8 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/_index.md @@ -0,0 +1,5 @@ +--- +title: ClickHouse +description: Widgets for visualizing and exploring data from ClickHouse. +weight: 40 +--- diff --git a/content/documentation/admin/widgets/clickhouse/_index.ru.md b/content/documentation/admin/widgets/clickhouse/_index.ru.md new file mode 100644 index 00000000..70852d56 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: ClickHouse +description: Виджеты для визуализации и анализа данных из ClickHouse. +weight: 40 +--- diff --git a/content/documentation/admin/widgets/clickhouse/metrics-range.md b/content/documentation/admin/widgets/clickhouse/metrics-range.md new file mode 100644 index 00000000..87ef6d34 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/metrics-range.md @@ -0,0 +1,39 @@ +--- +title: ClickHouse. Metrics (range) +description: Time-series chart based on a ClickHouse SQL query. +weight: 10 +--- + +The widget plots a line chart based on a read-only SQL query to ClickHouse. +Use the `{{from}}` and `{{to}}` placeholders in the query to specify the time range boundaries. + +Example of a valid widget query: + +```sql +SELECT + toStartOfMinute(timestamp) AS time, + avg(value) AS value, + service AS series +FROM metrics +WHERE timestamp >= {{from}} AND timestamp < {{to}} +GROUP BY time, series +ORDER BY time +``` + +## Configuration + +| Name | Required | Description | Default value | +| ------------- | -------- | ----------------------------------------------------------------------------------------------- | ------------- | +| Query | Yes | Read-only SQL query. Use `{{from}}` and `{{to}}` to specify the time range | — | +| Database | No | ClickHouse database name passed in the `X-ClickHouse-Database` header | — | +| Default range | No | Range used when opening or refreshing the widget if no range is specified in the query parameters | Last hour | +| Time column | Yes | Column containing timestamps for the chart's X-axis | — | +| Value column | Yes | Column containing numeric values for the chart's Y-axis | — | +| Series column | No | Column used as the series name in the chart legend | — | +| Threshold | No | Threshold displayed as a horizontal line on the chart | — | +| Minimum value | No | Starting point for the chart's vertical axis | — | +| Maximum value | No | End point for the chart's vertical axis | — | + +## Authorization + +Authorization is described in [External services](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/metrics-range.ru.md b/content/documentation/admin/widgets/clickhouse/metrics-range.ru.md new file mode 100644 index 00000000..f55701c3 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/metrics-range.ru.md @@ -0,0 +1,39 @@ +--- +title: ClickHouse. Метрики (диапазон) +description: График временных рядов на основе SQL-запроса к ClickHouse. +weight: 10 +--- + +Виджет строит линейный график на основе SQL-запроса только для чтения к ClickHouse. +Используйте в запросе плейсхолдеры `{{from}}` и `{{to}}` для подстановки границ временного интервала. + +Пример корректного запроса для виджета: + +```sql +SELECT + toStartOfMinute(timestamp) AS time, + avg(value) AS value, + service AS series +FROM metrics +WHERE timestamp >= {{from}} AND timestamp < {{to}} +GROUP BY time, series +ORDER BY time +``` + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | +| Запрос | Да | SQL-запрос только для чтения. Используйте `{{from}}` и `{{to}}` для подстановки интервала | — | +| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | — | +| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | +| Столбец времени | Да | Столбец с меткой времени для оси X графика | — | +| Столбец значения | Да | Столбец с числовыми значениями для оси Y графика | — | +| Столбец серии | Нет | Столбец с названием серии в легенде графика | — | +| Пороговое значение | Нет | Порог, отображаемый в виде горизонтальной линии на графике | — | +| Минимальное значение | Нет | Начальная точка отсчёта для вертикальной оси графика | — | +| Максимальное значение | Нет | Предельная точка отсчёта для вертикальной оси графика | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/metrics-single.md b/content/documentation/admin/widgets/clickhouse/metrics-single.md new file mode 100644 index 00000000..2742ffd8 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/metrics-single.md @@ -0,0 +1,36 @@ +--- +title: ClickHouse. Metrics (single value) +description: Single-value metric based on a ClickHouse SQL query. +weight: 20 +--- + +The widget displays a single number based on a read-only SQL query to ClickHouse. +You can specify a unit and configure a threshold for the value. +The query must return one row; the widget displays the value from the first column. + +Example of a valid widget query: + +```sql +SELECT count() AS value +FROM events +WHERE timestamp >= {{from}} AND timestamp < {{to}} +``` + +## Configuration + +| Name | Required | Description | Default value | +| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------- | +| Query | Yes | Read-only SQL query. Use `{{from}}` and `{{to}}` to specify the time range | — | +| Database | No | ClickHouse database name passed in the `X-ClickHouse-Database` header | — | +| Default range | No | Range used when opening or refreshing the widget if no range is specified in the query parameters | Last hour | +| Decimal places | No | Precision used to display the returned value | — | +| Unit | No | Suffix displayed with the returned value | — | +| Show threshold | No | Displays ` / `, where `` is the current metric value and `` is the configured threshold | `false` | +| Threshold | No | Threshold value | — | +| Lower value is better | No | Considers the metric healthy when its value is below the configured threshold | `false` | +| Warning threshold (%) | No | Boundary between red and orange. A metric value above this percentage of the threshold is displayed in orange | 60 | +| Success threshold (%) | No | Boundary between orange and green. A metric value above this percentage of the threshold is displayed in green | 90 | + +## Authorization + +Authorization is described in [External services](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/metrics-single.ru.md b/content/documentation/admin/widgets/clickhouse/metrics-single.ru.md new file mode 100644 index 00000000..46fde53e --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/metrics-single.ru.md @@ -0,0 +1,36 @@ +--- +title: ClickHouse. Метрики (значение) +description: Одиночное значение метрики на основе SQL-запроса к ClickHouse. +weight: 20 +--- + +Виджет выводит одно число на основе SQL-запроса только для чтения к ClickHouse. +Для числа можно задать единицу измерения и пороговое значение. +Запрос должен возвращать одну строку: виджет отображает значение первого столбца. + +Пример корректного запроса для виджета: + +```sql +SELECT count() AS value +FROM events +WHERE timestamp >= {{from}} AND timestamp < {{to}} +``` + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Запрос | Да | SQL-запрос только для чтения. Используйте `{{from}}` и `{{to}}` для подстановки интервала | — | +| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | — | +| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | +| Количество цифр после запятой | Нет | Точность отображения полученного значения | — | +| Единица измерения | Нет | Постфикс, с которым отображается полученное значение | — | +| Отображать пороговое значение | Нет | Отображает ` / `, где `` — текущее значение метрики, а `` — настроенный порог | `false` | +| Пороговое значение | Нет | Пороговое значение | — | +| Меньшее значение считается лучше | Нет | Метрика считается «хорошей», когда её значение ниже заданного порогового значения | `false` | +| Порог предупреждения (%) | Нет | Граница между красным и оранжевым цветами. Если значение метрики превышает этот процент от порога, оно получит оранжевый цвет | 60 | +| Порог успеха (%) | Нет | Граница между оранжевым и зелёным цветами. Если значение метрики превышает этот процент от порога, оно получит зелёный цвет | 90 | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/table.md b/content/documentation/admin/widgets/clickhouse/table.md new file mode 100644 index 00000000..0e77ba79 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/table.md @@ -0,0 +1,21 @@ +--- +title: ClickHouse. Table +description: Sortable and paginated table based on a ClickHouse SQL query. +weight: 30 +--- + +The widget displays the result of a read-only SQL query to ClickHouse as a sortable, paginated table. +Use the `{{from}}` and `{{to}}` placeholders in the query. + +## Configuration + +| Name | Required | Description | Default value | +| ------------- | -------- | ------------------------------------------------------------------------------------------------- | ------------- | +| Query | Yes | Read-only SQL query. Use `{{from}}` and `{{to}}` to specify the time range | — | +| Database | No | ClickHouse database name passed in the `X-ClickHouse-Database` header | — | +| Default range | No | Range used when opening or refreshing the widget if no range is specified in the query parameters | Last hour | +| Page size | Yes | Number of rows loaded by each query | 50 | + +## Authorization + +Authorization is described in [External services](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/table.ru.md b/content/documentation/admin/widgets/clickhouse/table.ru.md new file mode 100644 index 00000000..1a4dd593 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/table.ru.md @@ -0,0 +1,22 @@ +--- +title: ClickHouse. Таблица +description: Таблица с сортировкой и пагинацией на основе SQL-запроса к ClickHouse. +weight: 30 +--- + +Виджет выводит результат SQL-запроса только для чтения к ClickHouse +в виде таблицы с сортировкой и постраничной навигацией. +Используйте в запросе плейсхолдеры `{{from}}` и `{{to}}`. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | +| Запрос | Да | SQL-запрос только для чтения. Используйте `{{from}}` и `{{to}}` для подстановки интервала | — | +| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | — | +| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | +| Размер страницы | Да | Количество строк, загружаемых за один запрос | 50 | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/top-n.md b/content/documentation/admin/widgets/clickhouse/top-n.md new file mode 100644 index 00000000..80ac28be --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/top-n.md @@ -0,0 +1,34 @@ +--- +title: ClickHouse. Top N +description: Horizontal bar chart based on a ClickHouse SQL query. +weight: 40 +--- + +The widget plots a horizontal bar chart based on a read-only SQL query to ClickHouse. +The query must return columns containing labels and numeric values. +The **Limit** parameter restricts the number of displayed rows. + +Example of a valid widget query: + +```sql +SELECT service AS label, count() AS value +FROM events +WHERE timestamp >= {{from}} AND timestamp < {{to}} +GROUP BY label +ORDER BY value DESC +``` + +## Configuration + +| Name | Required | Description | Default value | +| ------------- | -------- | ------------------------------------------------------------------------------------------------- | ------------- | +| Query | Yes | Read-only SQL query. Use `{{from}}` and `{{to}}` to specify the time range | — | +| Database | No | ClickHouse database name passed in the `X-ClickHouse-Database` header | — | +| Default range | No | Range used when opening or refreshing the widget if no range is specified in the query parameters | Last hour | +| Label column | Yes | Column containing the bar labels | — | +| Value column | Yes | Column containing numeric values that determine bar length | — | +| Limit | Yes | Maximum number of rows in the chart | 10 | + +## Authorization + +Authorization is described in [External services](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/clickhouse/top-n.ru.md b/content/documentation/admin/widgets/clickhouse/top-n.ru.md new file mode 100644 index 00000000..7823fae4 --- /dev/null +++ b/content/documentation/admin/widgets/clickhouse/top-n.ru.md @@ -0,0 +1,34 @@ +--- +title: ClickHouse. Топ N +description: Горизонтальная столбчатая диаграмма на основе SQL-запроса к ClickHouse. +weight: 40 +--- + +Виджет строит горизонтальную столбчатую диаграмму на основе SQL-запроса только для чтения к ClickHouse. +Запрос должен возвращать столбцы с лейблами и числовыми значениями. +Параметр «Лимит» ограничивает количество отображаемых строк. + +Пример корректного запроса для виджета: + +```sql +SELECT service AS label, count() AS value +FROM events +WHERE timestamp >= {{from}} AND timestamp < {{to}} +GROUP BY label +ORDER BY value DESC +``` + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | +| Запрос | Да | SQL-запрос только для чтения. Используйте `{{from}}` и `{{to}}` для подстановки интервала | — | +| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | — | +| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | +| Столбец лейбла | Да | Столбец с подписями элементов диаграммы | — | +| Столбец значения | Да | Столбец с числовыми значениями, определяющими длину элементов диаграммы | — | +| Лимит | Да | Максимальное количество строк для диаграммы | 10 | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#clickhouse). diff --git a/content/documentation/admin/widgets/codescoring/_index.md b/content/documentation/admin/widgets/codescoring/_index.md new file mode 100644 index 00000000..9c363665 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/_index.md @@ -0,0 +1,5 @@ +--- +title: CodeScoring +description: Widgets for software composition and security analysis data +weight: 50 +--- diff --git a/content/documentation/admin/widgets/codescoring/_index.ru.md b/content/documentation/admin/widgets/codescoring/_index.ru.md new file mode 100644 index 00000000..b87a8185 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: CodeScoring +description: Виджеты с данными анализа состава и безопасности программного обеспечения +weight: 50 +--- diff --git a/content/documentation/admin/widgets/codescoring/dependencies.md b/content/documentation/admin/widgets/codescoring/dependencies.md new file mode 100644 index 00000000..341a19d2 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/dependencies.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Dependencies +description: Product dependency details retrieved from CodeScoring +weight: 10 +--- + +The widget displays a table of product dependencies based on CodeScoring data. For each dependency, the table includes its name, version, license, number of vulnerabilities, and other information. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | -------------------------- | ------------- | +| URL | Yes | CodeScoring URL | — | +| Project ID | Yes | Project ID in CodeScoring | — | + +## Authentication + +Authentication is described in [External services](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/codescoring/dependencies.ru.md b/content/documentation/admin/widgets/codescoring/dependencies.ru.md new file mode 100644 index 00000000..1d799eee --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/dependencies.ru.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Зависимости +description: Сведения о зависимостях продукта, полученные из CodeScoring +weight: 10 +--- + +Виджет позволяет вывести таблицу с зависимостями продукта на основе данных из CodeScoring с указанием названия зависимости, версии, лицензии, количества уязвимостей и другой информации для каждой зависимости. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ----------------------------------- | --------------------- | +| URL | Да | URL CodeScoring | — | +| ID проекта | Да | Идентификатор проекта в CodeScoring | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/codescoring/secrets.md b/content/documentation/admin/widgets/codescoring/secrets.md new file mode 100644 index 00000000..3edb05f9 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/secrets.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Secrets +description: Project secret findings and scan controls from CodeScoring +weight: 30 +--- + +The widget displays a table of secrets detected in a project by CodeScoring. It can start or cancel secret scanning for the selected branch or tag. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | -------------------------- | ------------- | +| URL | Yes | CodeScoring URL | — | +| Project ID | Yes | Project ID in CodeScoring | — | + +## Authentication + +Authentication is described in [External services](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/codescoring/secrets.ru.md b/content/documentation/admin/widgets/codescoring/secrets.ru.md new file mode 100644 index 00000000..5cb3271d --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/secrets.ru.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Секреты +description: Найденные секреты проекта и управление сканированием в CodeScoring +weight: 30 +--- + +Виджет позволяет вывести таблицу найденных секретов проекта из CodeScoring. Поддерживаются запуск либо отмена сканирования секретов по выбранной ветке или тегу. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ----------------------------------- | --------------------- | +| URL | Да | URL CodeScoring | — | +| ID проекта | Да | Идентификатор проекта в CodeScoring | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/codescoring/vulnerabilities.md b/content/documentation/admin/widgets/codescoring/vulnerabilities.md new file mode 100644 index 00000000..fffe5178 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/vulnerabilities.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Vulnerabilities +description: Product vulnerability details retrieved from CodeScoring +weight: 20 +--- + +The widget displays a table of product vulnerabilities based on CodeScoring data. For each vulnerability, the table includes its code, severity, exploit availability, and fixed version. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | -------------------------- | ------------- | +| URL | Yes | CodeScoring URL | — | +| Project ID | Yes | Project ID in CodeScoring | — | + +## Authentication + +Authentication is described in [External services](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/codescoring/vulnerabilities.ru.md b/content/documentation/admin/widgets/codescoring/vulnerabilities.ru.md new file mode 100644 index 00000000..ca728e97 --- /dev/null +++ b/content/documentation/admin/widgets/codescoring/vulnerabilities.ru.md @@ -0,0 +1,18 @@ +--- +title: CodeScoring. Уязвимости +description: Сведения об уязвимостях продукта, полученные из CodeScoring +weight: 20 +--- + +Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из CodeScoring с указанием кода уязвимости, уровня критичности, наличия эксплойта, исправленной версии для каждой уязвимости. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ----------------------------------- | --------------------- | +| URL | Да | URL CodeScoring | — | +| ID проекта | Да | Идентификатор проекта в CodeScoring | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#codescoring). diff --git a/content/documentation/admin/widgets/defectdojo/_index.md b/content/documentation/admin/widgets/defectdojo/_index.md new file mode 100644 index 00000000..c313a4ed --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/_index.md @@ -0,0 +1,5 @@ +--- +title: DefectDojo +description: Widgets for visualizing product vulnerability data from DefectDojo +weight: 60 +--- diff --git a/content/documentation/admin/widgets/defectdojo/_index.ru.md b/content/documentation/admin/widgets/defectdojo/_index.ru.md new file mode 100644 index 00000000..343dd51f --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: DefectDojo +description: Виджеты для визуализации данных об уязвимостях из DefectDojo +weight: 60 +--- diff --git a/content/documentation/admin/widgets/defectdojo/product-findings-summary.md b/content/documentation/admin/widgets/defectdojo/product-findings-summary.md new file mode 100644 index 00000000..36d9bb0b --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product-findings-summary.md @@ -0,0 +1,25 @@ +--- +title: DefectDojo. Product vulnerabilities summary +description: Product vulnerability totals grouped by severity +weight: 30 +--- + +The widget displays a chart with the total number of product vulnerabilities from DefectDojo, grouped by severity. + +## Configuration + +| Name | Required | Description | Default value | +| ------------ | -------- | ------------------------------------------------------------ | ------------- | +| URL | Yes | DefectDojo URL without the API path (`/api/v2`) | — | +| Product name | Yes | Product name in DefectDojo | — | + +## Additional widget features + +When viewing the widget, configure the following parameters: + +- **Active vulnerabilities** — when enabled, loads product vulnerabilities with the `Active` flag set to `true`. When disabled, loads vulnerabilities with the `Active` flag set to `false`. Enabled by default. +- **Duplicate vulnerabilities** — when enabled, loads product vulnerabilities with the `Duplicate` flag set to `true`. When disabled, loads vulnerabilities with the `Duplicate` flag set to `false`. Disabled by default. + +## Authentication + +Authentication is described in [External services](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/defectdojo/product-findings-summary.ru.md b/content/documentation/admin/widgets/defectdojo/product-findings-summary.ru.md new file mode 100644 index 00000000..3b804516 --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product-findings-summary.ru.md @@ -0,0 +1,25 @@ +--- +title: DefectDojo. Уязвимости в продукте (общая статистика) +description: Общее количество уязвимостей продукта по уровням критичности +weight: 30 +--- + +Виджет позволяет вывести график с общим количеством уязвимостей продукта на основе информации из DefectDojo с разбивкой по уровням критичности. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------- | -------------- | ------------------------------------------------------ | --------------------- | +| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | — | +| Название продукта | Да | Название продукта в DefectDojo | — | + +## Дополнительные возможности виджета + +При просмотре виджета настройте следующие параметры: + +* «Активные уязвимости» — если включено, загружаются уязвимости продукта с флагом `Active`, равным `true`. Если отключено, загружаются уязвимости продукта с флагом `Active`, равным `false`. Включено по умолчанию. +* «Дублирующиеся уязвимости» — если включено, загружаются уязвимости продукта с флагом `Duplicate`, равным `true`. Если отключено, загружаются уязвимости продукта с флагом `Duplicate`, равным `false`. Отключено по умолчанию. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/defectdojo/product-findings.md b/content/documentation/admin/widgets/defectdojo/product-findings.md new file mode 100644 index 00000000..4b7c7435 --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product-findings.md @@ -0,0 +1,25 @@ +--- +title: DefectDojo. Product vulnerability details +description: Detailed product vulnerabilities retrieved from DefectDojo +weight: 20 +--- + +The widget displays a table of product vulnerabilities based on DefectDojo data. For each vulnerability, the table includes its severity, description, and detection date. + +## Configuration + +| Name | Required | Description | Default value | +| ------------ | -------- | ------------------------------------------------------------ | ------------- | +| URL | Yes | DefectDojo URL without the API path (`/api/v2`) | — | +| Product name | Yes | Product name in DefectDojo | — | + +## Additional widget features + +When viewing the widget, configure the following parameters: + +- **Active vulnerabilities** — when enabled, loads product vulnerabilities with the `Active` flag set to `true`. When disabled, loads vulnerabilities with the `Active` flag set to `false`. Enabled by default. +- **Duplicate vulnerabilities** — when enabled, loads product vulnerabilities with the `Duplicate` flag set to `true`. When disabled, loads vulnerabilities with the `Duplicate` flag set to `false`. Disabled by default. + +## Authentication + +Authentication is described in [External services](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/defectdojo/product-findings.ru.md b/content/documentation/admin/widgets/defectdojo/product-findings.ru.md new file mode 100644 index 00000000..d1e8ab36 --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product-findings.ru.md @@ -0,0 +1,25 @@ +--- +title: DefectDojo. Уязвимости в продукте (детали) +description: Подробные сведения об уязвимостях продукта из DefectDojo +weight: 20 +--- + +Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из DefectDojo с указанием уровня критичности, описания и даты обнаружения для каждой уязвимости. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------- | -------------- | ------------------------------------------------------ | --------------------- | +| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | — | +| Название продукта | Да | Название продукта в DefectDojo | — | + +## Дополнительные возможности виджета + +При просмотре виджета настройте следующие параметры: + +* «Активные уязвимости» — если включено, загружаются уязвимости продукта с флагом `Active`, равным `true`. Если отключено, загружаются уязвимости продукта с флагом `Active`, равным `false`. Включено по умолчанию. +* «Дублирующиеся уязвимости» — если включено, загружаются уязвимости продукта с флагом `Duplicate`, равным `true`. Если отключено, загружаются уязвимости продукта с флагом `Duplicate`, равным `false`. Отключено по умолчанию. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/defectdojo/product.md b/content/documentation/admin/widgets/defectdojo/product.md new file mode 100644 index 00000000..aebbdaba --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product.md @@ -0,0 +1,39 @@ +--- +title: DefectDojo. Product +description: Product vulnerabilities grouped by engagement and severity +weight: 10 +--- + +The widget displays product vulnerabilities from DefectDojo, grouped by engagement and severity. + +## Configuration + +| Name | Required | Description | Default value | +| -------------- | -------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- | +| URL | Yes | DefectDojo URL without the API path (`/api/v2`) | — | +| Product name | Yes | Product name in DefectDojo | — | +| Severity levels | Yes | Vulnerability severity levels loaded when the widget opens or when the selected engagement changes | `Critical`, `High`, `Medium`, `Low`, `Info` | + +## Request parameters + +In the widget request settings, select the severity levels to load only vulnerabilities with those levels. By default, the widget uses the levels from its configuration. Changing the levels reloads data from DefectDojo. + +## Additional widget features + +### Filters + +- **Engagement** — selects a product engagement. By default, the most recently created engagement, with the highest ID, is selected. Changing the engagement reloads the data. +- **Filters** — filters vulnerabilities by severity, tags, tests, and components. Tag, test, and component filters apply only to already loaded vulnerabilities and do not send new requests to DefectDojo. + +### Tabs + +- **Overview** — displays vulnerabilities by severity, tags (top 10), tests (top 10), and components (top 10). Charts use the filtered vulnerability set. +- **Details** — displays a table with details for each vulnerability. + +{{< alert level="info" >}} +If the selected Engagement and severity levels contain more than 1,000 vulnerabilities, the widget displays the first 1,000 records and a partial-load warning. Tag, test, and component filters apply only to the loaded set. +{{< /alert >}} + +## Authentication + +Authentication is described in [External services](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/defectdojo/product.ru.md b/content/documentation/admin/widgets/defectdojo/product.ru.md new file mode 100644 index 00000000..92d8be53 --- /dev/null +++ b/content/documentation/admin/widgets/defectdojo/product.ru.md @@ -0,0 +1,39 @@ +--- +title: DefectDojo. Продукт +description: Уязвимости продукта с разбивкой по объектам Engagement и критичности +weight: 10 +--- + +Виджет позволяет просматривать уязвимости продукта в DefectDojo с разбивкой по объектам Engagement и уровням критичности. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------ | -------------- | ------------------------------------------------------------------------------------------------ | --------------------------------- | +| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | — | +| Название продукта | Да | Название продукта в DefectDojo | — | +| Уровни уязвимостей | Да | Уровни критичности уязвимостей, которые загружаются при открытии виджета и при смене объекта Engagement | `Critical`, `High`, `Medium`, `Low`, `Info` | + +## Параметры запроса + +В настройках запроса виджета выберите уровни критичности, чтобы загрузить только соответствующие уязвимости. По умолчанию используются уровни из конфигурации виджета. Изменение уровней приводит к повторной загрузке данных из DefectDojo. + +## Дополнительные возможности виджета + +### Фильтры + +* «Engagement» — выбор объекта Engagement для продукта. По умолчанию выбирается последний созданный объект Engagement (с наибольшим идентификатором). При смене объекта Engagement данные загружаются повторно. +* «Фильтры» — панель фильтров по уровням критичности, тегам, тестам и компонентам. Фильтры по тегам, тестам и компонентам применяются только к уже загруженным уязвимостям и не вызывают новых запросов к DefectDojo. + +### Вкладки + +* «Обзор» — уязвимости по уровню критичности, по тегам (топ-10), по тестам (топ-10), по компонентам (топ-10). Диаграммы строятся по отфильтрованному набору уязвимостей. +* «Детали» — таблица уязвимостей с деталями по каждой из них. + +{{< alert level="info" >}} +Если уязвимостей для выбранного Engagement и уровней критичности больше 1000, в виджете отображаются первые 1000 записей и предупреждение о частичной загрузке. Фильтры по тегам, тестам и компонентам действуют только в пределах загруженного набора. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#defectdojo). diff --git a/content/documentation/admin/widgets/entities/_index.md b/content/documentation/admin/widgets/entities/_index.md new file mode 100644 index 00000000..c911f374 --- /dev/null +++ b/content/documentation/admin/widgets/entities/_index.md @@ -0,0 +1,5 @@ +--- +title: Entities +description: Widgets for displaying and managing entities in Deckhouse Development Platform. +weight: 70 +--- diff --git a/content/documentation/admin/widgets/entities/_index.ru.md b/content/documentation/admin/widgets/entities/_index.ru.md new file mode 100644 index 00000000..48e2cab7 --- /dev/null +++ b/content/documentation/admin/widgets/entities/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Сущности +description: Виджеты для отображения сущностей и управления ими в Deckhouse Development Platform. +weight: 70 +--- diff --git a/content/documentation/admin/widgets/entities/calendar.md b/content/documentation/admin/widgets/entities/calendar.md new file mode 100644 index 00000000..f365b36a --- /dev/null +++ b/content/documentation/admin/widgets/entities/calendar.md @@ -0,0 +1,29 @@ +--- +title: Entity calendar +description: Configuration and behavior of the widget that displays resource entities in a calendar. +weight: 10 +--- + +The widget displays entities of the selected resource in a calendar. + +## Displayed data + +- **Weekly calendar** — a seven-day grid for the current week. +- **Entities by date** — all entities whose selected date field matches a given day. +- **Entity information** — the name and description, if specified, of each entity. +- **Week navigation** — buttons for moving to the previous or next week. + +## Configuration + +| Name | Required | Description | Default | +|------------|----------|-------------------------------------------------------------------------------------------------------------------------------|---------| +| Resource | Yes | Resource whose entities are displayed in the calendar | — | +| Date field | Yes | Field containing the date used to display the entity in the calendar. It can be a system field (`createdAt`, `updatedAt`) or a `Date` parameter | — | + +## Notes + +- The widget displays the current week, from Monday through Sunday, by default. +- Use the **Previous week** and **Next week** buttons to navigate between weeks. +- Each day displays its date in `DD.MM` format. +- Entities are displayed as cards that link to the corresponding entity page. +- Entities with an empty or zero date are automatically excluded. diff --git a/content/documentation/admin/widgets/entities/calendar.ru.md b/content/documentation/admin/widgets/entities/calendar.ru.md new file mode 100644 index 00000000..d7641a33 --- /dev/null +++ b/content/documentation/admin/widgets/entities/calendar.ru.md @@ -0,0 +1,29 @@ +--- +title: Календарь сущностей +description: Настройка и особенности виджета для отображения сущностей ресурса в календаре. +weight: 10 +--- + +Виджет отображает сущности выбранного ресурса в календаре. + +## Отображаемые данные + +- «Недельный календарь» — сетка из 7 дней текущей недели. +- «Сущности по датам» — для каждого дня отображаются все сущности, у которых дата в выбранном поле соответствует этому дню. +- «Информация о сущностях» — для каждой сущности отображаются название и описание (если указано). +- «Навигация по неделям» — кнопки для перехода к предыдущей и следующей неделе. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Да | Ресурс, для которого отображается календарь | — | +| Поле даты | Да | Поле, из которого берётся дата для отображения сущности в календаре. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | — | + +## Особенности + +- Виджет отображает текущую неделю по умолчанию (с понедельника по воскресенье). +- Доступна навигация между неделями с помощью кнопок «Предыдущая неделя» и «Следующая неделя». +- Для каждого дня отображается дата в формате `DD.MM`. +- Сущности отображаются в виде карточек с возможностью перехода на страницу сущности. +- Сущности с пустой или нулевой датой автоматически исключаются из отображения. diff --git a/content/documentation/admin/widgets/entities/entity-status.md b/content/documentation/admin/widgets/entities/entity-status.md new file mode 100644 index 00000000..10297a5b --- /dev/null +++ b/content/documentation/admin/widgets/entities/entity-status.md @@ -0,0 +1,60 @@ +--- +title: Entity status +description: Status check results, blocked actions, and behavior of the entity status widget. +weight: 50 +--- + +The widget displays the entity status and status check results. + +## Displayed data + +The widget displays the following information. + +### Overall status + +The **progress bar** visualizes the overall entity status, including the percentage of successful checks. +The **successful check count** shows the number of successful checks out of all configured status checks. + +### Check list + +The following information is displayed for each status check: + +- **Check name** — the name of the check rule. +- **Status** — the check result: + - **Passed** — the check completed successfully. + - **Failed** — the check did not pass, but no execution error occurred. + - **Error** — an error occurred while running the check. +- **Last check time** — the date and time when the check last ran. +- **Error message** — the error text, displayed if the check ended with an error. + +### Statistics + +The bottom of the widget displays summary check statistics: + +- **Passed** — the number of successful checks. +- **Failed** — the number of checks that did not pass without execution errors. +- **Error** — the number of checks that ended with an error. + +### Blocked actions + +The widget automatically identifies and displays actions that are unavailable for the entity's current status. + +Display conditions: + +- The action must be available for the resource associated with the entity. +- The action must have allowed statuses configured. +- The entity's current status must not be in the action's list of allowed statuses. + +The widget displays the action name and description, if specified. + +## Configuration + +The widget requires no additional configuration. + +To use the widget, configure status checks for the resource associated with the entity. +For details, refer to [status check configuration](../../healthchecks/overview/). + +## Notes + +If no status checks are configured for the entity, the widget indicates that no checks are available. +If status check data is unavailable, the widget indicates that no data is available. diff --git a/content/documentation/admin/widgets/entities/entity-status.ru.md b/content/documentation/admin/widgets/entities/entity-status.ru.md new file mode 100644 index 00000000..5f847cfb --- /dev/null +++ b/content/documentation/admin/widgets/entities/entity-status.ru.md @@ -0,0 +1,59 @@ +--- +title: Статус сущности +description: Результаты проверок, заблокированные действия и особенности виджета статуса сущности. +weight: 50 +--- + +Виджет отображает информацию о статусе сущности и результатах проверок статуса. + +## Отображаемые данные + +Виджет показывает следующую информацию. + +### Общий статус + +«Прогресс-бар» визуально отображает общий статус сущности и процент успешно пройденных проверок. +«Счётчик успешных проверок» показывает количество пройденных проверок из общего числа настроенных проверок статуса. + +### Список проверок + +Для каждой проверки статуса отображается: + +- «Название проверки» — название правила проверки. +- «Статус» — результат выполнения проверки: + - «Пройдено» — проверка успешно пройдена. + - «Не пройдено» — проверка не пройдена (ошибок выполнения нет). + - «Ошибка» — при выполнении проверки произошла ошибка. +- «Время последней проверки» — дата и время последнего выполнения проверки. +- «Сообщение об ошибке» — текст ошибки (отображается, если проверка завершилась с ошибкой). + +### Статистика + +В нижней части виджета отображается сводная статистика по проверкам: + +- «Пройдено» — количество успешно пройденных проверок. +- «Не пройдено» — количество проверок, которые не были пройдены (без ошибок выполнения). +- «Ошибка» — количество проверок, завершившихся с ошибкой. + +### Заблокированные действия + +Виджет автоматически определяет и отображает действия, которые недоступны при текущем статусе сущности. +Действие отображается как заблокированное при выполнении следующих условий: + +- действие доступно для ресурса, связанного с сущностью; +- для действия настроены разрешённые статусы; +- текущий статус сущности не входит в список разрешённых статусов для этого действия. + +Виджет отображает название действия и его описание, если оно указано. + +## Конфигурация + +Виджет не требует дополнительной конфигурации. + +Настройте проверки статуса для ресурса, связанного с сущностью. +Инструкции приведены в разделе [«Проверки статуса»](../../healthchecks/overview/). + +## Особенности + +Если для сущности не настроено ни одной проверки статуса, виджет сообщает, что проверки отсутствуют. +Если данные о проверках статуса недоступны, виджет сообщает об отсутствии данных. diff --git a/content/documentation/admin/widgets/entities/entity-table.md b/content/documentation/admin/widgets/entities/entity-table.md new file mode 100644 index 00000000..0601cd5f --- /dev/null +++ b/content/documentation/admin/widgets/entities/entity-table.md @@ -0,0 +1,14 @@ +--- +title: Entity table +description: Configuration of the widget that displays Deckhouse Development Platform entities in a table. +weight: 30 +--- + +The widget displays entities created in Deckhouse Development Platform (DDP) as a table. + +## Configuration + +| Name | Required | Description | Default | +|--------------|----------|---------------------------------------------------------------------------------------------------------------|---------| +| Resource | Yes | Resource whose entities are displayed in the table | — | +| Show actions | No | Whether to display entity actions, such as running actions and scenarios or deleting entities | `false` | diff --git a/content/documentation/admin/widgets/entities/entity-table.ru.md b/content/documentation/admin/widgets/entities/entity-table.ru.md new file mode 100644 index 00000000..f296e38a --- /dev/null +++ b/content/documentation/admin/widgets/entities/entity-table.ru.md @@ -0,0 +1,14 @@ +--- +title: Таблица сущностей +description: Настройка виджета для отображения сущностей Deckhouse Development Platform в таблице. +weight: 30 +--- + +Виджет отображает сущности, созданные в Deckhouse Development Platform (DDP), в виде таблицы. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Да | Ресурс, сущности которого отображаются в таблице | — | +| Показывать действия | Нет | Необходимость отображения действий с сущностями (возможность запуска действий и сценариев, возможность удаления и др.) | `false` | diff --git a/content/documentation/admin/widgets/entities/kanban.md b/content/documentation/admin/widgets/entities/kanban.md new file mode 100644 index 00000000..62d1163b --- /dev/null +++ b/content/documentation/admin/widgets/entities/kanban.md @@ -0,0 +1,26 @@ +--- +title: Entity Kanban board +description: Configuration and behavior of the Kanban board for resource entities. +weight: 20 +--- + +The widget displays entities of the selected resource on a Kanban board. + +## Displayed data + +- **Columns** — configured board columns and a **No status** column for entities without a matching state parameter value. +- **Entity cards** — each entity displays its name, description if specified, check status, owner, and update date. +- **Moving cards** — dragging a card between columns updates the entity's state parameter value. This requires permission to modify entities. + +## Configuration + +| Name | Required | Description | Default | +|-----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| +| Resource | Yes | Resource whose entities are displayed on the board | — | +| State parameter | Yes | Entity parameter that determines the card column. Supported types: `String`, `Number`, `Boolean`, `Enum`, `List`, `Date`, `Percentage`, and `URL` | — | +| Columns | Yes | List of board columns. For each column, specify a name (the board heading), value (the state parameter value; for `Enum` and `List` parameters, select from the available options), and color (the tag color in the heading). Drag columns to change their order | — | + +## Notes + +Entities without a matching state parameter value are displayed in the **No status** column. +Cards cannot be moved without permission to modify entities. diff --git a/content/documentation/admin/widgets/entities/kanban.ru.md b/content/documentation/admin/widgets/entities/kanban.ru.md new file mode 100644 index 00000000..ea41407c --- /dev/null +++ b/content/documentation/admin/widgets/entities/kanban.ru.md @@ -0,0 +1,26 @@ +--- +title: Kanban-доска сущностей +description: Настройка и особенности Kanban-доски для сущностей ресурса. +weight: 20 +--- + +Виджет отображает сущности выбранного ресурса на Kanban-доске. + +## Отображаемые данные + +- «Колонки» — настроенные колонки доски и колонка «Без статуса» для сущностей без подходящего значения параметра состояния. +- «Карточки сущностей» — для каждой сущности отображаются название, описание (если указано), статус проверок, владелец и дата обновления. +- «Перемещение карточек» — перетаскивание карточки между колонками обновляет значение параметра состояния сущности (доступно при наличии прав на изменение сущностей). + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Да | Ресурс, сущности которого отображаются на доске | — | +| Параметр состояния | Да | Параметр сущности, определяющий колонку карточки. Поддерживаются типы `String`, `Number`, `Boolean`, `Enum`, `List`, `Date`, `Percentage`, `URL` | — | +| Колонки | Да | Список колонок доски. Для каждой колонки задаются: название (заголовок на доске), значение (значение параметра состояния; для параметров типа `Enum` и `List` выбирается из доступных опций) и цвет (цвет тега в заголовке). Порядок колонок настраивается перетаскиванием | — | + +## Особенности + +Сущности без подходящего значения параметра состояния отображаются в колонке «Без статуса». +При отсутствии прав на изменение сущностей перемещение карточек недоступно. diff --git a/content/documentation/admin/widgets/entities/timeline.md b/content/documentation/admin/widgets/entities/timeline.md new file mode 100644 index 00000000..86abbf8c --- /dev/null +++ b/content/documentation/admin/widgets/entities/timeline.md @@ -0,0 +1,26 @@ +--- +title: Entity timeline +description: Configuration and behavior of the timeline that displays resource entities by date. +weight: 40 +--- + +The widget displays entities of the selected resource on a timeline. + +## Displayed data + +- **Timeline chart** — a horizontal chart where each entity is represented by a bar spanning from its start date to its end date. +- **Entity information** — hovering over a bar displays the entity name and the period's start and end dates. +- **Sorting** — entities are sorted from oldest at the top to newest at the bottom. + +## Configuration + +| Name | Required | Description | Default | +|----------------|----------|---------------------------------------------------------------------------------------------------------------------|---------| +| Resource | Yes | Resource whose entities are displayed on the timeline | — | +| Start date field | Yes | Field containing the period start date. It can be a system field (`createdAt`, `updatedAt`) or a `Date` parameter | — | +| End date field | Yes | Field containing the period end date. It can be a system field (`createdAt`, `updatedAt`) or a `Date` parameter | — | + +## Notes + +The widget automatically scales the timeline to display all entities. +Entities with invalid dates, where the start date is later than the end date, are automatically excluded. diff --git a/content/documentation/admin/widgets/entities/timeline.ru.md b/content/documentation/admin/widgets/entities/timeline.ru.md new file mode 100644 index 00000000..fdfc9b52 --- /dev/null +++ b/content/documentation/admin/widgets/entities/timeline.ru.md @@ -0,0 +1,26 @@ +--- +title: Временная шкала сущностей +description: Настройка и особенности временной шкалы для отображения сущностей ресурса по датам. +weight: 40 +--- + +Виджет отображает сущности выбранного ресурса на временной шкале. + +## Отображаемые данные + +- «График временной шкалы» — горизонтальная диаграмма, где каждая сущность отображается в виде полосы, показывающей период времени (от даты начала до даты окончания). +- «Информация о сущностях» — при наведении на полосу отображается название сущности, дата начала и дата окончания периода. +- «Сортировка» — сущности отсортированы от самых старых (сверху) к самым новым (снизу). + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Да | Ресурс, для которого отображается временная шкала | — | +| Поле даты начала | Да | Поле, из которого берётся дата начала периода. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | — | +| Поле даты окончания | Да | Поле, из которого берётся дата окончания периода. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | — | + +## Особенности + +Виджет автоматически масштабирует временную шкалу для отображения всех сущностей. +Сущности с некорректными датами (дата начала позже даты окончания) автоматически исключаются из отображения. diff --git a/content/documentation/admin/widgets/generic/_index.md b/content/documentation/admin/widgets/generic/_index.md new file mode 100644 index 00000000..a10e6a99 --- /dev/null +++ b/content/documentation/admin/widgets/generic/_index.md @@ -0,0 +1,5 @@ +--- +title: Other +description: Configuration reference for generic dashboard widgets available in Deckhouse Development Platform. +weight: 140 +--- diff --git a/content/documentation/admin/widgets/generic/_index.ru.md b/content/documentation/admin/widgets/generic/_index.ru.md new file mode 100644 index 00000000..d4a3f0c5 --- /dev/null +++ b/content/documentation/admin/widgets/generic/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Прочее +description: Справочник по настройке универсальных виджетов дашбордов Deckhouse Development Platform. +weight: 140 +--- diff --git a/content/documentation/admin/widgets/generic/api.md b/content/documentation/admin/widgets/generic/api.md new file mode 100644 index 00000000..7804b589 --- /dev/null +++ b/content/documentation/admin/widgets/generic/api.md @@ -0,0 +1,34 @@ +--- +title: API +description: Configure the API widget to display OpenAPI and Protobuf specifications from URLs or GitLab repositories. +weight: 10 +--- + +The widget displays an API specification from a file in a GitLab repository or from a URL in OpenAPI (Swagger) or Protobuf format. For an OpenAPI specification in a YAML or JSON file, the widget displays the Swagger UI. In all other cases, it displays the specification as text. + +## General configuration + +| Name | Required | Description | Possible values | Default | +| ------------------ | -------- | ------------------------------------------------ | ----------------------------------- | ------- | +| Specification type | Yes | Specification type | OpenAPI (Swagger), Protocol Buffers | — | +| Source type | Yes | Source from which the specification file is loaded | URL, GitLab | — | + +## Source type configuration: URL + +| Name | Required | Description | Default | +| ------- | -------- | ------------------------------------------------ | ------- | +| URL | Yes | URL of the specification file | — | +| Headers | No | Headers used to access the specification file | — | + +## Source type configuration: GitLab + +| Name | Required | Description | Default | +| ----------- | -------- | ------------------------------------------------------------- | ------- | +| GitLab URL | Yes | GitLab URL | — | +| Project ID | Yes | ID of the project containing the specification file | — | +| Branch | Yes | Branch containing the specification file | — | +| File path | Yes | Path to the specification file relative to the repository root | — | + +## Authorization + +Authorization is configured in [External services](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/generic/api.ru.md b/content/documentation/admin/widgets/generic/api.ru.md new file mode 100644 index 00000000..e3c7bdd3 --- /dev/null +++ b/content/documentation/admin/widgets/generic/api.ru.md @@ -0,0 +1,34 @@ +--- +title: API +description: Настройка виджета API для отображения спецификаций OpenAPI и Protobuf по URL или из репозитория GitLab. +weight: 10 +--- + +Виджет позволяет вывести спецификацию API из файла в репозитории GitLab или по ссылке в формате OpenAPI (Swagger) или Protobuf. При выводе спецификации OpenAPI из файла в формате YAML или JSON виджет отображает интерфейс Swagger. Во всех остальных случаях виджет отображает спецификацию в виде текста. + +## Общая конфигурация + +| Название | Обязательность | Описание | Возможные значения | Значение по умолчанию | +| ---------------- | -------------- | ------------------------------------------------------------------ | ----------------------------------- | --------------------- | +| Тип спецификации | Да | Тип спецификации | OpenAPI (Swagger), Protocol Buffers | — | +| Тип источника | Да | Тип источника, из которого будет загружаться файл со спецификацией | URL, GitLab | — | + +## Конфигурация типа источника: URL + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------- | -------------- | ---------------------------------------------- | --------------------- | +| URL | Да | Ссылка на файл со спецификацией | — | +| Заголовки | Нет | Заголовки для доступа к файлу со спецификацией | — | + +## Конфигурация типа источника: GitLab + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------ | -------------- | ---------------------------------------------------------------------- | --------------------- | +| GitLab URL | Да | URL GitLab | — | +| ID проекта | Да | Идентификатор проекта, из которого будет браться файл со спецификацией | — | +| Ветка | Да | Ветка, из которой будет браться файл со спецификацией | — | +| Путь к файлу | Да | Путь к файлу со спецификацией относительно корня репозитория | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/generic/docker.md b/content/documentation/admin/widgets/generic/docker.md new file mode 100644 index 00000000..45eff36b --- /dev/null +++ b/content/documentation/admin/widgets/generic/docker.md @@ -0,0 +1,18 @@ +--- +title: Docker +description: Configure the Docker widget to browse container images, tags, and pull commands in a registry. +weight: 70 +--- + +The widget displays available images in a Docker registry. It shows all available tags and the `docker pull` command. Search is supported. + +## Configuration + +| Name | Required | Description | Default | +| ---- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | +| URL | Yes | Docker Registry URL used to retrieve available image data | — | +| Name | No | Name of the repository from which the widget loads data. Example: `repo`. If omitted, all available images are loaded | — | + +## Authorization + +Authorization is configured in [External services](../../external-services/#docker-registry). diff --git a/content/documentation/admin/widgets/generic/docker.ru.md b/content/documentation/admin/widgets/generic/docker.ru.md new file mode 100644 index 00000000..bb9d5823 --- /dev/null +++ b/content/documentation/admin/widgets/generic/docker.ru.md @@ -0,0 +1,18 @@ +--- +title: Docker +description: Настройка виджета Docker для просмотра образов, тегов и команд загрузки в реестре контейнеров. +weight: 70 +--- + +Виджет позволяет отображать данные о доступных образах в Docker Registry. На виджет выводятся все доступные теги и команда `docker pull`. Поддерживается поиск. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL Docker Registry. Используется для получения данных о доступных образах | — | +| Название | Нет | Название репозитория, из которого будут загружаться данные в виджет. Пример: `repo`. Без указания названия, будут получены все доступные образы | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#docker-registry). diff --git a/content/documentation/admin/widgets/generic/event-stats.md b/content/documentation/admin/widgets/generic/event-stats.md new file mode 100644 index 00000000..a9745ab6 --- /dev/null +++ b/content/documentation/admin/widgets/generic/event-stats.md @@ -0,0 +1,47 @@ +--- +title: Event statistics +description: Monitor entity events, Redis streams, and event trends with the Event statistics widget. +weight: 140 +--- + +The widget displays statistics about events involving DDP entities. It contains three tabs: + +1. **Event statistics** — A chart showing the number of events by type over the selected time range, with configurable time grouping. +1. **Top entities** — A table of entities that generated the most events. +1. **Redis events** — A table of Redis event streams. For each stream, it shows: + - The stream name, which you can select to view all events. + - The resource associated with the stream. + - The number of events in the stream. + - Information about the latest event: entity, resource, event type, and time. + +## Query parameters + +| Name | Required | Description | Default | +| ------------ | -------- | -------------------------------------------------------------------------------------- | ------------ | +| Date from | Yes | Start date for selecting events | 3 days ago | +| Date to | Yes | End date for selecting events | Current date | +| Interval | No | Chart grouping interval: seconds, minutes, hours, days, weeks, months, or years | Hour | +| Interval step | No | Number of interval units used for grouping | 1 | +| Top entities | No | Number of entities with the most events to display in the table | 10 | + +## Event types + +The widget supports the following event types: + +- `ENTITY_CREATED` — Entity created. +- `ENTITY_UPDATED` — Entity updated. +- `ENTITY_DELETED` — Entity deleted. + +### Behavior + +- The chart shows events over the selected time range with configurable time grouping. The default grouping is by hour. +- The table displays all events for each entity without date filtering. +- Deleted entities are shown using the names extracted from their event specifications. +- The **Redis events** tab lets you monitor events stored in Redis Streams: + - Each stream shows its event count and latest event. + - Selecting a stream name opens a dialog containing all events from that stream. + - Streams are automatically associated with resources by the UUID in the stream name. + - The stream view shows the latest 1,000 events, newest first. Older events are not displayed. +- Each table row contains information about the latest event for the entity. +- A detailed change history is available for each entity. +- Events for deleted resources are not displayed because they are removed from the database when the resource is deleted. diff --git a/content/documentation/admin/widgets/generic/event-stats.ru.md b/content/documentation/admin/widgets/generic/event-stats.ru.md new file mode 100644 index 00000000..2c074c46 --- /dev/null +++ b/content/documentation/admin/widgets/generic/event-stats.ru.md @@ -0,0 +1,47 @@ +--- +title: Статистика событий +description: Мониторинг событий сущностей, потоков Redis и динамики событий в виджете статистики. +weight: 140 +--- + +Виджет отображает статистику событий, происходящих с сущностями в DDP. Виджет содержит три таба: + +1. «Статистика событий» — график, показывающий количество событий по типам за выбранный временной период с настраиваемой группировкой по времени. +1. «Топ сущностей» — таблица с сущностями, для которых было сгенерировано максимальное количество событий. +1. «События в Redis» — таблица со стримами событий из Redis, показывающая для каждого стрима: + - название стрима (кликабельное для просмотра всех событий); + - ресурс, к которому относится стрим; + - количество событий в стриме; + - информацию о последнем событии (сущность, ресурс, тип события, время). + +## Параметры запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------- | -------------- | ------------------------------------------------------------------------------------------ | --------------------- | +| Дата от | Да | Начальная дата для выборки событий | 3 дня назад | +| Дата до | Да | Конечная дата для выборки событий | текущая дата | +| Интервал | Нет | Интервал группировки событий на графике (секунды, минуты, часы, дни, недели, месяцы, годы) | час | +| Шаг интервала | Нет | Количество единиц интервала для группировки | 1 | +| Топ сущностей | Нет | Количество сущностей с максимальным количеством событий для отображения в таблице | 10 | + +## Типы событий + +Виджет поддерживает следующие типы событий: + +- `ENTITY_CREATED` — создание сущности. +- `ENTITY_UPDATED` — обновление сущности. +- `ENTITY_DELETED` — удаление сущности. + +### Особенности + +- График показывает события за выбранный временной период с настраиваемой группировкой по времени (по умолчанию — по часам). +- Таблица отображает все события для каждой сущности (без фильтрации по дате). +- Для удалённых сущностей отображается их название, извлечённое из спецификации события. +- Вкладка «События в Redis» позволяет отслеживать события, хранящиеся в Redis Streams: + - Для каждого стрима отображается количество событий и информация о последнем событии. + - При клике на название стрима открывается диалог со всеми событиями из этого стрима. + - Стримы автоматически привязываются к ресурсам по UUID, указанному в названии стрима. + - При просмотре событий из стрима отображаются последние 1000 событий (новые первыми). Если в стриме больше 1000 событий, более старые события не отображаются. +- Каждая строка в таблице содержит информацию о последнем событии для сущности. +- Доступен просмотр детальной истории изменений для каждой сущности. +- События для удалённых ресурсов не отображаются (удаляются из БД при удалении ресурса). diff --git a/content/documentation/admin/widgets/generic/graph.md b/content/documentation/admin/widgets/generic/graph.md new file mode 100644 index 00000000..473e0901 --- /dev/null +++ b/content/documentation/admin/widgets/generic/graph.md @@ -0,0 +1,83 @@ +--- +title: Graph +description: Configure charts that aggregate and visualize Deckhouse Development Platform object data. +weight: 130 +--- + +The widget displays information about DDP objects using one of the following chart types: + +* Bar chart. +* Doughnut chart. +* Pie chart. +* Polar area chart. +* Radar chart. + +## Configuration + +| Name | Required | Description | Default | +| ---------------------- | -------- | ----------------------------------------------------------------------------------- | ------- | +| Chart type | Yes | Chart visualization type | — | +| Table name | Yes | Database table containing the records to visualize | — | +| Field name | Yes | Field used to aggregate records | — | +| Filters | No | Fields and values used to filter the retrieved records | — | +| Aggregation type | Yes | Method used to group the retrieved records | — | +| Aggregation parameters | No | Time range and grouping step used when aggregating records by date | — | + +When configuring the widget, account for differences between database field names and object specification field names. When structures are stored in the database, camelCase names from object specifications are converted to snake_case. For example: + +* Specify the `createdAt` field as `created_at` in the widget configuration. +* Specify the `resourceUuid` field as `resource_uuid` in the widget configuration. + +Nested values are supported. Separate nesting levels with a period. For example, configure the widget as follows to aggregate entities by status: + +| Table name | Field name | +| ---------- | --------------- | +| `entities` | `health.status` | + +## Aggregation types + +### Date + +Chart data is sorted and grouped by the selected time intervals. + +You can configure the following aggregation parameters: + +- **Step unit** — For example, seconds, minutes, hours, or days. +- **Units per step** — For example, 5 minutes, 2 hours, or 1 day. + +These parameters control the time-based granularity of the displayed data. + +### Value + +Chart data is sorted by value. For each unique value in the source data: + +- The number of occurrences is counted. +- The chart displays a value-count pair. + +This aggregation shows the distribution and frequency of values. + +### Interval ranges + +The **Interval ranges** aggregation divides values into configured numeric ranges. Use it to build histograms and analyze data distributions. + +Configure intervals in one of two modes: + +1. **Automatic division by interval count**. + + Specify the number of intervals into which the available data is divided. Intervals are calculated automatically and distributed evenly from the minimum to the maximum value. + +1. **Manual interval boundaries**. + + Specify an array of numeric interval boundaries. For example: `0, 10, 20, 50`. + + The numbers are sorted in ascending order and form these intervals: `[0, 10)`, `[10, 20)`, `[20, 50]`. + +Specify at least one of these aggregation parameters: + +- `Count` — Number of intervals. +- `Boundaries` — Interval boundaries. + +Examples: + +- `Count = 5` — Creates five equal intervals based on the data. +- `Boundaries = 100, 0, 50` — Sorts the boundaries to `[0, 50, 100]` and creates the intervals `[0, 50)` and `[50, 100]`. diff --git a/content/documentation/admin/widgets/generic/graph.ru.md b/content/documentation/admin/widgets/generic/graph.ru.md new file mode 100644 index 00000000..565d02fc --- /dev/null +++ b/content/documentation/admin/widgets/generic/graph.ru.md @@ -0,0 +1,90 @@ +--- +title: График +description: Настройка графиков для агрегации и визуализации данных объектов Deckhouse Development Platform. +weight: 130 +--- + +Виджет позволяет выводить информацию об объектах DDP в виде одного из следующих типов графиков: + +* Столбчатая диаграмма; +* Кольцевая диаграмма; +* Круговая диаграмма; +* Полярная диаграмма; +* Радарная диаграмма. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------- | -------------- | -------------------------------------------------------------------------------- | --------------------- | +| Тип графика | Да | Тип визуализации графика | — | +| Название таблицы | Да | Название таблицы в базе данных, из которой будут браться записи для визуализации | — | +| Название поля | Да | Название поля, по которому будет происходить агрегация записей | — | +| Фильтры | Нет | Поля, по которым будут фильтроваться полученные записи, и их значения | — | +| Тип агрегации | Да | Принцип, по которому будут группироваться полученные записи | — | +| Параметры агрегации | Нет | Выбор временного периода и шага группировки при агрегации записей по дате | — | + +При настройке виджета учитывайте, что названия полей в базе данных могут отличаться от названий полей в спецификации объектов. Общий принцип таков: формат camelCase в спецификации объектов при сохранении структур в базу данных преобразуется в snake_case. Например: + +* Укажите поле `createdAt` в конфигурации виджета как `created_at`. +* Укажите поле `resourceUuid` в конфигурации виджета как `resource_uuid`. + +Доступно обращение к вложенным значениям. В таком случае разделителем для вложенности служит символ точки. Например, чтобы выполнить агрегацию по статусу сущностей, настройте виджет следующим образом: + +| Название таблицы | Название поля | +| ---------------- | --------------- | +| `entities` | `health.status` | + +## Типы агрегации + +### Дата + +Данные на графике будут отсортированы и сгруппированы по выбранным временным интервалам. + +В параметрах агрегации можно задать параметры: + +- «Единица измерения шага» — например: секунды, минуты, часы, дни и т. д. +- «Количество единиц в одном шаге» — например: 5 минут, 2 часа, 1 день и т. п. + +Это позволяет управлять детализацией отображения данных во времени и адаптировать график под нужный масштаб анализа. + +### Значение + +Данные на графике отображаются в отсортированном порядке — по значениям. +Для каждого уникального значения в исходном наборе данных: + +- Выполняется подсчёт количества вхождений. +- На графике отображается пара: значение — количество. + +Это позволяет быстро увидеть распределение и частоту повторения различных значений. + +### Разбивка по интервалам + +Тип агрегации «Разбивка по интервалам» позволяет гибко настроить отображение данных на графике, разделяя значения по заданным числовым диапазонам (интервалам). Это удобно для построения гистограмм и анализа распределения данных. + +Доступны два режима настройки интервалов: + +1. «Автоматическая разбивка по количеству интервалов». + + Укажите количество интервалов, на которые нужно разделить доступные данные. + Интервалы будут рассчитаны автоматически — равномерно от минимального до максимального значения. + +1. «Ручное задание границ интервалов». + + Укажите массив числовых границ интервалов. + Например: `0, 10, 20, 50` + + В этом случае: + + - Числа будут автоматически отсортированы по возрастанию. + - Интервалы сформируются на основе отсортированных значений: + `[0, 10)`, `[10, 20)`, `[20, 50]` + +Укажите хотя бы один из двух параметров агрегации: + +- `Количество` — количество интервалов; +- `Границы` — границы интервалов. + +Примеры: + +- `Количество = 5` — построится 5 равных интервалов на основании данных. +- `Границы = 100, 0, 50` — после сортировки: `[0, 50, 100]`, график будет построен по интервалам `[0, 50)`, `[50, 100]`. diff --git a/content/documentation/admin/widgets/generic/helm-releases.md b/content/documentation/admin/widgets/generic/helm-releases.md new file mode 100644 index 00000000..8b1dddd1 --- /dev/null +++ b/content/documentation/admin/widgets/generic/helm-releases.md @@ -0,0 +1,24 @@ +--- +title: Helm releases +description: View Helm releases, manifests, values, and rollback history in Kubernetes. +weight: 20 +--- + +The widget displays data about Helm releases in Kubernetes and lets you roll back to previous versions. + +The widget displays: + +* **Helm release list** — Information about current releases created with Helm in the specified Kubernetes namespace. +* **Release manifests** — Manifests associated with Helm releases in the specified Kubernetes namespace, including YAML files that define resource configuration and state. +* **Values** — Variables used to deploy Helm releases. + +## Configuration + +| Name | Required | Description | Default | +| --------- | -------- | ------------------------------------------------------------------------------------ | ------- | +| Namespace | No | Namespace from which the widget loads data. Example: `default` | — | +| Release | No | Name of the release from which the widget loads data. Example: `my-release` | — | + +## Authorization + +Authorization is configured in [External services](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/generic/helm-releases.ru.md b/content/documentation/admin/widgets/generic/helm-releases.ru.md new file mode 100644 index 00000000..457ef42b --- /dev/null +++ b/content/documentation/admin/widgets/generic/helm-releases.ru.md @@ -0,0 +1,24 @@ +--- +title: Helm. Релизы +description: Просмотр релизов Helm, манифестов, значений и истории откатов в Kubernetes. +weight: 20 +--- + +Виджет позволяет отображать данные о Helm-релизах в Kubernetes и выполнять откат на предыдущие версии. + +Данные, отображаемые на виджете: + +* «Список релизов Helm» — информация о текущих релизах, созданных с помощью Helm в указанном неймспейсе Kubernetes. +* «Манифесты релизов» — манифесты, связанные с Helm-релизами в указанном неймспейсе Kubernetes. Это включает в себя файлы YAML, которые определяют конфигурацию и состояние ресурсов. +* «Values» — переменные, которые использовались для развёртывания Helm-релизов. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------- | -------------- | ------------------------------------------------------------------------------------ | --------------------- | +| Namespace | Нет | Неймспейс, из которого будут загружаться данные в виджет. Пример: `default` | — | +| Релиз | Нет | Название релиза, из которого будут загружаться данные в виджет. Пример: `my-release` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/generic/iframe.md b/content/documentation/admin/widgets/generic/iframe.md new file mode 100644 index 00000000..e08a05bd --- /dev/null +++ b/content/documentation/admin/widgets/generic/iframe.md @@ -0,0 +1,17 @@ +--- +title: Iframe +description: Configure an Iframe widget that displays content from an external URL. +weight: 120 +--- + +{{< alert level="warning" >}} +The Iframe widget works only when `allowIframe: true` is enabled in the security headers configuration (`security.headers.csp.allowIframe`). This option is disabled by default, so the widget does not display content until the configuration is changed. +{{< /alert >}} + +The widget displays data from an external source. + +## Configuration + +| Name | Required | Description | Default | +| ---- | -------- | --------------------------------------------------- | ------- | +| URL | Yes | External source URL used to display data in the widget | — | diff --git a/content/documentation/admin/widgets/generic/iframe.ru.md b/content/documentation/admin/widgets/generic/iframe.ru.md new file mode 100644 index 00000000..d487624b --- /dev/null +++ b/content/documentation/admin/widgets/generic/iframe.ru.md @@ -0,0 +1,17 @@ +--- +title: Iframe +description: Настройка виджета Iframe для отображения содержимого по внешнему URL. +weight: 120 +--- + +{{< alert level="warning" >}} +Виджет Iframe работает только при включённой опции `allowIframe: true` в конфигурации заголовков безопасности (`security.headers.csp.allowIframe`). По умолчанию эта опция отключена, поэтому виджет не будет отображать контент до изменения конфигурации. +{{< /alert >}} + +Виджет позволяет отображать данные из внешнего источника. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------- | -------------- | --------------------------------------------------------------------- | --------------------- | +| URL | Да | URL внешнего источника. Используется для отображения данных в виджете | — | diff --git a/content/documentation/admin/widgets/generic/jenkins.md b/content/documentation/admin/widgets/generic/jenkins.md new file mode 100644 index 00000000..27a2fab5 --- /dev/null +++ b/content/documentation/admin/widgets/generic/jenkins.md @@ -0,0 +1,60 @@ +--- +title: Jenkins +description: Monitor Jenkins pipelines and manage regular or multibranch builds from a dashboard. +weight: 80 +--- + +The widget displays Jenkins pipeline data and lets you manage builds. + +## Configuration + +| Name | Required | Description | Default | +| ---- | -------- | ------------------------------------------------------------------------------------ | ------- | +| URL | Yes | Jenkins URL used to retrieve data | — | +| Name | Yes | Jenkins pipeline name. Nested paths are supported: `folder1/folder2/jobName` | — | + +## Displayed data + +The widget automatically detects the pipeline type and displays the appropriate view. + +### Regular pipelines + +For regular pipelines, the widget displays: + +* **Build list** — A table of all pipeline builds with their number, status, duration, execution time, and user. +* **Latest build** — Information about the latest completed build. +* **Latest successful build** — Information about the latest successful build. +* **Latest failed build** — Information about the latest failed build. + +### Multibranch pipelines + +For multibranch pipelines, the widget displays: + +* **Branch list** — A table of all branches with their status, build count, and latest build. +* All information described for regular pipelines, grouped by branch. + +## Additional widget features + +The widget supports the following actions. + +### Regular pipelines + +* **Start build** — Starts a new build. If the build has parameters, the widget opens a dialog for entering: + * String parameters. + * Passwords. + * List selections. + * Boolean values. +* **Cancel build** — Cancels a running build. +* **Rebuild** — Runs the latest build again. +* **View logs** — Displays build execution logs. + +### Multibranch pipelines + +* **Start branch build** — Starts a new build for a specific branch. If the build has parameters, the widget opens a dialog for entering them. +* **Get branch builds** — Loads the build list for a specific branch. +* **Scan multibranch** — Starts a multibranch pipeline scan to discover new branches. +* **View logs** — Displays build execution logs. + +## Authorization + +Authorization is configured in [External services](../../external-services/#jenkins). diff --git a/content/documentation/admin/widgets/generic/jenkins.ru.md b/content/documentation/admin/widgets/generic/jenkins.ru.md new file mode 100644 index 00000000..ff0dba4f --- /dev/null +++ b/content/documentation/admin/widgets/generic/jenkins.ru.md @@ -0,0 +1,60 @@ +--- +title: Jenkins +description: Мониторинг пайплайнов Jenkins и управление обычными и multibranch-сборками на дашборде. +weight: 80 +--- + +Виджет отображает данные о пайплайнах в Jenkins и позволяет управлять сборками. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------- | -------------- | ----------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL Jenkins. Используется для получения данных из Jenkins | — | +| Название | Да | Название пайплайна в Jenkins. Поддерживается вложенность: `folder1/folder2/jobName` | — | + +## Отображаемые данные + +Виджет автоматически определяет тип пайплайна и отображает соответствующее представление. + +### Обычные пайплайны + +Для обычных пайплайнов виджет отображает: + +* «Список сборок» — таблица со всеми сборками пайплайна с информацией о номере, статусе, длительности, времени выполнения и пользователе. +* «Последняя сборка» — информация о последней выполненной сборке. +* «Последняя успешная сборка» — информация о последней успешной сборке. +* «Последняя неудачная сборка» — информация о последней неудачной сборке. + +### Multibranch пайплайны + +Для multibranch пайплайнов виджет отображает: + +* «Список веток» — таблица со всеми ветками с информацией о статусе, количестве сборок и последней сборке для каждой ветки. +* Всю информацию, описанную в разделе «обычные пайплайны», в разрезе каждой ветки. + +## Дополнительные возможности виджета + +Виджет позволяет выполнять следующие действия: + +### Для обычных пайплайнов + +* «Запустить сборку» — запуск новой сборки. Если у сборки есть параметры, отображается диалог для их ввода: + * Строковые параметры; + * Пароли; + * Выбор из списка; + * Булевые значения. +* «Отменить сборку» — отмена выполняющейся сборки. +* «Повторить сборку» — повторный запуск последней сборки. +* «Просмотр логов» — просмотр логов выполнения сборки. + +### Для multibranch пайплайнов + +* «Запустить сборку ветки» — запуск новой сборки для конкретной ветки. Если у сборки есть параметры, отображается диалог для их ввода. +* «Получить сборки ветки» — загрузка списка сборок для конкретной ветки. +* «Сканировать multibranch» — запуск сканирования multibranch пайплайна для обнаружения новых веток. +* «Просмотр логов» — просмотр логов выполнения сборки. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#jenkins). diff --git a/content/documentation/admin/widgets/generic/jira.md b/content/documentation/admin/widgets/generic/jira.md new file mode 100644 index 00000000..4577bb69 --- /dev/null +++ b/content/documentation/admin/widgets/generic/jira.md @@ -0,0 +1,31 @@ +--- +title: Jira +description: Display and filter Jira issues with configurable JQL queries. +weight: 110 +--- + +The widget displays Jira issues based on a JQL query. + +## Configuration + +| Name | Required | Description | Default | +| ---- | -------- | --------------------------------------------------------------------------- | ------- | +| URL | Yes | Jira URL used to retrieve data | — | +| JQL | Yes | JQL query used to filter issues. Example: `project = PROJ AND status = Open` | — | + +## Query parameters + +| Name | Required | Description | Default | +| --------------- | -------- | ------------------------------------------------------------------------ | ------------------ | +| JQL | No | JQL query used to filter issues. If omitted, the configured JQL is used | From configuration | +| Maximum results | No | Maximum number of issues to display, from 1 to 1000 | 50 | + +## Additional widget features + +* **View description** — Opens a dialog with the full issue description. +* **Open in Jira** — Opens the issue in a new tab when you select its key. +* **Dynamic filtering** — Lets you change the JQL query and maximum number of results directly in the widget without changing its configuration. + +## Authorization + +Authorization is configured in [External services](../../external-services/#jira). diff --git a/content/documentation/admin/widgets/generic/jira.ru.md b/content/documentation/admin/widgets/generic/jira.ru.md new file mode 100644 index 00000000..e05b1d55 --- /dev/null +++ b/content/documentation/admin/widgets/generic/jira.ru.md @@ -0,0 +1,31 @@ +--- +title: Jira +description: Отображение и фильтрация задач Jira с помощью настраиваемых JQL-запросов. +weight: 110 +--- + +Виджет позволяет отображать задачи из Jira на основе JQL-запроса. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------- | -------------- | --------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL Jira. Используется для получения данных из Jira | — | +| JQL | Да | JQL-запрос для фильтрации задач. Пример: `project = PROJ AND status = Open` | — | + +## Параметры запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------- | -------------- | --------------------------------------------------------------------------------- | --------------------- | +| JQL | Нет | JQL-запрос для фильтрации задач. Если не указан, используется JQL из конфигурации | Из конфигурации | +| Максимум результатов | Нет | Максимальное количество задач для отображения (от 1 до 1000) | 50 | + +## Дополнительные возможности виджета + +* «Просмотр описания» — при клике на кнопку «Просмотр описания» открывается диалоговое окно с полным описанием задачи. +* «Переход в Jira» — клик по ключу задачи открывает задачу в Jira в новой вкладке. +* «Динамическая фильтрация» — возможность изменить JQL-запрос и максимальное количество результатов прямо в виджете без изменения конфигурации. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#jira). diff --git a/content/documentation/admin/widgets/generic/markdown.md b/content/documentation/admin/widgets/generic/markdown.md new file mode 100644 index 00000000..94eb6a1c --- /dev/null +++ b/content/documentation/admin/widgets/generic/markdown.md @@ -0,0 +1,13 @@ +--- +title: Markdown +description: Display formatted Markdown content in a dashboard widget. +weight: 200 +--- + +The widget displays text written in Markdown. + +## Configuration + +| Name | Required | Description | Default | +| -------- | -------- | ------------------------------------------------- | ------- | +| Markdown | Yes | Markdown text rendered in the widget | — | diff --git a/content/documentation/admin/widgets/generic/markdown.ru.md b/content/documentation/admin/widgets/generic/markdown.ru.md new file mode 100644 index 00000000..5dbf8b45 --- /dev/null +++ b/content/documentation/admin/widgets/generic/markdown.ru.md @@ -0,0 +1,13 @@ +--- +title: Markdown +description: Отображение форматированного содержимого Markdown в виджете дашборда. +weight: 200 +--- + +Виджет обеспечивает отображение текста, написанного в формате Markdown. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------- | -------------- | ------------------------------------------------------------------------- | --------------------- | +| Markdown | Да | Текст в формате Markdown. Отображается в виджете в отформатированном виде | — | diff --git a/content/documentation/admin/widgets/generic/nexus.md b/content/documentation/admin/widgets/generic/nexus.md new file mode 100644 index 00000000..48d5b74e --- /dev/null +++ b/content/documentation/admin/widgets/generic/nexus.md @@ -0,0 +1,19 @@ +--- +title: Nexus +description: Browse artifacts from a configured Nexus repository. +weight: 90 +--- + +The widget displays a list of artifacts in a Nexus repository. + +## Configuration + +| Name | Required | Description | Default | +| ---------- | -------- | ------------------------------------------------------------------------------------- | ------- | +| URL | Yes | Nexus API URL used to retrieve data | — | +| Repository | Yes | Name of the repository whose data is displayed in the widget. Example: `my-repo` | — | +| Name | No | Name of the artifact whose data is displayed in the widget | — | + +## Authorization + +Authorization is configured in [External services](../../external-services/#nexus). diff --git a/content/documentation/admin/widgets/generic/nexus.ru.md b/content/documentation/admin/widgets/generic/nexus.ru.md new file mode 100644 index 00000000..c79d5134 --- /dev/null +++ b/content/documentation/admin/widgets/generic/nexus.ru.md @@ -0,0 +1,19 @@ +--- +title: Nexus +description: Просмотр артефактов из настроенного репозитория Nexus. +weight: 90 +--- + +Виджет позволяет выводить список артефактов в репозитории Nexus. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ---------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL Nexus API. Используется для получения данных из Nexus | — | +| Repository | Да | Название репозитория, данные из которого будут отображаться в виджете. Пример: `my-repo` | — | +| Name | Нет | Название артефакта, данные о котором будут отображаться в виджете | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#nexus). diff --git a/content/documentation/admin/widgets/generic/numeric-value.md b/content/documentation/admin/widgets/generic/numeric-value.md new file mode 100644 index 00000000..bb7a12e2 --- /dev/null +++ b/content/documentation/admin/widgets/generic/numeric-value.md @@ -0,0 +1,14 @@ +--- +title: Numeric value +description: Display a numeric value derived from static data or a template. +weight: 170 +--- + +The widget displays a specified numeric value. + +## Configuration + +| Name | Required | Description | Default | +| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| Resource | No | Resource from which required values are extracted when processing the template | — | +| Numeric value | No | Value displayed in the widget. Templating is supported. Without templating: `100`. With templating: `{{ .entity.properties.id }}` | — | diff --git a/content/documentation/admin/widgets/generic/numeric-value.ru.md b/content/documentation/admin/widgets/generic/numeric-value.ru.md new file mode 100644 index 00000000..2c1f18a5 --- /dev/null +++ b/content/documentation/admin/widgets/generic/numeric-value.ru.md @@ -0,0 +1,14 @@ +--- +title: Числовое значение +description: Отображение числового значения из статических данных или шаблона. +weight: 170 +--- + +Виджет позволяет отображать заданное числовое значение. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Нет | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | — | +| Числовое значение | Нет | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.properties.id }}` | — | diff --git a/content/documentation/admin/widgets/generic/opensearch.md b/content/documentation/admin/widgets/generic/opensearch.md new file mode 100644 index 00000000..e1f8c3e2 --- /dev/null +++ b/content/documentation/admin/widgets/generic/opensearch.md @@ -0,0 +1,20 @@ +--- +title: OpenSearch +description: Search and inspect records from an OpenSearch index or index pattern. +weight: 40 +--- + +The OpenSearch index widget displays data from a specific index or index pattern in the platform. By default, data is sorted from newest to oldest. Full-text search is available to filter the displayed data. Each record (table row) can be displayed as key-value pairs or as JSON. When an index pattern is specified, the widget provides a link to the Discover page in OpenSearch Dashboards. + +## Configuration + +| Name | Required | Description | Default | +| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| API URL | Yes | OpenSearch API URL used to retrieve data | — | +| Dashboards URL | Yes | OpenSearch Dashboards URL used to generate a link for viewing data directly in OpenSearch | — | +| Index pattern | Yes | Index pattern from which the widget loads data. May contain `*`. Examples: `security-auditlog`, `security-auditlog-*` | — | +| Timestamp field | No | Name of the timestamp field. Its value is displayed in a separate column in the data table | `@timestamp` | + +## Authorization + +Authorization is configured in [External services](../../external-services/#opensearch). diff --git a/content/documentation/admin/widgets/generic/opensearch.ru.md b/content/documentation/admin/widgets/generic/opensearch.ru.md new file mode 100644 index 00000000..18e2c962 --- /dev/null +++ b/content/documentation/admin/widgets/generic/opensearch.ru.md @@ -0,0 +1,20 @@ +--- +title: OpenSearch +description: Поиск и просмотр записей из индекса или шаблона индекса OpenSearch. +weight: 40 +--- + +Виджет индекса OpenSearch позволяет отображать данные из заданного индекса или шаблона индекса. По умолчанию данные сортируются от новых к старым. Для фильтрации доступен полнотекстовый поиск. Каждую запись в таблице можно просмотреть в формате «ключ — значение» или JSON. Если указан шаблон индекса, виджет отображает ссылку на страницу Discover в OpenSearch Dashboards. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------- | +| URL API | Да | URL API OpenSearch для получения данных | — | +| URL Dashboards | Да | URL OpenSearch Dashboards для создания ссылки на данные в OpenSearch | — | +| Шаблон индекса | Да | Шаблон индекса, из которого виджет загружает данные. Может содержать `*`. Примеры: `security-auditlog`, `security-auditlog-*` | — | +| Поле временной метки | Нет | Название поля с временной меткой. Значение отображается в отдельном столбце таблицы | `@timestamp` | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#opensearch). diff --git a/content/documentation/admin/widgets/generic/percent-value.md b/content/documentation/admin/widgets/generic/percent-value.md new file mode 100644 index 00000000..4337e3ec --- /dev/null +++ b/content/documentation/admin/widgets/generic/percent-value.md @@ -0,0 +1,14 @@ +--- +title: Percentage value +description: Display a percentage value derived from static data or a template. +weight: 180 +--- + +The widget displays a specified percentage value. + +## Configuration + +| Name | Required | Description | Default | +| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| Resource | No | Resource from which required values are extracted when processing the template | — | +| Percentage value | No | Value displayed in the widget. Templating is supported. Without templating: `100`. With templating: `{{ .entity.properties.id }}` | — | diff --git a/content/documentation/admin/widgets/generic/percent-value.ru.md b/content/documentation/admin/widgets/generic/percent-value.ru.md new file mode 100644 index 00000000..43eca626 --- /dev/null +++ b/content/documentation/admin/widgets/generic/percent-value.ru.md @@ -0,0 +1,14 @@ +--- +title: Процентное значение +description: Отображение процентного значения из статических данных или шаблона. +weight: 180 +--- + +Виджет позволяет отображать заданное процентное значение. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Ресурс | Нет | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | — | +| Процентное значение | Нет | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.properties.id }}` | — | diff --git a/content/documentation/admin/widgets/generic/repository-browser.md b/content/documentation/admin/widgets/generic/repository-browser.md new file mode 100644 index 00000000..7b263dbc --- /dev/null +++ b/content/documentation/admin/widgets/generic/repository-browser.md @@ -0,0 +1,44 @@ +--- +title: Repository browser +description: Browse files and directories from GitLab, Bitbucket, or GitHub repositories. +weight: 190 +--- + +The widget displays the structure and contents of files in GitLab, Bitbucket, and GitHub repositories. + +## Configuration + +| Name | Required | Description | Default | +| ------------ | -------- | -------------------------------------------------------------- | ------- | +| Provider | Yes | Service hosting the repository: GitLab, GitHub, or Bitbucket | — | +| Branch / Tag | No | Branch name, tag, or commit SHA | `main` | +| Path | No | Directory path in the repository. Leave empty for the root | — | +| Recursive | No | Retrieve files recursively from subdirectories | `false` | + +## GitLab configuration + +| Name | Required | Description | Default | +| ---------- | -------- | ---------------------------------------- | ------- | +| Project ID | Yes | GitLab project ID, for example, `12345` | — | + +## Bitbucket configuration + +| Name | Required | Description | Example | Default | +| ------------- | -------- | -------------------------------------------------------- | ------- | ------- | +| Project key | Yes | Bitbucket project key, for example, `MYPROJ` | `MYPROJ` | — | +| Repository ID | Yes | Bitbucket repository ID, for example, `my-repo` | `my-repo` | — | + +## GitHub configuration + +| Name | Required | Description | Default | +| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | ------- | +| Repository owner | Yes | Repository owner: an organization or user. For `https://github.com/example/my-repo`, specify `example` | — | +| Repository | Yes | Repository name without `.git`. For `https://github.com/example/my-repo`, specify `my-repo` | — | + +## Authorization + +Configure authorization separately for each provider: + +* [GitLab](../../external-services/#gitlab). +* [Bitbucket](../../external-services/#bitbucket). +* [GitHub](../../external-services/#github). diff --git a/content/documentation/admin/widgets/generic/repository-browser.ru.md b/content/documentation/admin/widgets/generic/repository-browser.ru.md new file mode 100644 index 00000000..e050cd40 --- /dev/null +++ b/content/documentation/admin/widgets/generic/repository-browser.ru.md @@ -0,0 +1,44 @@ +--- +title: Просмотр репозитория +description: Просмотр файлов и директорий в репозиториях GitLab, Bitbucket и GitHub. +weight: 190 +--- + +Виджет позволяет просматривать структуру и содержимое файлов в репозитории. Поддерживаются репозитории GitLab, Bitbucket и GitHub. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------- | -------------- | ------------------------------------------------------------------ | --------------------- | +| Провайдер | Да | Сервис, в котором размещён репозиторий (GitLab, GitHub, Bitbucket) | — | +| Ветка / Тег | Нет | Название ветки, тег или SHA коммита (по умолчанию: `main`) | `main` | +| Путь | Нет | Путь к директории в репозитории (оставьте пустым для корня) | — | +| Рекурсивно | Нет | Получать файлы рекурсивно из поддиректорий | `false` | + +## Конфигурация для GitLab + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------- | --------------------- | +| ID проекта | Да | ID проекта в GitLab (например, `12345`). | — | + +## Конфигурация для Bitbucket + +| Название | Обязательность | Описание | Пример | Значение по умолчанию | +| ------------------------- | -------------- | --------------------------------------------------------- | ------- | --------------------- | +| Ключ проекта | Да | Ключ проекта в Bitbucket (например, `MYPROJ`) | `MYPROJ` | — | +| Идентификатор репозитория | Да | Идентификатор репозитория в Bitbucket (например, `my-repo`) | `my-repo` | — | + +## Конфигурация для GitHub + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Владелец репозитория | Да | Владелец репозитория (организация или пользователь). Пример: для `https://github.com/example/my-repo` укажите `example` | — | +| Репозиторий | Да | Название репозитория без `.git`. Пример: для `https://github.com/example/my-repo` укажите `my-repo` | — | + +## Авторизация + +Настройте авторизацию отдельно для каждого провайдера: + +* [GitLab](../../external-services/#gitlab). +* [Bitbucket](../../external-services/#bitbucket). +* [GitHub](../../external-services/#github). diff --git a/content/documentation/admin/widgets/generic/s3.md b/content/documentation/admin/widgets/generic/s3.md new file mode 100644 index 00000000..09e0f7d1 --- /dev/null +++ b/content/documentation/admin/widgets/generic/s3.md @@ -0,0 +1,79 @@ +--- +title: S3 +description: Browse, search, inspect, and download objects from S3-compatible storage. +weight: 100 +--- + +The widget lets you browse S3-compatible object storage, including Amazon S3, Yandex Object Storage, and MinIO. + +For each object, you can: + +* View objects in a bucket with their size, modification date, and storage class. +* Search for objects by prefix (path). +* Download files from the bucket. +* View object metadata, including size, content type, custom metadata, and cache settings. +* Navigate bucket folders. + +## Using credential templates + +You can use credential templating: + +* `{{ .credentials.accessKeyId }}` — Inserts the Access Key ID from the credentials. +* `{{ .credentials.secretAccessKey }}` — Inserts the Secret Access Key from the credentials. + +{{< alert level="info" >}} +The connected account's permissions determine what information is available in the widget. +{{< /alert >}} + +## Configuration + +| Name | Required | Description | Default | +| ------------------- | -------- | ------------------------------------------------------------------------------------ | ------- | +| Bucket name | Yes | Name of the S3 bucket to browse | — | +| Endpoint | Yes | S3-compatible storage endpoint URL, for example, `https://storage.yandexcloud.net` | — | +| Region | Yes | Region containing the bucket | — | +| Access Key ID | Yes | Access key identifier used for authentication | — | +| Secret Access Key | Yes | Secret access key used for authentication | — | +| Prefix | No | Prefix (path) used to filter objects on initial load | — | +| Maximum objects | No | Maximum number of objects displayed per request | 100 | + +## Additional widget features + +### Object search + +The widget searches for objects by prefix (path). The object list updates to match the specified prefix. + +{{< alert level="info" >}} +Search matches only characters at the beginning of an object name. Searching by characters in the middle of a name is not supported. +{{< /alert >}} + +If the widget configuration specifies an initial prefix, searches are restricted to that prefix. Files with other prefixes cannot be loaded or displayed. + +### Downloading files + +The widget lets you download files from a bucket directly in the browser. A download button is available for each file. + +### Object details + +Select the document icon for an object to view: + +* Basic properties: key, size, modification date, storage class, content type, and ETag. +* Content information: encoding, language, and disposition. +* Cache settings: Cache-Control and expiration. +* Security: server-side encryption. +* Custom metadata. + +### Loading more objects + +For buckets containing many objects, use **Load more** to load objects incrementally without reducing performance. + +## Authentication + +The widget requires credentials with access to the S3 bucket. It supports: + +* Access Key ID and Secret Access Key. +* Different S3-compatible providers through endpoint configuration. + +{{< alert level="info" >}} +Unlike other widgets, the S3 widget cannot obtain credentials from external services. Specify all authentication parameters directly in the widget configuration. +{{< /alert >}} diff --git a/content/documentation/admin/widgets/generic/s3.ru.md b/content/documentation/admin/widgets/generic/s3.ru.md new file mode 100644 index 00000000..7a979c7d --- /dev/null +++ b/content/documentation/admin/widgets/generic/s3.ru.md @@ -0,0 +1,79 @@ +--- +title: S3 +description: Просмотр, поиск и загрузка объектов из S3-совместимого хранилища. +weight: 100 +--- + +Виджет позволяет просматривать содержимое S3-совместимых хранилищ объектов, таких как Amazon S3, Yandex Object Storage, MinIO и другие. + +Для каждого объекта доступно: + +* Просмотр списка объектов в S3-бакете с информацией о размере, дате изменения и классе хранения. +* Поиск объектов по префиксу (пути). +* Загрузка файлов из S3-бакета. +* Просмотр детальной метаинформации объектов (размер, тип контента, метаданные, настройки кеширования и т. д.). +* Навигация по каталогам S3-бакета. + +## Использование шаблонов для учётных данных + +Для повышения безопасности можно использовать механизм шаблонизации с учётными данными: + +* `{{ .credentials.accessKeyId }}` — подставить Access Key ID из учётных данных. +* `{{ .credentials.secretAccessKey }}` — подставить Secret Access Key из учётных данных. + +{{< alert level="info" >}} +Доступность информации в виджете определяется уровнем прав подключённой учётной записи. +{{< /alert >}} + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------- | -------------- | ------------------------------------------------------------------------------------ | --------------------- | +| Название S3-бакета | Да | Название S3-бакета для просмотра | — | +| Endpoint | Да | Эндпоинт URL S3-совместимого хранилища (например, `https://storage.yandexcloud.net`) | — | +| Регион | Да | Регион, в котором находится S3-бакет | — | +| Access Key ID | Да | Идентификатор ключа доступа для аутентификации | — | +| Secret Access Key | Да | Секретный ключ доступа для аутентификации | — | +| Префикс | Нет | Префикс (путь) для фильтрации объектов при первоначальной загрузке | — | +| Максимум объектов | Нет | Максимальное количество объектов для отображения за один запрос (по умолчанию 100) | 100 | + +## Дополнительные возможности виджета + +### Поиск объектов + +Виджет позволяет искать объекты по префиксу (пути). При поиске список объектов обновляется в соответствии с заданным префиксом. + +{{< alert level="info" >}} +Поиск работает только при вводе символов с начала названия объекта. Поиск по символам из середины названия не поддерживается. +{{< /alert >}} + +Если в конфигурации виджета задан начальный префикс, поиск в виджете ограничивается этим префиксом. Загрузка и отображение файлов с другим префиксом недоступны. + +### Загрузка файлов + +Виджет позволяет загружать файлы из S3-бакета напрямую в браузер. Для каждого файла доступна кнопка загрузки. + +### Детальная информация об объектах + +При клике на иконку документа для каждого объекта отображается детальная информация: + +* Основные параметры: ключ, размер, дата изменения, класс хранения, тип контента, ETag. +* Информация о контенте: кодировка, язык, диспозиция. +* Настройки кеширования: Cache-Control, срок действия. +* Безопасность: серверное шифрование. +* Пользовательские метаданные. + +### Загрузка дополнительных объектов + +При наличии большого количества объектов в S3-бакете доступна функция «Загрузить ещё» для пошаговой загрузки объектов без потери производительности. + +## Аутентификация + +Для работы с виджетом требуется учётная запись с правами доступа к S3-бакету. Система поддерживает следующие методы аутентификации: + +* Access Key ID и Secret Access Key. +* Поддержка различных S3-совместимых провайдеров через настройку эндпоинта. + +{{< alert level="info" >}} +В отличие от других виджетов, виджет S3 не поддерживает использование внешних сервисов для передачи учётных данных. Укажите все параметры аутентификации непосредственно в конфигурации виджета. +{{< /alert >}} diff --git a/content/documentation/admin/widgets/generic/sonarqube.md b/content/documentation/admin/widgets/generic/sonarqube.md new file mode 100644 index 00000000..590f69b1 --- /dev/null +++ b/content/documentation/admin/widgets/generic/sonarqube.md @@ -0,0 +1,26 @@ +--- +title: SonarQube +description: Display project metrics for a selected SonarQube branch. +weight: 30 +--- + +The widget displays SonarQube metrics. + +## Configuration + +| Name | Required | Description | Default | +| ----------- | -------- | ------------------------------------------------------------------------- | ------------------------------------- | +| URL | Yes | SonarQube URL, for example, `https://sonarqube.example.com` | — | +| Project key | Yes | Project identifier in SonarQube | — | +| Branch | No | Project branch from which metrics are retrieved | According to the SonarQube project settings | +| Metrics | Yes | Project metrics displayed in the widget. Specify each metric key in the configuration | — | + +See the [list of available metrics](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition) for the current SonarQube version. + +## Additional widget features + +The widget can display data for the default branch or any other branch. + +## Authorization + +Authorization is configured in [External services](../../external-services/#sonarqube). diff --git a/content/documentation/admin/widgets/generic/sonarqube.ru.md b/content/documentation/admin/widgets/generic/sonarqube.ru.md new file mode 100644 index 00000000..fb891dbf --- /dev/null +++ b/content/documentation/admin/widgets/generic/sonarqube.ru.md @@ -0,0 +1,26 @@ +--- +title: SonarQube +description: Отображение метрик проекта для выбранной ветки SonarQube. +weight: 30 +--- + +Виджет позволяет отображать данные о метриках в платформе SonarQube. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------ | -------------- | ------------------------------------------------------------------------------------------ | --------------------------------------- | +| URL | Да | Адрес SonarQube, например, `https://sonarqube.example.com` | — | +| Ключ проекта | Да | Идентификатор проекта в SonarQube | — | +| Ветка | Нет | Ветка проекта, для которой будут браться метрики | Согласно настройкам проекта в SonarQube | +| Метрики | Да | Метрики проекта, которые будут выводиться в виджете. Укажите ключ каждой метрики в конфигурации | — | + +Список доступных метрик для текущей версии см. в [документации SonarQube](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition). + +## Дополнительные возможности виджета + +Виджет позволяет просматривать данные не только для ветки по умолчанию, но и для любой другой ветки. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#sonarqube). diff --git a/content/documentation/admin/widgets/generic/svacer.md b/content/documentation/admin/widgets/generic/svacer.md new file mode 100644 index 00000000..4caf7efe --- /dev/null +++ b/content/documentation/admin/widgets/generic/svacer.md @@ -0,0 +1,49 @@ +--- +title: Svacer +description: Review static analysis findings, trends, and snapshots from Svacer. +weight: 50 +--- + +The widget displays static code analysis results for a project branch in Svacer: marker review progress, findings by severity, branch finding trends, snapshot comparisons, and a paginated marker table. + +## Configuration + +| Name | Required | Description | Default | +| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- | +| Project name | Yes | Project name in Svacer | — | +| Branch name | Yes | Branch name in Svacer, used as the default branch when the widget opens | — | +| Cache the full marker list | No | Caches the selected Svacer snapshot's full marker list in the DDP backend to speed up pagination on the **Findings** tab | Enabled | +| Cache lifetime (seconds) | No | Number of seconds to keep the response in DDP memory when caching is enabled. Valid range: 30–86400 | 180 | +| Snapshot marker threshold | No | Number of markers above which a snapshot is considered large | 10,000 | +| Large snapshot strategy | No | Behavior when the marker threshold is exceeded | Hybrid | + +Large snapshot strategies: + +* **Hybrid** — The unfiltered **Findings** tab is unavailable. The overview is generated using lightweight Svacer requests. +* **Unlimited** — The full marker list is always loaded. For a large snapshot, the widget only displays a warning. + +## Query parameters + +The following parameters are available when viewing the widget: + +* **Branch** — Svacer branch from which data is loaded. The list is generated for the project in the widget configuration. The configured branch is selected by default. +* **Snapshot** — Branch snapshot from which data is loaded. **Latest snapshot** refers to the current branch snapshot when the widget is refreshed. +* **Filters**: + * **Review status** — Marker review status: confirmed, false positive, unclear, no decision, or will not fix. + * **Severity** — Finding severity. + * **Checker** — Checker name, for example, `gosec.G402`. + +## Tabs + +* **Overview** — Review progress, number of unreviewed markers, branch findings, findings by severity, finding trends, reviews by status, and comparison with the previous snapshot: new, fixed, matched, and unchanged. +* **Findings** — Paginated marker table with **Severity**, **Confidence**, **Location**, **Checker**, **Review**, **Message**, and **Tags** columns. Each marker links to Svacer. + +The widget footer displays summary metrics for the selected snapshot: total markers, unreviewed markers, and filtered findings by severity. + +{{< alert level="info" >}} +With the **Hybrid** strategy, if the snapshot marker count exceeds the threshold, the **Findings** tab is unavailable unless you filter by review status, severity, or checker. +{{< /alert >}} + +## Authorization + +Authorization is configured in [External services](../../external-services/#svacer). diff --git a/content/documentation/admin/widgets/generic/svacer.ru.md b/content/documentation/admin/widgets/generic/svacer.ru.md new file mode 100644 index 00000000..11eb413e --- /dev/null +++ b/content/documentation/admin/widgets/generic/svacer.ru.md @@ -0,0 +1,49 @@ +--- +title: Svacer +description: Просмотр результатов, динамики и снимков статического анализа из Svacer. +weight: 50 +--- + +Виджет позволяет просматривать результаты статического анализа кода по ветке проекта в Svacer: прогресс ревью маркеров, распределение находок по критичности, динамику срабатываний на ветке, сравнение снимков и таблицу маркеров с пагинацией. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Название проекта | Да | Название проекта в Svacer | — | +| Название ветки | Да | Название ветки в Svacer; используется как ветка по умолчанию при открытии виджета | — | +| Кэшировать полный список маркеров | Нет | Кэширует на бэкенде DDP полный список маркеров выбранного снимка из Svacer; ускоряет пагинацию на вкладке «Находки» | Включено | +| Время жизни кэша (сек.) | Нет | Сколько секунд хранить ответ в памяти DDP; действует при включённом кэше. Допустимый диапазон при указании значения: 30–86400 | 180 | +| Порог маркеров в снимке | Нет | Число маркеров, после которого снимок считается большим | 10 000 | +| Стратегия для больших снимков | Нет | Поведение при превышении порога маркеров (см. ниже) | Гибрид | + +Стратегии для больших снимков: + +* «Гибрид» — вкладка «Находки» без фильтров недоступна; обзор собирается облегчёнными запросами к Svacer. +* «Без ограничений» — всегда загружается полный список маркеров; при большом снимке отображается только предупреждение. + +## Параметры запроса + +При просмотре виджета доступны следующие параметры: + +* «Ветка» — ветка Svacer для загрузки данных. Список формируется по проекту из настроек виджета. По умолчанию используется ветка из конфигурации виджета. +* «Снимок» — снимок ветки для загрузки данных. Значение «Последний снимок» соответствует актуальному снимку на ветке в момент обновления виджета. +* «Фильтры»: + * «Статус ревью» — фильтр по статусу разметки маркера (подтверждено, ложное срабатывание, неясно, без решения, не исправлять). + * «Критичность» — фильтр по уровню критичности находки. + * «Чекер» — фильтр по имени чекера (например, `gosec.G402`). + +## Вкладки + +* «Обзор» — прогресс ревью, число маркеров без ревью, срабатывания на ветке, распределение по критичности, динамика срабатываний, разбивка ревью по статусам и сравнение с предыдущим снимком (новые, исправленные, совпавшие и без изменений). +* «Находки» — таблица маркеров с колонками «Критичность», «Надёжность», «Место», «Чекер», «Ревью», «Сообщение» и «Теги». Поддерживается пагинация и переход к маркеру в Svacer по ссылке. + +В нижней панели виджета отображаются сводные показатели по выбранному снимку: число маркеров в снимке, маркеры без ревью и отфильтрованные находки по уровням критичности. + +{{< alert level="info" >}} +При стратегии «Гибрид» и числе маркеров в снимке выше порога вкладка «Находки» недоступна без фильтра по статусу ревью, критичности или чекеру. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#svacer). diff --git a/content/documentation/admin/widgets/generic/task-queue.md b/content/documentation/admin/widgets/generic/task-queue.md new file mode 100644 index 00000000..db41bc56 --- /dev/null +++ b/content/documentation/admin/widgets/generic/task-queue.md @@ -0,0 +1,50 @@ +--- +title: Task queue +description: Monitor background task queues, active workers, and task processing status. +weight: 150 +--- + +The widget monitors the task queue and the workers that process tasks in the background. It displays queue statistics, worker (consumer) information, and details of every task in the queue. + +## Displayed data + +The widget has three main sections. + +### Queue statistics + +The top of the widget displays four key metrics: + +- **Queue size** — Total number of tasks in the queue. +- **Pending tasks** — Number of tasks waiting to be processed. +- **Active workers** — Number of active workers (consumers) processing tasks. +- **Queued tasks** — Total number of new and in-progress tasks. + +### Workers table + +The table provides information about each active worker: + +- **Consumer name** — Worker (consumer) identifier. +- **Pending tasks** — Number of tasks assigned to the worker and waiting to be processed. +- **Idle time** — Time since the worker's last activity. + +{{< alert level="info" >}} +The table displays only active workers. Workers that are not processing tasks and have been inactive for more than five minutes are automatically hidden. +{{< /alert >}} + +### Tasks table + +The table provides details about every task in the queue: + +- **Task UUID** — Unique task identifier. +- **Type** — Task type, for example, `health_check`. +- **Resource UUID** — Identifier of the resource or entity associated with the task. +- **Consumer** — Name of the consumer processing the task. +- **Idle time** — Time since the task was delivered to the worker. +- **Delivery time** — Time when the task was delivered to the worker. +- **Status** — Current task status: + - **New** — The task has been added to the queue but has not yet been assigned to a worker. + - **In progress** — The task has been assigned to a worker and is being processed. + +## Configuration + +The widget requires no additional configuration and works immediately after you add it to the dashboard. diff --git a/content/documentation/admin/widgets/generic/task-queue.ru.md b/content/documentation/admin/widgets/generic/task-queue.ru.md new file mode 100644 index 00000000..2c6f0437 --- /dev/null +++ b/content/documentation/admin/widgets/generic/task-queue.ru.md @@ -0,0 +1,50 @@ +--- +title: Очередь задач +description: Мониторинг очередей фоновых задач, активных воркеров и статусов обработки. +weight: 150 +--- + +Виджет позволяет отслеживать состояние очереди задач и работу воркеров, обрабатывающих задачи в фоновом режиме. Виджет отображает статистику очереди, информацию о воркерах (консьюмерах) и детали всех задач в очереди. + +## Отображаемые данные + +Виджет состоит из трех основных разделов: + +### Статистика очереди + +В верхней части виджета отображаются четыре ключевых показателя: + +- «Размер очереди» — общее количество задач в очереди. +- «Ожидающие задачи» — количество задач, ожидающих обработки. +- «Активные воркеры» — количество активных воркеров (консьюмеров), обрабатывающих задачи. +- «Задачи в очереди» — общее количество задач, включая новые и обрабатываемые. + +### Таблица воркеров + +Таблица содержит информацию о каждом активном воркере: + +- «Название консьюмера» — идентификатор воркера (консьюмера). +- «Ожидающие задачи» — количество задач, назначенных данному воркеру и ожидающих обработки. +- «Время простоя» — время с момента последней активности воркера. + +{{< alert level="info" >}} +В таблице отображаются только активные воркеры. Воркеры, которые не обрабатывают задачи и неактивны более 5 минут, автоматически скрываются из списка. +{{< /alert >}} + +### Таблица задач + +Таблица содержит детальную информацию о всех задачах в очереди: + +- «UUID задачи» — уникальный идентификатор задачи. +- «Тип» — тип задачи (например, `health_check`). +- «UUID ресурса» — идентификатор ресурса или сущности, к которой относится задача. +- «Консьюмер» — название консьюмера, обрабатывающего задачу. +- «Время простоя» — время с момента доставки задачи воркеру. +- «Время доставки» — время, когда задача была доставлена воркеру. +- «Статус» — текущий статус задачи: + - «Новая» — задача добавлена в очередь, но ещё не назначена воркеру. + - «В обработке» — задача назначена воркеру и обрабатывается. + +## Конфигурация + +Виджет не требует дополнительной конфигурации и работает сразу после добавления на дашборд. diff --git a/content/documentation/admin/widgets/generic/tech-radar.md b/content/documentation/admin/widgets/generic/tech-radar.md new file mode 100644 index 00000000..e7dbbdee --- /dev/null +++ b/content/documentation/admin/widgets/generic/tech-radar.md @@ -0,0 +1,26 @@ +--- +title: Technology radar +description: Visualize technologies and practices by quadrant and maturity ring. +weight: 160 +--- + +The widget visualizes technologies, tools, and practices used in the company, grouped by maturity level: Adopt, Trial, Assess, and Hold. + +The widget displays a circular chart with four quadrants, four rings, and a set of items. Each item has a number, name, quadrant, and ring. Configure the radar contents in the widget settings. + +## Configuration + +| Name | Required | Description | +| --------- | -------- | ----------------------------------------------- | +| Quadrants | Yes | Quadrant names | +| Items | No | List and configuration of up to 200 radar items | + +### Item configuration + +| Name | Required | Description | +| ----------- | -------- | ------------------------------------------------------------------- | +| Name | Yes | Item name | +| Number | Yes | Integer from 0 to 9999 | +| Description | No | Item description, displayed as Markdown in the details dialog | +| Quadrant | Yes | Quadrant containing the item | +| Ring | Yes | Ring containing the item: Adopt, Trial, Assess, or Hold | diff --git a/content/documentation/admin/widgets/generic/tech-radar.ru.md b/content/documentation/admin/widgets/generic/tech-radar.ru.md new file mode 100644 index 00000000..a5eb1ed7 --- /dev/null +++ b/content/documentation/admin/widgets/generic/tech-radar.ru.md @@ -0,0 +1,26 @@ +--- +title: Технологический радар +description: Визуализация технологий и практик по квадрантам и уровням зрелости. +weight: 160 +--- + +Виджет позволяет визуализировать технологии, инструменты и практики, используемые в компании, с их разбивкой по уровням зрелости (Adopt, Trial, Assess, Hold). + +На виджете отображается круговая диаграмма: четыре квадранта, четыре кольца и набор элементов с номером, названием и привязкой к квадранту и кольцу. Наполнение радара настраивается в конфигурации виджета. + +## Конфигурация + +| Название | Обязательность | Описание | +| --------- | -------------- | ----------------------------------------------------------- | +| Квадранты | Да | Названия квадрантов | +| Элементы | Нет | Список элементов на радаре (не более 200) и их конфигурация | + +### Конфигурация элемента + +| Название | Обязательность | Описание | +| -------- | -------------- | ---------------------------------------------------------------------- | +| Название | Да | Название элемента | +| Номер | Да | Целое число от 0 до 9999 | +| Описание | Нет | Описание элемента, в диалоге просмотра отображается в формате Markdown | +| Квадрант | Да | Квадрант, к которому относится элемент | +| Кольцо | Да | Кольцо, к которому относится элемент: Adopt, Trial, Assess или Hold | diff --git a/content/documentation/admin/widgets/generic/vault.md b/content/documentation/admin/widgets/generic/vault.md new file mode 100644 index 00000000..828ab493 --- /dev/null +++ b/content/documentation/admin/widgets/generic/vault.md @@ -0,0 +1,62 @@ +--- +title: Vault secrets +description: Browse KV v2 secret metadata and key structures without exposing secret values. +weight: 60 +--- + +The widget lets you browse secrets in HashiCorp Vault or Deckhouse Stronghold. KV v2 secrets are supported. + +{{< alert level="info" >}} +The widget does not send secret values to users. Only secret metadata, such as version and creation time, and the key structure without values are sent to the client. +{{< /alert >}} + +For each secret, you can: + +* Browse the hierarchical structure of secrets and directories. +* View secret metadata: version, creation time, deletion time, and destruction status. +* View secret keys in a key-value table. Placeholders are displayed instead of values. +* Navigate nested secrets and directories. + +## Configuration + +| Name | Required | Description | Default | +| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | +| Path | Yes | Path to a secret or directory in Vault. The path must explicitly include `/data/`. Examples: `services/data/`, `services/data/example` | — | +| UI prefix | No | UI URL prefix. Use `vault` for HashiCorp Vault or `stronghold` for Deckhouse Stronghold | — | + +## Path behavior + +Paths to KV v2 secrets must explicitly include `/data/`. Valid examples: + +* `services/data/` — Browse all secrets in the `services` directory. +* `services/data/example` — View the `example` secret. +* `services/data/nested/secret` — View a nested secret. + +## Displayed data + +The widget displays the following information. + +### Secret structure + +* **Directories** — Displayed with a trailing slash, for example, `nested/`, and always identified as directories even if they contain keys. +* **Secrets** — Displayed without a trailing slash and contain keys. + +### Secret metadata + +The following metadata is displayed when available: + +* **Version** — Secret version in KV v2. +* **Creation time** — Date and time when the secret was created. +* **Deletion time** — Date and time when the secret version was deleted. +* **Destruction status** — Indicates that the secret was destroyed. + +### Secret keys + +Secret keys are displayed in a key-value table: + +* **Key** — Full path to the key in the secret structure, for example, `database.host`. +* **Value** — Always masked as `********` and cannot be revealed. + +## Authorization + +Authorization is configured in [External services](../../external-services/#vault). diff --git a/content/documentation/admin/widgets/generic/vault.ru.md b/content/documentation/admin/widgets/generic/vault.ru.md new file mode 100644 index 00000000..ede9a2aa --- /dev/null +++ b/content/documentation/admin/widgets/generic/vault.ru.md @@ -0,0 +1,62 @@ +--- +title: Vault. Секреты +description: Просмотр метаданных и структуры ключей секретов KV v2 без раскрытия значений. +weight: 60 +--- + +Виджет позволяет просматривать секреты в HashiCorp Vault или Deckhouse Stronghold. Поддерживается работа с KV v2 секретами. + +{{< alert level="info" >}} +Виджет не передаёт значения секретов пользователю. На клиентскую сторону передаются только метаданные секретов (версия, время создания и т. д.) и структура ключей без их значений. +{{< /alert >}} + +Для каждого секрета доступно: + +* Просмотр иерархической структуры секретов и директорий. +* Просмотр метаданных секрета: версия, время создания, время удаления, статус уничтожения. +* Просмотр ключей секрета в формате таблицы «ключ/значение» (вместо значений отображается маска). +* Навигация по вложенным секретам и директориям. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | +| Путь | Да | Путь к секрету или директории в Vault. Необходимо явно указывать путь с `/data/`. Примеры: `services/data/`, `services/data/example` | — | +| Префикс UI | Нет | Префикс для URL интерфейса. Используйте `vault` для HashiCorp Vault или `stronghold` для Deckhouse Stronghold | — | + +## Особенности работы с путями + +Для работы с KV v2 секретами путь должен явно содержать `/data/`. Примеры корректных путей: + +* `services/data/` — для просмотра всех секретов в директории `services`. +* `services/data/example` — для просмотра конкретного секрета `example`. +* `services/data/nested/secret` — для вложенных секретов. + +## Отображаемые данные + +Виджет отображает следующую информацию: + +### Структура секретов + +* «Директории» — отображаются с завершающим слешем (например, `nested/`) и всегда помечаются как директории, даже если содержат ключи. +* «Секреты» — отображаются без завершающего слеша и содержат ключи. + +### Метаданные секрета + +Для каждого секрета отображаются следующие метаданные (если доступны): + +* «Версия» — версия секрета в KV v2. +* «Время создания» — дата и время создания секрета. +* «Время удаления» — дата и время удаления секрета (для удалённых версий). +* «Статус уничтожения» — индикатор того, что секрет был уничтожен. + +### Ключи секрета + +Ключи секрета отображаются в формате таблицы «ключ/значение»: + +* Ключ — полный путь к ключу в структуре секрета (например, `database.host`). +* Значение — всегда маскируется символами `********` и не может быть раскрыто. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#vault). diff --git a/content/documentation/admin/widgets/github/_index.md b/content/documentation/admin/widgets/github/_index.md new file mode 100644 index 00000000..9e5015c9 --- /dev/null +++ b/content/documentation/admin/widgets/github/_index.md @@ -0,0 +1,5 @@ +--- +title: GitHub +description: GitHub widgets for working with repository workflows, pull requests, and tags. +weight: 80 +--- diff --git a/content/documentation/admin/widgets/github/_index.ru.md b/content/documentation/admin/widgets/github/_index.ru.md new file mode 100644 index 00000000..045384ad --- /dev/null +++ b/content/documentation/admin/widgets/github/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: GitHub +description: Виджеты GitHub для работы с процессами, запросами на слияние и тегами репозиториев. +weight: 80 +--- diff --git a/content/documentation/admin/widgets/github/actions.md b/content/documentation/admin/widgets/github/actions.md new file mode 100644 index 00000000..0119329e --- /dev/null +++ b/content/documentation/admin/widgets/github/actions.md @@ -0,0 +1,49 @@ +--- +title: GitHub. Actions +description: Filters and actions for GitHub Actions workflow runs, jobs, logs, and artifacts. +weight: 10 +--- + +The widget displays GitHub Actions runs in a repository. It also displays jobs and artifacts and provides actions for managing them. + +## Account and action initiator + +Requests to GitHub use the token from the credentials of the platform user on whose behalf the action is invoked. If **Select an account for the widget** is enabled in the widget settings, the selected platform user's credentials are used instead of the current user's credentials. + +When a workflow is started, canceled, or restarted, or when artifacts and logs are accessed, GitHub identifies the GitHub account that owns the token as the initiator. The login displayed in GitHub may differ from the name in the Deckhouse Development Platform (DDP) profile. + +## Configuration + +| Name | Required | Description | Example | +| ---------------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------- | +| Repository owner | Yes | Repository owner, either an organization or a user | For `https://github.com/example/my-repo`, specify `example` | +| Repository | Yes | Repository name without the `.git` suffix | For `https://github.com/example/my-repo`, specify `my-repo` | + +## Request parameters + +Configure the following filters in the widget request settings: + +- **Branch** — displays only runs from the specified head branch. +- **Event** — displays only runs triggered by the selected event type. +- **Status** — displays only runs with the selected status or conclusion. +- **Workflow** — displays only runs for the selected workflow file. +- **Triggered by** — displays only runs started by the specified GitHub user. +- **Creation date filter** — displays runs created within the specified start and end dates. + +## Actions + +The widget provides the following actions: + +- **Run workflow** — manually starts a workflow with the `workflow_dispatch` trigger. Select the workflow and branch or tag. If the input YAML declares parameters, the input parameters are displayed. +- **Restart workflow**, **Restart failed jobs**, and **Cancel workflow** — manage the selected run. +- **Restart job** — restarts a completed job with the `failure` or `cancelled` conclusion. +- **View run details** — displays job logs, artifacts, the run on GitHub, and the job and step tree. + +{{< alert level="info" >}} +Workflow and artifact actions require the corresponding permissions in the GitHub repository. +{{< /alert >}} + +## Authentication + +Authentication is described in [External services](../../external-services/#github). +In the external service settings, set **URL** to `https://api.github.com`. diff --git a/content/documentation/admin/widgets/github/actions.ru.md b/content/documentation/admin/widgets/github/actions.ru.md new file mode 100644 index 00000000..4dcbc89b --- /dev/null +++ b/content/documentation/admin/widgets/github/actions.ru.md @@ -0,0 +1,53 @@ +--- +title: GitHub. Actions +description: Фильтры и действия для рабочих процессов, задач, логов и артефактов GitHub Actions. +weight: 10 +--- + +Виджет показывает запуски GitHub Actions в репозитории и позволяет просматривать задачи и артефакты, а также управлять ими. + +## Учётная запись и автор действий + +Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. + +При запуске, отмене и перезапуске рабочего процесса, а также при работе с артефактами и логами +в GitHub инициатором считается учётная запись GitHub, которой принадлежит токен. +Логин в интерфейсе GitHub может не совпадать с именем в профиле Deckhouse Development Platform (DDP). + +## Конфигурация + +| Название | Обязательность | Описание | Пример | +| -------------------- | -------------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| Владелец репозитория | Да | Владелец репозитория (организация или пользователь) | Для `https://github.com/example/my-repo` укажите `example` | +| Репозиторий | Да | Название репозитория без `.git` | Для `https://github.com/example/my-repo` укажите `my-repo` | + +## Параметры запроса + +В настройках запроса виджета можно задать фильтры: + +- «Ветка» — только запуски с указанной исходной веткой. +- «Событие» — только запуски с выбранным типом события. +- «Статус» — только запуски в выбранном статусе или с выбранным результатом. +- «Workflow» — только запуски для выбранного файла рабочего процесса. +- «Кто запустил» — только запуски, начатые указанным пользователем GitHub. +- «Фильтр по дате создания» — интервал дат создания запуска (дата начала и дата окончания). + +## Действия + +В виджете доступны следующие действия: + +- «Запустить рабочий процесс» — ручной запуск с триггером `workflow_dispatch`. + Выберите «Workflow» и «Ветка или тег». + Если во входном YAML объявлены параметры, виджет отобразит «Входные параметры». +- «Перезапустить рабочий процесс», «Перезапустить завершившиеся с ошибкой задачи», «Отменить рабочий процесс» — действия для выбранного запуска. +- «Перезапустить задачу» — перезапуск завершённой задачи с результатом `failure` или `cancelled`. +- «Просмотреть сведения о запуске» — просмотр логов задач и дерева задач и шагов, скачивание артефактов и открытие запуска на GitHub. + +{{< alert level="info" >}} +Для действий с рабочими процессами и артефактами нужны соответствующие права в репозитории GitHub. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#github). +В настройках внешнего сервиса в поле «URL» укажите `https://api.github.com`. diff --git a/content/documentation/admin/widgets/github/pull-requests.md b/content/documentation/admin/widgets/github/pull-requests.md new file mode 100644 index 00000000..caecd033 --- /dev/null +++ b/content/documentation/admin/widgets/github/pull-requests.md @@ -0,0 +1,47 @@ +--- +title: GitHub. Pull Requests +description: Status filtering and repository actions for GitHub pull requests. +weight: 20 +--- + +The widget displays Pull Requests (PRs) for a GitHub repository. It also provides actions for viewing changes and creating, merging, and closing PRs. + +## Account and action initiator + +Requests to GitHub use the token from the credentials of the platform user on whose behalf the action is invoked. If **Select an account for the widget** is enabled in the widget settings, the selected platform user's credentials are used instead of the current user's credentials. + +When a Pull Request is created, merged, or closed, GitHub identifies the GitHub account that owns the token as the PR author and action initiator. The login and name displayed in GitHub may differ from the name in the Deckhouse Development Platform (DDP) profile. + +## Configuration + +| Name | Required | Description | Example | +| ---------------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------- | +| Repository owner | Yes | Repository owner, either an organization or a user | For `https://github.com/example/my-repo`, specify `example` | +| Repository | Yes | Repository name without the `.git` suffix | For `https://github.com/example/my-repo`, specify `my-repo` | + +## Status + +Filter PRs by status in the widget request settings: + +- **Open** — displays only open PRs that are not drafts. +- **Draft** — displays only drafts. +- **Closed** — displays only closed PRs. +- **All** — displays PRs in any status. + +By default, the widget displays open PRs. The table displays the number, title, description, status, labels, author, creation date, and update date. An action menu is available for each PR. + +## Actions + +- **Changes** — displays the list of changed files and the diff for each file. +- **Merge** — merges an open PR. This action is available only for open PRs that are not drafts. +- **Close** — closes a PR without merging it. +- **Create PR** — creates a Pull Request. In the dialog, specify the title, source branch, target branch, and description. + +{{< alert level="info" >}} +Pull Request actions require the corresponding permissions in the GitHub repository. +{{< /alert >}} + +## Authentication + +Authentication is described in [External services](../../external-services/#github). +In the external service settings or widget configuration, set **URL** to `https://api.github.com`. diff --git a/content/documentation/admin/widgets/github/pull-requests.ru.md b/content/documentation/admin/widgets/github/pull-requests.ru.md new file mode 100644 index 00000000..e381043a --- /dev/null +++ b/content/documentation/admin/widgets/github/pull-requests.ru.md @@ -0,0 +1,50 @@ +--- +title: GitHub. Запросы на слияние +description: Фильтрация по статусу и действия с запросами на слияние в репозитории GitHub. +weight: 20 +--- + +Виджет отображает запросы на слияние (PR) репозитория на GitHub и позволяет просматривать изменения, создавать, сливать и закрывать PR. + +## Учётная запись и автор действий + +Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. + +При создании, слиянии и закрытии запроса на слияние в GitHub автором PR и исполнителем действий считается учётная запись GitHub, которой принадлежит этот токен. Логин и имя в интерфейсе GitHub могут не совпадать с именем в профиле Deckhouse Development Platform (DDP). + +## Конфигурация + +| Название | Обязательность | Описание | Пример | +| -------------------- | -------------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| Владелец репозитория | Да | Владелец репозитория (организация или пользователь) | Для `https://github.com/example/my-repo` укажите `example` | +| Репозиторий | Да | Название репозитория без `.git` | Для `https://github.com/example/my-repo` укажите `my-repo` | + +## Статус + +В настройках запроса виджета можно фильтровать PR по статусу: + +- «Открыт» — только открытые PR (не черновики). +- «Черновик» — только черновики. +- «Закрыт» — только закрытые PR. +- «Все» — любые PR. + +По умолчанию отображаются открытые PR. +В таблице отображаются номер, название, описание, статус, лейблы, автор, дата создания и дата обновления. +Для каждого PR доступны действия через меню. + +## Действия + +- «Изменения» — просмотр списка изменённых файлов и сравнение изменений по каждому файлу. +- «Слить» — слияние открытого PR (доступно только для открытых PR, не черновиков). +- «Закрыть» — закрытие PR без слияния. +- «Создать PR» — создание нового запроса на слияние. + В диалоге укажите название, исходную ветку, целевую ветку и описание. + +{{< alert level="info" >}} +Для выполнения действий с PR требуются соответствующие права доступа в репозитории GitHub. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#github). +В настройках внешнего сервиса или в конфигурации виджета в поле «URL» укажите `https://api.github.com`. diff --git a/content/documentation/admin/widgets/github/tags.md b/content/documentation/admin/widgets/github/tags.md new file mode 100644 index 00000000..6d09d437 --- /dev/null +++ b/content/documentation/admin/widgets/github/tags.md @@ -0,0 +1,49 @@ +--- +title: GitHub. Tags +description: Repository tag details and tag creation settings for GitHub. +weight: 30 +--- + +The widget displays GitHub repository tags with commit information, including the author, date, and description. It can also create tags. + +## Account and action initiator + +Requests to GitHub use the token from the credentials of the platform user on whose behalf the action is invoked. If **Select an account for the widget** is enabled in the widget settings, the selected platform user's credentials are used instead of the current user's credentials. + +For an annotated tag, where **Description** is provided, the annotation author fields (`tagger`) in the Git tag metadata are populated with the name and email address of the platform user who performed the action, as defined in the Deckhouse Development Platform (DDP) profile. If no name is specified, the email address may be used. + +For a lightweight tag without a description, no separate Git tag author is set. The tag is created as a reference to a commit. + +The API creates the tag using the GitHub account associated with the token. However, the `tagger` data comes from the DDP profile and may not match the GitHub login. + +## Configuration + +| Name | Required | Description | Example | +| ---------------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------- | +| Repository owner | Yes | Repository owner, either an organization or a user | For `https://github.com/example/my-repo`, specify `example` | +| Repository | Yes | Repository name without the `.git` suffix | For `https://github.com/example/my-repo`, specify `my-repo` | + +## Displayed data + +The table displays the tag, description, commit author, commit link, and commit creation date. The **View** action displays the commit description for each tag. + +## Additional widget features + +### Creating a tag + +The widget can create tags in GitHub. Specify the following fields in the **Create tag** dialog: + +| Name | Required | Description | Default value | +| ----------- | -------- | ------------------------------------------------------------------------------------------------- | ------------- | +| Tag name | Yes | A unique tag name, such as `v1.0.0` or `release-2024-01` | — | +| Create from | Yes | The branch or existing tag from which to create the new tag | — | +| Description | No | Tag annotation, such as a release description. If specified, the widget creates an annotated tag | — | + +{{< alert level="info" >}} +Creating tags requires write permissions in the GitHub repository. +{{< /alert >}} + +## Authentication + +Authentication is described in [External services](../../external-services/#github). +In the external service settings, set **URL** to `https://api.github.com`. diff --git a/content/documentation/admin/widgets/github/tags.ru.md b/content/documentation/admin/widgets/github/tags.ru.md new file mode 100644 index 00000000..56e3cf91 --- /dev/null +++ b/content/documentation/admin/widgets/github/tags.ru.md @@ -0,0 +1,52 @@ +--- +title: GitHub. Теги +description: Сведения о тегах репозитория и настройка создания тегов в GitHub. +weight: 30 +--- + +Виджет отображает теги репозитория GitHub с информацией о коммите (автор, дата, описание) и позволяет создавать новые теги. + +## Учётная запись и автор действий + +Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. + +«Аннотированный тег» (поле «Описание» заполнено): в метаданных Git-тега поля автора аннотации (`tagger`) заполняются из имени и email пользователя платформы, выполнившего действие (как в профиле Deckhouse Development Platform (DDP)). Если имя не задано, может подставляться email. + +«Лёгкий тег» (без описания): отдельный автор тега в Git не задаётся; создаётся ссылка на коммит. + +Создание тега через API выполняется от учётной записи GitHub по токену; данные `tagger` при этом берутся из профиля DDP и могут не совпадать с логином GitHub. + +## Конфигурация + +| Название | Обязательность | Описание | Пример | +| -------------------- | -------------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| Владелец репозитория | Да | Владелец репозитория (организация или пользователь) | Для `https://github.com/example/my-repo` укажите `example` | +| Репозиторий | Да | Название репозитория без `.git` | Для `https://github.com/example/my-repo` укажите `my-repo` | + +## Отображаемые данные + +В таблице отображаются столбцы «Тег», «Описание», «Автор коммита», «Ссылка на коммит» +и «Дата создания коммита». +Для каждого тега доступно действие «Просмотр», которое показывает описание коммита. + +## Дополнительные возможности виджета + +### Создание тега + +Виджет позволяет создавать теги в GitHub. +В диалоге «Создать тег» укажите следующие параметры: + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------- | -------------- | ---------------------------------------------------------------------------------------- | --------------------- | +| Название тега | Да | Уникальное название тега, например `v1.0.0` или `release-2024-01` | — | +| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег | — | +| Описание | Нет | Аннотация к тегу (например, описание релиза). Если указано, создаётся аннотированный тег | — | + +{{< alert level="info" >}} +Для создания тегов требуются права на запись в репозиторий GitHub. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#github). +В настройках внешнего сервиса в поле «URL» укажите `https://api.github.com`. diff --git a/content/documentation/admin/widgets/gitlab/_index.md b/content/documentation/admin/widgets/gitlab/_index.md new file mode 100644 index 00000000..ae65c56c --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/_index.md @@ -0,0 +1,5 @@ +--- +title: GitLab +description: GitLab widgets for viewing project data and managing development workflows. +weight: 90 +--- diff --git a/content/documentation/admin/widgets/gitlab/_index.ru.md b/content/documentation/admin/widgets/gitlab/_index.ru.md new file mode 100644 index 00000000..42328130 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: GitLab +description: Виджеты GitLab для просмотра данных проектов и управления процессами разработки. +weight: 90 +--- diff --git a/content/documentation/admin/widgets/gitlab/members.md b/content/documentation/admin/widgets/gitlab/members.md new file mode 100644 index 00000000..fb79f8d4 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/members.md @@ -0,0 +1,17 @@ +--- +title: GitLab. Members +description: Configuration of the widget that displays GitLab project members. +weight: 10 +--- + +The widget displays data about GitLab project members. [Learn more about project members](https://docs.gitlab.com/user/project/members/). + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/members.ru.md b/content/documentation/admin/widgets/gitlab/members.ru.md new file mode 100644 index 00000000..7a88c021 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/members.ru.md @@ -0,0 +1,17 @@ +--- +title: GitLab. Участники +description: Настройка виджета для просмотра участников проекта в GitLab. +weight: 10 +--- + +Виджет позволяет отображать данные об участниках проекта в GitLab. More information about members is available in the [GitLab documentation](https://docs.gitlab.com/user/project/members/). + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/merge-requests.md b/content/documentation/admin/widgets/gitlab/merge-requests.md new file mode 100644 index 00000000..5c4fa3d9 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/merge-requests.md @@ -0,0 +1,43 @@ +--- +title: GitLab. Merge requests +description: Status filtering and management actions for GitLab merge requests. +weight: 20 +--- + +The widget displays GitLab merge requests (MRs) and provides actions for managing them. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| URL | Yes | GitLab API URL used to retrieve data from GitLab | — | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Status filtering + +The widget can filter merge requests by status. +In the widget request settings, select one of the following statuses: + +- **Open** — displays only open MRs. +- **Closed** — displays only closed MRs. +- **Merged** — displays only merged MRs. +- **Blocked** — displays only blocked MRs. + +By default, the widget displays only open MRs. + +## Additional widget features + +When actions are enabled in the settings, the widget provides the following merge request actions: + +- **Merge** — merges an open merge request. This action is available only for open MRs. +- **Close** — closes a merge request. +- **Mark as draft/ready** — changes the draft status of a merge request. +- **View changes** — displays the diff for a merge request. + +{{< alert level="info" >}} +Actions on MRs require the corresponding access permissions in the GitLab repository. +{{< /alert >}} + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/merge-requests.ru.md b/content/documentation/admin/widgets/gitlab/merge-requests.ru.md new file mode 100644 index 00000000..56d7688c --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/merge-requests.ru.md @@ -0,0 +1,43 @@ +--- +title: GitLab. Запросы на слияние +description: Фильтрация по статусу и действия с запросами на слияние в GitLab. +weight: 20 +--- + +Виджет позволяет отображать данные о запросах на слияние (MR) в GitLab и выполнять действия с ними. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Фильтрация по статусу + +Виджет позволяет фильтровать отображаемые запросы на слияние по статусу. +В настройках запроса виджета можно выбрать один из следующих статусов: + +- «Открытые» — показывает только открытые MR. +- «Закрытые» — показывает только закрытые MR. +- «Слитые» — показывает только слитые MR. +- «Заблокированные» — показывает только заблокированные MR. + +По умолчанию отображаются только открытые MR. + +## Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет выполнять следующие действия с запросами на слияние: + +- «Слить» — слияние открытого запроса на слияние (доступно только для открытых MR). +- «Закрыть» — закрытие запроса на слияние. +- «Отметить как черновик/готово» — изменение статуса черновика запроса на слияние. +- «Просмотр изменений» — сравнение изменений в запросе на слияние. + +{{< alert level="info" >}} +Для выполнения действий с MR требуются соответствующие права доступа в репозитории GitLab. +{{< /alert >}} + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/pipeline-editor.md b/content/documentation/admin/widgets/gitlab/pipeline-editor.md new file mode 100644 index 00000000..40b1f987 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipeline-editor.md @@ -0,0 +1,46 @@ +--- +title: GitLab. Pipeline editor +description: Editing GitLab CI/CD configuration and creating merge requests from the widget. +weight: 30 +--- + +The widget lets you edit the GitLab CI/CD pipeline configuration in `.gitlab-ci.yml` +and create merge requests with the changes. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| URL | Yes | GitLab API URL used to retrieve data from GitLab | — | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Displayed data + +The widget displays a Monaco code editor for editing `.gitlab-ci.yml` +and a diff view of the original and edited configuration. + +## Additional widget features + +### Creating a merge request + +The widget lets you create a merge request containing pipeline configuration changes. + +#### Merge request parameters + +| Name | Required | Description | Default value | +| --------------- | -------- | ----------------------------------------------------- | ------------- | +| MR title | Yes | Short title describing the purpose of the merge request | — | +| MR description | No | Detailed description of the merge request and changes | — | +| New branch name | Yes | Name of the new branch that will contain the changes | — | +| Target branch | Yes | Branch to which the merge request will be submitted | `main` | +| Commit message | Yes | Description of changes to the pipeline configuration | — | + +### Limitations + +- The widget supports only the `.gitlab-ci.yml` file in the project root. +- Creating a merge request requires write access to the repository. +- The maximum configuration file size is limited by the GitLab API. + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/pipeline-editor.ru.md b/content/documentation/admin/widgets/gitlab/pipeline-editor.ru.md new file mode 100644 index 00000000..7a8a7cc5 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipeline-editor.ru.md @@ -0,0 +1,45 @@ +--- +title: GitLab. Редактор пайплайна +description: Редактирование конфигурации GitLab CI/CD и создание запросов на слияние из виджета. +weight: 30 +--- + +Виджет позволяет редактировать конфигурацию пайплайна GitLab CI/CD (файл `.gitlab-ci.yml`) и создавать запросы на слияние с изменениями. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Отображаемые данные + +Виджет отображает редактор кода Monaco Editor для файла `.gitlab-ci.yml` +и сравнение исходной и редактируемой версий конфигурации. + +## Дополнительные возможности виджета + +### Создание запроса на слияние + +Виджет позволяет создавать запросы на слияние с изменениями конфигурации пайплайна. + +#### Параметры запроса на слияние + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------- | -------------- | ------------------------------------------------------------ | --------------------- | +| Заголовок MR | Да | Краткий заголовок, описывающий цель запроса на слияние | — | +| Описание MR | Нет | Подробное описание запроса на слияние и изменений | — | +| Название новой ветки | Да | Название новой ветки, которая будет содержать изменения | — | +| Целевая ветка | Да | Ветка, в которую будет выполнен запрос на слияние | `main` | +| Сообщение коммита | Да | Описание изменений, внесённых в конфигурацию пайплайна | — | + +### Ограничения + +* Виджет работает только с файлом `.gitlab-ci.yml` в корне проекта. +* Для создания запроса на слияние требуются права на запись в репозиторий. +* Максимальный размер файла конфигурации ограничен возможностями GitLab API. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/pipeline-statistics.md b/content/documentation/admin/widgets/gitlab/pipeline-statistics.md new file mode 100644 index 00000000..6425f889 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipeline-statistics.md @@ -0,0 +1,69 @@ +--- +title: GitLab. Pipeline statistics +description: Pipeline metrics, breakdowns, request parameters, and limits for GitLab projects. +weight: 40 +--- + +The widget displays GitLab pipeline statistics, +including overall statistics and breakdowns by status, source, member, and branch. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| URL | Yes | GitLab API URL used to retrieve data from GitLab | — | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Displayed data + +The widget displays the following statistics: + +### Key metrics + +- **Total pipelines** — total number of pipelines during the selected period. +- **Success rate** — percentage of successful pipelines. +- **Failure rate** — percentage of failed pipelines. +- **Average duration** — average pipeline execution time. + +### Breakdown by status + +- Successful pipelines. +- Failed pipelines. +- Canceled pipelines. +- Skipped pipelines. +- Manual pipelines. + +### Breakdown by source + +- Push events (commits). +- Merge requests. +- Scheduled runs. +- Web interface. + +### Top members + +- Members who started the most pipelines. +- Member avatars, if available. +- Number of pipelines for each member. + +### Branch activity + +The widget shows the branches with the most pipelines and the number of pipelines for each branch. + +## Request parameters + +| Name | Required | Description | Default value | +| ---------- | -------- | ----------------------------------------------------------------------------------------------- | ------------- | +| Start date | Yes | Start date of the pipeline analysis period in ISO 8601 format. Example: `2024-01-01T00:00:00Z` | — | +| End date | Yes | End date of the pipeline analysis period in ISO 8601 format. Example: `2024-01-31T23:59:59Z` | — | +| Branch | No | Filters by a specific branch. If omitted, the widget analyzes all branches | — | + +## Limitations + +- To optimize performance, the widget analyzes no more than 100 pipelines per request. +- Statistics include only pipelines with valid data, including a status and execution time. +- Data is updated each time the widget refreshes. + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/pipeline-statistics.ru.md b/content/documentation/admin/widgets/gitlab/pipeline-statistics.ru.md new file mode 100644 index 00000000..ea2277a4 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipeline-statistics.ru.md @@ -0,0 +1,68 @@ +--- +title: GitLab. Статистика пайплайнов +description: Метрики, распределения, параметры запроса и ограничения статистики пайплайнов GitLab. +weight: 40 +--- + +Виджет позволяет отображать статистику пайплайнов в платформе GitLab, включая общую статистику, распределение по статусам, источникам, участникам и веткам. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Отображаемые данные + +Виджет отображает следующую статистику: + +### Основные метрики + +* «Общее количество пайплайнов» — общее число пайплайнов за выбранный период. +* «Процент успеха» — процент успешно выполненных пайплайнов. +* «Процент неудач» — процент неудачно выполненных пайплайнов. +* «Средняя длительность» — среднее время выполнения пайплайнов. + +### Распределение по статусам + +* Успешные пайплайны. +* Неудачные пайплайны. +* Отменённые пайплайны. +* Пропущенные пайплайны. +* Ручные пайплайны. + +### Распределение по источникам + +* Отправка изменений (коммиты). +* Запросы на слияние. +* Запуски по расписанию. +* Запуски через веб-интерфейс. + +### Топ участников + +* Список участников с наибольшим количеством запущенных пайплайнов. +* Аватары участников (при наличии). +* Количество пайплайнов для каждого участника. + +### Активность веток + +Виджет показывает ветки с наибольшим количеством пайплайнов и количество пайплайнов для каждой ветки. + +## Параметры запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------- | -------------- | ---------------------------------------------------------------------------------------- | --------------------- | +| Начальная дата | Да | Начальная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-01T00:00:00Z` | — | +| Конечная дата | Да | Конечная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-31T23:59:59Z` | — | +| Ветка | Нет | Фильтр по конкретной ветке. Если не указана, анализируются все ветки | — | + +## Ограничения + +* Виджет анализирует максимум 100 пайплайнов за один запрос для оптимизации производительности. +* Статистика рассчитывается только для пайплайнов с валидными данными (имеющими статус и время выполнения). +* Данные обновляются при каждом обновлении виджета. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/pipelines.md b/content/documentation/admin/widgets/gitlab/pipelines.md new file mode 100644 index 00000000..c6782145 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipelines.md @@ -0,0 +1,31 @@ +--- +title: GitLab. Pipelines +description: Configuration and manual start settings for GitLab pipelines. +weight: 50 +--- + +The widget displays data about GitLab pipelines. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| URL | Yes | GitLab API URL used to retrieve data from GitLab | — | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Additional widget features + +### Starting pipelines + +The widget lets you start GitLab pipelines directly from Deckhouse Development Platform (DDP). + +#### Configuration + +| Name | Required | Description | Default value | +| --------- | -------- | ------------------------------------------------------------- | ------------- | +| Ref | Yes | Target branch or tag on which to start the pipeline | — | +| Variables | No | Key-value variables to pass to the pipeline being started | — | + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/pipelines.ru.md b/content/documentation/admin/widgets/gitlab/pipelines.ru.md new file mode 100644 index 00000000..5d966a64 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/pipelines.ru.md @@ -0,0 +1,31 @@ +--- +title: GitLab. Пайплайны +description: Настройка просмотра и ручного запуска пайплайнов GitLab. +weight: 50 +--- + +Виджет позволяет отображать данные о пайплайнах в GitLab. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Дополнительные возможности виджета + +### Запуск пайплайнов + +Виджет позволяет запускать пайплайны в GitLab напрямую из Deckhouse Development Platform (DDP). + +#### Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | --------------------------------------------------------------------------------- | --------------------- | +| Ref | Да | Целевая ветка или тег для запуска пайплайна | — | +| Переменные | Нет | Переменные в формате ключ-значение, которые будут переданы в запускаемый пайплайн | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/releases.md b/content/documentation/admin/widgets/gitlab/releases.md new file mode 100644 index 00000000..7ac5ca03 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/releases.md @@ -0,0 +1,33 @@ +--- +title: GitLab. Releases +description: Release details and release creation settings for GitLab projects. +weight: 60 +--- + +The widget displays GitLab project releases, highlights the latest release, +and shows related information: the tag, commit link, author, publication date, +and a description with Markdown support. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Additional widget features + +### Creating a release + +The widget lets you create a release in GitLab directly from Deckhouse Development Platform (DDP): + +| Name | Required | Description | Default value | +| ------------ | -------- | --------------------------------------------------------------------------- | ------------- | +| Release name | Yes | Release name displayed in the list | — | +| Tag | Yes | Existing tag on which to base the release, selected from the project's tags | — | +| Description | No | Release description in Markdown format | — | + +The created release appears in the list automatically, and the latest release is highlighted. + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/releases.ru.md b/content/documentation/admin/widgets/gitlab/releases.ru.md new file mode 100644 index 00000000..d2d04e85 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/releases.ru.md @@ -0,0 +1,31 @@ +--- +title: GitLab. Релизы +description: Просмотр сведений о релизах и настройка создания релизов GitLab. +weight: 60 +--- + +Виджет отображает список релизов GitLab-проекта, подсвечивает последний релиз и показывает связанную информацию: тег, ссылку на коммит, автора, дату публикации и описание (поддерживает Markdown). + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Дополнительные возможности виджета + +### Создание релиза + +Виджет позволяет создать релиз в GitLab напрямую из Deckhouse Development Platform (DDP): + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------- | -------------- | ------------------------------------------------------------------------------------------------- | --------------------- | +| Название релиза | Да | Название релиза, отображаемое в списке | — | +| Тег | Да | Существующий тег, на основе которого будет сформирован релиз (выбирается из списка тегов проекта) | — | +| Описание | Нет | Описание релиза в формате Markdown | — | + +Созданный релиз автоматически появляется в списке, а последний релиз подсвечивается. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/tags.md b/content/documentation/admin/widgets/gitlab/tags.md new file mode 100644 index 00000000..80762941 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/tags.md @@ -0,0 +1,32 @@ +--- +title: GitLab. Tags +description: Configuration and creation settings for tags in GitLab projects. +weight: 70 +--- + +The widget displays data about GitLab project tags. + +## Configuration + +| Name | Required | Description | Default value | +| ---------- | -------- | ------------------------------------------------------------------ | ------------- | +| URL | Yes | GitLab API URL used to retrieve data from GitLab | — | +| Project ID | Yes | ID of the project from which the widget retrieves data. Example: `12345` | — | + +## Additional widget features + +### Creating tags + +The widget lets you create GitLab tags directly from Deckhouse Development Platform (DDP). + +#### Configuration + +| Name | Required | Description | Default value | +| ----------- | -------- | ---------------------------------------------------- | ------------- | +| Name | Yes | Name of the tag to create | — | +| Create from | Yes | Branch or existing tag from which to create the tag | — | +| Description | No | Description of the tag to create | — | + +## Authentication + +Authentication configuration is described in the [External services](../../external-services/#gitlab) section. diff --git a/content/documentation/admin/widgets/gitlab/tags.ru.md b/content/documentation/admin/widgets/gitlab/tags.ru.md new file mode 100644 index 00000000..24e103c2 --- /dev/null +++ b/content/documentation/admin/widgets/gitlab/tags.ru.md @@ -0,0 +1,32 @@ +--- +title: GitLab. Теги +description: Настройка просмотра и создания тегов в проектах GitLab. +weight: 70 +--- + +Виджет позволяет отображать данные о тегах проекта в GitLab. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | -------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | +| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | + +## Дополнительные возможности виджета + +### Создание тегов + +Виджет позволяет создавать теги в GitLab напрямую из Deckhouse Development Platform (DDP). + +#### Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ---------- | -------------- | ----------------------------------------------------------- | --------------------- | +| Название | Да | Название создаваемого тега | — | +| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег | — | +| Описание | Нет | Описание создаваемого тега | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/kafka/_index.md b/content/documentation/admin/widgets/kafka/_index.md new file mode 100644 index 00000000..3f1ea37c --- /dev/null +++ b/content/documentation/admin/widgets/kafka/_index.md @@ -0,0 +1,5 @@ +--- +title: Kafka +description: Widgets for inspecting and managing Kafka resources. +weight: 100 +--- diff --git a/content/documentation/admin/widgets/kafka/_index.ru.md b/content/documentation/admin/widgets/kafka/_index.ru.md new file mode 100644 index 00000000..e357d1ff --- /dev/null +++ b/content/documentation/admin/widgets/kafka/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Kafka +description: Виджеты для просмотра и управления ресурсами Kafka. +weight: 100 +--- diff --git a/content/documentation/admin/widgets/kafka/acls.md b/content/documentation/admin/widgets/kafka/acls.md new file mode 100644 index 00000000..042fec4e --- /dev/null +++ b/content/documentation/admin/widgets/kafka/acls.md @@ -0,0 +1,46 @@ +--- +title: Kafka. ACLs +description: Access-control rule inspection and management for Kafka clusters. +weight: 10 +--- + +The widget displays a list of access control lists (ACLs) for a Kafka cluster. + +For each ACL, the widget displays: + +* Principal. +* Resource type. +* Pattern. +* Pattern type. +* Host. +* Operation. +* Permission type. + +## Configuration + +| Name | Required | Description | Default value | +| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| URL | Yes | Kafka cluster URL | — | +| Authentication protocol | Yes | Protocol used to connect to Kafka. [Authentication protocol reference](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | — | +| SASL mechanism | No | Authentication mechanism used by SASL. Required when using the `SASL_PLAINTEXT` or `SASL_SSL` protocol. [SASL reference](https://kafka.apache.org/documentation/#security_sasl_mechanism) | — | +| Kafka user | Yes | Username of the account used to interact with Kafka | — | +| Password | Yes | Password of the account used to interact with Kafka | — | +| Resource types | No | Filter by resource type | — | +| Pattern types | No | Filter by pattern type | — | +| Operations | No | Filter by operation | — | +| Permission types | No | Filter by permission type | — | +| Principals | No | Filter by principal. Supports templates and regular expressions | — | +| Hosts | No | Filter by host. Supports templates and regular expressions | — | + +## Additional widget capabilities + +When actions are enabled in the settings, the widget allows users to create and delete ACL rules. + +## Authentication + +The widget requires a user account. +The system supports the following authentication methods: + +* `PLAINTEXT`. +* `SCRAM-SHA-256`. +* `SCRAM-SHA-512`. diff --git a/content/documentation/admin/widgets/kafka/acls.ru.md b/content/documentation/admin/widgets/kafka/acls.ru.md new file mode 100644 index 00000000..f263f023 --- /dev/null +++ b/content/documentation/admin/widgets/kafka/acls.ru.md @@ -0,0 +1,45 @@ +--- +title: Kafka. ACL +description: Просмотр и управление правилами контроля доступа в кластерах Kafka. +weight: 10 +--- + +Виджет отображает список правил контроля доступа (ACL) кластера Kafka. + +Для каждого ACL отображается следующая информация: + +* Субъект. +* Тип ресурса. +* Шаблон. +* Тип шаблона. +* Хост. +* Операция. +* Тип разрешения. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL кластера Kafka | — | +| Протокол аутентификации | Да | Протокол для подключения к Kafka. [Описание `security.protocol`](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | — | +| Механизм SASL | Нет | Механизм аутентификации SASL. Обязателен при использовании протокола `SASL_PLAINTEXT` или `SASL_SSL`. [Описание механизма SASL](https://kafka.apache.org/documentation/#security_sasl_mechanism) | — | +| Пользователь Kafka | Да | Имя пользователя учётной записи для взаимодействия с Kafka | — | +| Пароль | Да | Пароль учётной записи для взаимодействия с Kafka | — | +| Типы ресурсов | Нет | Фильтр по типам ресурсов | — | +| Типы шаблонов | Нет | Фильтр по типам шаблонов | — | +| Операции | Нет | Фильтр по операциям | — | +| Типы разрешений | Нет | Фильтр по типам разрешений | — | +| Субъекты | Нет | Фильтр по субъектам. Поддерживается шаблонизация и регулярные выражения | — | +| Хосты | Нет | Фильтр по хостам. Поддерживается шаблонизация и регулярные выражения | — | + +## Дополнительные возможности виджета + +Если в настройках включена функция действий, виджет позволяет создавать и удалять правила ACL. + +## Аутентификация + +Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: + +* `PLAINTEXT`. +* `SCRAM-SHA-256`. +* `SCRAM-SHA-512`. diff --git a/content/documentation/admin/widgets/kafka/topics.md b/content/documentation/admin/widgets/kafka/topics.md new file mode 100644 index 00000000..5534d588 --- /dev/null +++ b/content/documentation/admin/widgets/kafka/topics.md @@ -0,0 +1,49 @@ +--- +title: Kafka. Topics +description: Topic inspection and management capabilities for Kafka clusters. +weight: 20 +--- + +The widget displays Kafka topic data. + +The following information and actions are available for each topic: + +* General topic information, including key parameters, configuration, and status. +* Partition information, including leaders, offsets, and replica counts. +* Consumer information, including active consumers, their groups, current offsets, and lag. +* Message content. +* Message search by timestamp and offset. +* Topic configuration as a key-value table. + +## Configuration + +| Name | Required | Description | Default value | +| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| URL | Yes | Kafka cluster URL | — | +| Authentication protocol | Yes | Protocol used to connect to Kafka. [Authentication protocol reference](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | — | +| SASL mechanism | No | Authentication mechanism used by SASL. Required when using the `SASL_PLAINTEXT` or `SASL_SSL` protocol. [SASL reference](https://kafka.apache.org/documentation/#security_sasl_mechanism) | — | +| Kafka user | Yes | Username of the account used to interact with Kafka | — | +| Password | Yes | Password of the account used to interact with Kafka | — | +| Kafka topics | No | Topic name or regular expression used to filter topics displayed in the widget. If empty, all topics available to the user are displayed | — | + +## Additional widget capabilities + +When actions are enabled in the settings, the widget allows users to: + +* Create topics. +* Delete topics. +* Send a message to a topic. +* Remove all messages from a topic. + +## Authentication + +The widget requires a user account. +The system supports the following authentication methods: + +* `PLAINTEXT`. +* `SCRAM-SHA-256`. +* `SCRAM-SHA-512`. + +{{< alert level="info" >}} +The connected account's permissions determine which information is available in the widget. +{{< /alert >}} diff --git a/content/documentation/admin/widgets/kafka/topics.ru.md b/content/documentation/admin/widgets/kafka/topics.ru.md new file mode 100644 index 00000000..fa53761f --- /dev/null +++ b/content/documentation/admin/widgets/kafka/topics.ru.md @@ -0,0 +1,48 @@ +--- +title: Kafka. Топики +description: Просмотр данных и управление топиками в кластерах Kafka. +weight: 20 +--- + +Виджет отображает данные о топиках Kafka. + +Для каждого топика доступно: + +* Общая информация о топике: основные параметры, конфигурация и статус. +* Информация о разделах: лидер, смещения и количество реплик. +* Информация о потребителях: активные потребители, их группы, текущие смещения и отставание. +* Содержимое сообщений топика. +* Поиск сообщений по временной метке и смещению. +* Конфигурация топика в виде таблицы «ключ — значение». + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL кластера Kafka | — | +| Протокол аутентификации | Да | Протокол для подключения к Kafka. [Описание `security.protocol`](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | — | +| Механизм SASL | Нет | Механизм аутентификации SASL. Обязателен при использовании протокола `SASL_PLAINTEXT` или `SASL_SSL`. [Описание механизма SASL](https://kafka.apache.org/documentation/#security_sasl_mechanism) | — | +| Пользователь Kafka | Да | Имя пользователя учётной записи для взаимодействия с Kafka | — | +| Пароль | Да | Пароль учётной записи для взаимодействия с Kafka | — | +| Топики Kafka | Нет | Название топика или регулярное выражение для фильтрации отображаемых топиков в виджете. Если значение не задано, отображаются все доступные пользователю топики | — | + +## Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет: + +* создавать новые топики; +* удалять существующие топики; +* отправлять сообщение в топик; +* очищать топик от сообщений. + +## Аутентификация + +Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: + +* `PLAINTEXT`. +* `SCRAM-SHA-256`. +* `SCRAM-SHA-512`. + +{{< alert level="info" >}} +Доступность информации в виджете определяется уровнем прав подключённой учётной записи. +{{< /alert >}} diff --git a/content/documentation/admin/widgets/kaiten/_index.md b/content/documentation/admin/widgets/kaiten/_index.md new file mode 100644 index 00000000..d85cfffe --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/_index.md @@ -0,0 +1,5 @@ +--- +title: Kaiten +description: Widgets for viewing Kaiten space cards and task statistics. +weight: 110 +--- diff --git a/content/documentation/admin/widgets/kaiten/_index.ru.md b/content/documentation/admin/widgets/kaiten/_index.ru.md new file mode 100644 index 00000000..b80e951f --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Kaiten +description: Виджеты для просмотра карточек и статистики задач пространства Kaiten. +weight: 110 +--- diff --git a/content/documentation/admin/widgets/kaiten/space-cards.md b/content/documentation/admin/widgets/kaiten/space-cards.md new file mode 100644 index 00000000..9efc64ae --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/space-cards.md @@ -0,0 +1,40 @@ +--- +title: Kaiten. Space cards +description: Configuration and displayed task details for the Kaiten space cards widget. +weight: 10 +--- + +The widget displays the task structure of a Kaiten space as a multi-level **Board → Cards** table. +Use it to view tasks at every level of the work hierarchy and review key card details, +including status, urgency, blocking state, and assignees. + +## Configuration + +| Name | Required | Description | Default | +|----------|----------|------------------------------------|---------| +| Space ID | Yes | Kaiten space identifier | — | + +## Query parameters + +| Name | Required | Description | Default | +|---------------|----------|--------------------------------|-------------| +| My tasks | No | Filters by the current user | `false` | +| Created after | Yes | Start date of the query period | 1 month ago | +| Created before | Yes | End date of the query period | Now | + +## Displayed data + +Each card contains: + +- Card name. +- Column (board status). +- Status (queued, in progress, or completed). +- Lane. +- Owner (avatar, name, and email). +- Participants. +- Due date and urgency. +- Blocking state. + +## Authorization + +Authorization is described in [External services](../../external-services/#kaiten). diff --git a/content/documentation/admin/widgets/kaiten/space-cards.ru.md b/content/documentation/admin/widgets/kaiten/space-cards.ru.md new file mode 100644 index 00000000..38d44a50 --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/space-cards.ru.md @@ -0,0 +1,41 @@ +--- +title: Kaiten. Карточки пространства +description: Настройка и состав данных виджета карточек пространства Kaiten. +weight: 10 +--- + +Виджет отображает структуру задач в пространстве Kaiten +в виде многоуровневой таблицы «Доска → Карточки». +Используйте его, чтобы просматривать задачи на всех уровнях организации работы +и ключевые сведения о карточках: статус, срочность, состояние блокировки и исполнителей. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------- | -------------- | ----------------------------------- | --------------------- | +| Идентификатор пространства | Да | Идентификатор пространства в Kaiten | — | + +## Параметры запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------- | -------------- | ------------------------------- | --------------------- | +| Мои задачи | Нет | Фильтр по текущему пользователю | `false` | +| Создано после | Да | Начальная дата для выборки | 1 месяц назад | +| Создано до | Да | Конечная дата для выборки | Сейчас | + +## Отображаемые данные + +Каждая карточка содержит: + +- Название карточки. +- Колонка (статус в доске). +- Статус (очередь, в работе, готово). +- Линия. +- Владелец (аватар, имя, email). +- Участники. +- Срок выполнения и срочность. +- Состояние блокировки. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kaiten). diff --git a/content/documentation/admin/widgets/kaiten/space-stats.md b/content/documentation/admin/widgets/kaiten/space-stats.md new file mode 100644 index 00000000..3002b609 --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/space-stats.md @@ -0,0 +1,65 @@ +--- +title: Kaiten. Space statistics +description: Configuration and metrics provided by the Kaiten space statistics widget. +weight: 20 +--- + +The widget provides aggregated metrics and statistics for cards in a Kaiten space over a selected period. +Use it to analyze team performance and identify bottlenecks in business processes. + +## Configuration + +| Name | Required | Description | Default | +|----------|----------|------------------------------------|---------| +| Space ID | Yes | Kaiten space identifier | — | + +## Query parameters + +| Name | Required | Description | Default | +|----------------|----------|-----------------------------------|-------------| +| Created after | Yes | Start date of the analysis period | 1 month ago | +| Created before | Yes | End date of the analysis period | Now | + +## Displayed data + +The widget contains four tabs. + +### General metrics + +Primary metrics: + +- **Queued** — tasks waiting to be processed. +- **Completed** — completed tasks. +- **In progress** — active tasks. + +Additional metrics: + +- **Blocked** — number of blocked tasks. +- **Blocking** — number of tasks that block other tasks. +- **Archived** — number of archived tasks. +- **Urgent** — number of urgent tasks. +- **Average completion time** — average time to complete a task, in minutes. + +Checklist statistics: + +- **Total with checklists** — total number of tasks that have checklists. +- **Checklist completed** — tasks with fully completed checklists. +- **Checklist incomplete** — tasks with incomplete checklists. + +### By user + +- List of users and their assigned task counts. +- Progress bar visualization. +- Number of tasks assigned to each user. + +### Forgotten tasks + +Cards that have not been updated since they were created. + +### Recently updated + +The ten most recently updated cards. + +## Authorization + +Authorization is described in [External services](../../external-services/#kaiten). diff --git a/content/documentation/admin/widgets/kaiten/space-stats.ru.md b/content/documentation/admin/widgets/kaiten/space-stats.ru.md new file mode 100644 index 00000000..6992e47d --- /dev/null +++ b/content/documentation/admin/widgets/kaiten/space-stats.ru.md @@ -0,0 +1,65 @@ +--- +title: Kaiten. Статистика пространства +description: Настройка и показатели виджета статистики пространства Kaiten. +weight: 20 +--- + +Виджет предоставляет агрегированные метрики и статистику карточек пространства Kaiten за выбранный период. +Он позволяет анализировать эффективность работы команды и выявлять узкие места в бизнес-процессах. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------- | -------------- | ----------------------------------- | --------------------- | +| Идентификатор пространства | Да | Идентификатор пространства в Kaiten | — | + +## Параметры запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------- | -------------- | -------------------------- | --------------------- | +| Создано после | Да | Начальная дата для анализа | 1 месяц назад | +| Создано до | Да | Конечная дата для анализа | Сейчас | + +## Отображаемые данные + +Виджет содержит четыре вкладки: + +### Общие показатели + +Основные метрики: + +- «В очереди» — задачи в очереди на выполнение. +- «Выполнено» — завершённые задачи. +- «В работе» — активные задачи. + +Дополнительные метрики: + +- «Заблокировано» — количество заблокированных задач. +- «Блокирующих» — количество задач, блокирующих другие. +- «Архивировано» — количество задач в архиве. +- «Срочных» — количество срочных задач. +- «В среднем на выполнение» — среднее время выполнения в минутах. + +Статистика по чек-листам: + +- «Всего с чек-листом» — общее количество задач с чек-листами. +- «Чек-лист полностью выполнен» — задачи с полностью выполненными чек-листами. +- «Чек-лист не выполнен» — задачи с невыполненными чек-листами. + +### По пользователю + +- Список пользователей с количеством назначенных задач. +- Визуализация в виде прогресс-баров. +- Количество задач на каждого пользователя. + +### Забытые задачи + +Карточки, которые не обновлялись с момента создания. + +### Последние обновлённые + +Десять последних обновлённых карточек. + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kaiten). diff --git a/content/documentation/admin/widgets/kubernetes/_index.md b/content/documentation/admin/widgets/kubernetes/_index.md new file mode 100644 index 00000000..a4166586 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/_index.md @@ -0,0 +1,5 @@ +--- +title: Kubernetes +description: Widgets for inspecting and managing Kubernetes resources. +weight: 120 +--- diff --git a/content/documentation/admin/widgets/kubernetes/_index.ru.md b/content/documentation/admin/widgets/kubernetes/_index.ru.md new file mode 100644 index 00000000..88d6d306 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Kubernetes +description: Виджеты для просмотра и управления ресурсами Kubernetes. +weight: 120 +--- diff --git a/content/documentation/admin/widgets/kubernetes/deployments.md b/content/documentation/admin/widgets/kubernetes/deployments.md new file mode 100644 index 00000000..c3be2eb5 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/deployments.md @@ -0,0 +1,27 @@ +--- +title: Kubernetes. Deployments +description: Deployment inspection, scaling, and resource management in Kubernetes. +weight: 10 +--- + +The Kubernetes deployments widget displays key information about all Deployments in a Kubernetes cluster. +You can filter Deployments by namespace, label selector, or both. + +The following actions are available for each Deployment: + +- View the Deployment specification and status. +- Scale the number of Deployment replicas. After selecting the required number of replicas, apply the change by clicking the floppy-disk **Save** button. +- View information about pods managed by the Deployment and their containers, including logs for each container. +- View and edit container resources. The widget displays all configured container resources, including CPU, memory, `ephemeral-storage`, and other resource types. You can edit only CPU and memory in the `requests` and `limits` sections. Changes are applied at the Deployment level and propagated to all pods managed by that Deployment. Clearing a CPU or memory value removes the corresponding resource from the container configuration. Other resources, such as `ephemeral-storage`, are displayed but cannot be edited in the widget. + +## Configuration + +| Name | Required | Description | Default value | +| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| Kubernetes API | Yes | Kubernetes API server URL used to retrieve data from Kubernetes | — | +| Namespace | No | Kubernetes namespace from which Deployments are loaded. If no namespace is specified, the widget attempts to load all Deployments in the cluster. Example: `default` | — | +| Label selector | No | Comma-separated selectors used to filter Deployments. Example: `app.kubernetes.io/name=example` | — | + +## Authorization + +Authorization is described in [External services](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/deployments.ru.md b/content/documentation/admin/widgets/kubernetes/deployments.ru.md new file mode 100644 index 00000000..8989bd57 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/deployments.ru.md @@ -0,0 +1,27 @@ +--- +title: Kubernetes. Deployments +description: Просмотр, масштабирование и настройка ресурсов Deployment в Kubernetes. +weight: 10 +--- + +Виджет отображает основную информацию обо всех ресурсах Deployment в кластере Kubernetes. +Ресурсы можно фильтровать по неймспейсу, селектору лейблов или обоим параметрам. + +Для каждого ресурса Deployment доступны следующие действия: + +- Просмотр спецификации и статуса Deployment. +- Масштабирование количества реплик Deployment. После выбора требуемого количества реплик нажмите кнопку «Сохранить» с иконкой дискеты. +- Просмотр информации о подах, управляемых Deployment, и их контейнерах, включая логи каждого контейнера. +- Просмотр и редактирование ресурсов контейнеров. Виджет отображает все настроенные ресурсы контейнеров, включая CPU, memory, `ephemeral-storage` и другие типы ресурсов. Редактировать можно только CPU и memory в разделах `requests` и `limits`. Изменения применяются на уровне Deployment и распространяются на все поды, управляемые этим ресурсом. При очистке значений CPU или memory соответствующие ресурсы удаляются из конфигурации контейнера. Остальные ресурсы, например `ephemeral-storage`, отображаются, но недоступны для редактирования в виджете. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| API Kubernetes | Да | URL сервера API Kubernetes для получения данных из кластера | — | +| Неймспейс | Нет | Неймспейс Kubernetes, из которого загружаются ресурсы Deployment. Если неймспейс не указан, виджет загружает все ресурсы Deployment в кластере. Пример: `default` | — | +| Селектор лейблов | Нет | Селекторы лейблов для фильтрации ресурсов Deployment, разделённые запятыми. Пример: `app.kubernetes.io/name=example` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/ingresses.md b/content/documentation/admin/widgets/kubernetes/ingresses.md new file mode 100644 index 00000000..af01cd3b --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/ingresses.md @@ -0,0 +1,25 @@ +--- +title: Kubernetes. Ingresses +description: Ingress specification, rule, and TLS inspection in Kubernetes. +weight: 20 +--- + +The widget displays information about Ingress resources in a Kubernetes cluster. + +The following information is available for each Ingress: + +* Ingress specification as YAML configuration. +* Ingress rules. +* TLS settings. + +## Configuration + +| Name | Required | Description | Default value | +| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| URL | Yes | Kubernetes API server URL used to retrieve data from Kubernetes | — | +| Namespace | No | Kubernetes namespace from which Ingress resources are loaded. If no namespace is specified, the widget attempts to load all Ingress resources in the cluster. Example: `default` | — | +| Label selector | No | Comma-separated selectors used to filter Ingress resources. Example: `app.kubernetes.io/name=example` | — | + +## Authorization + +Authorization is described in [External services](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/ingresses.ru.md b/content/documentation/admin/widgets/kubernetes/ingresses.ru.md new file mode 100644 index 00000000..d79c02bf --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/ingresses.ru.md @@ -0,0 +1,25 @@ +--- +title: Kubernetes. Ingresses +description: Просмотр спецификации, правил и настроек TLS для ресурсов Ingress в Kubernetes. +weight: 20 +--- + +Виджет отображает данные о ресурсах Ingress в кластере Kubernetes. + +Для каждого Ingress доступны: + +* Просмотр спецификации Ingress в виде YAML-конфигурации. +* Правила Ingress. +* Настройки TLS. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL сервера API Kubernetes для получения данных из кластера | — | +| Неймспейс | Нет | Неймспейс Kubernetes, из которого загружаются ресурсы Ingress. Если неймспейс не указан, виджет загружает все ресурсы Ingress в кластере. Пример: `default` | — | +| Селектор лейблов | Нет | Селекторы лейблов для фильтрации ресурсов Ingress, разделённые запятыми. Пример: `app.kubernetes.io/name=example` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/pods.md b/content/documentation/admin/widgets/kubernetes/pods.md new file mode 100644 index 00000000..928aa76a --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/pods.md @@ -0,0 +1,25 @@ +--- +title: Kubernetes. Pods +description: Pod status, specification, and log inspection in Kubernetes. +weight: 30 +--- + +The widget displays information about pods in a Kubernetes cluster. + +The following information is available for each pod: + +* Pod specification as YAML configuration. +* Container logs. +* Pod state information, including status and restart count. + +## Configuration + +| Name | Required | Description | Default value | +| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------------- | +| URL | Yes | Kubernetes API server URL used to retrieve data from Kubernetes | — | +| Namespace | No | Namespace from which the widget loads data. Example: `default` | — | +| Label selector | No | Comma-separated selectors used to filter pods. Example: `app.kubernetes.io/name=example` | — | + +## Authorization + +Authorization is described in [External services](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/pods.ru.md b/content/documentation/admin/widgets/kubernetes/pods.ru.md new file mode 100644 index 00000000..f8c14009 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/pods.ru.md @@ -0,0 +1,25 @@ +--- +title: Kubernetes. Pods +description: Просмотр статуса, спецификации и логов подов в Kubernetes. +weight: 30 +--- + +Виджет отображает данные о подах в кластере Kubernetes. + +Для каждого пода доступны: + +* Просмотр спецификации пода в виде YAML-конфигурации. +* Логи контейнеров. +* Информация о состоянии пода, включая статус и количество перезапусков. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL сервера API Kubernetes для получения данных из кластера | — | +| Неймспейс | Нет | Неймспейс, из которого виджет загружает данные. Пример: `default` | — | +| Селектор лейблов | Нет | Селекторы лейблов для фильтрации подов, разделённые запятыми. Пример: `app.kubernetes.io/name=example` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/quotas.md b/content/documentation/admin/widgets/kubernetes/quotas.md new file mode 100644 index 00000000..b999cc44 --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/quotas.md @@ -0,0 +1,20 @@ +--- +title: Kubernetes. Resource quotas +description: Resource quota usage visualization for Kubernetes namespaces. +weight: 40 +--- + +The widget displays resource quota data from a Kubernetes cluster. + +For each quota, the widget visualizes the resources in use. + +## Configuration + +| Name | Required | Description | Default value | +| --------- | -------- | ----------------------------------------------------------------------- | ------------- | +| URL | Yes | Kubernetes API server URL used to retrieve data from Kubernetes | — | +| Namespace | Yes | Namespace from which the widget loads data. Example: `default` | — | + +## Authorization + +Authorization is described in [External services](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/kubernetes/quotas.ru.md b/content/documentation/admin/widgets/kubernetes/quotas.ru.md new file mode 100644 index 00000000..8bf9161b --- /dev/null +++ b/content/documentation/admin/widgets/kubernetes/quotas.ru.md @@ -0,0 +1,20 @@ +--- +title: Kubernetes. Квоты ресурсов +description: Визуализация использования квот ресурсов в неймспейсах Kubernetes. +weight: 40 +--- + +Виджет отображает данные о квотах ресурсов в кластере Kubernetes. + +Виджет показывает используемые ресурсы для каждой квоты. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------- | -------------- | --------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL сервера API Kubernetes для получения данных из кластера | — | +| Неймспейс | Да | Неймспейс, из которого виджет загружает данные. Пример: `default` | — | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#kubernetes). diff --git a/content/documentation/admin/widgets/overview.md b/content/documentation/admin/widgets/overview.md new file mode 100644 index 00000000..c9d8a8f1 --- /dev/null +++ b/content/documentation/admin/widgets/overview.md @@ -0,0 +1,30 @@ +--- +title: Overview +description: Widget purpose, scope, credentials, and configuration principles +weight: 10 +--- + +Widgets are cards that visualize data stored in the platform and information from infrastructure services. Unlike data sources, widgets retrieve information from infrastructure services when they are displayed in the interface. + +Widgets can be added to dashboards. Dashboards can be linked to: + +- static pages, such as the Catalog, Self-service, Home, and Administration pages; +- entity cards. + +## Configuration + +A widget configuration includes common parameters and fields specific to the widget type. + +Widget configurations support [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax) syntax for templating during widget processing. For example: + +* `{{ .entity.name }}` — substitutes the value of the entity's `name` parameter. +* `{{ .credentials.token }}` — substitutes credentials named `token`. + +You can set a scope for each widget: + +* `Global` — the widget cannot retrieve entity parameters using [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax). +* `Resource` — the widget can retrieve entity parameters using [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax). Widgets with the `Resource` scope can only be attached to entity pages. + +In the widget configuration, you can specify the account whose credentials the widget uses to interact with infrastructure systems and select the credentials type. + +If no account is specified, the widget uses the credentials of the current user. diff --git a/content/documentation/admin/widgets/overview.ru.md b/content/documentation/admin/widgets/overview.ru.md index 49533a61..ca1c5f31 100644 --- a/content/documentation/admin/widgets/overview.ru.md +++ b/content/documentation/admin/widgets/overview.ru.md @@ -1,13 +1,14 @@ --- title: Обзор +description: Назначение, области видимости и принципы конфигурации виджетов weight: 10 --- Виджеты — карточки для визуализации данных, хранящихся в платформе, а также информации из инфраструктурных сервисов. В отличие от источников данных, виджеты получают информацию из инфраструктурных сервисов непосредственно в момент их отображения в интерфейсе. -Виджеты могут быть добавлены на дашборды; дашборды, в свою очередь, могут быть привязаны: +Виджеты могут быть добавлены на дашборды. Дашборды, в свою очередь, могут быть привязаны: -- к статическим страницам (каталог, самообслуживание, главная страница, администрирование); +- к статическим страницам ((«Каталог», «Самообслуживание», «Главная страница», «Администрирование»); - к карточкам сущностей. ## Конфигурация @@ -16,13 +17,13 @@ weight: 10 В конфигурации поддерживается использование синтаксиса [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax) для шаблонизации при обработке виджета, например: -* `{{ .entity.name }}` — подстановка значения параметра сущности «name». -* `{{ .credentials.token }}` — подстановка учётных данных с названием «token». +* `{{ .entity.name }}` — подстановка значения параметра сущности `name`. +* `{{ .credentials.token }}` — подстановка учётных данных с названием `token`. Для каждого виджета доступно задание области видимости: -* «Global» — виджет не поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax); -* «Resource» — виджет поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax). Виджеты с областью видимости Resource можно прикрепить только к страницам сущности. +* `Global` — виджет не поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax); +* `Resource` — виджет поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax). Виджеты с областью видимости `Resource` можно прикрепить только к страницам сущности. В конфигурации виджетов возможно задание учётной записи, с данными которой виджет будет взаимодействовать с инфраструктурными системами, а также выбрать тип учётных данных, который будет использоваться. diff --git a/content/documentation/admin/widgets/prometheus/_index.md b/content/documentation/admin/widgets/prometheus/_index.md new file mode 100644 index 00000000..9cc70f17 --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/_index.md @@ -0,0 +1,5 @@ +--- +title: Prometheus +description: Widgets for visualizing metrics queried from Prometheus. +weight: 130 +--- diff --git a/content/documentation/admin/widgets/prometheus/_index.ru.md b/content/documentation/admin/widgets/prometheus/_index.ru.md new file mode 100644 index 00000000..d8ffd852 --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/_index.ru.md @@ -0,0 +1,5 @@ +--- +title: Prometheus +description: Виджеты для визуализации метрик из Prometheus. +weight: 130 +--- diff --git a/content/documentation/admin/widgets/prometheus/metrics-range.md b/content/documentation/admin/widgets/prometheus/metrics-range.md new file mode 100644 index 00000000..dc611317 --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/metrics-range.md @@ -0,0 +1,45 @@ +--- +title: Prometheus. Metrics (range) +description: Time-series chart based on a PromQL range query to Prometheus. +weight: 10 +--- + +The widget plots a chart from the result of a Prometheus `query_range` query. +The PromQL query must return a `Matrix` type containing one or more time series. + +Example query with placeholders: + +```promql +sum by (status) (rate(http_requests_total[{{rateInterval}}])) +``` + +## Query placeholders + +The widget substitutes values calculated from the active time range: + +| Placeholder | Description | +| ------------------ | ------------------------------------------------------------------ | +| `{{range}}` | Duration of the selected time range | +| `{{rateInterval}}` | Range window for the `rate()` and `increase()` functions | +| `{{interval}}` | Interval between chart points, calculated automatically | + +The query step is selected based on the time range duration. +The chart contains no more than 1100 points, and the minimum step is 30 seconds. +The **Resolution step** configuration field is no longer used. + +## Configuration + +| Name | Required | Description | Default value | +| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------- | ------------- | +| URL | Yes | Prometheus URL | — | +| Query | Yes | PromQL query for the range chart | — | +| Label | Yes | Prometheus label name used as the series name in the chart legend | — | +| Default range | No | Range used when loading or refreshing the widget unless the user selects another range in the widget panel | Last hour | +| Threshold | No | Horizontal dashed line on the chart | — | +| Minimum value | No | Lower Y-axis boundary. Leave empty to scale automatically | — | +| Maximum value | No | Upper Y-axis boundary. Leave empty to scale automatically | — | +| `InsecureSkipVerify` | No | Disables verification of the Prometheus TLS/SSL certificate | `false` | + +## Authorization + +Authorization is described in [External services](../../external-services/#prometheus). diff --git a/content/documentation/admin/widgets/prometheus/metrics-range.ru.md b/content/documentation/admin/widgets/prometheus/metrics-range.ru.md new file mode 100644 index 00000000..6f2ef433 --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/metrics-range.ru.md @@ -0,0 +1,42 @@ +--- +title: Prometheus. Метрики (диапазон) +description: График временных рядов на основе диапазонного PromQL-запроса к Prometheus. +weight: 10 +--- + +Виджет строит график по результату запроса `query_range` к Prometheus. Запрос в формате PromQL должен возвращать тип `Matrix` (одну или несколько временных серий). + +Пример запроса с плейсхолдерами: + +```promql +sum by (status) (rate(http_requests_total[{{rateInterval}}])) +``` + +## Плейсхолдеры в запросе + +Виджет подставляет в запрос значения, рассчитанные из активного интервала: + +| Плейсхолдер | Описание | +| ------------------ | ----------------------------------------------------------- | +| `{{range}}` | Длительность выбранного интервала | +| `{{rateInterval}}` | Окно диапазона для функций `rate()` и `increase()` | +| `{{interval}}` | Шаг между точками на графике (рассчитывается автоматически) | + +Шаг запроса выбирается по длительности интервала (не более 1100 точек на графике, минимум 30 секунд). Поле «Шаг разрешения» в конфигурации больше не используется. + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- | +| URL | Да | URL Prometheus | — | +| Запрос | Да | PromQL-запрос для графика диапазона | — | +| Лейбл | Да | Имя лейбла Prometheus, используемое как название серии в легенде графика | — | +| Интервал по умолчанию | Нет | Интервал при загрузке виджета и при обновлении, если пользователь не выбрал другой диапазон в панели виджета | Последний час | +| Пороговое значение | Нет | Горизонтальная пунктирная линия на графике | — | +| Минимальное значение | Нет | Нижняя граница оси Y. Оставьте пустым для автоматического масштабирования | — | +| Максимальное значение | Нет | Верхняя граница оси Y. Оставьте пустым для автоматического масштабирования | — | +| `InsecureSkipVerify` | Нет | Отключение проверки подлинности TLS/SSL-сертификата Prometheus | `false` | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#prometheus). diff --git a/content/documentation/admin/widgets/prometheus/metrics-single.md b/content/documentation/admin/widgets/prometheus/metrics-single.md new file mode 100644 index 00000000..d4496335 --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/metrics-single.md @@ -0,0 +1,51 @@ +--- +title: Prometheus. Metrics (single value) +description: Single-value metric based on a PromQL query to Prometheus. +weight: 20 +--- + +The widget displays a single number from a PromQL query to Prometheus. +The query must return a `Scalar` or a `Vector` containing one value. + +Example query without placeholders: + +```promql +sum(machine_cpu_cores) +``` + +Example with a placeholder for the time range duration selected in the widget panel: + +```promql +sum(increase(http_requests_total[{{range}}])) +``` + +## Query placeholders + +Use placeholders when the expression requires the duration of the time range selected in the widget panel. +The query runs at the end of this time range. + +| Placeholder | Description | +| ------------------ | --------------------------------------------------------- | +| `{{range}}` | Duration of the selected time range | +| `{{rateInterval}}` | Range window for the `rate()` and `increase()` functions | +| `{{interval}}` | Query step calculated from the time range | + +## Configuration + +| Name | Required | Description | Default value | +| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------- | +| URL | Yes | Prometheus URL | — | +| Query | Yes | PromQL query that returns one value | — | +| Default range | No | Range used when loading or refreshing the widget unless the user selects another range in the widget panel | Last hour | +| Decimal places | No | Precision used to display the returned value | — | +| Unit | No | Suffix displayed with the returned value | — | +| Show threshold | No | Displays ` / `, where `` is the current metric value and `` is the configured threshold | `false` | +| Threshold | No | Threshold value | — | +| Lower value is better | No | Considers the metric healthy when its value is below the configured threshold | `false` | +| Warning threshold (%) | No | Boundary between red and orange. A metric value above this percentage of the threshold is displayed in orange | 60 | +| Success threshold (%) | No | Boundary between orange and green. A metric value above this percentage of the threshold is displayed in green | 90 | +| `InsecureSkipVerify` | No | Disables verification of the Prometheus TLS/SSL certificate | `false` | + +## Authorization + +Authorization is described in [External services](../../external-services/#prometheus). diff --git a/content/documentation/admin/widgets/prometheus/metrics-single.ru.md b/content/documentation/admin/widgets/prometheus/metrics-single.ru.md new file mode 100644 index 00000000..b6fbbb1f --- /dev/null +++ b/content/documentation/admin/widgets/prometheus/metrics-single.ru.md @@ -0,0 +1,50 @@ +--- +title: Prometheus. Метрики (значение) +description: Одиночное значение метрики на основе PromQL-запроса к Prometheus. +weight: 20 +--- + +Виджет показывает одно число по PromQL-запросу к Prometheus. +Запрос должен возвращать тип `Scalar` или тип `Vector` с одним значением. + +Пример запроса без плейсхолдеров: + +```promql +sum(machine_cpu_cores) +``` + +Пример с плейсхолдером (длительность интервала из панели виджета): + +```promql +sum(increase(http_requests_total[{{range}}])) +``` + +## Плейсхолдеры в запросе + +Используйте плейсхолдеры, если в выражении нужна длительность интервала, выбранного в панели виджета. Запрос выполняется на момент окончания этого интервала. + +| Плейсхолдер | Описание | +| ------------------ | -------------------------------------------------- | +| `{{range}}` | Длительность выбранного интервала | +| `{{rateInterval}}` | Окно диапазона для функций `rate()` и `increase()` | +| `{{interval}}` | Шаг запроса, рассчитанный из интервала | + +## Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +| -------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| URL | Да | URL Prometheus | — | +| Запрос | Да | PromQL-запрос, возвращающий одно значение | — | +| Интервал по умолчанию | Нет | Интервал при загрузке виджета и при обновлении, если пользователь не выбрал другой диапазон в панели виджета | Последний час | +| Количество цифр после запятой | Нет | Точность отображения полученного значения | — | +| Единица измерения | Нет | Постфикс, с которым отображается полученное значение | — | +| Отображать пороговое значение | Нет | Отображает ` / `, где `` — текущее значение метрики, а `` — настроенный порог | `false` | +| Пороговое значение | Нет | Пороговое значение | — | +| Меньшее значение считается лучше | Нет | Метрика считается «хорошей», когда её значение ниже заданного порогового значения | `false` | +| Порог предупреждения (%) | Нет | Граница между красным и оранжевым цветами. Если значение метрики превышает этот процент от порога, оно получит оранжевый цвет | 60 | +| Порог успеха (%) | Нет | Граница между оранжевым и зелёным цветами. Если значение метрики превышает этот процент от порога, оно получит зелёный цвет | 90 | +| `InsecureSkipVerify` | Нет | Отключение проверки подлинности TLS/SSL-сертификата Prometheus | `false` | + +## Авторизация + +Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#prometheus). diff --git a/content/documentation/admin/widgets/types.ru.md b/content/documentation/admin/widgets/types.ru.md deleted file mode 100644 index 8727fa5f..00000000 --- a/content/documentation/admin/widgets/types.ru.md +++ /dev/null @@ -1,1910 +0,0 @@ ---- -title: Типы виджетов ---- - -### AI-чат - -Виджет «AI-чат» позволяет отправлять запросы к языковой модели через выбранный AI-провайдер: задаются общие инструкции («Глобальный промпт») и набор кнопок быстрых вопросов («Быстрые вопросы»). - -#### Конфигурация - -| Название | Обязательность | Описание | -|---------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------| -| Глобальный промпт | Нет | Общие инструкции к каждому запросу; при отправке объединяются с промптом выбранной кнопки быстрого вопроса. | -| Быстрые вопросы | Да | Набор кнопок с подписью и текстом промпта (до 20 штук); для корректной работы виджета необходимо добавить хотя бы один вопрос. | - -Для каждого быстрого вопроса задаются поля: - -| Название | Обязательность | Описание | -|------------------|----------------|----------------------------------------------------------------------------------------------| -| Название вопроса | Да | Короткая подпись, отображается на нижней панели виджета и в чате. | -| Промпт | Да | Инструкция для модели при нажатии на эту кнопку; допускается использование Go-шаблонизации. | - -При заполнении промпта рекомендуется в явном виде указывать названия MCP-инструментов, которые должна вызвать модель при подготовке ответа. - -Пример промпта для быстрого вопроса: - -```sh -1. Вызови MCP tool get_external_data для внешнего сервиса «Deckhouse Code» и получи пайплайны для проекта с ID {{ .entity.properties.deckhouse_code_id }}. -2. Выведи таблицу с последними 10 пайплайнами. -``` - -#### Использование виджета - -Для использования виджета у пользователя должен быть добавлен как минимум один [AI-провайдер](../../user/ai-assistant/#подключение-ai-провайдера). - -У чата не предусмотрена история: - -- Выводится только один ответ на последний заданный вопрос. -- Ответ не сохраняется при переходе на другую страницу или при обновлении страницы. - -Перед отправкой вопроса пользователь может кастомизировать промпт, кликнув на пункт «Отправить с изменением промпта» в выпадающем меню кнопки вопроса. - -### API - -Виджет позволяет вывести спецификацию API из файла в репозитории GitLab или по ссылке в формате OpenAPI (Swagger) или Protobuf. При выводе спецификации OpenAPI из файла в формате YAML или JSON виджет отображает интерфейс Swagger. Во всех остальных случаях виджет отображает спецификацию в виде текста. - -#### Общая конфигурация - -| Название | Обязательность | Описание | Возможные значения | Значение по умолчанию | -|-------------------|----------------|--------------------------------------------------------------------|--------------------------------------|-----------------------| -| Тип спецификации | Да | Тип спецификации | OpenAPI (Swagger), Protocol Buffers | - | -| Тип источника | Да | Тип источника, из которого будет загружаться файл со спецификацией | URL, GitLab | - | - -#### Конфигурация типа источника: URL - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------|----------------|------------------------------------------------|-----------------------| -| URL | Да | Ссылка на файл со спецификацией | - | -| Заголовки | Нет | Заголовки для доступа к файлу со спецификацией | - | - -#### Конфигурация типа источника: GitLab - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------|----------------|------------------------------------------------------------------------|-----------------------| -| GitLab URL | Да | URL GitLab | - | -| ID проекта | Да | Идентификатор проекта, из которого будет браться файл со спецификацией | - | -| Ветка | Да | Ветка, из которой будет браться файл со спецификацией | - | -| Путь к файлу | Да | Путь к файлу со спецификацией относительно корня репозитория | - | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -### Bitbucket. Pull Requests - -Виджет позволяет отображать данные о Pull Requests (PR) в Bitbucket и выполнять действия с ними. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#bitbucket). - -#### Конфигурация - -| Название | Обязательность | Описание | Пример | -|---------------------------|-----------------|----------------------------------------------------------|------------------------------------------------------------------------| -| Ключ проекта | Да | Часть URL репозитория, которая идёт сразу после `/projects/` | Для репозитория `.../projects/MYTEAM/repos/backend` укажите `MYTEAM` | -| Идентификатор репозитория | Да | Часть URL репозитория, которая идёт сразу после `/repos/` | Для репозитория `.../projects/MYTEAM/repos/backend` укажите `backend` | - -#### Фильтрация по статусу - -Виджет позволяет фильтровать отображаемые Pull Requests по статусу. В настройках запроса виджета можно выбрать один из следующих статусов: - -- «Открыт» — показывает только открытые PR. -- «Слит» — показывает только слитые PR. -- «Отклонён» — показывает только отклонённые PR. -- «Все» — показывает PR в любом статусе. - -По умолчанию отображаются только открытые PR. - -#### Дополнительные возможности виджета - -При активированной функции действий в настройках виджет позволяет выполнять следующие действия с Pull Requests: - -- «Слить» — слияние открытого запроса на слияние (доступно только для открытых PR). -- «Закрыть» — отклонение (decline) запроса на слияние. -- «Просмотр изменений» — просмотр диффа (изменений) в запросе на слияние. -- «Комментарии» — просмотр и добавление комментариев к PR. -- «Создать PR» — создание нового Pull Request с указанием исходной и целевой ветки, ревьюеров, названия и описания. - -{{< alert level="info" >}} -Для выполнения действий с PR требуются соответствующие права доступа в репозитории Bitbucket. -{{< /alert >}} - -### GitHub. Pull Requests - -Виджет отображает Pull Requests (PR) репозитория на GitHub и позволяет просматривать изменения, создавать, сливать и закрывать PR. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#github). -В настройках внешнего сервиса или в конфигурации виджета в поле «URL» необходимо указать `https://api.github.com`. - -#### Учётная запись и автор действий - -Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. - -При создании, слиянии и закрытии Pull Request в GitHub автором PR и исполнителем действий считается учётная запись GitHub, которой принадлежит этот токен. Логин и имя в интерфейсе GitHub могут не совпадать с именем в профиле Deckhouse Development Platform (DDP). - -#### Конфигурация - -| Название | Обязательность | Описание | Пример | -|----------------------|----------------|------------------------------------------------------|------------------------------------------------------------| -| Владелец репозитория | Да | Владелец репозитория (организация или пользователь). | Для `https://github.com/example/my-repo` укажите `example` | -| Репозиторий | Да | Название репозитория без `.git`. | Для `https://github.com/example/my-repo` укажите `my-repo` | - -#### Статус - -В настройках запроса виджета можно фильтровать PR по статусу: - -- «Открыт» — только открытые PR (не черновики). -- «Черновик» — только черновики. -- «Закрыт» — только закрытые PR. -- «Все» — любые PR. - -По умолчанию отображаются открытые PR. В таблице отображаются: номер, название, описание, статус, метки, автор, дата создания, дата обновления; для каждого PR доступны действия через меню. - -#### Действия - -- «Изменения» — просмотр списка изменённых файлов и диффа по каждому файлу. -- «Слить» — слияние открытого PR (доступно только для открытых PR, не черновиков). -- «Закрыть» — закрытие PR без слияния. -- «Создать PR» — создание нового Pull Request. В диалоге указываются название, исходная ветка, целевая ветка и описание. - -{{< alert level="info" >}} -Для выполнения действий с PR требуются соответствующие права доступа в репозитории GitHub. -{{< /alert >}} - -### GitHub. Actions - -Виджет показывает запуски GitHub Actions в репозитории и позволяет просматривать jobs, артефакты, а также производить действия над ними. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#github). -В настройках внешнего сервиса в поле «URL» необходимо указать `https://api.github.com`. - -#### Учётная запись и автор действий - -Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. - -При запуске, отмене запуска и перезапуске workflow, работе с артефактами и логами в GitHub инициатором считается учётная запись GitHub, которой принадлежит токен. Логин в интерфейсе GitHub может не совпадать с именем в профиле DDP. - -#### Конфигурация - -| Название | Обязательность | Описание | Пример | -|----------------------|----------------|------------------------------------------------------|------------------------------------------------------------| -| Владелец репозитория | Да | Владелец репозитория (организация или пользователь). | Для `https://github.com/example/my-repo` укажите `example` | -| Репозиторий | Да | Название репозитория без `.git`. | Для `https://github.com/example/my-repo` укажите `my-repo` | - -#### Параметры запроса - -В настройках запроса виджета можно задать фильтры: - -- «Ветка» — только запуски с указанной head-веткой. -- «Событие» — только запуски с выбранным типом события. -- «Статус» — только запуски в выбранном статусе или с выбранным итогом (conclusion). -- «Workflow» — только запуски для выбранного файла workflow. -- «Кто запустил» — только запуски, начатые указанным пользователем GitHub. -- «Фильтр по дате создания» — интервал дат создания запуска (дата начала и дата окончания). - -#### Действия - -В виджете доступны следующие действия: - -- «Запустить workflow» — ручной запуск workflow с триггером `workflow_dispatch`: выбираются «Workflow» и «Ветка или тег»; при объявленных во входном YAML параметрах отображаются «Входные параметры». -- «Перезапустить workflow», «Перезапустить упавшие jobs», «Отменить workflow» — для выбранного запуска. -- «Перезапустить job» — для job в статусе «завершён» с итогом failure или cancelled. -- Просмотр логов job, скачивание артефактов, открытие запуска на GitHub, дерево jobs и шагов. - -{{< alert level="info" >}} -Для действий с workflow и артефактами нужны соответствующие права в репозитории GitHub. -{{< /alert >}} - -### CodeScoring. Зависимости - -Виджет позволяет вывести таблицу с зависимостями продукта на основе данных из CodeScoring с указанием названия зависимости, версии, лицензии, количества уязвимостей и другой информации для каждой зависимости. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#codescoring). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|-----------------|-------------------------------------|-----------------------| -| URL | Да | URL CodeScoring | - | -| ID проекта | Да | Идентификатор проекта в CodeScoring | - | - -### CodeScoring. Уязвимости - -Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из CodeScoring с указанием кода уязвимости, уровня критичности, наличия эксплойта, исправленной версии для каждой уязвимости. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#codescoring). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|-----------------|-------------------------------------|-----------------------| -| URL | Да | URL CodeScoring | - | -| ID проекта | Да | Идентификатор проекта в CodeScoring | - | - -### CodeScoring. Секреты - -Виджет позволяет вывести таблицу найденных секретов проекта из CodeScoring. Поддерживаются запуск либо отмена сканирования секретов по выбранной ветке или тегу. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#codescoring). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|-----------------|-------------------------------------|-----------------------| -| URL | Да | URL CodeScoring | - | -| ID проекта | Да | Идентификатор проекта в CodeScoring | - | - -### ClickHouse. Метрики (диапазон) - -Виджет позволяет построить линейный график на основе read-only SQL-запроса к ClickHouse. В запросе можно использовать плейсхолдеры `{{from}}` и `{{to}}` для подстановки границ временного интервала. - -Пример корректного запроса для виджета: - -```sql -SELECT - toStartOfMinute(timestamp) AS time, - avg(value) AS value, - service AS series -FROM metrics -WHERE timestamp >= {{from}} AND timestamp < {{to}} -GROUP BY time, series -ORDER BY time -``` - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Запрос | Да | Read-only SQL-запрос. Используйте `{{from}}` и `{{to}}` для подстановки интервала | - | -| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | - | -| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | -| Колонка времени | Да | Колонка с меткой времени для оси X графика | - | -| Колонка значения | Да | Колонка с числовыми значениями для оси Y графика | - | -| Колонка серии | Нет | Колонка, используемая как название серии в легенде графика | - | -| Пороговое значение | Нет | Порог, отображаемый в виде горизонтальной линии на графике | - | -| Минимальное значение | Нет | Начальная точка отсчёта для вертикальной оси графика | - | -| Максимальное значение | Нет | Предельная точка отсчёта для вертикальной оси графика | - | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#clickhouse). - -### ClickHouse. Метрики (значение) - -Виджет позволяет вывести одно число на основе read-only SQL-запроса к ClickHouse, задать для него единицу измерения и настроить пороговое значение. Запрос должен возвращать одну строку; отображается значение первой колонки. - -Пример корректного запроса для виджета: - -```sql -SELECT count() AS value -FROM events -WHERE timestamp >= {{from}} AND timestamp < {{to}} -``` - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Запрос | Да | Read-only SQL-запрос. Используйте `{{from}}` и `{{to}}` для подстановки интервала | - | -| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | - | -| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | -| Количество цифр после запятой | Нет | Точность, с которой будет выводиться полученное значение | - | -| Единица измерения | Нет | Постфикс, с которым будет выводиться полученное значение | - | -| Отображать пороговое значение | Нет | Отображать пороговое значение в формате <значение метрики> / <пороговое значение> | false | -| Пороговое значение | Нет | Пороговое значение | - | -| Меньшее значение считается лучше | Нет | Метрика считается «хорошей», когда её значение ниже заданного порогового значения | false | -| Порог предупреждения (%) | Нет | Граница между красным и оранжевым цветами. Если значение метрики превышает этот процент от порога, оно получит оранжевый цвет | 60 | -| Порог успеха (%) | Нет | Граница между оранжевым и зелёным цветами. Если значение метрики превышает этот процент от порога, оно получит зелёный цвет | 90 | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#clickhouse). - -### ClickHouse. Таблица - -Виджет позволяет вывести результат read-only SQL-запроса к ClickHouse в виде таблицы с сортировкой и постраничной навигацией. В запросе можно использовать плейсхолдеры `{{from}}` и `{{to}}`. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------------|----------------|------------------------------------------------------------------------------------------------------------|-----------------------| -| Запрос | Да | Read-only SQL-запрос. Используйте `{{from}}` и `{{to}}` для подстановки интервала | - | -| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | - | -| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | -| Размер страницы | Да | Количество строк, загружаемых за один запрос | 50 | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#clickhouse). - -### ClickHouse. Топ N - -Виджет позволяет построить горизонтальную столбчатую диаграмму на основе read-only SQL-запроса к ClickHouse. Запрос должен возвращать колонки с метками и числовыми значениями; количество отображаемых строк ограничивается параметром «Лимит». - -Пример корректного запроса для виджета: - -```sql -SELECT service AS label, count() AS value -FROM events -WHERE timestamp >= {{from}} AND timestamp < {{to}} -GROUP BY label -ORDER BY value DESC -``` - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------------|----------------|------------------------------------------------------------------------------------------------------------|-----------------------| -| Запрос | Да | Read-only SQL-запрос. Используйте `{{from}}` и `{{to}}` для подстановки интервала | - | -| База данных | Нет | Название базы ClickHouse, передаётся в заголовке `X-ClickHouse-Database` | - | -| Интервал по умолчанию | Нет | Интервал, используемый при открытии виджета и при обновлении, если в параметрах запроса интервал не задан | Последний час | -| Колонка метки | Да | Колонка для подписей столбцов диаграммы | - | -| Колонка значения | Да | Колонка с числовыми значениями для длины столбцов | - | -| Лимит | Да | Максимальное количество строк для диаграммы | 10 | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#clickhouse). - -### DefectDojo. Продукт - -Виджет позволяет просматривать уязвимости продукта в DefectDojo с разбивкой по engagements и уровням критичности. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#defectdojo). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------| -| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | - | -| Название продукта | Да | Название продукта в DefectDojo | - | -| Уровни уязвимостей | Да | Уровни критичности уязвимостей, которые подгружаются при открытии виджета и при смене engagement | Critical, High, Medium, Low, Info | - -#### Параметры запроса - -В настройках запроса виджета можно изменить уровни уязвимостей — загружаются только уязвимости выбранных уровней критичности. По умолчанию используются уровни из конфигурации виджета. Изменение уровней приводит к повторной загрузке данных из DefectDojo. - -#### Дополнительные возможности виджета - -##### Фильтры - -* «Engagement» — выбор engagement продукта. По умолчанию выбирается последний созданный engagement (с наибольшим идентификатором). При смене engagement данные перезагружаются. -* «Фильтры» — панель фильтров по уровням критичности, тегам, тестам и компонентам. Фильтры по тегам, тестам и компонентам применяются только к уже загруженным уязвимостям и не вызывают новых запросов к DefectDojo. - -##### Вкладки - -* «Обзор» — уязвимости по уровню критичности, по тегам (топ-10), по тестам (топ-10), по компонентам (топ-10). Диаграммы строятся по отфильтрованному набору уязвимостей. -* «Детали» — таблица уязвимостей с деталями по каждой из них. - -{{< alert level="info" >}} -Если уязвимостей для выбранного engagement и уровней критичности больше 1000, в виджете отображаются первые 1000 записей и предупреждение о частичной загрузке. Фильтры по тегам, тестам и компонентам действуют только в пределах загруженного набора. -{{< /alert >}} - -### DefectDojo. Уязвимости в продукте (детали) - -Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из DefectDojo с указанием уровня критичности, описания и даты обнаружения для каждой уязвимости. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#defectdojo). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|-----------------|--------------------------------------------------------|-----------------------| -| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | - | -| Название продукта | Да | Название продукта в DefectDojo | - | - -#### Дополнительные возможности виджета - -При просмотре виджета доступна настройка следующих параметров: - -* «Активные уязвимости» — если включено, то загружаются уязвимости продукта с флагом ‘Active’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Active’ = false. Включено по умолчанию. -* «Дублирующиеся уязвимости» — если включено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = false. Отключено по умолчанию. - -### DefectDojo. Уязвимости в продукте (общая статистика) - -Виджет позволяет вывести график с общим количеством уязвимостей продукта на основе информации из DefectDojo с разбивкой по уровням критичности. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#defectdojo). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL DefectDojo. Указывается без пути к API (`/api/v2`) | - | -| Название продукта | Да | Название продукта в DefectDojo | - | - -#### Дополнительные возможности виджета - -При просмотре виджета доступна настройка следующих параметров: - -* «Активные уязвимости» — если включено, то загружаются уязвимости продукта с флагом ‘Active’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Active’ = false. Включено по умолчанию. -* «Дублирующиеся уязвимости» — если включено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = false. Отключено по умолчанию. - -### Docker образы - -Виджет позволяет отображать данные о доступных образах в docker registry. На виджет выводятся все доступные теги и команда docker pull. Поддерживается поиск. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#docker-registry). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Docker Registry. Используется для получения данных о доступных образах | - | -| Название | Нет | Название репозитория, из которого будут загружаться данные в виджет. Пример: `repo`. Без указания названия, будут получены все доступные образы | - | - -### GitLab. Запросы слияния - -Виджет позволяет отображать данные о Merge Requests (MR) в платформе GitLab и выполнять действия с ними. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL GitLab API. Используется для получения данных из GitLab | - | -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Фильтрация по статусу - -Виджет позволяет фильтровать отображаемые Merge Requests по статусу. В настройках запроса виджета можно выбрать один из следующих статусов: - -- «Открытые» — показывает только открытые MR. -- «Закрытые» — показывает только закрытые MR. -- «Слитые» — показывает только слитые MR. -- «Заблокированные» — показывает только заблокированные MR. - -По умолчанию отображаются только открытые MR. - -#### Дополнительные возможности виджета - -При активированной функции действий в настройках виджет позволяет выполнять следующие действия с Merge Requests: - -- «Слить» — слияние открытого запроса на слияние (доступно только для открытых MR). -- «Закрыть» — закрытие запроса на слияние. -- «Отметить как черновик/готово» — изменение статуса черновика запроса на слияние. -- «Просмотр изменений» — просмотр диффа (изменений) в запросе на слияние. - -{{< alert level="info" >}} -Для выполнения действий с MR требуются соответствующие права доступа в репозитории GitLab. -{{< /alert >}} - -### GitLab. Пайплайны - -Виджет позволяет отображать данные о пайплайнах в платформе GitLab. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL GitLab API. Используется для получения данных из GitLab | - | -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Дополнительные возможности виджета - -##### Запуск пайплайнов - -Виджет позволяет запускать пайплайны в GitLab напрямую из DDP. - -###### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|----------------|------------------------------------------------------------------------------------|-----------------------| -| Ref | Да | Целевая ветка или тег для запуска пайплайна | - | -| Переменные | Нет | Переменные в формате ключ-значение, которые будут переданы в запускаемый пайплайн | - | - -### GitLab. Редактор пайплайна - -Виджет позволяет редактировать конфигурацию пайплайна GitLab CI/CD (файл `.gitlab-ci.yml`) и создавать запросы на слияние с изменениями. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL GitLab API. Используется для получения данных из GitLab | - | -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Отображаемые данные - -Виджет отображает: - -* «Редактор кода» — Monaco Editor для редактирования файла `.gitlab-ci.yml`. -* «Дифф-просмотр» — отображение изменений между оригинальной и редактируемой версией конфигурации. - -#### Дополнительные возможности виджета - -##### Создание запроса на слияние - -Виджет позволяет создавать запросы на слияние с изменениями конфигурации пайплайна. - -###### Параметры запроса на слияние - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|--------------|--------------------------------------------------------------|-----------------------| -| Заголовок MR | Да | Краткий заголовок, описывающий цель запроса на слияние | - | -| Описание MR | Нет | Подробное описание запроса на слияние и изменений | - | -| Название новой ветки | Да | Название новой ветки, которая будет содержать ваши изменения | - | -| Целевая ветка | Да | Ветка, в которую будет выполнен запрос на слияние | main | -| Сообщение коммита | Да | Описание изменений, внесенных в конфигурацию пайплайна | - | - -##### Ограничения - -* Виджет работает только с файлом `.gitlab-ci.yml` в корне проекта. -* Для создания запроса на слияние требуются права на запись в репозиторий. -* Максимальный размер файла конфигурации ограничен возможностями GitLab API. - -### GitLab. Статистика пайплайнов - -Виджет позволяет отображать статистику пайплайнов в платформе GitLab, включая общую статистику, распределение по статусам, источникам, участникам и веткам. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL GitLab API. Используется для получения данных из GitLab | - | -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Отображаемые данные - -Виджет отображает следующую статистику: - -##### Основные метрики - -* «Общее количество пайплайнов» — общее число пайплайнов за выбранный период. -* «Процент успеха» — процент успешно выполненных пайплайнов. -* «Процент неудач» — процент неудачно выполненных пайплайнов. -* «Средняя длительность» — среднее время выполнения пайплайнов. - -##### Распределение по статусам - -* Успешные пайплайны. -* Неудачные пайплайны. -* Отмененные пайплайны. -* Пропущенные пайплайны. -* Ручные пайплайны. - -##### Распределение по источникам - -* Push (коммиты). -* Merge requests (запросы слияния). -* Schedule (по расписанию). -* Web (через веб-интерфейс). - -##### Топ участников - -* Список участников с наибольшим количеством запущенных пайплайнов. -* Аватары участников (при наличии). -* Количество пайплайнов для каждого участника. - -##### Активность веток - -* Список веток с наибольшим количеством пайплайнов. -* Количество пайплайнов для каждой ветки. - -#### Параметры запроса - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------|----------------|------------------------------------------------------------------------------------------|-----------------------| -| Начальная дата | Да | Начальная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-01T00:00:00Z` | - | -| Конечная дата | Да | Конечная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-31T23:59:59Z` | - | -| Ветка | Нет | Фильтр по конкретной ветке. Если не указана, анализируются все ветки | - | - -#### Ограничения - -* Виджет анализирует максимум 100 пайплайнов за один запрос для оптимизации производительности. -* Статистика рассчитывается только для пайплайнов с валидными данными (имеющими статус и время выполнения). -* Данные обновляются при каждом обновлении виджета. - -### GitLab. Теги - -Виджет позволяет отображать данные о тегах проекта в платформе GitLab. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL GitLab API. Используется для получения данных из GitLab | - | -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Дополнительные возможности виджета - -##### Создание тегов - -Виджет позволяет создать теги в GitLab напрямую из DDP. - -###### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|----------------|---------------------------------------------|-----------------------| -| Название | Да | Название создаваемого тега | - | -| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег | - | -| Описание | Нет | Описание создаваемого тега | - | - -### Bitbucket. Теги - -Виджет позволяет отображать данные о тегах репозитория в Bitbucket. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#bitbucket). - -#### Конфигурация - -| Название | Обязательность | Описание | Пример | -|--------------|-----------------|------------------------------------------------------------|------------------------------------------------------------------------| -| Ключ проекта | Да | Часть URL репозитория, которая идёт сразу после `/projects/` | Для репозитория `.../projects/MYTEAM/repos/backend` укажите `MYTEAM` | -| Репозиторий | Да | Часть URL репозитория, которая идёт сразу после `/repos/` | Для репозитория `.../projects/MYTEAM/repos/backend` укажите `backend` | - -#### Отображаемые данные - -Виджет отображает список тегов репозитория с информацией о каждом теге: - -* «Название тега» — название тега. -* «Коммит» — хеш коммита, сообщение коммита, автор, дата создания, ссылка на коммит в Bitbucket. - -#### Дополнительные возможности виджета - -##### Создание тегов - -Виджет позволяет создавать теги в Bitbucket напрямую из DDP. - -###### Конфигурация - -| Название | Обязательность | Описание | -|------------|----------------|------------------------------------------------------------------------------------| -| Название | Да | Название создаваемого тега | -| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег (выбирается из списка) | -| Описание | Нет | Описание создаваемого тега | - -### GitHub. Теги - -Виджет отображает теги репозитория GitHub с информацией о коммите (автор, дата, описание) и позволяет создавать новые теги. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#github). -В настройках внешнего сервиса в поле «URL» необходимо указать `https://api.github.com`. - -#### Учётная запись и автор действий - -Запросы к GitHub выполняются с токеном из учётных данных того пользователя платформы, от имени которого вызывается действие. Если в настройках виджета включено «Выбрать учётную запись для виджета», используются учётные данные выбранного пользователя платформы, а не текущего. - -«Аннотированный тег» (поле «Описание» заполнено): в метаданных git-тега поля автора аннотации (`tagger`) заполняются из имени и email пользователя платформы, выполнившего действие (как в профиле в DDP). Если имя не задано, может подставляться email. - -«Лёгкий тег» (без описания): отдельный автор тега в git не задаётся; создаётся ссылка на коммит. - -Создание тега через API выполняется от учётной записи GitHub по токену; данные `tagger` при этом берутся из профиля DDP и могут не совпадать с логином GitHub. - -#### Конфигурация - -| Название | Обязательность | Описание | Пример | -|----------------------|----------------|------------------------------------------------------|------------------------------------------------------------| -| Владелец репозитория | Да | Владелец репозитория (организация или пользователь). | Для `https://github.com/example/my-repo` укажите `example` | -| Репозиторий | Да | Название репозитория без `.git`. | Для `https://github.com/example/my-repo` укажите `my-repo` | - -#### Отображаемые данные - -В таблице отображаются колонки: тег, описание, автор коммита, ссылка на коммит, дата создания коммита; для каждого тега доступно действие «Просмотр» (просмотр описания коммита). - -#### Дополнительные возможности виджета - -##### Создание тега - -Виджет позволяет создавать теги в GitHub. В диалоге «Создать тег» указываются: - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------|----------------|-------------------------------------------------------------------------------------------|-----------------------| -| Название тега | Да | Уникальное название тега, например `v1.0.0` или `release-2024-01` | — | -| Создать из | Да | Ветка или существующий тег, от которого создаётся новый тег | — | -| Описание | Нет | Аннотация к тегу (например, описание релиза). Если указано, создаётся аннотированный тег | — | - -{{< alert level="info" >}} -Для создания тегов требуются права на запись в репозиторий GitHub. -{{< /alert >}} - -### GitLab. Релизы - -Виджет отображает список релизов GitLab-проекта, подсвечивает последний релиз и показывает связанную информацию: тег, ссылку на коммит, автора, дату публикации и описание (поддерживает Markdown). - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -#### Дополнительные возможности виджета - -##### Создание релиза - -Виджет позволяет создать релиз в GitLab напрямую из DDP: - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------|----------------|---------------------------------------------------------------------------------------------------|-----------------------| -| Название релиза | Да | Название релиза, отображаемое в списке | - | -| Тег | Да | Существующий тег, на основе которого будет сформирован релиз (выбирается из списка тегов проекта) | - | -| Описание | Нет | Описание релиза в формате Markdown | - | - -Созданный релиз автоматически появляется в списке, а последний релиз подсвечивается. - -### GitLab. Участники - -Виджет позволяет отображать данные об участниках проекта в GitLab. [Подробнее об участниках](https://docs.gitlab.com/user/project/members/). - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | - -### Просмотр репозитория - -Виджет позволяет просматривать структуру и содержимое файлов в репозитории. Поддерживаются репозитории GitLab, Bitbucket и GitHub. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#gitlab). - -* [GitLab](../external-services/#gitlab). -* [Bitbucket](../external-services/#bitbucket). -* [GitHub](../external-services/#github). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------|----------------|--------------------------------------------------------------------|-----------------------| -| Провайдер | Да | Сервис, в котором размещён репозиторий (GitLab, GitHub, Bitbucket) | - | -| Ветка / Тег | Нет | Название ветки, тег или SHA коммита (по умолчанию: main) | main | -| Путь | Нет | Путь к директории в репозитории (оставьте пустым для корня) | - | -| Рекурсивно | Нет | Получать файлы рекурсивно из поддиректорий | false | - -#### Конфигурация для GitLab - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------|-----------------|--------------------------------------------------|-----------------------| -| ID проекта | Да | ID проекта в GitLab (например, 12345). | - | - -#### Конфигурация для Bitbucket - -| Название | Обязательность | Описание | Пример | Значение по умолчанию | -|---------------------------|----------------|------------------------------------------------------------|----------|-----------------------| -| Ключ проекта | Да | Ключ проекта в Bitbucket (например, MYPROJ) | MYPROJ | - | -| Идентификатор репозитория | Да | Идентификатор репозитория в Bitbucket (например, my-repo) | my-repo | - | - -#### Конфигурация для GitHub - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------------|----------------|-------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Владелец репозитория | Да | Владелец репозитория (организация или пользователь). Пример: для `https://github.com/example/my-repo` укажите «example» | - | -| Репозиторий | Да | Название репозитория без `.git`. Пример: для `https://github.com/example/my-repo` укажите «my-repo» | - | - -### Jenkins. Пайплайны - -Виджет отображает данные о пайплайнах в Jenkins и позволяет управлять сборками. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#jenkins). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Jenkins. Используется для получения данных из Jenkins | - | -| Название | Да | Название пайплайна в Jenkins. Поддерживается вложенность: `folder1/folder2/jobName` | - | - -#### Отображаемые данные - -Виджет автоматически определяет тип пайплайна и отображает соответствующее представление. - -##### Обычные пайплайны - -Для обычных пайплайнов виджет отображает: - -* «Список сборок» — таблица со всеми сборками пайплайна с информацией о номере, статусе, длительности, времени выполнения и пользователе. -* «Последняя сборка» — информация о последней выполненной сборке. -* «Последняя успешная сборка» — информация о последней успешной сборке. -* «Последняя неудачная сборка» — информация о последней неудачной сборке. - -##### Multibranch пайплайны - -Для multibranch пайплайнов виджет отображает: - -* «Список веток» — таблица со всеми ветками с информацией о статусе, количестве сборок и последней сборке для каждой ветки. -* Всю информацию, описанную в разделе «обычные пайплайны», в разрезе каждой ветки. - -#### Дополнительные возможности виджета - -Виджет позволяет выполнять следующие действия: - -##### Для обычных пайплайнов - -* «Запустить сборку» — запуск новой сборки. Если у сборки есть параметры, отображается диалог для их ввода: - * Строковые параметры; - * Пароли; - * Выбор из списка; - * Булевые значения. -* «Отменить сборку» — отмена выполняющейся сборки. -* «Повторить сборку» — повторный запуск последней сборки. -* «Просмотр логов» — просмотр логов выполнения сборки. - -##### Для multibranch пайплайнов - -* «Запустить сборку ветки» — запуск новой сборки для конкретной ветки. Если у сборки есть параметры, отображается диалог для их ввода. -* «Получить сборки ветки» — загрузка списка сборок для конкретной ветки. -* «Сканировать multibranch» — запуск сканирования multibranch пайплайна для обнаружения новых веток. -* «Просмотр логов» — просмотр логов выполнения сборки. - -### Jira. Задачи - -Виджет позволяет отображать задачи из Jira на основе JQL-запроса. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#jira). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|-----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Jira. Используется для получения данных из Jira | - | -| JQL | Да | JQL-запрос для фильтрации задач. Пример: `project = PROJ AND status = Open` | - | - -#### Параметры запроса - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------------|----------------|-----------------------------------------------------------------------------------|-----------------------| -| JQL | Нет | JQL-запрос для фильтрации задач. Если не указан, используется JQL из конфигурации | Из конфигурации | -| Максимум результатов | Нет | Максимальное количество задач для отображения (от 1 до 1000) | 50 | - -#### Дополнительные возможности виджета - -* «Просмотр описания» — при клике на кнопку «Просмотр описания» открывается диалоговое окно с полным описанием задачи. -* «Переход в Jira» — клик по ключу задачи открывает задачу в Jira в новой вкладке. -* «Динамическая фильтрация» — возможность изменить JQL-запрос и максимальное количество результатов прямо в виджете без изменения конфигурации. - -### Helm. Релизы - -Виджет позволяет отображать данные о Helm-релизах в Kubernetes и производить rollback на предыдущие версии. - -Данные, отображаемые на виджете: - -* «Список релизов Helm» — информация о текущих релизах, созданных с помощью Helm в указанном неймспейсе Kubernetes. -* «Манифесты релизов» — манифесты, связанные с Helm-релизами в указанном неймспейсе Kubernetes. Это включает в себя файлы YAML, которые определяют конфигурацию и состояние ресурсов. -* «Values» — переменные, которые использовались для развёртывания Helm-релизов. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kubernetes). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------|----------------|--------------------------------------------------------------------------------------|-----------------------| -| Namespace | Нет | Неймспейс, из которого будут загружаться данные в виджет. Пример: `default` | - | -| Релиз | Нет | Название релиза, из которого будут загружаться данные в виджет. Пример: `my-release` | - | - -### Iframe - -{{< alert level="warning" >}} -Виджет Iframe работает только при включённой опции `allowIframe: true` в конфигурации заголовков безопасности (`security.headers.csp.allowIframe`). По умолчанию эта опция отключена, поэтому виджет не будет отображать контент до изменения конфигурации. -{{< /alert >}} - -Виджет позволяет отображать данные из внешнего источника. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|------------------------------------------------------------------------|-----------------------| -| URL | Да | URL внешнего источника. Используется для отображения данных в виджете | - | - -### Kafka. ACLs - -Виджет позволяет отображать список ACLs кластера Kafka. - -Для каждого ACL отображается следующая информация: - -* Субъект. -* Тип ресурса. -* Шаблон. -* Тип шаблона. -* Хост. -* Операция. -* Тип разрешения. - -#### Аутентификация - -Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: - -* PLAINTEXT. -* SCRAM-SHA-256. -* SCRAM-SHA-512. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Kafka кластера | - | -| Протокол аутентификации | Да | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | - | -| Механизм SASL | Нет | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | - | -| Пользователь Kafka | Да | Username учётной записи для взаимодействия с Kafka | - | -| Пароль | Да | Пароль учётной записи для взаимодействия с Kafka | - | -| Типы ресурсов | Нет | Фильтр по типам ресурсов | - | -| Типы шаблонов | Нет | Фильтр по типам шаблонов | - | -| Операции | Нет | Фильтр по операциям | - | -| Типы разрешений | Нет | Фильтр по типам разрешений | - | -| Субъекты | Нет | Фильтр по субъектам. Поддерживается шаблонизация и регулярные выражения | - | -| Хосты | Нет | Фильтр по хостам. Поддерживается шаблонизация и регулярные выражения | - | - -#### Дополнительные возможности виджета - -При активированной функции действий в настройках виджет позволяет: - -* Создавать новые правила ACL. -* Удалять существующие правила ACL. - -### Kafka. Топики - -Виджет позволяет отображать различные данные о Kafka топиках. - -Для каждого топика доступно: - -* Общая информация о топике: основные параметры, конфигурация и статус. -* Информация о партициях: лидер и оффсеты, количество реплик и т. д. -* Информация о консьюмерах: список активных потребителей, их группы, текущие оффсеты и лаги. -* Сообщения: просмотр содержимого сообщений топиков. -* Поиск сообщений: фильтрация сообщений по timestamp и offset. -* Настройки топика: просмотр конфигурации топика в виде таблицы ключ-значение. - -#### Аутентификация - -Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: - -* PLAINTEXT. -* SCRAM-SHA-256. -* SCRAM-SHA-512. - -{{< alert level="info" >}} -Доступность информации в виджете определяется уровнем прав подключённой учётной записи. -{{< /alert >}} - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Kafka кластера | - | -| Протокол аутентификации | Да | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | - | -| Механизм SASL | Нет | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | - | -| Пользователь Kafka | Да | username учётной записи для взаимодействия с Kafka | - | -| Пароль | Да | пароль учётной записи для взаимодействия с Kafka | - | -| Топики Kafka | Нет | Название топика или регулярное выражение для фильтрации отображаемых топиков в виджете; при пустом значении отображаются все доступные пользователю топики. | - | - -#### Дополнительные возможности виджета - -При активированной функции действий в настройках виджет позволяет: - -* Создавать новые топики; -* Удалять существующие топики; -* Отправлять сообщение в топик; -* Очищать топик от сообщений. - -### Kubernetes deployments - -Виджет Kubernetes deployments позволяет выводить основную информацию обо всех deployments в кластере Kubernetes. Доступна фильтрация по неймспейсу и/или по label selector. - -Для каждого ресурса Deployment доступны: - -- «Просмотр спецификации и статуса Deployment». -- «Масштабирование количества реплик Deployment». Для применения изменений после выбора требуемого количества реплик необходимо нажать кнопку «Сохранить» с иконкой дискеты. -- «Просмотр информации о подах», управляемых Deployment, и контейнерах этих подов, включая просмотр логов каждого контейнера. -- «Просмотр и редактирование ресурсов контейнеров». Виджет отображает все настроенные ресурсы контейнеров, включая CPU, Memory, ephemeral-storage и другие типы ресурсов. Редактирование доступно только для CPU и Memory в секциях `requests` и `limits`. Изменения применяются на уровне Deployment и распространяются на все поды, управляемые данным Deployment. При очистке значений CPU или Memory соответствующие ресурсы удаляются из конфигурации контейнера. Остальные ресурсы (например, `ephemeral-storage`) отображаются, но не могут быть отредактированы через виджет. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kubernetes). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Kubernetes API | Да | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | -| Namespace | Нет | Kubernetes namespace из которого будут загружаться deployment. В случае, если namespace не указан, виджет будет пытаться загрузить все deployment кластера. Пример: `default` | - | -| Label selector | Нет | Селекторы для фильтрации получаемых deployment. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | - -### Kubernetes ingresses - -Виджет позволяет отображать данные об Ingress в кластере Kubernetes. - -Для каждого Ingress доступны: - -* Просмотр спецификации Ingress в виде YAML-конфигурации. -* Правила Ingress. -* Настройки TLS. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kubernetes). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | -| Namespace | Нет | Неймспейс Kubernetes из которого будут загружаться ingresses. В случае, если неймспейс не указан, виджет будет пытаться загрузить все ingress кластера. Пример: `default` | - | -| Label selector | Нет | Селекторы для фильтрации получаемых ingress. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | - -### Kubernetes pods - -Виджет позволяет отображать данные о подах в кластере Kubernetes. - -Для каждого pod доступны: - -* Просмотр спецификации пода в виде YAML-конфигурации. -* Логи контейнеров. -* Различная информация о состоянии пода: статус, количество перезапусков и др. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kubernetes). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------|----------------|------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | -| Namespace | Нет | Неймспейс, из которого будут загружаться данные в виджет. Пример: `default` | - | -| Label selector | Нет | Селекторы для фильтрации получаемых подов. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | - -### Markdown - -Виджет обеспечивает отображение текста, написанного в формате Markdown. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|-----------------|---------------------------------------------------------------------------------------|-----------------------| -| Markdown | Да | Текст в формате Markdown. Отображается в виджете в отформатированном виде | - | - -### Nexus artifacts - -Виджет позволяет выводить список артефактов в репозитории Nexus. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#nexus). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|----------------|-------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Nexus API. Используется для получения данных из Nexus | - | -| Repository | Да | Название репозитория, данные из которого будут отображаться в виджете. Пример: `my-repo` | - | -| Name | Нет | Название артефакта, данные о котором будут отображаться в виджете | - | - -### Opensearch index - -Виджет Opensearch index позволяет отобразить данные из определённого index или index pattern в платформе. Данные по умолчанию сортируются от более новых к более старым. Доступен полнотекстовый поиск для фильтрации отображаемых данных. Для каждой записи (строки таблицы) доступно отображение в формате «ключ-значение», либо в JSON. При указании index pattern в виджете будет выводиться ссылка на страницу Discover в OpenSearch Dashboards. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#opensearch). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| API URL | Да | URL Opensearch API. Используется для получения данных из Opensearch | - | -| Dashboards URL | Да | URL Opensearch Dashboards. Используется при генерации ссылки для перехода в Opensearch и просмотра данных непосредственно в системе | - | -| Index pattern | Да | Название index pattern из которого будут загружаться данные в виджет. Может содержать символ «*». Примеры: `security-auditlog`, `security-auditlog-*` | - | -| Timestamp field | Нет | Название поля с timestamp. Значение поля выводится в таблице с данными в отдельной колонке | @timestamp | - -### Prometheus. Метрики (диапазон) - -Виджет строит график по результату запроса `query_range` к Prometheus. Запрос в формате PromQL должен возвращать тип `Matrix` (одну или несколько временных серий). - -Пример запроса с плейсхолдерами: - -```promql -sum by (status) (rate(http_requests_total[{{rateInterval}}])) -``` - -#### Плейсхолдеры в запросе - -Виджет подставляет в запрос значения, рассчитанные из активного интервала: - -| Плейсхолдер | Описание | -|-------------|----------| -| `{{range}}` | Длительность выбранного интервала | -| `{{rateInterval}}` | Окно диапазона для функций `rate()` и `increase()` | -| `{{interval}}` | Шаг между точками на графике (рассчитывается автоматически) | - -Шаг запроса выбирается по длительности интервала (не более 1100 точек на графике, минимум 30 секунд). Поле «Шаг разрешения» в конфигурации больше не используется. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Prometheus | - | -| Запрос | Да | PromQL-запрос для графика диапазона | - | -| Метка | Да | Имя метки Prometheus, используемое как название серии в легенде графика | - | -| Интервал по умолчанию | Нет | Интервал при загрузке виджета и при обновлении, если пользователь не выбрал другой диапазон в панели виджета | Последний час | -| Пороговое значение | Нет | Горизонтальная пунктирная линия на графике | - | -| Минимальное значение | Нет | Нижняя граница оси Y; оставьте пустым для автоматического масштабирования | - | -| Максимальное значение | Нет | Верхняя граница оси Y; оставьте пустым для автоматического масштабирования | - | -| InsecureSkipVerify | Нет | Отключение проверки подлинности TLS/SSL-сертификата Prometheus | false | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#prometheus). - -### Prometheus. Метрики (значение) - -Виджет показывает одно число по PromQL-запросу к Prometheus. Запрос должен возвращать тип **Scalar** или тип **Vector** с одним значением. - -Пример запроса без плейсхолдеров: - -```promql -sum(machine_cpu_cores) -``` - -Пример с плейсхолдером (длительность интервала из панели виджета): - -```promql -sum(increase(http_requests_total[{{range}}])) -``` - -#### Плейсхолдеры в запросе - -Используйте плейсхолдеры, если в выражении нужна длительность интервала, выбранного в панели виджета. Запрос выполняется на момент окончания этого интервала. - -| Плейсхолдер | Описание | -|-------------|----------| -| `{{range}}` | Длительность выбранного интервала | -| `{{rateInterval}}` | Окно диапазона для функций `rate()` и `increase()` | -| `{{interval}}` | Шаг запроса, рассчитанный из интервала | - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| URL | Да | URL Prometheus | - | -| Запрос | Да | PromQL-запрос, возвращающий одно значение | - | -| Интервал по умолчанию | Нет | Интервал при загрузке виджета и при обновлении, если пользователь не выбрал другой диапазон в панели виджета | Последний час | -| Количество цифр после запятой | Нет | Точность, с которой будет выводиться полученное значение | - | -| Единица измерения | Нет | Постфикс, с которым будет выводиться полученное значение | - | -| Отображать пороговое значение | Нет | Отображать пороговое значение в формате <значение метрики> / <пороговое значение> | false | -| Пороговое значение | Нет | Пороговое значение | - | -| Меньшее значение считается лучше | Нет | Метрика считается «хорошей», когда её значение ниже заданного порогового значения | false | -| Порог предупреждения (%) | Нет | Граница между красным и оранжевым цветами. Если значение метрики превышает этот процент от порога, оно получит оранжевый цвет | 60 | -| Порог успеха (%) | Нет | Граница между оранжевым и зелёным цветами. Если значение метрики превышает этот процент от порога, оно получит зелёный цвет | 90 | -| InsecureSkipVerify | Нет | Отключение проверки подлинности TLS/SSL-сертификата Prometheus | false | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#prometheus). - -### SonarQube - -Виджет позволяет отображать данные о метриках в платформе SonarQube. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#sonarqube). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------|----------------|--------------------------------------------------------------------------------------------|-----------------------------------------| -| URL | Да | Адрес SonarQube, например, `https://sonarqube.example.com` | - | -| Ключ проекта | Да | Идентификатор проекта в SonarQube | - | -| Ветка | Нет | Ветка проекта для которой будут браться метрики | Согласно настройкам проекта в Sonarqube | -| Метрики | Да | Метрики проекта, которые будут выводиться в виджете. В конфигурации указывается Metric key | | - -[Список возможных метрик](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition) для текущей версии SonarQube. - -#### Дополнительные возможности виджета - -Виджет позволяет просматривать данные не только для ветки по умолчанию, но и для любой другой ветки. - -### Svacer. Ветка - -Виджет позволяет просматривать результаты статического анализа кода по ветке проекта в Svacer: прогресс ревью маркеров, распределение находок по критичности, динамику срабатываний на ветке, сравнение снимков и таблицу маркеров с пагинацией. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#svacer). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Название проекта | Да | Название проекта в Svacer | - | -| Название ветки | Да | Название ветки в Svacer; используется как ветка по умолчанию при открытии виджета | - | -| Кэшировать полный список маркеров | Нет | Кэширует на бэкенде DDP полный список маркеров выбранного снимка из Svacer; ускоряет пагинацию на вкладке «Находки» | Включено | -| Время жизни кэша (сек.) | Нет | Сколько секунд хранить ответ в памяти DDP; действует при включённом кэше. Допустимый диапазон при указании значения: 30–86400 | 180 | -| Порог маркеров в снимке | Нет | Число маркеров, после которого снимок считается большим | 10 000 | -| Стратегия для больших снимков | Нет | Поведение при превышении порога маркеров (см. ниже) | Гибрид | - -Стратегии для больших снимков: - -* «Гибрид» — вкладка «Находки» без фильтров недоступна; обзор собирается облегчёнными запросами к Svacer. -* «Без ограничений» — всегда загружается полный список маркеров; при большом снимке отображается только предупреждение. - -#### Параметры запроса - -При просмотре виджета доступны следующие параметры: - -* «Ветка» — ветка Svacer для загрузки данных. Список формируется по проекту из настроек виджета. По умолчанию используется ветка из конфигурации виджета. -* «Снимок» — снимок ветки для загрузки данных. Значение «Последний снимок» соответствует актуальному снимку на ветке в момент обновления виджета. -* «Фильтры»: - * «Статус ревью» — фильтр по статусу разметки маркера (подтверждено, ложное срабатывание, неясно, без решения, не исправлять). - * «Критичность» — фильтр по уровню критичности находки. - * «Чекер» — фильтр по имени чекера (например, `gosec.G402`). - -#### Вкладки - -* «Обзор» — прогресс ревью, число маркеров без ревью, срабатывания на ветке, распределение по критичности, динамика срабатываний, разбивка ревью по статусам и сравнение с предыдущим снимком (новые, исправленные, совпавшие и без изменений). -* «Находки» — таблица маркеров с колонками «Критичность», «Надёжность», «Место», «Чекер», «Ревью», «Сообщение» и «Теги». Поддерживается пагинация и переход к маркеру в Svacer по ссылке. - -В нижней панели виджета отображаются сводные показатели по выбранному снимку: число маркеров в снимке, маркеры без ревью и отфильтрованные находки по уровням критичности. - -{{< alert level="info" >}} -При стратегии «Гибрид» и числе маркеров в снимке выше порога вкладка «Находки» недоступна без фильтра по статусу ревью, критичности или чекеру. -{{< /alert >}} - -### S3 bucket - -Виджет позволяет просматривать содержимое S3-совместимых хранилищ объектов, таких как Amazon S3, Yandex Object Storage, MinIO и другие. - -Для каждого объекта доступно: - -* Просмотр списка объектов в контейнере (bucket) с информацией о размере, дате изменения и классе хранения. -* Поиск объектов по префиксу (пути). -* Загрузка файлов из bucket. -* Просмотр детальной метаинформации объектов (размер, тип контента, метаданные, настройки кеширования и т. д.). -* Навигация по папкам bucket. - -#### Аутентификация - -Для работы с виджетом требуется учётная запись с правами доступа к S3 Bucket. Система поддерживает следующие методы аутентификации: - -* Access Key ID и Secret Access Key. -* Поддержка различных S3-совместимых провайдеров через настройку эндпоинта. - -{{< alert level="info" >}} -В отличие от других виджетов, S3 Bucket виджет не поддерживает использование внешних сервисов для передачи учётных данных. Все параметры аутентификации указываются непосредственно в конфигурации виджета. -{{< /alert >}} - -#### Использование шаблонов для учётных данных - -Для повышения безопасности можно использовать механизм шаблонизации с учётными данными: - -* `{{ .credentials.accessKeyId }}` — подставить Access Key ID из учётных данных. -* `{{ .credentials.secretAccessKey }}` — подставить Secret Access Key из учётных данных. - -{{< alert level="info" >}} -Доступность информации в виджете определяется уровнем прав подключённой учётной записи. -{{< /alert >}} - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|--------------------|----------------|--------------------------------------------------------------------------------------|-----------------------| -| Название bucket | Да | Название S3 Bucket для просмотра | - | -| Endpoint | Да | Эндпоинт URL S3-совместимого хранилища (например, `https://storage.yandexcloud.net`) | - | -| Регион | Да | Регион, в котором находится Bucket | - | -| Access Key ID | Да | Идентификатор ключа доступа для аутентификации | - | -| Secret Access Key | Да | Секретный ключ доступа для аутентификации | - | -| Префикс | Нет | Префикс (путь) для фильтрации объектов при первоначальной загрузке | - | -| Максимум объектов | Нет | Максимальное количество объектов для отображения за один запрос (по умолчанию 100) | 100 | - -#### Дополнительные возможности виджета - -#### Поиск объектов - -Виджет позволяет искать объекты по префиксу (пути). При поиске список объектов обновляется в соответствии с заданным префиксом. - -{{< alert level="info" >}} -Поиск работает только при вводе символов с начала названия объекта. Поиск по символам из середины названия не поддерживается. -{{< /alert >}} - -Если в конфигурации виджета задан начальный префикс, поиск в виджете ограничивается этим префиксом. Загрузка и отображение файлов с другим префиксом недоступны. - -#### Загрузка файлов - -Виджет позволяет загружать файлы из bucket напрямую в браузер. Для каждого файла доступна кнопка загрузки. - -#### Детальная информация об объектах - -При клике на иконку документа для каждого объекта отображается детальная информация: - -* Основные параметры: ключ, размер, дата изменения, класс хранения, тип контента, ETag. -* Информация о контенте: кодировка, язык, диспозиция. -* Настройки кеширования: Cache-Control, срок действия. -* Безопасность: серверное шифрование. -* Пользовательские метаданные. - -#### Подгрузка дополнительных объектов - -При наличии большого количества объектов в bucket доступна функция «Загрузить ещё» для пошаговой загрузки объектов без потери производительности. - -### Vault. Секреты - -Виджет позволяет просматривать секреты в HashiCorp Vault или Deckhouse Stronghold. Поддерживается работа с KV v2 секретами. - -{{< alert level="info" >}} -Виджет не передаёт значения секретов пользователю. На клиентскую сторону передаются только метаданные секретов (версия, время создания и т. д.) и структура ключей без их значений. -{{< /alert >}} - -Для каждого секрета доступно: - -* Просмотр иерархической структуры секретов и директорий. -* Просмотр метаданных секрета: версия, время создания, время удаления, статус уничтожения. -* Просмотр ключей секрета в формате таблицы «ключ/значение» (вместо значений отображается плейсхолдер). -* Навигация по вложенным секретам и директориям. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#vault). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Путь | Да | Путь к секрету или директории в Vault. Необходимо явно указывать путь с `/data/`. Примеры: `services/data/`, `services/data/example` | - | -| Префикс UI | Нет | Префикс для URL интерфейса. Используйте `vault` для HashiCorp Vault или `stronghold` для Deckhouse Stronghold | - | - -#### Особенности работы с путями - -Для работы с KV v2 секретами путь должен явно содержать `/data/`. Примеры корректных путей: - -* `services/data/` — для просмотра всех секретов в директории `services`. -* `services/data/example` — для просмотра конкретного секрета `example`. -* `services/data/nested/secret` — для вложенных секретов. - -#### Отображаемые данные - -Виджет отображает следующую информацию: - -##### Структура секретов - -* «Директории» — отображаются с завершающим слешем (например, `nested/`) и всегда помечаются как директории, даже если содержат ключи. -* «Секреты» — отображаются без завершающего слеша и содержат ключи. - -##### Метаданные секрета - -Для каждого секрета отображаются следующие метаданные (если доступны): - -* «Версия» — версия секрета в KV v2. -* «Время создания» — дата и время создания секрета. -* «Время удаления» — дата и время удаления секрета (для удалённых версий). -* «Статус уничтожения» — индикатор того, что секрет был уничтожен. - -##### Ключи секрета - -Ключи секрета отображаются в формате таблицы «ключ/значение»: - -* Ключ — полный путь к ключу в структуре секрета (например, `database.host`). -* Значение — всегда маскируется символами `********` и не может быть раскрыто. - -### График - -Виджет позволяет выводить информацию об объектах DDP в виде одного из следующих типов графиков: - -* Столбчатая диаграмма; -* Кольцевая диаграмма; -* Круговая диаграмма; -* Полярная диаграмма; -* Радарная диаграмма. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|--------------------------------------------------------------------------------------------|------------------------| -| Тип графика | Да | Тип визуализации графика | - | -| Название таблицы | Да | Название таблицы в базе данных, из которой будут браться записи для визуализации | - | -| Название поля | Да | Название поля, по которому будет происходить агрегация записей | - | -| Фильтры | Нет | Поля, по которым будут фильтроваться полученные записи, и их значения | - | -| Тип агрегации | Да | Принцип, по которому будут группироваться полученные записи | - | -| Параметры агрегации | Нет | Выбор временного периода и шага группировки при агрегации записей по дате | - | - -При настройке виджета следует учитывать, что названия полей в базе данных могут отличаться от названий полей в спецификации объектов. Общий принцип таков: формат camelCase в спецификации объектов при сохранении структур в базу данных преобразуется в snake_case. Например: - -* Поле `createdAt` в спецификации следует указывать в конфигурации виджета как `created_at`. -* Поле `resourceUuid` в спецификации следует указывать в конфигурации виджета как `resource_uuid`. - -Доступно обращение к вложенным значениям. В таком случае разделителем для вложенности служит символ точки. Например, чтобы выполнить агрегацию по статусу сущностей, виджет следует настроить следующим образом: - -| Название таблицы | Название поля | -|-------------------|-------------------| -| `entities` | `health.status` | - -#### Типы агрегации - -##### Дата - -Данные на графике будут отсортированы и сгруппированы по выбранным временным интервалам. - -В параметрах агрегации можно задать параметры: - -- «Единица измерения шага» — например: секунды, минуты, часы, дни и т. д. -- «Количество единиц в одном шаге» — например: 5 минут, 2 часа, 1 день и т. п. - -Это позволяет управлять детализацией отображения данных во времени и адаптировать график под нужный масштаб анализа. - -##### Значение - -Данные на графике отображаются в отсортированном порядке — по значениям. -Для каждого уникального значения в исходном наборе данных: - -- Выполняется подсчёт количества вхождений. -- На графике отображается пара: значение — количество. - -Это позволяет быстро увидеть распределение и частоту повторения различных значений. - -##### Разбивка по интервалам - -Тип агрегации «Разбивка по интервалам» позволяет гибко настроить отображение данных на графике, разделяя значения по заданным числовым диапазонам (интервалам). Это удобно для построения гистограмм и анализа распределения данных. - -Доступны два режима настройки интервалов: - -1. «Автоматическая разбивка по количеству интервалов». - - Указывается только количество интервалов, на которые нужно разделить доступные данные. - Интервалы будут рассчитаны автоматически — равномерно от минимального до максимального значения. - -1. «Ручное задание границ интервалов». - - Указывается массив числовых границ интервалов. - Например: `0, 10, 20, 50` - - В этом случае: - - - Числа будут автоматически отсортированы по возрастанию. - - Интервалы сформируются на основе отсортированных значений: - `[0, 10)`, `[10, 20)`, `[20, 50]` - -В параметрах агрегации должно быть указано хотя бы одно из двух: - -- `Количество` — количество интервалов; -- `Границы` — границы интервалов. - -Примеры: - -- `Количество = 5` — построится 5 равных интервалов на основании данных. -- `Границы = 100, 0, 50` — после сортировки: `[0, 50, 100]`, график будет построен по интервалам `[0, 50)`, `[50, 100]`. - -### Квоты ресурсов Kubernetes - -Виджет позволяет отображать данные о квотах ресурсов в кластере Kubernetes. - -Для каждой квоты происходит визуализация занятых ресурсов. - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kubernetes). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------|-----------------|-----------------------------------------------------------------------------|-----------------------| -| URL | Да | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | -| Namespace | Да | Неймспейс, из которого будут загружаться данные в виджет. Пример: `default` | - | - -### Процентное значение - -Виджет позволяет отображать заданное процентное значение. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Нет | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | - | -| Процентное значение | Нет | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.properties.id }}` | - | - -### Таблица сущностей - -Виджет позволяет отображать сущности, созданные в DDP, в виде таблицы. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Да | Ресурс, сущности которого отображаются в таблице | - | -| Показывать действия | Нет | Необходимость отображения действий с сущностями (возможность запуска действий и сценариев, возможность удаления и др.) | false | - -### Kanban доска сущностей - -Виджет отображает сущности выбранного ресурса на Kanban-доске. - -#### Отображаемые данные - -- «Колонки» — настроенные колонки доски и колонка «Без статуса» для сущностей без подходящего значения параметра состояния. -- «Карточки сущностей» — для каждой сущности отображаются название, описание (если указано), статус проверок, владелец и дата обновления. -- «Перемещение карточек» — перетаскивание карточки между колонками обновляет значение параметра состояния сущности (доступно при наличии прав на изменение сущностей). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|----------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Да | Ресурс, сущности которого отображаются на доске | - | -| Параметр состояния | Да | Параметр сущности, определяющий колонку карточки. Поддерживаются типы `String`, `Number`, `Boolean`, `Enum`, `List`, `Date`, `Percentage`, `URL` | - | -| Колонки | Да | Список колонок доски. Для каждой колонки задаются: название (заголовок на доске), значение (значение параметра состояния; для параметров типа `Enum` и `List` выбирается из доступных опций) и цвет (цвет тега в заголовке). Порядок колонок настраивается перетаскиванием | - | - -#### Особенности - -- Сущности без подходящего значения параметра состояния отображаются в колонке «Без статуса». -- При отсутствии прав на изменение сущностей перемещение карточек недоступно. - -### Временная шкала сущностей - -Виджет отображает сущности выбранного ресурса на временной шкале. - -#### Отображаемые данные - -- «График временной шкалы» — горизонтальная диаграмма, где каждая сущность отображается в виде полосы, показывающей период времени (от даты начала до даты окончания). -- «Информация о сущностях» — при наведении на полосу отображается название сущности, дата начала и дата окончания периода. -- «Сортировка» — сущности отсортированы от самых старых (сверху) к самым новым (снизу). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Да | Ресурс, для которого отображается временная шкала | - | -| Поле даты начала | Да | Поле, из которого берется дата начала периода. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | - | -| Поле даты окончания | Да | Поле, из которого берется дата окончания периода. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | - | - -#### Особенности - -- Виджет автоматически масштабирует временную шкалу для отображения всех сущностей; -- Сущности с некорректными датами (дата начала позже даты окончания) автоматически исключаются из отображения. - -### Календарь сущностей - -Виджет отображает сущности выбранного ресурса в календаре. - -#### Отображаемые данные - -- «Недельный календарь» — сетка из 7 дней текущей недели. -- «Сущности по датам» — для каждого дня отображаются все сущности, у которых дата в выбранном поле соответствует этому дню. -- «Информация о сущностях» — для каждой сущности отображаются название и описание (если указано). -- «Навигация по неделям» — кнопки для перехода к предыдущей и следующей неделе. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Да | Ресурс, для которого отображается календарь | - | -| Поле даты | Да | Поле, из которого берется дата для отображения сущности в календаре. Может быть системным полем (`createdAt`, `updatedAt`) или параметром типа `Date` | - | - -#### Особенности - -- Виджет отображает текущую неделю по умолчанию (с понедельника по воскресенье). -- Доступна навигация между неделями с помощью кнопок «Предыдущая неделя» и «Следующая неделя». -- Для каждого дня отображается дата в формате `ДД.ММ`. -- Сущности отображаются в виде карточек с возможностью перехода на страницу сущности. -- Сущности с пустой или нулевой датой автоматически исключаются из отображения. - -### Статус сущности - -Виджет отображает информацию о статусе сущности и результатах проверок статуса. - -#### Отображаемые данные - -Виджет показывает следующую информацию. - -##### Общий статус - -- «Прогресс-бар» — визуальное отображение общего статуса сущности с указанием процента успешно пройденных проверок. -- «Счётчик успешных проверок» — количество пройденных проверок из общего числа настроенных проверок статуса. - -##### Список проверок - -Для каждой проверки статуса отображается: - -- «Название проверки» — название правила проверки. -- «Статус» — результат выполнения проверки: - - «Пройдено» — проверка успешно пройдена. - - «Не пройдено» — проверка не пройдена (ошибок выполнения нет). - - «Ошибка» — при выполнении проверки произошла ошибка. -- «Время последней проверки» — дата и время последнего выполнения проверки. -- «Сообщение об ошибке» — текст ошибки (отображается, если проверка завершилась с ошибкой). - -##### Статистика - -В нижней части виджета отображается сводная статистика по проверкам: - -- «Пройдено» — количество успешно пройденных проверок. -- «Не пройдено» — количество проверок, которые не были пройдены (без ошибок выполнения). -- «Ошибка» — количество проверок, завершившихся с ошибкой. - -##### Заблокированные действия - -Виджет автоматически определяет и отображает действия, которые недоступны при текущем статусе сущности. - -- Условия отображения: - - действие должно быть доступно для ресурса, связанного с сущностью; - - у действия должны быть настроены разрешённые статусы; - - текущий статус сущности не входит в список разрешённых статусов для этого действия. - -- Отображаемая информация: - - название действия; - - описание действия (если указано). - -#### Конфигурация - -Виджет не требует дополнительной конфигурации. - -Для работы виджета необходимо настроить проверки статуса для ресурса, связанного с сущностью, подробнее — [в документации](../healthchecks/overview/). - -#### Особенности - -Виджет имеет следующие особенности: -- если для сущности не настроено ни одной проверки статуса, виджет отображает сообщение о том, что проверки отсутствуют; -- если данные о проверках статуса недоступны, виджет отображает сообщение об отсутствии данных. - -### Статистика событий - -Виджет отображает статистику событий, происходящих с сущностями в DDP. Виджет содержит три таба: - -1. «Статистика событий» — график, показывающий количество событий по типам за выбранный временной период с настраиваемой группировкой по времени. -1. «Топ сущностей» — таблица с сущностями, для которых было сгенерировано максимальное количество событий. -1. «События в Redis» — таблица со стримами событий из Redis, показывающая для каждого стрима: - - название стрима (кликабельное для просмотра всех событий); - - ресурс, к которому относится стрим; - - количество событий в стриме; - - информацию о последнем событии (сущность, ресурс, тип события, время). - -#### Параметры запроса - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------|-----------------|--------------------------------------------------------------------------------------------|-----------------------| -| Дата от | Да | Начальная дата для выборки событий | 3 дня назад | -| Дата до | Да | Конечная дата для выборки событий | текущая дата | -| Интервал | Нет | Интервал группировки событий на графике (секунды, минуты, часы, дни, недели, месяцы, годы) | час | -| Шаг интервала | Нет | Количество единиц интервала для группировки | 1 | -| Топ сущностей | Нет | Количество сущностей с максимальным количеством событий для отображения в таблице | 10 | - -#### Типы событий - -Виджет поддерживает следующие типы событий: - -- `ENTITY_CREATED` — создание сущности. -- `ENTITY_UPDATED` — обновление сущности. -- `ENTITY_DELETED` — удаление сущности. - -##### Особенности - -- График показывает события за выбранный временной период с настраиваемой группировкой по времени (по умолчанию — по часам). -- Таблица отображает все события для каждой сущности (без фильтрации по дате). -- Для удалённых сущностей отображается их название, извлечённое из спецификации события. -- Вкладка «События в Redis» позволяет отслеживать события, хранящиеся в Redis Streams: - - Для каждого стрима отображается количество событий и информация о последнем событии. - - При клике на название стрима открывается диалог со всеми событиями из этого стрима. - - Стримы автоматически привязываются к ресурсам по UUID, указанному в названии стрима. - - При просмотре событий из стрима отображаются последние 1000 событий (новые первыми). Если в стриме больше 1000 событий, более старые события не отображаются. -- Каждая строка в таблице содержит информацию о последнем событии для сущности. -- Доступен просмотр детальной истории изменений для каждой сущности. -- События для удалённых ресурсов не отображаются (удаляются из БД при удалении ресурса). - -### Числовое значение - -Виджет позволяет отображать заданное числовое значение. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| -| Ресурс | Нет | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | - | -| Числовое значение | Нет | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.properties.id }}` | - | - -### Kaiten. Карточки пространства - -Виджет позволяет отображать структуру задач в пространстве Kaiten в виде многоуровневой таблицы «Доска → Карточки», просматривать задачи на всех уровнях организации работы и получать информацию о критичных параметрах карточек (статус, срочность, блокировки, исполнители и др.). - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------|----------------|-------------------------------------|-----------------------| -| ID пространства | Да | Идентификатор пространства в Kaiten | - | - -#### Параметры запроса - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------|----------------|---------------------------------|-----------------------| -| Мои задачи | Нет | Фильтр по текущему пользователю | false | -| Создано после | Да | Начальная дата для выборки | 1 месяц назад | -| Создано до | Да | Конечная дата для выборки | сейчас | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kaiten). - -#### Отображаемые данные - -Каждая карточка содержит: -- Название карточки. -- Колонка (статус в доске). -- Статус (очередь, в работе, готово). -- Линия. -- Владелец (аватар, имя, email). -- Участники. -- Срок (дата дедлайна, срочность). -- Блокированная/незаблокированная. - -### Kaiten. Статистика пространства - -Виджет предоставляет агрегированные метрики и статистику карточек пространства Kaiten за выбранный период. Позволяет анализировать эффективность работы команды и выявлять узкие места в бизнес-процессах. - -#### Конфигурация - -| Название | Обязательность | Описание | Значение по умолчанию | -|-----------------|----------------|------------------------------------ |-----------------------| -| ID пространства | Да | Идентификатор пространства в Kaiten | - | - -#### Параметры запроса - -| Название | Обязательность | Описание | Значение по умолчанию | -|---------------|-----------------|----------------------------|-----------------------| -| Создано после | Да | Начальная дата для анализа | 1 месяц назад | -| Создано до | Да | Конечная дата для анализа | сейчас | - -#### Авторизация - -Конфигурация авторизации описана в разделе [«Внешние сервисы»](../external-services/#kaiten). - -#### Отображаемые данные - -Виджет содержит четыре вкладки: - -##### Общие показатели - -Основные метрики: - -- В очереди: задачи в очереди на выполнение. -- Выполнено: завершённые задачи. -- В работе: активные задачи. - -Дополнительные метрики: - -- Заблокировано: количество заблокированных задач. -- Блокирующих: количество задач, блокирующих другие. -- Архивировано: количество задач в архиве. -- Срочных: количество срочных задач. -- В среднем на выполнение: среднее время выполнения (в минутах). - -Статистика по чеклистам: - -- Всего с чек-листом: общее количество задач с чек-листами. -- Чеклист полностью выполнен: задачи с полностью выполненными чек-листами. -- Чеклист не выполнен: задачи с невыполненными чек-листами. - -##### По пользователю - -- Список пользователей с количеством назначенных задач. -- Визуализация в виде прогресс-баров. -- Количество задач на каждого пользователя. - -##### Забытые задачи - -Карточки, которые не обновлялись с момента создания. - -##### Последние обновлённые - -Десять последних обновлённых карточек. - -### Очередь задач - -Виджет позволяет отслеживать состояние очереди задач и работу воркеров, обрабатывающих задачи в фоновом режиме. Виджет отображает статистику очереди, информацию о воркерах (консьюмерах) и детали всех задач в очереди. - -#### Отображаемые данные - -Виджет состоит из трех основных разделов: - -##### Статистика очереди - -В верхней части виджета отображаются четыре ключевых показателя: - -- «Размер очереди» — общее количество задач в очереди. -- «Ожидающие задачи» — количество задач, ожидающих обработки. -- «Активные воркеры» — количество активных воркеров (консьюмеров), обрабатывающих задачи. -- «Задачи в очереди» — общее количество задач, включая новые и обрабатываемые. - -##### Таблица воркеров - -Таблица содержит информацию о каждом активном воркере: - -- «Название консьюмера» — идентификатор воркера (консьюмера). -- «Ожидающие задачи» — количество задач, назначенных данному воркеру и ожидающих обработки. -- «Время простоя» — время с момента последней активности воркера. - -{{< alert level="info" >}} -В таблице отображаются только активные воркеры. Воркеры, которые не обрабатывают задачи и неактивны более 5 минут, автоматически скрываются из списка. -{{< /alert >}} - -##### Таблица задач - -Таблица содержит детальную информацию о всех задачах в очереди: - -- «UUID задачи» — уникальный идентификатор задачи. -- «Тип» — тип задачи (например, `health_check`). -- «UUID ресурса» — идентификатор ресурса или сущности, к которой относится задача. -- «Консьюмер» — название консьюмера, обрабатывающего задачу. -- «Время простоя» — время с момента доставки задачи воркеру. -- «Время доставки» — время, когда задача была доставлена воркеру. -- «Статус» — текущий статус задачи: - - «Новая» — задача добавлена в очередь, но ещё не назначена воркеру. - - «В обработке» — задача назначена воркеру и обрабатывается. - -#### Конфигурация - -Виджет не требует дополнительной конфигурации и работает сразу после добавления на дашборд. - -### Технологический радар - -Виджет позволяет визуализировать технологии, инструменты и практики, используемые в компании, с их разбивкой по уровням зрелости (Adopt, Trial, Assess, Hold). - -На виджете отображается круговая диаграмма: четыре квадранта, четыре кольца и набор элементов с номером, названием и привязкой к квадранту и кольцу. Наполнение радара настраивается в конфигурации виджета. - -#### Конфигурация - -| Название | Обязательность | Описание | -|---------------------|----------------|--------------------------------------------------------------| -| Квадранты | Да | Названия квадрантов | -| Элементы | Нет | Список элементов на радаре (не более 200) и их конфигурация | - -##### Конфигурация элемента - -| Название | Обязательность | Описание | -|-----------|----------------|--------------------------------------------------------------------------| -| Название | Да | Название элемента | -| Номер | Да | Целое число от 0 до 9999 | -| Описание | Нет | Описание элемента, в диалоге просмотра отображается в формате Markdown | -| Квадрант | Да | Квадрант, к которому относится элемент | -| Кольцо | Да | Кольцо, к которому относится элемент: Adopt, Trial, Assess или Hold | diff --git a/content/documentation/release-notes/v1.0.0.ru.md b/content/documentation/release-notes/v1.0.0.ru.md index 4ac42875..f61cbae5 100644 --- a/content/documentation/release-notes/v1.0.0.ru.md +++ b/content/documentation/release-notes/v1.0.0.ru.md @@ -14,7 +14,7 @@ description: Заметки о выпуске v1.0.0 — виджеты, ист #### Kaiten виджеты -Добавлены два виджета для интеграции с [платформой управления проектами Kaiten](../../admin/widgets/types/#kaiten-карточки-пространства). +Добавлены два виджета для интеграции с [платформой управления проектами Kaiten](../../admin/widgets/kaiten/space-cards/). - «Kaiten. Карточки пространства» — просмотр задач в пространстве: - Многоуровневое отображение структуры «Доска → Карточки». @@ -29,7 +29,7 @@ description: Заметки о выпуске v1.0.0 — виджеты, ист #### Kafka виджеты -Расширены возможности работы с [Kafka ACL](../../admin/widgets/types/#kafka-acls). +Расширены возможности работы с [Kafka ACL](../../admin/widgets/kafka/acls/). - Действия для виджета Kafka Topics: - Создание и удаление топиков. @@ -45,17 +45,17 @@ description: Заметки о выпуске v1.0.0 — виджеты, ист Добавлены новые возможности для работы с GitLab. -- [«GitLab. Редактор пайплайна»](../../admin/widgets/types/#gitlab-редактор-пайплайна) — редактирование `.gitlab-ci.yml`: +- [«GitLab. Редактор пайплайна»](../../admin/widgets/gitlab/pipeline-editor/) — редактирование `.gitlab-ci.yml`: - Редактирование конфигурации пайплайнов. - Просмотр различий между версиями. - Создание Merge Requests с изменениями. -- [«GitLab. Статистика пайплайнов»](../../admin/widgets/types/#gitlab-статистика-пайплайнов) — аналитика по пайплайнам: +- [«GitLab. Статистика пайплайнов»](../../admin/widgets/gitlab/pipeline-statistics/) — аналитика по пайплайнам: - Общие метрики (количество, процент успеха/неудач, средняя длительность). - Распределение по статусам и источникам. - Статистика по участникам и веткам. -Расширены функции виджета [«GitLab. Запросы слияния»](../../admin/widgets/types/#gitlab-запросы-слияния): +Расширены функции виджета [«GitLab. Запросы слияния»](../../admin/widgets/gitlab/merge-requests/): - «Действия виджета» — добавлена возможность выполнения действий с Merge Requests (MR): - Слияние и закрытие MR. - Изменение статуса черновика. @@ -63,7 +63,7 @@ description: Заметки о выпуске v1.0.0 — виджеты, ист #### S3 bucket виджет -Добавлен [виджет для работы с S3-совместимыми хранилищами](../../admin/widgets/types/#s3-bucket): +Добавлен [виджет для работы с S3-совместимыми хранилищами](../../admin/widgets/generic/s3/): - Просмотр содержимого бакета. - Поиск объектов по префиксу. - Загрузка файлов из бакета. @@ -72,7 +72,7 @@ description: Заметки о выпуске v1.0.0 — виджеты, ист #### Виджет статистики событий -[Виджет для анализа событий сущностей в системе](../../admin/widgets/types/#статистика-событий): +[Виджет для анализа событий сущностей в системе](../../admin/widgets/generic/event-stats/): - График событий по типам за выбранный период. - Топ сущностей по количеству событий. - Настраиваемая группировка по времени. diff --git a/content/documentation/release-notes/v1.1.0.ru.md b/content/documentation/release-notes/v1.1.0.ru.md index 85df2f46..ba4d03dd 100644 --- a/content/documentation/release-notes/v1.1.0.ru.md +++ b/content/documentation/release-notes/v1.1.0.ru.md @@ -105,24 +105,24 @@ description: Заметки о выпуске v1.1.0 — несовместим #### Kubernetes deployments -Обновлён виджет [«Kubernetes Deployments»](../../admin/widgets/types/#kubernetes-deployments): добавлена возможность просмотра и редактирования ресурсов контейнеров (CPU и Memory для requests и limits). +Обновлён виджет [«Kubernetes Deployments»](../../admin/widgets/kubernetes/deployments/): добавлена возможность просмотра и редактирования ресурсов контейнеров (CPU и Memory для requests и limits). #### Статистика событий -Обновлён виджет [«Статистика событий»](../../admin/widgets/types/#статистика-событий): добавлена вкладка «События в Redis» для отслеживания событий, хранящихся в Redis Streams. +Обновлён виджет [«Статистика событий»](../../admin/widgets/generic/event-stats/): добавлена вкладка «События в Redis» для отслеживания событий, хранящихся в Redis Streams. #### CodeScoring виджеты Добавлены виджеты для интеграции с платформой анализа безопасности кода CodeScoring: -- [«CodeScoring. Зависимости»](../../admin/widgets/types/#codescoring-зависимости) — просмотр зависимостей продукта с информацией о версиях, лицензиях и количестве уязвимостей. -- [«CodeScoring. Уязвимости»](../../admin/widgets/types/#codescoring-уязвимости) — таблица уязвимостей с уровнем критичности (CVSS2/CVSS3), наличием эксплойта и исправленными версиями. +- [«CodeScoring. Зависимости»](../../admin/widgets/codescoring/dependencies/) — просмотр зависимостей продукта с информацией о версиях, лицензиях и количестве уязвимостей. +- [«CodeScoring. Уязвимости»](../../admin/widgets/codescoring/vulnerabilities/) — таблица уязвимостей с уровнем критичности (CVSS2/CVSS3), наличием эксплойта и исправленными версиями. Оба виджета поддерживают запуск и отмену SCA-анализа, пагинацию и фильтрацию данных. #### Очередь задач -Добавлен виджет [«Очередь задач»](../../admin/widgets/types/#очередь-задач) для мониторинга очереди задач и работы воркеров: +Добавлен виджет [«Очередь задач»](../../admin/widgets/generic/task-queue/) для мониторинга очереди задач и работы воркеров: - «Статистика очереди» — размер очереди, количество ожидающих задач, активных воркеров. - «Таблица воркеров» — информация о каждом активном воркере (название, ожидающие задачи, время простоя). @@ -133,7 +133,7 @@ description: Заметки о выпуске v1.1.0 — несовместим #### GitLab. Релизы -Добавлен виджет [«GitLab. Релизы»](../../admin/widgets/types/#gitlab-релизы): +Добавлен виджет [«GitLab. Релизы»](../../admin/widgets/gitlab/releases/): - отображает список релизов проекта с подсветкой актуального (последнего) релиза; - показывает тег, ссылку на коммит, дату и автора релиза, описание поддерживает Markdown; @@ -141,7 +141,7 @@ description: Заметки о выпуске v1.1.0 — несовместим #### Статус сущности -Добавлен виджет [«Статус сущности»](../../admin/widgets/types/#статус-сущности), который: +Добавлен виджет [«Статус сущности»](../../admin/widgets/entities/entity-status/), который: - отображает общий статус сущности; - показывает детальную информацию по каждой проверке (текущий статус, время последней проверки, сообщения об ошибках); @@ -149,11 +149,11 @@ description: Заметки о выпуске v1.1.0 — несовместим #### Временная шкала сущностей -Добавлен виджет [«Временная шкала сущностей»](../../admin/widgets/types/#временная-шкала-сущностей), который отображает сущности выбранного ресурса на временной шкале. +Добавлен виджет [«Временная шкала сущностей»](../../admin/widgets/entities/timeline/), который отображает сущности выбранного ресурса на временной шкале. #### Календарь сущностей -Добавлен виджет [«Календарь сущностей»](../../admin/widgets/types/#календарь-сущностей), который отображает сущности выбранного ресурса в календаре. +Добавлен виджет [«Календарь сущностей»](../../admin/widgets/entities/calendar/), который отображает сущности выбранного ресурса в календаре. ### Воркеры diff --git a/content/documentation/release-notes/v1.3.0.ru.md b/content/documentation/release-notes/v1.3.0.ru.md index 4fa5d1fc..a585f22f 100644 --- a/content/documentation/release-notes/v1.3.0.ru.md +++ b/content/documentation/release-notes/v1.3.0.ru.md @@ -19,11 +19,11 @@ description: Заметки о выпуске v1.3.0 — источники да Добавлены новые виджеты: -- [Просмотр репозитория](../../admin/widgets/types/#просмотр-репозитория) — для просмотра структуры и содержимого файлов в репозиториях. -- [Jenkins. Пайплайны](../../admin/widgets/types/#jenkins-пайплайны) — для управления сборками в Jenkins. -- [Jira. Задачи](../../admin/widgets/types/#jira-задачи) — для просмотра задач в Jira. -- [Bitbucket. Pull Requests](../../admin/widgets/types/#bitbucket-pull-requests) — для просмотра и управления Pull Requests в Bitbucket. -- [Vault. Секреты](../../admin/widgets/types/#vault-секреты) — для просмотра секретов в HashiCorp Vault или Deckhouse Stronghold. +- [Просмотр репозитория](../../admin/widgets/generic/repository-browser/) — для просмотра структуры и содержимого файлов в репозиториях. +- [Jenkins. Пайплайны](../../admin/widgets/generic/jenkins/) — для управления сборками в Jenkins. +- [Jira. Задачи](../../admin/widgets/generic/jira/) — для просмотра задач в Jira. +- [Bitbucket. Pull Requests](../../admin/widgets/bitbucket/pull-requests/) — для просмотра и управления Pull Requests в Bitbucket. +- [Vault. Секреты](../../admin/widgets/generic/vault/) — для просмотра секретов в HashiCorp Vault или Deckhouse Stronghold. ### Процессы и действия diff --git a/content/documentation/release-notes/v1.4.0.ru.md b/content/documentation/release-notes/v1.4.0.ru.md index 2878dd4c..4ba31293 100644 --- a/content/documentation/release-notes/v1.4.0.ru.md +++ b/content/documentation/release-notes/v1.4.0.ru.md @@ -66,15 +66,15 @@ CREATE EXTENSION IF NOT EXISTS pg_trgm; Добавлены новые виджеты: -- «GitHub. Pull Requests» — для просмотра и управления [Pull Requests в GitHub](../../admin/widgets/types/#github-pull-requests). -- «GitHub. Теги» — для просмотра и создания [тегов в репозитории GitHub](../../admin/widgets/types/#github-теги). -- «Bitbucket. Теги» — для отображения и создания [тегов репозитория в Bitbucket](../../admin/widgets/types/#bitbucket-теги). -- «CodeScoring. Секреты» — для отображения [секретов проекта в CodeScoring](../../admin/widgets/types/#codescoring-секреты). +- «GitHub. Pull Requests» — для просмотра и управления [Pull Requests в GitHub](../../admin/widgets/github/pull-requests/). +- «GitHub. Теги» — для просмотра и создания [тегов в репозитории GitHub](../../admin/widgets/github/tags/). +- «Bitbucket. Теги» — для отображения и создания [тегов репозитория в Bitbucket](../../admin/widgets/bitbucket/tags/). +- «CodeScoring. Секреты» — для отображения [секретов проекта в CodeScoring](../../admin/widgets/codescoring/secrets/). Изменения в существующих виджетах: - Изменена визуализация для виджета «GitLab. Участники»: отображается вклад каждого из участников в репозиторий (активность по коммитам). -- В виджете «Просмотр репозитория» добавлена поддержка [Bitbucket и GitHub](../../admin/widgets/types/#просмотр-репозитория). +- В виджете «Просмотр репозитория» добавлена поддержка [Bitbucket и GitHub](../../admin/widgets/generic/repository-browser/). ### Действия diff --git a/content/documentation/release-notes/v1.5.0.ru.md b/content/documentation/release-notes/v1.5.0.ru.md index b37a2502..b6bdaa27 100644 --- a/content/documentation/release-notes/v1.5.0.ru.md +++ b/content/documentation/release-notes/v1.5.0.ru.md @@ -20,9 +20,9 @@ description: Заметки о выпуске v1.5.0 — несовместим Добавлены новые виджеты: -- «AI-чат» — для предоставления пользователям преднастроенных вопросов при взаимодействии с AI-провайдерами. Подробнее — в разделе [«AI-чат»](../../admin/widgets/types/#ai-чат). -- «GitHub. Actions» — для просмотра запусков и управления [GitHub Actions](../../admin/widgets/types/#github-actions). -- «Технологический радар» — для визуализации технологий, инструментов и практик, используемых в компании. Подробнее — в разделе [«Технологический радар»](../../admin/widgets/types/#технологический-радар). +- «AI-чат» — для предоставления пользователям преднастроенных вопросов при взаимодействии с AI-провайдерами. Подробнее — в разделе [«AI-чат»](../../admin/widgets/ai/chat/). +- «GitHub. Actions» — для просмотра запусков и управления [GitHub Actions](../../admin/widgets/github/actions/). +- «Технологический радар» — для визуализации технологий, инструментов и практик, используемых в компании. Подробнее — в разделе [«Технологический радар»](../../admin/widgets/generic/tech-radar/). ### Связи diff --git a/content/documentation/release-notes/v1.6.0.ru.md b/content/documentation/release-notes/v1.6.0.ru.md index ca57c233..68244d25 100644 --- a/content/documentation/release-notes/v1.6.0.ru.md +++ b/content/documentation/release-notes/v1.6.0.ru.md @@ -12,7 +12,7 @@ description: Заметки о выпуске v1.6.0 — управление MC ### Виджеты Prometheus -Обновлены виджеты [«Prometheus. Метрики (диапазон)»](../../admin/widgets/types/#prometheus-метрики-диапазон) и [«Prometheus. Метрики (значение)»](../../admin/widgets/types/#prometheus-метрики-значение). Существующие виджеты продолжают открываться, но для корректного отображения данных может потребоваться перенастройка: +Обновлены виджеты [«Prometheus. Метрики (диапазон)»](../../admin/widgets/prometheus/metrics-range/) и [«Prometheus. Метрики (значение)»](../../admin/widgets/prometheus/metrics-single/). Существующие виджеты продолжают открываться, но для корректного отображения данных может потребоваться перенастройка: - у виджета **«Prometheus. Метрики (диапазон)»** удалено поле «Шаг разрешения» — шаг между точками рассчитывается автоматически; сохранённое значение в конфигурации игнорируется; - запросы PromQL теперь поддерживают плейсхолдеры `{{range}}`, `{{rateInterval}}` и `{{interval}}` — проверьте запросы с фиксированными окнами (`[5m]`, `[1h]` и т. п.) и при необходимости замените их на плейсхолдеры; @@ -51,11 +51,11 @@ description: Заметки о выпуске v1.6.0 — управление MC ### Виджеты -- Добавлены виджеты для визуализации данных из ClickHouse: [«ClickHouse. Метрики (диапазон)»](../../admin/widgets/types/#clickhouse-метрики-диапазон), [«ClickHouse. Метрики (значение)»](../../admin/widgets/types/#clickhouse-метрики-значение), [«ClickHouse. Таблица»](../../admin/widgets/types/#clickhouse-таблица), [«ClickHouse. Топ N»](../../admin/widgets/types/#clickhouse-топ-n). -- Добавлен виджет [«DefectDojo. Продукт»](../../admin/widgets/types/#defectdojo-продукт) для просмотра уязвимостей продукта в DefectDojo с разбивкой по engagement и уровням критичности. -- Добавлен виджет [«Kanban доска сущностей»](../../admin/widgets/types/#kanban-доска-сущностей) для отображения сущностей ресурса на Kanban-доске. -- Добавлен виджет [«Svacer. Ветка»](../../admin/widgets/types/#svacer-ветка) для просмотра статистики по ветке проекта в Svacer. -- Обновлены виджеты [«Prometheus. Метрики (диапазон)»](../../admin/widgets/types/#prometheus-метрики-диапазон) и [«Prometheus. Метрики (значение)»](../../admin/widgets/types/#prometheus-метрики-значение): выбор интервала в панели виджета, плейсхолдеры в PromQL, автоматический расчёт шага графика. +- Добавлены виджеты для визуализации данных из ClickHouse: [«ClickHouse. Метрики (диапазон)»](../../admin/widgets/clickhouse/metrics-range/), [«ClickHouse. Метрики (значение)»](../../admin/widgets/clickhouse/metrics-single/), [«ClickHouse. Таблица»](../../admin/widgets/clickhouse/table/), [«ClickHouse. Топ N»](../../admin/widgets/clickhouse/top-n/). +- Добавлен виджет [«DefectDojo. Продукт»](../../admin/widgets/defectdojo/product/) для просмотра уязвимостей продукта в DefectDojo с разбивкой по engagement и уровням критичности. +- Добавлен виджет [«Kanban доска сущностей»](../../admin/widgets/entities/kanban/) для отображения сущностей ресурса на Kanban-доске. +- Добавлен виджет [«Svacer. Ветка»](../../admin/widgets/generic/svacer/) для просмотра статистики по ветке проекта в Svacer. +- Обновлены виджеты [«Prometheus. Метрики (диапазон)»](../../admin/widgets/prometheus/metrics-range/) и [«Prometheus. Метрики (значение)»](../../admin/widgets/prometheus/metrics-single/): выбор интервала в панели виджета, плейсхолдеры в PromQL, автоматический расчёт шага графика. ### Наборы данных diff --git a/content/documentation/release-notes/v1.6.2.ru.md b/content/documentation/release-notes/v1.6.2.ru.md index e1ea312e..35395f99 100644 --- a/content/documentation/release-notes/v1.6.2.ru.md +++ b/content/documentation/release-notes/v1.6.2.ru.md @@ -21,5 +21,5 @@ description: Заметки о выпуске v1.6.2 — сопоставлен ## Исправления - Исправлена ошибка в диалоге [запуска процесса](../../admin/processes/overview/#запуск-процесса): параметры типа «Entities» корректно подставляют значение по умолчанию и проходят проверку обязательности. -- Исправлена ошибка виджета [«Svacer. Ветка»](../../admin/widgets/types/#svacer-ветка): шаблонизация названия ветки в конфигурации виджета применяется корректно. +- Исправлена ошибка виджета [«Svacer. Ветка»](../../admin/widgets/generic/svacer/): шаблонизация названия ветки в конфигурации виджета применяется корректно. - Исправлена ошибка при создании сценария для ресурса с [проверками статуса](../../admin/healthchecks/overview/). diff --git a/content/documentation/user/ai-assistant.md b/content/documentation/user/ai-assistant.md new file mode 100644 index 00000000..0dca29d1 --- /dev/null +++ b/content/documentation/user/ai-assistant.md @@ -0,0 +1,196 @@ +--- +title: AI assistant +description: Configure AI providers, credentials, chats, context, and MCP tools for the AI assistant. +--- + +{{< alert level="warning" >}} +Experimental feature +{{< /alert >}} + +The AI assistant is an intelligent helper built into Deckhouse Development Platform (DDP). It answers questions about the platform, analyzes catalog data, and performs tasks using Model Context Protocol (MCP) tools. + +The AI assistant uses configurable AI providers to process requests. It supports various language models, including OpenAI GPT, Ollama, and any models available through a compatible REST API. + +## Connecting an AI provider + +{{< alert level="info" >}} +Users configure AI providers in their profiles. +{{< /alert >}} + +To connect a new AI provider: + +1. Open **Profile** → **AI providers**. +1. Select **Add**. +1. Fill in **Name**, **Model**, **URL**, **Method**, and **Headers**. If necessary, specify the [Response field](#response-field) and [Request body template](#request-body-template). +1. When using tokens in headers, store the credentials and insert them through [templating](#templating-in-headers). +1. Select **Save**. + +For common API configurations, refer to [Configuration examples](#configuration-examples). + +## Provider credentials + +The credential system securely stores tokens and keys: it encrypts them in the database and inserts them into request headers through templating. + +### Adding credentials + +To add credentials: + +1. In the provider creation or editing form, select **Manage credentials**. +1. In the dialog, select **Add credentials**. +1. Enter a **Key** and **Value** pair, for example, `api_key` and its secret. +1. Select **Save**. + +### Editing credentials + +Consider the following: + +- You cannot change the key of existing credentials. Delete the entry and create a new one. +- To update a value, enter a new one. +- Saved values are not displayed in the interface. + +### Templating in headers + +Use a substitution instead of a plaintext token: + +```sh +Authorization: Bearer {{ .credentials.api_key }} +``` + +Here, `Authorization` is the header, `credentials` is the encrypted credential store, and `api_key` is the key defined in the credentials. + +## Response field + +The **Response field** defines the path to the model response text in the JSON API response body, for example, `choices.0.message.content`. If the field is empty, the platform attempts to locate the response text automatically. + +{{< alert level="info" >}} +To determine the path, send a test API request, open the response, and locate the field containing the model response text in the JSON body. +{{< /alert >}} + +## Request body template + +The **Request body template** field contains the JSON structure sent to the API. + +The following variables are available: + +- `{{.prompt}}` — User request text. +- `{{.model}}` — Model configured for the provider. + +### Structure examples + +OpenAI-compatible chat: + +```json +{ + "model": "{{.model}}", + "messages": [ + { + "role": "user", + "content": "{{.prompt}}" + } + ], + "temperature": 0.7 +} +``` + +Alternative message format: + +```json +{ + "messages": [ + { + "content": "{{.prompt}}", + "role": "user" + } + ], + "model": "{{.model}}", + "stream": false +} +``` + +Minimal format: + +```json +{ + "query": "{{.prompt}}", + "model_name": "{{.model}}" +} +``` + +{{< alert level="info" >}} +The template must be valid JSON. You can add fields such as `temperature` and `max_tokens`. +{{< /alert >}} + +## Configuration examples + +### OpenAI API (Chat Completions) + +1. **Name** — Any name, for example, `ChatGPT`. +1. **Model** — For example, `gpt-4` or `gpt-3.5-turbo`. +1. **URL** — `https://api.openai.com/v1/chat/completions`. +1. **Method** — `POST`. +1. **Headers** — For example, `Authorization: Bearer {{ .credentials.openai_api_key }}`. Add the `openai_api_key` key under **Manage credentials**. +1. **Response field** — `choices.0.message.content`. +1. **Body template** — Use the [first example](#structure-examples) under **Request body template**. + +### Ollama (`/api/generate`) + +1. **URL** — `http://localhost:11434/api/generate`, or your Ollama address. +1. **Method** — `POST`. +1. **Response field** — `response`. +1. **Body template**: + + ```json + { + "model": "{{.model}}", + "prompt": "{{.prompt}}", + "stream": false + } + ``` + +### Custom REST API + +- **URL** — Your service endpoint, for example, `https://api.example.com/v1/chat`. +- **Method** — Usually `POST`. +- **Headers** — For example, `Authorization: Bearer {{ .credentials.api_key }}` and `Content-Type: application/json`. +- **Response field** — Path to the text field in your JSON response. +- **Body template** — Base it on the first example under [Request body template](#request-body-template). Add fields such as `max_tokens` if necessary. + +## Using the AI assistant + +The assistant panel opens on the right. Use the button in the lower-right corner of the screen to open it. + +### Selecting a provider + +The provider list is at the top of the chat panel. If only one provider is available, it is selected automatically. + +### Chats + +Conversations are organized into chats. The chat list and **New chat** are on the left. + +Chats have the following constraints: + +1. Each user can have up to 20 chats. When you reach the limit, delete old chats from the **⋯** menu. +1. Before the first message, a chat has a default name. After the first question, the question text becomes the chat name. You can select **Rename** to change it. +1. Deleting a chat and its message history is irreversible. + +### Sending context + +Configure **Send context** separately for each chat: + +1. **Enabled** — Sends the conversation context for this chat with the request. +1. **Disabled** — Sends only the current message. This uses fewer tokens but does not retain chat context. + +With context enabled, long histories are not sent in full with every request. Recent messages are sent in full, while earlier messages are summarized in a separate request to the same provider. + +{{< alert level="warning" >}} +Sending context increases token usage when interacting with the model. +{{< /alert >}} + +### MCP tools + +The AI assistant uses built-in platform tools and tools from [MCP collections](../mcp-management/#mcp-collections) available to the user. + +Expand **Available tools** in the chat panel to view each tool's name, type (`internal`, `external`, or `custom`), arguments, and example. Select an example to insert its text into the input field. The model can call multiple tools in one request. + +- Built-in tools (`internal`) and their parameters are described in the [MCP server documentation](../mcp-server/). +- To connect MCP servers, create custom MCP tools, and configure collections, refer to [MCP management](../mcp-management/). diff --git a/content/documentation/user/mcp-management.md b/content/documentation/user/mcp-management.md new file mode 100644 index 00000000..53bc3c5b --- /dev/null +++ b/content/documentation/user/mcp-management.md @@ -0,0 +1,87 @@ +--- +title: MCP management +description: Connect upstream MCP servers, custom MCP tools, and MCP collections for the AI assistant and external MCP clients. +--- + +Use **AI** → **MCP** to configure tools that the AI assistant and [built-in MCP server](../mcp-server/) can call on behalf of a user. + +Access to **AI** is controlled by the global `view:ai-page` permission. Separate global `read:` and `edit:` permissions control MCP server, tool, and collection configuration. For details, refer to the [role model](../../admin/security/rbac/#global-permissions). + +## Overview + +| Section | Purpose | +|---------|---------| +| **MCP servers** | Connect upstream MCP servers and synchronize their tool catalogs | +| **MCP collections** | Group tools and control user access | +| **MCP tools** | Create custom MCP tools without an upstream MCP server | +| **Catalog** | View all available tools | + +The AI assistant displays the following tool types: + +- `internal` — Built-in platform tools described in the [MCP server documentation](../mcp-server/). +- `external` — Tools retrieved from a connected upstream MCP server. +- `custom` — Custom MCP tools. + +Tools of the `external` and `custom` types can be called only if they belong to an enabled MCP collection available to the user. + +## MCP servers + +Connect an upstream MCP server to import its tools into the platform catalog. + +1. Go to **AI** → **MCP** → **MCP servers**. +1. Select **Connect**. +1. On the **General information** tab, specify **Name**, **Identifier**, **Description**, **Owner**, and **Team**. +1. On the **Configuration** tab: + 1. Enable the **Enabled** toggle. + 1. Select a **Transport**: `HTTP` or `SSE`. + 1. Specify the upstream MCP server **URL**. + 1. If necessary, add **HTTP headers** and **Credentials** for authentication. +1. Select **Save**. + +After saving, open the server card and select **Synchronize** to load the tool catalog. On the **Tools** tab, enable the required tools and add **Tags** if necessary. + +## MCP tools + +Create a custom MCP tool that the AI assistant calls directly without an upstream MCP server. + +1. Go to **AI** → **MCP** → **MCP tools**. +1. Select **Add**. +1. On the **General information** tab, specify **Name**, **Description**, **Owner**, **Team**, and **Tags**. +1. On the **Configuration** tab: + 1. Enable the **Enabled** toggle. + 1. Define the **Argument schema** as a `JSON Schema` with the root type `object`. + 1. If necessary, specify **Path parameter mapping** as a `JSON` object that maps argument names to `{placeholder}` segments in the executor URL. + 1. If necessary, specify **Query parameter mapping** as a `JSON` object that maps argument names to URL query parameter names. +1. On the **Authorization** tab, specify the executor endpoint **URL**, **HTTP method**, **HTTP headers**, and **Credentials**. The URL can contain `{placeholder}` segments for path parameters and credential placeholders such as `{{ .credentials.tenant_id }}`. +1. Select **Save**. + +For example, assume the argument schema defines the `space_id` argument, the executor URL is `https://api.example.com/v1/spaces/{spaceId}/boards`, and the path parameter mapping is `{"space_id": "spaceId"}`. If the tool is called with `space_id=42`, the request is sent to `https://api.example.com/v1/spaces/42/boards`. + +For `GET` and `DELETE`, arguments not mapped to path parameters are passed only as query parameters. For `POST`, `PUT`, and `PATCH`, arguments not mapped to path or query parameters are passed in the JSON request body. + +## MCP collections + +An MCP collection groups catalog tools and determines which tools are available to AI assistant users and external MCP clients. + +1. Go to **AI** → **MCP** → **MCP collections**. +1. Select **Create**. +1. On the **General information** tab, specify **Name**, **Identifier**, **Description**, **Owner**, and **Team**. +1. On the **Configuration** tab: + 1. Enable the **Enabled** toggle. + 1. Under **Tools**, select tools from the available catalog. Each item includes the MCP server identifier in parentheses. +1. Select **Save**. + +To let a user call collection tools, open the collection card menu and select **Configure access**. Assign users or teams a role with the `use:mcp-collections` permission. For the permission list, refer to the [role model](../../admin/security/rbac/#mcp-collections). + +The collection owner and super administrator automatically receive access to the collection. + +## Catalog + +The **Catalog** section displays all tools available to the current user based on MCP collections and access permissions. This section is read-only. Edit tools on the **MCP servers**, **MCP tools**, and **MCP collections** pages. + +## Integration with the AI assistant and MCP server + +Tools from MCP collections are used as follows: + +- In the [AI assistant](../ai-assistant/#mcp-tools), **Available tools** displays built-in tools and tools from available collections. +- The platform [MCP server](../mcp-server/) returns and calls the same collection tools available to the user based on their RBAC permissions. diff --git a/content/documentation/user/mcp-server.md b/content/documentation/user/mcp-server.md new file mode 100644 index 00000000..0808115c --- /dev/null +++ b/content/documentation/user/mcp-server.md @@ -0,0 +1,335 @@ +--- +title: MCP server +description: Connect external AI clients to Deckhouse Development Platform and use built-in and collection tools over MCP. +--- + +{{< alert level="warning" >}} +Experimental feature +{{< /alert >}} + +The MCP server is a Deckhouse Development Platform (DDP) component that implements the Model Context Protocol (MCP). It enables external AI clients, such as LM Studio and Claude Desktop, to interact with the platform. +The server uses JSON-RPC 2.0 and provides tools for working with platform resources and proxying requests to external infrastructure services. + +MCP is an open protocol for connecting AI models to external systems. For details, refer to the [official MCP website](https://modelcontextprotocol.io/). + +{{< alert level="info" >}} +In addition to built-in platform tools, the MCP server can call tools from [MCP collections](../mcp-management/#mcp-collections) available to the user. Configure MCP servers, custom MCP tools, and collections under [MCP management](../mcp-management/). +{{< /alert >}} + +## Available tools + +The following **built-in** platform tools are available. Tools of the `external` and `custom` types become available after you [synchronize the catalog](../mcp-management/#mcp-servers) and [add them to an MCP collection](../mcp-management/#mcp-collections). + +### get_resources + +Gets a list of resources. + +Parameters: None. + +Returns: A list of resources. + +Example: + +```sh +Get a list of resources +``` + +--- + +### get_external_services + +Gets a list of external services, such as GitLab and SonarQube. + +Parameters: None. + +Returns: A list of external services. + +Example: + +```sh +Get a list of external services +``` + +--- + +### get_resource_entities + +Gets all entities of the selected resource. + +Parameters: + +| Name | Type | Required | Description | +|-----------------|--------|----------|---------------| +| `resource_uuid` | String | Yes | Resource UUID | + +Returns: A list of resource entities. + +Example: + +```sh +Get all services and show their names and creation dates +``` + +--- + +### get_entity + +Gets one entity by UUID. + +Parameters: + +| Name | Type | Required | Description | +|---------------|--------|----------|-------------| +| `entity_uuid` | String | Yes | Entity UUID | + +Returns: Data for one entity. + +Example: + +```sh +Get the entity with UUID 3fa85f64-5717-4562-b3fc-2c963f66afa6 +``` + +--- + +### get_entity_relations + +Gets entity relations. + +Parameters: + +| Name | Type | Required | Description | +|-----------------|--------|----------|-------------------| +| `resource_uuid` | String | Yes | Resource UUID | +| `entity_slug` | String | Yes | Entity identifier | + +Returns: A list of entity relations. + +Example: + +```sh +Get the relations of the "api-gateway" entity in the "Services" resource +``` + +--- + +### get_external_data + +Sends an HTTP request to an external service using the user's credentials. + +Parameters: + +| Name | Type | Required | Description | +|-------------------------|--------|----------|--------------------------------------------------------------------------------| +| `external_service_uuid` | String | Yes | External service UUID | +| `query` | String | Yes | Request description, for example, "get pipelines for project 123" | +| `api_path` | String | Yes | API path with request parameters, such as pagination | +| `method` | String | No | HTTP method. Default: `GET` | +| `body` | String | No | Request body for POST, PUT, or PATCH as a JSON string | + +Credentials and headers are taken from the external service settings in the platform. + +Returns: The result of the HTTP request to the external service. + +Example: + +```sh +Get a list of projects from the external GitLab service +``` + +--- + +### get_actions + +Gets a list of actions. + +Parameters: None. + +Returns: A list of actions. + +Example: + +```sh +Get a list of actions +``` + +--- + +### get_datasources + +Gets a list of data sources. + +Parameters: None. + +Returns: A list of data sources. + +Example: + +```sh +Get a list of data sources +``` + +--- + +### get_processes + +Gets a list of processes. + +Parameters: None. + +Returns: A list of processes. + +Example: + +```sh +Get a list of processes +``` + +## Connecting to the MCP server + +### LM Studio + +1. Get the connection parameters: + + - Sign in to Deckhouse Development Platform. + - Get an API token under **Profile**. + - Note the platform URL, for example, `https://ddp.example.com`. + +1. Configure LM Studio: + + - Open LM Studio. + - Open **Settings**. + - Find **MCP Servers** or **Model Context Protocol**. + - Select **Add Server**. + +1. Configure the server: + + - **Server Name**: `DDP MCP Server`, or another name. + - **Server URL**: `https:///api/v2/mcp`. + - **Transport**: `HTTP` or `JSON-RPC`. + - **Authentication**: + - **Type**: `Bearer Token` or an equivalent that uses the `Authorization` header. + - **Header**: `Authorization: Bearer `. + - **Token**: Enter the platform API token from **Profile**. + +1. Verify the connection: + + - Save the configuration. + - LM Studio connects to the server after saving. + - After a successful connection, the following tools are available: + - `get_resources` — Gets a list of resources. + - `get_external_services` — Gets a list of external services, such as GitLab and SonarQube. + - `get_resource_entities` — Gets all entities of the selected resource. + - `get_entity` — Gets one entity by UUID. + - `get_entity_relations` — Gets entity relations by resource and identifier. + - `get_external_data` — Sends an HTTP request to an external service using the user's credentials. + - `get_actions` — Gets a list of actions. + - `get_datasources` — Gets a list of data sources. + - `get_processes` — Gets a list of processes. + +After connecting, you can use these tools in conversations with models. + +All calls use your access permissions. + +### Connecting other MCP clients + +The Deckhouse Development Platform MCP server is compatible with any client that supports MCP over JSON-RPC 2.0. + +To connect a client: + +1. **Endpoint URL**: `https://your-platform.com/api/v2/mcp`. +1. **Protocol**: JSON-RPC 2.0. +1. **Authentication**: + - Header: `Authorization: Bearer YOUR_API_TOKEN`. + - `YOUR_API_TOKEN` is your platform API token from **Profile**. +1. **Method**: POST. + +### MCP server request example + +HTTP headers: + +```sh +Authorization: Bearer your-api-token-here +Content-Type: application/json +``` + +Request body: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "get_resource_entities", + "arguments": { + "resource_uuid": "target-resource-uuid" + } + } +} +``` + +### MCP server response example + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "content": [ + { + "type": "text", + "text": "[{\"uuid\":\"...\",\"name\":\"Service 1\",\"properties\":{...}},...]" + } + ] + } +} +``` + +## Security + +Authentication: + +- Every MCP server request must be authenticated with an API token from **Profile**. Pass the token in the `Authorization: Bearer ` header. +- Access permissions match your platform user permissions. + +Access permissions: + +- Tools use the same permissions as the user. +- If you cannot access a resource, the tool returns an access error. +- Data is filtered according to your RBAC permissions. + +## Troubleshooting + +### Cannot connect to the server + +If you cannot connect to the server: + +- Verify that the URL is correct and ends with `/api/v2/mcp`. +- Verify that the API token is valid. +- Verify that the platform is accessible from your computer. +- Check the firewall and proxy settings. + +### Authentication error + +If authentication fails: + +- Verify the token format. +- Verify that the token has not expired. +- Verify that you use the `Authorization: Bearer ` header. + +### Tool returns an access error + +If a tool returns an access error: + +- Verify that your user has permission to access the requested resource. +- Verify the resource name or identifier. +- Ask the platform administrator to verify your access permissions. + +### No data returned + +If no data is returned: + +- Verify the request parameters. +- Verify that the resource exists and contains entities. +- Check the platform logs for detailed error information.