diff --git a/es/_specs/cloud-openapi.json b/es/_specs/cloud-openapi.json new file mode 100644 index 000000000..b84b1e71d --- /dev/null +++ b/es/_specs/cloud-openapi.json @@ -0,0 +1,8933 @@ +{ + "components": { + "schemas": { + "Activity": { + "properties": { + "actorDetails": { + "description": "Información adicional sobre el actor.", + "type": "string" + }, + "actorId": { + "description": "ID único del actor.", + "type": "string" + }, + "actorIpAddress": { + "description": "Dirección IP del actor. Se define para los tipos de actor 'user' y 'api'.", + "type": "string" + }, + "actorType": { + "description": "Tipo de actor: 'user', 'support', 'system', 'api'.", + "enum": [ + "user", + "support", + "system", + "api" + ], + "type": "string" + }, + "createdAt": { + "description": "Timestamp de la actividad. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "ID único de la actividad.", + "type": "string" + }, + "organizationId": { + "description": "Alcance de la actividad: Organization ID con el que se relaciona esta actividad.", + "type": "string" + }, + "serviceId": { + "description": "Alcance de la actividad: ID del servicio al que está asociada esta actividad.", + "type": "string" + }, + "type": { + "description": "Tipo de la actividad.", + "enum": [ + "create_organization", + "organization_update_name", + "transfer_service_in", + "transfer_service_out", + "save_payment_method", + "marketplace_subscription", + "migrate_marketplace_billing_details_in", + "migrate_marketplace_billing_details_out", + "organization_update_tier", + "organization_invite_create", + "organization_invite_delete", + "organization_member_join", + "organization_member_add", + "organization_member_leave", + "organization_member_delete", + "organization_member_update_role", + "organization_member_update_mfa_method", + "user_login", + "user_login_failed", + "user_logout", + "key_create", + "key_delete", + "openapi_key_update", + "service_create", + "service_start", + "service_stop", + "service_awaken", + "service_partially_running", + "service_delete", + "service_update_name", + "service_update_ip_access_list", + "service_update_autoscaling_memory", + "service_update_autoscaling_idling", + "service_update_password", + "service_update_autoscaling_replicas", + "service_update_max_allowable_replicas", + "service_update_backup_configuration", + "service_restore_backup", + "service_update_release_channel", + "service_update_gpt_usage_consent", + "service_update_private_endpoints", + "service_import_to_organization", + "service_export_from_organization", + "service_maintenance_start", + "service_maintenance_end", + "service_update_core_dump", + "backup_delete" + ], + "type": "string" + }, + "userAgent": { + "description": "User agent del actor", + "type": "string" + } + } + }, + "ApiKey": { + "properties": { + "createdAt": { + "description": "Marca temporal en la que se creó la clave. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "expireAt": { + "description": "Marca temporal en la que expira la clave. Si no está presente, es `null` o está vacía, la clave nunca expira. ISO-8601.", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "id": { + "description": "ID único de la API key.", + "format": "uuid", + "type": "string" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder a la API con esta clave", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "keySuffix": { + "description": "Últimos 4 caracteres de la clave.", + "type": "string" + }, + "name": { + "description": "Nombre de la clave", + "type": "string" + }, + "roles": { + "description": "Lista de roles asignados a la clave. Contiene al menos 1 elemento.", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "Estado de la clave: 'enabled', 'disabled'.", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + }, + "usedAt": { + "description": "Marca temporal de la última vez que se usó la clave. Si no está presente, la clave nunca se ha usado. ISO-8601.", + "format": "date-time", + "type": "string" + } + } + }, + "ApiKeyHashData": { + "properties": { + "keyIdHash": { + "description": "Hash del ID de la clave. ", + "type": "string" + }, + "keyIdSuffix": { + "description": "Últimos 4 dígitos del ID de la clave. Algoritmo: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + }, + "keySecretHash": { + "description": "Hash del secreto de la clave. Algoritmo: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ApiKeyPatchRequest": { + "properties": { + "expireAt": { + "description": "Marca de tiempo en la que expira la clave. Si es `null` o está vacía, la clave nunca expira. ISO-8601.", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder a la API con esta clave", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "name": { + "description": "Nombre de la clave", + "type": "string" + }, + "roles": { + "description": "Lista de roles asignados a la clave. Contiene al menos 1 elemento.", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "Estado de la clave: 'enabled', 'disabled'.", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + } + } + }, + "ApiKeyPostRequest": { + "properties": { + "expireAt": { + "description": "Marca de tiempo en la que expira la clave. Si no está presente, es `null` o está vacío, la clave no expira nunca. ISO-8601.", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "hashData": { + "$ref": "#/components/schemas/ApiKeyHashData" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder a la API usando esta clave", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "name": { + "description": "Nombre de la clave.", + "type": "string" + }, + "roles": { + "description": "Lista de roles asignados a la clave. Contiene al menos 1 elemento.", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "Estado inicial de la clave: 'enabled', 'disabled'. Si no se proporciona, la nueva clave será 'enabled'.", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + } + } + }, + "ApiKeyPostResponse": { + "properties": { + "key": { + "$ref": "#/components/schemas/ApiKey" + }, + "keyId": { + "description": "ID de clave generado. Se proporciona solo si no había 'hashData' en la solicitud.", + "type": "string" + }, + "keySecret": { + "description": "Secreto de clave generado. Se proporciona solo si no había 'hashData' en la solicitud.", + "type": "string" + } + } + }, + "AwsBackupBucket": { + "properties": { + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "ARN del rol de AWS", + "type": "string" + }, + "iamRoleSessionName": { + "description": "Nombre de la sesión del rol de AWS", + "type": "string" + }, + "id": { + "description": "ID único del bucket de copia de seguridad", + "format": "uuid", + "type": "string" + } + } + }, + "AwsBackupBucketPatchRequestV1": { + "properties": { + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "ARN del rol de AWS", + "type": "string" + }, + "iamRoleSessionName": { + "description": "Nombre de sesión del rol de AWS IAM", + "nullable": true, + "type": "string" + } + } + }, + "AwsBackupBucketPostRequestV1": { + "properties": { + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "ARN del rol de AWS", + "type": "string" + }, + "iamRoleSessionName": { + "description": "Nombre de la sesión del rol de AWS", + "type": "string" + } + } + }, + "AwsBackupBucketProperties": { + "properties": { + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "Rol de AWS IAM", + "type": "string" + }, + "iamRoleSessionName": { + "description": "Rol de AWS IAM", + "type": "string" + } + } + }, + "AzureBackupBucket": { + "properties": { + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "containerName": { + "description": "Nombre del contenedor", + "type": "string" + }, + "id": { + "description": "ID único del bucket de copia de seguridad.", + "format": "uuid", + "type": "string" + } + } + }, + "AzureBackupBucketPatchRequestV1": { + "properties": { + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "connectionString": { + "description": "Cadena de conexión", + "type": "string" + }, + "containerName": { + "description": "Nombre del contenedor", + "type": "string" + } + } + }, + "AzureBackupBucketPostRequestV1": { + "properties": { + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "connectionString": { + "description": "Cadena de conexión", + "type": "string" + }, + "containerName": { + "description": "Nombre del contenedor", + "type": "string" + } + } + }, + "AzureBackupBucketProperties": { + "properties": { + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "containerName": { + "description": "Nombre del contenedor", + "type": "string" + } + } + }, + "AzureEventHub": { + "properties": { + "connectionString": { + "description": "Cadena de conexión para el source de Azure EventHub.", + "type": "string" + } + } + }, + "Backup": { + "properties": { + "backupName": { + "description": "Nombre de la copia de seguridad en el bucket de backup externo.", + "type": "string" + }, + "bucket": { + "description": "Bucket donde se almacena la copia de seguridad.", + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketProperties" + } + ] + }, + "durationInSeconds": { + "description": "Tiempo, en segundos, que tardó en realizarse la copia de seguridad. Si el estado sigue siendo in_progress, este es el tiempo en segundos transcurrido desde que se inició la copia de seguridad hasta ahora.", + "type": "number" + }, + "finishedAt": { + "description": "Marca temporal de finalización de la copia de seguridad. ISO-8601. Disponible solo para las copias de seguridad finalizadas", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "ID único de la copia de seguridad.", + "format": "uuid", + "type": "string" + }, + "serviceId": { + "description": "Nombre ", + "type": "string" + }, + "sizeInBytes": { + "description": "Tamaño de la copia de seguridad en bytes.", + "type": "number" + }, + "startedAt": { + "description": "Marca temporal de inicio de la copia de seguridad. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "status": { + "description": "Estado de la copia de seguridad: 'done', 'error', 'in_progress'.", + "enum": [ + "done", + "error", + "in_progress" + ], + "type": "string" + }, + "type": { + "description": "Tipo de copia de seguridad (\"full\" o \"incremental\").", + "enum": [ + "full", + "incremental" + ], + "type": "string" + } + } + }, + "BackupBucket": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucket" + }, + { + "$ref": "#/components/schemas/GcpBackupBucket" + }, + { + "$ref": "#/components/schemas/AzureBackupBucket" + } + ] + }, + "BackupBucketPatchRequest": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketPatchRequestV1" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketPatchRequestV1" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketPatchRequestV1" + } + ] + }, + "BackupBucketPostRequest": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketPostRequestV1" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketPostRequestV1" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketPostRequestV1" + } + ] + }, + "BackupBucketProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketProperties" + } + ] + }, + "BackupConfiguration": { + "properties": { + "backupPeriodInHours": { + "description": "Intervalo en horas entre copias de seguridad.", + "type": "number" + }, + "backupRetentionPeriodInHours": { + "description": "Duración mínima, en horas, durante la que las copias de seguridad están disponibles.", + "type": "number" + }, + "backupStartTime": { + "description": "Hora, en formato HH:MM, a la que se realizarán las copias de seguridad (se evalúa en la zona horaria UTC). Cuando se define, el período de las copias de seguridad se restablece a 24 horas.", + "type": "string" + } + } + }, + "BackupConfigurationPatchRequest": { + "properties": { + "backupPeriodInHours": { + "description": "El intervalo en horas entre cada copia de seguridad.", + "type": "number" + }, + "backupRetentionPeriodInHours": { + "description": "La duración mínima en horas durante la cual las copias de seguridad están disponibles.", + "type": "number" + }, + "backupStartTime": { + "description": "La hora en formato HH:MM a la que deben realizarse las copias de seguridad (evaluada en la zona horaria UTC). Cuando se define, el período de copia de seguridad se restablece a cada 24 horas.", + "type": "string" + } + } + }, + "ByocConfig": { + "properties": { + "accountName": { + "description": "Nombre de la cuenta", + "type": "string" + }, + "cloudProvider": { + "description": "Cloud Provider de la región", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "id": { + "description": "Identificador único de la configuración de BYOC", + "type": "string" + }, + "regionId": { + "description": "Región para la que se ha configurado el BYOC y en la que es posible crear servicios", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "state": { + "description": "Estado de la infraestructura", + "enum": [ + "infra-ready", + "infra-provisioning", + "infra-terminated" + ], + "type": "string" + } + } + }, + "ByocInfrastructurePostRequest": { + "properties": { + "accountId": { + "description": "ID de la cuenta en la nube para la que está configurada la infraestructura de BYOC", + "type": "string" + }, + "availabilityZoneSuffixes": { + "description": "Lista de sufijos de zonas de disponibilidad", + "items": { + "enum": [ + "a", + "b", + "c", + "d", + "e", + "f" + ], + "type": "string" + }, + "type": "array" + }, + "regionId": { + "description": "Región en la que se ubicará la infraestructura de BYOC", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "vpcCidrRange": { + "description": "Rango CIDR para la VPC", + "type": "string" + } + } + }, + "ClickPipe": { + "properties": { + "createdAt": { + "description": "Fecha de creación del ClickPipe.", + "type": "string" + }, + "destination": { + "$ref": "#/components/schemas/ClickPipeDestination" + }, + "fieldMappings": { + "description": "Correspondencias de campos del ClickPipe. Tenga en cuenta que todas las columnas de destino deben incluirse en las correspondencias.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "id": { + "description": "ID único de ClickPipe.", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "Nombre del ClickPipe.", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "serviceId": { + "description": "ID del servicio al que pertenece este ClickPipe.", + "format": "uuid", + "type": "string" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipeSource" + }, + "state": { + "description": "Estado actual del ClickPipe.", + "type": "string" + }, + "updatedAt": { + "description": "Fecha de la última actualización del ClickPipe.", + "type": "string" + } + } + }, + "ClickPipeDestination": { + "properties": { + "columns": { + "description": "Columnas de la tabla de destino. Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "Base de datos de destino.", + "type": "string" + }, + "managedTable": { + "description": "¿La tabla está gestionada por ClickPipes? Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "type": "boolean" + }, + "table": { + "description": "Tabla de destino. Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeDestinationColumn": { + "properties": { + "name": { + "description": "Nombre de la columna.", + "type": "string" + }, + "type": { + "description": "Tipo de la columna.", + "type": "string" + } + } + }, + "ClickPipeDestinationTableDefinition": { + "properties": { + "engine": { + "$ref": "#/components/schemas/ClickPipeDestinationTableEngine" + }, + "partitionBy": { + "description": "Expresión SQL de la clave de partición.", + "type": "string" + }, + "primaryKey": { + "description": "Clave primaria de la expresión SQL.", + "type": "string" + }, + "sortingKey": { + "description": "Clave de ordenación de la tabla de destino. Lista de columnas.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipeDestinationTableEngine": { + "properties": { + "columnIds": { + "description": "Nombres de las columnas que se sumarán para el motor SummingMergeTree.", + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "description": "Tipo de motor de la tabla de destino.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "SummingMergeTree", + "Null" + ], + "type": "string" + }, + "versionColumnId": { + "description": "Nombre de la columna que se usará como versión para el motor ReplacingMergeTree.", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipeFieldMapping": { + "properties": { + "destinationField": { + "description": "Nombre del campo de destino.", + "type": "string" + }, + "sourceField": { + "description": "Nombre del campo de origen.", + "type": "string" + } + } + }, + "ClickPipeKafkaOffset": { + "properties": { + "strategy": { + "description": "Estrategia de offset.", + "enum": [ + "from_beginning", + "from_latest", + "from_timestamp" + ], + "type": "string" + }, + "timestamp": { + "description": "Timestamp UTC con precisión de minuto desde el que se debe empezar. Obligatorio para la estrategia \"from_timestamp\".", + "example": "2021-01-01T00:00", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipeKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Tipo de autenticación del schema registry.", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados en PEM para validar el certificado del schema registry.", + "nullable": true, + "type": "string" + }, + "url": { + "description": "URL del esquema. Se requiere HTTPS.", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeKafkaSchemaRegistryCredentials": { + "properties": { + "password": { + "description": "Contraseña del schema registry.", + "type": "string" + }, + "username": { + "description": "Nombre de usuario del schema registry.", + "type": "string" + } + } + }, + "ClickPipeKafkaSource": { + "properties": { + "authentication": { + "description": "Método de autenticación del source de Kafka. Métodos de autenticación compatibles: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Brókeres del source de Kafka.", + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados en PEM para validar el certificado del broker.", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Consumer group del source de Kafka. Si no se proporciona, se usará \"clickpipes-<>\".", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato del source de Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role para el source de Kafka. Úselo con autenticación de IAM role. Lea más en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para una conexión privada segura al source de Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Topics del source de Kafka.", + "type": "string" + }, + "type": { + "description": "Tipo del source de Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "Método de autenticación que se usará con el Kinesis Stream.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Formato del Kinesis Stream.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Rol de IAM que se usará para la autenticación. Obligatorio si se usa IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Tipo de iterador que se usará al leer desde el Kinesis Stream. Si se usa AT_TIMESTAMP, se debe proporcionar el campo timestamp.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Región de AWS del Kinesis Stream.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Nombre del Kinesis Stream.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Unix timestamp para empezar a leer desde el Kinesis Stream. Obligatorio si iteratorType es AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Use fan-out mejorado para el Kinesis Stream.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "Columnas de la tabla de destino. Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "Base de datos de destino.", + "type": "string" + }, + "managedTable": { + "description": "¿La tabla está gestionada por ClickPipes? Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "type": "boolean" + }, + "roles": { + "description": "ClickPipe creará un usuario de ClickHouse con estos roles. Agregue aquí sus roles personalizados si es necesario.", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "Tabla de destino. Campo obligatorio para todos los tipos de pipe excepto Postgres.", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Tipo de autenticación del schema registry.", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados en PEM para validar el certificado del schema registry.", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "URL del esquema. Se requiere HTTPS.", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "Base de datos de la instancia de Postgres a la que se conectará.", + "type": "string" + }, + "host": { + "description": "Host de la instancia de Postgres a la que se conectará.", + "type": "string" + }, + "port": { + "description": "Puerto de la instancia de Postgres a la que se conectará.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Correspondencias de tablas para el pipe de Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "Método de autenticación. CONNECTION_STRING es para Azure Blob Storage. IAM_ROLE e IAM_USER son para AWS S3/GCS/DigitalOcean. Si no se proporciona, no se usa autenticación.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nombre del contenedor para Azure Blob Storage. Obligatorio cuando type es azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Algoritmo de compresión usado para los archivos.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Cadena de conexión para la autenticación de Azure Blob Storage. Obligatorio cuando authentication es CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Delimitador usado en los archivos.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato de los archivos.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "Rol de IAM que se usará con la autenticación mediante rol de IAM. Lea más en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Si se establece en true, el pipe leerá continuamente archivos nuevos de la fuente. Si se establece en false, el pipe leerá los archivos solo una vez. Los archivos nuevos deben cargarse en orden lexicográfico.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Ruta a los archivos dentro del contenedor de Azure. Se usa para fuentes de Azure Blob Storage. Puede especificar varios archivos mediante comodines de estilo bash. Para obtener más información, consulte la documentación sobre el uso de comodines en rutas: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL de la cola de SQS para la ingestión continua basada en eventos. Cuando se proporciona, los archivos se ingestan según las notificaciones de eventos de S3 en lugar de por orden lexicográfico. Solo se aplica cuando isContinuous es true y la autenticación no es public.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo de la fuente de ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Proporcione una ruta a los archivos que desea ingestar. Puede especificar varios archivos mediante comodines de estilo bash. Para obtener más información, consulte la documentación sobre el uso de comodines en rutas: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "Columnas de la tabla de destino. Esto no actualizará el esquema de la tabla, solo la configuración de ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Método de autenticación del source de Kafka. Métodos de autenticación compatibles: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados en PEM para validar el certificado del broker.", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Credenciales para el source de Kafka. Elija una de las compatibles con el método de autenticación.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "IAM role para el source de Kafka. Úselo con autenticación de IAM role. Lea más en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para una conexión privada segura al source de Kafka.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticación que se usará con el Kinesis Stream.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "Rol de IAM que se usará para la autenticación. Obligatorio si se usa IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticación. CONNECTION_STRING es para Azure Blob Storage. IAM_ROLE e IAM_USER son para AWS S3/GCS/DigitalOcean. Si no se proporciona, no se usa autenticación.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nombre del contenedor de Azure Blob Storage. Obligatorio cuando type es azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Connection string para la autenticación de Azure Blob Storage. Obligatoria cuando authentication es CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "IAM role que se utilizará con la autenticación mediante IAM role. Más información en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Ruta a los archivos dentro del contenedor de Azure. Se usa para Sources de Azure Blob Storage. Puede especificar varios archivos mediante comodines de estilo bash. Para obtener más información, consulte la documentación sobre el uso de comodines en la ruta: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "Nombre del esquema de origen.", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "Nombre de la tabla de origen.", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "Motor de tabla que se usará para la tabla de destino.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "Nombre de la tabla de destino.", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "Número de filas que se extraerán en cada lote.", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Intervalo, en segundos, para sincronizar datos desde Postgres.", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "Base de datos de la instancia de Postgres a la que se conectará.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "Host de la instancia de Postgres a la que se conectará.", + "nullable": true, + "type": "string" + }, + "port": { + "description": "Puerto de la instancia de Postgres a la que se conectará.", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "Correspondencias de tablas que se agregarán al pipe de Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "Correspondencias de tablas que se eliminarán del pipe de Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "Correspondencias de campos del ClickPipe. Esto no actualizará el esquema de la tabla, solo la configuración del ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Nombre del ClickPipe.", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "Valida las muestras de datos recibidas del origen de datos. Validará la conexión, así como la disponibilidad y la corrección de los datos. Si no está habilitado, solo se validará la conexión. Esto no tiene efecto en los pipes de Postgres; siempre validan únicamente la conexión y las definiciones de tabla. Esto es experimental y podría eliminarse en el futuro.", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Método de autenticación del source de Kafka. Métodos de autenticación compatibles: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Brókeres del source de Kafka.", + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados en PEM para validar el certificado del broker.", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Consumer group del source de Kafka. Si no se proporciona, se usará \"clickpipes-<>\".", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Credenciales para el source de Kafka. Elija una de las compatibles con el método de autenticación.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Formato del source de Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role para el source de Kafka. Úselo con autenticación de IAM role. Lea más en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para una conexión privada segura al source de Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Topics del source de Kafka.", + "type": "string" + }, + "type": { + "description": "Tipo del source de Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticación que se usará con el Kinesis Stream.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Formato del Kinesis Stream.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Rol de IAM que se usará para la autenticación. Obligatorio si se usa IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Tipo de iterador que se usará al leer desde el Kinesis Stream. Si se usa AT_TIMESTAMP, se debe proporcionar el campo timestamp.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Región de AWS del Kinesis Stream.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Nombre del Kinesis Stream.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Unix timestamp para empezar a leer desde el Kinesis Stream. Obligatorio si iteratorType es AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Use fan-out mejorado para el Kinesis Stream.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticación. CONNECTION_STRING es para Azure Blob Storage. IAM_ROLE e IAM_USER son para AWS S3/GCS/DigitalOcean. Si no se proporciona, no se usa autenticación.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nombre del contenedor de Azure Blob Storage. Obligatorio cuando type es azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Algoritmo de compresión usado para los archivos.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Connection string para la autenticación de Azure Blob Storage. Obligatoria cuando authentication es CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Delimitador usado en los archivos.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato de los archivos.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role que se utilizará con la autenticación mediante IAM role. Más información en la documentación de ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Si se establece en true, el pipe leerá continuamente los archivos nuevos del origen. Si se establece en false, el pipe leerá los archivos solo una vez. Los archivos nuevos deben cargarse en orden lexicográfico.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Ruta a los archivos dentro del contenedor de Azure. Se usa para Sources de Azure Blob Storage. Puede especificar varios archivos mediante comodines de estilo bash. Para obtener más información, consulte la documentación sobre el uso de comodines en la ruta: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL de la cola SQS para la ingestión continua basada en eventos. Cuando se proporciona, los archivos se ingestan según las notificaciones de eventos de S3 en lugar de seguir un orden lexicográfico. Solo se aplica cuando isContinuous es true y la autenticación no es pública.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo de la fuente de ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Proporcione la ruta de los archivos que desea ingestar. Puede especificar varios archivos mediante comodines de estilo bash. Para obtener más información, consulte la documentación sobre el uso de comodines en la ruta: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "Correspondencias de campos del ClickPipe. Ten en cuenta que todas las columnas de destino deben incluirse en las correspondencias.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Nombre del ClickPipe.", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "Valida las muestras de datos recibidas del origen de datos. Validará la conexión, así como la disponibilidad y la corrección de los datos. Si no está habilitado, solo se validará la conexión. Esto no tiene efecto en los pipes de Postgres; siempre validan únicamente la conexión y las definiciones de tabla. Esto es experimental y podría eliminarse en el futuro.", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "Permitir columnas Nullable en la tabla de destino.", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "Habilita la conmutación por error para el replication slot creado. Requiere que NO se configure un replication slot.", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "Número de tablas paralelas que se sincronizarán durante la carga inicial.", + "type": "number" + }, + "publicationName": { + "description": "Nombre de la publicación que se usará para la replicación.", + "type": "string" + }, + "pullBatchSize": { + "description": "Número de filas que se extraerán en cada lote.", + "type": "number" + }, + "replicationMode": { + "description": "Modo de replicación que se usará para el pipe.", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "Nombre del replication slot que se usará para la replicación.", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "Número de filas para generar un snapshot por partición.", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "Número de tablas paralelas para generar snapshots.", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Intervalo, en segundos, para sincronizar datos desde Postgres.", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "Columnas que se excluirán de la tabla de destino.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "Lista ordenada de columnas que se usarán como clave de ordenación de la tabla de destino.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "Nombre del esquema de origen.", + "type": "string" + }, + "sourceTable": { + "description": "Nombre de la tabla de origen.", + "type": "string" + }, + "tableEngine": { + "description": "Motor de tabla que se usará para la tabla de destino.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "Nombre de la tabla de destino.", + "type": "string" + }, + "useCustomSortingKey": { + "description": "Indica si se debe usar una clave de ordenación personalizada para la tabla de destino.", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "Base de datos de la instancia de Postgres a la que se conectará.", + "type": "string" + }, + "host": { + "description": "Host de la instancia de Postgres a la que se conectará.", + "type": "string" + }, + "port": { + "description": "Puerto de la instancia de Postgres a la que se conectará.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Correspondencias de tablas para el pipe de Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "Nivel deseado de concurrencia. Solo para pipes de S3. Si se establece en 0, la concurrencia se ajusta automáticamente en función de la memoria del clúster.", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU en milicores para cada réplica. Solo para pipes de streaming.", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memoria en GB para cada réplica. Solo para pipes de streaming.", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "Número deseado de réplicas. Solo para pipes escalables.", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "Nivel de concurrencia al que se debe escalar. Se usa para escalar pipes de S3.", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU en milicores para cada réplica. Se usa para escalar pipes de streaming.", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memoria en GB para cada réplica. Se usa para escalar pipes de streaming.", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "Número de réplicas al que se debe escalar. Se usa para escalar pipes de Kafka.", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de hilos de descarga. Número máximo de hilos de descarga concurrentes", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de hilos de inserción. Número máximo de hilos de inserción concurrentes", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de hilos. Número máximo de hilos concurrentes para el procesamiento de archivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamaño mínimo en bytes del bloque de inserción. Tamaño mínimo del bloque de datos para la inserción (en bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Inserción SELECT distribuida en paralelo. Configuración de inserción SELECT distribuida en paralelo", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "Procesamiento paralelo de vistas. Si se debe habilitar el envío concurrente a las vistas adjuntas en lugar de secuencial", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concurrencia del almacenamiento de objetos. Número de hilos concurrentes para el procesamiento de archivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Cantidad máxima de archivos. Número máximo de archivos que se procesarán en un único lote de inserción", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por inserción. Número de bytes que se procesarán en un único lote de inserción", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de sondeo del almacenamiento de objetos. Configura el intervalo de actualización para consultar la ingesta continua de nuevos datos desde el almacenamiento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "Usar la función cluster. Si se debe usar la función cluster de ClickHouse para el procesamiento distribuido", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tiempo máximo de espera para inserciones de streaming. Configura el tiempo máximo de espera antes de insertar datos en ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de hilos de descarga. Número máximo de hilos de descarga concurrentes", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de hilos de inserción. Número máximo de hilos de inserción concurrentes", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de hilos. Número máximo de hilos concurrentes para el procesamiento de archivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamaño mínimo en bytes del bloque de inserción. Tamaño mínimo del bloque de datos para la inserción (en bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Insert select distribuido en paralelo. Configuración de insert select distribuido en paralelo", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "procesamiento paralelo de vistas. Si se debe habilitar el envío concurrente a las vistas adjuntas en lugar de hacerlo secuencialmente", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concurrencia del almacenamiento de objetos. Número de hilos concurrentes de procesamiento de archivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Cantidad máxima de archivos. Número máximo de archivos que se procesarán en un solo lote de inserción", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por inserción. Número de bytes que se procesarán en un solo lote de inserción", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de sondeo del almacenamiento de objetos. Configura el intervalo de actualización para consultar la ingesta continua de nuevos datos del almacenamiento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "usar la función cluster. Si se debe usar la función cluster de ClickHouse para el procesamiento distribuido", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tiempo máximo de espera para inserciones de streaming. Configura el período máximo de espera antes de insertar datos en ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de hilos de descarga. Número máximo de hilos de descarga concurrentes", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de hilos de inserción. Número máximo de hilos de inserción concurrentes", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de hilos. Número máximo de hilos concurrentes para el procesamiento de archivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamaño mínimo en bytes del bloque de inserción. Tamaño mínimo del bloque de datos para la inserción (en bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Insert select distribuido en paralelo. Configuración de insert select distribuido en paralelo", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "procesamiento paralelo de vistas. Si se debe habilitar el envío concurrente a las vistas adjuntas en lugar de hacerlo secuencialmente", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concurrencia del almacenamiento de objetos. Número de hilos concurrentes de procesamiento de archivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Cantidad máxima de archivos. Número máximo de archivos que se procesarán en un solo lote de inserción", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por inserción. Número de bytes que se procesarán en un solo lote de inserción", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de sondeo del almacenamiento de objetos. Configura el intervalo de actualización para consultar la ingesta continua de nuevos datos del almacenamiento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "usar la función cluster. Si se debe usar la función cluster de ClickHouse para el procesamiento distribuido", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tiempo máximo de espera para inserciones de streaming. Configura el período máximo de espera antes de insertar datos en ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "Comando para cambiar el estado: 'start', 'stop', 'resync'.", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU en milicores para DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memoria en GiB para DB ClickPipes. Debe ser 4× la cantidad de núcleos de CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU en milicores para DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memoria en GiB para DB ClickPipes. Debe ser 4× el número de núcleos de CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Descripción del endpoint privado inverso. La longitud máxima es de 255 caracteres.", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "Tipo de autenticación del clúster de MSK. Obligatorio para el tipo MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN del clúster de MSK. Obligatorio para el tipo MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo de endpoint privado inverso.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Nombre del servicio del endpoint de VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID de configuración del recurso de VPC. Obligatorio para el tipo VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN del recurso compartido de VPC. Obligatorio para el tipo VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "ID de la clave de acceso (clave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "ID único del bucket de copia de seguridad", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "ID de la clave de acceso (clave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Clave de acceso secreta (clave secreta HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "ID de la clave de acceso (clave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Clave de acceso secreta (clave secreta HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "ID de la clave de acceso (clave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Ruta del bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Proveedor del bucket", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Proveedor de nube en el que se encuentra el endpoint privado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descripción del endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador del endpoint privado", + "type": "string" + }, + "region": { + "description": "Región en la que se encuentra el endpoint privado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "Elementos que se deben agregar. Se ejecutan después de procesar la parte \"remove\".", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "Elementos que se deben eliminar. Se ejecutan antes de procesar la parte \"add\".", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "Los orígenes permitidos como lista de dominios separados por comas", + "type": "string" + }, + "openApiKeys": { + "description": "La versión del endpoint de consulta del servicio", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "Los roles", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "Marca temporal de creación de la invitación. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "Correo electrónico del usuario invitado. Solo un usuario con este correo electrónico puede unirse mediante la invitación. El correo electrónico se almacena en minúsculas.", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "Marca temporal en la que expira la invitación. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "ID de invitación único.", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "Rol del miembro en la organización.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "Correo electrónico del usuario invitado. Solo un usuario con esta dirección de correo electrónico puede unirse mediante la invitación. La dirección de correo electrónico se almacena en minúsculas.", + "format": "email", + "type": "string" + }, + "role": { + "description": "Rol del miembro en la organización.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "Descripción opcional de la dirección IPv4 o del CIDR IPv4 desde los que se permitirá el acceso", + "type": "string" + }, + "source": { + "description": "IP o CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "Elementos que se deben agregar. Se ejecutan después de procesar la parte \"remove\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "Elementos que se deben eliminar. Se ejecutan antes de procesar la parte \"add\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "Correo electrónico del miembro, tal como se establece en el perfil personal del usuario.", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "Marca temporal en la que el miembro se unió a la organización. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "Nombre del miembro, tal como se establece en el perfil personal del usuario.", + "type": "string" + }, + "role": { + "description": "Rol del miembro en la organización.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "ID de usuario único. Si un usuario es miembro de varias organizaciones, este ID seguirá siendo el mismo.", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "Rol del miembro en la organización.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "ID de la clave de acceso de IAM.", + "type": "string" + }, + "secretKey": { + "description": "Clave secreta de IAM.", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "Configuración de BYOC para la organización", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "Timestamp de creación de la organización. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Organization ID único.", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "Nombre de la organización.", + "type": "string" + }, + "privateEndpoints": { + "description": "Lista de endpoints privados de la organización", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Identificador único del interface endpoint que creó en su VPC con el recurso AWS(Service Name) o GCP(Target Service)", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Cloud Provider en el que se encuentra el endpoint privado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descripción opcional del endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador del endpoint privado", + "type": "string" + }, + "region": { + "description": "Región en la que se encuentra el endpoint privado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "Nombre de la organización.", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Cloud Provider en el que se encuentra el endpoint privado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descripción del endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador del endpoint privado", + "type": "string" + }, + "region": { + "description": "Región en la que se encuentra el endpoint privado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "Elementos que se añadirán. Se ejecutan después de que se procese la parte \"remove\". Use el endpoint `Update Service Basic Details` para modificar los endpoints privados.", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "Elementos que se eliminarán. Se ejecutan antes de que se procese la parte \"add\".", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "Contraseña.", + "type": "string" + }, + "username": { + "description": "Nombre de usuario.", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Identificador único del endpoint de interfaz que creó en su VPC con el recurso de AWS (Service Name), GCP (Target Service) o AZURE (Private Link Service)", + "type": "string" + }, + "privateDnsHostname": { + "description": "nombre de host DNS privado de la VPC que creó", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Descripción del endpoint privado inverso. La longitud máxima es de 255 caracteres.", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "Nombres DNS internos del endpoint privado inverso.", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "ID del endpoint del endpoint privado inverso.", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "ID del endpoint privado inverso.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "Tipo de autenticación del clúster de MSK. Obligatorio para el tipo MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN del clúster de MSK. Obligatorio para el tipo MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "Nombres DNS privados del endpoint privado inverso.", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "ID del servicio de ClickHouse al que está asociado el endpoint privado inverso.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Estado del endpoint privado inverso.", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "Tipo de endpoint privado inverso.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Nombre del servicio del endpoint de VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID de configuración del recurso de VPC. Obligatorio para el tipo VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN del recurso compartido del recurso de VPC. Obligatorio para el tipo VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "Descripción del endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador del endpoint privado", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Lista de los ID de endpoints privados disponibles que pueden adjuntarse al servicio", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Este es el ID que se devuelve después de configurar una región para Bring Your Own Cloud (BYOC). Cuando se especifica el parámetro byocId, también son obligatorios los parámetros minReplicaMemoryGb y maxReplicaGb, con valores entre los siguientes tamaños: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Versión de ClickHouse del servicio.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de cumplimiento normativo del servicio.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Timestamp de creación del servicio. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Warehouse de datos que contiene este servicio", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Rol opcional que se utilizará para el cifrado de disco", + "type": "string" + }, + "encryptionKey": { + "description": "Clave de cifrado de disco proporcionada por el cliente, opcional", + "type": "string" + }, + "encryptionRoleId": { + "description": "El ID del rol de IAM utilizado para el cifrado. Solo está disponible si hasTransparentDataEncryption es true.", + "type": "string" + }, + "endpoints": { + "description": "Lista de todos los endpoints del servicio.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "true si el servicio debe tener habilitado el Cifrado transparente de datos (TDE). TDE solo está disponible para los niveles de la organización ENTERPRISE y solo puede habilitarse al crear el servicio.", + "type": "boolean" + }, + "iamRole": { + "description": "Rol de IAM utilizado para acceder a objetos en S3", + "type": "string" + }, + "id": { + "description": "ID único del servicio.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Cuando se establece en true, el servicio puede escalar hasta cero cuando está inactivo. true de forma predeterminada.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Establezca el timeout mínimo de inactividad (en minutos). Debe ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder al servicio", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "true si este servicio es el servicio principal del warehouse de datos", + "type": "boolean" + }, + "isReadonly": { + "description": "true si este servicio es de solo lectura. Solo puede ser de solo lectura si se proporciona un dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memoria total máxima de cada réplica durante el autoescalado en Gb. Debe ser un múltiplo de 4 y menor o igual que 120* para servicios no de pago, o 356* para servicios de pago. * - el tamaño máximo de la réplica está sujeto a la disponibilidad de hardware del proveedor de Cloud en la región seleccionada. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED: inexacto para servicios con un número de réplicas distinto del predeterminado. Memoria máxima de tres workers durante el autoescalado en Gb. Disponible solo para servicios 'production'. Debe ser un múltiplo de 12 y menor o igual que 360 para servicios no de pago, o 1068 para servicios de pago.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memoria total mínima de cada réplica durante el autoescalado en Gb. Debe ser un múltiplo de 4 y mayor o igual que 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED: inexacto para servicios con un número de réplicas distinto del predeterminado. Memoria mínima de tres workers durante el autoescalado en Gb. Disponible solo para servicios 'production'. Debe ser un múltiplo de 12 y mayor o igual que 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nombre del servicio. Cadena alfanumérica con espacios en blanco de hasta 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas del servicio. El número de réplicas debe estar entre 2 y 20 para el primer servicio de un warehouse. Los servicios que se crean en un warehouse existente pueden tener tan solo 1 réplica. Pueden aplicarse restricciones adicionales según el nivel de su organización. El valor predeterminado es 1 para el nivel BASIC y 3 para los niveles SCALE y ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Lista de endpoints privados", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Perfil de instancia personalizado. Disponible solo para los niveles de la organización ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Proveedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Región del servicio.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Seleccione fast si desea obtener nuevas versiones de ClickHouse tan pronto como estén disponibles. Obtendrá nuevas funcionalidades más rápido, pero con un mayor riesgo de errores. Seleccione slow si desea aplazar las versiones para disponer de más tiempo para realizar pruebas. Esta funcionalidad solo está disponible para servicios de producción. default es el canal de versiones regular.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Estado actual del servicio.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "DEPRECATED para los niveles de la organización BASIC, SCALE y ENTERPRISE. Nivel del servicio: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Los servicios de producción escalan; los de Development tienen un tamaño fijo. Los servicios de Azure no admiten el nivel Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "El ID de la clave de Cifrado transparente de datos utilizada para el servicio. Solo está disponible si hasTransparentDataEncryption es true.", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "Nombre del host del servicio", + "type": "string" + }, + "port": { + "description": "Puerto numérico", + "type": "number" + }, + "protocol": { + "description": "Protocolo del endpoint: 'https', 'nativesecure', 'mysql'.", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "Nombre de usuario opcional para el endpoint", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "Habilitar o deshabilitar el endpoint", + "type": "boolean" + }, + "protocol": { + "description": "Protocolo del endpoint", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "Hash opcional de contraseña con double SHA1 para el protocolo MySQL. Si no se proporciona newPasswordHash, esta clave se ignorará y se usará la contraseña generada. Algorithm: echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "Hash de contraseña opcional. Se utiliza para evitar la transmisión de la contraseña por la red. Si no se proporciona, se genera una nueva contraseña y se incluye en la respuesta. De lo contrario, se usa este hash. Algorithm: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "Nueva contraseña del servicio. Se proporciona solo si no había 'newPasswordHash' en la solicitud", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "Lista de endpoints del servicio que se van a cambiar", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "Nombre del servicio. Cadena alfanumérica con espacios de hasta 50 caracteres.", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "Seleccione fast si quiere recibir las nuevas versiones de ClickHouse en cuanto estén disponibles. Recibirá nuevas funcionalidades más rápido, pero con un mayor riesgo de errores. Seleccione slow si desea aplazar las versiones para disponer de más tiempo para hacer pruebas. Esta funcionalidad solo está disponible para servicios de 'production'. El valor predeterminado es el regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "El id de la clave que se va a rotar", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "ID de Backup opcional que se usa como estado inicial del nuevo servicio. Cuando se usa, la región y el nivel de la nueva instancia deben ser los mismos que los de la instancia original.", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "Este es el ID que se devuelve después de configurar una región para Bring Your Own Cloud (BYOC). Cuando se especifica el parámetro byocId, también son obligatorios los parámetros minReplicaMemoryGb y maxReplicaGb, con valores entre los siguientes tamaños: 48, 116, 172, 232.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de cumplimiento normativo del servicio.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "Warehouse de datos que contiene este servicio", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Role opcional que se usará para el cifrado de disco", + "type": "string" + }, + "encryptionKey": { + "description": "Clave de cifrado de disco opcional proporcionada por el cliente", + "type": "string" + }, + "endpoints": { + "description": "Lista de endpoints del servicio para habilitar o deshabilitar", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "True si el servicio debe tener habilitado el Cifrado transparente de datos (TDE). TDE solo está disponible para los niveles de la organización ENTERPRISE y solo puede habilitarse al crear el servicio.", + "type": "boolean" + }, + "idleScaling": { + "description": "Cuando se establece en true, el servicio puede escalar hasta cero cuando está idle. True de forma predeterminada.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Establezca el timeout mínimo de idling (en minutos). Debe ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder al servicio", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "True si este servicio es read-only. Solo puede ser read-only si se proporciona un dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memoria total máxima de cada réplica durante el autoescalado, en Gb. Debe ser un múltiplo de 4 y menor o igual que 120* para servicios no pagos o 356* para servicios pagos.* - el tamaño máximo de la réplica está sujeto a la disponibilidad de hardware del proveedor de Cloud en la región seleccionada. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED: no es preciso para servicios con una cantidad no predeterminada de réplicas. Memoria máxima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios 'production'. Debe ser un múltiplo de 12 y menor o igual que 360 para servicios no pagos o 1068 para servicios pagos.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memoria total mínima de cada réplica durante el autoescalado, en Gb. Debe ser un múltiplo de 4 y mayor o igual que 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED: no es preciso para servicios con una cantidad no predeterminada de réplicas. Memoria mínima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios 'production'. Debe ser un múltiplo de 12 y mayor o igual que 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nombre del servicio. Cadena alfanumérica con espacios de hasta 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas del servicio. La cantidad de réplicas debe estar entre 2 y 20 para el primer servicio de un warehouse. Los servicios que se crean en un warehouse existente pueden tener solo 1 réplica. Pueden aplicarse restricciones adicionales según el nivel de su organización. El valor predeterminado es 1 para el nivel BASIC y 3 para los niveles SCALE y ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "Para asociar el servicio con private endpoints, primero cree el servicio y luego use el endpoint `Update Service Basic Details` para modificar los private endpoints.", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "Acepte los terms y conditions de private preview. Solo es necesario al crear el primer servicio de la organización en caso de private preview", + "type": "boolean" + }, + "profile": { + "description": "Perfil de instancia personalizado. Solo disponible para los niveles de la organización ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Proveedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Región del servicio.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Seleccione fast si desea obtener las nuevas versiones de ClickHouse en cuanto estén disponibles. Obtendrá Nuevas características más rápido, pero con un mayor riesgo de errores. Seleccione slow si desea aplazar las versiones para tener más tiempo para probarlas. Esta característica solo está disponible para servicios de production. El valor predeterminado es el regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "DEPRECATED para los niveles de la organización BASIC, SCALE y ENTERPRISE. Nivel del servicio: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Los servicios Production escalan; los Development tienen un tamaño fijo. Los servicios de Azure no admiten el nivel Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "Contraseña del servicio recién creado.", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "Orígenes permitidos, como lista de dominios separados por comas", + "type": "string" + }, + "id": { + "description": "El id del endpoint de consulta del service", + "type": "string" + }, + "openApiKeys": { + "description": "Lista de claves de OpenAPI que pueden acceder al endpoint de consulta del service", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "Lista de roles que pueden acceder al endpoint de consulta del service", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Cuando se establece en true, el servicio puede escalar hasta cero cuando está inactivo. True de forma predeterminada.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Establece el tiempo de espera mínimo de inactividad (en minutos). Debe ser >= 5 minutos.", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "Memoria máxima de escalado automático en Gb para una sola réplica. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 4 y menor o igual que 120 para servicios no de pago o 356 para servicios de pago.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memoria mínima de escalado automático en Gb para una sola réplica. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 4 y mayor o igual que 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "Número de réplicas del servicio. El número de réplicas debe estar entre 2 y 20 para el primer servicio de un warehouse. Los servicios que se crean en un warehouse existente pueden tener tan solo 1 réplica. Pueden aplicarse restricciones adicionales según el nivel de tu organization. El valor predeterminado es 1 para el nivel BASIC y 3 para los niveles SCALE y ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Cuando se establece en true, el servicio puede reducir su escala a cero cuando está inactivo. True de forma predeterminada.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Establece el timeout mínimo de inactividad (en minutos). Debe ser >= 5 minutos.", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - inexacto para servicios con una cantidad de réplicas distinta de la predeterminada. Memoria máxima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 12 y menor o igual que 360 para servicios no de pago, o 1068 para servicios de pago.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - inexacto para servicios con una cantidad de réplicas distinta de la predeterminada. Memoria mínima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 12 y mayor o igual que 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "Número de réplicas del servicio. El número de réplicas debe estar entre 2 y 20 para el primer servicio de un warehouse. Los servicios que se creen en un warehouse existente pueden tener tan solo 1 réplica. Pueden aplicarse restricciones adicionales según el nivel de la organización. El valor predeterminado es 1 para el nivel BASIC y 3 para los niveles SCALE y ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Lista de identificadores de endpoints privados disponibles que se pueden adjuntar al servicio", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Este es el ID que se devuelve después de configurar una Region para Bring Your Own Cloud (BYOC). Cuando se especifica el parámetro byocId, también son obligatorios los parámetros minReplicaMemoryGb y maxReplicaGb, con valores incluidos entre los siguientes tamaños: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Versión de ClickHouse del servicio.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de cumplimiento normativo del servicio.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Timestamp de creación del servicio. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Almacén de datos que contiene este servicio", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Role opcional que se usará para el cifrado de disco", + "type": "string" + }, + "encryptionKey": { + "description": "Clave de cifrado de disco opcional proporcionada por el cliente", + "type": "string" + }, + "encryptionRoleId": { + "description": "El ID del IAM role usado para el cifrado. Solo está disponible si hasTransparentDataEncryption es true.", + "type": "string" + }, + "endpoints": { + "description": "Lista de todos los endpoints del servicio.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "True si el servicio debe tener habilitado el Cifrado transparente de datos (TDE). TDE solo está disponible para niveles de organización ENTERPRISE y solo puede habilitarse al crear el servicio.", + "type": "boolean" + }, + "iamRole": { + "description": "IAM role usado para acceder a objetos en S3", + "type": "string" + }, + "id": { + "description": "ID único del servicio.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Cuando se establece en true, el servicio puede reducir su escala a cero cuando está inactivo. True de forma predeterminada.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Establece el timeout mínimo de inactividad (en minutos). Debe ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de direcciones IP autorizadas para acceder al servicio", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "True si este servicio es el servicio principal del almacén de datos", + "type": "boolean" + }, + "isReadonly": { + "description": "True si este servicio es de solo lectura. Solo puede ser de solo lectura si se proporciona un dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memoria máxima de autoescalado en Gb para una sola réplica. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 4 y menor o igual que 120 para servicios no de pago, o 356 para servicios de pago.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - inexacto para servicios con una cantidad de réplicas distinta de la predeterminada. Memoria máxima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 12 y menor o igual que 360 para servicios no de pago, o 1068 para servicios de pago.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memoria mínima de autoescalado en Gb para una sola réplica. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 4 y mayor o igual que 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - inexacto para servicios con una cantidad de réplicas distinta de la predeterminada. Memoria mínima de tres workers durante el autoescalado, en Gb. Disponible solo para servicios de 'production'. Debe ser un múltiplo de 12 y mayor o igual que 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nombre del servicio. Cadena alfanumérica con espacios de hasta 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas del servicio. El número de réplicas debe estar entre 2 y 20 para el primer servicio de un warehouse. Los servicios que se creen en un warehouse existente pueden tener tan solo 1 réplica. Pueden aplicarse restricciones adicionales según el nivel de la organización. El valor predeterminado es 1 para el nivel BASIC y 3 para los niveles SCALE y ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Lista de endpoints privados", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Perfil de instancia personalizado. Solo disponible para niveles de organización ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Proveedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Región del servicio.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Selecciona fast si quieres obtener las nuevas versiones de ClickHouse en cuanto estén disponibles. Recibirás nuevas funcionalidades más rápido, pero con un mayor riesgo de errores. Selecciona slow si deseas aplazar las versiones para tener más tiempo para probarlas. Esta funcionalidad solo está disponible para servicios de production. El valor predeterminado es el canal de versiones regular.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Estado actual del servicio.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "DEPRECATED para los niveles de la organización BASIC, SCALE y ENTERPRISE. Nivel del servicio: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Los servicios de Production escalan; los de Development tienen un tamaño fijo. Los servicios de Azure no admiten el nivel Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "El ID de la clave de Cifrado transparente de datos usada para el servicio. Solo está disponible si hasTransparentDataEncryption es true.", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "Comando para cambiar el estado: 'start', 'stop'.", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "Costo total general de uso en ClickHouse Credits (CHCs).", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "Costo de backup en ClickHouse Credits (CHCs). Se aplica a las entidades dataWarehouse.", + "type": "number" + }, + "computeCHC": { + "description": "Costo de cómputo en ClickHouse Credits (CHCs). Se aplica a las entidades service y ClickPipe.", + "type": "number" + }, + "dataTransferCHC": { + "description": "Costo de transferencia de datos en ClickHouse Credits (CHCs). Se aplica a las entidades ClickPipe.", + "type": "number" + }, + "initialLoadCHC": { + "description": "Costo de la carga inicial y las resincronizaciones en ClickHouse Credits (CHCs). Se aplica a las entidades ClickPipe.", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "Costo de la transferencia de datos interregional de tier1 en ClickHouse Credits (CHCs). Se aplica a las entidades service.", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "Costo de la transferencia de datos interregional de tier2 en ClickHouse Credits (CHCs). Se aplica a las entidades service.", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "Costo de la transferencia de datos interregional de tier3 en ClickHouse Credits (CHCs). Se aplica a las entidades service.", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "Costo de la transferencia de datos interregional de tier4 en ClickHouse Credits (CHCs). Se aplica a las entidades service.", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "Costo de transferencia de datos en ClickHouse Credits (CHCs). Se aplica a las entidades service.", + "type": "number" + }, + "storageCHC": { + "description": "Costo de almacenamiento en ClickHouse Credits (CHCs). Se aplica a las entidades dataWarehouse.", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "ID del dataWarehouse al que pertenece esta entidad (o que es).", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "Fecha de uso. Fecha ISO-8601, basada en la zona horaria UTC.", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "ID único de la entidad.", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "Nombre de la entidad.", + "type": "string" + }, + "entityType": { + "description": "Tipo de entidad.", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "Cuando es true, el registro es inmutable. Los registros desbloqueados pueden cambiar hasta que se bloqueen.", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "ID del service al que pertenece esta entidad (o que es). Se establece en null para las entidades dataWarehouse.", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "Costo total de uso en ClickHouse Credits (CHCs) para esta entidad.", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "Usa el ID de la clave y el secreto de la clave obtenidos en la consola de ClickHouse Cloud: https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "Devuelve una lista con una única organización asociada a la API key de la solicitud.", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no procesará la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener la lista de organizaciones disponibles", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "Devuelve los detalles de una única organización. Para obtenerlos, la clave de autenticación debe pertenecer a la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener los detalles de la organización", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "Actualiza los campos de la organización. Requiere una clave de autenticación con el Role ADMIN.", + "parameters": [ + { + "description": "ID de la organización que se va a actualizar.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actualizar los detalles de la organización", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "Devuelve una lista de todas las actividades de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Fecha de inicio para una búsqueda", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Fecha de finalización para una búsqueda", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no procesará la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Lista de actividades de la organización", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "Devuelve una actividad de la organización por ID.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la actividad solicitada.", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actividad de la organización", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "Crea una nueva infraestructura BYOC en la organización. Devuelve la configuración de la infraestructura recién creada", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Crear infraestructura BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "Elimina una infraestructura BYOC de la organización", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la infraestructura BYOC solicitada", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Eliminar una infraestructura BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "Devuelve la lista de todas las invitaciones de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Listar todas las invitaciones", + "tags": [ + "User management" + ] + }, + "post": { + "description": "Crea una invitación para la organización.", + "parameters": [ + { + "description": "ID de la organización a la que se invitará al usuario.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Crear una invitación", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "Elimina una invitación de la organización.", + "parameters": [ + { + "description": "ID de la organización que tiene la invitación.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no procesará la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Eliminar invitación de la organización", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Devuelve los detalles de una invitación individual de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no procesará la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Obtener los detalles de la invitación", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "Devuelve una lista de todas las claves de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede procesar la solicitud o no la procesará debido a un problema que se considera un error del cliente." + } + }, + "summary": "Obtener la lista de todas las claves", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "Crea una nueva clave de API.", + "parameters": [ + { + "description": "ID de la organización que será propietaria de la clave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede procesar la solicitud o no la procesará debido a un problema que se considera un error del cliente." + } + }, + "summary": "Crear una clave", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "Elimina la clave de API. Solo se puede eliminar una clave que no se haya utilizado para autenticar la solicitud activa.", + "parameters": [ + { + "description": "ID de la organización propietaria de la clave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la clave que se va a eliminar.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del cliente." + } + }, + "summary": "Eliminar la clave", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "Devuelve los detalles de una clave.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la clave solicitada.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede procesar la solicitud o no la procesará debido a un problema que se considera un error del cliente." + } + }, + "summary": "Obtener los detalles de la clave", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "Actualiza las propiedades de la clave de API.", + "parameters": [ + { + "description": "ID de la organización propietaria de la clave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la clave que se va a actualizar.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del cliente." + } + }, + "summary": "Actualizar la clave", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "Devuelve una lista de todos los miembros de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del cliente." + } + }, + "summary": "Listar los miembros de la organización", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "Elimina a un usuario de la organización", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del usuario solicitado.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Eliminar un miembro de la organización", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Devuelve los detalles de un solo miembro de la organización.", + "parameters": [ + { + "description": "ID de la organización de la que forma parte el miembro.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del usuario solicitado.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del cliente." + } + }, + "summary": "Obtener los detalles del miembro", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "Actualiza el rol del miembro de la organización.", + "parameters": [ + { + "description": "ID de la organización a la que pertenece el miembro.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del usuario a modificar", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Actualizar el miembro de la organización", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "Obsoleto. Consulte la [documentación](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list) para seguir el proceso actualizado.", + "parameters": [ + { + "description": "ID de la organization solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Identificador del proveedor de Cloud. Uno de aws, gcp o azure.", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Identificador de Region dentro de proveedores de Cloud específicos.", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener la configuración del Private Endpoint para una región dentro del Cloud Provider de una organización", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "Devuelve las métricas de Prometheus de todos los servicios de una organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Devuelve una lista filtrada de métricas de Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener las métricas de la organización", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "Devuelve una lista de todos los servicios de la organización.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Criterios de filtro que se aplicarán al recuperar el recurso. Actualmente, solo se admite el filtrado por etiquetas de recurso.", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Lista de servicios de la organización", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Crea un nuevo servicio en la organización y devuelve el estado actual del servicio y una contraseña para acceder a él. El servicio se inicia de forma asíncrona.", + "parameters": [ + { + "description": "ID de la organización que será propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Crear un nuevo servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "Elimina el servicio. El servicio debe estar detenido y se elimina de forma asíncrona después de esta llamada al método.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio que se va a eliminar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Eliminar el servicio", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Devuelve un servicio que pertenece a la organización", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Obtener los detalles del servicio", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "Actualiza los datos básicos del servicio, como el nombre del servicio o la IP Access List.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio que se va a actualizar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Actualizar los detalles básicos del servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "Devuelve la configuración de copias de seguridad del servicio.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Identificador único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Obtener la configuración de copia de seguridad del servicio", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "Actualiza la configuración de copias de seguridad del servicio. Requiere el rol ADMIN de la clave de autenticación. Establecer las propiedades con valor NULL restablecerá las propiedades a sus valores predeterminados.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Identificador único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Actualizar la configuración de copia de seguridad del servicio", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "Devuelve una lista de todos los backups del servicio. Los backups más recientes aparecen primero en la lista.", + "parameters": [ + { + "description": "ID de la organización propietaria del backup.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio a partir del cual se creó el backup.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Identificador único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Lista de copias de seguridad del servicio", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "Devuelve la información de una única copia de seguridad.", + "parameters": [ + { + "description": "ID de la organización propietaria de la copia de seguridad.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio a partir del cual se creó la copia de seguridad.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID de la copia de seguridad solicitada.", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Identificador único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del cliente." + } + }, + "summary": "Obtener los detalles de la copia de seguridad", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Devuelve una lista de ClickPipes.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Listar ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Crea un nuevo ClickPipe.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio para el que se va a crear el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Crear ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios importantes incompatibles en el futuro.

Elimina el ClickPipe especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe que se va a eliminar.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Eliminar ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios importantes incompatibles en el futuro.

Devuelve el ClickPipe especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe solicitado.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Obtener ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios importantes incompatibles en el futuro.

Actualiza el ClickPipe especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio para el que se crea el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe solicitado.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Actualizar ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Cambia la configuración de escalado del ClickPipe especificado.", + "parameters": [ + { + "description": "ID de la organización a la que pertenece el servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio al que pertenece el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe cuya configuración de escalado se actualizará.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Escalado de ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios importantes incompatibles en el futuro.

Devuelve la configuración avanzada del ClickPipe especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio al que pertenece el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe del que se obtendrá la configuración.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener la configuración de ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Actualiza la configuración avanzada del ClickPipe especificado. Envía pares clave-valor en los que los valores pueden ser cadenas, números o booleanos.", + "parameters": [ + { + "description": "ID de la organización a la que pertenece el servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio al que pertenece el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe cuya configuración se actualizará.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actualizar la configuración de ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Inicia, detén o resincroniza el ClickPipe. Al detener un ClickPipe, se detendrá el proceso de ingestión desde cualquier estado. Se permite iniciarlo para ClickPipes en estado \"Stopped\" o con estado \"Failed\". La resincronización solo está disponible para pipes de Postgres y puede realizarse desde cualquier estado.", + "parameters": [ + { + "description": "ID de la organización a la que pertenece el servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio al que pertenece el ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del ClickPipe cuyo estado se actualizará.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actualizar el estado de ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Obtenga la configuración de scaling de DB ClickPipes.\n\nLa infraestructura se comparte entre todos los DB ClickPipes del servicio, tanto para initial load como para CDC. A efectos de facturación, 2 CPU cores y 8 GB de RAM [corresponden](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) a una compute unit.\n\n**Este endpoint estará disponible una vez que se haya aprovisionado al menos un DB ClickPipe.**", + "parameters": [ + { + "description": "ID de la organization propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener el escalado de CDC de ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Actualice la configuración de scaling de DB ClickPipes.\n\nLa infraestructura se comparte entre todos los DB ClickPipes del servicio, tanto para initial load como para CDC. La configuración de scaling puede tardar unos minutos en propagarse por completo.\n\nA efectos de facturación, 2 CPU cores y 8 GB de RAM [corresponden](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) a una compute unit. Si cambia el nivel de la organización, los DB ClickPipes se [reescalarán](https://clickhouse.com/docs/cloud/manage/billing/overview#compute) según corresponda.\n\n**Este endpoint estará disponible una vez que se haya aprovisionado al menos un DB ClickPipe.**", + "parameters": [ + { + "description": "ID de la organization propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actualizar el escalado de CDC de ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Devuelve una lista de reverse private endpoints para el servicio especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Listar Reverse Private Endpoint", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan cambios incompatibles en el futuro.

Crea un nuevo reverse private endpoint.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Crear Reverse Private Endpoint", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan breaking changes en el futuro.

Elimina el reverse private endpoint con el ID especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del reverse private endpoint que se va a eliminar.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Eliminar Reverse Private Endpoint", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Este endpoint está en beta.** El contrato de la API es estable y no se esperan breaking changes en el futuro.

Devuelve el reverse private endpoint con el ID especificado.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio propietario del Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del reverse private endpoint que se va a obtener.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Obtener Reverse Private Endpoint", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "Establece una nueva contraseña para el servicio", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio cuya contraseña se va a actualizar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no procesará la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Actualizar la contraseña del servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "Crea un nuevo endpoint privado. El endpoint privado se asociará a este servicio y a esta organización", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no procesará la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Crear un endpoint privado", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "Información necesaria para configurar un Private Endpoint", + "parameters": [ + { + "description": "ID de la organization solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del service solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Obtener la configuración del endpoint privado", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "Devuelve métricas de Prometheus para un servicio.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Devuelve una lista filtrada de métricas de Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no procesará la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener las métricas del servicio", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "Actualiza los límites mínimo y máximo de memoria por réplica, así como el comportamiento del escalado en modo inactivo del servicio. La configuración de memoria está disponible solo para servicios de \"producción\" y debe ser un múltiplo de 4 a partir de 8 GB. Póngase en contacto con soporte para habilitar el ajuste de numReplicas.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio cuyos parámetros de escalado se van a actualizar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Actualizar la configuración del escalado automático del servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "Actualiza los límites mínimo y máximo de memoria total, así como el comportamiento del escalado en modo inactivo del servicio. La configuración de memoria está disponible solo para servicios de \"producción\" y debe ser un múltiplo de 12 a partir de 24 GB. Póngase en contacto con soporte para habilitar el ajuste de numReplicas.", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio cuyos parámetros de escalado se van a actualizar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Actualizar la configuración del escalado automático del servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "Esta es una feature experimental. Póngase en contacto con support para habilitarla.", + "parameters": [ + { + "description": "ID de la organization solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del service solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Eliminar el endpoint de consulta del servicio para una instancia determinada", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Esta es una feature experimental. Póngase en contacto con support para habilitarla.", + "parameters": [ + { + "description": "ID de la organization solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del service solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a un problema que se considera un error del client." + } + }, + "summary": "Obtener el endpoint de consulta del servicio para una instancia determinada", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Esta es una feature experimental. Póngase en contacto con support para habilitarla.", + "parameters": [ + { + "description": "ID de la organization solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Crear o actualizar el endpoint de consulta del servicio para una instancia determinada", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "Inicia o detiene el servicio", + "parameters": [ + { + "description": "ID de la organización propietaria del servicio.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID del servicio cuyo estado se va a actualizar.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta satisfactoria" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El servidor no puede o no quiere procesar la solicitud debido a algo que se percibe como un error del client." + } + }, + "summary": "Actualizar el estado del servicio", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "Devuelve un total general y una lista diaria, por entidad, de registros de costo de uso de la organización durante el período consultado (máximo 31 días). Todos los días, tanto de la solicitud como de la respuesta, se evalúan según la zona horaria UTC.", + "parameters": [ + { + "description": "ID de la organización solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Fecha de inicio del informe, por ejemplo, 2024-12-19.", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Fecha de finalización (incluida) del informe, por ejemplo, 2024-12-20. Esta fecha no puede ser más de 30 días posterior a from_date (para un período máximo consultado de 31 días).", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único asignado a cada solicitud. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Respuesta correcta" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descripción detallada del error.", + "type": "string" + }, + "status": { + "description": "Código de estado HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "El server no puede o no quiere procesar la solicitud debido a algo que se considera un error del client." + } + }, + "summary": "Obtener los costes de uso de la organización", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/es/_specs/hyperdx-openapi.json b/es/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..e3a4595b6 --- /dev/null +++ b/es/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "Función de agregación que se usará en los datos", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "Campo que se va a agregar", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "Campos por los que se agruparán los resultados", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "Tipo de dato de la métrica", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "Nombre de la métrica (para fuentes de datos de métricas)", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "ID de la fuente de datos de esta serie", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "Condición de filtro en sintaxis de consulta de Lucene", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "Lenguaje de consulta usado en la cláusula WHERE", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "Valores de agrupación si se especificó groupBy", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "Valor de la primera serie", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "Valor de la segunda serie", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "Marca de tiempo del punto de datos (hora de inicio del bucket)", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "Marca de tiempo de fin en milisegundos", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "Tamaño del bucket de tiempo para las agregaciones", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "Array de configuraciones de series", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "Formato de los datos devueltos", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "Marca de tiempo de inicio en milisegundos", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "API para gestionar alertas y dashboards de HyperDX", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "Obtiene una lista de todas las alertas del equipo autenticado", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "Lista de alertas", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "Alertas obtenidas correctamente" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + } + }, + "summary": "Listar alertas", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "Crea una nueva alerta", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "Crear una alerta basada en tiles", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta creada correctamente" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Error del servidor o fallo de validación" + } + }, + "summary": "Crear alerta", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "Elimina una alerta", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "ID de la alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Alerta eliminada correctamente" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta no encontrada" + } + }, + "summary": "Eliminar alerta", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "Recupera una alerta específica por ID", + "operationId": "getAlert", + "parameters": [ + { + "description": "ID de la alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "Respuesta de una alerta", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta recuperada correctamente" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta no encontrada" + } + }, + "summary": "Obtener alerta", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "Actualiza una alerta existente", + "operationId": "updateAlert", + "parameters": [ + { + "description": "ID de la alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "Actualizar las propiedades de la alerta", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta actualizada correctamente" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta no encontrada" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Error del servidor o error de validación" + } + }, + "summary": "Actualizar alerta", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "Obtiene datos de series temporales según los parámetros de serie configurados", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "Consulta básica de series temporales", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "Serie de datos de métricas", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "Varias series con group by", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "Series de varias fuentes", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "Datos de series temporales agrupados", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "Puntos de datos de series temporales", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "Datos de series temporales obtenidos correctamente" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Parámetros de solicitud no válidos" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Fuente no encontrada" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Error del servidor" + } + }, + "summary": "Consultar datos de series de un gráfico", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "Obtiene una lista de todos los dashboards del equipo autenticado", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "Dashboards obtenidos correctamente" + }, + "401": { + "description": "No autorizado" + } + }, + "summary": "Listar dashboards", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "Crea un nuevo dashboard", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "Dashboard con varios tipos de gráficos", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "Dashboard con gráfico de series temporales", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "Respuesta del dashboard creado", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard creado correctamente" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Error del servidor o fallo de validación" + } + }, + "summary": "Crear dashboard", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "Elimina un dashboard", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "ID del dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Dashboard eliminado correctamente" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No se encontró el dashboard" + } + }, + "summary": "Eliminar dashboard", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "Obtiene un dashboard específico por ID", + "operationId": "getDashboard", + "parameters": [ + { + "description": "ID del dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "Respuesta de un dashboard", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard obtenido correctamente" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Dashboard no encontrado" + } + }, + "summary": "Obtener dashboard", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "Actualiza un dashboard existente", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "ID del dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "Actualizar las propiedades y los tiles del dashboard", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "Respuesta del dashboard actualizado", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard actualizado correctamente" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "No autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Dashboard no encontrado" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Error del servidor o fallo de validación" + } + }, + "summary": "Actualizar dashboard", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "Servidor de API de producción", + "url": "https://api.hyperdx.io" + }, + { + "description": "Servidor actual", + "url": "/" + } + ], + "tags": [ + { + "description": "Endpoints para gestionar dashboards y sus visualizaciones", + "name": "Dashboards" + }, + { + "description": "Endpoints para gestionar alertas de monitorización", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/es/clickstack/features/dashboards/overview.mdx b/es/clickstack/features/dashboards/overview.mdx index 46b2043a1..a5191b62a 100644 --- a/es/clickstack/features/dashboards/overview.mdx +++ b/es/clickstack/features/dashboards/overview.mdx @@ -31,7 +31,7 @@ Cada visualización comienza seleccionando una **fuente de datos**, seguida de u Por ejemplo, podrías crear un gráfico con el número de errores (`count()`) agrupados por nombre de servicio. -Para los ejemplos siguientes, usamos el conjunto de datos remoto disponible en [sql.clickhouse.com](https://sql.clickhouse.com), descrito en la guía ["Remote Demo Dataset"](/es/clickstack/example-datasets/remote-demo-data). **También puedes reproducir estos ejemplos visitando [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).** +Para los ejemplos siguientes, usamos el conjunto de datos remoto disponible en [sql.clickhouse.com](https://sql.clickhouse.com), descrito en la guía ["Conjunto de datos de demostración remoto"](/es/clickstack/example-datasets/remote-demo-data). **También puedes reproducir estos ejemplos visitando [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).** @@ -63,6 +63,10 @@ Para los ejemplos siguientes, usamos el conjunto de datos remoto disponible en [ Visualización simple 2 + Para crear una serie similar a una existente, puedes duplicarla en lugar de empezar desde cero. Haz clic en el icono de copia (`Duplicate series`) en una fila de serie para insertar una copia directamente debajo. La copia conserva la configuración de la serie de origen, como la métrica, la columna y el filtro. Después, solo tienes que cambiar los campos que sean distintos (por ejemplo, la agregación) y asignarle a la copia su propio alias. La duplicación está disponible siempre que se admitan varias series. Está oculta en los tipos de visualización que solo permiten una serie, como `Number`, `Pie` y `Heatmap`. + + El icono de copia Duplicate series y su descripción emergente en una fila de serie de un gráfico + Las visualizaciones pueden crearse a partir de cualquier fuente de datos: métricas, traza o logs. ClickStack trata todos estos datos como eventos wide. Cualquier **columna numérica** puede representarse en un gráfico a lo largo del tiempo, y las columnas de tipo **cadena**, **fecha** o **numérico** pueden usarse para agrupaciones. diff --git a/es/clickstack/ingesting-data/collector.mdx b/es/clickstack/ingesting-data/collector.mdx index b37887d5b..27783e6f6 100644 --- a/es/clickstack/ingesting-data/collector.mdx +++ b/es/clickstack/ingesting-data/collector.mdx @@ -104,7 +104,7 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa - La instancia de ClickHouse de destino se configura mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` y `CLICKHOUSE_PASSWORD`. El valor de `CLICKHOUSE_ENDPOINT` debe ser el endpoint HTTP completo de ClickHouse Cloud, incluyendo el protocolo y el puerto; por ejemplo, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. + La instancia de ClickHouse de destino se configura mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` y `CLICKHOUSE_PASSWORD`. El valor de `CLICKHOUSE_ENDPOINT` debe ser el endpoint HTTP completo de ClickHouse Cloud, incluyendo el protocolo y el puerto; por ejemplo, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. Para obtener más información sobre cómo recuperar sus credenciales de Managed ClickStack, consulte [aquí](/es/products/cloud/guides/sql-console/connection-details). @@ -118,7 +118,7 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa #### Configuración de la instancia de Managed ClickStack - El OpenTelemetry collector puede configurarse para usar una instancia de Managed ClickStack mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` y `CLICKHOUSE_PASSWORD`. La forma en que se configuran depende del método de implementación: + El OpenTelemetry collector puede configurarse para usar una instancia de Managed ClickStack mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` y `CLICKHOUSE_PASSWORD`. La forma en que se configuran depende del método de implementación: @@ -162,7 +162,7 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa Con Docker Compose, modifique la configuración del collector usando las mismas variables de entorno mencionadas anteriormente: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # extensión health_check - - '24225:24225' # receptor fluentd - - '4317:4317' # receptor OTLP gRPC - - '4318:4318' # receptor OTLP HTTP - - '8888:8888' # extensión de métricas + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver + - '4317:4317' # OTLP gRPC receiver + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,21 +261,21 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa - La instancia de ClickHouse de destino se configura mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` y `CLICKHOUSE_PASSWORD`. El valor de `CLICKHOUSE_ENDPOINT` debe ser el endpoint HTTP completo de ClickHouse, incluido el protocolo y el puerto; por ejemplo, `http://localhost:8123`. + La instancia de ClickHouse de destino se configura mediante las variables de entorno `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` y `CLICKHOUSE_PASSWORD`. El valor de `CLICKHOUSE_ENDPOINT` debe ser el endpoint HTTP completo de ClickHouse, incluido el protocolo y el puerto; por ejemplo, `http://localhost:8123`. **Estas variables de entorno pueden utilizarse con cualquiera de las distribuciones de Docker que incluyen el conector.** - **Usuario de producción** + **Usuario para producción** - Debes usar en producción un usuario con las [credenciales adecuadas](/es/clickstack/ingesting-data/collector#creating-an-ingestion-user). + En producción, debe usar un usuario con las [credenciales adecuadas](/es/clickstack/ingesting-data/collector#creating-an-ingestion-user). ### Modificación de la configuración #### Configuración de la instancia de ClickHouse - El OpenTelemetry collector puede configurarse para usar una instancia de ClickHouse mediante las variables de entorno `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` y `CLICKHOUSE_PASSWORD`. La configuración de estas variables depende del método de implementación: + El OpenTelemetry collector puede configurarse para usar una instancia de ClickHouse mediante las variables de entorno `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` y `CLICKHOUSE_PASSWORD`. La configuración de estas variables depende del método de implementación: @@ -322,7 +322,7 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa Con Docker Compose, modifique la configuración del collector usando las mismas variables de entorno mencionadas anteriormente: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ Los usuarios que implementen OTel collectors en el rol de agente normalmente usa CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # extensión health_check - - '24225:24225' # receptor Fluentd - - '4317:4317' # receptor OTLP gRPC - - '4318:4318' # receptor OTLP HTTP - - '8888:8888' # extensión de métricas + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver + - '4317:4317' # OTLP gRPC receiver + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/es/clickstack/mcp.mdx b/es/clickstack/mcp.mdx index 4e5880d35..ca28ad56f 100644 --- a/es/clickstack/mcp.mdx +++ b/es/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'Servidor MCP de ClickStack' sidebarTitle: 'Servidor MCP' description: 'Conecta asistentes de IA a ClickStack mediante el servidor del Model Context Protocol (MCP)' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'IA', 'observabilidad', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'IA', 'observabilidad', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -23,108 +23,218 @@ El servidor MCP está disponible en los siguientes tipos de implementación de C | ------------------------------------------------- | ------------- | | **Open Source ClickStack** | Disponible | | **BYOC (Bring Your Own Cloud)** | Disponible | -| **Managed ClickStack** | Próximamente | +| **ClickStack on ClickHouse Cloud** | Disponible | | **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | No compatible | - - **Managed ClickStack** + + **Configuración diferente para ClickHouse Cloud frente a OSS/BYOC** - La compatibilidad del servidor MCP con Managed ClickStack se encuentra en desarrollo activo y estará disponible próximamente. Las instrucciones de esta página se aplican a las implementaciones de Open Source y BYOC. - + ClickStack on ClickHouse Cloud usa un endpoint y un método de autenticación diferentes a los de las implementaciones de Open Source y BYOC. Consulte la sección [ClickStack on ClickHouse Cloud](#managed-clickstack) más abajo para ver la configuración específica de Cloud. + -
- ## Requisitos previos +
+ ## ClickStack on ClickHouse Cloud
-Antes de conectar un cliente MCP, necesitas: +ClickStack on ClickHouse Cloud se conecta a través del endpoint MCP de Cloud en `https://mcp.clickhouse.cloud/clickstack` y se autentica con OAuth 2.0. La autenticación mediante API key no es compatible con este endpoint. -* Una instancia de ClickStack en ejecución (consulta [Implementación](/es/clickstack/deployment/overview) para ver las opciones de configuración) -* Una **Personal API Access Key** — encontrarás la tuya en HyperDX, en **Team Settings → API Keys → Personal API Access Key** +
+ ### Requisitos previos +
-Personal API Access Key en Team Settings +* Un servicio de ClickHouse Cloud en funcionamiento con [ClickStack habilitado](/es/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud) +* [MCP habilitado](/es/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) en el servicio — abre la consola de Cloud, haz clic en **Conectar**, selecciona **Conectar con MCP** y actívalo - - La Personal API Access Key es distinta de la **API key de ingesta** que se encuentra en Team Settings y se usa para autenticar los datos de telemetría enviados al collector de OpenTelemetry. - +
+ ### Endpoint +
-
- ## Punto de conexión +```text +https://mcp.clickhouse.cloud/clickstack +``` + +La autenticación utiliza OAuth 2.0. Cuando tu cliente MCP se conecta por primera vez, se abre una ventana del navegador para que inicies sesión con tus credenciales de ClickHouse Cloud. No necesitas ninguna API key. + +
+ ### Conectar un cliente MCP
-El servidor MCP está disponible en la ruta `/api/mcp` de la URL del frontend de ClickStack: +Cada cliente gestiona el flujo de OAuth automáticamente en la primera conexión. -Por ejemplo, con una implementación local predeterminada: + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -Reemplace `localhost:8080` por el host y el puerto de su instancia si ha personalizado los valores predeterminados. + Inicia Claude Code y ejecuta `/mcp`; luego, selecciona `clickstack-cloud` para completar el flujo de OAuth. + - - Los ejemplos de esta página usan la URL de la aplicación frontend (puerto `8080` de forma predeterminada). También puede acceder directamente al servidor MCP a través del backend en `/mcp`, pero no todas las implementaciones exponen el backend, por lo que esta documentación usa la ruta del frontend. - + + Agrega lo siguiente a `.cursor/mcp.json`: -El servidor MCP usa el transporte **Streamable HTTP** con autenticación mediante **token Bearer**. + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Agrega lo siguiente a `.vscode/mcp.json`: + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Agrega lo siguiente a `opencode.json`: + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Cualquier cliente MCP que admita **Streamable HTTP** con OAuth puede conectarse. Configúralo con lo siguiente: -
- ## Conectar un cliente MCP + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### Seleccionar un servicio específico
-Los ejemplos siguientes muestran cómo configurar clientes MCP populares. Reemplace `` por la URL de su instancia (por ejemplo, `http://localhost:8080`) y `` por su Personal API Access Key. +Sin el encabezado `x-service-id`, las solicitudes se dirigen de forma predeterminada al primer servicio de ClickStack aprovisionado y utilizado por su cuenta. Para dirigirse a otro servicio, pase `x-service-id: ` como encabezado en la configuración de su cliente MCP. -
- ### Claude Code +
+ ## Open Source y BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +Las implementaciones de Open Source y BYOC usan el endpoint MCP integrado de la instancia de ClickStack con autenticación mediante token Bearer. -
- ### Cursor +
+ ### Requisitos previos
-Añade lo siguiente a `.cursor/mcp.json` de tu proyecto o a la configuración global de Cursor: +* Una instancia de ClickStack en ejecución (consulta [Implementación](/es/clickstack/deployment/overview) para ver las opciones de configuración) +* Una **Personal API Access Key** — encontrarás la tuya en HyperDX, en **configuración del equipo → API Keys → Personal API Access Key** -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Personal API Access Key en configuración del equipo + + + La Personal API Access Key es distinta de la **API key de ingesta** que se encuentra en configuración del equipo y se usa para autenticar los datos de telemetría enviados al collector de OpenTelemetry. + -
- ### OpenCode +
+ ### Punto de conexión
-Añade lo siguiente a la configuración de `opencode.json`: +El servidor MCP está disponible en la ruta `/api/mcp` de la URL del frontend de ClickStack. Por ejemplo, con una implementación local predeterminada, la URL es `http://localhost:8080/api/mcp`. Reemplace `localhost:8080` por el host y el puerto de su instancia si ha personalizado los valores predeterminados. -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + Los ejemplos de esta página usan la URL de la aplicación frontend (puerto `8080` de forma predeterminada). También puede acceder directamente al servidor MCP a través del backend en `/mcp`, pero no todas las implementaciones exponen el backend, por lo que esta documentación usa la ruta del frontend. + + +El servidor MCP usa el transporte **Streamable HTTP** con autenticación mediante **token Bearer**. -
- ### Otros clientes +
+ ### Conectar un cliente MCP
-Cualquier cliente MCP compatible con el transporte **Streamable HTTP** puede conectarse. Configúralo así: +Sustituye `` por la URL de tu instancia (por ejemplo, `http://localhost:8080`) y `` por tu clave personal de acceso a la API. + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + Agrega lo siguiente a `.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Agrega lo siguiente a `.vscode/mcp.json`: + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + Agrega lo siguiente a `opencode.json`: + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Cualquier cliente MCP compatible con **Streamable HTTP** puede conectarse. Configúralo con: -* **URL:** `/api/mcp` -* **Encabezado:** `Authorization: Bearer ` + * **URL:** `/api/mcp` + * **Encabezado:** `Authorization: Bearer ` + +
## ¿Qué puedes hacer con MCP? @@ -143,10 +253,12 @@ Una vez conectado, tu asistente de IA tiene acceso a un conjunto de herramientas El conjunto concreto de herramientas puede ampliarse con el tiempo. Tu cliente MCP detectará automáticamente las herramientas disponibles al conectarse.
- ## Uso con varios equipos + ## Uso con varios equipos (OSS/BYOC)
-De forma predeterminada, las solicitudes de MCP se ejecutan en el contexto de tu equipo principal. Si perteneces a varios equipos, puedes dirigirte a un equipo concreto enviando el encabezado `x-hdx-team` con el ID del equipo junto con el encabezado `Authorization`. Si se omite el encabezado, se usa tu equipo principal. Si especificas un equipo al que no perteneces, la solicitud se rechaza con un error `401`. +Esto se aplica solo a implementaciones de Open Source y BYOC. Para ClickStack on ClickHouse Cloud, consulta [Dirigirse a un servicio específico](#managed-service-override). + +De forma predeterminada, las solicitudes de MCP se ejecutan en el contexto de tu equipo principal. Si perteneces a varios equipos, pasa el encabezado `x-hdx-team` con el ID del equipo junto con el encabezado `Authorization`. Si se omite el encabezado, se usa tu equipo principal. Si especificas un equipo al que no perteneces, la solicitud se rechaza con un error `401`. Usa la herramienta de listado de equipos de tu cliente MCP para ver a qué equipos tienes acceso y cuál está activo. @@ -154,6 +266,29 @@ Usa la herramienta de listado de equipos de tu cliente MCP para ver a qué equip ## Solución de problemas
+
+ ### ClickStack on ClickHouse Cloud +
+ + + * Confirma que tu cliente MCP sea compatible con OAuth 2.0. Los clientes que solo admiten token Bearer o transporte stdio no pueden autenticarse con el endpoint de Cloud. + * Comprueba que tu navegador no esté bloqueando la ventana emergente o la redirección de OAuth. + * Verifica que tu cuenta de ClickHouse Cloud tenga acceso a la organización y al servicio. + + + + * Confirma que estás usando el endpoint de ClickStack (`https://mcp.clickhouse.cloud/clickstack`), no el endpoint general de MCP de Cloud (`https://mcp.clickhouse.cloud/mcp`). + * Verifica que [MCP esté habilitado](/es/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) en el servicio de la consola de Cloud. + + + + Sin el encabezado `x-service-id`, las solicitudes se envían por defecto al primer servicio de ClickStack aprovisionado y usado por tu cuenta. Pasa el encabezado para dirigirte a un servicio específico. Consulta [Dirigirse a un servicio específico](#managed-service-override). + + +
+ ### Open Source y BYOC +
+ * Verifica que estés usando la **Personal API Access Key** (no la API key de ingesta). * Confirma que la API key se incluya como token `Bearer` en el encabezado `Authorization`. @@ -161,7 +296,7 @@ Usa la herramienta de listado de equipos de tu cliente MCP para ver a qué equip - El servidor MCP impone un límite de **600 solicitudes por minuto** por usuario. Si superas este límite, las solicitudes se rechazarán temporalmente. Reduce la frecuencia de las solicitudes o espera antes de reintentar. + El servidor MCP impone un límite de **600 solicitudes por minuto** por usuario. Si superas este límite, las solicitudes se rechazan temporalmente. Reduce la frecuencia de las solicitudes o espera antes de reintentar. diff --git a/es/clickstack/navigation.json b/es/clickstack/navigation.json index d6439cfc8..22be85464 100644 --- a/es/clickstack/navigation.json +++ b/es/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "es/_specs/hyperdx-openapi.json", "root": "es/clickstack/api-reference" } ] diff --git a/es/concepts/features/operations/update/replacing-merge-tree.mdx b/es/concepts/features/operations/update/replacing-merge-tree.mdx index 9684fa8de..1e2ad81e9 100644 --- a/es/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/es/concepts/features/operations/update/replacing-merge-tree.mdx @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --seleccionar 100 filas aleatorias +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --seleccionar 100 filas aleatorias +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -El resultado de las operaciones anteriores será de 16.000 filas, es decir, 10.000 + 5000 + 1000. Sin embargo, el total correcto aquí es que, en realidad, deberíamos tener solo 1000 filas menos que nuestro total original, es decir, 10.000 - 1000 = 9000. +El resultado de las operaciones anteriores será de 16.000 filas, es decir, 10.000 + 5000 + 1000. En realidad, deberíamos tener solo 1000 filas menos que nuestro total original, es decir, 10.000 - 1000 = 9000. ```sql SELECT count() @@ -210,7 +210,7 @@ FROM posts_updateable 1 row in set. Elapsed: 0.002 sec. ``` -Aquí, los resultados variarán en función de las fusiones que se hayan realizado. Podemos ver que el total es distinto porque tenemos filas duplicadas. Aplicar `FINAL` a la tabla devuelve el resultado correcto. +Los resultados variarán en función de las fusiones que se hayan realizado. Podemos ver que el total difiere debido a las filas duplicadas. Aplicar `FINAL` a la tabla devuelve el resultado correcto. ```sql SELECT count() @@ -359,11 +359,11 @@ Como se explica en Aprovechamiento de particiones con ReplacingMergeTree, recome ### Ajuste de las fusiones para mejorar el rendimiento de las consultas
-De forma predeterminada, min_age_to_force_merge_seconds y min_age_to_force_merge_on_partition_only se establecen en 0 y false, respectivamente, lo que desactiva estas funciones. Con esta configuración, ClickHouse aplicará el comportamiento de fusión estándar sin forzar fusiones en función de la antigüedad de la partición. +De forma predeterminada, `min_age_to_force_merge_seconds` y `min_age_to_force_merge_on_partition_only` se establecen en 0 y false, respectivamente, lo que desactiva estas funciones. Con esta configuración, ClickHouse aplicará el comportamiento de fusión estándar sin forzar fusiones en función de la antigüedad de la partición. -Si se especifica un valor para min_age_to_force_merge_seconds, ClickHouse ignorará las heurísticas de fusión habituales para las partes con una antigüedad superior al período especificado. Aunque, en general, esto solo resulta eficaz si el objetivo es minimizar el número total de partes, puede mejorar el rendimiento de las consultas en ReplacingMergeTree al reducir la cantidad de partes que deben fusionarse en tiempo de consulta. +Si se especifica un valor para `min_age_to_force_merge_seconds`, ClickHouse ignorará las heurísticas de fusión habituales para las partes con una antigüedad superior al período especificado. Aunque, en general, esto solo resulta eficaz si el objetivo es minimizar el número total de partes, puede mejorar el rendimiento de las consultas en ReplacingMergeTree al reducir la cantidad de partes que deben fusionarse en tiempo de consulta. -Este comportamiento puede ajustarse aún más estableciendo min_age_to_force_merge_on_partition_only=true, lo que exige que todas las partes de la partición sean más antiguas que min_age_to_force_merge_seconds para aplicar una fusión agresiva. Esta configuración permite que, con el tiempo, las particiones más antiguas se fusionen hasta quedar en una sola parte, lo que consolida los datos y mantiene el rendimiento de las consultas. +Este comportamiento puede ajustarse aún más estableciendo `min_age_to_force_merge_on_partition_only=true`, lo que exige que todas las partes de la partición sean más antiguas que `min_age_to_force_merge_seconds` para aplicar una fusión agresiva. Esta configuración permite que, con el tiempo, las particiones más antiguas se fusionen hasta quedar en una sola parte, lo que consolida los datos y mantiene el rendimiento de las consultas. * Los parámetros de la instantánea no se pueden editar después de crear el ClickPipe. Si quiere cambiarlos, tendrá que crear uno nuevo. -* Al añadir tablas a un ClickPipe existente, no puede cambiar los parámetros de la instantánea. El ClickPipe usará los parámetros existentes para las nuevas tablas. -* La columna de la clave de partición no debe contener valores `NULL`, ya que la lógica de particionamiento los omite. \ No newline at end of file +* Al añadir tablas a un ClickPipe existente, no puede cambiar los parámetros de la instantánea. El ClickPipe usará los parámetros existentes para las nuevas tablas. \ No newline at end of file diff --git a/es/integrations/language-clients/go/config-reference.mdx b/es/integrations/language-clients/go/config-reference.mdx index c21e6862e..05225b04f 100644 --- a/es/integrations/language-clients/go/config-reference.mdx +++ b/es/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### Tiempos de espera
-| Opción | Tipo | Predeterminado | Parámetro DSN | Descripción | Práctica recomendada | Si está mal configurado | -| ------------- | --------------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Tiempo máximo para establecer una conexión nueva. También controla el tiempo de espera para obtener una conexión del pool cuando se alcanza `MaxOpenConns`. | 5-10s en LAN, 15-30s en WAN/nube. Nunca por debajo de 1s. | Demasiado corto: `"clickhouse: acquire conn timeout"` durante la congestión. Demasiado largo (> 60s): la aplicación queda bloqueada durante caídas del servicio. | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Tiempo máximo de espera por una respuesta del servidor en cada llamada de lectura. Se aplica por bloque, no a toda la consulta. El límite de tiempo del contexto tiene prioridad. | 10-30s para consultas interactivas cortas; 5-30m para consultas analíticas largas. | Demasiado corto: `"i/o timeout"` o `"read: connection reset by peer"` a mitad de la consulta; el servidor sigue ejecutándola. Demasiado largo: no se detectan conexiones muertas. | +| Opción | Tipo | Predeterminado | Parámetro DSN | Descripción | Práctica recomendada | Si está mal configurado | +| ------------- | --------------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Tiempo máximo para establecer una conexión nueva. También controla el tiempo de espera para obtener una conexión del pool cuando se alcanza `MaxOpenConns`. | 5-10s en LAN, 15-30s en WAN/nube, 1-2m si se conecta a un servicio inactivo de ClickHouse Cloud. Nunca por debajo de 1s. | Demasiado corto: `"clickhouse: acquire conn timeout"` durante la congestión, o fallo de conexión antes de que un servicio de Cloud inactivo termine de activarse. Demasiado largo (> 60s): la aplicación queda bloqueada durante caídas del servicio. | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Tiempo máximo de espera por una respuesta del servidor en cada llamada de lectura. Se aplica por bloque, no a toda la consulta. El límite de tiempo del contexto tiene prioridad. | 10-30s para consultas interactivas cortas; 5-30m para consultas analíticas largas. | Demasiado corto: `"i/o timeout"` o `"read: connection reset by peer"` a mitad de la consulta; el servidor sigue ejecutándola. Demasiado largo: no se detectan conexiones muertas. | + + + Un servicio de ClickHouse Cloud que ha estado inactivo entra en pausa y se reactiva con la primera conexión entrante. La reactivación suele tardar unas pocas decenas de segundos, durante las cuales la conexión queda bloqueada. Si `DialTimeout` es menor que el tiempo de reactivación, la primera consulta después de un período de inactividad falla con un timeout de conexión en lugar de ejecutarse. + + Configure `DialTimeout` en `1m`–`2m` para los clients que puedan ser los primeros en llegar a un servicio inactivo. La contrapartida es una detección de fallos más lenta durante una caída real: los intentos de conexión quedan bloqueados durante todo el tiempo de espera antes de devolver un error, así que prefiera limitar el tiempo de espera más alto a la primera conexión, o use límites de tiempo del contexto en consultas individuales para acotar la latencia de extremo a extremo. + *** diff --git a/es/integrations/language-clients/go/configuration.mdx b/es/integrations/language-clients/go/configuration.mdx index d92247424..11eb00851 100644 --- a/es/integrations/language-clients/go/configuration.mdx +++ b/es/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: 'reference' Al abrir una conexión, se puede usar una estructura `Options` para controlar el comportamiento del cliente. Están disponibles los siguientes ajustes: -| Parámetro | Tipo | Predeterminado | Descripción | -| ---------------------- | -------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Protocol` | `Protocol` | `Native` | Protocolo de transporte: `Native` (TCP) o `HTTP`. Consulta [TCP vs HTTP](#tcp-vs-http). | -| `Addr` | `[]string` | — | Slice de direcciones `host:port`. Para varios nodos, consulta [conexión a varios nodos](#connecting-to-multiple-nodes). | -| `Auth` | `Auth` | — | Credenciales de autenticación (`Database`, `Username`, `Password`). Consulta [Autenticación](#authentication). | -| `TLS` | `*tls.Config` | `nil` | Configuración de TLS. Un valor distinto de `nil` habilita TLS. Consulta [TLS](#using-tls). | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Función personalizada para controlar cómo se establecen las conexiones TCP. | -| `DialTimeout` | `time.Duration` | `30s` | Tiempo máximo de espera al abrir una conexión nueva. | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Número máximo de conexiones abiertas en un momento dado. | -| `MaxIdleConns` | `int` | `5` | Número de conexiones inactivas que se mantienen en el grupo. | -| `ConnMaxLifetime` | `time.Duration` | `1h` | Tiempo de vida máximo de una conexión del grupo. Consulta [pool de conexiones](#connection-pooling). | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Estrategia para elegir un nodo de `Addr`. Consulta [conexión a varios nodos](#connecting-to-multiple-nodes). | -| `BlockBufferSize` | `uint8` | `2` | Número de bloques que se decodifican en paralelo. Los valores más altos aumentan el rendimiento a costa de más memoria. Se puede sobrescribir por consulta mediante el contexto. | -| `Settings` | `Settings` | — | Mapa de ajuste de ClickHouse aplicados a cada consulta. Las consultas individuales pueden sobrescribirlos mediante [context](/es/integrations/language-clients/go/clickhouse-api#using-context). | -| `Compression` | `*Compression` | `nil` | Compresión a nivel de bloque. Consulta [compresión](#compression). | -| `ReadTimeout` | `time.Duration` | — | Tiempo máximo de espera para una lectura del servidor en una sola llamada. | -| `FreeBufOnConnRelease` | `bool` | `false` | Si es `true`, libera el búfer de memoria de la conexión de vuelta al grupo en cada consulta. Reduce el uso de memoria con un pequeño coste de CPU. | -| `Logger` | `*slog.Logger` | `nil` | Logger estructurado (Go `log/slog`). Consulta [registro](#logging). | -| `Debug` | `bool` | `false` | **Obsoleto.** Usa `Logger` en su lugar. Habilita la salida de depuración heredada a stdout. | -| `Debugf` | `func(string, ...any)` | — | **Obsoleto.** Usa `Logger` en su lugar. Función personalizada de registro de depuración. Requiere `Debug: true`. | -| `GetJWT` | `GetJWTFunc` | — | Callback que devuelve un token JWT para la autenticación de ClickHouse Cloud (solo HTTPS). | -| `HttpHeaders` | `map[string]string` | — | Headers HTTP adicionales enviados en cada solicitud (solo transporte HTTP). | -| `HttpUrlPath` | `string` | — | Ruta URL adicional añadida a las solicitudes HTTP (solo transporte HTTP). | -| `HttpMaxConnsPerHost` | `int` | — | Sobrescribe `MaxConnsPerHost` en el `http.Transport` subyacente (solo transporte HTTP). | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Fábrica personalizada de transporte HTTP. El transporte predeterminado se pasa para aplicar sobrescrituras selectivas (solo transporte HTTP). | -| `HTTPProxyURL` | `*url.URL` | — | URL del proxy HTTP para todas las solicitudes (solo transporte HTTP). | +| Parámetro | Tipo | Predeterminado | Descripción | +| ---------------------- | -------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Protocol` | `Protocol` | `Native` | Protocolo de transporte: `Native` (TCP) o `HTTP`. Consulta [TCP vs HTTP](#tcp-vs-http). | +| `Addr` | `[]string` | — | Slice de direcciones `host:port`. Para varios nodos, consulta [conexión a varios nodos](#connecting-to-multiple-nodes). | +| `Auth` | `Auth` | — | Credenciales de autenticación (`Database`, `Username`, `Password`). Consulta [Autenticación](#authentication). | +| `TLS` | `*tls.Config` | `nil` | Configuración de TLS. Un valor distinto de `nil` habilita TLS. Consulta [TLS](#using-tls). | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Función personalizada para controlar cómo se establecen las conexiones TCP. | +| `DialTimeout` | `time.Duration` | `30s` | Tiempo máximo de espera al abrir una conexión nueva. Auméntalo a `1m`–`2m` al conectarte a un servicio de ClickHouse Cloud que pueda estar inactivo; consulta [Timeouts](/es/integrations/language-clients/go/config-reference#timeouts). | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Número máximo de conexiones abiertas en un momento dado. | +| `MaxIdleConns` | `int` | `5` | Número de conexiones inactivas que se mantienen en el grupo. | +| `ConnMaxLifetime` | `time.Duration` | `1h` | Tiempo de vida máximo de una conexión del grupo. Consulta [pool de conexiones](#connection-pooling). | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Estrategia para elegir un nodo de `Addr`. Consulta [conexión a varios nodos](#connecting-to-multiple-nodes). | +| `BlockBufferSize` | `uint8` | `2` | Número de bloques que se decodifican en paralelo. Los valores más altos aumentan el rendimiento a costa de más memoria. Se puede sobrescribir por consulta mediante el contexto. | +| `Settings` | `Settings` | — | Mapa de ajuste de ClickHouse aplicados a cada consulta. Las consultas individuales pueden sobrescribirlos mediante [context](/es/integrations/language-clients/go/clickhouse-api#using-context). | +| `Compression` | `*Compression` | `nil` | Compresión a nivel de bloque. Consulta [compresión](#compression). | +| `ReadTimeout` | `time.Duration` | — | Tiempo máximo de espera para una lectura del servidor en una sola llamada. | +| `FreeBufOnConnRelease` | `bool` | `false` | Si es `true`, libera el búfer de memoria de la conexión de vuelta al grupo en cada consulta. Reduce el uso de memoria con un pequeño coste de CPU. | +| `Logger` | `*slog.Logger` | `nil` | Logger estructurado (Go `log/slog`). Consulta [registro](#logging). | +| `Debug` | `bool` | `false` | **Obsoleto.** Usa `Logger` en su lugar. Habilita la salida de depuración heredada a stdout. | +| `Debugf` | `func(string, ...any)` | — | **Obsoleto.** Usa `Logger` en su lugar. Función personalizada de registro de depuración. Requiere `Debug: true`. | +| `GetJWT` | `GetJWTFunc` | — | Callback que devuelve un token JWT para la autenticación de ClickHouse Cloud (solo HTTPS). | +| `HttpHeaders` | `map[string]string` | — | Headers HTTP adicionales enviados en cada solicitud (solo transporte HTTP). | +| `HttpUrlPath` | `string` | — | Ruta URL adicional añadida a las solicitudes HTTP (solo transporte HTTP). | +| `HttpMaxConnsPerHost` | `int` | — | Sobrescribe `MaxConnsPerHost` en el `http.Transport` subyacente (solo transporte HTTP). | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Fábrica personalizada de transporte HTTP. El transporte predeterminado se pasa para aplicar sobrescrituras selectivas (solo transporte HTTP). | +| `HTTPProxyURL` | `*url.URL` | — | URL del proxy HTTP para todas las solicitudes (solo transporte HTTP). | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/es/products/cloud/guides/index.mdx b/es/products/cloud/guides/index.mdx index 0ee4e2925..018ab08cd 100644 --- a/es/products/cloud/guides/index.mdx +++ b/es/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['guías de ClickHouse Cloud', 'documentación', 'guías prácticas', | [Administrar mi cuenta](/es/products/cloud/guides/security/cloud-access-management/manage-my-account) | Esta página describe cómo aceptar invitaciones, gestionar la configuración de MFA y restablecer contraseñas | | [Administrar asignaciones de roles de la consola SQL](/es/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | Guía sobre cómo administrar las asignaciones de roles de la consola SQL | | [Administrar límites y cuotas de servicio de AWS](/es/products/bring-your-own-cloud/reference/aws-service-limits) | Cuotas de servicio de AWS que debe verificar antes del onboarding de BYOC, cómo solicitar aumentos y qué supervisar a medida que escalan los servicios | -| [Migración de CMEK v1 a v2](/es/products/cloud/guides/security/cmek-migration) | Instrucciones de migración para pasar de CMEK heredado a la versión 2 | | [Multi tenancy](/es/products/cloud/guides/best-practices/multitenancy) | Prácticas recomendadas para implementar multi tenancy | | [Optimización de las conversaciones del agente de ClickHouse Assistant con una capa semántica](/es/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | Guía para usar AGENTS.md con el fin de proporcionar lógica de negocio personalizada e instrucciones específicas de los datos al agente de chat de ClickHouse Assistant | | [Descripción general](/es/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | Implemente ClickHouse en su propia infraestructura de Cloud | diff --git a/es/products/cloud/guides/security/cmek-migration.mdx b/es/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index 8f9fbf39d..000000000 --- a/es/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: 'Migración heredada de CMEK' -slug: /cloud/security/cmek-migration -title: 'Migración de CMEK v1 a v2' -description: 'Instrucciones de migración para pasar de CMEK heredado a la versión 2' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', 'cifrado', 'CMEK'] ---- - -Estamos mejorando la seguridad de los servicios con claves de cifrado gestionadas por el cliente (CMEK). Ahora, todos los servicios están configurados con un AWS Role único por servicio para autorizar el uso de claves del cliente para cifrar y descifrar los servicios. Este nuevo rol solo se muestra en la pantalla de configuración del servicio. - -Este nuevo proceso es compatible tanto con OpenAPI como con Terraform. Para obtener más información, consulta nuestra documentación ([Cifrado mejorado](/es/products/cloud/guides/security/cmek), [Cloud API](/es/products/cloud/features/admin-features/api/api-overview), [Proveedor oficial de Terraform](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)). - - - Los clientes que utilizan CMEK v1 deben migrar sus servicios no más tarde del 1 de junio de 2026. Después de esa fecha, las claves gestionadas por el cliente se rotarán de forma predeterminada a claves gestionadas por ClickHouse. Los clientes podrán volver a rotarlas para usar claves gestionadas por el cliente después de la migración predeterminada. - - -
- ## Migración manual -
- -Completa los siguientes pasos para migrar al nuevo proceso: - -1. Inicia sesión en https://console.clickhouse.cloud -2. Haz clic en el servicio cifrado -3. Haz clic en Service Settings, a la izquierda -4. Desplázate hasta la parte inferior de la pantalla y expande View service details -5. Copia el ID del rol de cifrado (IAM) -6. Ve a tu clave de KMS en AWS y actualiza la Key Policy para agregar lo siguiente: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. En ClickHouse Cloud, abre un caso de soporte para avisarnos de que podemos habilitar el nuevo método. Este cambio requiere reiniciar el servicio; indícanos si hay algún día u hora que sea mejor para hacerlo. -8. Una vez que reiniciemos el servicio, ve a tu clave de KMS en AWS y elimina lo siguiente de la Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. ¡La actualización se ha completado! - -
- ## Migración de Terraform -
- -1. Actualiza a [la versión 3.5.0 o superior de Terraform](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) -2. Aplica Terraform sin cambios. Aparecerá un nuevo campo para transparent_data_encryption en el estado de Terraform. Toma nota del role_id. -3. Ve a tu clave de KMS en AWS y actualiza la Key Policy para añadir lo siguiente: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. En ClickHouse Cloud, abre un caso de soporte con el service name para informarnos de que podemos habilitar el nuevo método. Este cambio requiere reiniciar el servicio; indícanos si hay algún día/hora que sea mejor para reiniciar el servicio. -5. Después de que reiniciemos el servicio, puedes actualizar la configuración transparent_data_encryption.enabled a ‘True’, eliminar la configuración de tier en Terraform y aplicar los cambios. Esto no dará lugar a ningún cambio. -6. Ve a tu clave de KMS en AWS y elimina lo siguiente de la Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. ¡La actualización se ha completado! \ No newline at end of file diff --git a/es/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/es/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index 77cd3c7a4..f62cba1ac 100644 --- a/es/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/es/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ Para restringir el acceso a sus servicios de ClickHouse Cloud exclusivamente a t * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 diff --git a/es/products/cloud/navigation.json b/es/products/cloud/navigation.json index e1c4c0c98..603955f98 100644 --- a/es/products/cloud/navigation.json +++ b/es/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "es/products/cloud/guides/security/data-masking", - "es/products/cloud/guides/security/cmek", - "es/products/cloud/guides/security/cmek-migration" + "es/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "es/_specs/cloud-openapi.json" } ] }, diff --git a/es/products/kubernetes-operator/guides/configuration.mdx b/es/products/kubernetes-operator/guides/configuration.mdx index fdaf6edce..56a272c5c 100644 --- a/es/products/kubernetes-operator/guides/configuration.mdx +++ b/es/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: Configure la CPU y la memoria de los contenedores de ClickHouse: ```yaml -# valores predeterminados +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -321,6 +321,10 @@ spec: ## Configuración de TLS/SSL
+Para ver un ejemplo completo —emisión de certificados con cert-manager, conexión de +clientes a través de puertos seguros y cifrado del tráfico de Keeper—, consulta la +guía [Protección con TLS](/es/products/kubernetes-operator/guides/tls). +
### Configurar endpoints seguros
@@ -371,6 +375,323 @@ spec: key: ``` +
+ ## Secret externo +
+ +De forma predeterminada, el operador crea y controla un Secret que contiene las credenciales internas del clúster (contraseña entre servidores, contraseña de administración, identidad de Keeper, secreto del clúster y clave de colecciones con nombre). El Secret toma el nombre del clúster y reside en el espacio de nombres del clúster. + +Si quiere gestionar estas credenciales usted mismo —por ejemplo, obteniéndolas de HashiCorp Vault, AWS Secrets Manager o [External Secrets Operator](https://external-secrets.io/)—, haga que el operador apunte a un Secret ya existente mediante `spec.externalSecret`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + El Secret referenciado debe estar en el **mismo espacio de nombres** que el ClickHouseCluster. El operador nunca elimina un Secret que no haya creado. + + +
+ ### Claves requeridas +
+ +El Secret debe contener las siguientes claves: + +| Clave | Formato | Cuándo es obligatoria | +| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------- | +| `interserver-password` | contraseña en texto plano | Siempre | +| `management-password` | contraseña en texto plano | Siempre | +| `keeper-identity` | `clickhouse:` | Siempre | +| `cluster-secret` | contraseña en texto plano | Siempre | +| `named-collections-key` | clave AES de 16 bytes codificada en hexadecimal (32 caracteres hexadecimales) | Solo en ClickHouse `>= 25.12` | + +Un Secret completo tiene este aspecto: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### Política: Observe vs Manage +
+ +`spec.externalSecret.policy` controla cómo el operador maneja las claves obligatorias que faltan: + +| Política | Comportamiento cuando faltan claves | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Observe` (predeterminada) | La reconciliación queda **bloqueada** hasta que estén presentes todas las claves obligatorias. El operador informa de cada clave que falta —y de la indicación de formato correspondiente— mediante la condición `ExternalSecretValid` (con el motivo `ExternalSecretInvalid`) y un evento `Warning`. | +| `Manage` | El operador **genera** cualquier clave obligatoria que falte y la vuelve a escribir en el mismo Secret. Resulta útil para el aprovisionamiento inicial: crea un Secret vacío, deja que el operador lo complete y, después, opcionalmente, restringe el acceso. Aun así, el operador nunca elimina el Secret. | + + + Incluso con `policy: Manage`, el Secret ya debe existir en el espacio de nombres: el operador nunca crea el Secret por sí mismo; solo escribe las claves generadas en uno ya existente. Si el Secret referenciado no existe, la reconciliación se bloquea con el motivo `ExternalSecretNotFound`, independientemente de la política. + + +Elige `Observe` cuando un sistema externo (Vault, ESO, sealed-secrets, GitOps) sea la fuente de referencia y quieras que el operador falle claramente ante una configuración incorrecta. Elige `Manage` cuando quieras un aprovisionamiento inicial autosuficiente, pero también conservar la propiedad del propio objeto Secret (por ejemplo, para hacer una copia de seguridad). + +
+ ### Condición de estado y solución de problemas +
+ +El operador expone una condición `ExternalSecretValid` en `ClickHouseCluster.status.conditions`. Revísala cuando parezca que la reconciliación está atascada: + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +Posibles razones: + +| `reason` | Significado | Solución | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| `ExternalSecretNotFound` | El Secret referenciado no existe en el espacio de nombres. | Crea el Secret o corrige `spec.externalSecret.name`. | +| `ExternalSecretInvalid` | El Secret existe, pero no tiene las claves requeridas (solo con `Observe`). El mensaje enumera cada clave faltante junto con su formato esperado. | Agrega las claves faltantes o cambia a `policy: Manage`. | +| `ExternalSecretValid` | Todas las claves requeridas están presentes y el operador está usando el Secret. | — | + +El operador vuelve a encolar la reconciliación mientras el Secret no sea válido, así que, en cuanto agregues las claves faltantes, la siguiente reconciliación las detectará automáticamente; no hace falta reiniciar los pods. + + + El conjunto de claves requeridas depende de la versión de ClickHouse en ejecución. `named-collections-key` solo se valida una vez que la sonda de versión del operador ha detectado ClickHouse `25.12` o una versión posterior. En versiones anteriores, la clave puede no estar presente en el Secret. + + +
+ ## Puertos adicionales +
+ +El operador expone un conjunto fijo de puertos en cada pod de Kubernetes de ClickHouse y en su Service headless: `8123` para HTTP, `9000` nativo, `9009` entre servidores, `9001` de administración, `9363` para métricas de Prometheus, y las variantes TLS `8443`/`9440` cuando TLS está habilitado. Para que ClickHouse escuche en protocolos adicionales —MySQL, PostgreSQL, gRPC o cualquier puerto personalizado—, declárelos en `spec.additionalPorts`: + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +El operador añade esos puertos a `containerPorts` del pod de Kubernetes y al Service headless. El ejemplo completo se encuentra en [`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml). + + + `additionalPorts` solo abre los puertos del lado de Kubernetes. **No** configura el ClickHouse server para que escuche en ellos. También tienes que habilitar el protocolo correspondiente en `spec.settings.extraConfig.protocols`. De lo contrario, el puerto está abierto en el Service, pero nada dentro del pod de Kubernetes responde. + + +
+ ### Ejemplo completo: MySQL wire protocol +
+ +Para exponer ClickHouse mediante el MySQL wire protocol en el puerto `9004`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +Una vez aplicado, verifique desde dentro del clúster: + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### Restricciones de los campos +
+ +| Campo | Regla | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Debe coincidir con el patrón DNS_LABEL `^[a-z]([-a-z0-9]*[a-z0-9])?$`, con un máximo de 63 caracteres. El CRD aplica la unicidad como clave list-map. | +| `port` | Entero en `[1, 65535]`. El webhook rechaza números de puerto duplicados en la lista. | + +
+ ### Puertos y nombres reservados +
+ +El webhook de validación rechaza las entradas de `additionalPorts` que entrarían en conflicto con los puertos en los que el propio operador escucha. Todos los puertos relacionados con TLS están reservados **incondicionalmente** para que habilitar `spec.settings.tls.enabled` más adelante no invalide un clúster que antes era válido. + +| Port | Reservado para | +| ------ | ---------------------- | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | native TCP | +| `9440` | TLS nativo | +| `9009` | interserver | +| `9001` | management | +| `9363` | métricas de Prometheus | + +Los siguientes nombres también se rechazan: son los identificadores internos del operador para tipos de protocolo (no los alias legibles para humanos): + +| Name | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +Una solicitud rechazada produce un error como: + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## Sonda de versión y canal de actualización +
+ +El operador realiza dos tareas independientes con las versiones del clúster: + +1. **Sonda de versión** — un `Job` de Kubernetes que ejecuta la imagen de contenedor una vez para detectar la versión en ejecución de ClickHouse / Keeper. La versión detectada se registra en `.status.version` y se utiliza en otros pasos de reconciliación (por ejemplo, la clave de named collections de `External Secret` solo es necesaria a partir de ClickHouse `25.12`). +2. **Canal de actualización** — una comprobación periódica del feed público de versiones de ClickHouse (`https://clickhouse.com/data/version_date.tsv`). El operador informa si hay una versión más reciente disponible mediante la condición de estado `VersionUpgraded`. Nunca actualiza el clúster por sí solo; el usuario controla la etiqueta de la imagen. + +
+ ### Elegir un canal de lanzamientos +
+ +`spec.upgradeChannel` selecciona con qué conjunto de lanzamientos upstream compara el operador. El mismo campo existe tanto en `ClickHouseCluster` como en `KeeperCluster`. + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +Valores permitidos (validados por la CRD con el patrón `^(lts|stable|\d+\.\d+)?$`): + +| Valor | Comportamiento | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *vacío* (predeterminado) | El operador propone solo actualizaciones **menores** dentro de la línea major.minor que se está ejecutando actualmente. A un cluster en `25.8.3.1` se le notificará sobre `25.8.4.x`, pero no sobre `25.9.x`. | +| `stable` | Sigue el canal `stable` de upstream: la última versión que ClickHouse Inc. marca como estable en la línea principal de releases. Recibe actualizaciones mayores antes que el canal `lts`. | +| `lts` | Sigue el canal `lts` de upstream: releases con soporte a largo plazo. Recibe actualizaciones mayores con menos frecuencia y con ventanas de soporte más largas. | +| `25.8` (o cualquier `.`) | Fija el canal en una línea major.minor específica. No se proponen actualizaciones mayores más allá de esa línea, aunque exista una versión más reciente en upstream. | + +Para production, en general se prefiere fijar el canal a un `.` explícito (por ejemplo, `25.8`). Esto fija el cluster en la línea de release mayor prevista y permite que el operador muestre una advertencia `WrongReleaseChannel` si alguna réplica se desvía de algún modo a una major distinta, algo especialmente importante cuando la image se referencia mediante un digest (`@sha256:...`) en lugar de un tag legible para humanos. El valor predeterminado vacío es adecuado para clusters de Development en los que los saltos entre versiones major no son una preocupación. + +
+ ### Condiciones de estado +
+ +Dos condiciones reflejan el resultado de la sonda y de la comprobación de actualización: + +| Condición | Motivo | Significado | +| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionInSync` | `VersionMatch` | Todas las réplicas informan la misma versión que la imagen | +| `VersionInSync` | `VersionMismatch` | Las réplicas están ejecutando versiones distintas. El evento de advertencia se suprime durante una actualización gradual planificada. Suele aparecer cuando se ha fijado una etiqueta de imagen mutable (por ejemplo, `latest` o una versión major sin más, como `26.3`) y el registry subyacente ha cambiado entre una descarga y otra, por lo que distintas réplicas acabaron con parches diferentes de la misma etiqueta. | +| `VersionInSync` | `VersionPending` | El Job de la sonda de versión aún no ha terminado | +| `VersionInSync` | `VersionProbeFailed` | El Job de la sonda falló; el operador no puede determinar la versión en ejecución | +| `VersionUpgraded` | `UpToDate` | El cluster está en la versión más reciente disponible en el canal seleccionado | +| `VersionUpgraded` | `MinorUpdateAvailable` | Hay un parche más reciente disponible en la misma línea `major.minor` | +| `VersionUpgraded` | `MajorUpdateAvailable` | Hay una versión `major.minor` más reciente disponible dentro del canal elegido | +| `VersionUpgraded` | `VersionOutdated` | La versión en ejecución está desactualizada y ya no recibirá correcciones del canal seleccionado; normalmente porque la línea major se ha retirado de `lts` o `stable` upstream | +| `VersionUpgraded` | `WrongReleaseChannel` | La imagen en ejecución no pertenece al `upgradeChannel` seleccionado. Ejemplo: un cluster que ejecuta `26.5` con `upgradeChannel: lts`, ya que `26.5` no forma parte de la línea `lts` upstream. | +| `VersionUpgraded` | `UpgradeCheckFailed` | El operador no pudo acceder al feed de versiones upstream | + +Inspecciónalas con: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### Sobrescritura del Job de la sonda de versión +
+ +La sonda se implementa como un `Job` estándar de Kubernetes. Si su clúster tiene políticas de admisión que exigen Tolerations específicas, selectores de nodo o contextos de seguridad, o si desea limitar cuánto tiempo permanecen los Jobs de sonda completados, sobrescriba la plantilla mediante `spec.versionProbeTemplate`: + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +El nombre del contenedor `version-probe` es el predeterminado del operador: la entrada en `containers:` coincide con él por nombre, por lo que el operador aplica una fusión profunda de los campos proporcionados por el usuario sobre los valores predeterminados. + +
+ ### Controles globales del operador +
+ +Dos opciones del administrador del operador controlan globalmente el bucle de comprobación de actualizaciones: + +| Opción | Predeterminado | Efecto | +| --------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | Frecuencia con la que el operador vuelve a obtener la lista de versiones del origen | +| `--disable-version-update-checks` | `false` | Desactiva por completo la comprobación de actualizaciones. No se establece la condición `VersionUpgraded` y no se genera tráfico HTTP saliente a `clickhouse.com` | + +Establece `--disable-version-update-checks=true` en entornos aislados de la red o cuando no se permite la salida a `clickhouse.com`. +
## Configuración de ClickHouse
@@ -485,6 +806,49 @@ spec: Cuando está activado, el operador sincroniza las tablas Replicated y de integración en las nuevas réplicas. +
+ ### Registro del servidor +
+ +Configure el registro del servidor de ClickHouse mediante `spec.settings.logger`. Todos los campos son opcionales y tienen valores predeterminados seguros, por lo que incluso un clúster que no modifique registrará en `trace` tanto en la consola del contenedor como en un archivo rotado en disco. + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| Campo | Predeterminado | Descripción | +| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `logToFile` | `true` | Cuando es `false`, el operador elimina los destinos de archivo y el servidor solo escribe logs en la consola del contenedor. | +| `jsonLogs` | `false` | Cuando es `true`, el operador añade `formatting.type: json` para que cada línea sea un objeto JSON. | +| `level` | `trace` | Nivel de detalle de los logs. Uno de `test`, `trace`, `debug`, `information`, `notice`, `warning`, `error`, `critical`, `fatal`. | +| `size` | `1000M` | Tamaño máximo de un solo archivo de log antes de la rotación. | +| `count` | `50` | Número de archivos de log rotados que conserva el servidor. | + +El operador siempre mantiene activado el registro en consola para que `kubectl logs` funcione, y añade el registro en archivo cuando `logToFile` es `true`. Un clúster con los valores predeterminados genera este bloque `logger`: + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +El mismo bloque `spec.settings.logger` se aplica a un `KeeperCluster`; en ese caso, el operador escribe sus archivos en `/var/log/clickhouse-keeper/`. + + + El registro en consola permanece activado independientemente de `logToFile`, por lo que `kubectl logs` sigue funcionando incluso cuando desactivas el registro en archivos. Establece `jsonLogs: true` cuando envíes logs a un almacén de logs estructurados que procesa JSON. + +
## Configuración personalizada
diff --git a/es/products/kubernetes-operator/guides/introduction.mdx b/es/products/kubernetes-operator/guides/introduction.mdx index 80d34dd9a..4aecca913 100644 --- a/es/products/kubernetes-operator/guides/introduction.mdx +++ b/es/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: Para eliminar por completo el almacenamiento: ```bash -# Eliminar el clúster +# Delete cluster kubectl delete clickhousecluster my-cluster -# Esperar a que los pods terminen -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# Eliminar los PVCs -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/es/products/kubernetes-operator/guides/monitoring.mdx b/es/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..ba840843f --- /dev/null +++ b/es/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,420 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: Supervisión del ClickHouse Operator +keywords: ['kubernetes', 'prometheus', 'supervisión', 'métricas'] +description: 'Cómo recopilar, proteger y usar las métricas del operador y los endpoints de estado.' +doc_type: 'guide' +--- + +El operador expone métricas compatibles con Prometheus y sondas de estado de Kubernetes para que pueda observar su actividad de reconciliación, detectar controladores atascados y generar alertas ante fallos. + +Esta guía explica qué expone el operador, cómo recopilarlo y qué consultas resultan útiles en el día a día. + + + Esta guía trata sobre el **propio proceso del operador** (el controller manager). Para las métricas del ClickHouse server (consultas, partes, retraso de replicación), use el [endpoint de Prometheus en ClickHouse](/es/reference/settings/server-settings/settings#prometheus) para recopilarlo por separado. + + +
+ ## Endpoints +
+ +El proceso del operador expone dos endpoints HTTP dentro del pod de Kubernetes del manager: + +| Endpoint | Puerto predeterminado | Path | Propósito | +| --------------- | -------------------------------------------------------------------- | --------------------- | ---------------------------------------------------- | +| Métricas | `8080` (Helm) / `0` deshabilitado (valor predeterminado del binario) | `/metrics` | Formato de exposición de Prometheus | +| Sonda de estado | `8081` | `/healthz`, `/readyz` | Comprobaciones de liveness y readiness de Kubernetes | + +El endpoint de métricas está **desactivado de forma predeterminada** cuando se ejecuta directamente el binario del operador (`--metrics-bind-address=0`). El gráfico de Helm lo habilita con `metrics.enable: true` y `metrics.port: 8080`. + +El endpoint de la sonda de estado siempre está habilitado; la plantilla de implementación conecta `/healthz` y `/readyz` a las sondas de liveness y readiness del pod de Kubernetes en el puerto `8081`. + +
+ ## Indicadores del binario del operador +
+ +Los indicadores relevantes de `manager` (definidos en [`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go)): + +| Indicador | Predeterminado | Descripción | +| ----------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--metrics-bind-address` | `0` (deshabilitado) | Dirección de enlace del endpoint de métricas. Establézcala en `:8443` para HTTPS o `:8080` para HTTP. Déjela en `0` para deshabilitar el servidor de métricas. | +| `--metrics-secure` | `true` | Sirve las métricas a través de HTTPS con authn/authz. Establézcalo en `false` para HTTP sin cifrar. | +| `--metrics-cert-path` | vacío | Directorio que contiene los archivos de certificado TLS (`tls.crt`, `tls.key`) del servidor de métricas. | +| `--metrics-cert-name` | `tls.crt` | Nombre del archivo de certificado dentro de `--metrics-cert-path`. | +| `--metrics-cert-key` | `tls.key` | Nombre del archivo de clave dentro de `--metrics-cert-path`. | +| `--enable-http2` | `false` | Habilita HTTP/2 para los servidores de métricas **y webhook**. Está desactivado de forma predeterminada para mitigar CVE-2023-44487 / CVE-2023-39325. | +| `--leader-elect` | `false` (binario) / `true` (gráfico de Helm) | Habilita la elección de líder para que solo una réplica ejecute la reconciliación a la vez. El gráfico de Helm establece este indicador en `manager.args` de forma predeterminada. | +| `--health-probe-bind-address` | `:8081` | Dirección de enlace de `/healthz` y `/readyz`. | + + + La convención `8443` (HTTPS) / `8080` (HTTP) en el texto de ayuda del indicador es solo una referencia. El gráfico de Helm sirve HTTPS en `8080` porque establece tanto `metrics.port: 8080` como `metrics.secure: true`. No hay detección de modo basada en el puerto: `--metrics-secure` es lo que selecciona HTTPS o HTTP. + + +
+ ## Habilitar métricas con Helm +
+ +El chart ya crea un `Service` para el puerto de métricas y, opcionalmente, un `ServiceMonitor` para prometheus-operator. + +El endpoint de métricas está habilitado de forma predeterminada (`metrics.enable: true`, puerto `8080`, servido por HTTPS mediante `metrics.secure: true`). La única configuración que normalmente tendrás que cambiar es `prometheus.enable` para que el chart cree un `ServiceMonitor` por ti: + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +Si no usa cert-manager, establezca además `certManager.enable: false` y el ServiceMonitor recopilará las métricas con `insecureSkipVerify: true`, basándose únicamente en la autenticación mediante bearer token. + +El conjunto completo de valores predeterminados relacionados con las métricas es: + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +Aplicar: + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +Después de la instalación, el chart crea: + +* `Service/-metrics-service` — expone el puerto `8080` (HTTPS cuando `metrics.secure: true`). +* `ServiceMonitor/-controller-manager-metrics-monitor` — cuando `prometheus.enable: true`. +* `ClusterRole/-metrics-reader` — URL sin recurso `/metrics` con el verbo `get`. + +
+ ## Protección del endpoint de métricas +
+ +Cuando `metrics.secure: true`, el servidor de métricas exige TLS **y** autenticación/autorización de Kubernetes en cada recopilación. Los scrapers deben: + +1. Presentar un token Bearer de Kubernetes válido. +2. Pertenecer a una ServiceAccount vinculada a un Rol de clúster que conceda `get` sobre la URL sin recursos `/metrics`. + +El chart incluye ese Rol de clúster: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +Vincúlalo a la ServiceAccount que utiliza tu scraper (normalmente, Prometheus): + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + Si ves `401 Unauthorized` o `403 Forbidden` en el endpoint de métricas, el scraper está usando HTTPS, pero no tiene un token Bearer de Kubernetes o no está autorizado para usarlo, o bien su ServiceAccount no tiene la asociación indicada arriba. Deshabilitar la seguridad estableciendo `metrics.secure: false` **no se recomienda** en clústeres compartidos, porque cualquiera con conectividad de red al pod de Kubernetes podría recopilar métricas del endpoint. + + +
+ ## Referencia de ServiceMonitor +
+ +El chart genera un ServiceMonitor con esta estructura cuando `prometheus.enable: true`: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +Si tu instancia de Prometheus no usa cert-manager, establece `tlsConfig.insecureSkipVerify: true` y confía únicamente en la autenticación mediante bearer token; el chart ya lo hace cuando `certManager.enable: false`. + +
+ ## Ejemplo independiente de Prometheus +
+ +Si no utiliza kube-prometheus-stack, el repositorio incluye un ejemplo autocontenido en [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml). Crea una `ServiceAccount`, el RBAC necesario y un CR de `Prometheus` que selecciona el `ServiceMonitor` del operador. + +
+ ## Endpoints de las sondas de estado +
+ +| Path | Lo utiliza | Devuelve | +| ---------- | ---------------------------------- | ------------------------------------------------------------- | +| `/healthz` | Sonda de actividad de Kubernetes | `200 OK` siempre que el servidor de sondas esté a la escucha. | +| `/readyz` | Sonda de preparación de Kubernetes | `200 OK` siempre que el servidor de sondas esté a la escucha. | + +Ambos endpoints se registran con la misma comprobación trivial de ping (`healthz.Ping` de `sigs.k8s.io/controller-runtime`). Por lo tanto, una sonda fallida significa "el proceso del manager no está sirviendo HTTP en `:8081`", no "los controladores no están en mal estado". Para detectar problemas a nivel de controlador, use en su lugar las [métricas de reconciliación](#reconciliation-activity). + +Ambos endpoints se exponen en el puerto `8081` de forma predeterminada. Están conectados a la Implementación de la siguiente manera: + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +Una sonda que falla repetidamente suele significar que el propio servidor de la sonda nunca llegó a iniciarse; por ejemplo, que el manager se cerró prematuramente durante el arranque. Revise los logs del manager en busca de `unable to start manager`, errores de RBAC o errores de `cache did not sync`. + +
+ ## Catálogo de métricas +
+ +El operador no registra recolectores personalizados de Prometheus. Todo lo que aparece a continuación lo exponen las bibliotecas subyacentes `controller-runtime` y `client-go`. Las series más útiles, agrupadas según su finalidad: + +
+ ### Actividad de reconciliación +
+ +| Métrica | Tipo | Etiquetas | +| -------------------------------------------------- | ---------- | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | counter | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | counter | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | histograma | `controller` | +| `controller_runtime_active_workers` | gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | gauge | `controller` | + +La etiqueta `controller` se deriva en `controller-runtime` del tipo de recurso registrado con `For(...)`. Con el código actual en `internal/controller/clickhouse` e `internal/controller/keeper`, esto corresponde a `clickhousecluster` y `keepercluster`, respectivamente. Si ha personalizado el operador, verifíquelo con una recopilación puntual de `/metrics`. + +
+ ### Cola de trabajo +
+ +| Métrica | Tipo | Etiquetas | +| --------------------------------------------- | --------- | -------------------------------- | +| `workqueue_depth` | gauge | `name`, `controller`, `priority` | +| `workqueue_adds_total` | counter | `name`, `controller` | +| `workqueue_retries_total` | counter | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | gauge | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | gauge | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | histogram | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | histogram | `name`, `controller` | + +Las etiquetas `name` y `controller` tienen el mismo valor (el nombre del controlador). + +
+ ### Tráfico del servidor de API +
+ +| Métrica | Tipo | Etiquetas | +| ---------------------------- | -------- | ------------------------ | +| `rest_client_requests_total` | contador | `code`, `method`, `host` | + +
+ ### Elección de líder +
+ +| Métrica | Tipo | Etiquetas | +| ------------------------------- | ----- | ------------------------------------ | +| `leader_election_master_status` | gauge | `name` (= `d4ceba06.clickhouse.com`) | + +El gráfico de Helm habilita `--leader-elect` de forma predeterminada, por lo que esta métrica está presente en las instalaciones estándar de Helm. Cuando se ejecuta el binario directamente sin ese indicador, la métrica no aparece. + +
+ ### Entorno de ejecución +
+ +Colectores estándar del proceso y del entorno de ejecución de Go: `go_goroutines`, `go_memstats_*`, `process_cpu_seconds_total`, `process_resident_memory_bytes`, etc. + +
+ ## Consultas útiles de PromQL +
+ +
+ ### Resumen del estado de salud +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### Detección de acumulación +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### Limitación de tasa y carga sobre la API +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### Estado del líder (implementación de alta disponibilidad) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## Alertas sugeridas +
+ +Punto de partida para una PrometheusRule (ajuste los umbrales según su entorno): + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +La última regla solo tiene sentido cuando está habilitada la elección de líder. + +
+ ## Verificación de la configuración +
+ +Una comprobación rápida de extremo a extremo, suponiendo que el chart se ha instalado en `clickhouse-operator-system`: + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +Si la recopilación devuelve métricas en el formato de exposición de Prometheus, el endpoint y RBAC están correctamente conectados. + + + +* [Instalación](/es/products/kubernetes-operator/install/helm) — Valores de Helm relevantes para la supervisión. +* [Configuración](/es/products/kubernetes-operator/guides/configuration) — Configuración de TLS compartida con el servidor de métricas. \ No newline at end of file diff --git a/es/products/kubernetes-operator/guides/scaling.mdx b/es/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..8629062e1 --- /dev/null +++ b/es/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,109 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: Escalado de clústeres +keywords: ['kubernetes', 'escalado', 'réplicas', 'segmentos', 'keeper', 'quorum'] +description: 'Cómo escalar las réplicas y los segmentos de ClickHouse y los miembros del quórum de Keeper, y qué hace automáticamente el operador.' +doc_type: 'guide' +--- + +Para escalar un clúster, edite el número de réplicas y segmentos en el recurso personalizado. El operador reconcilia el clúster en ejecución con la nueva topología: crea o elimina los StatefulSets de cada réplica, mantiene el esquema sincronizado y refleja el progreso mediante las condiciones de estado. + +Esta guía explica cómo escalar las réplicas y los segmentos de `ClickHouseCluster`, cómo escalar de forma segura el quórum de un `KeeperCluster` y qué condiciones observar mientras una operación de escalado está en curso. + + + Un `ClickHouseCluster` siempre necesita un Keeper, al que se hace referencia mediante el campo obligatorio `spec.keeperClusterRef`; el operador coordina el clúster a través de él independientemente de su tamaño. Para ejecutar más de una réplica por segmento, los datos también deben residir en tablas `ReplicatedMergeTree`, ya que la replicación es lo que permite que una segunda réplica pueda servir las mismas filas. + + +
+ ## Escalado de réplicas +
+ +`spec.replicas` establece el número de réplicas en cada segmento. Cada réplica se ejecuta en su propio StatefulSet llamado `-clickhouse--`, por lo que un clúster con `shards: 2` y `replicas: 3` ejecuta seis StatefulSets. + +Aumente o reduzca la cantidad directamente: + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +Al ampliar la escala, el operador crea los nuevos StatefulSets por réplica, espera a que cada pod de Kubernetes esté listo y, a continuación, sincroniza el esquema con las nuevas réplicas (consulte [Sincronización automática del esquema](#automatic-schema-sync)). Al reducir la escala, elimina los StatefulSets sobrantes y limpia los registros obsoletos de réplicas de la base de datos replicada que dejaron las réplicas eliminadas. + +
+ ## Escalado de segmentos +
+ +`spec.shards` establece el número de segmentos. Cada segmento nuevo añade un conjunto completo de StatefulSets por réplica, y el operador crea un [PodDisruptionBudget por segmento](/es/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) para que una interrupción en un segmento no se contabilice para otro. + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +Cada segmento contiene una porción distinta de los datos, y el operador no copia ni mueve filas entre segmentos. Una tabla `Distributed` o un esquema de enrutamiento explícito decide en qué segmento acaba una fila, por lo que agregar un segmento proporciona un destino para las nuevas escrituras sin afectar a las filas ya almacenadas en los segmentos existentes. + +
+ ## Sincronización automática del esquema +
+ +Cuando `spec.settings.enableDatabaseSync` es `true` (valor predeterminado), el operador mantiene el esquema sincronizado a medida que cambia la topología: + +* **Al ampliar la escala** — una vez que al menos dos réplicas están listas, el operador replica las definiciones de las bases de datos en las réplicas recién creadas, de modo que una réplica nueva se una con las mismas bases de datos `Replicated` y de integración que el resto del clúster. +* **Al reducir la escala** — antes de que desaparezca una réplica, el operador elimina el registro de esa réplica de cada base de datos `Replicated` con `SYSTEM DROP DATABASE REPLICA`, para que el clúster reducido no espere a una réplica de base de datos `Replicated` que ya no existe. + +Esto cubre las bases de datos `Replicated` y los motores de base de datos de integración. No mueve datos de tablas: los datos a nivel de fila residen en tablas `ReplicatedMergeTree` y se replican mediante Keeper de forma independiente de esta sincronización del esquema. Con una sola réplica lista, no hay nada que replicar, por lo que el operador omite este paso y registra que no tiene ningún destino. + +Establece `enableDatabaseSync: false` para desactivar este comportamiento, por ejemplo, cuando una herramienta externa se encarga de la propagación del esquema. En ese caso, el operador informa del motivo `SchemaSyncDisabled` en la condición `SchemaInSync`. + +
+ ## Condiciones que debe vigilar +
+ +Inspeccione el progreso del recurso personalizado mientras se ejecuta una operación de escalado: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| Condición | Motivo | Significado | +| -------------------- | ---------------------- | -------------------------------------------------------------------------------------------- | +| `ClusterSizeAligned` | `UpToDate` | El número de réplicas en ejecución coincide con la topología solicitada | +| `ClusterSizeAligned` | `ScalingUp` | El operador está añadiendo réplicas | +| `ClusterSizeAligned` | `ScalingDown` | El operador está eliminando réplicas | +| `SchemaInSync` | `ReplicasInSync` | Las bases de datos existen en todas las réplicas y se han limpiado los metadatos obsoletos | +| `SchemaInSync` | `DatabasesNotCreated` | El operador aún no ha terminado de crear las bases de datos en las nuevas réplicas | +| `SchemaInSync` | `ReplicasNotCleanedUp` | Los metadatos obsoletos de las réplicas tras una reducción de escala aún no se han eliminado | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync` es `false` | +| `Ready` | `AllShardsReady` | Cada segmento tiene una réplica lista | +| `Ready` | `SomeShardsNotReady` | Al menos un segmento no tiene ninguna réplica lista | + +Una operación de escalado se completa cuando `ClusterSizeAligned` informa `UpToDate`, `SchemaInSync` informa `ReplicasInSync` y `Ready` informa `AllShardsReady`. + +
+ ## Escalado de Keeper +
+ +Un `KeeperCluster` ejecuta un quorum de RAFT, por lo que el operador modifica sus miembros **una réplica cada vez** y solo cuando el clúster se encuentra en un estado estable. Esto protege el quorum: un clúster `2F+1` tolera la caída de `F` miembros, de modo que un clúster de 3 nodos sigue funcionando si falta un miembro y uno de 5 nodos, si faltan dos. + +```yaml +spec: + replicas: 5 # was 3 +``` + +Al aumentar la escala, el operador añade al quórum el ID de réplica libre más bajo; al reducirla, elimina el ID más alto. Cada paso espera a que el quórum se estabilice antes de iniciar el siguiente. El [PodDisruptionBudget de Keeper](/es/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) usa de forma predeterminada `maxUnavailable: replicas/2` para preservar el quórum durante interrupciones voluntarias. + +La condición `ScaleAllowed` indica si el quórum puede cambiar de miembros en este momento: + +| Motivo | Significado | +| -------------------------- | --------------------------------------------------------------------------- | +| `ReadyToScale` | El quórum es estable y el operador puede añadir o eliminar un miembro | +| `ReplicaHasPendingChanges` | Una réplica aún tiene un cambio de configuración pendiente | +| `ReplicaNotReady` | Una réplica no está lista, por lo que los cambios de miembros deben esperar | +| `NoQuorum` | El clúster no tiene quórum y no puede cambiar de miembros de forma segura | +| `WaitingFollowers` | El operador está esperando a que los seguidores se pongan al día | + +Escala Keeper de uno en uno y deja que `ScaleAllowed` vuelva a `ReadyToScale` entre cambios. Saltar varios miembros a la vez no evita la reconciliación paso a paso: el operador sigue recorriendo el quórum, un miembro por paso. \ No newline at end of file diff --git a/es/products/kubernetes-operator/guides/tls.mdx b/es/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..2fa3b24e7 --- /dev/null +++ b/es/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,338 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: Protección de un clúster con TLS +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'seguridad', 'certificados'] +description: 'Cómo proteger un clúster de ClickHouse con TLS mediante cert-manager, incluidas las conexiones de Client y el cifrado de Keeper.' +doc_type: 'guide' +--- + +Esta guía explica cómo cifrar un clúster de ClickHouse de extremo a extremo: emitir un +certificado con [cert-manager](https://cert-manager.io/), habilitar TLS en el +clúster, conectar un Client a través de los puertos seguros y extender el cifrado al +tráfico de coordinación de Keeper. + +Está orientada a tareas. Para consultar la referencia campo por campo de `spec.settings.tls`, consulta +[Configuración → Configuración de TLS/SSL](/es/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +y la [Referencia de la API](/es/products/kubernetes-operator/reference/api-reference#clustertlsspec). + +
+ ## Requisitos previos +
+ +* Un clúster de ClickHouse en ejecución gestionado por el operador (consulte la [Introducción](/es/products/kubernetes-operator/guides/introduction)). +* [cert-manager](https://cert-manager.io/docs/installation/) instalado en el clúster. +* Acceso con `kubectl` al espacio de nombres del clúster. + +El operador no genera certificados por sí mismo, sino que consume un `Secret` de Kubernetes +que usted proporciona. cert-manager es la forma recomendada de generar y +rotar ese `Secret`, pero cualquier herramienta que escriba un `Secret` en el formato esperado funciona. + +
+ ## Cómo debe ser el formato de los certificados para el operador +
+ +TLS se habilita haciendo que `spec.settings.tls.serverCertSecret` apunte a un Secret que +contiene tres claves: + +| Clave del Secret | Contenido | +| ---------------- | ---------------------------------------------- | +| `tls.crt` | Certificado de servidor en formato PEM | +| `tls.key` | Clave privada en formato PEM | +| `ca.crt` | Cadena de certificados de la CA en formato PEM | + +Este es exactamente el formato que cert-manager genera para un recurso `Certificate`, por lo que no +hace falta ninguna conversión. El operador los monta en cada pod de Kubernetes en +`/etc/clickhouse-server/tls/` y los incorpora a la configuración `openSSL` de ClickHouse. + + + `serverCertSecret` es **obligatorio** cuando `tls.enabled: true`. El webhook de + validación rechaza un clúster que habilita TLS sin él, y rechaza `required: true` + salvo que `enabled: true`. + + +
+ ## Paso 1 — Crea una CA inicial con cert-manager +
+ +La configuración más reproducible es una CA autofirmada que luego firma el +certificado del servidor. Esto proporciona un `ca.crt` estable en el que los clientes pueden confiar. + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +En producción, reemplaza el bootstrap autofirmado por tu emisor real (una +CA corporativa, Vault, ACME, etc.). Solo cambia el Paso 2 — la configuración del +clúster es idéntica. + +
+ ## Paso 2 — Emitir el certificado del servidor +
+ +Solicita un certificado de entidad final al emisor de la CA. Los `dnsNames` deben cubrir la forma en que +los clientes acceden a los pods de Kubernetes. El operador crea un único Service **headless** llamado +`-clickhouse-headless`, y cada pod de Kubernetes de réplica es accesible en +`-clickhouse---0.-clickhouse-headless..svc.cluster.local`. +Un comodín para el dominio del servicio headless cubre todas las réplicas: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + El operador **no** crea un Service para todo el clúster (con balanceo de carga). Si + quieres un único endpoint estable al que conectarte, crea tu propio Service de tipo `ClusterIP` + que seleccione los pods de Kubernetes del clúster y añade su nombre DNS a `dnsNames` más arriba. + + +cert-manager crea el Secret `clickhouse-cert` con `tls.crt`, `tls.key` y +`ca.crt`, y lo renueva antes de que caduque. Verifica que exista: + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## Paso 3 — Habilitar TLS en el clúster +
+ +Configure el clúster para usar el Secret: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### Qué hace el operador +
+ +Cuando `tls.enabled: true`, el operador: + +* **Abre los puertos seguros** en cada pod de Kubernetes y en el Service headless: `9440` + (TLS nativo) y `8443` (HTTPS). Se añaden junto a los puertos ya existentes. +* **Monta el Secret** en `/etc/clickhouse-server/tls/` y genera el + bloque `openSSL` de ClickHouse con `verificationMode: relaxed`, + `disableProtocols: sslv2,sslv3` y `preferServerCiphers: true`. Estos son los + valores predeterminados; consulta [Personalizar la configuración de TLS](#custom-tls-settings) para sobrescribirlos. + +Cuando además estableces `required: true`, el operador también: + +* **Elimina los puertos inseguros** `9000` (nativo) y `8123` (HTTP): solo se mantienen las variantes + TLS, por lo que los clientes en texto plano ya no pueden conectarse. +* **Cambia la sonda de actividad del pod de Kubernetes** al puerto nativo seguro `9440`, para que las + comprobaciones de estado sigan funcionando sin necesidad de un listener en texto plano. + + + Los puertos TLS `8443` y `9440` quedan reservados por el webhook **de forma incondicional**, + incluso cuando TLS está desactivado, por lo que cambiar `tls.enabled` más adelante nunca entra en conflicto con una + entrada de `spec.additionalPorts`. Consulta + [Configuración → `additionalPorts`](/es/products/kubernetes-operator/guides/configuration#additional-ports). + + +
+ ## Paso 4 — Conéctese mediante TLS +
+ +Con `required: true`, los clientes deben usar los puertos seguros y confiar en la CA. Acceda +a un pod de Kubernetes de una réplica concreta a través del Service headless (o de su propio `ClusterIP` +Service si creó uno). + +**Protocolo nativo** (`clickhouse-client`, puerto `9440`): + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (puerto `8443`): + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +Obtén `ca.crt` directamente del Secret para hacer pruebas locales: + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## Cifrado del tráfico de Keeper +
+ +Habilitar TLS en el clúster de ClickHouse **no** cifra la conexión con Keeper. +Habilítelo en el `KeeperCluster` de forma independiente: emita un certificado para el servicio +de Keeper (pasos 1–2 con los `dnsNames` del servicio de Keeper) y haga referencia a él: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +Keeper expone su puerto de client seguro en `2281`. Una vez que Keeper tiene TLS habilitado, **el +clúster de ClickHouse se conecta a él automáticamente a través de TLS**; no se requiere ninguna configuración adicional en el +lado de ClickHouseCluster. ClickHouse verifica el certificado de Keeper con su propio +paquete `ca.crt` cuando tiene TLS habilitado; de lo contrario, usa el paquete de CA predeterminado del sistema. + +
+ ## Bundle de CA personalizado +
+ +Si ClickHouse debe confiar en una CA distinta de la que figura en su certificado del servidor (por +ejemplo, Keeper firmado por una CA independiente), proporcione un `caBundle`: + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +El operador monta este paquete y hace que la verificación de `openSSL` del lado del `Client` apunte a +este en lugar de al propio `ca.crt` del certificado. + +
+ ## Personalizar la configuración de TLS +
+ +El bloque `openSSL` que genera el operador es la configuración predeterminada, no un límite. Se escribe +en la configuración principal del servidor; todo lo que esté en `spec.settings.extraConfig` se renderiza en +`config.d/99-extra-config.yaml`, que ClickHouse combina **al final**, por lo que sobrescribe los +valores generados. + +Para reforzar la configuración predeterminada —por ejemplo, exigir una verificación estricta del extremo remoto y elevar el +protocolo mínimo a TLS 1.2—, establezca las claves de `openSSL.server` que quiera cambiar: + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +La combinación se realiza por clave: solo se reemplazan los valores que defines, y las claves generadas que +omites (rutas de los certificados, configuración de la CA) se conservan. Consulta las +[opciones de configuración del servidor para `openSSL`](/es/reference/settings/server-settings/settings#openssl) +para ver las opciones disponibles, y +[Configuración → Configuración adicional integrada](/es/products/kubernetes-operator/guides/configuration#embedded-extra-configuration) +para saber cómo se combina `extraConfig`. + +
+ ## Verificar y solucionar problemas +
+ +**Verifique que los puertos seguros estén abiertos en el Service headless:** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**Confirme que el certificado esté montado en el pod de Kubernetes:** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| Síntoma | Causa probable | +| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Los pods no se inician / error al montar el volumen tras habilitar TLS | Falta el Secret indicado o no contiene `tls.crt`/`tls.key`/`ca.crt`. El operador no valida el contenido del Secret; si faltan claves, esto se manifiesta como un error al montar el volumen del pod de Kubernetes, no como una condición de estado específica. Inspecciona el pod de Kubernetes con `kubectl describe pod`. | +| El webhook rechaza el clúster | Se estableció `required: true` sin `enabled: true`, o `enabled: true` sin `serverCertSecret`. | +| `certificate verify failed` del Client | El Client no confía en la CA. Pasa el `ca.crt` del Secret o comprueba que los `dnsNames` del certificado incluyan el host al que te conectas. | +| Un Client en texto sin cifrar de repente no puede conectarse | `required: true` quitó los puertos `9000`/`8123`. Cambia el Client a `9440`/`8443`, o establece `required: false` para mantener abiertos los puertos no seguros durante la migración. | + +
+ ## Véase también +
+ +* [Configuración → Configuración de TLS/SSL](/es/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — referencia de campos +* [Configuración → `additionalPorts`](/es/products/kubernetes-operator/guides/configuration#additional-ports) — puertos reservados +* [Referencia de la API → ClusterTLSSpec](/es/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [Configuración del servidor `openSSL`](/es/reference/settings/server-settings/settings#openssl) — opciones de TLS que se pueden sobrescribir mediante `extraConfig` \ No newline at end of file diff --git a/es/products/kubernetes-operator/install/helm.mdx b/es/products/kubernetes-operator/install/helm.mdx index 35571b533..1e214f159 100644 --- a/es/products/kubernetes-operator/install/helm.mdx +++ b/es/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ Instalar una versión específica del operador helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/es/products/kubernetes-operator/install/kubectl.mdx b/es/products/kubernetes-operator/install/kubectl.mdx index 0104f3572..55c62fa9f 100644 --- a/es/products/kubernetes-operator/install/kubectl.mdx +++ b/es/products/kubernetes-operator/install/kubectl.mdx @@ -72,10 +72,10 @@ keeperclusters.clickhouse.com 2025-01-06T00:00:00Z ```
- ## Configurar opciones personalizadas de despliegue + ## Configurar opciones personalizadas para desplegar
-Si quieres configurar las opciones de despliegue del operador, sigue estos pasos. +Si quieres configurar las opciones para desplegar el operador, sigue estos pasos. @@ -99,13 +99,13 @@ Si quieres configurar las opciones de despliegue del operador, sigue estos pasos - ### Compilar e implementar + ### Compilar y desplegar Compila los manifiestos del operador y aplícalos: ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/es/products/kubernetes-operator/navigation.json b/es/products/kubernetes-operator/navigation.json index b75f40840..040bf305a 100644 --- a/es/products/kubernetes-operator/navigation.json +++ b/es/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "es/products/kubernetes-operator/guides/introduction", - "es/products/kubernetes-operator/guides/configuration" + "es/products/kubernetes-operator/guides/configuration", + "es/products/kubernetes-operator/guides/monitoring", + "es/products/kubernetes-operator/guides/scaling", + "es/products/kubernetes-operator/guides/tls" ] }, { diff --git a/es/products/kubernetes-operator/overview.mdx b/es/products/kubernetes-operator/overview.mdx index 5db979d38..8f3005adc 100644 --- a/es/products/kubernetes-operator/overview.mdx +++ b/es/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ Elige el método de instalación que prefieras: * **[Introducción](/es/products/kubernetes-operator/guides/introduction)** - Descripción general de los conceptos de ClickHouse Operator * **[Guía de configuración](/es/products/kubernetes-operator/guides/configuration)** - Configuración de los clústeres de ClickHouse y Keeper -* **[Monitorización](/es/products/kubernetes-operator/guides/introduction)** - Supervise clickhouse-operator con métricas de Prometheus +* **[Monitorización](/es/products/kubernetes-operator/guides/monitoring)** - Métricas de Prometheus y sondas de estado para el operador +* **[Escalado](/es/products/kubernetes-operator/guides/scaling)** - Escalado de réplicas, segmentos y del quórum de Keeper +* **[Protección con TLS](/es/products/kubernetes-operator/guides/tls)** - Cifrado de los clústeres de extremo a extremo con cert-manager
## Referencia diff --git a/es/products/kubernetes-operator/reference/api-reference.mdx b/es/products/kubernetes-operator/reference/api-reference.mdx index 5e90e4b98..ee1618a5a 100644 --- a/es/products/kubernetes-operator/reference/api-reference.mdx +++ b/es/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'Referencia de la API' Este documento ofrece una referencia detallada de la API de los recursos personalizados de ClickHouse Operator. +
+ ## AdditionalPort +
+ +AdditionalPort define un puerto TCP adicional que se expondrá en el pod de ClickHouse y en el Service headless administrado por el operador. + +| Campo | Tipo | Descripción | Obligatorio | Predeterminado | +| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | +| `name` | string | El nombre identifica de forma única el puerto dentro de la lista. Se utiliza tanto como nombre del puerto del contenedor como nombre del puerto del Service.
Debe ser una `DNS_LABEL`. | true | | +| `port` | integer | El puerto es el número de puerto TCP que se va a exponer. | true | | + +Aparece en: + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec define el estado deseado de ClickHouseCluster. -| Campo | Tipo | Descripción | Obligatorio | Predeterminado | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | -| `replicas` | integer | Número de réplicas en el único segmento. | false | 3 | -| `shards` | integer | Número de segmentos en el clúster. | false | 1 | +| Campo | Tipo | Descripción | Obligatorio | Predeterminado | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | +| `replicas` | integer | Número de réplicas en el único segmento. | false | 3 | +| `shards` | integer | Número de segmentos en el clúster. | false | 1 | | `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Referencia al KeeperCluster que se usa para la coordinación de ClickHouse.
Cuando se omite el espacio de nombres, se usa el espacio de nombres de ClickHouseCluster. | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parámetros que se pasan a la especificación del pod de Kubernetes de ClickHouse. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parámetros que se pasan a la especificación del contenedor de ClickHouse. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificación del almacenamiento persistente para los datos de ClickHouse. | false | | -| `labels` | object (keys:string, values:string) | Etiquetas adicionales que se añaden a los recursos. | false | | -| `annotations` | object (keys:string, values:string) | Anotaciones adicionales que se añaden a los recursos. | false | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parámetros que se pasan a la especificación del pod de Kubernetes de ClickHouse. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parámetros que se pasan a la especificación del contenedor de ClickHouse. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificación del almacenamiento persistente para los datos de ClickHouse. | false | | +| `labels` | object (keys:string, values:string) | Etiquetas adicionales que se añaden a los recursos. | false | | +| `annotations` | object (keys:string, values:string) | Anotaciones adicionales que se añaden a los recursos. | false | | | `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura el PDB creado para cada segmento.
Si no se establece, el operador usa de forma predeterminada maxUnavailable=1 para segmentos
de una sola réplica y minAvailable=1 para segmentos con varias réplicas. | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | Parámetros de configuración del servidor ClickHouse. | false | | -| `clusterDomain` | string | ClusterDomain es el sufijo de dominio del clúster de Kubernetes que se usa para la resolución DNS. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel especifica el canal de versiones para las comprobaciones de actualización de versiones principales.
Cuando está vacío, solo se propondrán actualizaciones menores. Los valores permitidos son: stable, lts o una versión major.minor específica (por ejemplo, 25.8). | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Anulaciones de VersionProbeTemplate para el Job de detección de versión. | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret es una referencia opcional a un secreto gestionado externamente que contiene secretos del clúster.
El secreto debe residir en el mismo espacio de nombres que el clúster. | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | Parámetros de configuración del servidor ClickHouse. | false | | +| `clusterDomain` | string | ClusterDomain es el sufijo de dominio del clúster de Kubernetes que se usa para la resolución de DNS. | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel especifica el canal de publicación para las comprobaciones de actualización de versiones principales.
Cuando está vacío, solo se propondrán actualizaciones menores. Los valores permitidos son: stable, lts o una versión major.minor específica (por ejemplo, 25.8). | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescrituras de VersionProbeTemplate para el Job de detección de versión. | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret es una referencia opcional a un secreto gestionado externamente que contiene secretos del clúster.
El secreto debe residir en el mismo espacio de nombres que el clúster. | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) array | AdditionalPorts declara puertos TCP adicionales que se expondrán en el pod de Kubernetes de ClickHouse y en el Service headless gestionado por el operador.
El operador solo añade los puertos a los recursos de Kubernetes; no configura el servidor ClickHouse para escuchar en ellos. | false | | Aparece en: @@ -180,7 +196,7 @@ ContainerTemplateSpec describe las anulaciones de la configuración de los conte | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | | `image` | [ContainerImage](#containerimage) | Image es la imagen de contenedor que se va a desplegar. | true | | | `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | ImagePullPolicy de la imagen; de forma predeterminada, es IfNotPresent. | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources son los requisitos de recursos del contenedor del servidor.
Se combinan de forma recursiva con los valores predeterminados del operador mediante SMP. Los límites y solicitudes individuales reemplazan solo las
claves coincidentes; los campos no establecidos conservan los valores predeterminados del operador. | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources son los requisitos de recursos del contenedor del servidor.
Se aplica en su conjunto: los valores predeterminados del operador solo se usan cuando todos los campos de recursos están vacíos. | false | | | `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts es la lista de montajes de volumen del contenedor.
Se concatena con los montajes generados por el operador. Las entradas que comparten un `mountPath` con un montaje del operador
se combinan en un volumen proyectado. | false | | | `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env es la lista de variables de entorno que se establecerán en el contenedor.
Se combina con los valores predeterminados del operador por nombre. | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | SecurityContext define las opciones de seguridad con las que debe ejecutarse el contenedor.
Un SecurityContext no nulo reemplaza por completo los valores predeterminados del operador; el usuario es responsable de toda la
estructura. Cuando es nulo, se conservan los valores predeterminados del operador.
Más información: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | @@ -302,19 +318,19 @@ Aparece en: KeeperClusterSpec define el estado deseado de KeeperCluster. -| Campo | Tipo | Descripción | Obligatorio | Predeterminado | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | -| `replicas` | integer | Número de réplicas en el clúster | false | 3 | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parámetros que se pasan a la especificación del pod de Kubernetes de Keeper. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parámetros que se pasan a la especificación del contenedor de Keeper. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificación del almacenamiento persistente para los datos de ClickHouse Keeper. | false | | -| `labels` | object (keys:string, values:string) | Etiquetas adicionales que se añaden a los recursos. | false | | -| `annotations` | object (keys:string, values:string) | Anotaciones adicionales que se añaden a los recursos. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura el PDB creado para el clúster de Keeper.
Si no se establece, el operador usa de forma predeterminada maxUnavailable=replicas/2
(para preservar el quorum en un clúster 2F+1). | false | | -| `settings` | [KeeperSettings](#keepersettings) | Parámetros de configuración del servidor de ClickHouse Keeper. | false | | -| `clusterDomain` | string | ClusterDomain es el sufijo de dominio del clúster de Kubernetes que se usa para la resolución DNS. | false | cluster.local | +| Campo | Tipo | Descripción | Obligatorio | Predeterminado | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -------------- | +| `replicas` | integer | Número de réplicas en el clúster | false | 3 | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parámetros que se pasan a la especificación del pod de Kubernetes de Keeper. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parámetros que se pasan a la especificación del contenedor de Keeper. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificación del almacenamiento persistente para los datos de ClickHouse Keeper. | false | | +| `labels` | object (keys:string, values:string) | Etiquetas adicionales que se añaden a los recursos. | false | | +| `annotations` | object (keys:string, values:string) | Anotaciones adicionales que se añaden a los recursos. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura el PDB creado para el clúster de Keeper.
Si no se establece, el operador usa de forma predeterminada maxUnavailable=replicas/2
(para preservar el quorum en un clúster 2F+1); los clústeres con una sola réplica usan maxUnavailable=1. | false | | +| `settings` | [KeeperSettings](#keepersettings) | Parámetros de configuración del servidor de ClickHouse Keeper. | false | | +| `clusterDomain` | string | ClusterDomain es el sufijo de dominio del clúster de Kubernetes que se usa para la resolución DNS. | false | cluster.local | | `upgradeChannel` | string | UpgradeChannel especifica el canal de versiones para las comprobaciones de actualización de versiones principales.
Si está vacío, solo se propondrán actualizaciones menores. Los valores permitidos son: stable, lts o una versión específica major.minor (por ejemplo, 25.8). | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescrituras de VersionProbeTemplate para el Job de detección de versión. | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescrituras de VersionProbeTemplate para el Job de detección de versión. | false | | Aparece en: @@ -326,17 +342,17 @@ Aparece en: KeeperClusterStatus define el estado observado de KeeperCluster. -| Campo | Tipo | Descripción | Obligatorio | Predeterminado | -| ----------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | -| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array | | false | | -| `readyReplicas` | integer | ReadyReplicas Número total de réplicas listas para atender solicitudes. | false | | -| `configurationRevision` | string | ConfigurationRevision indica la revisión de configuración de destino para cada réplica. | true | | -| `statefulSetRevision` | string | StatefulSetRevision indica la revisión de StatefulSet de destino para cada réplica. | true | | -| `currentRevision` | string | CurrentRevision indica la última revisión de la especificación de KeeperCluster aplicada. | true | | -| `updateRevision` | string | UpdateRevision indica la última revisión de la especificación de KeeperCluster solicitada. | true | | -| `observedGeneration` | integer | ObservedGeneration indica la última generación observada por el controlador. | true | | -| `version` | string | Version indica la versión informada por la imagen del contenedor. | false | | -| `versionProbeRevision` | string | VersionProbeRevision es el hash de la imagen de la última comprobación de versión correcta.
Cuando coincide con el hash actual de la imagen, la Version almacenada en caché se usa directamente. | false | | +| Campo | Tipo | Descripción | Obligatorio | Predeterminado | +| ----------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | +| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array | | false | | +| `readyReplicas` | integer | ReadyReplicas Número total de réplicas listas para atender solicitudes. | false | | +| `configurationRevision` | string | ConfigurationRevision indica la revisión de configuración de destino para cada réplica. | true | | +| `statefulSetRevision` | string | StatefulSetRevision indica la revisión de StatefulSet de destino para cada réplica. | true | | +| `currentRevision` | string | CurrentRevision indica la última revisión de la especificación de KeeperCluster aplicada. | true | | +| `updateRevision` | string | UpdateRevision indica la última revisión de la especificación de KeeperCluster solicitada. | true | | +| `observedGeneration` | integer | ObservedGeneration indica la última generación observada por el controlador. | true | | +| `version` | string | Version indica la versión informada por la imagen del contenedor. | false | | +| `versionProbeRevision` | string | VersionProbeRevision es el hash de la imagen de la última sonda de versión correcta.
Cuando coincide con el hash actual de la imagen, la Version almacenada en caché se usa directamente. | false | | Aparece en: diff --git a/es/resources/changelogs/cloud/release-status.mdx b/es/resources/changelogs/cloud/release-status.mdx index 805ae6026..363ba55b0 100644 --- a/es/resources/changelogs/cloud/release-status.mdx +++ b/es/resources/changelogs/cloud/release-status.mdx @@ -51,14 +51,27 @@ Las ventanas de actualización programadas están disponibles para todos los can >\" が使用されます。", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Kafka ソースのフォーマット。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka ソース用の IAM ロール。IAM ロール認証とともに使用します。詳細は ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "Kafka ソースへの安全なプライベート接続に使用する Reverse Private Endpoint の UUID。", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka ソースのトピック。", + "type": "string" + }, + "type": { + "description": "Kafka ソースの種類。", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "Kinesis Stream で使用する認証方式。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis Stream のフォーマット。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "認証に使用する IAM ロール。IAM_ROLE を使用する場合は必須です。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Kinesis Stream から読み取る際に使用するイテレーターの種類。AT_TIMESTAMP を使用する場合は、timestamp フィールドを指定する必要があります。", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis Stream の AWS リージョン。", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis Stream の名前。", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Kinesis Stream から読み取りを開始する UNIX タイムスタンプ。iteratorType が AT_TIMESTAMP の場合は必須です。", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Kinesis Stream で拡張ファンアウトを使用します。", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "宛先テーブルのカラム。Postgres を除くすべてのパイプタイプで必須のフィールドです。", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "宛先データベース。", + "type": "string" + }, + "managedTable": { + "description": "テーブルは ClickPipes によって管理されていますか。Postgres を除くすべてのパイプタイプで必須のフィールドです。", + "type": "boolean" + }, + "roles": { + "description": "ClickPipe は、これらのロールを持つ ClickHouse ユーザーを作成します。必要に応じて、ここにカスタムロールを追加してください。", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "宛先テーブル。Postgres を除くすべてのパイプタイプで必須のフィールドです。", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "スキーマレジストリの認証方式。", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "スキーマレジストリの証明書を検証するための、PEM 形式でエンコードされた CA 証明書。", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "スキーマ URL。HTTPS が必要です。", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "接続先のPostgresインスタンスのデータベース。", + "type": "string" + }, + "host": { + "description": "接続先のPostgresインスタンスのホスト。", + "type": "string" + }, + "port": { + "description": "接続先のPostgresインスタンスのポート。", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgresパイプのテーブルマッピング。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "認証方式。CONNECTION_STRING は Azure Blob Storage 用です。IAM_ROLE と IAM_USER は AWS S3/GCS/DigitalOcean 用です。指定しない場合、認証は使用されません。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage のコンテナー名。type が azureblobstorage の場合は必須です。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "ファイルに使用される圧縮アルゴリズム。", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 認証用の接続文字列。authentication が CONNECTION_STRING の場合は必須です。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "ファイルで使用される区切り文字。", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "ファイルのフォーマット。", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM ロール認証で使用する IAM ロール。詳しくは ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "true に設定すると、パイプはソースから新しいファイルを継続的に読み取ります。false に設定すると、パイプはファイルを 1 回だけ読み取ります。新しいファイルは辞書式順序でアップロードする必要があります。", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure コンテナー内のファイルのパス。Azure Blob Storage ソースで使用されます。bash 形式のワイルドカードを使用して複数のファイルを指定できます。詳しくは、path でワイルドカードを使用する方法に関するドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "イベントベースの継続的インジェスト用の SQS キュー URL。指定すると、ファイルは辞書式順序ではなく S3 のイベント通知に基づいて取り込まれます。isContinuous が true で、authentication が public ではない場合にのみ適用されます。", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage ソースの種類。", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "取り込みたいファイルのパスを指定します。bash 形式のワイルドカードを使用して複数のファイルを指定できます。詳しくは、path でワイルドカードを使用する方法に関するドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "宛先テーブルのカラム。更新されるのは ClickPipe の設定のみで、テーブルスキーマは更新されません。", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka ソースの認証方式。サポートされている認証方式: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "ブローカーの証明書を検証するための、PEM 形式でエンコードされた CA 証明書。", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka ソースの認証情報。認証方式でサポートされているものを 1 つ選択してください。", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "Kafka ソース用の IAM ロール。IAM ロール認証とともに使用します。詳細は ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "Kafka ソースへの安全なプライベート接続に使用する Reverse Private Endpoint の UUID。", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Kinesis Stream で使用する認証方式。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "認証に使用する IAM ロール。IAM_ROLE を使用する場合は必須です。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "認証方式。CONNECTION_STRING は Azure Blob Storage 用です。IAM_ROLE と IAM_USER は AWS S3/GCS/DigitalOcean 用です。指定しない場合、認証は使用されません。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage のコンテナー名。type が azureblobstorage の場合に必須です。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 認証用の接続文字列。authentication が CONNECTION_STRING の場合に必須です。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "IAM ロール認証で使用する IAM ロール。詳しくは ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Azure コンテナー内のファイルへのパス。Azure Blob Storage のソースで使用されます。bash 形式のワイルドカードを使用して複数のファイルを指定できます。詳しくは、パスでのワイルドカードの使用に関するドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "ソーススキーマ名。", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "ソーステーブル名。", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "ターゲットテーブルで使用するテーブルエンジン。", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "ターゲットテーブル名。", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "各バッチで取得する行数。", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Postgres からデータを同期する間隔（秒）。", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "接続先のPostgresインスタンスのデータベース。", + "nullable": true, + "type": "string" + }, + "host": { + "description": "接続先のPostgresインスタンスのホスト。", + "nullable": true, + "type": "string" + }, + "port": { + "description": "接続先のPostgresインスタンスのポート。", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "Postgresパイプに追加するテーブルマッピング。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "Postgresパイプから削除するテーブルマッピング。", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "ClickPipe のフィールドマッピング。更新されるのは ClickPipe の設定のみで、テーブルスキーマは更新されません。", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe の名前。", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "データソースから受信したデータサンプルを検証します。接続に加えて、データの可用性と正確性も検証します。有効にしない場合は、接続のみを検証します。これは Postgres パイプには影響せず、Postgres パイプでは常に接続とテーブル定義のみが検証されます。これは Experimental であり、将来削除される可能性があります。", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka ソースの認証方式。サポートされている認証方式: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Kafka ソースのブローカー。", + "type": "string" + }, + "caCertificate": { + "description": "ブローカーの証明書を検証するための、PEM 形式でエンコードされた CA 証明書。", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Kafka ソースのコンシューマグループ。指定しない場合は \"clickpipes-<>\" が使用されます。", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka ソースの認証情報。認証方式でサポートされているものを 1 つ選択してください。", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Kafka ソースのフォーマット。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka ソース用の IAM ロール。IAM ロール認証とともに使用します。詳細は ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "Kafka ソースへの安全なプライベート接続に使用する Reverse Private Endpoint の UUID。", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka ソースのトピック。", + "type": "string" + }, + "type": { + "description": "Kafka ソースの種類。", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Kinesis Stream で使用する認証方式。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis Stream のフォーマット。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "認証に使用する IAM ロール。IAM_ROLE を使用する場合は必須です。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Kinesis Stream から読み取る際に使用するイテレーターの種類。AT_TIMESTAMP を使用する場合は、timestamp フィールドを指定する必要があります。", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis Stream の AWS リージョン。", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis Stream の名前。", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Kinesis Stream から読み取りを開始する UNIX タイムスタンプ。iteratorType が AT_TIMESTAMP の場合は必須です。", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Kinesis Stream で拡張ファンアウトを使用します。", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "認証方式。CONNECTION_STRING は Azure Blob Storage 用です。IAM_ROLE と IAM_USER は AWS S3/GCS/DigitalOcean 用です。指定しない場合、認証は使用されません。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage のコンテナー名。type が azureblobstorage の場合に必須です。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "ファイルで使用する圧縮アルゴリズム。", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 認証用の接続文字列。authentication が CONNECTION_STRING の場合に必須です。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "ファイルで使用する区切り文字。", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "ファイルのフォーマット。", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM ロール認証で使用する IAM ロール。詳しくは ClickPipes のドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "true に設定すると、パイプはソースから新しいファイルを継続的に読み取ります。false に設定すると、パイプはファイルを一度だけ読み取ります。新しいファイルは辞書式順序でアップロードする必要があります。", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure コンテナー内のファイルへのパス。Azure Blob Storage のソースで使用されます。bash 形式のワイルドカードを使用して複数のファイルを指定できます。詳しくは、パスでのワイルドカードの使用に関するドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "イベントベースの継続的インジェスト用の SQS キュー URL。指定すると、ファイルは辞書式順序ではなく S3 のイベント通知に基づいて取り込まれます。isContinuous が true で、authentication が public ではない場合にのみ適用されます。", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage ソースの種類。", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "取り込み対象のファイルへのパスを指定します。bash 形式のワイルドカードを使用して複数のファイルを指定できます。詳しくは、パスでのワイルドカードの使用に関するドキュメントを参照してください: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "ClickPipe のフィールドマッピング。すべての宛先カラムをマッピングに含める必要があることに注意してください。", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe の名前。", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "データソースから受信したデータサンプルを検証します。接続に加えて、データの可用性と正確性も検証します。有効にしない場合は、接続のみを検証します。これは Postgres パイプには影響せず、Postgres パイプでは常に接続とテーブル定義のみが検証されます。これは Experimental であり、将来削除される可能性があります。", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "宛先テーブルで Nullable カラムを許可します。", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "作成される replication slot のフェイルオーバーを有効にします。replication slot が設定されていない必要があります。", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "初期ロード中に並列で同期するテーブル数。", + "type": "number" + }, + "publicationName": { + "description": "レプリケーションに使用する publication 名。", + "type": "string" + }, + "pullBatchSize": { + "description": "各バッチで取得する行数。", + "type": "number" + }, + "replicationMode": { + "description": "パイプで使用するレプリケーションモード。", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "レプリケーションに使用する replication slot 名。", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "各パーティションでスナップショットする行数。", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "並列でスナップショットするテーブル数。", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Postgres からデータを同期する間隔（秒）。", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "ターゲットテーブルから除外するカラム。", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "ターゲットテーブルのソートキーとして使用する、順序付きのカラム一覧。", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "ソーススキーマ名。", + "type": "string" + }, + "sourceTable": { + "description": "ソーステーブル名。", + "type": "string" + }, + "tableEngine": { + "description": "ターゲットテーブルで使用するテーブルエンジン。", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "ターゲットテーブル名。", + "type": "string" + }, + "useCustomSortingKey": { + "description": "ターゲットテーブルにカスタム sorting key を使用するかどうか。", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "接続先のPostgresインスタンスのデータベース。", + "type": "string" + }, + "host": { + "description": "接続先のPostgresインスタンスのホスト。", + "type": "string" + }, + "port": { + "description": "接続先のPostgresインスタンスのポート。", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgresパイプのテーブルマッピング。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "必要な同時実行数。S3パイプでのみ使用します。0に設定すると、同時実行数はクラスターのメモリに基づいて自動調整されます。", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "各レプリカのCPU（ミリコア）。ストリーミングパイプでのみ使用します。", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "各レプリカのメモリ（GB）。ストリーミングパイプでのみ使用します。", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "必要なレプリカ数。スケーラブルなパイプでのみ使用します。", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "スケール先の同時実行数。S3 パイプのスケーリングに使用します。", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "各レプリカの CPU（ミリコア）。streaming パイプのスケーリングに使用します。", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "各レプリカのメモリ（GB）。streaming パイプのスケーリングに使用します。", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "スケール先のレプリカ数。Kafka パイプのスケーリングに使用します。", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大ダウンロードスレッド数。同時実行するダウンロードスレッドの最大数です", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大挿入スレッド数。同時実行する挿入スレッドの最大数です", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大スレッド数。ファイル処理を同時実行するスレッドの最大数です", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小 insert データブロックサイズ（バイト）。insert 用データブロックの最小サイズです（バイト単位）", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Parallel distributed insert select。parallel distributed insert select の設定です", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "並列ビュー処理。アタッチ済みビューへのプッシュを順次ではなく同時実行するかどうか", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "オブジェクトストレージの同時実行数。ファイル処理を同時実行するスレッド数です", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大ファイル数。1 回の insert バッチで処理するファイルの最大数です", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大 insert バイト数。1 回の insert バッチで処理するバイト数です", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "オブジェクトストレージのポーリング間隔。継続的な取り込みで新しいオブジェクトストレージデータを確認するための更新間隔を設定します", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster 関数を使用。分散処理に ClickHouse の cluster 関数を使用するかどうか", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "ストリーミング時の最大 insert 待機時間。ClickHouse にデータを挿入する前の最大待機時間を設定します。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大ダウンロードスレッド数。同時実行するダウンロードスレッドの最大数です", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大挿入スレッド数。同時実行する挿入スレッドの最大数です", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大スレッド数。ファイル処理の同時実行スレッドの最大数です", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小挿入ブロックサイズ（バイト）。挿入用データブロックの最小サイズです（バイト単位）", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Parallel distributed insert select。Parallel distributed insert select の設定です", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "並列ビュー処理。アタッチされたビューへのプッシュを逐次ではなく同時実行で有効にするかどうか", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "オブジェクトストレージの同時実行数。ファイル処理の同時実行スレッド数です", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大ファイル数。1 回の挿入バッチで処理するファイルの最大数です", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大挿入バイト数。1 回の挿入バッチで処理する最大バイト数です", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "オブジェクトストレージのポーリング間隔。新しいオブジェクトストレージデータを継続的に取り込むための確認間隔を設定します", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster 関数を使用。分散処理に ClickHouse の cluster 関数を使用するかどうか", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "ストリーミングの最大挿入待機時間。ClickHouse にデータを挿入するまでの最大待機時間を設定します。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大ダウンロードスレッド数。同時実行するダウンロードスレッドの最大数です", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大挿入スレッド数。同時実行する挿入スレッドの最大数です", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大スレッド数。ファイル処理の同時実行スレッドの最大数です", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小挿入ブロックサイズ（バイト）。挿入用データブロックの最小サイズです（バイト単位）", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Parallel distributed insert select。Parallel distributed insert select の設定です", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "並列ビュー処理。アタッチされたビューへのプッシュを逐次ではなく同時実行で有効にするかどうか", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "オブジェクトストレージの同時実行数。ファイル処理の同時実行スレッド数です", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大ファイル数。1 回の挿入バッチで処理するファイルの最大数です", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大挿入バイト数。1 回の挿入バッチで処理する最大バイト数です", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "オブジェクトストレージのポーリング間隔。新しいオブジェクトストレージデータを継続的に取り込むための確認間隔を設定します", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster 関数を使用。分散処理に ClickHouse の cluster 関数を使用するかどうか", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "ストリーミングの最大挿入待機時間。ClickHouse にデータを挿入するまでの最大待機時間を設定します。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "状態を変更するコマンド: 'start'、'stop'、'resync'。", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes の CPU（ミリコア単位）。", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes のメモリ（GiB 単位）。CPU コア数の 4 倍である必要があります。", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes の CPU（ミリコア）。", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes のメモリ（GiB）。CPU コア数の4倍である必要があります。", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Reverse private endpoint の説明。最大長は 255 文字です。", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK クラスターの認証タイプ。MSK_MULTI_VPC タイプでは必須です。", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK cluster ARN。MSK_MULTI_VPC タイプで必須です。", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Reverse private endpoint のタイプ。", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC endpoint service 名。", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC リソース構成 ID。VPC_RESOURCE タイプで必須です。", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC リソース共有 ARN。VPC_RESOURCE タイプで必須です。", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "アクセスキー ID (HMAC キー)", + "type": "string" + }, + "bucketPath": { + "description": "バケットパス", + "type": "string" + }, + "bucketProvider": { + "description": "バケットプロバイダー", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "一意のバックアップバケット ID", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "アクセスキー ID（HMAC Key）", + "type": "string" + }, + "bucketPath": { + "description": "バケットパス", + "type": "string" + }, + "bucketProvider": { + "description": "バケットプロバイダー", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "シークレットアクセスキー（HMAC の秘密鍵）", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "アクセスキー ID (HMAC キー)", + "type": "string" + }, + "bucketPath": { + "description": "バケットパス", + "type": "string" + }, + "bucketProvider": { + "description": "バケットプロバイダー", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "シークレットアクセスキー (HMAC シークレットキー)", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "アクセスキー ID (HMAC キー)", + "type": "string" + }, + "bucketPath": { + "description": "バケットパス", + "type": "string" + }, + "bucketProvider": { + "description": "バケットプロバイダー", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "プライベート エンドポイントが配置されているクラウドプロバイダー", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "プライベート エンドポイントの説明", + "type": "string" + }, + "id": { + "description": "プライベート エンドポイントの識別子", + "type": "string" + }, + "region": { + "description": "プライベート エンドポイントが配置されているリージョン", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "追加する要素。\"remove\" パートの処理後に実行されます。", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "削除する要素。\"add\" パートの処理前に実行されます。", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "許可されるオリジン。ドメインをカンマ区切りのリストで指定します", + "type": "string" + }, + "openApiKeys": { + "description": "サービスのクエリendpointのバージョン", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "ロール", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "招待の作成タイムスタンプ。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "招待されたユーザーのメールアドレス。このメールアドレスを持つユーザーのみが、この招待を使用して参加できます。メールアドレスは小文字で保存されます。", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "招待の有効期限タイムスタンプ。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "一意の招待 ID。", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "組織におけるメンバーのロール。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "招待されたユーザーのメールアドレス。このメールアドレスを持つユーザーのみが招待を使用して参加できます。メールアドレスは小文字で保存されます。", + "format": "email", + "type": "string" + }, + "role": { + "description": "組織におけるメンバーのロール。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "アクセスを許可する IPv4 アドレスまたは IPv4 CIDR の任意の説明", + "type": "string" + }, + "source": { + "description": "IP または CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "追加する要素。\"remove\" パートの処理後に実行されます。", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "削除する要素。\"add\" パートの処理前に実行されます。", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "個人ユーザープロファイルで設定されたメンバーのメールアドレス。", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "メンバーが組織に参加したタイムスタンプ。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "個人ユーザープロファイルで設定されたメンバー名。", + "type": "string" + }, + "role": { + "description": "組織におけるメンバーのロール。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "一意のユーザー ID。ユーザーが複数の組織に所属している場合でも、この ID は変わりません。", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "組織におけるメンバーのロール。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "IAM access key ID。", + "type": "string" + }, + "secretKey": { + "description": "IAM secret key。", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "組織の BYOC configuration", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "組織が作成された timestamp。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "一意の Organization ID。", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "組織名。", + "type": "string" + }, + "privateEndpoints": { + "description": "組織のプライベート エンドポイント一覧", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "AWS（Service Name）または GCP（Target Service）resource を使用して VPC 内に作成した interface endpoint の一意の識別子", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "プライベート エンドポイントが存在するクラウドプロバイダー", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "プライベート エンドポイントの任意の説明", + "type": "string" + }, + "id": { + "description": "プライベート エンドポイント識別子", + "type": "string" + }, + "region": { + "description": "プライベート エンドポイントが存在するリージョン", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "組織名。", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "プライベート エンドポイントが存在するクラウドプロバイダー", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "プライベート エンドポイントの説明", + "type": "string" + }, + "id": { + "description": "プライベート エンドポイント識別子", + "type": "string" + }, + "region": { + "description": "プライベート エンドポイントが存在するリージョン", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "追加する要素。\"remove\" 部分の処理後に実行されます。プライベート エンドポイントを変更する場合は、代わりに `Update Service Basic Details` endpoint を使用してください。", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "削除する要素。\"add\" 部分が処理される前に実行されます。", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "パスワード。", + "type": "string" + }, + "username": { + "description": "ユーザー名。", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "AWS（Service Name）、GCP（Target Service）、または AZURE（Private Link Service）リソースを使用して VPC に作成したインターフェイス エンドポイントの一意の識別子", + "type": "string" + }, + "privateDnsHostname": { + "description": "作成した VPC のプライベート DNS ホスト名", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "リバース プライベート エンドポイントの説明。最大長は 255 文字です。", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "リバース プライベート エンドポイントの内部 DNS 名。", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "リバース プライベート エンドポイントの Endpoint ID。", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "リバース プライベート エンドポイント ID。", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK クラスターの認証タイプ。MSK_MULTI_VPC タイプでは必須です。", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK クラスター ARN。MSK_MULTI_VPC タイプでは必須です。", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "リバース プライベート エンドポイントのプライベート DNS 名。", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "リバース プライベート エンドポイントに関連付けられている ClickHouse サービス ID。", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "リバース プライベート エンドポイントのステータス。", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "リバース プライベート エンドポイントのタイプ。", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC エンドポイントサービス名。", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC リソースの構成 ID。VPC_RESOURCE タイプでは必須です。", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC リソース共有 ARN。VPC_RESOURCE タイプでは必須です。", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "プライベート エンドポイントの説明", + "type": "string" + }, + "id": { + "description": "プライベート エンドポイント識別子", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "サービスにアタッチ可能な利用可能なプライベート エンドポイント ID の一覧", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "これは、Bring Your Own Cloud (BYOC) のリージョン設定後に返される ID です。byocId パラメータを指定する場合は、minReplicaMemoryGb と maxReplicaGb パラメータも必須で、値は次のサイズのいずれかである必要があります: 48、116、172、232。", + "type": "string" + }, + "clickhouseVersion": { + "description": "サービスの ClickHouse バージョン。", + "type": "string" + }, + "complianceType": { + "description": "サービスの規制コンプライアンスの種類。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "サービスの作成タイムスタンプ。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "このサービスを含むデータウェアハウス", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "ディスク暗号化に使用するオプションのロール", + "type": "string" + }, + "encryptionKey": { + "description": "オプションの、お客様が指定するディスク暗号化キー", + "type": "string" + }, + "encryptionRoleId": { + "description": "暗号化に使用する IAM ロールの ID。これは hasTransparentDataEncryption が true の場合にのみ利用できます。", + "type": "string" + }, + "endpoints": { + "description": "すべてのサービスエンドポイントの一覧。", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "サービスで透過的データ暗号化（TDE）を有効にする必要がある場合は True。TDE は ENTERPRISE の組織ティアでのみ利用可能で、サービス作成時にのみ有効にできます。", + "type": "boolean" + }, + "iamRole": { + "description": "S3 内のオブジェクトへのアクセスに使用する IAM ロール", + "type": "string" + }, + "id": { + "description": "一意のサービス ID。", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "true に設定すると、アイドル時にサービスをゼロまでスケールダウンできます。デフォルトでは true です。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "最小アイドルタイムアウトを設定します（分単位）。5 分以上である必要があります。", + "type": "number" + }, + "ipAccessList": { + "description": "サービスへのアクセスを許可する IP アドレスの一覧", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "このサービスがデータウェアハウスのプライマリサービスである場合は True", + "type": "boolean" + }, + "isReadonly": { + "description": "このサービスが読み取り専用である場合は True。読み取り専用にできるのは、dataWarehouseId が指定されている場合のみです。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "自動スケーリング中の各レプリカの最大合計メモリ容量（Gb）。4 の倍数で、無償サービスでは 120* 以下、有償サービスでは 356* 以下である必要があります。* - レプリカの最大サイズは、選択したリージョンで利用可能なクラウドプロバイダーのハードウェアによって異なります。 ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - レプリカ数がデフォルト以外のサービスでは正確ではありません。自動スケーリング中の 3 つのワーカーの最大メモリ容量（Gb）。'production' サービスでのみ使用できます。12 の倍数で、無償サービスでは 360 以下、有償サービスでは 1068 以下である必要があります。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "自動スケーリング中の各レプリカの最小合計メモリ容量（Gb）。4 の倍数で、8 以上である必要があります。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - レプリカ数がデフォルト以外のサービスでは正確ではありません。自動スケーリング中の 3 つのワーカーの最小メモリ容量（Gb）。'production' サービスでのみ使用できます。12 の倍数で、24 以上である必要があります。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "サービス名。英数字と空白を含む 50 文字以内の文字列。", + "type": "string" + }, + "numReplicas": { + "description": "サービスのレプリカ数。データウェアハウス内の最初のサービスでは、レプリカ数は 2 ～ 20 である必要があります。既存のデータウェアハウス内に作成されるサービスでは、レプリカ数は 1 まで設定できます。組織のティアに応じて、さらに制限が適用される場合があります。デフォルトは BASIC ティアでは 1、SCALE および ENTERPRISE ティアでは 3 です。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "プライベート エンドポイントの一覧", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "カスタム インスタンスプロファイル。ENTERPRISE の組織ティアでのみ利用できます。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "クラウドプロバイダー", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "サービスのリージョン。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "新しい ClickHouse releases を利用可能になり次第取得したい場合は fast を選択してください。新機能をより早く利用できますが、バグのリスクは高くなります。テストの時間をより多く確保するために release を遅らせたい場合は slow を選択してください。この機能は production サービスでのみ利用できます。default は通常のリリースチャネルです。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "サービスの現在の状態。", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC、SCALE、および ENTERPRISE の組織ティアでは非推奨。サービスのティア: 'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'、'dedicated_standard_n2d_standard_32_16SSD'、'dedicated_standard_n2d_standard_64_24SSD'。Production サービスはスケーリング可能で、Development は固定サイズです。Azure サービスでは Development ティアはサポートされていません", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "サービスで使用する透過的データ暗号化キーの ID。これは hasTransparentDataEncryption が true の場合にのみ利用できます。", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "サービスのホスト名", + "type": "string" + }, + "port": { + "description": "ポート番号", + "type": "number" + }, + "protocol": { + "description": "エンドポイントのプロトコル: 'https'、'nativesecure'、'mysql'。", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "エンドポイント用の任意のユーザー名", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "エンドポイントを有効または無効にします", + "type": "boolean" + }, + "protocol": { + "description": "エンドポイントのプロトコル", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "MySQL プロトコル用の任意のダブル SHA1 パスワード ハッシュ。newPasswordHash が指定されていない場合、この項目は無視され、生成されたパスワードが使用されます。Algorithm: echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "任意のパスワード ハッシュ。ネットワーク経由でのパスワード送信を避けるために使用されます。指定しない場合は新しいパスワードが生成され、レスポンスで返されます。指定した場合はこのハッシュが使用されます。Algorithm: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "新しいサービス パスワード。リクエストに 'newPasswordHash' がない場合にのみ提供されます", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "変更するサービスエンドポイントの一覧", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "サービス名。空白を含めて最大 50 文字の英数字文字列。", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "新しい ClickHouse リリースを利用可能になり次第すぐに取得したい場合は fast を選択します。新機能をより早く利用できますが、バグのリスクは高くなります。リリースを遅らせてテストの時間をより多く確保したい場合は slow を選択します。この機能は 'production' サービスでのみ利用できます。デフォルトは通常のリリースチャネルです。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "ローテーションするキーの ID", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "新しいサービスの初期状態として使用するオプションのBackup ID。これを使用する場合、新しいインスタンスのリージョンとtierは元のインスタンスの値と同じである必要があります。", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "これは、Bring Your Own Cloud (BYOC) のリージョンを設定した後に返されるIDです。byocId parameter を指定する場合は、minReplicaMemoryGb と maxReplicaGb parameter も必須であり、値は次のサイズのいずれかである必要があります: 48, 116, 172, 232。", + "type": "string" + }, + "complianceType": { + "description": "サービスに対する規制コンプライアンスの種類。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "このサービスを含むデータwarehouse", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "ディスク暗号化に使用するオプションのロール", + "type": "string" + }, + "encryptionKey": { + "description": "オプションのカスタマー提供ディスク暗号化キー", + "type": "string" + }, + "endpoints": { + "description": "有効化または無効化するサービスendpointsの一覧", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "サービスで透過的データ暗号化 (TDE) を有効にする場合は true。TDE は ENTERPRISE の組織tierでのみ利用可能で、サービス作成時にのみ有効化できます。", + "type": "boolean" + }, + "idleScaling": { + "description": "true に設定すると、サービスはアイドル時にゼロまでスケールダウンできます。デフォルトは true です。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "最小アイドルtimeout（分）を設定します。5分以上である必要があります。", + "type": "number" + }, + "ipAccessList": { + "description": "サービスへのアクセスを許可するIPアドレスの一覧", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "このサービスがread-onlyの場合は true。read-only にできるのは、dataWarehouseId が指定されている場合のみです。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "自動スケーリング時の各レプリカの合計最大メモリ量（Gb）。4の倍数で、かつ無償サービスでは120*以下、有償サービスでは356*以下である必要があります。* - レプリカの最大サイズは、選択したリージョンで利用可能なクラウドプロバイダーのハードウェアに依存します。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは正確ではありません。自動スケーリング時の3つのworkerの最大メモリ量（Gb）。'production' サービスでのみ使用できます。12の倍数で、かつ無償サービスでは360以下、有償サービスでは1068以下である必要があります。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "自動スケーリング時の各レプリカの合計最小メモリ量（Gb）。4の倍数で、8以上である必要があります。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは正確ではありません。自動スケーリング時の3つのworkerの最小メモリ量（Gb）。'production' サービスでのみ使用できます。12の倍数で、24以上である必要があります。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "サービス名。50文字以内の英数字と空白を含む文字列。", + "type": "string" + }, + "numReplicas": { + "description": "サービスのレプリカ数。warehouse 内の最初のサービスでは、レプリカ数は 2 ～ 20 である必要があります。既存のwarehouse内に作成されるサービスでは、レプリカ数を1まで下げられます。さらに、組織のtierに応じて追加の制限が適用される場合があります。デフォルトはBASIC tierで1、SCALEおよびENTERPRISE tierで3です。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "サービスをprivate endpointsに関連付けるには、まずサービスを作成してから、`Update Service Basic Details` endpoint を使用してprivate endpointsを変更してください。", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "プライベートプレビューの利用規約に同意します。プライベートプレビューの場合、組織内で最初のサービスを作成するときにのみ必要です", + "type": "boolean" + }, + "profile": { + "description": "カスタムインスタンスプロファイル。ENTERPRISE 組織ティアでのみ利用できます。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "クラウドプロバイダー", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "サービスのリージョン。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "新しいClickHouse releasesを利用可能になり次第すぐに取得したい場合は fast を選択してください。新機能をより早く利用できますが、バグのリスクは高くなります。テストのための時間をより多く確保したい場合は slow を選択してください。この機能は production サービスでのみ利用できます。デフォルトは regular release channel です。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC、SCALE、ENTERPRISE の組織tierでは非推奨。サービスのtier: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'。Productionサービスはスケーリング可能で、Developmentは固定サイズです。AzureのサービスはDevelopment tierをサポートしていません", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "新しく作成したサービスのパスワード。", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "許可されるオリジンを、ドメインのカンマ区切りリストで指定します", + "type": "string" + }, + "id": { + "description": "service query endpoint の ID", + "type": "string" + }, + "openApiKeys": { + "description": "service query endpoint にアクセスできる OpenAPI キーの一覧", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "service query endpoint にアクセスできるロールの一覧", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "true に設定すると、サービスはアイドル時にゼロまでスケールダウンできます。デフォルトは true です。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "最小アイドル タイムアウト（分）を設定します。5 分以上である必要があります。", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "単一レプリカの最大自動スケーリング メモリ（GB）。'production' サービスでのみ利用できます。4 の倍数であり、無償サービスでは 120 以下、有償サービスでは 356 以下である必要があります。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "単一レプリカの最小自動スケーリング メモリ（GB）。'production' サービスでのみ利用できます。4 の倍数かつ 8 以上である必要があります。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "サービスのレプリカ数。ウェアハウス内の最初のサービスでは、レプリカ数は 2 から 20 の間である必要があります。既存のウェアハウス内に作成されるサービスでは、レプリカ数を 1 まで少なくできます。さらに、組織のティアに応じて追加の制限が適用される場合があります。デフォルトは BASIC tier で 1、SCALE and ENTERPRISE tiers で 3 です。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "true に設定すると、サービスはアイドル時にゼロまでスケールダウンできます。デフォルトは true です。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "最小アイドルタイムアウト（分）を設定します。5 分以上である必要があります。", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは不正確です。自動スケーリング中の 3 つのワーカーの最大メモリ容量（Gb）。'production' サービスでのみ利用できます。12 の倍数で、非有料サービスでは 360 以下、有料サービスでは 1068 以下である必要があります。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは不正確です。自動スケーリング中の 3 つのワーカーの最小メモリ容量（Gb）。'production' サービスでのみ利用できます。12 の倍数かつ 24 以上である必要があります。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "サービスのレプリカ数。warehouse 内の最初のサービスでは、レプリカ数は 2 ～ 20 である必要があります。既存の warehouse に作成されるサービスでは、レプリカ数は 1 まで設定できます。さらに、組織のティアに応じて追加の制限が適用される場合があります。デフォルトは BASIC ティアで 1、SCALE および ENTERPRISE ティアで 3 です。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "サービスにアタッチできる利用可能なプライベート エンドポイント ID の一覧", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "これは Bring Your Own Cloud (BYOC) のリージョン設定後に返される ID です。byocId パラメータを指定する場合は、minReplicaMemoryGb パラメータと maxReplicaGb パラメータも必須で、値は次のサイズのいずれかである必要があります: 48、116、172、232。", + "type": "string" + }, + "clickhouseVersion": { + "description": "サービスの ClickHouse バージョン。", + "type": "string" + }, + "complianceType": { + "description": "サービスの規制コンプライアンスの種類。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "サービスの作成タイムスタンプ。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "このサービスが含まれるデータウェアハウス", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "ディスク暗号化に使用するオプションのロール", + "type": "string" + }, + "encryptionKey": { + "description": "オプションの顧客提供ディスク暗号化キー", + "type": "string" + }, + "encryptionRoleId": { + "description": "暗号化に使用される IAM role の ID。hasTransparentDataEncryption が true の場合にのみ利用できます。", + "type": "string" + }, + "endpoints": { + "description": "すべてのサービスエンドポイントの一覧。", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "サービスで透過的データ暗号化 (TDE) を有効にする必要がある場合は true。TDE は ENTERPRISE 組織ティアでのみ利用でき、サービス作成時にのみ有効化できます。", + "type": "boolean" + }, + "iamRole": { + "description": "S3 内のオブジェクトへのアクセスに使用する IAM role", + "type": "string" + }, + "id": { + "description": "一意のサービス ID。", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "true に設定すると、サービスはアイドル時にゼロまでスケールダウンできます。デフォルトは true です。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "最小アイドルタイムアウト（分）を設定します。5 分以上である必要があります。", + "type": "number" + }, + "ipAccessList": { + "description": "サービスへのアクセスを許可する IP アドレスの一覧", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "このサービスがデータウェアハウス内のプライマリ サービスである場合は true", + "type": "boolean" + }, + "isReadonly": { + "description": "このサービスが読み取り専用である場合は true。読み取り専用にできるのは、dataWarehouseId が指定されている場合のみです。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "単一レプリカの最大自動スケーリングメモリ容量（Gb）。'production' サービスでのみ利用できます。4 の倍数で、非有料サービスでは 120 以下、有料サービスでは 356 以下である必要があります。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは不正確です。自動スケーリング中の 3 つのワーカーの最大メモリ容量（Gb）。'production' サービスでのみ利用できます。12 の倍数で、非有料サービスでは 360 以下、有料サービスでは 1068 以下である必要があります。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "単一レプリカの最小自動スケーリングメモリ容量（Gb）。'production' サービスでのみ利用できます。4 の倍数かつ 8 以上である必要があります。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "非推奨 - デフォルト以外のレプリカ数を持つサービスでは不正確です。自動スケーリング中の 3 つのワーカーの最小メモリ容量（Gb）。'production' サービスでのみ利用できます。12 の倍数かつ 24 以上である必要があります。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "サービス名。空白を含めて最大 50 文字の英数字文字列。", + "type": "string" + }, + "numReplicas": { + "description": "サービスのレプリカ数。warehouse 内の最初のサービスでは、レプリカ数は 2 ～ 20 である必要があります。既存の warehouse に作成されるサービスでは、レプリカ数は 1 まで設定できます。さらに、組織のティアに応じて追加の制限が適用される場合があります。デフォルトは BASIC ティアで 1、SCALE および ENTERPRISE ティアで 3 です。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "プライベート エンドポイントの一覧", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "カスタム インスタンス プロファイル。ENTERPRISE 組織ティアでのみ利用できます。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "クラウドプロバイダー", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "サービスのリージョン。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "新しい ClickHouse リリースを利用可能になり次第すぐに取得したい場合は fast を選択します。新機能をより早く利用できますが、バグのリスクは高くなります。テストの時間をより多く確保するためにリリースを遅らせたい場合は slow を選択します。この機能は production サービスでのみ利用できます。default は regular release channel です。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "サービスの現在の状態。", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC、SCALE、ENTERPRISE の組織ティアでは非推奨。サービスのティア: 'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'、'dedicated_standard_n2d_standard_32_16SSD'、'dedicated_standard_n2d_standard_64_24SSD'。Production サービスはスケーリングされ、Development は固定サイズです。Azure のサービスは Development ティアをサポートしていません", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "サービスで使用される透過的データ暗号化キーの ID。hasTransparentDataEncryption が true の場合にのみ利用できます。", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "状態を変更するコマンド: 'start'、'stop'。", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "ClickHouse Credits（CHCs）の使用にかかる総コスト。", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "ClickHouse Credits（CHCs）でのバックアップ コスト。dataWarehouse エンティティに適用されます。", + "type": "number" + }, + "computeCHC": { + "description": "ClickHouse Credits（CHCs）でのコンピュート コスト。service および clickpipe エンティティに適用されます。", + "type": "number" + }, + "dataTransferCHC": { + "description": "ClickHouse Credits（CHCs）でのデータ転送コスト。clickpipe エンティティに適用されます。", + "type": "number" + }, + "initialLoadCHC": { + "description": "ClickHouse Credits（CHCs）での初期ロードおよび再同期のコスト。clickpipe エンティティに適用されます。", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "ClickHouse Credits（CHCs）での tier1 リージョン間データ転送コスト。service エンティティに適用されます。", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "ClickHouse Credits（CHCs）での tier2 リージョン間データ転送コスト。service エンティティに適用されます。", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "ClickHouse Credits（CHCs）での tier3 リージョン間データ転送コスト。service エンティティに適用されます。", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "ClickHouse Credits（CHCs）での tier4 リージョン間データ転送コスト。service エンティティに適用されます。", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "ClickHouse Credits（CHCs）でのデータ転送コスト。service エンティティに適用されます。", + "type": "number" + }, + "storageCHC": { + "description": "ClickHouse Credits（CHCs）でのストレージ コスト。dataWarehouse エンティティに適用されます。", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "このエンティティが属する dataWarehouse の ID（または、このエンティティ自体の ID）。", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "使用量の日付。UTC タイムゾーンに基づく ISO-8601 形式の日付です。", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "エンティティの一意の ID。", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "エンティティの名前。", + "type": "string" + }, + "entityType": { + "description": "エンティティの種別。", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "true の場合、このレコードは不変です。ロック解除されたレコードは、ロックされるまで変更される可能性があります。", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "このエンティティが属する service の ID（または、このエンティティ自体の ID）。dataWarehouse エンティティの場合は null に設定されます。", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "このentityにおける ClickHouse Credits（CHCs）の使用総コスト。", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "ClickHouse Cloud console で取得した key ID と key secret を使用してください: https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "リクエストの API key に関連付けられた単一の組織を含むリストを返します。", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "利用可能な組織一覧を取得", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "単一の組織の詳細を返します。詳細を取得するには、認証キーがその組織に属している必要があります。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーとみなされる何らかの理由により、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織の詳細を取得", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "組織のフィールドを更新します。ADMIN認証キーのロールが必要です。", + "parameters": [ + { + "description": "更新する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーとみなされる何らかの理由により、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織の詳細を更新", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "すべての組織アクティビティの一覧を返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "検索の開始日", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "検索の終了日", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "組織のアクティビティ一覧", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "IDで指定した組織アクティビティを1件返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたアクティビティのID。", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織のアクティビティ", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "組織内に新しい BYOC インフラストラクチャを作成します。新しく作成されたインフラストラクチャの設定を返します", + "parameters": [ + { + "description": "対象の組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "BYOC インフラストラクチャを作成", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "組織から BYOC インフラストラクチャを削除します", + "parameters": [ + { + "description": "対象の組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "対象の BYOC インフラストラクチャの ID", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "BYOC インフラストラクチャを削除", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "すべての組織招待の一覧を返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、serverがリクエストを処理できないか、処理しません。" + } + }, + "summary": "すべての招待を一覧表示", + "tags": [ + "User management" + ] + }, + "post": { + "description": "組織招待を作成します。", + "parameters": [ + { + "description": "ユーザーの招待先となる組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、serverがリクエストを処理できないか、処理しません。" + } + }, + "summary": "招待を作成", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "組織への招待を1件削除します。", + "parameters": [ + { + "description": "招待が属する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求された組織のID。", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "組織への招待を削除", + "tags": [ + "User management" + ] + }, + "get": { + "description": "1件の組織招待の詳細を返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求された組織のID。", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "招待の詳細を取得", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "組織内のすべてのAPI keyの一覧を返します。", + "parameters": [ + { + "description": "対象の組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "server が client error とみなされる何らかの理由により、リクエストを処理できないか、または処理しません。" + } + }, + "summary": "すべてのキーの一覧を取得", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "新しいAPI keyを作成します。", + "parameters": [ + { + "description": "keyを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "server が client error とみなされる何らかの理由により、リクエストを処理できないか、または処理しません。" + } + }, + "summary": "キーを作成", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "APIキーを削除します。現在のリクエストの認証に使用されていないキーのみ削除できます。", + "parameters": [ + { + "description": "キーを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "削除するキーの ID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断されたため、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "キーを削除", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "単一のkeyの詳細を返します。", + "parameters": [ + { + "description": "対象の組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "対象のkeyのID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "server が client error とみなされる何らかの理由により、リクエストを処理できないか、または処理しません。" + } + }, + "summary": "キーの詳細を取得", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "API keyのプロパティを更新します。", + "parameters": [ + { + "description": "keyを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "更新対象のkeyのID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断されたため、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "キーを更新", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "組織内のすべてのメンバーの一覧を返します。", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断されたため、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織メンバーの一覧", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "組織からユーザーを削除します", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたユーザーのID。", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、serverがリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織メンバーを削除", + "tags": [ + "User management" + ] + }, + "get": { + "description": "単一の組織メンバーの詳細を返します。", + "parameters": [ + { + "description": "メンバーが所属する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたユーザーの ID。", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断されたため、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "メンバーの詳細を取得", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "組織メンバーのロールを更新します。", + "parameters": [ + { + "description": "メンバーが所属する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "更新対象のユーザーの ID", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、serverがリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織メンバーを更新", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "非推奨です。更新後の手順については、[documentation](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list) を参照してください。", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "クラウドプロバイダー識別子。aws、gcp、azure のいずれかです。", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "各クラウドプロバイダー内のリージョン識別子。", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーがリクエストを処理できない、または処理しません。" + } + }, + "summary": "組織のクラウドプロバイダー内のリージョンにおけるプライベート エンドポイント設定を取得", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "組織内のすべてのサービスの Prometheus メトリクスを返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "フィルタリングされた Prometheus メトリクスの一覧を返します。", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーとみなされる何らかの理由により、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織のメトリクスを取得", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "組織内のすべてのサービスの一覧を返します。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "resource の取得時に適用するフィルタ条件。現在サポートされているのは、resource タグによるフィルタリングのみです。", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーとみなされる何らかの理由により、サーバーはリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織のサービス一覧", + "tags": [ + "Service" + ] + }, + "post": { + "description": "組織内に新しいserviceを作成し、現在のserviceの状態と、そのserviceにアクセスするためのpasswordを返します。serviceは非同期で開始されます。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorとみなされる何らかの理由により、serverがリクエストを処理できない、または処理しない場合。" + } + }, + "summary": "新しいサービスを作成", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "serviceを削除します。serviceは停止stateである必要があり、このmethodの呼び出し後に非同期で削除されます。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "削除するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTP status code.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "サーバーは、クライアント エラーと見なされる理由により、このリクエストを処理できないか、処理しません。" + } + }, + "summary": "サービスを削除", + "tags": [ + "Service" + ] + }, + "get": { + "description": "組織に属するserviceを返します", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorとみなされる何らかの理由により、serverがリクエストを処理できない、または処理しない場合。" + } + }, + "summary": "サービスの詳細を取得", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "service nameやIP Access Listなど、serviceの基本的な詳細を更新します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "更新するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorとみなされる何らかの理由により、serverがリクエストを処理できない、または処理しない場合。" + } + }, + "summary": "サービスの基本情報を更新", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "service のバックアップ設定を返します。", + "parameters": [ + { + "description": "この service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server がリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスのバックアップ構成を取得", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "service のバックアップ設定を更新します。ADMIN 認証キーのロールが必要です。プロパティに NULL 値を設定すると、そのプロパティはデフォルト値にリセットされます。", + "parameters": [ + { + "description": "この service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server がリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスのバックアップ構成を更新", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "service のすべての backups の一覧を返します。一覧では最新の backups が先頭に表示されます。", + "parameters": [ + { + "description": "backup を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "backup の作成元である service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server がリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスのバックアップ一覧", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "単一のバックアップ情報を返します。", + "parameters": [ + { + "description": "このバックアップを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "このバックアップの作成元である service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたバックアップの ID。", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server がリクエストを処理できないか、または処理しません。" + } + }, + "summary": "バックアップの詳細を取得", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**このendpointはベータです。** APIコントラクトはstableで、今後breaking changesが発生することは想定されていません。

ClickPipesの一覧を返します。", + "parameters": [ + { + "description": "service を所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有する service のID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "ClickPipes を一覧表示", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**このendpointはベータです。** APIコントラクトはstableで、今後breaking changesが発生することは想定されていません。

新しいClickPipeを作成します。", + "parameters": [ + { + "description": "service を所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe の作成先となる service のID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "ClickPipe を作成", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後互換性を損なう変更が行われる予定はありません。

指定したClickPipeを削除します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipeを所有するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "削除するClickPipeのID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "ClickPipe を削除", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後互換性を損なう変更が行われる予定はありません。

指定したClickPipeを返します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipeを所有するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたClickPipeのID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "ClickPipe を取得", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後互換性を損なう変更が行われる予定はありません。

指定したClickPipeを更新します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipeの作成先となるserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたClickPipeのID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "errorの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client errorと判断される何らかの理由により、serverがリクエストを処理できないか、または処理しません。" + } + }, + "summary": "ClickPipe を更新", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**この endpoint はベータです。** API コントラクトは安定しており、今後 breaking changes が発生することは想定されていません。

指定した ClickPipe の scaling 設定を変更します。", + "parameters": [ + { + "description": "サービスを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "scaling 設定の更新対象となる ClickPipe の ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "ClickPipe のスケーリング", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後互換性を損なう変更が行われる予定はありません。

指定したClickPipeのadvanced settingsを返します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "設定の取得対象となる ClickPipe の ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "ClickPipe の設定を取得", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**この endpoint はベータです。** API コントラクトは安定しており、今後 breaking changes が発生することは想定されていません。

指定した ClickPipe の advanced settings を更新します。値として String、数値、またはブール値を指定できるキー・バリューのペアを送信します。", + "parameters": [ + { + "description": "サービスを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "設定の更新対象となる ClickPipe の ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "ClickPipe の設定を更新", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**この endpoint はベータです。** API コントラクトは安定しており、今後 breaking changes が発生することは想定されていません。

ClickPipe の開始、停止、または再同期を行います。ClickPipe を停止すると、どの state であってもインジェスト処理が停止します。開始できるのは、\"Stopped\" state または \"Failed\" state の ClickPipes のみです。再同期は Postgres パイプでのみ使用でき、どの state からでも実行できます。", + "parameters": [ + { + "description": "サービスを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "state の更新対象となる ClickPipe の ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーがリクエストを処理できない、または処理しません。" + } + }, + "summary": "ClickPipe の状態を更新", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**このエンドポイントはベータです。** API コントラクトは安定しており、今後破壊的変更が発生することは想定されていません。

DB ClickPipes のスケーリング設定を取得します。\n\nインフラストラクチャは、初期ロードと CDC の両方について、サービス内のすべての DB ClickPipes で共有されます。課金上は、2 CPU コアと 8 GB の RAM が 1 コンピュートユニットに[相当します](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc)。\n\n**このエンドポイントは、少なくとも 1 つの DB ClickPipe がプロビジョニングされると利用可能になります。**", + "parameters": [ + { + "description": "サービスを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーがリクエストを処理できない、または処理しません。" + } + }, + "summary": "CDC ClickPipes のスケーリングを取得", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**このエンドポイントはベータです。** API コントラクトは安定しており、今後破壊的変更が発生することは想定されていません。

DB ClickPipes のスケーリング設定を更新します。\n\nインフラストラクチャは、初期ロードと CDC の両方について、サービス内のすべての DB ClickPipes で共有されます。スケーリング設定が完全に反映されるまで、数分かかる場合があります。\n\n課金上は、2 CPU コアと 8 GB の RAM が 1 コンピュートユニットに[相当します](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc)。組織 tier が変更された場合、DB ClickPipes は適切に[再スケーリング](https://clickhouse.com/docs/cloud/manage/billing/overview#compute)されます。\n\n**このエンドポイントは、少なくとも 1 つの DB ClickPipe がプロビジョニングされると利用可能になります。**", + "parameters": [ + { + "description": "サービスを所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe を所有するサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功レスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTP ステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーがリクエストを処理できない、または処理しません。" + } + }, + "summary": "CDC ClickPipes のスケーリングを更新", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**この endpoint はベータです。** API コントラクトは安定しており、今後 breaking changes が発生することはない見込みです。

指定した service の Reverse Private Endpoint の一覧を返します。", + "parameters": [ + { + "description": "service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpoint を所有する service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "Reverse Private Endpoint を一覧表示", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**この endpoint はベータです。** API コントラクトは安定しており、今後 breaking changes が発生することはない見込みです。

新しい Reverse Private Endpoint を作成します。", + "parameters": [ + { + "description": "service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpoint を所有する service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "Reverse Private Endpoint を作成", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後breaking changesが発生することはない見込みです。

指定したIDのreverse private endpointを削除します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpointを所有するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "削除するreverse private endpointのID。", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "Reverse Private Endpoint を削除", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**このendpointはベータです。** APIコントラクトは安定しており、今後breaking changesが発生することはない見込みです。

指定したIDのReverse Private Endpointを返します。", + "parameters": [ + { + "description": "serviceを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpointを所有するserviceのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "取得するreverse private endpointのID。", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なerrorの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアント エラーと判断される何らかの理由により、server がリクエストを処理できない、または処理しません。" + } + }, + "summary": "Reverse Private Endpoint を取得", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "service の新しい password を設定します", + "parameters": [ + { + "description": "service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "password を更新する service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client error と見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "サービスのパスワードを更新", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "新しいプライベート エンドポイントを作成します。このプライベート エンドポイントは、この service と組織に関連付けられます", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求された service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client error と見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "プライベート エンドポイントを作成", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "プライベート エンドポイントの設定に必要な情報", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "HTTP status code.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTP status code.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "サーバーは、クライアント エラーと見なされる理由により、このリクエストを処理できないか、処理しません。" + } + }, + "summary": "プライベート エンドポイントの構成を取得", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "service の Prometheus メトリクスを返します。", + "parameters": [ + { + "description": "service を所有する組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求された service の ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "フィルタリングされた Prometheus メトリクスの一覧を返します。", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "client error と見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "サービスのメトリクスを取得", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "サービスの各レプリカあたりの最小および最大メモリ制限と、アイドルモード時のスケーリング動作を更新します。メモリ設定は\"production\"サービスでのみ利用可能で、8GB以上かつ4GB単位で指定する必要があります。numReplicasの調整を有効にするには、サポートにお問い合わせください。", + "parameters": [ + { + "description": "サービスを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "スケーリングパラメータを更新するサービスのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラー説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーはリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスの自動スケーリング設定を更新", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "サービスの最小および最大の合計メモリ制限と、アイドルモード時のスケーリング動作を更新します。メモリ設定は\"production\"サービスでのみ利用可能で、24GB以上かつ12GB単位で指定する必要があります。numReplicasの調整を有効にするには、サポートにお問い合わせください。", + "parameters": [ + { + "description": "サービスを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "スケーリングパラメータを更新するサービスのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーはリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスの自動スケーリング設定を更新", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "これは Experimental 機能です。有効にするにはサポートにお問い合わせください。", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP status code.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTP status code.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "サーバーは、クライアント エラーと見なされる理由により、このリクエストを処理できないか、処理しません。" + } + }, + "summary": "指定したインスタンスのサービスのクエリ エンドポイントを削除", + "tags": [ + "Service" + ] + }, + "get": { + "description": "これは Experimental 機能です。有効にするにはサポートにお問い合わせください。", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたサービスの ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意の ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTP status code.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTP status code.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "サーバーは、クライアント エラーと見なされる理由により、このリクエストを処理できないか、処理しません。" + } + }, + "summary": "指定したインスタンスのサービスのクエリ エンドポイントを取得", + "tags": [ + "Service" + ] + }, + "post": { + "description": "これは Experimental 機能です。有効にするにはサポートにお問い合わせください。", + "parameters": [ + { + "description": "要求された組織の ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要求されたサービスのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーはリクエストを処理できないか、または処理しません。" + } + }, + "summary": "指定したインスタンスのサービスのクエリ エンドポイントをupsert", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "サービスを開始または停止します", + "parameters": [ + { + "description": "サービスを所有する組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "状態を更新するサービスのID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "正常なレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "エラーの詳細な説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと判断される何らかの理由により、サーバーはリクエストを処理できないか、または処理しません。" + } + }, + "summary": "サービスの状態を更新", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "照会した期間内の組織について、合計額と、組織内の各entityごとの日次Usageコストレコード一覧を返します（最大31日間）。リクエストとレスポンスの両方におけるすべての日付は、UTC timezone に基づいて評価されます。", + "parameters": [ + { + "description": "要求された組織のID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "レポートの開始日。例: 2024-12-19。", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "レポートの終了日（この日を含む）。例: 2024-12-20。この日付は from_date から30日を超えることはできません（照会可能な最大期間は31日間）。", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "各リクエストに割り当てられる一意のID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功時のレスポンス" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "詳細なエラーの説明。", + "type": "string" + }, + "status": { + "description": "HTTPステータスコード。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "クライアントエラーと見なされる何らかの理由により、server はリクエストを処理できないか、処理しません。" + } + }, + "summary": "組織の利用料金を取得", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/ja/_specs/hyperdx-openapi.json b/ja/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..85731e1a1 --- /dev/null +++ b/ja/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "データに使用する集計関数", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "集計するフィールド", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "結果のグループ化に使用するフィールド", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "metricデータのType", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "Metric名（metricデータソース用）", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "このseriesのデータソースID", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "Luceneクエリ構文でのフィルタ条件", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "WHERE clauseで使用するクエリ言語", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "groupByが指定されている場合のグループ化の値", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "1番目のseriesの値", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "2番目のseriesの値", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "データポイントのtimestamp（bucket開始時刻）", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "終了timestamp（Milliseconds）", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "集計の時間bucketサイズ", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "series設定のArray", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "返されるデータのフォーマット", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "開始timestamp（Milliseconds）", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "HyperDX のアラートとダッシュボードを管理する API", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "認証済みのチームにあるすべてのアラートの一覧を取得します", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "アラートの一覧", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "アラートを正常に取得しました" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていません" + } + }, + "summary": "アラートを一覧表示", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "新しいアラートを作成します", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "タイルベースのアラートを作成", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "アラートを正常に作成しました" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていません" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "サーバーエラーまたは検証エラー" + } + }, + "summary": "アラートを作成", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "アラートを削除します", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "アラートID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "アラートを正常に削除しました" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていない" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "アラートが見つかりません" + } + }, + "summary": "アラートを削除", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "IDで特定のアラートを取得します", + "operationId": "getAlert", + "parameters": [ + { + "description": "アラートID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "単一アラートのレスポンス", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "アラートを正常に取得しました" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていない" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "アラートが見つかりません" + } + }, + "summary": "アラートを取得", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "既存のアラートを更新します", + "operationId": "updateAlert", + "parameters": [ + { + "description": "アラートID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "アラートのプロパティを更新", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "アラートを正常に更新しました" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていない" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "アラートが見つかりません" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "サーバーエラーまたは検証エラー" + } + }, + "summary": "アラートを更新", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "設定された系列パラメータに基づいて時系列データを取得します", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "基本的な時系列クエリ", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "メトリクスの時系列", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "GROUP BY を使用した複数系列", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "複数のログソースからの系列", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "グループ化された時系列データ", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "時系列データポイント", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "時系列データを正常に取得しました" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "リクエストパラメータが無効です" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "認証されていません" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "ログソースが見つかりません" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "サーバーエラー" + } + }, + "summary": "チャートの時系列データをクエリ", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "認証済みのチームにあるすべてのダッシュボードの一覧を取得します", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "ダッシュボードを正常に取得しました" + }, + "401": { + "description": "認証されていません" + } + }, + "summary": "ダッシュボードを一覧表示", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "新しいダッシュボードを作成します", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "複数のチャートタイプを含むダッシュボード", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "時系列チャートを含むダッシュボード", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "ダッシュボード作成時のレスポンス", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "ダッシュボードを正常に作成しました" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていません" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "サーバーエラーまたは検証エラー" + } + }, + "summary": "ダッシュボードを作成", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "ダッシュボードを削除します", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "ダッシュボード ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "ダッシュボードを正常に削除しました" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていない" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "ダッシュボードが見つかりません" + } + }, + "summary": "ダッシュボードを削除", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "IDで指定したダッシュボードを取得します", + "operationId": "getDashboard", + "parameters": [ + { + "description": "ダッシュボードID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "単一ダッシュボードのレスポンス", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "ダッシュボードを正常に取得しました" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていません" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "ダッシュボードが見つかりません" + } + }, + "summary": "ダッシュボードを取得", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "既存のダッシュボードを更新します", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "ダッシュボードID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "ダッシュボードのプロパティとタイルを更新", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "更新後のダッシュボードのレスポンス", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "ダッシュボードを正常に更新しました" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "認証されていません" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "ダッシュボードが見つかりません" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "サーバーエラーまたは検証エラー" + } + }, + "summary": "ダッシュボードを更新", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "本番 API サーバー", + "url": "https://api.hyperdx.io" + }, + { + "description": "現在のサーバー", + "url": "/" + } + ], + "tags": [ + { + "description": "ダッシュボードとその可視化を管理するエンドポイント", + "name": "Dashboards" + }, + { + "description": "監視アラートを管理するエンドポイント", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/ja/clickstack/features/dashboards/overview.mdx b/ja/clickstack/features/dashboards/overview.mdx index 5621d4f61..278884362 100644 --- a/ja/clickstack/features/dashboards/overview.mdx +++ b/ja/clickstack/features/dashboards/overview.mdx @@ -59,10 +59,14 @@ HyperDX の **Chart Explorer** インターフェイスでは、メトリクス イベントは SQL の `WHERE` 句または Lucene 構文のいずれかを使ってフィルタでき、イベントを可視化する時間範囲も設定できます。複数の系列にも対応しています。 - たとえば、フィルタ `ServiceName:\"frontend\"` を追加して、サービス `frontend` でフィルタします。さらに、`Add Series` をクリックして、エイリアス `Count` を持つ時系列のイベント件数の 2 つ目の系列を追加します。 + たとえば、フィルタ `ServiceName:"frontend"` を追加して、サービス `frontend` でフィルタします。さらに、`Add Series` をクリックして、エイリアス `Count` を持つ時系列のイベント件数の 2 つ目の系列を追加します。 シンプルな可視化 2 + 既存の系列に似た系列を作成するには、最初から作成する代わりに複製できます。系列行のコピーアイコン (`Duplicate series`) をクリックすると、そのすぐ下にコピーが挿入されます。コピーには、メトリクス、カラム、フィルタなど、元の系列の設定が保持されます。その後、異なるフィールド (たとえば集計) だけを変更し、コピーに固有のエイリアスを付けます。複製は、複数の系列がサポートされている場所であればどこでも利用できます。`Number`、`Pie`、`Heatmap` など、1 つの系列しか許可しない可視化タイプでは表示されません。 + + チャート系列の行にある Duplicate series コピーアイコンとそのツールチップ + 可視化は、メトリクス、トレース、ログなど、任意のデータソースから作成できます。ClickStack はこれらすべてをワイドイベントとして扱います。任意の **numeric column** を時系列でチャート化でき、**string**、**date**、または **numeric** のカラムをグループ化に使用できます。 diff --git a/ja/clickstack/ingesting-data/collector.mdx b/ja/clickstack/ingesting-data/collector.mdx index d85825921..f84f5c7e6 100644 --- a/ja/clickstack/ingesting-data/collector.mdx +++ b/ja/clickstack/ingesting-data/collector.mdx @@ -104,7 +104,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき - 対象の ClickHouse インスタンスは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME`、`CLICKHOUSE_PASSWORD` を使用して設定します。`CLICKHOUSE_ENDPOINT` には、プロトコルとポートを含む完全な ClickHouse Cloud HTTP エンドポイントを指定してください (例: `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`) 。 + 対象の ClickHouse インスタンスは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER`、`CLICKHOUSE_PASSWORD` を使用して設定します。`CLICKHOUSE_ENDPOINT` には、プロトコルとポートを含む完全な ClickHouse Cloud HTTP エンドポイントを指定してください (例: `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`) 。 Managed ClickStack の認証情報の取得方法については、[こちら](/ja/products/cloud/guides/sql-console/connection-details)を参照してください。 @@ -118,7 +118,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき #### Managed ClickStack インスタンスの設定 - OpenTelemetry collectorは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME`、`CLICKHOUSE_PASSWORD` を通じて、Managed ClickStack インスタンスを使用するよう設定できます。これらの設定方法は、デプロイメント方法によって異なります。 + OpenTelemetry collectorは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER`、`CLICKHOUSE_PASSWORD` を通じて、Managed ClickStack インスタンスを使用するよう設定できます。これらの設定方法は、デプロイメント方法によって異なります。 @@ -162,7 +162,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき Docker Composeを使用する場合は、上記と同じ環境変数を使用してcollectorのconfigurationを変更します。 ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # health_check 拡張機能 - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # メトリクス拡張機能 + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,7 +261,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき - 対象の ClickHouse インスタンスは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME`、`CLICKHOUSE_PASSWORD` で設定します。`CLICKHOUSE_ENDPOINT` には、プロトコルとポートを含む完全な ClickHouse HTTP エンドポイントを指定します (例: `http://localhost:8123`) 。 + 対象の ClickHouse インスタンスは、環境変数 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER`、`CLICKHOUSE_PASSWORD` で設定します。`CLICKHOUSE_ENDPOINT` には、プロトコルとポートを含む完全な ClickHouse HTTP エンドポイントを指定します (例: `http://localhost:8123`) 。 **これらの環境変数は、コネクタを含むすべてのDockerディストリビューションで使用できます。** @@ -275,7 +275,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき #### ClickHouseインスタンスの設定 - OpenTelemetry collectorは、環境変数`OPAMP_SERVER_URL`、`CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME`、`CLICKHOUSE_PASSWORD`を通じてClickHouseインスタンスを使用するよう設定できます。これらの設定方法はデプロイメント方法によって異なります。 + OpenTelemetry collectorは、環境変数`OPAMP_SERVER_URL`、`CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER`、`CLICKHOUSE_PASSWORD`を通じてClickHouseインスタンスを使用するよう設定できます。これらの設定方法はデプロイメント方法によって異なります。 @@ -322,7 +322,7 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき Docker Composeを使用する場合は、上記と同じ環境変数を使用してcollectorのconfigurationを変更します。 ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ OpenTelemetry collector は、主に次の 2 つの役割でデプロイでき CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # health_check 拡張機能 - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # メトリクス拡張機能 + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/ja/clickstack/mcp.mdx b/ja/clickstack/mcp.mdx index 17dd67378..47996f634 100644 --- a/ja/clickstack/mcp.mdx +++ b/ja/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'ClickStack MCPサーバー' sidebarTitle: 'MCPサーバー' description: 'Model Context Protocol（MCP）サーバーを使用して、AIアシスタントをClickStackに接続します' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'オブザーバビリティ', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'オブザーバビリティ', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -23,108 +23,218 @@ MCPサーバーは、以下の ClickStack のデプロイ形態で利用でき | ------------------------------------------------- | ------- | | **Open Source ClickStack** | 利用可能 | | **BYOC (Bring Your Own Cloud)** | 利用可能 | -| **Managed ClickStack** | 近日提供予定 | +| **ClickStack on ClickHouse Cloud** | 利用可能 | | **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | サポート対象外 | - - **Managed ClickStack** + + **ClickHouse Cloud と OSS/BYOC ではセットアップが異なります** - Managed ClickStack 向けの MCPサーバーサポートは現在鋭意開発中で、まもなく利用可能になる予定です。このページの手順は、Open Source および BYOC のデプロイメントに適用されます。 - + ClickStack on ClickHouse Cloud は、Open Source と BYOC のデプロイメントとは異なるエンドポイントと認証方式を使用します。Cloud 固有のセットアップについては、以下の [ClickStack on ClickHouse Cloud](#managed-clickstack) セクションを参照してください。 + -
- ## 前提条件 +
+ ## ClickStack on ClickHouse Cloud
-MCPクライアント を接続する前に、以下が必要です。 +ClickStack on ClickHouse Cloud は、Cloud MCP エンドポイント `https://mcp.clickhouse.cloud/clickstack` 経由で接続し、OAuth 2.0 で認証します。このエンドポイントでは API key 認証はサポートされていません。 -* 稼働中の ClickStack インスタンス (セットアップ方法については [デプロイメント](/ja/clickstack/deployment/overview) を参照してください) -* **Personal API Access Key** — HyperDX の **Team Settings → API Keys → Personal API Access Key** で確認できます +
+ ### 前提条件 +
-Team Settings 内の Personal API Access Key +* [ClickStack が有効になっている](/ja/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud)稼働中の ClickHouse Cloud サービス +* サービスで [MCP を有効にする](/ja/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) — Cloud コンソールを開き、**Connect** をクリックして **Connect with MCP** を選択し、トグルをオンにします - - Personal API Access Key は、Team Settings にある **インジェスト API key** とは異なります。インジェスト API key は、OpenTelemetry Collector に送信されるテレメトリー データの認証に使用されます。 - +
+ ### エンドポイント +
+ +```text +https://mcp.clickhouse.cloud/clickstack +``` -
- ## エンドポイント +認証には OAuth 2.0 を使用します。MCP client が初めて接続する際に、ClickHouse Cloud の認証情報でサインインするためのブラウザウィンドウが開きます。API key は必要ありません。 + +
+ ### MCP client の接続
-MCPサーバーは、ClickStack のフロントエンドURLの `/api/mcp` パスで利用できます。 +各クライアントは、初回接続時に OAuth フローを自動的に処理します。 -たとえば、デフォルトのローカルデプロイメントでは次のようになります。 + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -デフォルト設定を変更している場合は、`localhost:8080` をご利用のインスタンスのホスト名とポートに置き換えてください。 + Claude Code を起動して `/mcp` を実行し、`clickstack-cloud` を選択して OAuth フローを完了します。 + - - このページの例では、フロントエンドアプリのURL (デフォルトではポート `8080`) を使用しています。MCPサーバーには、バックエンド経由で `/mcp` に直接アクセスすることもできますが、すべてのデプロイメントでバックエンドが公開されているわけではないため、このドキュメントではフロントエンドのパスを使用しています。 - + + 以下を `.cursor/mcp.json` に追加します。 -MCPサーバーは、**Bearer token** 認証で **Streamable HTTP** トランスポートを使用します。 + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 以下を `.vscode/mcp.json` に追加します。 + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 以下を `opencode.json` に追加します。 + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + OAuth に対応した **Streamable HTTP** をサポートする任意の MCP client から接続できます。次のように設定します。 -
- ## MCPクライアント の接続 + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### 特定のサービスを指定する
-以下の例では、一般的な MCPクライアント の設定方法を紹介します。`` はご利用のインスタンスの URL (例: `http://localhost:8080`) に、`` はお使いの Personal API Access Key に置き換えてください。 +`x-service-id` ヘッダーがない場合、リクエストの送信先は、アカウントで最初にプロビジョニングされ使用されている ClickStack サービスにデフォルト設定されます。別のサービスを指定するには、MCP client の設定で `x-service-id: ` をヘッダーとして渡してください。 -
- ### Claude code +
+ ## Open Source と BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +Open Source および BYOC のデプロイメントでは、ClickStack インスタンスに組み込まれた MCP エンドポイントを Bearer トークン認証で使用します。 -
- ### Cursor +
+ ### 前提条件
-プロジェクトの `.cursor/mcp.json` または Cursor のグローバル設定に、以下を追加します。 +* 稼働中の ClickStack インスタンス (セットアップ方法については [デプロイメント](/ja/clickstack/deployment/overview) を参照してください) +* **Personal API Access Key** — HyperDX の **Team Settings → API Keys → Personal API Access Key** で確認できます -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Team Settings 内の Personal API Access Key + + + Personal API Access Key は、Team Settings にある **インジェスト API key** とは異なります。インジェスト API key は、OpenTelemetry Collector に送信されるテレメトリー データの認証に使用されます。 + -
- ### OpenCode +
+ ### エンドポイント
-`opencode.json` の設定に以下を追加します。 +MCPサーバーは、ClickStack のフロントエンドURLの `/api/mcp` パスで利用できます。たとえば、デフォルトのローカルデプロイメントでは、URLは `http://localhost:8080/api/mcp` です。デフォルト設定を変更している場合は、`localhost:8080` をご利用のインスタンスのホスト名とポートに置き換えてください。 -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + このページの例では、フロントエンドアプリのURL (デフォルトではポート `8080`) を使用しています。MCPサーバーには、バックエンド経由で `/mcp` に直接アクセスすることもできますが、すべてのデプロイメントでバックエンドが公開されているわけではないため、このドキュメントではフロントエンドのパスを使用しています。 + + +MCPサーバーは、**Bearer token** 認証で **Streamable HTTP** トランスポートを使用します。 -
- ### その他のクライアント +
+ ### MCP client の接続
-**Streamable HTTP** トランスポートに対応した MCPクライアント であれば接続できます。次のように設定してください。 +`` はインスタンス URL (例: `http://localhost:8080`) に、`` は Personal API Access Key に置き換えてください。 + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + 以下を `.cursor/mcp.json` に追加します。 + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + 以下を `.vscode/mcp.json` に追加します。 + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + 以下を `opencode.json` に追加します。 + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + **Streamable HTTP** をサポートする任意の MCP client で接続できます。次のように設定してください。 -* **URL:** `/api/mcp` -* **ヘッダー:** `Authorization: Bearer ` + * **URL:** `/api/mcp` + * **ヘッダー:** `Authorization: Bearer ` + +
## MCP でできること @@ -143,17 +253,42 @@ claude mcp add --transport http hyperdx /api/mcp \ 利用できるツールの内容は、今後拡張される可能性があります。MCP client は接続時に利用可能なツールを自動的に検出します。
- ## 複数チームでの利用 + ## 複数チームでの利用 (OSS/BYOC)
+これは Open Source と BYOC のデプロイメントにのみ適用されます。ClickStack on ClickHouse Cloud については、[特定のサービスを対象にする](#managed-service-override) を参照してください。 + デフォルトでは、MCP リクエストはプライマリ チームのコンテキストで処理されます。複数のチームに所属している場合は、`Authorization` ヘッダーに加えて、チーム ID を設定した `x-hdx-team` ヘッダーを渡すことで、特定のチームを対象にできます。このヘッダーを省略すると、プライマリ チームが使用されます。所属していないチームを指定した場合、リクエストは `401` エラーで拒否されます。 -アクセス可能なチームと現在アクティブなチームを確認するには、MCPクライアント のチーム一覧ツールを使用してください。 +アクセス可能なチームと現在アクティブなチームを確認するには、MCP client のチーム一覧ツールを使用してください。
## トラブルシューティング
+
+ ### ClickStack on ClickHouse Cloud +
+ + + * 使用している MCP client が OAuth 2.0 をサポートしていることを確認してください。Bearer token または stdio transport のみをサポートする client は、Cloud エンドポイントでは認証できません。 + * ブラウザーが OAuth のポップアップやリダイレクトをブロックしていないか確認してください。 + * 使用している ClickHouse Cloud アカウントが、その組織とサービスにアクセスできることを確認してください。 + + + + * 汎用の Cloud MCP エンドポイント (`https://mcp.clickhouse.cloud/mcp`) ではなく、ClickStack エンドポイント (`https://mcp.clickhouse.cloud/clickstack`) を使用していることを確認してください。 + * Cloudコンソールで、そのサービスに対して [MCP が有効になっている](/ja/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) ことを確認してください。 + + + + `x-service-id` ヘッダーがない場合、リクエストは、アカウントで最初にプロビジョニングされ使用された ClickStack サービスにデフォルトで送られます。特定のサービスを対象にするには、このヘッダーを指定してください。[特定のサービスを指定する](#managed-service-override) を参照してください。 + + +
+ ### Open Source と BYOC +
+ * **Personal API Access Key** を使用していることを確認してください (インジェスト API key ではありません) 。 * `Authorization` ヘッダーに、`Bearer` トークンとしてキーが含まれていることを確認してください。 @@ -169,7 +304,7 @@ claude mcp add --transport http hyperdx /api/mcp \ - * 使用している MCPクライアントが **Streamable HTTP** トランスポートをサポートしていることを確認してください。stdio トランスポートのみをサポートする古いクライアントは動作しません。 + * 使用している MCP client が **Streamable HTTP** トランスポートをサポートしていることを確認してください。stdio トランスポートのみをサポートする古いクライアントは動作しません。 * ClickStack をローカルで実行している場合は、設定した URL でアプリにアクセスできることを確認してください (デフォルトは `http://localhost:8080` です) 。 * ロードバランサーまたはリバースプロキシの背後で BYOC デプロイメントを実行している場合は、`/api/mcp` パスがブロックまたは書き換えされていないことを確認してください。 \ No newline at end of file diff --git a/ja/clickstack/navigation.json b/ja/clickstack/navigation.json index e36114ff5..eba2559c1 100644 --- a/ja/clickstack/navigation.json +++ b/ja/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "ja/_specs/hyperdx-openapi.json", "root": "ja/clickstack/api-reference" } ] diff --git a/ja/concepts/features/operations/update/replacing-merge-tree.mdx b/ja/concepts/features/operations/update/replacing-merge-tree.mdx index 3453aadd8..929279328 100644 --- a/ja/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/ja/concepts/features/operations/update/replacing-merge-tree.mdx @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --ランダムな100行を選択 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --ランダムな100行を選択 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -上記の操作の結果は 16,000 行、つまり 10,000 + 5000 + 1000 になります。ここで正しい合計は、実際には元の合計より 1000 行少ないだけなので、10,000 - 1000 = 9000 です。 +上記の操作の結果は 16,000 行、つまり 10,000 + 5000 + 1000 になります。実際には、元の合計より 1000 行少ないだけなので、10,000 - 1000 = 9000 であるはずです。 ```sql SELECT count() @@ -207,10 +207,10 @@ FROM posts_updateable ┌─count()─┐ │ 10000 │ └─────────┘ -1 行、セット内。経過時間: 0.002 秒。 +1 row in set. Elapsed: 0.002 sec. ``` -ここでの結果は、発生しているマージの状況によって異なります。重複した行があるため、合計値が異なっていることがわかります。テーブルに `FINAL` を適用すると、正しい結果が得られます。 +結果は、発生しているマージの状況によって異なります。重複した行があるため、合計値が異なっていることがわかります。テーブルに `FINAL` を適用すると、正しい結果が得られます。 ```sql SELECT count() @@ -342,11 +342,11 @@ ClickHouseのマージ選択メカニズムは、単にパーツをマージす ### 大きなパーツにおけるマージ動作
-ClickHouse の ReplacingMergeTree エンジンは、データパーツをマージして重複する行を管理し、指定した一意キーに基づいて各行の最新バージョンのみを保持するよう最適化されています。ただし、マージ後のパーツが `max_bytes_to_merge_at_max_space_in_pool` のしきい値に達すると、`min_age_to_force_merge_seconds` が設定されていても、以降のマージ対象には選ばれなくなります。その結果、継続的なデータ挿入に伴って蓄積する可能性がある重複の除去を、自動マージに頼ることはできなくなります。 +ClickHouse の ReplacingMergeTree エンジンは、パーツをマージして重複する行を管理し、指定した一意キーに基づいて各行の最新バージョンのみを保持するよう最適化されています。ただし、マージ後のパーツが `max_bytes_to_merge_at_max_space_in_pool` のしきい値に達すると、`min_age_to_force_merge_seconds` が設定されていても、以降のマージ対象には選ばれなくなります。その結果、継続的なデータ挿入に伴って蓄積する可能性がある重複の除去を、自動マージに頼ることはできなくなります。 これに対処するには、`OPTIMIZE FINAL` を実行して、パーツを手動でマージし、重複を削除できます。自動マージとは異なり、`OPTIMIZE FINAL` は `max_bytes_to_merge_at_max_space_in_pool` のしきい値を回避し、利用可能なリソース、特にディスク容量のみに基づいてパーツをマージし、各パーティションでパーツが 1 つだけ残るまで処理を進めます。ただし、この方法は大規模なテーブルではメモリ消費が大きくなる可能性があり、新しいデータが追加されるたびに繰り返し実行が必要になる場合があります。 -パフォーマンスを維持しつつ、より持続可能な解決策とするには、テーブルのパーティション化を推奨します。これにより、データパーツがマージの最大サイズに達するのを防ぎやすくなり、継続的な手動最適化の必要性も減らせます。 +パフォーマンスを維持しつつ、より持続可能な解決策とするには、テーブルのパーティション化を推奨します。これにより、パーツがマージの最大サイズに達するのを防ぎやすくなり、継続的な手動最適化の必要性も減らせます。
### パーティション化とパーティションをまたぐマージ @@ -358,11 +358,11 @@ ReplacingMergeTree でパーティションを活用するで説明したよう ### クエリパフォーマンスを向上させるためのマージの調整
-デフォルトでは、min_age_to_force_merge_seconds と min_age_to_force_merge_on_partition_only はそれぞれ 0 と false に設定されており、これらの機能は無効です。この構成では、ClickHouse はパーティションの経過時間に基づいてマージを強制せず、標準のマージ動作を適用します。 +デフォルトでは、`min_age_to_force_merge_seconds` と `min_age_to_force_merge_on_partition_only` はそれぞれ 0 と false に設定されており、これらの機能は無効です。この構成では、ClickHouse はパーティションの経過時間に基づいてマージを強制せず、標準のマージ動作を適用します。 -min_age_to_force_merge_seconds に値を指定すると、ClickHouse は指定した期間より古いパーツに対して、通常のマージヒューリスティクスを無視します。これは一般に、パーツの総数を最小限に抑えることが目的の場合にのみ効果的ですが、ReplacingMergeTree ではクエリ実行時にマージ対象となるパーツ数を減らすことで、クエリパフォーマンスの向上につながる場合があります。 +`min_age_to_force_merge_seconds` に値を指定すると、ClickHouse は指定した期間より古いパーツに対して、通常のマージヒューリスティクスを無視します。これは一般に、パーツの総数を最小限に抑えることが目的の場合にのみ効果的ですが、ReplacingMergeTree ではクエリ実行時にマージ対象となるパーツ数を減らすことで、クエリパフォーマンスの向上につながる場合があります。 -この挙動は、min_age_to_force_merge_on_partition_only=true を設定することでさらに調整できます。この設定では、積極的なマージを行う条件として、パーティション内のすべてのパーツが min_age_to_force_merge_seconds で指定した時間より古くなっている必要があります。この構成により、古いパーティションは時間の経過とともに 1 つのパーツまでマージされ、データが集約されることでクエリパフォーマンスを維持できます。 +この挙動は、`min_age_to_force_merge_on_partition_only=true` を設定することでさらに調整できます。この設定では、積極的なマージを行う条件として、パーティション内のすべてのパーツが `min_age_to_force_merge_seconds` で指定した時間より古くなっている必要があります。この構成により、古いパーティションは時間の経過とともに 1 つのパーツまでマージされ、データが集約されることでクエリパフォーマンスを維持できます。 * スナップショットパラメータは、パイプの作成後は編集できません。変更する場合は、新しい ClickPipe を作成する必要があります。 -* 既存の ClickPipe にテーブルを追加する場合、スナップショットパラメータは変更できません。新しいテーブルにも既存のパラメータが使用されます。 -* パーティションキーのカラムに `NULL` を含めないでください。`NULL` はパーティション化のロジックでスキップされます。 \ No newline at end of file +* 既存の ClickPipe にテーブルを追加する場合、スナップショットパラメータは変更できません。新しいテーブルにも既存のパラメータが使用されます。 \ No newline at end of file diff --git a/ja/integrations/language-clients/go/config-reference.mdx b/ja/integrations/language-clients/go/config-reference.mdx index fb151a7ec..340c6f6ee 100644 --- a/ja/integrations/language-clients/go/config-reference.mdx +++ b/ja/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### タイムアウト
-| オプション | 型 | デフォルト | DSN パラメータ | 説明 | 推奨事項 | 誤設定時 | -| ------------- | --------------- | ----------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 新しい接続の確立にかけられる最大時間。`MaxOpenConns` に達した場合のプールからの接続取得待ち時間も制御します。 | LAN では 5〜10 秒、WAN/クラウドでは 15〜30 秒。1 秒未満にはしないでください。 | 短すぎる場合: 輻輳時に `"clickhouse: acquire conn timeout"` が発生します。長すぎる場合 (> 60s) : 障害時にアプリが長時間応答しなくなります。 | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 読み取り呼び出しごとにサーバー応答を待つ最大時間。クエリ全体ではなく、ブロックごとに適用されます。コンテキストの期限が優先されます。 | 短時間の対話型クエリでは 10〜30 秒、長時間の分析クエリでは 5〜30 分。 | 短すぎる場合: クエリの途中で `"i/o timeout"` または `"read: connection reset by peer"` が発生し、サーバー側では実行が継続します。長すぎる場合: 切断された接続を検出できません。 | +| オプション | 型 | デフォルト | DSN パラメータ | 説明 | 推奨事項 | 誤設定時 | +| ------------- | --------------- | ----------- | -------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 新しい接続の確立にかけられる最大時間。`MaxOpenConns` に達した場合のプールからの接続取得待ち時間も制御します。 | LAN では 5〜10 秒、WAN/クラウドでは 15〜30 秒、アイドル状態の ClickHouse Cloud サービスに接続する場合は 1〜2 分。1 秒未満にはしないでください。 | 短すぎる場合: 輻輳時に `"clickhouse: acquire conn timeout"` が発生するか、アイドル状態の Cloud サービスの起動完了前に接続が失敗します。長すぎる場合 (> 60s): 障害時にアプリが長時間応答しなくなります。 | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 読み取り呼び出しごとにサーバー応答を待つ最大時間。クエリ全体ではなく、ブロックごとに適用されます。コンテキストのデッドラインが優先されます。 | 短時間の対話型クエリでは 10〜30 秒、長時間の分析クエリでは 5〜30 分。 | 短すぎる場合: クエリの途中で `"i/o timeout"` または `"read: connection reset by peer"` が発生し、サーバー側では実行が継続します。長すぎる場合: 切断された接続を検出できません。 | + + + アイドル状態だった ClickHouse Cloud サービスは一時停止され、最初の受信接続で起動します。起動には通常数十秒かかり、その間は接続試行がブロックされます。`DialTimeout` が起動時間より短いと、アイドル期間後の最初のクエリは実行されず、接続タイムアウトで失敗します。 + + アイドル状態のサービスに最初に到達する可能性がある client では、`DialTimeout` を `1m`〜`2m` に設定してください。その代償として、実際の障害時の失敗検出は遅くなります。つまり、エラーになるまで接続試行がタイムアウトいっぱいまでブロックされます。そのため、高めのタイムアウトは最初の接続だけに適用するか、個々のクエリでコンテキストのデッドラインを使ってエンドツーエンドのレイテンシを抑えることを推奨します。 + *** diff --git a/ja/integrations/language-clients/go/configuration.mdx b/ja/integrations/language-clients/go/configuration.mdx index 4eb6f500f..831d020a2 100644 --- a/ja/integrations/language-clients/go/configuration.mdx +++ b/ja/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: 'reference' 接続を開く際は、Options 構造体を使用してクライアントの動作を制御できます。利用可能な設定は次のとおりです。 -| Parameter | Type | Default | Description | -| ---------------------- | -------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| `Protocol` | `Protocol` | `Native` | 転送プロトコル: `Native` (TCP) または `HTTP`。詳しくは [TCP vs HTTP](#tcp-vs-http) を参照してください。 | -| `Addr` | `[]string` | — | `host:port` 形式のアドレスを格納したスライス。複数ノードについては [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 | -| `Auth` | `Auth` | — | 認証情報 (`Database`、`Username`、`Password`) 。詳しくは [認証](#authentication) を参照してください。 | -| `TLS` | `*tls.Config` | `nil` | TLS 設定。`nil` 以外の値を指定すると TLS が有効になります。詳しくは [TLS](#using-tls) を参照してください。 | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | TCP 接続の確立方法を制御するためのカスタム dial 関数。 | -| `DialTimeout` | `time.Duration` | `30s` | 新しい接続を開く際の最大待機時間。 | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 同時にオープンできる接続の最大数。 | -| `MaxIdleConns` | `int` | `5` | 接続プール内に保持するアイドル接続の数。 | -| `ConnMaxLifetime` | `time.Duration` | `1h` | プールされた接続の最大存続時間。詳しくは [接続プーリング](#connection-pooling) を参照してください。 | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | `Addr` からノードを選択する戦略。詳しくは [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 | -| `BlockBufferSize` | `uint8` | `2` | 並列にデコードするブロック数。値を大きくするとスループットは向上しますが、その分メモリ使用量も増えます。コンテキスト経由でクエリごとに上書きできます。 | -| `Settings` | `Settings` | — | すべてのクエリに適用される ClickHouse settings の map。個々のクエリでは [context](/ja/integrations/language-clients/go/clickhouse-api#using-context) を介して上書きできます。 | -| `Compression` | `*Compression` | `nil` | ブロック単位の圧縮。詳しくは [圧縮](#compression) を参照してください。 | -| `ReadTimeout` | `time.Duration` | — | 1 回の呼び出しでサーバーからの読み取りを待機する最大時間。 | -| `FreeBufOnConnRelease` | `bool` | `false` | `true` の場合、クエリごとに接続のメモリバッファをプールへ戻します。わずかな CPU コストと引き換えにメモリ使用量を削減します。 | -| `Logger` | `*slog.Logger` | `nil` | 構造化ロガー (Go の `log/slog`) 。詳しくは [ログ](#logging) を参照してください。 | -| `Debug` | `bool` | `false` | **非推奨。** 代わりに `Logger` を使用してください。従来のデバッグ出力を stdout に出力します。 | -| `Debugf` | `func(string, ...any)` | — | **非推奨。** 代わりに `Logger` を使用してください。カスタムのデバッグログ関数。`Debug: true` が必要です。 | -| `GetJWT` | `GetJWTFunc` | — | ClickHouse Cloud の認証用 JWT トークンを返すコールバック (HTTPS のみ) 。 | -| `HttpHeaders` | `map[string]string` | — | すべての HTTP リクエストで送信される追加の HTTP ヘッダー (HTTP トランスポートのみ) 。 | -| `HttpUrlPath` | `string` | — | HTTP リクエストに追加される URL パス (HTTP トランスポートのみ) 。 | -| `HttpMaxConnsPerHost` | `int` | — | 基盤となる `http.Transport` の `MaxConnsPerHost` を上書きします (HTTP トランスポートのみ) 。 | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | カスタム HTTP トランスポートファクトリ。必要な項目だけを上書きできるよう、デフォルトのトランスポートが渡されます (HTTP トランスポートのみ) 。 | -| `HTTPProxyURL` | `*url.URL` | — | すべてのリクエストに使用される HTTP プロキシ URL (HTTP トランスポートのみ) 。 | +| Parameter | Type | Default | Description | +| ---------------------- | -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Protocol` | `Protocol` | `Native` | 転送プロトコル: `Native` (TCP) または `HTTP`。詳しくは [TCP vs HTTP](#tcp-vs-http) を参照してください。 | +| `Addr` | `[]string` | — | `host:port` 形式のアドレスを格納したスライス。複数ノードについては [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 | +| `Auth` | `Auth` | — | 認証情報 (`Database`、`Username`、`Password`) 。詳しくは [認証](#authentication) を参照してください。 | +| `TLS` | `*tls.Config` | `nil` | TLS 設定。`nil` 以外の値を指定すると TLS が有効になります。詳しくは [TLS](#using-tls) を参照してください。 | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | TCP 接続の確立方法を制御するためのカスタム dial 関数。 | +| `DialTimeout` | `time.Duration` | `30s` | 新しい接続を開く際の最大待機時間。アイドル状態になっている可能性がある ClickHouse Cloud サービスに接続する場合は、`1m`～`2m` に引き上げてください。詳しくは [Timeouts](/ja/integrations/language-clients/go/config-reference#timeouts) を参照してください。 | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 同時にオープンできる接続の最大数。 | +| `MaxIdleConns` | `int` | `5` | 接続プール内に保持するアイドル接続の数。 | +| `ConnMaxLifetime` | `time.Duration` | `1h` | プールされた接続の最大存続時間。詳しくは [接続プーリング](#connection-pooling) を参照してください。 | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | `Addr` からノードを選択する戦略。詳しくは [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 | +| `BlockBufferSize` | `uint8` | `2` | 並列にデコードするブロック数。値を大きくするとスループットは向上しますが、その分メモリ使用量も増えます。コンテキスト経由でクエリごとに上書きできます。 | +| `Settings` | `Settings` | — | すべてのクエリに適用される ClickHouse settings の map。個々のクエリでは [context](/ja/integrations/language-clients/go/clickhouse-api#using-context) を介して上書きできます。 | +| `Compression` | `*Compression` | `nil` | ブロック単位の圧縮。詳しくは [圧縮](#compression) を参照してください。 | +| `ReadTimeout` | `time.Duration` | — | 1 回の呼び出しでサーバーからの読み取りを待機する最大時間。 | +| `FreeBufOnConnRelease` | `bool` | `false` | `true` の場合、クエリごとに接続のメモリバッファをプールへ戻します。わずかな CPU コストと引き換えにメモリ使用量を削減します。 | +| `Logger` | `*slog.Logger` | `nil` | 構造化ロガー (Go の `log/slog`) 。詳しくは [ログ](#logging) を参照してください。 | +| `Debug` | `bool` | `false` | **非推奨。** 代わりに `Logger` を使用してください。従来のデバッグ出力を stdout に出力します。 | +| `Debugf` | `func(string, ...any)` | — | **非推奨。** 代わりに `Logger` を使用してください。カスタムのデバッグログ関数。`Debug: true` が必要です。 | +| `GetJWT` | `GetJWTFunc` | — | ClickHouse Cloud の認証用 JWT トークンを返すコールバック (HTTPS のみ) 。 | +| `HttpHeaders` | `map[string]string` | — | すべての HTTP リクエストで送信される追加の HTTP ヘッダー (HTTP トランスポートのみ) 。 | +| `HttpUrlPath` | `string` | — | HTTP リクエストに追加される URL パス (HTTP トランスポートのみ) 。 | +| `HttpMaxConnsPerHost` | `int` | — | 基盤となる `http.Transport` の `MaxConnsPerHost` を上書きします (HTTP トランスポートのみ) 。 | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | カスタム HTTP トランスポートファクトリ。必要な項目だけを上書きできるよう、デフォルトのトランスポートが渡されます (HTTP トランスポートのみ) 。 | +| `HTTPProxyURL` | `*url.URL` | — | すべてのリクエストに使用される HTTP プロキシ URL (HTTP トランスポートのみ) 。 | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/ja/products/cloud/guides/index.mdx b/ja/products/cloud/guides/index.mdx index e4ddb4629..c0fa30050 100644 --- a/ja/products/cloud/guides/index.mdx +++ b/ja/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['cloud guides', 'documentation', 'how-to', 'cloud features', 'tutoria | [自分のアカウントを管理する](/ja/products/cloud/guides/security/cloud-access-management/manage-my-account) | このページでは、招待の承諾、MFA 設定の管理、パスワードのリセットを行う方法を説明します | | [SQL コンソールのロール割り当てを管理する](/ja/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | SQL コンソールのロール割り当てを管理する方法を説明するガイド | | [AWS のサービス制限とクォータを管理する](/ja/products/bring-your-own-cloud/reference/aws-service-limits) | BYOC オンボーディング前に確認すべき AWS のサービスクォータ、引き上げを申請する方法、サービスのスケールに応じて監視すべき項目を説明します | -| [CMEK v1 から v2 への移行](/ja/products/cloud/guides/security/cmek-migration) | 従来の CMEK からバージョン 2 に移行するための手順 | | [マルチテナンシー](/ja/products/cloud/guides/best-practices/multitenancy) | マルチテナンシーを実装するためのベストプラクティス | | [セマンティックレイヤーで ClickHouse Assistant agent の会話を最適化する](/ja/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | AGENTS.md を使用して、ClickHouse Assistant chat agent にカスタムのビジネスロジックやデータ固有の指示を与えるためのガイド | | [概要](/ja/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | 自社のクラウドインフラストラクチャ上に ClickHouse をデプロイします | diff --git a/ja/products/cloud/guides/security/cmek-migration.mdx b/ja/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index 3bd3272d3..000000000 --- a/ja/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: '旧CMEKの移行' -slug: /cloud/security/cmek-migration -title: 'CMEK v1 から v2 への移行' -description: '旧CMEKからバージョン2へ移行するための手順' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', 'encryption', 'CMEK'] ---- - -顧客管理暗号化キー (CMEK) サービスのセキュリティ強化を進めています。現在、すべてのサービスは、サービスごとに固有の AWS Role を使用するよう構成されており、顧客キーを用いたサービスの暗号化と復号を許可します。この新しいロールは、サービス設定画面にのみ表示されます。 - -この新しいプロセスは、OpenAPI と Terraform の両方に対応しています。詳細については、ドキュメント ([Enhanced Encryption](/ja/products/cloud/guides/security/cmek)、[Cloud API](/ja/products/cloud/features/admin-features/api/api-overview)、[Official Terraform Provider](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)) を参照してください。 - - - CMEK v1 を利用しているお客様は、2026 年 6 月 1 日までにサービスを移行する必要があります。この日以降、顧客管理キーはデフォルトで ClickHouse 管理キーに切り替えられます。デフォルト移行後は、顧客管理キーに戻すこともできます。 - - -
- ## 手動移行 -
- -新しい手順に移行するには、次の手順を実行してください。 - -1. https://console.clickhouse.cloud にサインインします -2. 暗号化されたサービスをクリックします -3. 左側の Service Settings をクリックします -4. 画面下部までスクロールし、View service details を展開します -5. Encryption Role ID (IAM) をコピーします -6. AWS の KMSキーに移動し、Key Policy を更新して次の内容を追加します: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. ClickHouse Cloud で新しい方式を有効にできるよう、サポートケースを作成してご連絡ください。この変更にはサービスの再起動が必要ですので、再起動に適した曜日や時間帯があればお知らせください。 -8. サービスの再起動後、AWS の KMS キーに移動し、キーポリシーから以下を削除します。 - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. 更新が完了しました！ - -
- ## Terraform への移行 -
- -1. [Terraform バージョン 3.5.0 以降](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)に更新します -2. 変更を加えずに Terraform を適用します。Terraform の state に transparent_data_encryption の新しいフィールドが表示されるので、role_id を控えておいてください。 -3. AWS の KMS キーに移動し、Key Policy を更新して以下を追加します: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. ClickHouse Cloud で、service name を添えてサポートケースを作成し、新しい方法を有効化できるようお知らせください。この変更にはサービスの再起動が必要となるため、再起動に適した曜日・時間帯があればお知らせください。 -5. サービスの再起動後、transparent_data_encryption.enabled 設定を ‘True’ に更新し、Terraform の tier 設定を削除して適用できます。これによる変更はありません。 -6. AWS の KMSキーに移動し、Key Policy から以下を削除します: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. 更新が完了しました！ \ No newline at end of file diff --git a/ja/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/ja/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index ac56c4514..df0f8c187 100644 --- a/ja/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/ja/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ ClickHouse Cloud サービスへのアクセスを AWS PrivateLink のアドレ * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 @@ -54,7 +55,7 @@ ClickHouse Cloud サービスへのアクセスを AWS PrivateLink のアドレ 1. Endpoint "Service name" を取得します。 2. AWS エンドポイント を作成します。 3. "Endpoint ID" を ClickHouse Cloud 組織に追加します。 -4. "Endpoint ID" を ClickHouse service の許可リストに追加します。 +4. "Endpoint ID" を ClickHouseサービス の許可リストに追加します。 Terraform の例は[こちら](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/)をご覧ください。 diff --git a/ja/products/cloud/navigation.json b/ja/products/cloud/navigation.json index e989880bf..ea67a071b 100644 --- a/ja/products/cloud/navigation.json +++ b/ja/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "ja/products/cloud/guides/security/data-masking", - "ja/products/cloud/guides/security/cmek", - "ja/products/cloud/guides/security/cmek-migration" + "ja/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "ja/_specs/cloud-openapi.json" } ] }, diff --git a/ja/products/kubernetes-operator/guides/configuration.mdx b/ja/products/kubernetes-operator/guides/configuration.mdx index 3edcb76fc..4be766b84 100644 --- a/ja/products/kubernetes-operator/guides/configuration.mdx +++ b/ja/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: ClickHouse コンテナーの CPU とメモリを設定します。 ```yaml -# デフォルト値 +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -318,9 +318,12 @@ spec:
- ## TLS/SSL 設定 + ## TLS/SSL の設定
+cert-manager を使用した証明書の発行、セキュアポート経由でのクライアント接続、Keeper トラフィックの暗号化まで含むエンドツーエンドの例については、 +[TLS による保護](/ja/products/kubernetes-operator/guides/tls) ガイドを参照してください。 +
### セキュアなエンドポイントを設定する
@@ -371,6 +374,323 @@ spec: key: ``` +
+ ## External Secret +
+ +デフォルトでは、オペレーター はクラスターの内部認証情報 (interserver password、management password、Keeper identity、cluster secret、named-collections key) を含む Secret を作成して管理します。この Secret にはクラスター名が付けられ、クラスターのネームスペース内に作成されます。 + +これらの認証情報を自分で管理したい場合 (たとえば、HashiCorp Vault、AWS Secrets Manager、または [External Secrets Operator](https://external-secrets.io/) から取得する場合) は、`spec.externalSecret` を使用して、既存の Secret をオペレーター に指定します。 + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + 参照先のSecretは、ClickHouseClusterと**同じネームスペース**内に存在している必要があります。オペレーターが自ら作成していないSecretを削除することはありません。 + + +
+ ### 必須のキー +
+ +Secret には、次のキーが含まれている必要があります。 + +| Key | Format | When required | +| ----------------------- | ------------------------------------------------ | --------------------------- | +| `interserver-password` | 平文のパスワード | 常に必須 | +| `management-password` | 平文のパスワード | 常に必須 | +| `keeper-identity` | `clickhouse:` | 常に必須 | +| `cluster-secret` | 平文のパスワード | 常に必須 | +| `named-collections-key` | 16 バイトの AES 秘密鍵を 16 進数でエンコードしたもの (32 文字の 16 進数) | ClickHouse `>= 25.12` の場合のみ | + +完全な Secret は次のようになります。 + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### ポリシー: Observe と Manage +
+ +`spec.externalSecret.policy` は、必須キーが不足している場合に オペレーター がどのように扱うかを制御します。 + +| Policy | キー不足時の動作 | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Observe` (デフォルト) | 必須キーがすべて揃うまで リコンサイル処理 は**停止**されます。オペレーター は不足している各キーとそのフォーマットのヒントを、`ExternalSecretValid` 条件 (reason は `ExternalSecretInvalid`) と `Warning` イベントで報告します。 | +| `Manage` | オペレーター は不足している必須キーを**生成**し、同じ Secret に書き戻します。Bootstrap に便利です。空の Secret を作成して オペレーター に値を補完させ、必要に応じてその後アクセスをさらに制限できます。なお、オペレーター が Secret を削除することはありません。 | + + + `policy: Manage` を指定していても、Secret はそのネームスペース内にあらかじめ存在している必要があります。オペレーター は Secret 自体を作成せず、既存の Secret に生成したキーを書き込むだけです。参照先の Secret が存在しない場合、ポリシーに関係なく `ExternalSecretNotFound` reason で リコンサイル処理 は停止されます。 + + +外部システム (Vault、ESO、sealed-secrets、GitOps) を信頼できる情報源として扱い、設定ミスがあれば オペレーター に明確に失敗させたい場合は `Observe` を選択してください。自己完結的な Bootstrap を行いつつ、Secret オブジェクト自体の管理権は保持しておきたい (たとえばバックアップしたい) 場合は `Manage` を選択してください. + +
+ ### ステータス条件とトラブルシューティング +
+ +オペレーターは `ClickHouseCluster.status.conditions` に `ExternalSecretValid` 条件を出力します。リコンサイルが停止しているように見える場合は、この条件を確認してください。 + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +考えられる理由: + +| `reason` | 意味 | 対処 | +| ------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------- | +| `ExternalSecretNotFound` | 参照先の Secret がネームスペース内に存在しません。 | Secret を作成するか、`spec.externalSecret.name` を修正してください。 | +| `ExternalSecretInvalid` | Secret は存在しますが、必要なキーが不足しています (`Observe` の場合のみ) 。メッセージには、不足している各キーと想定されるフォーマットが表示されます。 | 不足しているキーを追加するか、`policy: Manage` に切り替えてください。 | +| `ExternalSecretValid` | 必要なキーがすべてそろっており、operator がその Secret を使用しています。 | — | + +Secret が無効な間、operator はリコンサイルを再キューするため、不足しているキーを追加すれば、次回のリコンサイルで自動的に反映されます。ポッドを再起動する必要はありません。 + + + 必要なキーのセットは、実行中の ClickHouse のバージョンによって異なります。`named-collections-key` が検証されるのは、operator の version probe が ClickHouse `25.12` 以降を検出した場合のみです。古いバージョンでは、このキーが Secret に含まれていなくても問題ありません。 + + +
+ ## 追加ポート +
+ +オペレーターは、すべての ClickHouse ポッドとそのヘッドレス Service で、固定のポート群を公開します。具体的には、`8123` HTTP、`9000` ネイティブ、`9009` interserver、`9001` management、`9363` Prometheus メトリクス、さらに TLS が有効な場合は TLS 用の `8443`/`9440` です。ClickHouse で MySQL、PostgreSQL、gRPC、または任意のカスタムポートなどの追加プロトコルを待ち受けるようにするには、`spec.additionalPorts` で宣言します。 + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +operator は、それらのポートをポッドの `containerPorts` と headless Service に追加します。完全な例は、[`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml) にあります。 + + + `additionalPorts` は、Kubernetes 側でのみポートを開きます。これだけでは、ClickHouse server がそれらのポートで待ち受けるようには設定され**ません**。対応するプロトコルを `spec.settings.extraConfig.protocols` で有効にする必要もあります。これを行わないと、Service 上ではポートが開いていても、ポッド内では何も応答しません。 + + +
+ ### エンドツーエンドの例: MySQLワイヤプロトコル +
+ +ポート `9004` で ClickHouse を MySQLワイヤプロトコル経由で公開するには: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +適用後、クラスター内で確認します： + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### フィールドの制約 +
+ +| フィールド | ルール | +| ------ | ------------------------------------------------------------------------------------------------------------ | +| `name` | DNS_LABEL パターン `^[a-z]([-a-z0-9]*[a-z0-9])?$` に一致する必要があります。最大 63 文字です。一意性は、CRD により list-map キーとして保証されます。 | +| `port` | `[1, 65535]` の整数です。webhook は、リスト内の重複するポート番号を拒否します。 | + +
+ ### 予約済みのポートと名前 +
+ +validating webhook は、operator 自身がバインドするポートと競合する `additionalPorts` エントリを拒否します。TLS 関連のポートは、後から `spec.settings.tls.enabled` を切り替えても、それまで有効だったクラスターが壊れないよう、**無条件で**予約されています。 + +| ポート | 予約用途 | +| ------ | ---------------- | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | native TCP | +| `9440` | native TLS | +| `9009` | interserver | +| `9001` | management | +| `9363` | Prometheus メトリクス | + +次の名前も拒否されます。これらは operator の内部的なプロトコル種別の識別子であり (人が読める別名ではありません) 、以下のとおりです。 + +| 名前 | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +拒否されたリクエストでは、次のようなエラーが生成されます。 + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## バージョンプローブとアップグレードチャネル +
+ +オペレーターは、クラスターのバージョンに関して 2 つの独立した処理を行います。 + +1. **バージョンプローブ** — Kubernetes の `Job` でコンテナーイメージを 1 回実行し、実行中の ClickHouse / Keeper のバージョンを検出します。検出されたバージョンは `.status.version` に記録され、他の reconciliation ステップで使用されます (たとえば、`External Secret` の named-collections キーは ClickHouse `25.12` 以降でのみ必要です) 。 +2. **アップグレードチャネル** — 公開されている ClickHouse のリリースフィード (`https://clickhouse.com/data/version_date.tsv`) を定期的に確認します。オペレーターは、新しいバージョンが利用可能かどうかを `VersionUpgraded` ステータス条件で報告します。クラスターを自動的にアップグレードすることはなく、イメージタグはユーザーが管理します。 + +
+ ### リリースチャネルの選択 +
+ +`spec.upgradeChannel` は、オペレーターが比較対象とするアップストリームのリリース群を選択します。このフィールドは `ClickHouseCluster` と `KeeperCluster` の両方にあります。 + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +許可される値 (CRD によりパターン `^(lts|stable|\d+\.\d+)?$` で検証) : + +| Value | Behavior | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| *empty* (default) | オペレーターは、現在実行中の major.minor 系列内の **マイナー** 更新のみを提示します。`25.8.3.1` のクラスターには `25.8.4.x` が通知されますが、`25.9.x` は通知されません。 | +| `stable` | アップストリームの `stable` チャネルを追跡します。これは、ClickHouse Inc. がメインのリリース系列で安定版として示している最新の release です。`lts` チャネルより早くメジャーアップグレードを受け取ります。 | +| `lts` | アップストリームの `lts` チャネルを追跡します。これは長期サポートの release です。メジャーアップグレードの頻度は低く、サポート期間は長くなります。 | +| `25.8` (or any `.`) | チャネルを特定の major.minor 系列に固定します。アップストリームに新しいバージョンが存在していても、それを超えるメジャーアップグレードは提示されません。 | + +本番環境では、通常、チャネルを明示的な `.` (例: `25.8`) に固定することが推奨されます。これにより、クラスターを意図したメジャー release 系列に固定でき、いずれかのレプリカが何らかの理由で別のメジャーへずれてしまった場合に、オペレーターが `WrongReleaseChannel` 警告を表示できるようになります。これは特に、イメージが人が読めるタグではなくダイジェスト (`@sha256:...`) で参照されている場合に重要です。デフォルトの空値は、メジャーバージョンのジャンプが問題にならない開発用クラスターであれば問題ありません。 + +
+ ### ステータス条件 +
+ +プローブとアップグレードチェックの結果は、次の 2 つの条件に反映されます。 + +| Condition | Reason | Meaning | +| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `VersionInSync` | `VersionMatch` | すべてのレプリカが、イメージと同じバージョンを報告しています | +| `VersionInSync` | `VersionMismatch` | レプリカごとに異なるバージョンで稼働しています。計画されたローリングアップグレード中は、警告イベントは抑止されます。通常これは、可変のイメージタグ (たとえば `latest` や、`26.3` のようなメジャー番号だけのタグ) を固定しており、基盤となるレジストリの内容が pull の間に変わった結果、同じタグでも各レプリカで異なるパッチ版が使われた場合に発生します。 | +| `VersionInSync` | `VersionPending` | バージョンプローブ Job がまだ完了していません | +| `VersionInSync` | `VersionProbeFailed` | Probe Job が失敗したため、オペレーターは実行中のバージョンを特定できません | +| `VersionUpgraded` | `UpToDate` | クラスターは、選択したチャネルで利用可能な最新バージョンを実行しています | +| `VersionUpgraded` | `MinorUpdateAvailable` | 同じ `major.minor` 系列で、より新しいパッチが利用可能です | +| `VersionUpgraded` | `MajorUpdateAvailable` | 選択したチャネル内で、より新しい `major.minor` が利用可能です | +| `VersionUpgraded` | `VersionOutdated` | 実行中のバージョンは古く、選択したチャネルから今後修正を受けられなくなります。通常、これはそのメジャー系列が上流の `lts` または `stable` から外されたためです | +| `VersionUpgraded` | `WrongReleaseChannel` | 実行中のイメージは、選択した `upgradeChannel` に属していません。例: `upgradeChannel: lts` で `26.5` を実行しているクラスター。`26.5` は上流の `lts` 系列に含まれていないためです。 | +| `VersionUpgraded` | `UpgradeCheckFailed` | オペレーターが上流のリリースフィードに到達できませんでした | + +次のように確認します: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### バージョンプローブ Job のオーバーライド +
+ +この probe は通常の Kubernetes `Job` として実装されています。クラスターで、特定の Tolerations、node selector、security context を必須とする Admission ポリシーが設定されている場合や、完了後の probe Job の保持期間を制限したい場合は、`spec.versionProbeTemplate` でテンプレートをオーバーライドします: + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +コンテナー名 `version-probe` はオペレーターのデフォルトです。`containers:` 配下の項目は名前でこれに一致するため、オペレーターはユーザー指定のフィールドをデフォルトに対してディープマージします。 + +
+ ### オペレーター全体に適用される制御 +
+ +オペレーターマネージャーの 2 つのフラグで、アップグレードチェックのループ全体を制御します。 + +| フラグ | デフォルト | 効果 | +| --------------------------------- | ------- | -------------------------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | オペレーターがアップストリームのバージョン一覧を再取得する頻度 | +| `--disable-version-update-checks` | `false` | アップグレードチェッカーを完全に無効にします。`VersionUpgraded` 条件は設定されず、`clickhouse.com` への外向きの HTTP トラフィックも発生しません | + +エアギャップ環境、または `clickhouse.com` への egress が許可されていない場合は、`--disable-version-update-checks=true` を設定してください。 +
## ClickHouse の設定
@@ -485,6 +805,49 @@ spec: 有効にすると、オペレーターは Replicated テーブルとインテグレーション テーブルを新しいレプリカに同期します。 +
+ ### サーバーロギング +
+ +`spec.settings.logger` で ClickHouse server のログを設定します。すべてのフィールドは省略可能で、安全なデフォルト値が設定されているため、何も変更していないクラスターでも、コンテナーのコンソールとディスク上のローテーションされるファイルの両方に `trace` レベルでログが出力されます。 + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| フィールド | 既定値 | 説明 | +| ----------- | ------- | -------------------------------------------------------------------------------------------------------- | +| `logToFile` | `true` | `false` の場合、オペレーターはファイル出力先を削除し、サーバーはコンテナーのコンソールにのみログを出力します。 | +| `jsonLogs` | `false` | `true` の場合、オペレーターは `formatting.type: json` を追加するため、各行が JSONオブジェクトになります。 | +| `level` | `trace` | ログの詳細度です。`test`、`trace`、`debug`、`information`、`notice`、`warning`、`error`、`critical`、`fatal` のいずれかを指定します。 | +| `size` | `1000M` | ローテーションされる前の単一ログファイルの最大サイズです。 | +| `count` | `50` | サーバーが保持するローテーション済みログファイルの数です。 | + +オペレーターは、`kubectl logs` が使えるよう、常にコンソールへのログ出力を有効にしています。`logToFile` が `true` の場合は、それに加えてファイルへのログ出力も有効にします。既定値を使用するクラスターでは、次の `ロガー` ブロックが生成されます。 + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +同じ `spec.settings.logger` ブロックは `KeeperCluster` にも適用されます。この場合、operator はファイルを代わりに `/var/log/clickhouse-keeper/` 配下へ書き込みます。 + + + `logToFile` の設定にかかわらずコンソールへのログ出力は有効なままなので、ファイルロギングを無効にしても `kubectl logs` は引き続き利用できます。JSON を解析する構造化ログストアにログを送る場合は、`jsonLogs: true` を設定してください。 + +
## カスタム設定
diff --git a/ja/products/kubernetes-operator/guides/introduction.mdx b/ja/products/kubernetes-operator/guides/introduction.mdx index 0473334e7..d8534322c 100644 --- a/ja/products/kubernetes-operator/guides/introduction.mdx +++ b/ja/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: ストレージを完全に削除するには: ```bash -# クラスターを削除する +# Delete cluster kubectl delete clickhousecluster my-cluster -# ポッドが終了するまで待機する -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# PVC を削除する -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/ja/products/kubernetes-operator/guides/monitoring.mdx b/ja/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..ea5f092f6 --- /dev/null +++ b/ja/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,420 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: ClickHouse Operator の監視 +keywords: ['kubernetes', 'prometheus', '監視', 'メトリクス'] +description: 'operator のメトリクスとヘルスエンドポイントをスクレイプし、保護して活用する方法。' +doc_type: 'guide' +--- + +operator は Prometheus 互換のメトリクスと Kubernetes のヘルスプローブを公開しているため、reconciliation の動作を観測し、処理が停滞したコントローラーを検出し、障害時にアラートを設定できます。 + +このガイドでは、operator が公開する内容、スクレイプ方法、そして日常的に役立つクエリについて説明します。 + + + このガイドの対象は **operator プロセス自体** (controller manager) です。ClickHouse server のメトリクス (クエリ、パーツ、レプリケーションラグ) については、[ClickHouse の Prometheus エンドポイント](/ja/reference/settings/server-settings/settings#prometheus) を使って個別にスクレイプしてください。 + + +
+ ## エンドポイント +
+ +operator のプロセスは、manager ポッド内で 2 つの HTTP エンドポイントを公開します。 + +| エンドポイント | デフォルトポート | パス | 用途 | +| ------- | ------------------------------------ | --------------------- | --------------------------------- | +| メトリクス | `8080` (Helm) / `0` で無効 (バイナリのデフォルト) | `/metrics` | Prometheus エクスポジション形式 | +| ヘルスプローブ | `8081` | `/healthz`, `/readyz` | Kubernetes の liveness と readiness | + +operator のバイナリを直接実行する場合、メトリクスエンドポイントは**デフォルトで無効**です (`--metrics-bind-address=0`)。Helm チャートでは、`metrics.enable: true` と `metrics.port: 8080` によって有効になります。 + +ヘルスプローブエンドポイントは常に有効です。デプロイメントテンプレートでは、`/healthz` と `/readyz` がポート `8081` のポッドの liveness probe および readiness probe に割り当てられます。 + +
+ ## Operator バイナリのフラグ +
+ +関連する `manager` フラグ ([`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go) で定義) : + +| フラグ | デフォルト | 説明 | +| ----------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- | +| `--metrics-bind-address` | `0` (無効) | メトリクスエンドポイントのバインドアドレスです。HTTPS の場合は `:8443`、HTTP の場合は `:8080` に設定します。メトリクスサーバーを無効にする場合は `0` のままにします。 | +| `--metrics-secure` | `true` | 認証・認可付きで、HTTPS 経由でメトリクスを提供します。プレーン HTTP にするには `false` に設定します。 | +| `--metrics-cert-path` | empty | メトリクスサーバー用の TLS 証明書ファイル (`tls.crt`、`tls.key`) が格納されたディレクトリです。 | +| `--metrics-cert-name` | `tls.crt` | `--metrics-cert-path` 内の証明書ファイル名です。 | +| `--metrics-cert-key` | `tls.key` | `--metrics-cert-path` 内の秘密鍵ファイル名です。 | +| `--enable-http2` | `false` | メトリクス **および webhook** サーバーで HTTP/2 を有効にします。CVE-2023-44487 / CVE-2023-39325 の緩和のため、デフォルトでは無効になっています。 | +| `--leader-elect` | `false` (バイナリ) / `true` (Helm チャート) | リーダー選出を有効にし、一度に 1 つのレプリカだけがリコンサイルするようにします。Helm チャートでは、このフラグはデフォルトで `manager.args` に設定されます。 | +| `--health-probe-bind-address` | `:8081` | `/healthz` と `/readyz` のバインドアドレスです。 | + + + フラグのヘルプテキストにある `8443` (HTTPS) / `8080` (HTTP) という慣例は、あくまで目安です。Helm チャートでは `metrics.port: 8080` と `metrics.secure: true` の両方を設定するため、`8080` で HTTPS を提供します。ポート番号に基づくモード判定はありません。HTTPS と HTTP のどちらを使うかを決めるのは `--metrics-secure` です。 + + +
+ ## Helm でメトリクスを有効にする +
+ +この chart は、メトリクス用の `Service` と、必要に応じて prometheus-operator 向けの `ServiceMonitor` をすでに作成します。 + +メトリクスエンドポイント 自体はデフォルトで有効です (`metrics.enable: true`、ポート `8080`、`metrics.secure: true` により HTTPS 経由で提供) 。通常、変更が必要なのは `prometheus.enable` だけで、これを有効にすると chart が `ServiceMonitor` を作成します。 + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +cert-manager を使用しない場合は、追加で `certManager.enable: false` を設定してください。その場合、ServiceMonitor は `insecureSkipVerify: true` でスクレイプを行い、ベアラートークン認証のみに依存します。 + +メトリクス関連のデフォルト設定一式は次のとおりです。 + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +適用: + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +インストール後、チャートによって次が作成されます: + +* `Service/-metrics-service` — ポート `8080` を公開します (`metrics.secure: true` の場合は HTTPS) 。 +* `ServiceMonitor/-controller-manager-metrics-monitor` — `prometheus.enable: true` の場合に作成されます。 +* `ClusterRole/-metrics-reader` — 非リソース URL `/metrics` に対する `get` 権限。 + +
+ ## メトリクス エンドポイントの保護 +
+ +`metrics.secure: true` の場合、メトリクス サーバーはすべてのスクレイプに対して、TLS **および** Kubernetes の認証/認可を必須にします。スクレーパーは次の条件を満たす必要があります。 + +1. 有効な Kubernetes ベアラートークン を提示する。 +2. 非リソース URL `/metrics` への `get` を許可するクラスター ロールにバインドされた ServiceAccount に属している。 + +このチャートには、そのようなクラスター ロールが含まれています。 + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +これを、スクレーパー (通常は Prometheus) が使用する ServiceAccount に紐付けます： + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + メトリクスエンドポイントから `401 Unauthorized` または `403 Forbidden` が返される場合、スクレーパーは HTTPS を使用しているものの、Kubernetes の ベアラートークン がないか認可されていない、またはその ServiceAccount に上記のバインディングが付与されていない可能性があります。`metrics.secure: false` を設定してセキュリティを無効にすることは、共有クラスターでは**推奨されません**。そのポッドにネットワーク経由で到達できる人であれば、誰でもそのエンドポイントをスクレイプできてしまうためです。 + + +
+ ## ServiceMonitor リファレンス +
+ +`prometheus.enable: true` の場合、チャートは以下のような ServiceMonitor をレンダリングします: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +Prometheus インスタンスで cert-manager が実行されていない場合は、`tlsConfig.insecureSkipVerify: true` を設定し、ベアラートークン認証のみに依存してください — `certManager.enable: false` の場合、チャートではすでにこのように設定されています。 + +
+ ## スタンドアロンの Prometheus の例 +
+ +kube-prometheus-stack を使用しない場合は、リポジトリに [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml) という自己完結型のサンプルが用意されています。これにより、ServiceAccount、必要な RBAC、および operator の ServiceMonitor を選択する `Prometheus` CR が作成されます。 + +
+ ## ヘルスプローブのエンドポイント +
+ +| Path | 使用先 | 戻り値 | +| ---------- | -------------------------- | ----------------------------- | +| `/healthz` | Kubernetes liveness probe | プローブサーバーがリッスンしている限り `200 OK`。 | +| `/readyz` | Kubernetes readiness probe | プローブサーバーがリッスンしている限り `200 OK`。 | + +どちらのエンドポイントにも、同じ簡易的な Ping チェック (`sigs.k8s.io/controller-runtime` の `healthz.Ping`) が登録されています。したがって、プローブの失敗が意味するのは「マネージャープロセスが `:8081` で HTTP を提供していない」ということであり、「コントローラーが不健全である」という意味ではありません。コントローラーレベルの問題を検出するには、代わりに[reconciliation メトリクス](#reconciliation-activity)を使用してください。 + +どちらのエンドポイントも、デフォルトではポート `8081` で提供されます。デプロイメントには次のように設定されています。 + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +プローブの失敗が繰り返し発生する場合、通常はプローブ用の server 自体が起動していないことを意味します。たとえば、起動時の早い段階で manager が終了した場合です。manager のログで、`unable to start manager`、RBAC の失敗、または `cache did not sync` のエラーを確認してください。 + +
+ ## メトリクスカタログ +
+ +この operator はカスタムの Prometheus collector を登録しません。以下はすべて、基盤となる `controller-runtime` および `client-go` ライブラリによって公開されるものです。特に有用な series を用途別にまとめると、次のとおりです。 + +
+ ### リコンサイルのアクティビティ +
+ +| メトリクス | 型 | ラベル | +| -------------------------------------------------- | ------ | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | カウンター | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | カウンター | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | ヒストグラム | `controller` | +| `controller_runtime_active_workers` | Gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | Gauge | `controller` | + +`controller` ラベルは、`For(...)` に登録されたリソース型をもとに `controller-runtime` が導出します。現在の `internal/controller/clickhouse` および `internal/controller/keeper` のコードでは、これはそれぞれ `clickhousecluster` と `keepercluster` になります。operator をカスタマイズしている場合は、`/metrics` を一回限りスクレイプして確認してください。 + +
+ ### ワークキュー +
+ +| メトリック | 型 | ラベル | +| --------------------------------------------- | ------ | -------------------------------- | +| `workqueue_depth` | Gauge | `name`, `controller`, `priority` | +| `workqueue_adds_total` | カウンター | `name`, `controller` | +| `workqueue_retries_total` | カウンター | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | Gauge | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | Gauge | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | ヒストグラム | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | ヒストグラム | `name`, `controller` | + +`name` と `controller` のラベルには、同じ値 (コントローラー名) が設定されます。 + +
+ ### API サーバーのトラフィック +
+ +| メトリクス | 型 | ラベル | +| ---------------------------- | ----- | ------------------------ | +| `rest_client_requests_total` | カウンター | `code`, `method`, `host` | + +
+ ### リーダー選出 +
+ +| メトリクス | 型 | ラベル | +| ------------------------------- | ----- | ------------------------------------ | +| `leader_election_master_status` | Gauge | `name` (= `d4ceba06.clickhouse.com`) | + +Helm チャートではデフォルトで `--leader-elect` が有効になっているため、このメトリクスは標準的な Helm インストールでは利用できます。フラグを付けずにバイナリを直接実行した場合、このメトリクスは出力されません。 + +
+ ### ランタイム +
+ +標準の Go プロセスおよびランタイム collector — `go_goroutines`, `go_memstats_*`, `process_cpu_seconds_total`, `process_resident_memory_bytes` など。 + +
+ ## 役立つPromQLクエリ +
+ +
+ ### ヘルス概要 +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### バックログの検知 +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### スロットリングとAPIへの負荷 +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### リーダーのステータス (HA 構成) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## 推奨アラート +
+ +PrometheusRule のひな形 (しきい値はご利用の環境に合わせて調整してください) : + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +最後のルールは、リーダー選出 が有効な場合にのみ意味があります。 + +
+ ## セットアップの確認 +
+ +`clickhouse-operator-system` にチャートがインストールされていることを前提に、エンドツーエンドで簡単に確認します。 + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +スクレイプで Prometheus エクスポジション形式 のメトリクスが返される場合、エンドポイントと RBAC は正しく設定されています。 + + + +* [インストール](/ja/products/kubernetes-operator/install/helm) — 監視に関連する Helm values。 +* [設定](/ja/products/kubernetes-operator/guides/configuration) — metrics server と共通の TLS 設定。 \ No newline at end of file diff --git a/ja/products/kubernetes-operator/guides/scaling.mdx b/ja/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..cdc53a4df --- /dev/null +++ b/ja/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,109 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: クラスターのスケーリング +keywords: ['kubernetes', 'スケーリング', 'レプリカ', '分片', 'Keeper', 'クォーラム'] +description: 'ClickHouseのレプリカと分片、Keeperのクォーラムメンバーをスケーリングする方法と、オペレーターが自動的に実行する処理について説明します。' +doc_type: 'guide' +--- + +クラスターをスケーリングするには、カスタムリソース 上でレプリカ数と分片数を編集します。オペレーター は新しいトポロジーに向けて稼働中のクラスターをリコンサイルし、レプリカごとの StatefulSet を作成または削除し、スキーマの整合性を保ち、status 条件 を通じて進捗を示します。 + +このガイドでは、`ClickHouseCluster` のレプリカと分片をスケーリングする方法、`KeeperCluster` のクォーラムを安全にスケーリングする方法、そしてスケール操作の進行中に確認すべき 条件 について説明します。 + + + `ClickHouseCluster` では常に Keeper が必要で、必須の `spec.keeperClusterRef` フィールドで参照します。オペレーター はクラスターのサイズに関係なく、これを通じてクラスターを調整します。1 つの分片あたり複数のレプリカを実行するには、データが `ReplicatedMergeTree` テーブルにも保存されている必要があります。レプリケーションによって、2 つ目のレプリカでも同じ行を提供できるようになるためです。 + + +
+ ## レプリカのスケーリング +
+ +`spec.replicas` は、各分片のレプリカ数を設定します。各レプリカは `-clickhouse--` という名前のそれぞれ独立した StatefulSet で実行されるため、`shards: 2` と `replicas: 3` のクラスターでは 6 つの StatefulSet が実行されます。 + +この数はそのまま増減できます: + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +スケールアップ時には、オペレーターがレプリカごとの新しい StatefulSets を作成し、各ポッドが Ready になるのを待ってから、新しいレプリカにスキーマを同期します ([スキーマの自動同期](#automatic-schema-sync) を参照) 。スケールダウン時には、余分な StatefulSets を削除し、削除したレプリカが残した古い replicated-database のレプリカ登録をクリーンアップします。 + +
+ ## 分片のスケーリング +
+ +`spec.shards` は分片数を設定します。新しい分片を追加するたびに、レプリカごとの StatefulSets 一式が追加されます。また、オペレーターは [分片ごとに 1 つの PodDisruptionBudget](/ja/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) を作成するため、ある分片での中断が別の分片の許容中断数に影響することはありません。 + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +各分片はデータのそれぞれ異なる一部を保持しており、オペレーターが分片間で行をコピーしたり移動したりすることはありません。`Distributed` テーブルまたは明示的なルーティング方式によって行の格納先となる分片が決まるため、分片を追加しても、既存の分片にすでに保存されている行に手を加えることなく、新しい書き込みの格納先を増やせます。 + +
+ ## 自動スキーマ同期 +
+ +`spec.settings.enableDatabaseSync` が `true` (デフォルト) の場合、トポロジーの変化に応じて、オペレーターがスキーマの整合性を維持します。 + +* **スケールアップ時** — 少なくとも 2 つのレプリカの準備が完了すると、オペレーターは新しく作成されたレプリカへデータベース定義をレプリケートします。これにより、新しいレプリカはクラスター内の他のレプリカと同じ `Replicated` データベースおよびインテグレーションデータベースを持った状態で参加できます。 +* **スケールダウン時** — レプリカが削除される前に、オペレーターは `SYSTEM DROP DATABASE REPLICA` を使用して、各 `Replicated` データベースからそのレプリカの登録を削除します。これにより、縮小後のクラスターが、すでに存在しない `Replicated` データベースのレプリカを待ち続けることを防ぎます。 + +この動作の対象は `Replicated` データベースとインテグレーションのデータベースエンジンです。テーブルデータは移動されません。行データは `ReplicatedMergeTree` テーブルに保持され、このスキーマ同期とは独立して Keeper 経由でレプリケートされます。準備完了したレプリカが 1 つしかない場合はレプリケート先がないため、オペレーターはこのステップをスキップし、対象がないことをログに記録します。 + +たとえば、外部ツールがスキーマ伝播を管理している場合は、`enableDatabaseSync: false` を設定してこの動作を無効にします。その場合、オペレーターは `SchemaInSync` 条件に `SchemaSyncDisabled` という reason を報告します。 + +
+ ## 確認すべき 条件 +
+ +スケール操作の実行中に、カスタムリソースの進捗を確認します: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| 条件 | 理由 | 意味 | +| -------------------- | ---------------------- | ------------------------------------ | +| `ClusterSizeAligned` | `UpToDate` | 稼働中のレプリカ数が要求されたトポロジーと一致している | +| `ClusterSizeAligned` | `ScalingUp` | オペレーターがレプリカを追加している | +| `ClusterSizeAligned` | `ScalingDown` | オペレーターがレプリカを削除している | +| `SchemaInSync` | `ReplicasInSync` | すべてのレプリカ上にデータベースが存在し、古いメタデータが削除されている | +| `SchemaInSync` | `DatabasesNotCreated` | オペレーターは新しいレプリカ上でのデータベース作成をまだ完了していない | +| `SchemaInSync` | `ReplicasNotCleanedUp` | スケールダウンで発生した古いレプリカのメタデータがまだ削除されていない | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync` が `false` である | +| `Ready` | `AllShardsReady` | すべての分片に Ready なレプリカがある | +| `Ready` | `SomeShardsNotReady` | 少なくとも 1 つの分片に Ready なレプリカがない | + +スケール操作は、`ClusterSizeAligned` が `UpToDate`、`SchemaInSync` が `ReplicasInSync`、`Ready` が `AllShardsReady` をそれぞれ報告した時点で完了します。 + +
+ ## Keeper のスケーリング +
+ +`KeeperCluster` は RAFT クォーラムで動作するため、オペレーター はメンバーシップを**一度に 1 レプリカずつ**変更し、クラスターが安定した状態にある場合にのみ実行します。これによりクォーラムが保護されます。`2F+1` のクラスターは `F` 個のメンバーの停止に耐えられるため、3 ノードのクラスターは 1 メンバーが欠けても動作を継続でき、5 ノードのクラスターは 2 メンバーが欠けても動作を継続できます。 + +```yaml +spec: + replicas: 5 # was 3 +``` + +スケールアップ時には、オペレーター は未使用の中で最も小さいレプリカ ID をクォーラムに追加します。スケールダウン時には、最も大きい ID を削除します。各ステップでは、次の処理を開始する前にクォーラムが安定するまで待機します。[Keeper PodDisruptionBudget](/ja/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) のデフォルトは `maxUnavailable: replicas/2` で、自発的な中断中もクォーラムを維持できるようになっています。 + +`ScaleAllowed` 条件は、クォーラムのメンバー構成を現在変更できるかどうかを示します。 + +| Reason | Meaning | +| -------------------------- | --------------------------------------- | +| `ReadyToScale` | クォーラムは安定しており、オペレーター はメンバーを追加または削除できます | +| `ReplicaHasPendingChanges` | レプリカに保留中の設定変更がまだあります | +| `ReplicaNotReady` | レプリカの準備ができていないため、メンバー構成の変更は待機します | +| `NoQuorum` | クラスターにクォーラムがなく、安全にメンバー構成を変更できません | +| `WaitingFollowers` | オペレーター はフォロワーが追いつくのを待っています | + +Keeper は 1 ステップずつスケールし、変更の合間に `ScaleAllowed` が `ReadyToScale` に戻るのを待ってください。一度に複数メンバー分を変更しても、1 回に 1 メンバーずつ行うリコンサイルを省略することはできません。オペレーター はそれでも、クォーラムをステップごとに 1 メンバーずつ進めます。 \ No newline at end of file diff --git a/ja/products/kubernetes-operator/guides/tls.mdx b/ja/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..c28596ea3 --- /dev/null +++ b/ja/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,331 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: TLS でクラスターを保護する +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'security', 'certificates'] +description: 'cert-manager を使用して ClickHouse クラスターを TLS で保護する方法を説明します。クライアント接続と Keeper の暗号化も含みます。' +doc_type: 'guide' +--- + +このガイドでは、ClickHouse クラスター全体をエンドツーエンドで暗号化する手順を説明します。具体的には、[cert-manager](https://cert-manager.io/) による証明書の発行、クラスターでの TLS の有効化、セキュアなポート経由でのクライアント接続、さらに Keeper の協調通信への暗号化の適用を扱います。 + +このガイドは、実際の作業手順に沿って構成されています。`spec.settings.tls` のフィールドごとのリファレンスについては、 +[Configuration → TLS/SSL 設定](/ja/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +および [API リファレンス](/ja/products/kubernetes-operator/reference/api-reference#clustertlsspec) を参照してください。 + +
+ ## 前提条件 +
+ +* オペレーターによって管理されている稼働中の ClickHouse クラスター ([Introduction](/ja/products/kubernetes-operator/guides/introduction)を参照) 。 +* クラスターに [cert-manager](https://cert-manager.io/docs/installation/) がインストールされていること。 +* クラスターのネームスペースに `kubectl` でアクセスできること。 + +オペレーター自体は証明書を生成しません。代わりに、ユーザーが用意した Kubernetes の +`Secret` を利用します。cert-manager はその `Secret` の生成とローテーションに推奨される方法ですが、想定された形式で `Secret` を書き込めるツールであればどれでも利用できます。 + +
+ ## オペレーターが想定する証明書の形式 +
+ +TLS は、3 つのキーを含む Secret を `spec.settings.tls.serverCertSecret` で指定することで有効になります。 + +| Secret キー | 内容 | +| --------- | ----------------------- | +| `tls.crt` | PEM エンコードされたサーバー証明書 | +| `tls.key` | PEM エンコードされた秘密鍵 | +| `ca.crt` | PEM エンコードされた CA 証明書チェーン | + +これは cert-manager が `Certificate` リソースに書き込む形式と完全に同じなので、変換は不要です。オペレーターはこれらを各ポッドの +`/etc/clickhouse-server/tls/` にマウントし、ClickHouse の `openSSL` 設定に組み込みます。 + + + `tls.enabled: true` の場合、`serverCertSecret` は **必須** です。validating + webhook は、これが設定されていない状態で TLS を有効にしたクラスターを拒否し、`enabled: true` + でない限り `required: true` も拒否します。 + + +
+ ## ステップ 1 — cert-manager で CA を Bootstrap する +
+ +最も再現性が高い構成は、自己署名 CA を用意し、その CA でサーバー +証明書に署名する方法です。これにより、クライアントが信頼できる安定した `ca.crt` を使用できます。 + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +本番環境では、自己署名のブートストラップを実際の発行元 (社内 CA、 +Vault、ACME など) に置き換えます。変更が必要なのはステップ 2 のみで、クラスターの構成は +同じです。 + +
+ ## ステップ 2 — サーバー証明書を発行する +
+ +CA issuer からリーフ証明書をリクエストします。`dnsNames` には、クライアントが +ポッドのアドレス指定に使用する名前を含める必要があります。オペレーターは +`-clickhouse-headless` という名前の単一の **ヘッドレス** Service を作成し、 +各レプリカ ポッドには +`-clickhouse---0.-clickhouse-headless..svc.cluster.local` +でアクセスできます。 +ヘッドレス Service ドメインに対するワイルドカードを使用すると、すべてのレプリカをカバーできます。 + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + オペレーターは、クラスター全体で利用できる (ロードバランシングされた) Service を**作成しません**。接続先として単一の安定したエンドポイントが必要な場合は、クラスターのポッドを選択する独自の `クラスタIP` Service を作成し、その DNS 名を上記の `dnsNames` に追加してください。 + + +cert-manager は `tls.crt`、`tls.key`、`ca.crt` を含む `clickhouse-cert` Secret を作成し、有効期限が切れる前に更新します。存在することを確認してください。 + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## ステップ 3 — クラスターで TLS を有効にする +
+ +クラスターがその Secret を参照するように設定します: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### オペレーターの動作 +
+ +`tls.enabled: true` の場合、オペレーターは次の処理を行います。 + +* **すべてのポッドと ヘッドレス Service でセキュアなポートを公開**します: `9440` + (native TLS) および `8443` (HTTPS) 。これらは既存のポートに追加されます。 +* **Secret を** `/etc/clickhouse-server/tls/` **にマウント**し、 + `verificationMode: relaxed`、 + `disableProtocols: sslv2,sslv3`、`preferServerCiphers: true` を含む + ClickHouse の `openSSL` ブロックを生成します。これらはデフォルト値です。上書きするには、[TLS 設定のカスタマイズ](#custom-tls-settings)を参照してください。 + +さらに `required: true` も設定すると、オペレーターは追加で次の処理を行います。 + +* **非セキュアなポート** `9000` (native) と `8123` (HTTP) を**削除**します。TLS + 版のみが残るため、平文クライアントは接続できなくなります。 +* **ポッドの liveness probe を** セキュアな native ポート `9440` に**切り替え**るため、 + 平文リスナーがなくてもヘルスチェックは引き続き機能します。 + + + TLS ポート `8443` と `9440` は、TLS が無効な場合でも webhook により**無条件で** + 予約されます。 + そのため、後から `tls.enabled` を切り替えても、 + `spec.additionalPorts` のエントリと競合することはありません。詳しくは + [Configuration → `additionalPorts`](/ja/products/kubernetes-operator/guides/configuration#additional-ports)を参照してください。 + + +
+ ## ステップ 4 — TLS 経由で接続する +
+ +`required: true` の場合、クライアントはセキュアなポートを使用し、CA を信頼する必要があります。ヘッドレスService (または作成している場合は独自の`クラスタIP` +Service) 経由で、特定のレプリカのポッドを指定してください。 + +**ネイティブプロトコル** (`clickhouse-client`, ポート `9440`): + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (ポート `8443`) : + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +ローカルでのテスト用に、Secret から `ca.crt` を直接取得します: + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## Keeper トラフィックの暗号化 +
+ +ClickHouse クラスターで TLS を有効にしても、Keeper との接続は**暗号化されません**。 +`KeeperCluster` 側でも個別に有効にしてください — Keeper +サービス用の証明書を発行し (Keeper サービスの `dnsNames` を使って手順 1～2 を実施) 、それを参照してください: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +Keeper は、セキュアなクライアントポートを `2281` で公開します。Keeper で TLS を有効にすると、**ClickHouse +クラスターは自動的に TLS 経由で Keeper に接続します**。ClickHouseCluster 側で追加の設定を行う必要は +ありません。ClickHouse は、TLS が有効な場合は独自の `ca.crt` バンドルを使用して Keeper の証明書を検証し、 +そうでない場合はシステムのデフォルト CA バンドルを使用します。 + +
+ ## カスタム CA バンドル +
+ +ClickHouse がサーバー証明書で使用されている CA とは別の CA を信頼する必要がある場合 (たとえば、 +別の CA によって署名された Keeper を使用する場合) は、`caBundle` を指定します。 + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +オペレーターはこのバンドルをマウントし、クライアント側の `openSSL` 検証が +証明書自身の `ca.crt` ではなく、こちらを参照するようにします。 + +
+ ## TLS 設定のカスタマイズ +
+ +オペレーターが生成する `openSSL` ブロックはデフォルト設定であり、上限ではありません。これは +メインのサーバー設定に書き込まれます。`spec.settings.extraConfig` 配下の内容はすべて +`config.d/99-extra-config.yaml` にレンダリングされ、ClickHouse はそれを**最後に**マージするため、 +生成された値を上書きします。 + +デフォルトを強化するには — たとえば、厳格なピア検証を必須にし、最小 +プロトコルを TLS 1.2 に引き上げるには — 変更したい `openSSL.server` のキーを設定します: + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +マージはキー単位で行われます。置き換えられるのは設定した値のみで、生成されたキーのうち +省略したもの (証明書のパス、CA の設定) は保持されます。使用可能なオプションについては +[`openSSL` サーバー設定](/ja/reference/settings/server-settings/settings#openssl) +を、`extraConfig` がどのようにマージされるかについては +[設定 → 埋め込みの追加設定](/ja/products/kubernetes-operator/guides/configuration#embedded-extra-configuration) +を参照してください。 + +
+ ## 確認とトラブルシューティング +
+ +**ヘッドレス Service でセキュアポートが有効になっていることを確認します。** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**証明書がポッドにマウントされていることを確認します。** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| 症状 | 考えられる原因 | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| TLS を有効にした後、ポッドが起動しない / ボリュームマウントエラー | 参照先の Secret が存在しないか、`tls.crt`/`tls.key`/`ca.crt` が不足しています。オペレーターは Secret の内容を検証しないため、キー不足は専用の status 条件ではなく、ポッドのボリュームマウント失敗として表面化します。`kubectl describe pod` でポッドを確認してください。 | +| Webhook がクラスターを拒否する | `enabled: true` を設定せずに `required: true` を設定しているか、`serverCertSecret` を設定せずに `enabled: true` を設定しています。 | +| クライアントで `certificate verify failed` | クライアントが CA を信頼していません。Secret の `ca.crt` を渡すか、証明書の `dnsNames` に接続先のホストが含まれていることを確認してください。 | +| 平文クライアントが突然接続できなくなる | `required: true` により、ポート `9000`/`8123` が使えなくなっています。クライアントを `9440`/`8443` に切り替えるか、移行中も安全でないポートを開けたままにするには `required: false` を設定してください。 | + +
+ ## 関連項目 +
+ +* [設定 → TLS/SSL 設定](/ja/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — フィールドのリファレンス +* [設定 → `additionalPorts`](/ja/products/kubernetes-operator/guides/configuration#additional-ports) — 予約済みポート +* [API リファレンス → ClusterTLSSpec](/ja/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [`openSSL` サーバー設定](/ja/reference/settings/server-settings/settings#openssl) — `extraConfig` で上書き可能な TLS オプション \ No newline at end of file diff --git a/ja/products/kubernetes-operator/install/helm.mdx b/ja/products/kubernetes-operator/install/helm.mdx index 3c72ba6ff..0d644115e 100644 --- a/ja/products/kubernetes-operator/install/helm.mdx +++ b/ja/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-man helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/ja/products/kubernetes-operator/install/kubectl.mdx b/ja/products/kubernetes-operator/install/kubectl.mdx index 73528afea..8d7e93267 100644 --- a/ja/products/kubernetes-operator/install/kubectl.mdx +++ b/ja/products/kubernetes-operator/install/kubectl.mdx @@ -93,7 +93,7 @@ operator のデプロイメントオプションを設定するには、以下 必要に応じて機能を有効または無効にするため、config/default/kustomization.yaml を編集します。 * webhooks を無効にするには、`[WEBHOOK]` セクションと `[CERTMANAGER]` セクションをコメントアウトします。 - * セキュアなメトリクス endpoint を有効にするには、`[METRICS]` セクションをコメントアウトし、`[METRICS SECURE]` セクションと `[CERTMANAGER]` セクションのコメントを解除します。 + * セキュアなメトリクスエンドポイントを有効にするには、`[METRICS]` セクションをコメントアウトし、`[METRICS SECURE]` セクションと `[CERTMANAGER]` セクションのコメントを解除します。 * Prometheus Operator の ServiceMonitor を有効にするには、`[PROMETHEUS]` セクションのコメントを解除します。 * operator のネットワークポリシーを有効にするには、`[NETWORK POLICY]` セクションのコメントを解除します。 @@ -105,7 +105,7 @@ operator のデプロイメントオプションを設定するには、以下 ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/ja/products/kubernetes-operator/navigation.json b/ja/products/kubernetes-operator/navigation.json index 90e68e7ef..9bdbd6ddd 100644 --- a/ja/products/kubernetes-operator/navigation.json +++ b/ja/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "ja/products/kubernetes-operator/guides/introduction", - "ja/products/kubernetes-operator/guides/configuration" + "ja/products/kubernetes-operator/guides/configuration", + "ja/products/kubernetes-operator/guides/monitoring", + "ja/products/kubernetes-operator/guides/scaling", + "ja/products/kubernetes-operator/guides/tls" ] }, { diff --git a/ja/products/kubernetes-operator/overview.mdx b/ja/products/kubernetes-operator/overview.mdx index 0a975dab6..2ccd109d6 100644 --- a/ja/products/kubernetes-operator/overview.mdx +++ b/ja/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ ClickHouse Operator は、Kubernetes 上で ClickHouse クラスターおよび * **[はじめに](/ja/products/kubernetes-operator/guides/introduction)** - ClickHouse Operator の概念の概要 * **[設定ガイド](/ja/products/kubernetes-operator/guides/configuration)** - ClickHouse と Keeper クラスターを設定する -* **[監視](/ja/products/kubernetes-operator/guides/introduction)** - Prometheus メトリクスを使用して clickhouse-operator を監視する +* **[監視](/ja/products/kubernetes-operator/guides/monitoring)** - オペレーター の Prometheus メトリクスとヘルスプローブ +* **[スケーリング](/ja/products/kubernetes-operator/guides/scaling)** - レプリカ、分片、Keeper クォーラムをスケールする +* **[TLS で保護する](/ja/products/kubernetes-operator/guides/tls)** - cert-manager を使用してクラスターをエンドツーエンドで暗号化する
## リファレンス diff --git a/ja/products/kubernetes-operator/reference/api-reference.mdx b/ja/products/kubernetes-operator/reference/api-reference.mdx index 0f33bc8a7..7a4dc7cab 100644 --- a/ja/products/kubernetes-operator/reference/api-reference.mdx +++ b/ja/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'API リファレンス' このドキュメントでは、ClickHouse Operator のカスタムリソースに関する詳細な API リファレンスを提供します。 +
+ ## AdditionalPort +
+ +AdditionalPort は、ClickHouse ポッドおよびオペレーターが管理するヘッドレス Service で公開する追加の TCP ポートを 1 つ定義します。 + +| フィールド | 型 | 説明 | 必須 | デフォルト | +| ------ | ------- | ------------------------------------------------------------------------------------- | ---- | ----- | +| `name` | string | リスト内でポートを一意に識別する名前です。コンテナポート名と Service ポート名の両方に使用されます。
DNS_LABEL である必要があります。 | true | | +| `port` | integer | 公開する TCP ポート番号です。 | true | | + +登場箇所: + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec は、ClickHouseCluster の望ましい状態を定義します。 -| Field | Type | Description | Required | Default | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | -| `replicas` | integer | 単一分片内のレプリカ数。 | false | 3 | -| `shards` | integer | クラスター内の分片数。 | false | 1 | -| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | ClickHouse のコーディネーションに使用される KeeperCluster への参照。
ネームスペースが省略された場合は、ClickHouseCluster のネームスペースが使用されます。 | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | ClickHouse ポッド仕様に渡されるパラメーター。 | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | ClickHouse コンテナー仕様に渡されるパラメーター。 | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse データ用の永続ストレージ仕様。 | false | | -| `labels` | object (keys:string, values:string) | リソースに追加されるラベル。 | false | | -| `annotations` | object (keys:string, values:string) | リソースに追加されるアノテーション。 | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget は、各分片に対して作成される PDB を設定します。
未設定の場合、オペレーターは単一レプリカの
分片では maxUnavailable=1、複数レプリカの分片では minAvailable=1 をデフォルトで使用します。 | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse server の設定パラメーター。 | false | | -| `clusterDomain` | string | ClusterDomain は、DNS 名前解決に使用される Kubernetes クラスターのドメイン接尾辞です。 | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel は、メジャーバージョンのアップグレードチェックに使用するリリースチャネルを指定します。
空の場合は、マイナーアップデートのみが提案されます。指定できる値は stable、lts、または特定の major.minor バージョン (例: 25.8) です。 | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | バージョン検出 Job に対する VersionProbeTemplate のオーバーライド。 | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret は、クラスターのシークレットを含む外部管理された Secret への任意の参照です。
この Secret はクラスターと同じネームスペース内に存在している必要があります。 | false | | +| Field | Type | Description | Required | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | +| `replicas` | integer | 単一分片内のレプリカ数。 | false | 3 | +| `shards` | integer | クラスター内の分片数。 | false | 1 | +| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | ClickHouse のコーディネーションに使用される KeeperCluster への参照。
ネームスペースが省略された場合は、ClickHouseCluster のネームスペースが使用されます。 | true | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | ClickHouse ポッド仕様に渡されるパラメーター。 | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | ClickHouse コンテナー仕様に渡されるパラメーター。 | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse データ用の永続ストレージ仕様。 | false | | +| `labels` | object (keys:string, values:string) | リソースに追加されるラベル。 | false | | +| `annotations` | object (keys:string, values:string) | リソースに追加されるアノテーション。 | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget は、各分片に対して作成される PDB を設定します。
未設定の場合、オペレーターは単一レプリカの
分片では maxUnavailable=1、複数レプリカの分片では minAvailable=1 をデフォルトで使用します。 | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse server の設定パラメーター。 | false | | +| `clusterDomain` | string | ClusterDomain は、DNS 名前解決に使用される Kubernetes クラスターのドメイン接尾辞です。 | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel は、メジャーバージョンのアップグレードチェックに使用するリリースチャネルを指定します。
空の場合は、マイナーアップデートのみが提案されます。指定できる値は stable、lts、または特定の major.minor バージョン (例: 25.8) です。 | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | バージョン検出 ジョブ に対する VersionProbeTemplate のオーバーライド。 | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret は、クラスターのシークレットを含む外部管理された Secret への任意の参照です。
この Secret はクラスターと同じネームスペース内に存在している必要があります。 | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) array | AdditionalPorts は、ClickHouse ポッドおよびオペレーター管理の headless Service で公開する追加の TCP ポートを定義します。
オペレーターは Kubernetes リソースにポートを追加するだけで、ClickHouse server がそれらのポートで待ち受けるようには設定しません。 | false | | Appears in: @@ -182,7 +198,7 @@ ContainerTemplateSpec は、クラスター内のコンテナーに対する設 | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----- | | `image` | [ContainerImage](#containerimage) | Image は、デプロイするコンテナーイメージです。 | true | | | `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | image の ImagePullPolicy です。デフォルトは IfNotPresent です。 | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources は、サーバーコンテナーのリソース要件です。
SMP によりオペレーターのデフォルトとディープマージされます。個々の limits と requests は一致する
キーのみを上書きし、未設定のフィールドではオペレーターのデフォルトが保持されます。 | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources は、サーバーコンテナーのリソース要件です。
全体として適用されます。すべての resource フィールドが空の場合にのみ、オペレーターのデフォルトが使用されます。 | false | | | `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts は、コンテナーのボリュームマウントの一覧です。
オペレーターが生成したマウントと連結されます。オペレーターのマウントと `mountPath` を共有するエントリは、
projected volume にマージされます。 | false | | | `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env は、コンテナーに設定する環境変数の一覧です。
名前を基準にオペレーターのデフォルトとマージされます。 | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | SecurityContext は、コンテナーの実行時に使用するセキュリティオプションを定義します。
nil ではない SecurityContext を指定すると、オペレーターのデフォルトは完全に置き換えられます。つまり、
構造体全体の管理はユーザー側の責任となります。nil の場合は、オペレーターのデフォルトが保持されます。
詳細: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | @@ -304,19 +320,19 @@ KeeperClusterReference は、ClickHouseCluster で使用される KeeperCluster KeeperClusterSpec は、KeeperCluster の望ましい状態を定義します。 -| Field | Type | Description | Required | Default | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------- | -| `replicas` | integer | クラスター内のレプリカ数 | false | 3 | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Keeper ポッド仕様に渡されるパラメーター。 | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Keeper コンテナー仕様に渡されるパラメーター。 | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper データ用の永続ストレージ仕様。 | false | | -| `labels` | object (keys:string, values:string) | リソースに追加されるラベル。 | false | | -| `annotations` | object (keys:string, values:string) | リソースに追加される annotations。 | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget は、Keeper クラスター用に作成される PDB を設定します。
未設定の場合、オペレーターは既定で maxUnavailable=replicas/2 を使用します
(2F+1 クラスターでクォーラムを維持するため)。 | false | | -| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper サーバーの設定パラメーター。 | false | | -| `clusterDomain` | string | ClusterDomain は、DNS 名前解決に使用される Kubernetes クラスターのドメイン接尾辞です。 | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel は、メジャーバージョンのアップグレード確認に使用するリリースチャネルを指定します。
空の場合、マイナーアップデートのみが提案されます。指定可能な値は stable、lts、または特定の major.minor バージョン (例: 25.8) です。 | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | バージョン検出ジョブ用の VersionProbeTemplate を上書きします。 | false | | +| Field | Type | Description | Required | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------- | +| `replicas` | integer | クラスター内のレプリカ数 | false | 3 | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Keeper ポッド仕様に渡されるパラメーター。 | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Keeper コンテナー仕様に渡されるパラメーター。 | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper データ用の永続ストレージ仕様。 | false | | +| `labels` | object (keys:string, values:string) | リソースに追加されるラベル。 | false | | +| `annotations` | object (keys:string, values:string) | リソースに追加される annotations。 | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget は、Keeper クラスター用に作成される PDB を設定します。
未設定の場合、オペレーターは既定で maxUnavailable=replicas/2 を使用します
(2F+1 クラスターでクォーラムを維持するため)。単一レプリカのクラスターでは maxUnavailable=1 を使用します。 | false | | +| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper サーバーの設定パラメーター。 | false | | +| `clusterDomain` | string | ClusterDomain は、DNS 名前解決に使用される Kubernetes クラスターのドメイン接尾辞です。 | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel は、メジャーバージョンのアップグレード確認に使用するリリースチャネルを指定します。
空の場合、マイナーアップデートのみが提案されます。指定可能な値は stable、lts、または特定の major.minor バージョン (例: 25.8) です。 | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | バージョン検出ジョブ用の VersionProbeTemplate を上書きします。 | false | | 以下に表示されます: diff --git a/ja/resources/changelogs/cloud/release-status.mdx b/ja/resources/changelogs/cloud/release-status.mdx index f8e25ef6e..089235bec 100644 --- a/ja/resources/changelogs/cloud/release-status.mdx +++ b/ja/resources/changelogs/cloud/release-status.mdx @@ -43,7 +43,7 @@ Enterprise ティアのサービスでは、すべてのリリースチャネル 以下に示す日付は、ClickHouse が各リリースチャネルへの**ロールアウトを開始する**時点を示すものであり、個々のサービスがアップグレードされる時点を示すものではありません。 * ロールアウトは自動で実施され、数週間かけて段階的に進行します - * スケジュールされたアップグレードウィンドウが設定されているサービスは、チャネルのロールアウト終了翌週の予定されたウィンドウ内にアップグレードされます (UTC の月曜日 00:00 開始) + * スケジュールされたアップグレードウィンドウが設定されているサービスは、チャネルのロールアウト終了翌週の予定されたウィンドウ内にアップグレードされます (UTC の月曜日 00:00 開始) * ロールアウトの一時停止 (例: 休日期間中の凍結) やヘルスモニタリングにより、ロールアウト完了が遅れる場合があります 本番環境へのアップグレード前に事前検証を行う場合は、非本番サービスには Fast または Regular チャネルを、本番サービスには Slow チャネルを使用してください。 @@ -51,14 +51,27 @@ Enterprise ティアのサービスでは、すべてのリリースチャネル >\"를 사용합니다.", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Kafka source의 포맷입니다.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka source용 IAM role입니다. IAM role 인증과 함께 사용하십시오. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "Kafka source에 대한 안전한 비공개 connection에 사용되는 Reverse Private Endpoint UUIDs입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka source의 topics입니다.", + "type": "string" + }, + "type": { + "description": "Kafka source의 유형입니다.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "Kinesis 스트림에 사용할 인증 방법입니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis 스트림의 포맷입니다.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "인증에 사용할 IAM role입니다. IAM_ROLE을 사용하는 경우 필수입니다.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Kinesis 스트림에서 읽을 때 사용할 iterator 유형입니다. AT_TIMESTAMP를 사용하는 경우 timestamp 필드를 제공해야 합니다.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis 스트림의 AWS 리전입니다.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis 스트림 이름입니다.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Kinesis 스트림에서 읽기를 시작할 Unix timestamp입니다. iteratorType이 AT_TIMESTAMP인 경우 필수입니다.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Kinesis 스트림에 enhanced fan-out을 사용합니다.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "대상 테이블의 컬럼입니다. Postgres를 제외한 모든 파이프 유형에서 필수 필드입니다.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "대상 데이터베이스입니다.", + "type": "string" + }, + "managedTable": { + "description": "이 테이블을 ClickPipes에서 관리합니까? Postgres를 제외한 모든 파이프 유형에서 필수 필드입니다.", + "type": "boolean" + }, + "roles": { + "description": "ClickPipe는 이러한 역할로 ClickHouse 사용자를 생성합니다. 필요한 경우 여기에 사용자 지정 역할을 추가하십시오.", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "대상 테이블입니다. Postgres를 제외한 모든 파이프 유형에서 필수 필드입니다.", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "스키마 레지스트리의 인증 유형입니다.", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "스키마 레지스트리 인증서를 검증하기 위한 PEM 인코딩 CA 인증서입니다.", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "스키마 URL입니다. HTTPS가 필요합니다.", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "연결할 Postgres 인스턴스의 데이터베이스입니다.", + "type": "string" + }, + "host": { + "description": "연결할 Postgres 인스턴스의 호스트입니다.", + "type": "string" + }, + "port": { + "description": "연결할 Postgres 인스턴스의 포트입니다.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgres 파이프의 테이블 매핑입니다.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "인증 방법입니다. CONNECTION_STRING은 Azure Blob Storage에 사용합니다. IAM_ROLE 및 IAM_USER는 AWS S3/GCS/DigitalOcean에 사용합니다. 지정하지 않으면 인증을 사용하지 않습니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage의 container 이름입니다. type이 azureblobstorage인 경우 필수입니다.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "파일에 사용되는 압축 알고리즘입니다.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 인증에 사용할 connection string입니다. authentication이 CONNECTION_STRING인 경우 필수입니다.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "파일에 사용되는 구분자입니다.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "파일의 포맷입니다.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role 인증에 사용할 IAM role입니다. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "true로 설정하면 파이프가 소스에서 새 파일을 지속적으로 읽습니다. false로 설정하면 파이프는 파일을 한 번만 읽습니다. 새 파일은 사전식 순서에 맞게 업로드해야 합니다.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure container 내 파일의 경로입니다. Azure Blob Storage 소스에 사용됩니다. bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 자세한 내용은 경로에서 와일드카드를 사용하는 방법에 대한 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "이벤트 기반 지속적인 수집을 위한 SQS 큐 URL입니다. 지정하면 파일은 사전식 순서가 아니라 S3 이벤트 알림을 기준으로 수집됩니다. isContinuous가 true이고 인증이 public이 아닐 때만 적용됩니다.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage 소스의 유형입니다.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "수집할 파일 경로를 지정하십시오. bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 자세한 내용은 경로에서 와일드카드를 사용하는 방법에 대한 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "대상 테이블의 컬럼입니다. 테이블 스키마는 업데이트되지 않으며 ClickPipe 구성만 업데이트됩니다.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka source의 인증 방법입니다. 지원되는 인증 방법: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "broker 인증서를 검증하기 위한 PEM 인코딩 CA 인증서입니다.", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka source의 자격 증명입니다. 인증 방법에서 지원하는 항목 중 하나를 선택하십시오.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "Kafka source용 IAM role입니다. IAM role 인증과 함께 사용하십시오. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "Kafka source에 대한 안전한 비공개 connection에 사용되는 Reverse Private Endpoint UUIDs입니다.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Kinesis 스트림에 사용할 인증 방법입니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "인증에 사용할 IAM role입니다. IAM_ROLE을 사용하는 경우 필수입니다.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "인증 방법입니다. CONNECTION_STRING은 Azure Blob Storage에 사용합니다. IAM_ROLE 및 IAM_USER는 AWS S3/GCS/DigitalOcean에 사용합니다. 지정하지 않으면 인증을 사용하지 않습니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage의 Container 이름입니다. type이 azureblobstorage일 때 필요합니다.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 인증에 사용할 연결 문자열입니다. authentication이 CONNECTION_STRING일 때 필요합니다.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "IAM role 인증에 사용할 IAM role입니다. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Azure container 내 파일의 경로입니다. Azure Blob Storage 원본에 사용됩니다. bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 자세한 내용은 경로에서 와일드카드 사용에 대한 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "원본 스키마 이름입니다.", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "원본 테이블 이름입니다.", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "대상 테이블에 사용할 테이블 엔진입니다.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "대상 테이블 이름입니다.", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "각 Batch에서 가져올 행 수입니다.", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Postgres에서 데이터를 동기화하는 주기(초)입니다.", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "연결할 Postgres 인스턴스의 데이터베이스입니다.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "연결할 Postgres 인스턴스의 호스트입니다.", + "nullable": true, + "type": "string" + }, + "port": { + "description": "연결할 Postgres 인스턴스의 포트입니다.", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "Postgres 파이프에 추가할 테이블 매핑입니다.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "Postgres 파이프에서 제거할 테이블 매핑입니다.", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "ClickPipe의 필드 매핑입니다. 테이블 schema는 업데이트되지 않으며, ClickPipe 구성만 업데이트됩니다.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe의 이름입니다.", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "데이터 소스에서 받은 데이터 샘플을 검증합니다. 연결과 데이터의 가용성 및 정확성을 검증합니다. 활성화하지 않으면 연결만 검증합니다. 이 설정은 Postgres 파이프에는 적용되지 않으며, Postgres 파이프는 항상 연결과 테이블 정의만 검증합니다. 이 기능은 Experimental 상태이며 향후 제거될 수 있습니다.", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka source의 인증 방법입니다. 지원되는 인증 방법: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Kafka source의 brokers입니다.", + "type": "string" + }, + "caCertificate": { + "description": "broker 인증서를 검증하기 위한 PEM 인코딩 CA 인증서입니다.", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Kafka source의 consumer group입니다. 지정하지 않으면 \"clickpipes-<>\"를 사용합니다.", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka source의 자격 증명입니다. 인증 방법에서 지원하는 항목 중 하나를 선택하십시오.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Kafka source의 포맷입니다.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka source용 IAM role입니다. IAM role 인증과 함께 사용하십시오. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "Kafka source에 대한 안전한 비공개 connection에 사용되는 Reverse Private Endpoint UUIDs입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka source의 topics입니다.", + "type": "string" + }, + "type": { + "description": "Kafka source의 유형입니다.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Kinesis 스트림에 사용할 인증 방법입니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis 스트림의 포맷입니다.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "인증에 사용할 IAM role입니다. IAM_ROLE을 사용하는 경우 필수입니다.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Kinesis 스트림에서 읽을 때 사용할 iterator 유형입니다. AT_TIMESTAMP를 사용하는 경우 timestamp 필드를 제공해야 합니다.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis 스트림의 AWS 리전입니다.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis 스트림 이름입니다.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Kinesis 스트림에서 읽기를 시작할 Unix timestamp입니다. iteratorType이 AT_TIMESTAMP인 경우 필수입니다.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Kinesis 스트림에 enhanced fan-out을 사용합니다.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "인증 방법입니다. CONNECTION_STRING은 Azure Blob Storage에 사용합니다. IAM_ROLE 및 IAM_USER는 AWS S3/GCS/DigitalOcean에 사용합니다. 지정하지 않으면 인증을 사용하지 않습니다.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob Storage의 Container 이름입니다. type이 azureblobstorage일 때 필요합니다.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "파일에 사용되는 압축 알고리즘입니다.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Azure Blob Storage 인증에 사용할 연결 문자열입니다. authentication이 CONNECTION_STRING일 때 필요합니다.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "파일에 사용되는 구분자입니다.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "파일의 포맷입니다.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role 인증에 사용할 IAM role입니다. 자세한 내용은 ClickPipes 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "true로 설정하면 파이프가 원본에서 새 파일을 지속적으로 읽습니다. false로 설정하면 파이프가 파일을 한 번만 읽습니다. 새 파일은 사전식 순서에 맞게 업로드되어야 합니다.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure container 내 파일의 경로입니다. Azure Blob Storage 원본에 사용됩니다. bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 자세한 내용은 경로에서 와일드카드 사용에 대한 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "이벤트 기반 지속적인 수집을 위한 SQS 큐 URL입니다. 지정하면 파일은 사전식 순서가 아니라 S3 이벤트 알림을 기준으로 수집됩니다. isContinuous가 true이고 authentication이 public이 아닐 때만 적용됩니다.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage 소스의 유형입니다.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "수집할 파일의 경로를 입력하십시오. bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 자세한 내용은 경로에서 와일드카드 사용에 대한 문서를 참조하십시오: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "ClickPipe의 필드 매핑입니다. 모든 대상 컬럼이 매핑에 포함되어야 합니다.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe의 이름입니다.", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "데이터 소스에서 받은 데이터 샘플을 검증합니다. 연결과 데이터의 가용성 및 정확성을 검증합니다. 활성화하지 않으면 연결만 검증합니다. 이 설정은 Postgres 파이프에는 적용되지 않으며, Postgres 파이프는 항상 연결과 테이블 정의만 검증합니다. 이 기능은 Experimental 상태이며 향후 제거될 수 있습니다.", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "대상 테이블에서 널 허용 컬럼을 허용합니다.", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "생성된 replication slot에 대해 failover를 활성화합니다. replication slot이 설정되지 않은 경우에만 사용할 수 있습니다.", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "초기 적재 중 동기화할 병렬 테이블 수입니다.", + "type": "number" + }, + "publicationName": { + "description": "복제에 사용할 publication 이름입니다.", + "type": "string" + }, + "pullBatchSize": { + "description": "각 Batch에서 가져올 행 수입니다.", + "type": "number" + }, + "replicationMode": { + "description": "파이프에 사용할 복제 모드입니다.", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "복제에 사용할 replication slot 이름입니다.", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "파티션별로 스냅샷할 행 수입니다.", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "병렬로 스냅샷할 테이블 수입니다.", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Postgres에서 데이터를 동기화하는 주기(초)입니다.", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "대상 테이블에서 제외할 컬럼입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "대상 테이블의 정렬 키로 사용할 컬럼의 순서가 있는 목록입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "원본 schema 이름입니다.", + "type": "string" + }, + "sourceTable": { + "description": "원본 테이블 이름입니다.", + "type": "string" + }, + "tableEngine": { + "description": "대상 테이블에 사용할 테이블 엔진입니다.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "대상 테이블 이름입니다.", + "type": "string" + }, + "useCustomSortingKey": { + "description": "대상 테이블에 사용자 지정 sorting key를 사용할지 여부입니다.", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "연결할 Postgres 인스턴스의 데이터베이스입니다.", + "type": "string" + }, + "host": { + "description": "연결할 Postgres 인스턴스의 호스트입니다.", + "type": "string" + }, + "port": { + "description": "연결할 Postgres 인스턴스의 포트입니다.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgres 파이프의 테이블 매핑입니다.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "원하는 동시 실행 수입니다. S3 파이프에만 적용됩니다. 0으로 설정하면 클러스터 메모리에 따라 동시 실행 수가 자동으로 조정됩니다.", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "각 레플리카의 CPU 밀리코어 값입니다. streaming 파이프에만 적용됩니다.", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "각 레플리카의 메모리 용량(GB)입니다. streaming 파이프에만 적용됩니다.", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "원하는 레플리카 수입니다. 확장 가능한 파이프에만 적용됩니다.", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "확장할 동시성 수입니다. S3 파이프를 확장할 때 사용합니다.", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "각 레플리카의 CPU(millicores)입니다. streaming 파이프를 확장할 때 사용합니다.", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "각 레플리카의 메모리(GB)입니다. streaming 파이프를 확장할 때 사용합니다.", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "확장할 레플리카 수입니다. Kafka 파이프를 확장할 때 사용합니다.", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "최대 다운로드 스레드 수입니다. 최대 동시 다운로드 스레드 수입니다.", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "최대 삽입 스레드 수입니다. 최대 동시 삽입 스레드 수입니다.", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "최대 스레드 수입니다. 파일 처리를 위한 최대 동시 스레드 수입니다.", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "최소 삽입 데이터 블록 크기(바이트)입니다. 삽입용 데이터 블록의 최소 크기(바이트)입니다.", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "병렬 분산 insert select입니다. 병렬 분산 insert select 설정입니다.", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "병렬 view 처리입니다. attached 상태인 view로 순차적으로 푸시하는 대신 동시에 푸시하도록 활성화할지 여부입니다.", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "객체 스토리지 동시성입니다. 파일을 동시에 처리하는 스레드 수입니다.", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "최대 파일 수입니다. 단일 삽입 배치에서 처리할 최대 파일 수입니다.", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "최대 삽입 바이트입니다. 단일 삽입 배치에서 처리할 바이트 수입니다.", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "객체 스토리지 폴링 인터벌입니다. 새 객체 스토리지 데이터를 지속적으로 수집하기 위해 조회하는 갱신 인터벌을 구성합니다.", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster function 사용 여부입니다. 분산 처리에 ClickHouse 클러스터 함수를 사용할지 여부입니다.", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "스트리밍 최대 삽입 대기 시간입니다. 데이터를 ClickHouse에 삽입하기 전 대기할 최대 시간을 구성합니다.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "최대 다운로드 스레드 수입니다. 최대 동시 다운로드 스레드 수입니다.", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "최대 삽입 스레드 수입니다. 최대 동시 삽입 스레드 수입니다.", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "최대 스레드 수입니다. 파일 처리에 사용할 최대 동시 스레드 수입니다.", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "최소 삽입 블록 크기(바이트)입니다. 삽입용 데이터 블록의 최소 크기입니다(바이트 단위).", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "병렬 분산 삽입 선택입니다. 병렬 분산 삽입 선택 설정입니다.", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "병렬 VIEW 처리입니다. attached 상태인 VIEW에 순차적으로 푸시하는 대신 동시에 푸시하도록 활성화할지 여부입니다.", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "객체 스토리지 동시성입니다. 파일 처리를 위한 최대 동시 스레드 수입니다.", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "최대 파일 수입니다. 단일 삽입 배치에서 처리할 최대 파일 수입니다.", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "최대 삽입 바이트 수입니다. 단일 삽입 배치에서 처리할 바이트 수입니다.", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "객체 스토리지 폴링 인터벌입니다. 새 객체 스토리지 데이터를 연속 수집할 때 조회하는 갱신 인터벌을 구성합니다.", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster function 사용입니다. 분산 처리에 ClickHouse cluster function을 사용할지 여부입니다.", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Streaming 최대 삽입 대기 시간입니다. 데이터를 ClickHouse에 삽입하기 전까지의 최대 대기 시간을 구성합니다.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "최대 다운로드 스레드 수입니다. 최대 동시 다운로드 스레드 수입니다.", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "최대 삽입 스레드 수입니다. 최대 동시 삽입 스레드 수입니다.", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "최대 스레드 수입니다. 파일 처리에 사용할 최대 동시 스레드 수입니다.", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "최소 삽입 블록 크기(바이트)입니다. 삽입용 데이터 블록의 최소 크기입니다(바이트 단위).", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "병렬 분산 삽입 선택입니다. 병렬 분산 삽입 선택 설정입니다.", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "병렬 VIEW 처리입니다. attached 상태인 VIEW에 순차적으로 푸시하는 대신 동시에 푸시하도록 활성화할지 여부입니다.", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "객체 스토리지 동시성입니다. 파일 처리를 위한 최대 동시 스레드 수입니다.", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "최대 파일 수입니다. 단일 삽입 배치에서 처리할 최대 파일 수입니다.", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "최대 삽입 바이트 수입니다. 단일 삽입 배치에서 처리할 바이트 수입니다.", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "객체 스토리지 폴링 인터벌입니다. 새 객체 스토리지 데이터를 연속 수집할 때 조회하는 갱신 인터벌을 구성합니다.", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "cluster function 사용입니다. 분산 처리에 ClickHouse cluster function을 사용할지 여부입니다.", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Streaming 최대 삽입 대기 시간입니다. 데이터를 ClickHouse에 삽입하기 전까지의 최대 대기 시간을 구성합니다.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "상태를 변경하는 명령입니다: 'start', 'stop', 'resync'.", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes용 CPU(밀리코어)입니다.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes용 메모리(GiB)입니다. CPU 코어 수의 4배여야 합니다.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes용 CPU(millicores)입니다.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes용 메모리(GiB)입니다. CPU core 수의 4배여야 합니다.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Reverse Private Endpoint 설명입니다. 최대 길이는 255자입니다.", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK cluster authentication 유형입니다. MSK_MULTI_VPC 유형에 필요합니다.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK 클러스터 ARN입니다. MSK_MULTI_VPC 유형에 필요합니다.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Reverse Private Endpoint 유형입니다.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC 엔드포인트 서비스 이름입니다.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC 리소스 구성 ID입니다. VPC_RESOURCE 유형에 필요합니다.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC 리소스 공유 ARN입니다. VPC_RESOURCE 유형에 필요합니다.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "액세스 키 ID (HMAC 키)", + "type": "string" + }, + "bucketPath": { + "description": "버킷 경로", + "type": "string" + }, + "bucketProvider": { + "description": "버킷 제공자", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "고유한 Backup 버킷 ID", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "Access Key ID (HMAC 키)", + "type": "string" + }, + "bucketPath": { + "description": "버킷 경로", + "type": "string" + }, + "bucketProvider": { + "description": "버킷 제공업체", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Secret Access Key (HMAC secret key)", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "액세스 키 ID (HMAC 키)", + "type": "string" + }, + "bucketPath": { + "description": "버킷 경로", + "type": "string" + }, + "bucketProvider": { + "description": "버킷 제공자", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Secret Access Key (HMAC secret key)", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "액세스 키 ID (HMAC 키)", + "type": "string" + }, + "bucketPath": { + "description": "버킷 경로", + "type": "string" + }, + "bucketProvider": { + "description": "버킷 제공자", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Private endpoint가 위치한 클라우드 제공업체입니다.", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Private endpoint에 대한 설명입니다.", + "type": "string" + }, + "id": { + "description": "Private endpoint 식별자입니다.", + "type": "string" + }, + "region": { + "description": "Private endpoint가 위치한 Region입니다.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "추가할 요소입니다. \"remove\" 부분이 처리된 후 실행됩니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "제거할 요소입니다. \"add\" 부분이 처리되기 전에 실행됩니다.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "허용된 origin을 도메인의 쉼표로 구분된 목록으로 지정합니다.", + "type": "string" + }, + "openApiKeys": { + "description": "서비스 쿼리 endpoint의 버전입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "역할", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "초대가 생성된 시각입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "초대된 사용자의 이메일입니다. 이 이메일을 가진 사용자만 초대를 통해 참여할 수 있습니다. 이메일은 소문자 형식으로 저장됩니다.", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "초대가 만료되는 시각입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "고유한 초대 ID입니다.", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "조직 내 구성원의 역할입니다.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "초대된 사용자의 이메일입니다. 이 이메일 주소를 가진 사용자만 초대를 사용해 참여할 수 있습니다. 이메일은 소문자 형식으로 저장됩니다.", + "format": "email", + "type": "string" + }, + "role": { + "description": "organization 내 멤버의 역할입니다.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "액세스를 허용할 IPv4 주소 또는 IPv4 CIDR에 대한 선택적 설명", + "type": "string" + }, + "source": { + "description": "IP 또는 CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "추가할 요소입니다. \"remove\" 부분이 처리된 후 실행됩니다.", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "제거할 요소입니다. \"add\" 부분이 처리되기 전에 실행됩니다.", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "개인 사용자 프로필에 설정된 구성원 이메일입니다.", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "구성원이 조직에 참여한 시각입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "개인 사용자 프로필에 설정된 구성원 이름입니다.", + "type": "string" + }, + "role": { + "description": "조직 내 구성원의 역할입니다.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "고유한 사용자 ID입니다. 사용자가 여러 조직의 구성원인 경우에도 이 ID는 동일하게 유지됩니다.", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "organization 내 멤버의 역할입니다.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "IAM 액세스 키 ID.", + "type": "string" + }, + "secretKey": { + "description": "IAM 시크릿 키.", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "조직의 BYOC 구성", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "조직이 생성된 timestamp입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "고유한 조직 ID입니다.", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "조직 이름입니다.", + "type": "string" + }, + "privateEndpoints": { + "description": "조직의 Private Endpoint 목록", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "AWS(Service Name) 또는 GCP(Target Service) 리소스를 사용해 VPC에 생성한 interface endpoint의 고유 식별자", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Private Endpoint가 위치한 클라우드 제공업체", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Private Endpoint에 대한 선택적 설명", + "type": "string" + }, + "id": { + "description": "Private Endpoint 식별자", + "type": "string" + }, + "region": { + "description": "Private Endpoint가 위치한 리전", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "조직의 이름입니다.", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Private Endpoint가 위치한 클라우드 제공업체", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Private Endpoint 설명", + "type": "string" + }, + "id": { + "description": "Private Endpoint 식별자", + "type": "string" + }, + "region": { + "description": "Private Endpoint가 위치한 리전", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "추가할 요소입니다. \"remove\" 부분이 처리된 후 실행됩니다. Private Endpoint를 수정하려면 대신 `Update Service Basic Details` endpoint를 사용하십시오.", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "제거할 요소입니다. \"add\" 부분이 처리되기 전에 실행됩니다.", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "비밀번호.", + "type": "string" + }, + "username": { + "description": "사용자 이름.", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "AWS(Service Name), GCP(Target Service) 또는 AZURE(Private Link Service) 리소스로 VPC에 생성한 인터페이스 endpoint의 고유 식별자입니다.", + "type": "string" + }, + "privateDnsHostname": { + "description": "생성한 VPC의 Private DNS 호스트명입니다.", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Reverse private endpoint 설명입니다. 최대 길이는 255자입니다.", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "Reverse private endpoint의 내부 DNS 이름입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "Reverse private endpoint의 엔드포인트 ID입니다.", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "Reverse private endpoint ID입니다.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK cluster authentication 유형입니다. MSK_MULTI_VPC 유형에 필요합니다.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK cluster ARN입니다. MSK_MULTI_VPC 유형에 필요합니다.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "Reverse private endpoint의 Private DNS 이름입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "Reverse private endpoint에 연결된 ClickHouse 서비스 ID입니다.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Reverse private endpoint 상태입니다.", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "Reverse private endpoint 유형입니다.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC 엔드포인트 서비스 이름입니다.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC 리소스 구성 ID입니다. VPC_RESOURCE 유형에 필요합니다.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC 리소스 공유 ARN입니다. VPC_RESOURCE 유형에 필요합니다.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "private endpoint 설명", + "type": "string" + }, + "id": { + "description": "private endpoint 식별자", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "서비스에 연결할 수 있는 사용 가능한 private endpoint ID 목록", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Bring Your Own Cloud (BYOC)용 리전을 설정한 후 반환되는 ID입니다. byocId 매개변수를 지정하는 경우, minReplicaMemoryGb 및 maxReplicaGb 매개변수도 필요하며 값은 다음 크기 중 하나여야 합니다: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "서비스의 ClickHouse 버전입니다.", + "type": "string" + }, + "complianceType": { + "description": "서비스의 규제 컴플라이언스 유형입니다.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "서비스 생성 timestamp입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "이 서비스를 포함하는 데이터 warehouse", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "디스크 암호화에 사용할 선택 사항인 Role", + "type": "string" + }, + "encryptionKey": { + "description": "선택 사항인 고객 제공 디스크 암호화 키", + "type": "string" + }, + "encryptionRoleId": { + "description": "암호화에 사용되는 IAM role ID입니다. hasTransparentDataEncryption이 true인 경우에만 사용할 수 있습니다.", + "type": "string" + }, + "endpoints": { + "description": "모든 서비스 endpoint 목록입니다.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "서비스에서 Transparent Data Encryption (TDE)을 활성화해야 하면 true입니다. TDE는 ENTERPRISE organization tier에서만 사용할 수 있으며 서비스 생성 시에만 활성화할 수 있습니다.", + "type": "boolean" + }, + "iamRole": { + "description": "S3의 객체에 접근하는 데 사용되는 IAM role", + "type": "string" + }, + "id": { + "description": "고유한 서비스 ID입니다.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "true로 설정하면 유휴 상태일 때 서비스가 0까지 스케일 다운될 수 있습니다. 기본값은 true입니다.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "최소 유휴 timeout(분)을 설정합니다. 5분 이상이어야 합니다.", + "type": "number" + }, + "ipAccessList": { + "description": "서비스에 대한 접근이 허용된 IP 주소 목록", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "이 서비스가 데이터 warehouse의 기본 서비스이면 true입니다.", + "type": "boolean" + }, + "isReadonly": { + "description": "이 서비스가 읽기 전용이면 true입니다. dataWarehouseId가 제공된 경우에만 읽기 전용일 수 있습니다.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "자동 스케일링 중 각 레플리카의 최대 총 메모리(GB)입니다. 4의 배수여야 하며, 유료가 아닌 서비스는 120* 이하여야 하고 유료 서비스는 356* 이하여야 합니다. * 최대 레플리카 크기는 선택한 리전에서 클라우드 제공업체 하드웨어 가용성에 따라 달라집니다. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "더 이상 사용되지 않습니다. 기본값이 아닌 개수의 레플리카를 사용하는 서비스에서는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최대 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수이면서, 유료가 아닌 서비스는 360 이하여야 하고 유료 서비스는 1068 이하여야 합니다.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "자동 스케일링 중 각 레플리카의 최소 총 메모리(GB)입니다. 4의 배수이면서 8 이상이어야 합니다.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "더 이상 사용되지 않습니다. 기본값이 아닌 개수의 레플리카를 사용하는 서비스에서는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최소 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수이면서 24 이상이어야 합니다.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "서비스 이름입니다. 공백을 포함할 수 있는 최대 50자의 영숫자 문자열입니다.", + "type": "string" + }, + "numReplicas": { + "description": "서비스의 레플리카 수입니다. warehouse의 첫 번째 서비스는 레플리카 수가 2~20개여야 합니다. 기존 warehouse에 생성되는 서비스는 레플리카 수를 1개까지 설정할 수 있습니다. organization tier에 따라 추가 제한이 적용될 수 있습니다. 기본값은 BASIC tier에서 1, SCALE 및 ENTERPRISE tier에서 3입니다.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "private endpoint 목록", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "사용자 지정 instance profile입니다. ENTERPRISE organization tier에서만 사용할 수 있습니다.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "클라우드 제공업체", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "서비스 리전입니다.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "새 ClickHouse releases를 제공되는 즉시 받으려면 fast를 선택하십시오. 새 기능을 더 빠르게 사용할 수 있지만 버그 위험은 더 높습니다. 릴리스를 늦춰 테스트 시간을 더 확보하려면 slow를 선택하십시오. 이 기능은 production 서비스에서만 사용할 수 있습니다. 기본값은 정기 릴리스 채널입니다.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "서비스의 현재 상태입니다.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC, SCALE 및 ENTERPRISE organization tier에서는 더 이상 사용되지 않습니다. 서비스 tier는 다음과 같습니다: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Production 서비스는 스케일링되며, Development는 크기가 고정됩니다. Azure 서비스는 Development tier를 지원하지 않습니다.", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "서비스에 사용되는 Transparent Data Encryption 키 ID입니다. hasTransparentDataEncryption이 true인 경우에만 사용할 수 있습니다.", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "서비스 호스트 이름", + "type": "string" + }, + "port": { + "description": "포트 번호", + "type": "number" + }, + "protocol": { + "description": "엔드포인트 프로토콜: 'https', 'nativesecure', 'mysql'.", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "엔드포인트용 선택적 사용자 이름", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "endpoint를 활성화하거나 비활성화합니다.", + "type": "boolean" + }, + "protocol": { + "description": "endpoint 프로토콜입니다.", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "MySQL protocol용 선택적 double SHA1 password hash입니다. newPasswordHash가 제공되지 않으면 이 key는 무시되고 생성된 password가 사용됩니다. 알고리즘: echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "선택적 password hash입니다. 네트워크를 통한 password 전송을 피하는 데 사용됩니다. 제공하지 않으면 새 password가 생성되어 응답에 포함됩니다. 제공하면 이 hash가 사용됩니다. 알고리즘: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "새 서비스 password입니다. 요청에 'newPasswordHash'가 없는 경우에만 제공됩니다.", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "변경할 서비스 endpoint 목록", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "서비스 이름입니다. 공백을 포함할 수 있는 최대 50자의 영숫자 문자열입니다.", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "새 ClickHouse releases를 제공되는 즉시 받으려면 fast를 선택하십시오. 새 기능을 더 빠르게 사용할 수 있지만 버그 위험이 더 높습니다. 릴리스를 미뤄 테스트 시간을 더 확보하려면 slow를 선택하십시오. 이 기능은 'production' 서비스에서만 사용할 수 있습니다. 기본값은 정기 릴리스 채널입니다.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "교체할 key의 ID", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "새 서비스의 초기 상태로 사용할 수 있는 선택적 Backup ID입니다. 이 값을 사용하면 새 instance의 Region과 tier는 원본 instance의 값과 같아야 합니다.", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "Bring Your Own Cloud (BYOC)에 사용할 Region을 설정한 후 반환되는 ID입니다. byocId 매개변수를 지정하면 minReplicaMemoryGb 및 maxReplicaGb 매개변수도 함께 지정해야 하며, 값은 다음 크기 중 하나여야 합니다: 48, 116, 172, 232.", + "type": "string" + }, + "complianceType": { + "description": "서비스의 규제 컴플라이언스 유형입니다.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "이 서비스가 포함된 데이터 warehouse입니다.", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "디스크 암호화에 사용할 선택적 역할입니다.", + "type": "string" + }, + "encryptionKey": { + "description": "선택적으로 고객이 제공하는 디스크 암호화 키입니다.", + "type": "string" + }, + "endpoints": { + "description": "활성화하거나 비활성화할 서비스 endpoints 목록", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "서비스에서 Transparent Data Encryption (TDE)을 활성화해야 하면 true입니다. TDE는 ENTERPRISE organization tier에서만 사용할 수 있으며, 서비스 생성 시에만 활성화할 수 있습니다.", + "type": "boolean" + }, + "idleScaling": { + "description": "true로 설정하면 유휴 상태일 때 서비스를 0까지 축소할 수 있습니다. 기본값은 true입니다.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "최소 유휴 상태 전환 timeout(분)을 설정합니다. 5분 이상이어야 합니다.", + "type": "number" + }, + "ipAccessList": { + "description": "서비스에 액세스할 수 있도록 허용된 IP 주소 목록", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "이 서비스가 읽기 전용이면 true입니다. dataWarehouseId가 제공된 경우에만 읽기 전용일 수 있습니다.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "자동 스케일링 중 각 레플리카의 최대 총 메모리(Gb)입니다. 4의 배수여야 하며, 무료 서비스는 120* 이하, 유료 서비스는 356* 이하여야 합니다. * - 최대 레플리카 크기는 선택한 Region에서 클라우드 제공업체 하드웨어의 가용성에 따라 달라집니다. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "더 이상 사용되지 않음 - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최대 메모리(Gb)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며, 무료 서비스는 360 이하, 유료 서비스는 1068 이하여야 합니다.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "자동 스케일링 중 각 레플리카의 최소 총 메모리(Gb)입니다. 4의 배수여야 하며 8 이상이어야 합니다.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "더 이상 사용되지 않음 - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최소 메모리(Gb)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며 24 이상이어야 합니다.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "서비스 이름입니다. 공백을 포함할 수 있는 최대 50자의 영숫자 문자열입니다.", + "type": "string" + }, + "numReplicas": { + "description": "서비스의 레플리카 수입니다. warehouse의 첫 번째 서비스는 레플리카 수가 2~20 사이여야 합니다. 기존 warehouse에서 생성되는 서비스는 레플리카 수를 최소 1까지 설정할 수 있습니다. 조직의 tier에 따라 추가 제한이 적용될 수 있습니다. 기본값은 BASIC tier에서 1, SCALE 및 ENTERPRISE tier에서 3입니다.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "서비스를 private endpoints와 연결하려면 먼저 서비스를 생성한 다음 `Update Service Basic Details` endpoint를 사용해 private endpoints를 수정하십시오.", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "비공개 프리뷰 약관에 동의합니다. 비공개 프리뷰의 경우 조직에서 첫 번째 서비스를 생성할 때만 필요합니다.", + "type": "boolean" + }, + "profile": { + "description": "사용자 지정 인스턴스 프로필입니다. ENTERPRISE 조직 tier에서만 사용할 수 있습니다.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "클라우드 제공업체", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "서비스 Region입니다.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "새 ClickHouse releases를 제공되는 즉시 받으려면 fast를 선택하십시오. 새 기능을 더 빨리 사용할 수 있지만 버그가 발생할 위험은 더 높습니다. 테스트 시간을 더 확보하려면 slow를 선택해 release를 늦출 수 있습니다. 이 기능은 production 서비스에서만 사용할 수 있습니다. 기본값은 정기 릴리스 채널입니다.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC, SCALE 및 ENTERPRISE organization tier에서는 더 이상 사용되지 않습니다. 서비스 tier: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Production 서비스는 스케일링되며 Development는 고정 크기입니다. Azure 서비스는 Development tier를 지원하지 않습니다.", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "새로 생성된 서비스의 비밀번호입니다.", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "허용된 origin을 도메인 목록으로 지정하며, 각 항목은 쉼표로 구분됩니다.", + "type": "string" + }, + "id": { + "description": "서비스 query endpoint의 ID입니다.", + "type": "string" + }, + "openApiKeys": { + "description": "서비스 query endpoint에 접근할 수 있는 OpenAPI keys 목록입니다.", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "서비스 query endpoint에 접근할 수 있는 역할 목록입니다.", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "true로 설정하면 서비스는 유휴 상태일 때 0까지 스케일 다운할 수 있습니다. 기본값은 True입니다.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "최소 유휴 상태 전환 timeout(분)을 설정합니다. 5분 이상이어야 합니다.", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "단일 레플리카의 최대 자동 스케일링 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 4의 배수여야 하며, 무료 서비스는 120 이하여야 하고 유료 서비스는 356 이하여야 합니다.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "단일 레플리카의 최소 자동 스케일링 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 4의 배수여야 하며 8 이상이어야 합니다.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "서비스의 레플리카 수입니다. 웨어하우스의 첫 번째 서비스는 레플리카 수가 2개 이상 20개 이하여야 합니다. 기존 웨어하우스에서 생성되는 서비스는 레플리카 수를 1개까지 설정할 수 있습니다. 조직 tier에 따라 추가 제한이 적용될 수 있습니다. 기본값은 BASIC tier에서 1, SCALE 및 ENTERPRISE tier에서 3입니다.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "true로 설정하면 유휴 상태일 때 서비스를 0까지 축소할 수 있습니다. 기본값은 true입니다.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "최소 유휴 timeout(분)을 설정합니다. 5분 이상이어야 합니다.", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최대 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며, 유료가 아닌 서비스는 360 이하, 유료 서비스는 1068 이하여야 합니다.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최소 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며 24 이상이어야 합니다.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "서비스의 레플리카 수입니다. warehouse의 첫 번째 서비스는 레플리카 수가 2개에서 20개 사이여야 합니다. 기존 warehouse에 생성되는 서비스는 레플리카 수를 최소 1개까지 설정할 수 있습니다. 추가 제한은 organization의 tier에 따라 적용될 수 있습니다. 기본값은 BASIC tier는 1, SCALE 및 ENTERPRISE tiers는 3입니다.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "서비스에 연결할 수 있는 private endpoint ID 목록", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Bring Your Own Cloud(BYOC)의 Region을 설정한 후 반환되는 ID입니다. byocId 매개변수를 지정하면 minReplicaMemoryGb 및 maxReplicaGb 매개변수도 반드시 지정해야 하며, 값은 다음 크기 중 하나여야 합니다: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "서비스의 ClickHouse 버전입니다.", + "type": "string" + }, + "complianceType": { + "description": "서비스에 적용되는 규제 컴플라이언스 유형입니다.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "서비스 생성 timestamp입니다. ISO-8601 형식입니다.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "이 서비스를 포함하는 데이터 웨어하우스", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "디스크 암호화에 사용할 선택 사항 role입니다.", + "type": "string" + }, + "encryptionKey": { + "description": "선택 사항인 고객 제공 디스크 암호화 key입니다.", + "type": "string" + }, + "encryptionRoleId": { + "description": "암호화에 사용되는 IAM role ID입니다. hasTransparentDataEncryption이 true인 경우에만 사용할 수 있습니다.", + "type": "string" + }, + "endpoints": { + "description": "모든 서비스 endpoint 목록입니다.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "서비스에서 Transparent Data Encryption(TDE) 기능을 활성화해야 하면 True입니다. TDE는 ENTERPRISE 조직 tier에서만 사용할 수 있으며 서비스 생성 시에만 활성화할 수 있습니다.", + "type": "boolean" + }, + "iamRole": { + "description": "S3의 객체에 접근하는 데 사용되는 IAM role입니다.", + "type": "string" + }, + "id": { + "description": "고유한 서비스 ID입니다.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "true로 설정하면 유휴 상태일 때 서비스를 0까지 축소할 수 있습니다. 기본값은 true입니다.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "최소 유휴 timeout(분)을 설정합니다. 5분 이상이어야 합니다.", + "type": "number" + }, + "ipAccessList": { + "description": "서비스에 대한 접근이 허용된 IP 주소 목록입니다.", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "이 서비스가 데이터 웨어하우스의 기본 서비스이면 True", + "type": "boolean" + }, + "isReadonly": { + "description": "이 서비스가 읽기 전용이면 True입니다. dataWarehouseId가 제공된 경우에만 읽기 전용일 수 있습니다.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "단일 레플리카의 최대 자동 스케일링 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 4의 배수여야 하며, 유료가 아닌 서비스는 120 이하, 유료 서비스는 356 이하여야 합니다.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최대 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며, 유료가 아닌 서비스는 360 이하, 유료 서비스는 1068 이하여야 합니다.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "단일 레플리카의 최소 자동 스케일링 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 4의 배수여야 하며 8 이상이어야 합니다.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - 기본값이 아닌 레플리카 수를 사용하는 서비스에는 정확하지 않습니다. 자동 스케일링 중 3개 worker의 최소 메모리(GB)입니다. 'production' 서비스에서만 사용할 수 있습니다. 12의 배수여야 하며 24 이상이어야 합니다.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "서비스 이름입니다. 공백을 포함할 수 있는 최대 50자의 영숫자 문자열입니다.", + "type": "string" + }, + "numReplicas": { + "description": "서비스의 레플리카 수입니다. warehouse의 첫 번째 서비스는 레플리카 수가 2개에서 20개 사이여야 합니다. 기존 warehouse에 생성되는 서비스는 레플리카 수를 최소 1개까지 설정할 수 있습니다. 추가 제한은 organization의 tier에 따라 적용될 수 있습니다. 기본값은 BASIC tier는 1, SCALE 및 ENTERPRISE tiers는 3입니다.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "private endpoint 목록", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "사용자 지정 인스턴스 프로필입니다. ENTERPRISE 조직 tier에서만 사용할 수 있습니다.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "클라우드 제공업체", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "서비스 Region입니다.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "새 ClickHouse 릴리스를 제공되는 즉시 받으려면 fast를 선택하십시오. 새 기능을 더 빨리 사용할 수 있지만 버그 위험이 더 높습니다. 릴리스를 미뤄 테스트할 시간을 더 확보하려면 slow를 선택하십시오. 이 기능은 'production' 서비스에서만 사용할 수 있습니다. 기본값은 정기 릴리스 채널입니다.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "서비스의 현재 state입니다.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "BASIC, SCALE 및 ENTERPRISE organization tiers에서는 DEPRECATED입니다. 서비스의 tier입니다: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Production 서비스는 스케일링되며 Development는 고정 크기입니다. Azure 서비스는 Development tier를 지원하지 않습니다.", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "서비스에 사용되는 Transparent Data Encryption 키 ID입니다. hasTransparentDataEncryption이 true인 경우에만 사용할 수 있습니다.", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "state를 변경하는 명령입니다: 'start', 'stop'.", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "ClickHouse Credits(CHCs)의 총 사용 비용입니다.", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "ClickHouse Credits(CHCs) 기준 Backup 비용입니다. dataWarehouse 엔터티에 적용됩니다.", + "type": "number" + }, + "computeCHC": { + "description": "ClickHouse Credits(CHCs) 기준 컴퓨트 비용입니다. service 및 clickpipe 엔터티에 적용됩니다.", + "type": "number" + }, + "dataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 데이터 전송 비용입니다. clickpipe 엔터티에 적용됩니다.", + "type": "number" + }, + "initialLoadCHC": { + "description": "ClickHouse Credits(CHCs) 기준 초기 적재 및 resync 비용입니다. clickpipe 엔터티에 적용됩니다.", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 tier1 리전 간 데이터 전송 비용입니다. service 엔터티에 적용됩니다.", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 tier2 리전 간 데이터 전송 비용입니다. service 엔터티에 적용됩니다.", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 tier3 리전 간 데이터 전송 비용입니다. service 엔터티에 적용됩니다.", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 tier4 리전 간 데이터 전송 비용입니다. service 엔터티에 적용됩니다.", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "ClickHouse Credits(CHCs) 기준 데이터 전송 비용입니다. service 엔터티에 적용됩니다.", + "type": "number" + }, + "storageCHC": { + "description": "ClickHouse Credits(CHCs) 기준 Storage 비용입니다. dataWarehouse 엔터티에 적용됩니다.", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "이 엔터티가 속한 dataWarehouse의 ID 또는 엔터티 자체가 dataWarehouse인 경우 해당 ID입니다.", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "사용 날짜입니다. UTC 시간대를 기준으로 하는 ISO-8601 형식의 날짜입니다.", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "엔터티의 고유 ID입니다.", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "엔터티의 이름입니다.", + "type": "string" + }, + "entityType": { + "description": "엔터티의 유형입니다.", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "true이면 이 레코드는 변경할 수 없습니다. 잠금이 설정될 때까지 잠금 해제된 레코드는 변경될 수 있습니다.", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "이 엔터티가 속한 service의 ID 또는 엔터티 자체가 service인 경우 해당 ID입니다. dataWarehouse 엔터티에는 null로 설정됩니다.", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "이 엔터티의 ClickHouse Credits(CHCs) 총 사용 비용입니다.", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "ClickHouse Cloud 콘솔에서 발급받은 key ID와 key secret을 사용합니다: https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "요청의 API Key와 연결된 단일 조직이 포함된 목록을 반환합니다.", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "사용 가능한 조직 목록 조회", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "단일 organization의 세부 정보를 반환합니다. 세부 정보를 가져오려면 auth key가 해당 organization에 속해야 합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 상세 정보 조회", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "organization field를 업데이트합니다. 관리자 ADMIN auth key role이 필요합니다.", + "parameters": [ + { + "description": "업데이트할 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 상세 정보 업데이트", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "모든 organization 활동 목록을 반환합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "검색 시작 날짜입니다.", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "검색 종료 날짜입니다.", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 활동 목록", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "ID로 organization 활동 1건을 반환합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 활동의 ID입니다.", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 활동", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "조직에 새 BYOC 인프라를 생성합니다. 새로 생성된 인프라의 구성을 반환합니다.", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "BYOC 인프라 생성", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "조직에서 BYOC 인프라를 제거합니다.", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 BYOC 인프라의 ID", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "BYOC 인프라 제거", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "모든 조직 초대 목록을 반환합니다.", + "parameters": [ + { + "description": "요청된 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "모든 초대 조회", + "tags": [ + "User management" + ] + }, + "post": { + "description": "조직 초대를 생성합니다.", + "parameters": [ + { + "description": "사용자를 초대할 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "초대 생성", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "organization 초대 1건을 삭제합니다.", + "parameters": [ + { + "description": "초대가 있는 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 초대 삭제", + "tags": [ + "User management" + ] + }, + "get": { + "description": "단일 조직 초대의 세부 정보를 반환합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "초대 세부 정보 조회", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "조직의 모든 키 목록을 반환합니다.", + "parameters": [ + { + "description": "요청한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "모든 키 목록 조회", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "새 API Key를 생성합니다.", + "parameters": [ + { + "description": "키를 소유할 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "키 생성", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "API Key를 삭제합니다. 현재 활성 요청을 인증하는 데 사용되지 않은 키만 삭제할 수 있습니다.", + "parameters": [ + { + "description": "키를 소유한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "삭제할 키의 ID입니다.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버가 클라이언트 오류로 간주한 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "키 삭제", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "단일 키의 세부 정보를 반환합니다.", + "parameters": [ + { + "description": "요청한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 키의 ID입니다.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "키 상세 정보 조회", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "API Key 속성을 업데이트합니다.", + "parameters": [ + { + "description": "키를 소유한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "업데이트할 키의 ID입니다.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버가 클라이언트 오류로 간주한 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "키 업데이트", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "조직의 모든 멤버 목록을 반환합니다.", + "parameters": [ + { + "description": "요청된 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버가 클라이언트 오류로 간주한 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 멤버 목록", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "조직에서 사용자를 제거합니다.", + "parameters": [ + { + "description": "요청된 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청된 사용자의 ID.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 멤버 제거", + "tags": [ + "User management" + ] + }, + "get": { + "description": "조직 멤버 1명의 상세 정보를 반환합니다.", + "parameters": [ + { + "description": "멤버가 속한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청된 사용자의 ID입니다.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버가 클라이언트 오류로 간주한 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "멤버 상세 정보 조회", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "조직 멤버의 역할을 업데이트합니다.", + "parameters": [ + { + "description": "멤버가 속한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "patch할 사용자의 ID입니다.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 멤버 업데이트", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "지원 중단되었습니다. 업데이트된 절차는 [문서](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list)를 참조하십시오.", + "parameters": [ + { + "description": "요청된 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "클라우드 제공업체 식별자입니다. aws, gcp 또는 azure 중 하나입니다.", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "특정 클라우드 제공업체 내의 Region 식별자입니다.", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직의 클라우드 제공업체 내 리전에 대한 Private Endpoint 구성 조회", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "organization의 모든 service에 대한 Prometheus 메트릭을 반환합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "필터링된 Prometheus 메트릭 목록을 반환합니다.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 메트릭 조회", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "organization의 모든 service 목록을 반환합니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "resource를 조회할 때 적용할 필터 조건입니다. 현재는 resource tags 기준 필터링만 지원합니다.", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 서비스 목록", + "tags": [ + "Service" + ] + }, + "post": { + "description": "organization에 새 service를 생성하고, 현재 service 상태와 service에 액세스하기 위한 password를 반환합니다. service는 비동기적으로 시작됩니다.", + "parameters": [ + { + "description": "service를 소유할 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "새 서비스 생성", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "service를 삭제합니다. service는 중지된 상태여야 하며, 이 메서드 호출 후 비동기적으로 삭제됩니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "삭제할 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버는 클라이언트 오류로 판단되는 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 삭제", + "tags": [ + "Service" + ] + }, + "get": { + "description": "organization에 속한 service를 반환합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 상세 정보 조회", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "service name 또는 IP 액세스 목록과 같은 기본 service 세부 정보를 업데이트합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "업데이트할 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 기본 정보 업데이트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "service Backup 구성을 반환합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 백업 구성 조회", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "service Backup 구성을 업데이트합니다. 관리자 인증 키 Role이 필요합니다. 속성을 NULL 값으로 설정하면 해당 속성은 기본값으로 재설정됩니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 백업 구성 업데이트", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "service의 모든 백업 목록을 반환합니다. 목록에는 가장 최근 백업이 먼저 표시됩니다.", + "parameters": [ + { + "description": "백업을 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "백업이 생성된 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 백업 목록", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "단일 Backup 정보를 반환합니다.", + "parameters": [ + { + "description": "Backup을 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Backup이 생성된 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청된 Backup의 ID.", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "백업 상세 정보 조회", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**이 엔드포인트는 베타입니다.** API 계약은 안정적이며, 향후 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

ClickPipes 목록을 반환합니다.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipes 목록 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**이 엔드포인트는 베타입니다.** API 계약은 안정적이며, 향후 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

새 ClickPipe를 생성합니다.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 생성할 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 생성", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe를 삭제합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "삭제할 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 삭제", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe를 반환합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe를 업데이트합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 생성할 service의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP status 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 server가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 업데이트", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**이 endpoint는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe의 스케일링 설정을 변경합니다.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "스케일링 설정을 업데이트할 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 스케일링", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe의 고급 설정을 반환합니다.", + "parameters": [ + { + "description": "service를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "설정을 조회할 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 설정 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**이 endpoint는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ClickPipe의 고급 설정을 업데이트합니다. 값은 문자열, 숫자 또는 불리언일 수 있으며, key-value 쌍으로 전송하십시오.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "설정을 업데이트할 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 설정 업데이트", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**이 endpoint는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

ClickPipe를 시작, 중지 또는 resync합니다. ClickPipe를 중지하면 어떤 상태에서든 수집 프로세스가 중지됩니다. 시작은 \"Stopped\" 상태이거나 \"Failed\" 상태인 ClickPipes에서만 허용됩니다. resync는 Postgres 파이프에만 적용되며 어떤 상태에서든 수행할 수 있습니다.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "상태를 업데이트할 ClickPipe의 ID입니다.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "ClickPipe 상태 업데이트", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

DB ClickPipes의 스케일링 설정을 가져옵니다.\n\n인프라는 서비스의 모든 DB ClickPipes에서 공유되며, 초기 적재와 CDC 모두에 사용됩니다. 청구 기준으로 CPU 코어 2개와 RAM 8GB는 1개의 compute unit에 [해당합니다](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc).\n\n**이 endpoint는 최소 1개의 DB ClickPipe가 프로비저닝된 후에 사용할 수 있습니다.**", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "CDC ClickPipes 스케일링 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**이 endpoint는 베타 상태입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

DB ClickPipes의 스케일링 설정을 업데이트합니다.\n\n인프라는 서비스의 모든 DB ClickPipes에서 공유되며, 초기 적재와 CDC 모두에 사용됩니다. 스케일링 설정이 완전히 반영되기까지 몇 분 정도 걸릴 수 있습니다.\n\n청구 기준으로 CPU 코어 2개와 RAM 8GB는 1개의 compute unit에 [해당합니다](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc). organization tier가 변경되면 DB ClickPipes는 이에 맞게 [재조정됩니다](https://clickhouse.com/docs/cloud/manage/billing/overview#compute).\n\n**이 endpoint는 최소 1개의 DB ClickPipe가 프로비저닝된 후에 사용할 수 있습니다.**", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ClickPipe를 소유한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "CDC ClickPipes 스케일링 업데이트", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**이 엔드포인트는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 서비스의 Reverse Private Endpoint 목록을 반환합니다.", + "parameters": [ + { + "description": "서비스를 소유한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpoint를 소유한 서비스의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Reverse Private Endpoint 목록 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**이 엔드포인트는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

새 Reverse Private Endpoint를 생성합니다.", + "parameters": [ + { + "description": "서비스를 소유한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Reverse Private Endpoint를 소유한 서비스의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Reverse Private Endpoint 생성", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**이 endpoint는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ID의 Reverse Private Endpoint를 삭제합니다.", + "parameters": [ + { + "description": "해당 service를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "해당 Reverse Private Endpoint를 소유한 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "삭제할 Reverse Private Endpoint의 ID.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Reverse Private Endpoint 삭제", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**이 endpoint는 베타입니다.** API 계약은 안정적이며, 앞으로 호환되지 않는 변경 사항은 없을 것으로 예상됩니다.

지정된 ID의 Reverse Private Endpoint를 반환합니다.", + "parameters": [ + { + "description": "해당 service를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "해당 Reverse Private Endpoint를 소유한 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "조회할 Reverse Private Endpoint의 ID.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 판단되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Reverse Private Endpoint 조회", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "서비스의 새 password를 설정합니다", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "password를 업데이트할 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 password 업데이트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "새 Private Endpoint를 생성합니다. 이 Private Endpoint는 해당 service 및 organization에 연결됩니다", + "parameters": [ + { + "description": "요청한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Private Endpoint 생성", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "Private Endpoint를 설정하는 데 필요한 정보", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 서비스의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버는 클라이언트 오류로 판단되는 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "Private Endpoint 구성 조회", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "service의 Prometheus 메트릭을 반환합니다.", + "parameters": [ + { + "description": "서비스를 소유한 organization의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 service의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "필터링된 Prometheus 메트릭 목록을 반환합니다.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 인식되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 메트릭 조회", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "서비스의 레플리카별 최소 및 최대 메모리 한도와 유휴 모드 스케일링 동작을 업데이트합니다. 메모리 설정은 \"production\" 서비스에서만 사용할 수 있으며, 8GB부터 시작하는 4의 배수여야 합니다. numReplicas 조정을 활성화하려면 지원팀에 문의하십시오.", + "parameters": [ + { + "description": "서비스를 소유한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "스케일링 매개변수를 업데이트할 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 auto scaling 설정 업데이트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "서비스의 최소 및 최대 총 메모리 한도와 유휴 모드 스케일링 동작을 업데이트합니다. 메모리 설정은 \"production\" 서비스에서만 사용할 수 있으며, 24GB부터 시작하는 12의 배수여야 합니다. numReplicas 조정을 활성화하려면 지원팀에 문의하십시오.", + "parameters": [ + { + "description": "서비스를 소유한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "스케일링 매개변수를 업데이트할 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 auto scaling 설정 업데이트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "이 기능은 Experimental 기능입니다. 사용하려면 지원팀에 문의하십시오.", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 서비스의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버는 클라이언트 오류로 판단되는 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "지정된 instance의 서비스 쿼리 endpoint 삭제", + "tags": [ + "Service" + ] + }, + "get": { + "description": "이 기능은 Experimental 기능입니다. 사용하려면 지원팀에 문의하십시오.", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 서비스의 ID.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "서버는 클라이언트 오류로 판단되는 문제로 인해 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "지정된 instance의 서비스 쿼리 endpoint 조회", + "tags": [ + "Service" + ] + }, + "post": { + "description": "이 기능은 Experimental 기능입니다. 사용하려면 지원팀에 문의하십시오.", + "parameters": [ + { + "description": "요청한 조직의 ID.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "요청한 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "지정된 instance의 서비스 쿼리 endpoint 업서트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "서비스를 시작하거나 중지합니다.", + "parameters": [ + { + "description": "서비스를 소유한 조직의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "상태를 업데이트할 서비스의 ID입니다.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "각 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 사유로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "서비스 상태 업데이트", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "조회한 시간 범위(최대 31일) 동안 해당 organization의 일별 엔터티별 organization 사용 비용 레코드 목록과 총합계를 반환합니다. 요청과 응답의 모든 날짜는 UTC 시간대를 기준으로 계산됩니다.", + "parameters": [ + { + "description": "요청한 organization의 ID입니다.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "보고서의 시작 날짜입니다. 예: 2024-12-19.", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "보고서의 종료 날짜(포함)입니다. 예: 2024-12-20. 이 날짜는 from_date로부터 30일을 초과할 수 없습니다(최대 조회 기간 31일).", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "모든 요청에 할당되는 고유 ID입니다. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "성공적인 응답" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "상세 오류 설명입니다.", + "type": "string" + }, + "status": { + "description": "HTTP 상태 코드입니다.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "클라이언트 오류로 간주되는 문제로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다." + } + }, + "summary": "조직 사용 비용 조회", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/ko/_specs/hyperdx-openapi.json b/ko/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..d48f91ca3 --- /dev/null +++ b/ko/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "데이터에 사용할 집계 함수", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "집계할 필드", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "결과를 그룹화할 필드", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "메트릭 데이터 유형", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "메트릭 이름(메트릭 data source용)", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "이 시리즈의 data source ID", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "Lucene 쿼리 구문의 필터 조건", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "WHERE 절에서 사용하는 쿼리 언어", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "groupBy가 지정된 경우의 그룹화 값", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "첫 번째 시리즈의 값", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "두 번째 시리즈의 값", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "데이터 포인트의 타임스탬프(버킷 시작 시간)", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "밀리초 단위 종료 타임스탬프", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "집계용 시간 버킷 크기", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "시리즈 구성 배열", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "반환 데이터의 포맷", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "밀리초 단위 시작 타임스탬프", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "HyperDX 알림 및 대시보드 관리 API", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "인증된 팀의 모든 알림 목록을 조회합니다", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "알림 목록", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "알림을 성공적으로 조회했습니다" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + } + }, + "summary": "알림 목록 조회", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "새 알림을 생성합니다", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "타일 기반 알림 생성", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "알림을 성공적으로 생성했습니다" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "서버 오류 또는 유효성 검사 실패" + } + }, + "summary": "알림 생성", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "알림을 삭제합니다", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "알림 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "알림을 성공적으로 삭제했습니다" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "알림을 찾을 수 없습니다" + } + }, + "summary": "알림 삭제", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "ID로 특정 알림을 조회합니다", + "operationId": "getAlert", + "parameters": [ + { + "description": "알림 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "단일 알림 응답", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "알림을 성공적으로 조회했습니다" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "알림을 찾을 수 없습니다" + } + }, + "summary": "알림 조회", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "기존 알림을 업데이트합니다", + "operationId": "updateAlert", + "parameters": [ + { + "description": "알림 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "알림 속성 업데이트", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "알림을 성공적으로 업데이트했습니다" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "알림을 찾을 수 없습니다" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "서버 오류 또는 유효성 검사 실패" + } + }, + "summary": "알림 업데이트", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "구성된 시리즈 매개변수를 기반으로 시계열 데이터를 조회합니다", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "기본 시계열 쿼리", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "메트릭 데이터 시리즈", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "group by를 사용한 다중 시리즈", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "여러 소스의 시리즈", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "그룹화된 시계열 데이터", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "시계열 데이터 포인트", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "시계열 데이터를 성공적으로 조회했습니다" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "잘못된 요청 매개변수" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "소스를 찾을 수 없습니다" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "서버 오류" + } + }, + "summary": "차트 시리즈 데이터 쿼리", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "인증된 팀의 모든 대시보드 목록을 조회합니다", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "대시보드를 성공적으로 조회했습니다" + }, + "401": { + "description": "인증되지 않음" + } + }, + "summary": "대시보드 목록 조회", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "새 대시보드를 생성합니다", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "여러 차트 유형이 있는 대시보드", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "시계열 차트가 있는 대시보드", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "생성된 대시보드 응답", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "대시보드를 성공적으로 생성했습니다" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "서버 오류 또는 유효성 검사 실패" + } + }, + "summary": "대시보드 만들기", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "대시보드를 삭제합니다", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "대시보드 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "대시보드가 성공적으로 삭제되었습니다" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "대시보드를 찾을 수 없습니다" + } + }, + "summary": "대시보드 삭제", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "ID로 특정 대시보드를 조회합니다", + "operationId": "getDashboard", + "parameters": [ + { + "description": "대시보드 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "단일 대시보드 응답", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "대시보드를 성공적으로 조회했습니다" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "대시보드를 찾을 수 없습니다" + } + }, + "summary": "대시보드 조회", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "기존 대시보드를 업데이트합니다", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "대시보드 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "대시보드 속성 및 타일 업데이트", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "업데이트된 대시보드 응답", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "대시보드를 성공적으로 업데이트했습니다" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "인증되지 않음" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "대시보드를 찾을 수 없습니다" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "서버 오류 또는 유효성 검사 실패" + } + }, + "summary": "대시보드 업데이트", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "운영 API 서버", + "url": "https://api.hyperdx.io" + }, + { + "description": "현재 서버", + "url": "/" + } + ], + "tags": [ + { + "description": "대시보드 및 해당 시각화를 관리하는 엔드포인트", + "name": "Dashboards" + }, + { + "description": "모니터링 알림을 관리하는 엔드포인트", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/ko/clickstack/features/dashboards/overview.mdx b/ko/clickstack/features/dashboards/overview.mdx index b2658dd32..19bb06c6f 100644 --- a/ko/clickstack/features/dashboards/overview.mdx +++ b/ko/clickstack/features/dashboards/overview.mdx @@ -47,7 +47,7 @@ HyperDX의 **Chart Explorer** 인터페이스를 사용하면 시간 흐름에 아래 예시에서는 서비스 이름별로 시간에 따른 평균 요청 지속 시간을 차트로 표시합니다. 이를 위해서는 메트릭, 컬럼(SQL 표현식일 수 있음), 집계 필드를 지정해야 합니다. - 상단 메뉴에서 `Line/Bar` 시각화 유형을 선택한 다음 `Traces` 데이터셋([play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)을 사용하는 경우 `Demo Traces`)을 선택합니다. 다음 값을 입력합니다: + 상단 메뉴에서 `Line/Bar` 시각화 유형을 선택한 다음 `Traces` 데이터셋(`Demo Traces`는 [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)을 사용하는 경우)을 선택합니다. 다음 값을 입력합니다: * Metric: `Average` * Column: `Duration/1000` @@ -63,6 +63,10 @@ HyperDX의 **Chart Explorer** 인터페이스를 사용하면 시간 흐름에 단순 시각화 2 + 기존 시리즈와 비슷한 시리즈를 만들려면 처음부터 새로 만드는 대신 복제할 수 있습니다. 시리즈 행의 복사 아이콘(`Duplicate series`)을 클릭하면 바로 아래에 복사본이 삽입됩니다. 복사본은 메트릭, 컬럼, 필터 등 원본 시리즈의 설정을 유지합니다. 이후 달라지는 필드만 변경하고(예: 집계) 복사본에 별도의 별칭을 지정하면 됩니다. 복제 기능은 여러 시리즈를 지원하는 모든 곳에서 사용할 수 있습니다. `Number`, `Pie`, `Heatmap`처럼 하나의 시리즈만 허용하는 시각화 유형에서는 이 기능이 표시되지 않습니다. + + 차트 시리즈 행의 Duplicate series 복사 아이콘과 해당 툴팁 + 시각화는 메트릭, 트레이스, 로그 등 모든 데이터 소스에서 만들 수 있습니다. ClickStack은 이 모두를 wide events로 처리합니다. 모든 **numeric column**은 시간에 따라 차트로 표시할 수 있으며, **string**, **date**, **numeric** 컬럼은 그룹화에 사용할 수 있습니다. diff --git a/ko/clickstack/ingesting-data/collector.mdx b/ko/clickstack/ingesting-data/collector.mdx index c9b481330..1258a4c74 100644 --- a/ko/clickstack/ingesting-data/collector.mdx +++ b/ko/clickstack/ingesting-data/collector.mdx @@ -104,7 +104,7 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic - 대상 ClickHouse 인스턴스는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`를 통해 구성됩니다. `CLICKHOUSE_ENDPOINT`에는 프로토콜과 포트를 포함한 전체 ClickHouse Cloud HTTP 엔드포인트를 지정해야 합니다(예시: `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`). + 대상 ClickHouse 인스턴스는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 통해 구성됩니다. `CLICKHOUSE_ENDPOINT`에는 프로토콜과 포트를 포함한 전체 ClickHouse Cloud HTTP 엔드포인트를 지정해야 합니다(예시: `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`). Managed ClickStack 자격 증명을 확인하는 방법에 대한 자세한 내용은 [여기](/ko/products/cloud/guides/sql-console/connection-details)를 참조하십시오. @@ -118,7 +118,7 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic #### Managed ClickStack 인스턴스 설정 - OpenTelemetry collector는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`를 통해 Managed ClickStack 인스턴스를 사용하도록 구성할 수 있습니다. 이 변수들을 설정하는 방법은 배포 방식에 따라 다릅니다. + OpenTelemetry collector는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 통해 Managed ClickStack 인스턴스를 사용하도록 구성할 수 있습니다. 이 변수들을 설정하는 방법은 배포 방식에 따라 다릅니다: @@ -162,7 +162,7 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic Docker Compose를 사용하는 경우 위와 동일한 환경 변수를 사용하여 collector 구성을 수정하십시오: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # health_check 확장 기능 - - '24225:24225' # fluentd 수신기 - - '4317:4317' # OTLP gRPC 수신기 - - '4318:4318' # OTLP HTTP 수신기 - - '8888:8888' # 메트릭 확장 기능 + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver + - '4317:4317' # OTLP gRPC receiver + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,21 +261,21 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic - 대상 ClickHouse 인스턴스는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`를 통해 구성됩니다. `CLICKHOUSE_ENDPOINT`에는 프로토콜과 포트를 포함한 전체 ClickHouse HTTP 엔드포인트를 지정해야 합니다(예: `http://localhost:8123`). + 대상 ClickHouse 인스턴스는 환경 변수 `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 통해 구성됩니다. `CLICKHOUSE_ENDPOINT`에는 프로토콜과 포트를 포함한 전체 ClickHouse HTTP 엔드포인트를 지정해야 합니다(예: `http://localhost:8123`). **이 환경 변수들은 커넥터가 포함된 모든 Docker 배포판에서 사용할 수 있습니다.** - **운영 환경용 사용자** + **운영 환경 사용자** - 운영 환경에서는 [적절한 자격 증명을 갖춘 사용자](/ko/clickstack/ingesting-data/collector#creating-an-ingestion-user)를 사용해야 합니다. + 운영 환경에서는 [적절한 자격 증명](/ko/clickstack/ingesting-data/collector#creating-an-ingestion-user)을 갖춘 사용자를 사용해야 합니다. ### 구성 수정 #### ClickHouse 인스턴스 설정 - OpenTelemetry collector는 환경 변수 `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`를 통해 ClickHouse 인스턴스를 사용하도록 구성할 수 있습니다. 이 변수들을 설정하는 방법은 배포 방식에 따라 다릅니다. + OpenTelemetry collector는 환경 변수 `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 통해 ClickHouse 인스턴스를 사용하도록 구성할 수 있습니다. 이 변수들을 설정하는 방법은 배포 방식에 따라 다릅니다. @@ -322,7 +322,7 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic Docker Compose를 사용하는 경우 위와 동일한 환경 변수를 사용하여 collector 구성을 수정하십시오: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ agent 역할로 OTel collector를 배포하는 사용자는 일반적으로 Clic CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # health_check 확장 기능 - - '24225:24225' # fluentd 수신기 - - '4317:4317' # OTLP gRPC 수신기 - - '4318:4318' # OTLP HTTP 수신기 - - '8888:8888' # 메트릭 확장 기능 + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver + - '4317:4317' # OTLP gRPC receiver + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/ko/clickstack/mcp.mdx b/ko/clickstack/mcp.mdx index 73c79e1c0..b5ab0e4c8 100644 --- a/ko/clickstack/mcp.mdx +++ b/ko/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'ClickStack MCP 서버' sidebarTitle: 'MCP 서버' description: 'Model Context Protocol(MCP) 서버를 통해 AI 어시스턴트를 ClickStack에 연결합니다' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', '관측성', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', '관측성', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -23,108 +23,218 @@ MCP 서버는 다음 ClickStack 배포 유형에서 사용할 수 있습니다: | ------------------------------------------------- | ------ | | **Open Source ClickStack** | 사용 가능 | | **BYOC (Bring Your Own Cloud)** | 사용 가능 | -| **Managed ClickStack** | 출시 예정 | +| **ClickStack on ClickHouse Cloud** | 사용 가능 | | **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | 지원 안 함 | - - **Managed ClickStack** + + **ClickHouse Cloud와 OSS/BYOC의 설정 차이** - Managed ClickStack의 MCP 서버 지원은 현재 개발 중이며 곧 제공될 예정입니다. 이 페이지의 지침은 Open Source 및 BYOC 배포에 적용됩니다. - + ClickStack on ClickHouse Cloud는 Open Source 및 BYOC 배포와 엔드포인트 및 인증 방법이 다릅니다. Cloud 전용 설정은 아래의 [ClickStack on ClickHouse Cloud](#managed-clickstack) 섹션을 참조하십시오. + -
- ## 사전 요구 사항 +
+ ## ClickStack on ClickHouse Cloud
-MCP 클라이언트를 연결하기 전에 다음이 필요합니다: +ClickHouse Cloud의 ClickStack은 Cloud MCP endpoint `https://mcp.clickhouse.cloud/clickstack`를 통해 연결되며, OAuth 2.0으로 인증됩니다. 이 endpoint에서는 API Key 인증이 지원되지 않습니다. -* 실행 중인 ClickStack 인스턴스([배포](/ko/clickstack/deployment/overview)에서 설정 옵션 참조) -* **Personal API Access Key** — HyperDX의 **Team Settings → API Keys → Personal API Access Key**에서 확인할 수 있습니다 +
+ ### 사전 요구 사항 +
-Team Settings의 Personal API Access Key +* [ClickStack이 활성화된](/ko/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud) 실행 중인 ClickHouse Cloud 서비스 +* 서비스에서 [MCP가 활성화되어 있어야 합니다](/ko/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) — Cloud Console을 열고 **Connect**를 클릭한 다음 **Connect with MCP**를 선택한 후 토글을 켜십시오 - - Personal API Access Key는 Team Settings에서 찾을 수 있는 **수집 API key**와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터를 인증하는 데 사용됩니다. - +
+ ### 엔드포인트 +
+ +```text +https://mcp.clickhouse.cloud/clickstack +``` -
- ## 엔드포인트 +인증에는 OAuth 2.0을 사용합니다. MCP client가 처음 연결되면 브라우저 창이 열리며 ClickHouse Cloud 자격 증명으로 로그인할 수 있습니다. API Key는 필요하지 않습니다. + +
+ ### MCP 클라이언트 연결
-MCP 서버는 ClickStack 프론트엔드 URL의 `/api/mcp` 경로에서 이용할 수 있습니다: +각 클라이언트는 처음 연결할 때 OAuth 흐름을 자동으로 처리합니다. -예를 들어, 기본 로컬 배포에서는 다음과 같습니다: + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -기본 설정을 변경한 경우 `localhost:8080`을 인스턴스에 맞는 호스트와 포트로 바꾸십시오. + Claude Code를 실행하고 `/mcp`를 입력한 다음 `clickstack-cloud`를 선택하여 OAuth 흐름을 완료하십시오. + - - 이 페이지의 예시는 프론트엔드 앱 URL(기본 포트 `8080`)을 사용합니다. 백엔드를 통해 `/mcp`로 MCP 서버에 직접 접근할 수도 있지만, 모든 배포에서 백엔드가 노출되는 것은 아니므로 이 문서에서는 프론트엔드 경로를 사용합니다. - + + 다음을 `.cursor/mcp.json`에 추가하십시오. -MCP 서버는 **Bearer token** 인증을 사용하는 **Streamable HTTP** 전송 방식을 사용합니다. + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 다음을 `.vscode/mcp.json`에 추가하십시오. + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 다음을 `opencode.json`에 추가하십시오. + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + OAuth와 **Streamable HTTP**를 지원하는 모든 MCP 클라이언트에서 연결할 수 있습니다. 다음과 같이 구성하십시오. -
- ## MCP 클라이언트 연결하기 + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### 특정 서비스 지정
-아래 예시에서는 널리 사용되는 MCP 클라이언트를 구성하는 방법을 보여줍니다. ``은 인스턴스 URL(예: `http://localhost:8080`)로, ``는 Personal API Access Key로 바꾸십시오. +`x-service-id` 헤더가 없으면 요청은 기본적으로 계정에서 프로비저닝해 사용 중인 첫 번째 ClickStack 서비스로 전송됩니다. 다른 서비스를 지정하려면 MCP 클라이언트 구성의 헤더에 `x-service-id: `를 추가하십시오. -
- ### Claude Code +
+ ## Open Source 및 BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +Open Source 및 BYOC 배포는 ClickStack 인스턴스에 내장된 MCP 엔드포인트를 Bearer token 인증으로 사용합니다. -
- ### Cursor +
+ ### 사전 요구 사항
-프로젝트의 `.cursor/mcp.json` 파일이나 Cursor 전역 설정에 다음 내용을 추가하십시오: +* 실행 중인 ClickStack 인스턴스([배포](/ko/clickstack/deployment/overview)에서 설정 옵션 참조) +* **Personal API Access Key** — HyperDX의 **Team Settings → API Keys → Personal API Access Key**에서 확인할 수 있습니다 -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Team Settings의 Personal API Access Key + + + Personal API Access Key는 Team Settings에서 찾을 수 있는 **수집 API key**와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터를 인증하는 데 사용됩니다. + -
- ### OpenCode +
+ ### 엔드포인트
-다음을 `opencode.json` 설정에 추가하십시오: +MCP 서버는 ClickStack 프론트엔드 URL의 `/api/mcp` 경로에서 이용할 수 있습니다. 예를 들어, 기본 로컬 배포에서는 URL이 `http://localhost:8080/api/mcp`입니다. 기본 설정을 변경한 경우 `localhost:8080`을 인스턴스에 맞는 호스트와 포트로 바꾸십시오. -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + 이 페이지의 예시는 프론트엔드 앱 URL(기본 포트 `8080`)을 사용합니다. 백엔드를 통해 `/mcp`로 MCP 서버에 직접 접근할 수도 있지만, 모든 배포에서 백엔드가 노출되는 것은 아니므로 이 문서에서는 프론트엔드 경로를 사용합니다. + + +MCP 서버는 **Bearer token** 인증을 사용하는 **Streamable HTTP** 전송 방식을 사용합니다. -
- ### 기타 클라이언트 +
+ ### MCP 클라이언트 연결
-**Streamable HTTP** 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다. 다음과 같이 구성하십시오. +``은 인스턴스 URL(예: `http://localhost:8080`)로, ``는 Personal API Access Key로 바꾸십시오. + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + 다음을 `.cursor/mcp.json`에 추가하십시오: + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + 다음을 `.vscode/mcp.json`에 추가하십시오: + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + 다음을 `opencode.json`에 추가하십시오: + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + **Streamable HTTP**를 지원하는 모든 MCP 클라이언트에서 연결할 수 있습니다. 다음과 같이 구성하십시오: -* **URL:** `/api/mcp` -* **헤더:** `Authorization: Bearer ` + * **URL:** `/api/mcp` + * **헤더:** `Authorization: Bearer ` + +
## MCP로 무엇을 할 수 있나요? @@ -143,10 +253,12 @@ claude mcp add --transport http hyperdx /api/mcp \ 제공되는 도구의 구체적인 구성은 시간이 지나면서 확장될 수 있습니다. MCP 클라이언트는 연결 시 사용 가능한 도구를 자동으로 탐색합니다.
- ## 여러 팀 사용 + ## 여러 팀 사용 (OSS/BYOC)
-기본적으로 MCP 요청은 사용자의 기본 팀 컨텍스트에서 실행됩니다. 여러 팀에 속해 있다면 `Authorization` 헤더와 함께 팀 ID로 설정한 `x-hdx-team` 헤더를 전달해 특정 팀을 대상으로 지정할 수 있습니다. 이 헤더를 생략하면 기본 팀이 사용됩니다. 속해 있지 않은 팀을 지정하면 요청이 `401` 오류와 함께 거부됩니다. +이는 Open Source 및 BYOC 배포에만 적용됩니다. ClickStack on ClickHouse Cloud는 [특정 service 지정](#managed-service-override)을 참조하십시오. + +기본적으로 MCP 요청은 사용자의 기본 팀 컨텍스트에서 실행됩니다. 여러 팀에 속해 있다면 `Authorization` 헤더와 함께 팀 ID로 설정한 `x-hdx-team` 헤더를 전달하십시오. 이 헤더를 생략하면 기본 팀이 사용됩니다. 속해 있지 않은 팀을 지정하면 요청이 `401` 오류와 함께 거부됩니다. MCP 클라이언트의 팀 목록 도구를 사용하면 액세스할 수 있는 팀과 현재 활성 상태인 팀을 확인할 수 있습니다. @@ -154,6 +266,29 @@ MCP 클라이언트의 팀 목록 도구를 사용하면 액세스할 수 있는 ## 문제 해결
+
+ ### ClickStack on ClickHouse Cloud +
+ + + * 사용 중인 MCP 클라이언트가 OAuth 2.0을 지원하는지 확인하십시오. Bearer token 또는 stdio 전송만 지원하는 클라이언트는 Cloud 엔드포인트로 인증할 수 없습니다. + * 브라우저가 OAuth 팝업이나 리디렉션을 차단하고 있지 않은지 확인하십시오. + * ClickHouse Cloud 계정에 해당 organization 및 service에 대한 접근 권한이 있는지 확인하십시오. + + + + * 일반 Cloud MCP 엔드포인트(`https://mcp.clickhouse.cloud/mcp`)가 아니라 ClickStack 엔드포인트(`https://mcp.clickhouse.cloud/clickstack`)를 사용하고 있는지 확인하십시오. + * Cloud Console의 service에서 [MCP가 활성화되어 있는지](/ko/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) 확인하십시오. + + + + `x-service-id` header가 없으면 요청은 계정에서 프로비저닝되어 사용된 첫 번째 ClickStack 서비스로 기본 전송됩니다. 특정 service를 대상으로 하려면 해당 header를 전달하십시오. 자세한 내용은 [특정 service 대상 지정](#managed-service-override)을 참조하십시오. + + +
+ ### Open Source 및 BYOC +
+ * **Personal API Access Key**를 사용하고 있는지 확인하십시오(**수집 API key**가 아닙니다). * `Authorization` 헤더에 key가 `Bearer` 토큰으로 포함되어 있는지 확인하십시오. diff --git a/ko/clickstack/navigation.json b/ko/clickstack/navigation.json index dddb304ef..a0d65de9f 100644 --- a/ko/clickstack/navigation.json +++ b/ko/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "ko/_specs/hyperdx-openapi.json", "root": "ko/clickstack/api-reference" } ] diff --git a/ko/concepts/features/operations/update/replacing-merge-tree.mdx b/ko/concepts/features/operations/update/replacing-merge-tree.mdx index 0d02797c0..842a70946 100644 --- a/ko/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/ko/concepts/features/operations/update/replacing-merge-tree.mdx @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --무작위로 100개의 행을 선택 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --임의의 행 100개 선택 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -위 작업의 결과는 16,000행, 즉 10,000 + 5000 + 1000이 됩니다. 하지만 여기서 올바른 합계는 실제로 원래 합계보다 1000행만 적은 값이어야 하므로, 즉 10,000 - 1000 = 9000입니다. +위 작업의 결과는 16,000행, 즉 10,000 + 5000 + 1000이 됩니다. 실제로는 원래 총합보다 1000행만 적어야 하므로, 즉 10,000 - 1000 = 9000이어야 합니다. ```sql SELECT count() @@ -210,7 +210,7 @@ FROM posts_updateable 1 row in set. Elapsed: 0.002 sec. ``` -여기서는 어떤 머지가 발생했는지에 따라 결과가 달라집니다. 중복된 행이 있기 때문에 총계가 다르게 보입니다. 테이블에 `FINAL`을 적용하면 올바른 결과를 얻을 수 있습니다. +어떤 머지가 발생했는지에 따라 결과가 달라집니다. 중복된 행 때문에 총계가 달라집니다. 테이블에 `FINAL`을 적용하면 올바른 결과를 얻을 수 있습니다. ```sql SELECT count() @@ -359,11 +359,11 @@ Exploiting Partitions with ReplacingMergeTree에서 설명했듯이, 모범 사 ### 더 나은 쿼리 성능을 위한 머지 조정
-기본적으로 min_age_to_force_merge_seconds와 min_age_to_force_merge_on_partition_only는 각각 0과 false로 설정되어 있으므로, 이러한 기능은 비활성화됩니다. 이 구성에서는 ClickHouse가 파티션 경과 시간에 따라 머지를 강제하지 않고, 표준 머지 동작을 적용합니다. +기본적으로 `min_age_to_force_merge_seconds`와 `min_age_to_force_merge_on_partition_only`는 각각 0과 false로 설정되어 있으므로, 이러한 기능은 비활성화됩니다. 이 구성에서는 ClickHouse가 파티션 경과 시간에 따라 머지를 강제하지 않고, 표준 머지 동작을 적용합니다. -min_age_to_force_merge_seconds 값을 지정하면 ClickHouse는 지정된 주기보다 오래된 파트에 대해서는 일반적인 머지 휴리스틱을 무시합니다. 이는 대체로 전체 파트 수를 최소화하는 것이 목표일 때에만 효과적이지만, 쿼리 시점에 머지해야 하는 파트 수를 줄여 ReplacingMergeTree의 쿼리 성능을 개선할 수 있습니다. +`min_age_to_force_merge_seconds` 값을 지정하면 ClickHouse는 지정된 주기보다 오래된 파트에 대해서는 일반적인 머지 휴리스틱을 무시합니다. 이는 대체로 전체 파트 수를 최소화하는 것이 목표일 때에만 효과적이지만, 쿼리 시점에 머지해야 하는 파트 수를 줄여 ReplacingMergeTree의 쿼리 성능을 개선할 수 있습니다. -이 동작은 min_age_to_force_merge_on_partition_only=true를 설정해 추가로 세부 조정할 수 있습니다. 이렇게 하면 적극적인 머지를 수행하려면 해당 파티션의 모든 파트가 min_age_to_force_merge_seconds보다 오래되어야 합니다. 이 구성에서는 오래된 파티션이 시간이 지나면서 하나의 파트로 머지될 수 있으므로, 데이터를 통합하고 쿼리 성능을 유지하는 데 도움이 됩니다. +이 동작은 `min_age_to_force_merge_on_partition_only=true`를 설정해 추가로 세부 조정할 수 있습니다. 이렇게 하면 적극적인 머지를 수행하려면 해당 파티션의 모든 파트가 `min_age_to_force_merge_seconds`보다 오래되어야 합니다. 이 구성에서는 오래된 파티션이 시간이 지나면서 하나의 파트로 머지될 수 있으므로, 데이터를 통합하고 쿼리 성능을 유지하는 데 도움이 됩니다. * 파이프를 생성한 후에는 스냅샷 매개변수를 수정할 수 없습니다. 변경하려면 새 ClickPipe를 생성해야 합니다. -* 기존 ClickPipe에 테이블을 추가할 때는 스냅샷 매개변수를 변경할 수 없습니다. 새 테이블에는 기존 매개변수가 적용됩니다. -* partition key 컬럼에는 `NULL` 값이 없어야 합니다. `NULL` 값은 파티셔닝 로직에서 제외됩니다. \ No newline at end of file +* 기존 ClickPipe에 테이블을 추가할 때는 스냅샷 매개변수를 변경할 수 없습니다. 새 테이블에는 기존 매개변수가 적용됩니다. \ No newline at end of file diff --git a/ko/integrations/language-clients/go/config-reference.mdx b/ko/integrations/language-clients/go/config-reference.mdx index 9dbc91d68..debdac4a1 100644 --- a/ko/integrations/language-clients/go/config-reference.mdx +++ b/ko/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### 타임아웃
-| 옵션 | 유형 | 기본값 | DSN 매개변수 | 설명 | 권장 사항 | 잘못 구성된 경우 | -| ------------- | --------------- | ----------- | -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 새 연결을 설정하는 데 허용되는 최대 시간입니다. `MaxOpenConns` 한도에 도달했을 때 풀에서 연결을 획득하기 위해 대기하는 시간도 제어합니다. | LAN에서는 5~~10초, WAN/클라우드에서는 15~~30초를 권장합니다. 1초 미만으로 설정하지 마십시오. | 너무 짧으면 혼잡 시 `"clickhouse: acquire conn timeout"`이 발생합니다. 너무 길면(60초 초과) 장애 발생 시 애플리케이션이 멈춥니다. | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 각 read 호출에서 서버 응답을 기다리는 최대 시간입니다. 전체 쿼리가 아니라 각 블록별로 적용됩니다. Context 마감 시간이 우선합니다. | 짧은 대화형 쿼리에는 10~~30초, 긴 분석 쿼리에는 5~~30분을 권장합니다. | 너무 짧으면 쿼리 실행 도중 `"i/o timeout"` 또는 `"read: connection reset by peer"`가 발생하며, 서버는 계속 실행됩니다. 너무 길면 끊어진 연결을 감지하지 못합니다. | +| 옵션 | 유형 | 기본값 | DSN 매개변수 | 설명 | 권장 사항 | 잘못 구성된 경우 | +| ------------- | --------------- | ----------- | -------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 새 연결을 설정하는 데 허용되는 최대 시간입니다. `MaxOpenConns` 한도에 도달했을 때 풀에서 연결을 획득하기 위해 대기하는 시간도 제어합니다. | LAN에서는 5~~10초, WAN/클라우드에서는 15~~30초, 유휴 상태인 ClickHouse Cloud 서비스에 연결하는 경우에는 1~~2분을 권장합니다. 1초 미만으로 설정하지 마십시오. | 너무 짧으면 혼잡 시 `"clickhouse: acquire conn timeout"`이 발생하거나, 유휴 상태인 Cloud 서비스가 다시 깨어나기 전에 연결이 실패합니다. 너무 길면(60초 초과) 장애 발생 시 애플리케이션이 멈춥니다. | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 각 read 호출에서 서버 응답을 기다리는 최대 시간입니다. 전체 쿼리가 아니라 각 블록별로 적용됩니다. Context 마감 시간이 우선합니다. | 짧은 대화형 쿼리에는 10~~30초, 긴 분석 쿼리에는 5~~30분을 권장합니다. | 너무 짧으면 쿼리 실행 도중 `"i/o timeout"` 또는 `"read: connection reset by peer"`가 발생하며, 서버는 계속 실행됩니다. 너무 길면 끊어진 연결을 감지하지 못합니다. | + + + 유휴 상태였던 ClickHouse Cloud 서비스는 일시 중지되며, 첫 번째 인바운드 연결이 들어오면 다시 깨어납니다. 일반적으로 다시 깨어나는 데는 수십 초가 걸리며, 이 동안 dial이 차단됩니다. `DialTimeout`이 다시 깨어나는 시간보다 짧으면 유휴 기간 이후 첫 번째 쿼리는 실행되지 않고 dial timeout으로 실패합니다. + + 유휴 상태인 서비스에 가장 먼저 연결할 수 있는 클라이언트의 경우 `DialTimeout`을 `1m`–`2m`로 설정하십시오. 그 대신 실제 장애 상황에서는 실패 감지가 더 느려집니다. 즉, 오류를 반환하기 전까지 dial이 전체 타임아웃 동안 차단됩니다. 따라서 더 높은 타임아웃은 첫 연결에만 적용하거나, 개별 쿼리에 context deadline을 사용해 종단 간 지연 시간을 제한하는 방식을 권장합니다. + *** diff --git a/ko/integrations/language-clients/go/configuration.mdx b/ko/integrations/language-clients/go/configuration.mdx index fe9cf86db..f14571c71 100644 --- a/ko/integrations/language-clients/go/configuration.mdx +++ b/ko/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: 'reference' 연결을 열 때 `Options` 구조체를 사용해 클라이언트 동작을 제어할 수 있습니다. 사용할 수 있는 설정은 다음과 같습니다. -| Parameter | Type | Default | Description | -| ---------------------- | -------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `Protocol` | `Protocol` | `Native` | 전송 프로토콜입니다: `Native`(TCP) 또는 `HTTP`. [TCP vs HTTP](#tcp-vs-http)를 참조하십시오. | -| `Addr` | `[]string` | — | `host:port` 주소 슬라이스입니다. 여러 노드에 연결하는 방법은 [여러 노드에 연결](#connecting-to-multiple-nodes)을 참조하십시오. | -| `Auth` | `Auth` | — | 인증 자격 증명(`Database`, `Username`, `Password`)입니다. [Authentication](#authentication)을 참조하십시오. | -| `TLS` | `*tls.Config` | `nil` | TLS 구성입니다. `nil`이 아닌 값이면 TLS가 활성화됩니다. [TLS](#using-tls)를 참조하십시오. | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | TCP 연결을 설정하는 방식을 제어하는 사용자 지정 dial 함수입니다. | -| `DialTimeout` | `time.Duration` | `30s` | 새 연결을 열 때까지 기다리는 최대 시간입니다. | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 동시에 열어 둘 수 있는 최대 연결 수입니다. | -| `MaxIdleConns` | `int` | `5` | 연결 풀에 유지할 유휴 연결 수입니다. | -| `ConnMaxLifetime` | `time.Duration` | `1h` | 연결 풀의 연결이 유지될 수 있는 최대 시간입니다. [연결 풀링](#connection-pooling)을 참조하십시오. | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | `Addr`에서 노드를 선택하는 전략입니다. [여러 노드에 연결](#connecting-to-multiple-nodes)을 참조하십시오. | -| `BlockBufferSize` | `uint8` | `2` | 병렬로 디코딩할 블록 수입니다. 값을 높이면 메모리 사용량이 증가하는 대신 처리량이 늘어납니다. `context`를 통해 쿼리별로 재정의할 수 있습니다. | -| `Settings` | `Settings` | — | 모든 쿼리에 적용되는 ClickHouse settings의 맵입니다. 개별 쿼리는 [context](/ko/integrations/language-clients/go/clickhouse-api#using-context)를 통해 재정의할 수 있습니다. | -| `Compression` | `*Compression` | `nil` | 블록 수준 압축입니다. [Compression](#compression)을 참조하십시오. | -| `ReadTimeout` | `time.Duration` | — | 한 번의 호출에서 server로부터 읽기를 기다리는 최대 시간입니다. | -| `FreeBufOnConnRelease` | `bool` | `false` | true이면 매 쿼리마다 연결의 메모리 버퍼를 풀로 반환합니다. CPU 사용량이 약간 늘어나는 대신 메모리 사용량을 줄일 수 있습니다. | -| `Logger` | `*slog.Logger` | `nil` | 구조화된 로거(Go `log/slog`)입니다. [Logging](#logging)을 참조하십시오. | -| `Debug` | `bool` | `false` | **Deprecated.** 대신 `Logger`를 사용하십시오. stdout으로 레거시 디버그 출력을 활성화합니다. | -| `Debugf` | `func(string, ...any)` | — | **Deprecated.** 대신 `Logger`를 사용하십시오. 사용자 지정 디버그 로그 함수입니다. `Debug: true`가 필요합니다. | -| `GetJWT` | `GetJWTFunc` | — | ClickHouse Cloud 인증에 사용할 JWT 토큰을 반환하는 콜백입니다(HTTPS 전용). | -| `HttpHeaders` | `map[string]string` | — | 모든 요청에 전송되는 추가 HTTP headers입니다(HTTP 전송 전용). | -| `HttpUrlPath` | `string` | — | HTTP 요청에 덧붙이는 추가 URL 경로입니다(HTTP 전송 전용). | -| `HttpMaxConnsPerHost` | `int` | — | 내부 `http.Transport`의 `MaxConnsPerHost`를 재정의합니다(HTTP 전송 전용). | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | 사용자 지정 HTTP 전송 팩터리입니다. 필요한 항목만 선택적으로 재정의할 수 있도록 기본 전송이 함께 전달됩니다(HTTP 전송 전용). | -| `HTTPProxyURL` | `*url.URL` | — | 모든 요청에 사용할 HTTP 프록시 URL입니다(HTTP 전송 전용). | +| Parameter | Type | Default | Description | +| ---------------------- | -------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Protocol` | `Protocol` | `Native` | 전송 프로토콜입니다: `Native`(TCP) 또는 `HTTP`. [TCP vs HTTP](#tcp-vs-http)를 참조하십시오. | +| `Addr` | `[]string` | — | `host:port` 주소 슬라이스입니다. 여러 노드에 연결하는 방법은 [여러 노드에 연결하기](#connecting-to-multiple-nodes)을 참조하십시오. | +| `Auth` | `Auth` | — | 인증 자격 증명(`Database`, `Username`, `Password`)입니다. [인증](#authentication)을 참조하십시오. | +| `TLS` | `*tls.Config` | `nil` | TLS 구성입니다. `nil`이 아닌 값이면 TLS가 활성화됩니다. [TLS](#using-tls)를 참조하십시오. | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | TCP 연결을 설정하는 방식을 제어하는 사용자 지정 dial 함수입니다. | +| `DialTimeout` | `time.Duration` | `30s` | 새 연결을 열 때까지 기다리는 최대 시간입니다. 유휴 상태일 수 있는 ClickHouse Cloud 서비스에 연결할 때는 `1m`–`2m`로 늘리십시오 — [Timeouts](/ko/integrations/language-clients/go/config-reference#timeouts)를 참조하십시오. | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 동시에 열어 둘 수 있는 최대 연결 수입니다. | +| `MaxIdleConns` | `int` | `5` | 연결 풀에 유지할 유휴 연결 수입니다. | +| `ConnMaxLifetime` | `time.Duration` | `1h` | 연결 풀의 연결이 유지될 수 있는 최대 시간입니다. [연결 풀링](#connection-pooling)을 참조하십시오. | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | `Addr`에서 노드를 선택하는 전략입니다. [여러 노드에 연결하기](#connecting-to-multiple-nodes)을 참조하십시오. | +| `BlockBufferSize` | `uint8` | `2` | 병렬로 디코딩할 블록 수입니다. 값을 높이면 메모리 사용량이 증가하는 대신 처리량이 늘어납니다. `context`를 통해 쿼리별로 재정의할 수 있습니다. | +| `Settings` | `Settings` | — | 모든 쿼리에 적용되는 ClickHouse settings의 맵입니다. 개별 쿼리는 [context](/ko/integrations/language-clients/go/clickhouse-api#using-context)를 통해 재정의할 수 있습니다. | +| `Compression` | `*Compression` | `nil` | 블록 수준 압축입니다. [압축](#compression)을 참조하십시오. | +| `ReadTimeout` | `time.Duration` | — | 한 번의 호출에서 server로부터 읽기를 기다리는 최대 시간입니다. | +| `FreeBufOnConnRelease` | `bool` | `false` | true이면 매 쿼리마다 연결의 메모리 버퍼를 풀로 반환합니다. CPU 사용량이 약간 늘어나는 대신 메모리 사용량을 줄일 수 있습니다. | +| `Logger` | `*slog.Logger` | `nil` | 구조화된 로거(Go `log/slog`)입니다. [로깅](#logging)을 참조하십시오. | +| `Debug` | `bool` | `false` | **Deprecated.** 대신 `Logger`를 사용하십시오. stdout으로 레거시 디버그 출력을 활성화합니다. | +| `Debugf` | `func(string, ...any)` | — | **Deprecated.** 대신 `Logger`를 사용하십시오. 사용자 지정 디버그 로그 함수입니다. `Debug: true`가 필요합니다. | +| `GetJWT` | `GetJWTFunc` | — | ClickHouse Cloud 인증에 사용할 JWT 토큰을 반환하는 콜백입니다(HTTPS 전용). | +| `HttpHeaders` | `map[string]string` | — | 모든 요청에 전송되는 추가 HTTP headers입니다(HTTP 전송 전용). | +| `HttpUrlPath` | `string` | — | HTTP 요청에 덧붙이는 추가 URL 경로입니다(HTTP 전송 전용). | +| `HttpMaxConnsPerHost` | `int` | — | 내부 `http.Transport`의 `MaxConnsPerHost`를 재정의합니다(HTTP 전송 전용). | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | 사용자 지정 HTTP 전송 팩터리입니다. 필요한 항목만 선택적으로 재정의할 수 있도록 기본 전송이 함께 전달됩니다(HTTP 전송 전용). | +| `HTTPProxyURL` | `*url.URL` | — | 모든 요청에 사용할 HTTP 프록시 URL입니다(HTTP 전송 전용). | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/ko/products/cloud/guides/index.mdx b/ko/products/cloud/guides/index.mdx index 9ca5c2b23..931c3ba22 100644 --- a/ko/products/cloud/guides/index.mdx +++ b/ko/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['cloud guides', 'documentation', 'how-to', 'cloud features', 'tutoria | [내 계정 관리](/ko/products/cloud/guides/security/cloud-access-management/manage-my-account) | 이 페이지에서는 초대를 수락하고, MFA 설정을 관리하며, 비밀번호를 재설정하는 방법을 설명합니다 | | [SQL 콘솔 역할 할당 관리](/ko/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | SQL 콘솔 역할 할당을 관리하는 방법을 안내하는 가이드 | | [AWS 서비스 한도 및 쿼터 관리](/ko/products/bring-your-own-cloud/reference/aws-service-limits) | BYOC 온보딩 전에 확인해야 하는 AWS 서비스 쿼터, 증액 요청 방법, 그리고 서비스가 확장됨에 따라 모니터링해야 할 항목을 설명합니다 | -| [CMEK v1에서 v2로 마이그레이션](/ko/products/cloud/guides/security/cmek-migration) | 기존 CMEK에서 버전 2로 이전하기 위한 마이그레이션 지침 | | [멀티 테넌시](/ko/products/cloud/guides/best-practices/multitenancy) | 멀티 테넌시 구현을 위한 모범 사례 | | [시맨틱 레이어로 ClickHouse Assistant agent 대화 최적화](/ko/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | AGENTS.md를 사용하여 ClickHouse Assistant chat agent에 사용자 지정 비즈니스 로직과 데이터별 지침을 제공하는 방법을 안내하는 가이드 | | [개요](/ko/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | 자체 클라우드 인프라에 ClickHouse를 배포합니다 | diff --git a/ko/products/cloud/guides/security/cmek-migration.mdx b/ko/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index 60a495586..000000000 --- a/ko/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: '레거시 CMEK 마이그레이션' -slug: /cloud/security/cmek-migration -title: 'CMEK v1에서 v2로 마이그레이션' -description: '레거시 CMEK에서 버전 2로 이전하기 위한 마이그레이션 지침' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', 'encryption', 'CMEK'] ---- - -고객 관리형 암호화 키(CMEK) 서비스의 보안을 강화하고 있습니다. 이제 모든 서비스는 고객 키를 사용해 서비스를 암호화하고 복호화할 수 있도록 서비스마다 고유한 AWS Role로 구성됩니다. 이 새로운 AWS Role은 서비스 구성 화면에서만 표시됩니다. - -이 새로운 프로세스는 OpenAPI와 Terraform을 모두 지원합니다. 자세한 내용은 문서를 확인하십시오([향상된 암호화](/ko/products/cloud/guides/security/cmek), [Cloud API](/ko/products/cloud/features/admin-features/api/api-overview), [공식 Terraform 프로바이더](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)). - - - CMEK v1을 사용하는 고객은 2026년 6월 1일까지 서비스를 반드시 마이그레이션해야 합니다. 이 날짜 이후에는 고객 관리형 키가 기본적으로 ClickHouse 관리형 키로 교체됩니다. 기본 마이그레이션 이후에는 다시 고객 관리형 키로 전환할 수 있습니다. - - -
- ## 수동 마이그레이션 -
- -새 프로세스로 마이그레이션하려면 다음 단계를 수행하십시오: - -1. https://console.clickhouse.cloud에 로그인합니다 -2. 암호화된 서비스를 클릭합니다 -3. 왼쪽에서 Service Settings를 클릭합니다 -4. 화면 맨 아래로 스크롤한 다음 View service details를 펼칩니다 -5. Encryption Role ID (IAM)를 복사합니다 -6. AWS의 KMS 키로 이동하여 다음 내용을 추가하도록 Key Policy를 업데이트합니다: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. ClickHouse Cloud에서 지원 요청을 열어 새 메서드를 활성화할 수 있도록 알려주십시오. 이 변경 사항을 적용하려면 서비스 재시작이 필요하므로, 서비스를 재시작하기에 가장 적절한 날짜/시간이 있으면 알려주십시오. -8. 서비스를 재시작한 후 AWS의 KMS 키로 이동하여 Key Policy에서 다음 내용을 제거하십시오: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. 업데이트가 완료되었습니다! - -
- ## Terraform 마이그레이션 -
- -1. [Terraform 버전 3.5.0 이상](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)으로 업데이트합니다. -2. 변경 사항 없이 Terraform을 적용합니다. 그러면 Terraform state에 transparent_data_encryption용 새 필드가 나타납니다. 여기서 role_id를 기록해 두십시오. -3. AWS의 KMS 키로 이동한 다음 Key Policy를 업데이트하여 다음 내용을 추가합니다. - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. ClickHouse Cloud에서 service name을 포함해 support case를 등록하여 새 메서드를 활성화할 수 있도록 알려주십시오. 이 변경 사항을 적용하려면 서비스를 재시작해야 하므로, 재시작에 가장 적합한 날짜/시간이 있으면 알려주십시오. -5. 서비스 재시작 후 `transparent_data_encryption.enabled` 설정을 ‘True’로 업데이트하고, Terraform에서 tier 설정을 제거한 다음 적용할 수 있습니다. 이렇게 해도 변경 사항은 없습니다. -6. AWS에서 KMS 키로 이동한 다음, Key Policy에서 다음 내용을 제거하십시오: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. 업데이트가 완료되었습니다! \ No newline at end of file diff --git a/ko/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/ko/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index b902dfae1..74029b123 100644 --- a/ko/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/ko/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ ClickHouse Cloud 서비스에 대한 액세스를 AWS PrivateLink 주소로만 * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 @@ -51,8 +52,8 @@ ClickHouse Cloud 서비스에 대한 액세스를 AWS PrivateLink 주소로만 **AWS PrivateLink를 활성화하려면 다음 작업을 완료하십시오**: -1. Endpoint "Service name"을 확인합니다. -2. AWS Endpoint를 생성합니다. +1. 엔드포인트 "Service name"을 확인합니다. +2. AWS 엔드포인트를 생성합니다. 3. "Endpoint ID"를 ClickHouse Cloud 조직에 추가합니다. 4. "Endpoint ID"를 ClickHouse 서비스 허용 목록에 추가합니다. diff --git a/ko/products/cloud/navigation.json b/ko/products/cloud/navigation.json index 6d6dc1b07..d952e6cd8 100644 --- a/ko/products/cloud/navigation.json +++ b/ko/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "ko/products/cloud/guides/security/data-masking", - "ko/products/cloud/guides/security/cmek", - "ko/products/cloud/guides/security/cmek-migration" + "ko/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "ko/_specs/cloud-openapi.json" } ] }, diff --git a/ko/products/kubernetes-operator/guides/configuration.mdx b/ko/products/kubernetes-operator/guides/configuration.mdx index c085c806c..3dab82a41 100644 --- a/ko/products/kubernetes-operator/guides/configuration.mdx +++ b/ko/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: ClickHouse 컨테이너의 CPU와 메모리를 설정합니다: ```yaml -# 기본값 +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -321,6 +321,10 @@ spec: ## TLS/SSL 구성
+cert-manager를 사용한 인증서 발급, 보안 포트를 통한 +클라이언트 연결, Keeper 트래픽 암호화를 포함한 엔드투엔드 예시는 +[TLS로 보안 설정](/ko/products/kubernetes-operator/guides/tls) 가이드를 참조하십시오. +
### 보안 endpoint 구성
@@ -371,6 +375,323 @@ spec: key: ``` +
+ ## 외부 시크릿 +
+ +기본적으로 연산자는 클러스터의 내부 자격 증명(interserver password, management password, Keeper 아이덴티티, cluster secret, named-collections key)이 포함된 시크릿을 생성하고 관리합니다. 이 시크릿은 클러스터 이름으로 생성되며 클러스터의 네임스페이스에 위치합니다. + +이러한 자격 증명을 직접 관리하려는 경우(예: HashiCorp Vault, AWS Secrets Manager 또는 [External Secrets Operator](https://external-secrets.io/)에서 가져오는 경우) `spec.externalSecret`을 사용해 기존에 생성된 시크릿을 연산자가 참조하도록 지정하십시오: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + 참조된 시크릿은 ClickHouseCluster와 **같은 네임스페이스**에 있어야 합니다. 연산자는 직접 생성하지 않은 시크릿은 절대 삭제하지 않습니다. + + +
+ ### 필수 키 +
+ +시크릿에는 다음 키가 포함되어야 합니다: + +| Key | Format | When required | +| ----------------------- | -------------------------------------- | ------------------------ | +| `interserver-password` | 평문 비밀번호 | 항상 | +| `management-password` | 평문 비밀번호 | 항상 | +| `keeper-identity` | `clickhouse:` | 항상 | +| `cluster-secret` | 평문 비밀번호 | 항상 | +| `named-collections-key` | 16바이트 AES 키를 16진수로 인코딩한 값(16진수 문자 32개) | ClickHouse `>= 25.12`에서만 | + +전체 시크릿은 다음과 같습니다: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### 정책: Observe와 Manage +
+ +`spec.externalSecret.policy`는 필수 키가 누락되었을 때 연산자가 어떻게 처리할지를 제어합니다. + +| 정책 | 키 누락 시 동작 | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `Observe` (기본값) | 모든 필수 키가 준비될 때까지 리컨실리에이션이 **차단**됩니다. 연산자는 `ExternalSecretValid` 조건(사유: `ExternalSecretInvalid`)과 `Warning` 이벤트를 통해 누락된 각 키와 해당 키의 포맷 힌트를 보고합니다. | +| `Manage` | 연산자가 누락된 필수 키를 **생성**하여 동일한 시크릿에 다시 기록합니다. 초기 설정에 유용합니다. 빈 시크릿을 만든 뒤 연산자가 값을 채우게 하고, 이후 필요에 따라 접근 권한을 더 엄격하게 제한할 수 있습니다. 연산자는 시크릿을 삭제하지 않습니다. | + + + `policy: Manage`를 사용하더라도 시크릿은 해당 네임스페이스에 이미 존재해야 합니다. 연산자는 시크릿 자체를 생성하지 않고, 기존 시크릿에 생성된 키만 기록합니다. 참조된 시크릿이 없으면 정책과 관계없이 `ExternalSecretNotFound` 사유로 리컨실리에이션이 차단됩니다. + + +외부 시스템(Vault, ESO, sealed-secrets, GitOps)이 신뢰할 수 있는 원본(source of truth)이고, 구성 오류가 있을 때 연산자가 명확하게 실패하도록 하려면 `Observe`를 선택하십시오. 자체적으로 초기 설정을 진행하면서도 시크릿 객체 자체의 소유권은 유지하려면(예: 백업 목적) `Manage`를 선택하십시오. + +
+ ### 상태 조건과 문제 해결 +
+ +연산자는 `ClickHouseCluster.status.conditions`에 `ExternalSecretValid` 조건을 표시합니다. 리컨실리에이션이 멈춘 것처럼 보이면 이 조건을 확인하십시오: + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +가능한 원인: + +| `reason` | 의미 | 해결 방법 | +| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------ | +| `ExternalSecretNotFound` | 참조된 시크릿이 네임스페이스에 존재하지 않습니다. | 시크릿을 생성하거나 `spec.externalSecret.name` 값을 수정하십시오. | +| `ExternalSecretInvalid` | 시크릿은 존재하지만 필수 키가 누락되어 있습니다(`Observe`를 사용하는 경우에만 해당). 메시지에는 누락된 각 키와 예상 포맷이 함께 표시됩니다. | 누락된 키를 추가하거나 `policy: Manage`로 전환하십시오. | +| `ExternalSecretValid` | 필요한 모든 키가 존재하며, 연산자가 해당 시크릿을 사용하고 있습니다. | — | + +시크릿이 유효하지 않은 동안 연산자는 리컨실리에이션을 다시 큐에 넣습니다. 따라서 누락된 키를 추가하면 다음 reconcile 시 자동으로 반영되므로 파드를 재시작할 필요가 없습니다. + + + 필요한 키 집합은 실행 중인 ClickHouse 버전에 따라 달라집니다. `named-collections-key`는 연산자의 version probe가 ClickHouse `25.12` 이상을 감지한 경우에만 검증됩니다. 이전 버전에서는 해당 키가 시크릿에 없을 수 있습니다. + + +
+ ## 추가 포트 +
+ +오퍼레이터는 모든 ClickHouse 파드와 해당 헤드리스 Service에 고정된 포트 집합을 노출합니다: `8123` HTTP, `9000` 네이티브, `9009` interserver, `9001` management, `9363` Prometheus 메트릭, 그리고 TLS가 활성화된 경우 `8443`/`9440`의 TLS 포트도 함께 노출됩니다. ClickHouse가 MySQL, PostgreSQL, gRPC 또는 사용자 지정 포트 같은 추가 프로토콜을 수신하도록 하려면 `spec.additionalPorts`에 선언하십시오: + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +연산자는 해당 포트를 파드의 `containerPorts`와 헤드리스 Service에 추가합니다. 전체 예시는 [`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml)에 있습니다. + + + `additionalPorts`는 Kubernetes 측에서만 포트를 엽니다. ClickHouse 서버가 해당 포트에서 수신 대기하도록 구성하지는 **않습니다**. `spec.settings.extraConfig.protocols`에서 해당 protocol도 활성화해야 합니다. 그렇지 않으면 Service에서는 포트가 열려 있어도 파드 내부에서는 아무것도 응답하지 않습니다. + + +
+ ### 종단 간 예시: MySQL wire protocol +
+ +포트 `9004`에서 MySQL wire protocol로 ClickHouse를 노출하려면: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +적용 후 클러스터 내부에서 확인하십시오: + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### 필드 제약 조건 +
+ +| 필드 | 규칙 | +| ------ | ---------------------------------------------------------------------------------------------------------- | +| `name` | DNS_LABEL 패턴 `^[a-z]([-a-z0-9]*[a-z0-9])?$`와 일치해야 하며, 최대 63자까지 허용됩니다. 고유성은 CRD에서 list-map 키를 통해 보장됩니다. | +| `port` | `[1, 65535]` 범위의 정수입니다. 웹훅은 목록 내 중복된 포트 번호를 허용하지 않습니다. | + +
+ ### 예약된 포트 및 이름 +
+ +유효성 검사 웹훅은 연산자가 자체적으로 바인딩하는 포트와 충돌할 수 있는 `additionalPorts` 항목을 거부합니다. 모든 TLS 관련 포트는 **예외 없이** 예약되므로, 나중에 `spec.settings.tls.enabled`를 활성화하더라도 이전에 유효했던 클러스터가 손상되지 않습니다. + +| 포트 | 예약 용도 | +| ------ | -------------- | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | 네이티브 TCP | +| `9440` | 네이티브 TLS | +| `9009` | interserver | +| `9001` | management | +| `9363` | Prometheus 메트릭 | + +다음 이름도 거부됩니다. 이는 연산자의 내부 프로토콜 유형 식별자이며, 사람이 읽기 쉬운 별칭은 아닙니다. + +| 이름 | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +거부된 요청은 다음과 같은 오류를 반환합니다: + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## 버전 프로브 및 업그레이드 채널 +
+ +연산자는 클러스터 버전과 관련해 서로 독립적인 두 가지 작업을 수행합니다: + +1. **버전 프로브** — 컨테이너 이미지를 한 번 실행해 현재 실행 중인 ClickHouse / Keeper 버전을 확인하는 Kubernetes `Job`입니다. 확인된 버전은 `.status.version`에 기록되며, 다른 리컨실리에이션 단계에서 사용됩니다(예: `External Secret` named-collections 키는 ClickHouse `25.12`부터만 필요합니다). +2. **업그레이드 채널** — 공개 ClickHouse 릴리스 피드(`https://clickhouse.com/data/version_date.tsv`)를 주기적으로 확인합니다. 연산자는 `VersionUpgraded` 상태 조건을 통해 더 최신 버전을 사용할 수 있는지 보고합니다. 연산자가 자체적으로 클러스터를 업그레이드하지는 않으며, image tag는 사용자가 직접 제어합니다. + +
+ ### 릴리스 채널 선택 +
+ +`spec.upgradeChannel`은 연산자가 비교 대상으로 삼을 업스트림 릴리스 집합을 선택합니다. 동일한 필드는 `ClickHouseCluster`와 `KeeperCluster` 모두에 있습니다. + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +허용되는 값(CRD가 패턴 `^(lts|stable|\d+\.\d+)?$`로 검증함): + +| Value | Behavior | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| *empty* (기본값) | 연산자는 현재 실행 중인 major.minor 라인 내에서 **minor** 업데이트만 제안합니다. `25.8.3.1`의 클러스터에는 `25.8.4.x`가 안내되지만 `25.9.x`는 안내되지 않습니다. | +| `stable` | 업스트림 `stable` 채널을 따릅니다 — ClickHouse Inc.가 기본 릴리스 라인에서 안정으로 지정한 최신 릴리스입니다. `lts` 채널보다 major 업그레이드를 더 일찍 받습니다. | +| `lts` | 업스트림 `lts` 채널을 따릅니다 — 장기 지원 릴리스입니다. major 업그레이드는 더 드물게 받고 지원 기간은 더 깁니다. | +| `25.8` (또는 임의의 `.`) | 채널을 특정 major.minor 라인에 고정합니다. 업스트림에 더 새로운 버전이 있더라도 그보다 높은 major 업그레이드는 제안되지 않습니다. | + +프로덕션 환경에서는 채널을 명시적인 `.`(예: `25.8`)에 고정하는 방식을 일반적으로 권장합니다. 이렇게 하면 클러스터가 의도한 major 릴리스 라인에 고정되며, 어떤 레플리카가 다른 major로 벗어나는 경우 연산자가 `WrongReleaseChannel` 경고를 표시할 수 있습니다. 이는 특히 image가 사람이 읽기 쉬운 태그가 아니라 다이제스트(`@sha256:...`)로 참조될 때 중요합니다. 기본 empty 값은 major 버전 점프가 문제가 되지 않는 개발 클러스터에서는 적절합니다. + +
+ ### 상태 조건 +
+ +프로브 및 업그레이드 확인 결과는 다음 두 조건에 반영됩니다: + +| Condition | Reason | Meaning | +| ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionInSync` | `VersionMatch` | 모든 레플리카가 image와 동일한 버전을 보고합니다 | +| `VersionInSync` | `VersionMismatch` | 레플리카들이 서로 다른 버전으로 실행 중입니다. 계획된 rolling upgrade 동안에는 경고 이벤트가 억제됩니다. 일반적으로 변경 가능한 image tag(예: `latest` 또는 `26.3`처럼 major만 지정한 tag)를 고정해 두었고, pull 사이에 기본 registry의 내용이 바뀌어 같은 tag라도 레플리카마다 서로 다른 패치 버전이 적용된 경우에 나타납니다. | +| `VersionInSync` | `VersionPending` | 버전 프로브 Job이 아직 완료되지 않았습니다 | +| `VersionInSync` | `VersionProbeFailed` | probe Job이 실패했습니다. 연산자가 현재 실행 중인 버전을 확인할 수 없습니다 | +| `VersionUpgraded` | `UpToDate` | 클러스터가 선택한 채널에서 제공되는 최신 버전을 사용 중입니다 | +| `VersionUpgraded` | `MinorUpdateAvailable` | 동일한 `major.minor` 계열에서 더 새로운 패치 버전을 사용할 수 있습니다 | +| `VersionUpgraded` | `MajorUpdateAvailable` | 선택한 채널 내에서 더 새로운 `major.minor` 버전을 사용할 수 있습니다 | +| `VersionUpgraded` | `VersionOutdated` | 현재 실행 중인 버전이 오래되어 선택한 채널에서 더 이상 수정 사항을 받지 못합니다. 일반적으로 upstream에서 해당 major 계열이 `lts` 또는 `stable`에서 제외되었기 때문입니다 | +| `VersionUpgraded` | `WrongReleaseChannel` | 현재 실행 중인 image가 선택한 `upgradeChannel`에 속하지 않습니다. 예시: `upgradeChannel: lts`로 설정된 클러스터가 `26.5`를 실행 중인 경우입니다. `26.5`는 upstream `lts` 계열에 포함되지 않습니다. | +| `VersionUpgraded` | `UpgradeCheckFailed` | 연산자가 upstream release feed에 연결할 수 없었습니다 | + +다음으로 확인할 수 있습니다: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### 버전 프로브 Job 재정의 +
+ +프로브는 일반적인 Kubernetes `Job`으로 구현됩니다. 클러스터에 특정 Tolerations, 노드 셀렉터, 보안 컨텍스트를 요구하는 admission policy가 있거나 완료된 probe Job이 남아 있는 시간을 제한하려는 경우, `spec.versionProbeTemplate`을 통해 템플릿을 재정의하십시오: + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +컨테이너 이름 `version-probe`는 연산자의 기본값입니다 — `containers:` 아래의 항목이 이름으로 일치하므로, 연산자는 사용자가 제공한 필드를 기본값 위에 깊게 병합합니다. + +
+ ### Operator 전체 제어 +
+ +연산자 manager의 두 플래그는 업그레이드 확인 루프를 전역적으로 제어합니다: + +| 플래그 | 기본값 | 영향 | +| --------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | 연산자가 업스트림 버전 목록을 다시 가져오는 주기 | +| `--disable-version-update-checks` | `false` | 업그레이드 검사기를 완전히 비활성화합니다. `VersionUpgraded` 조건이 설정되지 않으며, `clickhouse.com`으로 나가는 아웃바운드 HTTP 트래픽도 발생하지 않습니다 | + +에어갭 환경이거나 `clickhouse.com`으로의 egress가 허용되지 않는 경우 `--disable-version-update-checks=true`를 설정하십시오. +
## ClickHouse 설정
@@ -485,6 +806,49 @@ spec: 활성화하면 operator가 Replicated 및 통합 테이블을 새 레플리카에 동기화합니다. +
+ ### 서버 로깅 +
+ +`spec.settings.logger`에서 ClickHouse 서버 로그를 구성합니다. 모든 필드는 안전한 기본값이 적용되는 선택 사항이므로, 별도로 설정하지 않은 클러스터도 기본적으로 컨테이너 콘솔과 디스크의 롤링 파일 모두에 `trace` 수준으로 로그를 기록합니다. + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| 필드 | 기본값 | 설명 | +| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| `logToFile` | `true` | `false`이면 연산자가 파일 대상을 제거하고, 서버는 컨테이너 콘솔에만 로그를 기록합니다. | +| `jsonLogs` | `false` | `true`이면 연산자가 `formatting.type: json`을 추가하므로 각 줄이 JSON 객체가 됩니다. | +| `level` | `trace` | 로그 출력 상세도입니다. `test`, `trace`, `debug`, `information`, `notice`, `warning`, `error`, `critical`, `fatal` 중 하나입니다. | +| `size` | `1000M` | 단일 로그 파일이 회전되기 전 최대 크기입니다. | +| `count` | `50` | 서버가 유지하는 회전된 로그 파일 수입니다. | + +연산자는 `kubectl logs`가 작동하도록 항상 콘솔 로깅을 유지하고, `logToFile`이 `true`이면 여기에 파일 로깅을 추가합니다. 기본값을 사용하는 cluster는 다음 `logger` 블록으로 렌더링됩니다: + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +동일한 `spec.settings.logger` 블록은 `KeeperCluster`에도 적용되며, 이 경우 오퍼레이터는 파일을 `/var/log/clickhouse-keeper/` 아래에 기록합니다. + + + `logToFile`과 관계없이 콘솔 로깅은 계속 활성화되므로, 파일 로깅을 비활성화해도 `kubectl logs`는 계속 작동합니다. JSON을 파싱하는 구조화된 로그 저장소로 로그를 전송하는 경우 `jsonLogs: true`로 설정하십시오. + +
## 사용자 지정 구성
diff --git a/ko/products/kubernetes-operator/guides/introduction.mdx b/ko/products/kubernetes-operator/guides/introduction.mdx index f7fce0788..6803c44e6 100644 --- a/ko/products/kubernetes-operator/guides/introduction.mdx +++ b/ko/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: 스토리지를 완전히 제거하려면: ```bash -# 클러스터 삭제 +# Delete cluster kubectl delete clickhousecluster my-cluster -# 파드 종료 대기 -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# PVC 삭제 -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/ko/products/kubernetes-operator/guides/monitoring.mdx b/ko/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..e8467eb09 --- /dev/null +++ b/ko/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,419 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: ClickHouse 연산자 모니터링 +keywords: ['kubernetes', 'prometheus', '모니터링', '메트릭'] +description: '연산자 메트릭과 상태 엔드포인트를 스크레이프하고 보호하며 활용하는 방법을 설명합니다.' +doc_type: 'guide' +--- + +연산자는 Prometheus와 호환되는 메트릭과 Kubernetes 상태 프로브를 노출하므로, 리컨실리에이션 활동을 관찰하고, 작동이 멈춘 컨트롤러를 감지하고, 장애에 대한 알림을 설정할 수 있습니다. + +이 가이드에서는 연산자가 무엇을 노출하는지, 이를 어떻게 스크레이프하는지, 그리고 일상적으로 어떤 쿼리가 유용한지 설명합니다. + + + 이 가이드는 **연산자 프로세스 자체**(controller manager)에 관한 내용입니다. ClickHouse 서버 메트릭(쿼리, 파트, 복제 지연)은 [ClickHouse의 Prometheus 엔드포인트](/ko/reference/settings/server-settings/settings#prometheus)를 사용해 별도로 스크레이프하십시오. + + +
+ ## 엔드포인트 +
+ +연산자 프로세스는 manager 파드 내에 2개의 HTTP 엔드포인트를 노출합니다. + +| Endpoint | Default port | Path | Purpose | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------- | ------------------------ | +| 메트릭 | `8080` (Helm) / `0` 비활성화됨(binary 기본값) | `/metrics` | Prometheus 노출 형식 | +| 헬스 프로브 | `8081` | `/healthz`, `/readyz` | Kubernetes 활성 상태 및 준비 상태 | +| 메트릭 엔드포인트는 연산자 binary를 직접 실행할 때 기본적으로 **비활성화**되어 있습니다(`--metrics-bind-address=0`). Helm 차트에서는 `metrics.enable: true` 및 `metrics.port: 8080`을 사용해 이를 활성화합니다. | | | | + +헬스 프로브 엔드포인트는 항상 활성화되어 있으며, 배포 템플릿은 `/healthz`와 `/readyz`를 포트 `8081`의 파드 활성 상태 프로브와 준비 상태 프로브에 연결합니다. + +
+ ## 연산자 바이너리 플래그 +
+ +관련 `manager` 플래그([`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go)에 정의됨)는 다음과 같습니다. + +| 플래그 | 기본값 | 설명 | +| ----------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `--metrics-bind-address` | `0` (비활성화) | 메트릭 엔드포인트의 바인드 주소입니다. HTTPS에는 `:8443`, HTTP에는 `:8080`으로 설정하십시오. 메트릭 서버를 비활성화하려면 `0`으로 두십시오. | +| `--metrics-secure` | `true` | 인증 및 권한 부여를 적용한 HTTPS로 메트릭을 제공합니다. 일반 HTTP를 사용하려면 `false`로 설정하십시오. | +| `--metrics-cert-path` | 비어 있음 | 메트릭 서버용 TLS 인증서 파일(`tls.crt`, `tls.key`)이 들어 있는 디렉터리입니다. | +| `--metrics-cert-name` | `tls.crt` | `--metrics-cert-path` 내 인증서 파일 이름입니다. | +| `--metrics-cert-key` | `tls.key` | `--metrics-cert-path` 내 키 파일 이름입니다. | +| `--enable-http2` | `false` | 메트릭 **및 웹훅** 서버에 대해 HTTP/2를 활성화합니다. CVE-2023-44487 / CVE-2023-39325 완화를 위해 기본적으로 비활성화되어 있습니다. | +| `--leader-elect` | `false` (바이너리) / `true` (Helm 차트) | 한 번에 하나의 레플리카만 reconcile을 수행하도록 leader election을 활성화합니다. Helm 차트는 기본적으로 `manager.args`에서 이 플래그를 설정합니다. | +| `--health-probe-bind-address` | `:8081` | `/healthz` 및 `/readyz`의 바인드 주소입니다. | + + + 플래그 도움말 텍스트의 `8443`(HTTPS) / `8080`(HTTP) 관례는 단지 참고용일 뿐입니다. Helm 차트는 `metrics.port: 8080`과 `metrics.secure: true`를 모두 설정하므로 `8080`에서 HTTPS를 제공합니다. 포트 기반 모드 감지는 없으며, HTTPS 또는 HTTP를 결정하는 것은 `--metrics-secure`입니다. + + +
+ ## Helm으로 메트릭 활성화 +
+ +차트는 이미 메트릭 포트용 `Service`를 생성하며, 필요에 따라 prometheus-operator용 `ServiceMonitor`도 생성합니다. + +메트릭 엔드포인트 자체는 기본적으로 활성화되어 있습니다(`metrics.enable: true`, 포트 `8080`, `metrics.secure: true`를 통해 HTTPS로 제공). 일반적으로 변경해야 할 설정은 `prometheus.enable`뿐이며, 이를 설정하면 차트가 `ServiceMonitor`를 생성합니다: + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +cert-manager를 사용하지 않는다면 `certManager.enable: false`도 추가로 설정해야 합니다. 그러면 ServiceMonitor는 `insecureSkipVerify: true`로 스크레이프하며 bearer-token 인증에만 의존하게 됩니다. + +메트릭 관련 전체 기본값은 다음과 같습니다: + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +적용: + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +설치 후 chart는 다음 리소스를 생성합니다: + +* `Service/-metrics-service` — 포트 `8080`을 노출합니다(`metrics.secure: true`이면 HTTPS). +* `ServiceMonitor/-controller-manager-metrics-monitor` — `prometheus.enable: true`일 때 생성됩니다. +* `ClusterRole/-metrics-reader` — 비리소스 URL `/metrics``에 대해 `get` 권한을 부여합니다. + +
+ ## 메트릭 엔드포인트 보안 +
+ +`metrics.secure: true`인 경우 메트릭 서버는 모든 스크레이프 요청에 대해 TLS **및** Kubernetes 인증/권한 부여를 적용합니다. 스크레이퍼는 다음 조건을 충족해야 합니다. + +1. 유효한 Kubernetes Bearer token을 제시해야 합니다. +2. 비리소스 URL `/metrics`에 대한 `get` 권한이 부여된 클러스터 역할에 바인딩된 ServiceAccount에 속해야 합니다. + +이 차트에는 이러한 클러스터 역할이 포함되어 있습니다. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +이를 스크레이퍼(일반적으로 Prometheus)에서 사용하는 ServiceAccount에 바인딩하십시오: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + 메트릭 엔드포인트에서 `401 Unauthorized` 또는 `403 Forbidden`이 표시되면, 스크레이퍼가 HTTPS를 사용하고 있지만 Kubernetes Bearer token이 없거나 해당 token이 인증되지 않았거나, ServiceAccount에 위의 바인딩이 없습니다. `metrics.secure: false`로 설정해 보안을 비활성화하는 것은 공유 클러스터에서는 **권장되지 않습니다**. 네트워크를 통해 해당 파드에 접근할 수 있는 사용자라면 누구나 엔드포인트를 스크레이프할 수 있기 때문입니다. + + +
+ ## ServiceMonitor 참고 +
+ +`prometheus.enable: true`로 설정하면 차트는 다음과 같은 형태의 ServiceMonitor를 렌더링합니다: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +Prometheus 인스턴스에서 cert-manager를 실행하지 않는다면 `tlsConfig.insecureSkipVerify: true`로 설정하고 bearer-token 인증만 사용하십시오 — `certManager.enable: false`일 때 차트는 이미 이렇게 설정됩니다. + +
+ ## 독립형 Prometheus 예시 +
+ +`kube-prometheus-stack`를 사용하지 않는다면, 리포지토리에는 [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml)에 포함된 자체 완결형 예시가 제공됩니다. 이 예시는 ServiceAccount, 필요한 RBAC, 그리고 연산자의 ServiceMonitor를 선택하는 `Prometheus` CR을 생성합니다. + +
+ ## 헬스 프로브 엔드포인트 +
+ +| 경로 | 사용 주체 | 반환값 | +| ---------- | ------------------------- | ------------------------------------ | +| `/healthz` | Kubernetes liveness probe | 프로브 서버가 수신 대기 중인 동안 `200 OK`를 반환합니다. | +| `/readyz` | Kubernetes 준비 상태 프로브 | 프로브 서버가 수신 대기 중인 동안 `200 OK`를 반환합니다. | + +두 엔드포인트는 모두 동일한 단순 Ping 검사(`sigs.k8s.io/controller-runtime`의 `healthz.Ping`)에 등록됩니다. 따라서 프로브 실패는 "manager 프로세스가 `:8081`에서 HTTP를 제공하지 않는다"는 뜻일 뿐, "컨트롤러가 비정상 상태이다"라는 뜻은 아닙니다. 컨트롤러 수준의 문제를 감지하려면 대신 [리컨실리에이션 메트릭](#reconciliation-activity)을 사용하십시오. + +두 엔드포인트는 기본적으로 포트 `8081`에서 제공됩니다. 배포에는 다음과 같이 연결됩니다: + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +프로브가 반복적으로 실패한다면, 대개 프로브 server 자체가 아예 시작되지 않았다는 뜻입니다. 예를 들어 startup 초기에 manager가 종료되었을 수 있습니다. manager logs에서 `unable to start manager`, RBAC 실패, 또는 `cache did not sync` 오류를 확인하십시오. + +
+ ## 메트릭 카탈로그 +
+ +연산자는 사용자 정의 Prometheus collector를 등록하지 않습니다. 아래 항목은 모두 기반이 되는 `controller-runtime` 및 `client-go` 라이브러리에서 노출하는 것입니다. 가장 유용한 시계열을 용도별로 정리하면 다음과 같습니다: + +
+ ### 리컨실리에이션 활동 +
+ +| 메트릭 | 유형 | 레이블 | +| -------------------------------------------------- | --------- | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | counter | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | counter | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | histogram | `controller` | +| `controller_runtime_active_workers` | gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | gauge | `controller` | + +`controller` 레이블은 `For(...)`에 등록된 리소스 유형을 바탕으로 `controller-runtime`이 결정합니다. 현재 `internal/controller/clickhouse` 및 `internal/controller/keeper`의 코드에서는 각각 `clickhousecluster`와 `keepercluster`로 해석됩니다. 연산자를 사용자 지정한 경우 `/metrics`를 한 번 스크레이프하여 확인하십시오. + +
+ ### 작업 큐 +
+ +| 메트릭 | 유형 | 레이블 | +| --------------------------------------------- | ----- | -------------------------------- | +| `workqueue_depth` | 게이지 | `name`, `controller`, `priority` | +| `workqueue_adds_total` | 카운터 | `name`, `controller` | +| `workqueue_retries_total` | 카운터 | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | 게이지 | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | 게이지 | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | 히스토그램 | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | 히스토그램 | `name`, `controller` | + +`name`과 `controller` 레이블에는 동일한 값(컨트롤러 이름)이 들어갑니다. + +
+ ### API 서버 트래픽 +
+ +| 메트릭 | 유형 | 레이블 | +| ---------------------------- | ------- | ------------------------ | +| `rest_client_requests_total` | counter | `code`, `method`, `host` | + +
+ ### 리더 선출 +
+ +| 메트릭 | 유형 | 레이블 | +| ------------------------------- | --- | ------------------------------------ | +| `leader_election_master_status` | 게이지 | `name` (= `d4ceba06.clickhouse.com`) | + +Helm 차트는 기본적으로 `--leader-elect`를 활성화하므로, 이 메트릭은 일반적인 Helm 설치에 포함됩니다. 플래그 없이 바이너리를 직접 실행하면 이 메트릭은 표시되지 않습니다. + +
+ ### 런타임 +
+ +표준 Go 프로세스 및 런타임 collector — `go_goroutines`, `go_memstats_*`, `process_cpu_seconds_total`, `process_resident_memory_bytes` 등입니다. + +
+ ## 유용한 PromQL 쿼리 +
+ +
+ ### 상태 개요 +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### 적체 감지 +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### 스로틀링과 API 부하 +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### 리더 상태(HA 배포) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## 권장 알림 +
+ +PrometheusRule 작성을 위한 출발점입니다(환경에 맞게 임계값을 조정하십시오): + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +마지막 규칙은 leader election이 활성화된 경우에만 의미가 있습니다. + +
+ ## 설정 확인 +
+ +차트가 `clickhouse-operator-system`에 설치되어 있다고 가정하고, 전체 과정을 빠르게 점검합니다: + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +스크레이프 결과가 Prometheus 노출 형식의 메트릭을 반환하면 엔드포인트와 RBAC가 올바르게 구성된 것입니다. + + + +* [설치](/ko/products/kubernetes-operator/install/helm) — 모니터링과 관련된 Helm values입니다. +* [구성](/ko/products/kubernetes-operator/guides/configuration) — 메트릭 서버와 공유하는 TLS 구성입니다. \ No newline at end of file diff --git a/ko/products/kubernetes-operator/guides/scaling.mdx b/ko/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..e496bdf16 --- /dev/null +++ b/ko/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,109 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: 클러스터 스케일링 +keywords: ['kubernetes', '스케일링', '레플리카', '세그먼트', 'Keeper', '쿼럼'] +description: 'ClickHouse 레플리카와 세그먼트, Keeper 쿼럼 멤버를 스케일링하는 방법과 연산자가 자동으로 수행하는 작업을 설명합니다.' +doc_type: 'guide' +--- + +사용자 지정 리소스에서 레플리카와 세그먼트 수를 편집해 클러스터를 스케일링합니다. 연산자는 실행 중인 클러스터를 새 토폴로지에 맞게 조정합니다. 즉, 레플리카별 StatefulSet을 생성하거나 제거하고, 스키마(schema)를 동기화된 상태로 유지하며, 상태 조건을 통해 진행 상황을 표시합니다. + +이 가이드에서는 `ClickHouseCluster`의 레플리카와 세그먼트를 스케일링하는 방법, `KeeperCluster` 쿼럼을 안전하게 스케일링하는 방법, 그리고 스케일 작업이 진행되는 동안 어떤 조건을 확인해야 하는지를 설명합니다. + + + `ClickHouseCluster`에는 항상 Keeper가 필요하며, 필수 `spec.keeperClusterRef` 필드를 통해 이를 참조합니다. 연산자는 클러스터 크기와 관계없이 이를 통해 클러스터를 조정합니다. 세그먼트당 2개 이상의 레플리카를 실행하려면 데이터도 `ReplicatedMergeTree` 테이블에 있어야 합니다. 복제가 있어야 두 번째 레플리카가 동일한 행을 제공할 수 있기 때문입니다. + + +
+ ## 레플리카 스케일링 +
+ +`spec.replicas`는 모든 세그먼트의 레플리카 수를 설정합니다. 각 레플리카는 `-clickhouse--`라는 이름의 개별 StatefulSet에서 실행되므로, `shards: 2` 및 `replicas: 3`인 클러스터는 총 6개의 StatefulSet을 실행합니다. + +다음과 같이 개수를 늘리거나 줄이십시오: + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +확장 시 연산자는 레플리카별 새 StatefulSets를 생성하고, 각 파드가 준비 상태가 될 때까지 기다린 다음 새 레플리카에 스키마(schema)를 동기화합니다([Automatic schema sync](#automatic-schema-sync) 참조). 축소 시에는 초과 StatefulSets를 제거하고, 제거된 레플리카가 남긴 오래된 복제된 데이터베이스의 레플리카 등록 정보를 정리합니다. + +
+ ## 세그먼트 스케일링 +
+ +`spec.shards`는 세그먼트 수를 설정합니다. 새 세그먼트가 추가될 때마다 각 레플리카에 대한 StatefulSet 전체가 추가되며, 연산자는 세그먼트마다 [파드 중단 예산](/ko/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) 1개를 생성하므로 한 세그먼트의 중단이 다른 세그먼트에 반영되지 않습니다. + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +각 세그먼트는 데이터의 서로 다른 일부를 보유하며, 연산자는 세그먼트 간에 행을 복사하거나 이동하지 않습니다. `Distributed` 테이블 또는 명시적으로 지정된 라우팅 방식이 행이 어느 세그먼트에 저장될지를 결정하므로, 세그먼트를 추가하면 기존 세그먼트에 이미 저장된 행은 건드리지 않은 채 새로 쓰는 데이터가 저장될 위치만 추가됩니다. + +
+ ## 자동 스키마 동기화 +
+ +`spec.settings.enableDatabaseSync`가 `true`(기본값)로 설정되면 토폴로지가 변경될 때 연산자가 스키마가 계속 일치하도록 유지합니다. + +* **스케일 업 시** — 최소 2개의 레플리카가 준비되면 연산자가 새로 생성된 레플리카에 데이터베이스 정의를 복제합니다. 따라서 새 레플리카는 클러스터의 다른 레플리카와 동일한 `Replicated` 및 통합 데이터베이스를 가진 상태로 합류합니다. +* **스케일 다운 시** — 레플리카가 제거되기 전에 연산자는 `SYSTEM DROP DATABASE REPLICA`를 사용해 각 `Replicated` 데이터베이스에서 해당 레플리카의 등록을 삭제합니다. 따라서 축소된 클러스터는 더 이상 존재하지 않는 `Replicated` 데이터베이스 레플리카를 기다리지 않습니다. + +이 동작은 `Replicated` 데이터베이스와 통합 데이터베이스 엔진에 적용됩니다. 테이블 데이터는 이동하지 않습니다. 행 데이터는 `ReplicatedMergeTree` 테이블에 저장되며, 이 스키마 동기화와 별개로 Keeper를 통해 독립적으로 복제됩니다. 준비된 레플리카가 1개뿐이면 복제할 대상이 없으므로 연산자는 이 단계를 건너뛰고 대상이 없다는 내용을 로그에 남깁니다. + +예를 들어 외부 도구가 스키마 전파를 관리하는 경우 `enableDatabaseSync: false`로 설정해 이 동작을 끌 수 있습니다. 그러면 연산자는 `SchemaInSync` 조건에 `SchemaSyncDisabled` 사유를 보고합니다. + +
+ ## 확인할 상태 +
+ +스케일 조정 작업이 진행되는 동안 사용자 지정 리소스의 진행 상태를 확인하십시오: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| 조건 | 이유 | 의미 | +| -------------------- | ---------------------- | ----------------------------------------------- | +| `ClusterSizeAligned` | `UpToDate` | 실행 중인 레플리카 수가 요청된 토폴로지와 일치합니다 | +| `ClusterSizeAligned` | `ScalingUp` | 연산자가 레플리카를 추가하고 있습니다 | +| `ClusterSizeAligned` | `ScalingDown` | 연산자가 레플리카를 제거하고 있습니다 | +| `SchemaInSync` | `ReplicasInSync` | 모든 레플리카에 데이터베이스가 존재하며 오래된 metadata가 정리되었습니다 | +| `SchemaInSync` | `DatabasesNotCreated` | 연산자가 새 레플리카에 데이터베이스를 생성하는 작업을 아직 완료하지 않았습니다 | +| `SchemaInSync` | `ReplicasNotCleanedUp` | 스케일 다운으로 인해 남은 오래된 레플리카 metadata가 아직 제거되지 않았습니다 | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync`가 `false`로 설정되어 있습니다 | +| `Ready` | `AllShardsReady` | 모든 세그먼트에 준비된 레플리카가 있습니다 | +| `Ready` | `SomeShardsNotReady` | 하나 이상의 세그먼트에 준비된 레플리카가 없습니다 | + +`ClusterSizeAligned`가 `UpToDate`이고, `SchemaInSync`가 `ReplicasInSync`이며, `Ready`가 `AllShardsReady`를 보고하면 스케일 작업이 완료된 것입니다. + +
+ ## Keeper 스케일링 +
+ +`KeeperCluster`는 RAFT 쿼럼을 실행하므로, 연산자는 **한 번에 레플리카 하나씩만** 멤버십을 변경하며 클러스터가 안정적인 상태일 때만 이를 수행합니다. 이렇게 하면 쿼럼을 보호할 수 있습니다. `2F+1` 클러스터는 `F`개의 멤버 장애를 허용하므로, 3개 노드 클러스터는 멤버 1개가 없어도 계속 동작하고 5개 노드 클러스터는 2개가 없어도 계속 동작합니다. + +```yaml +spec: + replicas: 5 # was 3 +``` + +확장 시 연산자는 사용 가능한 가장 낮은 레플리카 ID를 쿼럼에 추가하고, 축소 시에는 가장 높은 ID를 제거합니다. 각 단계에서는 다음 단계가 시작되기 전에 쿼럼이 안정화될 때까지 기다립니다. [Keeper 파드 중단 예산](/ko/products/kubernetes-operator/guides/configuration#pod-disruption-budgets)의 기본값은 자발적 중단 중 쿼럼을 유지하기 위해 `maxUnavailable: replicas/2`로 설정됩니다. + +`ScaleAllowed` 조건은 현재 쿼럼의 멤버 구성을 지금 변경할 수 있는지를 나타냅니다. + +| Reason | Meaning | +| -------------------------- | ----------------------------------------- | +| `ReadyToScale` | 쿼럼이 안정 상태이며 연산자가 멤버를 추가하거나 제거할 수 있음 | +| `ReplicaHasPendingChanges` | 레플리카에 아직 적용 대기 중인 구성 변경이 있음 | +| `ReplicaNotReady` | 레플리카가 준비되지 않아 멤버 구성 변경을 기다리는 중임 | +| `NoQuorum` | 클러스터에 쿼럼이 없어 멤버 구성을 안전하게 변경할 수 없음 | +| `WaitingFollowers` | 연산자가 팔로워가 따라잡기를 기다리는 중임 | + +Keeper는 한 번에 한 단계씩만 조정하고, 각 변경 사이에 `ScaleAllowed`가 `ReadyToScale`로 돌아온 뒤 다음 변경을 진행하십시오. 한 번에 여러 멤버를 변경하더라도 한 번에 하나씩 수행되는 reconcile을 건너뛸 수는 없습니다. 연산자는 여전히 단계마다 쿼럼을 멤버 1개씩 순차적으로 조정합니다. \ No newline at end of file diff --git a/ko/products/kubernetes-operator/guides/tls.mdx b/ko/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..009b539ad --- /dev/null +++ b/ko/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,338 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: TLS로 클러스터 보안 설정하기 +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'security', 'certificates'] +description: 'cert-manager를 사용해 TLS로 ClickHouse 클러스터를 보호하는 방법을 설명합니다. 클라이언트 연결과 Keeper 암호화도 포함됩니다.' +doc_type: 'guide' +--- + +이 가이드에서는 ClickHouse 클러스터를 엔드 투 엔드로 암호화하는 방법을 안내합니다. [cert-manager](https://cert-manager.io/)를 사용해 +인증서를 발급하고, 클러스터에서 TLS를 활성화하며, 보안 포트를 통해 +클라이언트를 연결하고, 암호화를 Keeper 조정 트래픽까지 확장하는 과정이 포함됩니다. + +이 문서는 작업 중심으로 구성되어 있습니다. `spec.settings.tls`의 필드별 참고 정보는 +[구성 → TLS/SSL 구성](/ko/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +및 [API 참조](/ko/products/kubernetes-operator/reference/api-reference#clustertlsspec)를 확인하십시오. + +
+ ## 사전 요구사항 +
+ +* 연산자가 관리하는 실행 중인 ClickHouse 클러스터([Introduction](/ko/products/kubernetes-operator/guides/introduction) 참조) +* 클러스터에 [cert-manager](https://cert-manager.io/docs/installation/)가 설치되어 있어야 합니다. +* 클러스터의 네임스페이스에 대한 `kubectl` 접근 권한. + +연산자는 인증서를 직접 생성하지 않으며, 대신 사용자가 제공한 Kubernetes +`시크릿`을 사용합니다. cert-manager는 해당 `시크릿`을 생성하고 +교체하는 데 권장되는 방법이지만, 필요한 포맷으로 `시크릿`을 작성할 수 있는 도구라면 무엇이든 사용할 수 있습니다. + +
+ ## 연산자가 기대하는 인증서 형식 +
+ +TLS는 `spec.settings.tls.serverCertSecret`이 3개의 키를 포함한 시크릿을 +가리키도록 설정해 활성화합니다: + +| 시크릿 키 | 내용 | +| --------- | ------------------------------- | +| `tls.crt` | PEM으로 인코딩된 서버 인증서 | +| `tls.key` | PEM으로 인코딩된 private key | +| `ca.crt` | PEM으로 인코딩된 CA certificate chain | + +이는 cert-manager가 `Certificate` 리소스에 기록하는 레이아웃과 정확히 같으므로 +변환할 필요가 없습니다. 연산자는 이를 각 파드의 +`/etc/clickhouse-server/tls/`에 마운트하고 ClickHouse의 `openSSL` 구성에 연결합니다. + + + `serverCertSecret`는 `tls.enabled: true`일 때 **필수**입니다. 검증 + 웹훅은 이 값 없이 TLS를 활성화한 cluster를 거부하며, `enabled: true`가 아니면 + `required: true`도 거부합니다. + + +
+ ## 1단계 — cert-manager로 CA Bootstrap +
+ +가장 재현 가능한 구성은 자체 서명된 CA를 생성한 뒤, 해당 CA로 서버 인증서에 서명하는 방식입니다. 이렇게 하면 클라이언트가 신뢰할 수 있는 안정적인 `ca.crt`를 사용할 수 있습니다. + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +운영 환경에서는 자체 서명된 Bootstrap을 실제 issuer(사내 +CA, Vault, ACME 등)로 대체하십시오. 변경되는 것은 Step 2뿐이며, 클러스터 구성은 +동일합니다. + +
+ ## 2단계 — 서버 인증서 발급 +
+ +CA issuer에 리프 인증서를 요청합니다. `dnsNames`는 클라이언트가 +파드에 접속할 때 사용하는 주소를 포함해야 합니다. 연산자는 +`-clickhouse-headless`라는 이름의 단일 **헤드리스** Service를 생성하며, +각 레플리카 파드는 +`-clickhouse---0.-clickhouse-headless..svc.cluster.local`로 +주소를 지정할 수 있습니다. +헤드리스 Service 도메인에 대한 와일드카드를 사용하면 모든 레플리카를 포괄할 수 있습니다: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + 연산자는 클러스터 전반에서 사용하는(로드 밸런싱된) Service를 **생성하지 않습니다**. 연결에 + 사용할 안정적인 단일 endpoint가 필요하면, 클러스터의 파드를 선택하는 `클러스터 IP` Service를 + 직접 생성하고 해당 DNS 이름을 위의 `dnsNames`에 추가하십시오. + + +cert-manager는 `tls.crt`, `tls.key`, `ca.crt`가 포함된 `clickhouse-cert` 시크릿을 생성하며, +만료 전에 이를 갱신합니다. 다음과 같이 존재 여부를 확인하십시오: + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## 단계 3 — 클러스터에서 TLS를 활성화 +
+ +클러스터가 시크릿을 참조하도록 설정합니다: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### 연산자의 동작 +
+ +`tls.enabled: true`로 설정하면 연산자는 다음을 수행합니다. + +* 모든 파드와 헤드리스 Service에 **보안 포트** `9440` + (네이티브 TLS) 및 `8443` (HTTPS)를 **엽니다**. 이 포트는 기존 포트에 추가됩니다. +* **시크릿을** `/etc/clickhouse-server/tls/`에 마운트하고, + `verificationMode: relaxed`, + `disableProtocols: sslv2,sslv3`, `preferServerCiphers: true`가 포함된 + ClickHouse `openSSL` 블록을 생성합니다. 이는 기본값이므로, 재정의하려면 + [TLS 설정 사용자 지정](#custom-tls-settings)을 참조하십시오. + +추가로 `required: true`도 설정하면 연산자는 다음 작업도 수행합니다. + +* **비보안 포트** `9000` (네이티브) 및 `8123` (HTTP)를 **제거**합니다. 따라서 TLS + 포트만 남으며, plaintext 클라이언트는 더 이상 연결할 수 없습니다. +* 파드의 **활성 상태 프로브(liveness probe)**를 보안 네이티브 포트 `9440`으로 **전환**하므로, plaintext 리스너 없이도 상태 + 확인이 계속 작동합니다. + + + TLS 포트 `8443` 및 `9440`은 TLS가 비활성화된 경우에도 웹훅이 **항상** + 예약하므로, 나중에 `tls.enabled`를 전환하더라도 + `spec.additionalPorts` 항목과 충돌하지 않습니다. 자세한 내용은 + [구성 → `additionalPorts`](/ko/products/kubernetes-operator/guides/configuration#additional-ports)를 참조하십시오. + + +
+ ## 4단계 — TLS를 통해 연결 +
+ +`required: true`로 설정하면 클라이언트는 보안 포트를 사용하고 CA를 신뢰해야 합니다. 헤드리스 Service(또는 직접 만든 경우 자체 `클러스터 IP` +Service)를 통해 특정 레플리카 파드에 연결하십시오. + +**네이티브 프로토콜** (`clickhouse-client`, port `9440`): + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (포트 `8443`): + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +로컬 테스트용으로 시크릿에서 `ca.crt`를 직접 가져오세요: + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## Keeper 트래픽 암호화 +
+ +ClickHouse 클러스터에서 TLS를 활성화해도 Keeper로 연결되는 구간은 **암호화되지 않습니다**. +`KeeperCluster`에서는 별도로 TLS를 활성화해야 합니다 — Keeper +서비스용 인증서를 발급하고(Keeper 서비스 `dnsNames`를 사용하는 1–2단계) 이를 참조하십시오: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +Keeper는 보안 클라이언트 포트를 `2281`에서 제공합니다. Keeper에서 TLS가 활성화되면 **ClickHouse 클러스터는 별도 설정 없이 +자동으로 TLS를 통해 Keeper에 연결됩니다** — ClickHouseCluster 측에 +추가로 설정할 것은 없습니다. ClickHouse는 TLS가 활성화된 경우 자체 +`ca.crt` 번들을 사용해 Keeper 인증서를 검증하며, 그렇지 않은 경우에는 시스템 기본 CA 번들을 사용합니다. + +
+ ## 사용자 지정 CA 번들 +
+ +ClickHouse가 서버 인증서에 포함된 CA와 다른 CA를 신뢰해야 하는 경우(예를 들어 +별도의 CA가 서명한 Keeper를 사용하는 경우), `caBundle`을 지정하십시오: + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +연산자는 이 번들을 마운트하고 클라이언트 측 `openSSL` 검증이 인증서 자체의 `ca.crt` 대신 +이 번들을 참조하도록 설정합니다. + +
+ ## TLS 설정 사용자 지정 +
+ +연산자가 생성하는 `openSSL` 블록은 기본값일 뿐, 상한선은 아닙니다. 이 설정은 +기본 서버 구성에 기록되며, `spec.settings.extraConfig` 아래의 모든 항목은 +`config.d/99-extra-config.yaml`에 렌더링됩니다. ClickHouse는 이를 **마지막에** +머지하므로 생성된 값을 재정의합니다. + +기본값을 더 강화하려면 — 예를 들어 엄격한 피어 검증을 요구하고 최소 +프로토콜을 TLS 1.2로 높이려면 — 변경할 `openSSL.server` 키를 설정하십시오: + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +머지는 키별로 수행됩니다. 설정한 값만 대체되며, 생략한 생성 키 +(인증서 경로, CA 구성)는 유지됩니다. 사용 가능한 옵션은 +[`openSSL` server 설정](/ko/reference/settings/server-settings/settings#openssl) +을 참조하고, `extraConfig`가 어떻게 머지되는지는 +[구성 → 내장 추가 구성](/ko/products/kubernetes-operator/guides/configuration#embedded-extra-configuration) +을 참조하십시오. + +
+ ## 확인 및 문제 해결 +
+ +**헤드리스 Service에서 보안 포트가 열려 있는지 확인합니다:** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**파드에 인증서가 마운트되었는지 확인합니다:** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| 증상 | 가능한 원인 | +| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| TLS 활성화 후 파드가 시작되지 않음 / 볼륨 마운트 오류 발생 | 참조된 시크릿이 없거나 `tls.crt`/`tls.key`/`ca.crt`가 없습니다. 연산자는 시크릿 내용을 검증하지 않으므로, 키가 누락되면 별도의 상태 조건으로 표시되지 않고 파드 볼륨 마운트 실패로 나타납니다. `kubectl describe pod`로 파드를 확인하십시오. | +| 웹훅이 클러스터를 거부함 | `enabled: true` 없이 `required: true`가 설정되었거나, `serverCertSecret` 없이 `enabled: true`가 설정되었습니다. | +| 클라이언트 `certificate verify failed` | 클라이언트가 CA를 신뢰하지 않습니다. 시크릿의 `ca.crt`를 전달하거나, 인증서의 `dnsNames`에 연결하려는 호스트가 포함되어 있는지 확인하십시오. | +| 평문 클라이언트가 갑자기 연결되지 않음 | `required: true`로 인해 포트 `9000`/`8123`가 제거되었습니다. 클라이언트를 `9440`/`8443`로 전환하거나, 전환 중에도 비보안 포트를 계속 열어 두려면 `required: false`로 설정하십시오. | + +
+ ## 관련 항목 +
+ +* [구성 → TLS/SSL 구성](/ko/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — 필드 참조 +* [구성 → `additionalPorts`](/ko/products/kubernetes-operator/guides/configuration#additional-ports) — 예약 포트 +* [API 참조 → ClusterTLSSpec](/ko/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [`openSSL` 서버 설정](/ko/reference/settings/server-settings/settings#openssl) — `extraConfig`를 통해 재정의할 수 있는 TLS 옵션 \ No newline at end of file diff --git a/ko/products/kubernetes-operator/install/helm.mdx b/ko/products/kubernetes-operator/install/helm.mdx index 5658d0083..79fc7f034 100644 --- a/ko/products/kubernetes-operator/install/helm.mdx +++ b/ko/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-man helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/ko/products/kubernetes-operator/install/kubectl.mdx b/ko/products/kubernetes-operator/install/kubectl.mdx index bc45e11d8..19d50b3e5 100644 --- a/ko/products/kubernetes-operator/install/kubectl.mdx +++ b/ko/products/kubernetes-operator/install/kubectl.mdx @@ -105,7 +105,7 @@ keeperclusters.clickhouse.com 2025-01-06T00:00:00Z ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/ko/products/kubernetes-operator/navigation.json b/ko/products/kubernetes-operator/navigation.json index f8f6ec80b..4cfcc1550 100644 --- a/ko/products/kubernetes-operator/navigation.json +++ b/ko/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "ko/products/kubernetes-operator/guides/introduction", - "ko/products/kubernetes-operator/guides/configuration" + "ko/products/kubernetes-operator/guides/configuration", + "ko/products/kubernetes-operator/guides/monitoring", + "ko/products/kubernetes-operator/guides/scaling", + "ko/products/kubernetes-operator/guides/tls" ] }, { diff --git a/ko/products/kubernetes-operator/overview.mdx b/ko/products/kubernetes-operator/overview.mdx index 113e53a5c..a57f52364 100644 --- a/ko/products/kubernetes-operator/overview.mdx +++ b/ko/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ ClickHouse Operator는 Kubernetes에서 ClickHouse 클러스터와 ClickHouse Ke * **[소개](/ko/products/kubernetes-operator/guides/introduction)** - ClickHouse Operator 개념 전반을 소개합니다 * **[구성 가이드](/ko/products/kubernetes-operator/guides/configuration)** - ClickHouse 및 Keeper 클러스터를 구성합니다 -* **[모니터링](/ko/products/kubernetes-operator/guides/introduction)** - Prometheus 메트릭을 사용해 clickhouse-operator를 모니터링합니다 +* **[모니터링](/ko/products/kubernetes-operator/guides/monitoring)** - 연산자를 위한 Prometheus 메트릭과 상태 프로브를 설명합니다 +* **[스케일링](/ko/products/kubernetes-operator/guides/scaling)** - 레플리카, 세그먼트, Keeper 쿼럼을 스케일링합니다 +* **[TLS로 보호](/ko/products/kubernetes-operator/guides/tls)** - cert-manager를 사용해 클러스터를 종단 간 암호화합니다
## 참고 diff --git a/ko/products/kubernetes-operator/reference/api-reference.mdx b/ko/products/kubernetes-operator/reference/api-reference.mdx index aecb54569..3bef3cb87 100644 --- a/ko/products/kubernetes-operator/reference/api-reference.mdx +++ b/ko/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'API 참조' 이 문서는 ClickHouse Operator의 사용자 정의 리소스에 대한 자세한 API 참조를 제공합니다. +
+ ## AdditionalPort +
+ +AdditionalPort는 ClickHouse 파드와 연산자가 관리하는 헤드리스 Service에 노출할 추가 TCP 포트 하나를 선언합니다. + +| 필드 | 유형 | 설명 | 필수 | 기본값 | +| ------ | ------- | ------------------------------------------------------------------------------------------------ | ---- | --- | +| `name` | string | 목록 내에서 포트를 고유하게 식별하는 이름입니다. 컨테이너 포트 이름과 Service 포트 이름으로 모두 사용됩니다.
반드시 DNS_LABEL이어야 합니다. | true | | +| `port` | integer | 노출할 TCP 포트 번호입니다. | true | | + +다음에 표시됩니다: + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec는 ClickHouseCluster의 원하는 상태를 정의합니다. -| Field | Type | Description | Required | Default | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | -| `replicas` | integer | 단일 세그먼트의 레플리카 수입니다. | false | 3 | -| `shards` | integer | 클러스터의 세그먼트 수입니다. | false | 1 | -| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | ClickHouse 코디네이션에 사용되는 KeeperCluster에 대한 참조입니다.
네임스페이스를 생략하면 ClickHouseCluster의 네임스페이스가 사용됩니다. | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | ClickHouse 파드 사양에 전달되는 매개변수입니다. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | ClickHouse 컨테이너 사양에 전달되는 매개변수입니다. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse 데이터용 영구 스토리지 사양입니다. | false | | -| `labels` | object (keys:string, values:string) | 리소스에 추가할 레이블입니다. | false | | -| `annotations` | object (keys:string, values:string) | 리소스에 추가할 어노테이션입니다. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget는 각 세그먼트에 대해 생성되는 PDB를 구성합니다.
설정하지 않으면 연산자는 단일 레플리카
세그먼트에는 기본적으로 maxUnavailable=1을, 다중 레플리카 세그먼트에는 minAvailable=1을 사용합니다. | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse 서버의 구성 매개변수입니다. | false | | -| `clusterDomain` | string | ClusterDomain은 DNS 해석에 사용되는 Kubernetes 클러스터 도메인 접미사입니다. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel은 메이저 버전 업그레이드 확인에 사용할 릴리스 채널을 지정합니다.
비어 있으면 마이너 업데이트만 제안됩니다. 허용되는 값은 stable, lts 또는 특정 major.minor 버전(예: 25.8)입니다. | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 버전 감지 Job에 대한 VersionProbeTemplate 재정의입니다. | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret은 클러스터 시크릿이 포함된 외부 관리형 시크릿에 대한 선택적 참조입니다.
해당 시크릿은 클러스터와 동일한 네임스페이스에 있어야 합니다. | false | | +| Field | Type | Description | Required | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | +| `replicas` | integer | 단일 세그먼트의 레플리카 수입니다. | false | 3 | +| `shards` | integer | 클러스터의 세그먼트 수입니다. | false | 1 | +| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | ClickHouse 코디네이션에 사용되는 KeeperCluster에 대한 참조입니다.
네임스페이스를 생략하면 ClickHouseCluster의 네임스페이스가 사용됩니다. | true | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | ClickHouse 파드 사양에 전달되는 매개변수입니다. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | ClickHouse 컨테이너 사양에 전달되는 매개변수입니다. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse 데이터용 영구 스토리지 사양입니다. | false | | +| `labels` | object (keys:string, values:string) | 리소스에 추가할 레이블입니다. | false | | +| `annotations` | object (keys:string, values:string) | 리소스에 추가할 어노테이션입니다. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget는 각 세그먼트에 대해 생성되는 PDB를 구성합니다.
설정하지 않으면 연산자는 단일 레플리카
세그먼트에는 기본적으로 maxUnavailable=1을, 다중 레플리카 세그먼트에는 minAvailable=1을 사용합니다. | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse 서버의 구성 매개변수입니다. | false | | +| `clusterDomain` | string | ClusterDomain은 DNS 해석에 사용되는 Kubernetes 클러스터 도메인 접미사입니다. | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel은 메이저 버전 업그레이드 확인에 사용할 릴리스 채널을 지정합니다.
비어 있으면 마이너 업데이트만 제안됩니다. 허용되는 값은 stable, lts 또는 특정 major.minor 버전(예: 25.8)입니다. | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 버전 감지 Job에 대한 VersionProbeTemplate 재정의입니다. | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret은 클러스터 시크릿이 포함된 외부 관리형 시크릿에 대한 선택적 참조입니다.
해당 시크릿은 클러스터와 동일한 네임스페이스에 있어야 합니다. | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) 배열 | AdditionalPorts는 ClickHouse 파드와 연산자가 관리하는 헤드리스 Service에 노출할 추가 TCP 포트를 선언합니다.
연산자는 Kubernetes 리소스에 포트만 추가하며, ClickHouse 서버가 해당 포트에서 수신 대기하도록 구성하지는 않습니다. | false | | 다음 항목에 나타납니다: @@ -176,16 +192,16 @@ ContainerImage는 리포지토리, 태그 또는 해시를 포함하는 컨테 ContainerTemplateSpec는 클러스터의 컨테이너에 대한 구성 재정의 항목을 설명합니다. -| Field | Type | Description | Required | Default | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -| `image` | [ContainerImage](#containerimage) | Image는 배포할 컨테이너 이미지입니다. | true | | -| `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | 이미지의 ImagePullPolicy이며, 기본값은 IfNotPresent입니다. | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources는 서버 컨테이너의 리소스 요구 사항입니다.
SMP를 통해 연산자 기본값과 딥 머지됩니다. 개별 limits 및 requests는 일치하는
키만 재정의하며, 설정되지 않은 필드는 연산자 기본값을 유지합니다. | false | | +| Field | Type | Description | Required | Default | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | +| `image` | [ContainerImage](#containerimage) | Image는 배포할 컨테이너 이미지입니다. | true | | +| `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | 이미지의 ImagePullPolicy이며, 기본값은 IfNotPresent입니다. | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources는 서버 컨테이너의 리소스 요구 사항입니다.
전체에 적용됩니다. 모든 리소스 필드가 비어 있을 때만 연산자 기본값이 사용됩니다. | false | | | `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts는 컨테이너의 볼륨 마운트 목록입니다.
연산자가 생성한 마운트와 결합됩니다. 연산자 마운트와 `mountPath`를 공유하는 항목은
projected volume으로 머지됩니다. | false | | -| `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env는 컨테이너에 설정할 환경 변수 목록입니다.
이름을 기준으로 연산자 기본값과 머지됩니다. | false | | +| `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env는 컨테이너에 설정할 환경 변수 목록입니다.
이름을 기준으로 연산자 기본값과 머지됩니다. | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | SecurityContext는 컨테이너 실행 시 적용할 보안 옵션을 정의합니다.
nil이 아닌 SecurityContext는 연산자 기본값을 완전히 대체하며, 사용자가
전체 구조체를 책임집니다. nil이면 연산자 기본값이 유지됩니다.
자세한 정보: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | -| `livenessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | LivenessProbe는 연산자의 기본 liveness probe를 재정의합니다. | false | | -| `readinessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | ReadinessProbe는 연산자의 기본 준비 상태 프로브를 재정의합니다. | false | | +| `livenessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | LivenessProbe는 연산자의 기본 liveness probe를 재정의합니다. | false | | +| `readinessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | ReadinessProbe는 연산자의 기본 준비 상태 프로브를 재정의합니다. | false | | 다음에 나타납니다: @@ -302,19 +318,19 @@ KeeperClusterReference는 ClickHouseCluster에서 사용할 KeeperCluster를 식 KeeperClusterSpec는 KeeperCluster의 원하는 상태를 정의합니다. -| Field | Type | Description | Required | Default | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | -| `replicas` | integer | cluster의 레플리카 수입니다. | false | 3 | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Keeper 파드 사양에 전달되는 매개변수입니다. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Keeper 컨테이너 사양에 전달되는 매개변수입니다. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper 데이터용 영구 스토리지 사양입니다. | false | | -| `labels` | object (keys:string, values:string) | 리소스에 추가할 추가 레이블입니다. | false | | -| `annotations` | object (keys:string, values:string) | 리소스에 추가할 추가 어노테이션입니다. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget는 Keeper cluster용으로 생성되는 PDB를 구성합니다.
설정하지 않으면 연산자는 기본적으로 maxUnavailable=replicas/2를 사용합니다.
(2F+1 cluster의 quorum 유지). | false | | -| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper server의 구성 매개변수입니다. | false | | -| `clusterDomain` | string | ClusterDomain은 DNS 확인에 사용되는 Kubernetes cluster 도메인 접미사입니다. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel은 메이저 버전 업그레이드 확인에 사용할 릴리스 채널을 지정합니다.
비어 있으면 마이너 업데이트만 제안됩니다. 허용되는 값은 stable, lts 또는 특정 major.minor 버전(예: 25.8)입니다. | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 버전 감지 job에 대한 VersionProbeTemplate 재정의입니다. | false | | +| Field | Type | Description | Required | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | +| `replicas` | integer | cluster의 레플리카 수입니다. | false | 3 | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Keeper 파드 사양에 전달되는 매개변수입니다. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Keeper 컨테이너 사양에 전달되는 매개변수입니다. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper 데이터용 영구 스토리지 사양입니다. | false | | +| `labels` | object (keys:string, values:string) | 리소스에 추가할 추가 레이블입니다. | false | | +| `annotations` | object (keys:string, values:string) | 리소스에 추가할 추가 어노테이션입니다. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget는 Keeper cluster용으로 생성되는 PDB를 구성합니다.
설정하지 않으면 연산자는 기본적으로 maxUnavailable=replicas/2를 사용합니다.
(2F+1 cluster의 quorum 유지); 단일 레플리카 cluster는 maxUnavailable=1을 사용합니다. | false | | +| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper server의 구성 매개변수입니다. | false | | +| `clusterDomain` | string | ClusterDomain은 DNS 해석에 사용되는 Kubernetes cluster 도메인 접미사입니다. | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel은 메이저 버전 업그레이드 확인에 사용할 릴리스 채널을 지정합니다.
비어 있으면 마이너 업데이트만 제안됩니다. 허용되는 값은 stable, lts 또는 특정 major.minor 버전(예: 25.8)입니다. | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 버전 감지 job에 대한 VersionProbeTemplate 재정의입니다. | false | | 다음에 표시됩니다: @@ -326,16 +342,16 @@ KeeperClusterSpec는 KeeperCluster의 원하는 상태를 정의합니다. KeeperClusterStatus는 KeeperCluster의 관찰된 상태를 정의합니다. -| 필드 | 유형 | 설명 | 필수 | 기본값 | -| ----------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----- | --- | -| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) 배열 | | false | | -| `readyReplicas` | integer | ReadyReplicas는 요청을 처리할 준비가 된 레플리카의 총 개수입니다. | false | | -| `configurationRevision` | string | ConfigurationRevision은 각 레플리카의 대상 구성 리비전을 나타냅니다. | true | | -| `statefulSetRevision` | string | StatefulSetRevision은 각 레플리카의 대상 StatefulSet 리비전을 나타냅니다. | true | | -| `currentRevision` | string | CurrentRevision은 가장 최근에 적용된 KeeperCluster spec 리비전을 나타냅니다. | true | | -| `updateRevision` | string | UpdateRevision은 가장 최근에 요청된 KeeperCluster spec 리비전을 나타냅니다. | true | | -| `observedGeneration` | integer | ObservedGeneration은 컨트롤러가 관찰한 최신 generation을 나타냅니다. | true | | -| `version` | string | Version은 컨테이너 이미지가 보고한 버전을 나타냅니다. | false | | +| 필드 | 유형 | 설명 | 필수 | 기본값 | +| ----------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ----- | --- | +| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) 배열 | | false | | +| `readyReplicas` | integer | ReadyReplicas는 요청을 처리할 준비가 된 레플리카의 총 개수입니다. | false | | +| `configurationRevision` | string | ConfigurationRevision은 각 레플리카의 대상 구성 리비전을 나타냅니다. | true | | +| `statefulSetRevision` | string | StatefulSetRevision은 각 레플리카의 대상 StatefulSet 리비전을 나타냅니다. | true | | +| `currentRevision` | string | CurrentRevision은 가장 최근에 적용된 KeeperCluster spec 리비전을 나타냅니다. | true | | +| `updateRevision` | string | UpdateRevision은 가장 최근에 요청된 KeeperCluster spec 리비전을 나타냅니다. | true | | +| `observedGeneration` | integer | ObservedGeneration은 컨트롤러가 관찰한 최신 generation을 나타냅니다. | true | | +| `version` | string | Version은 컨테이너 이미지가 보고한 버전을 나타냅니다. | false | | | `versionProbeRevision` | string | VersionProbeRevision은 마지막으로 성공한 버전 프로브의 이미지 해시입니다.
이 값이 현재 이미지 해시와 일치하면 캐시된 Version이 바로 사용됩니다. | false | | 다음 항목에 나타납니다: diff --git a/ko/resources/changelogs/cloud/release-status.mdx b/ko/resources/changelogs/cloud/release-status.mdx index 5dc1a51af..a2d405d49 100644 --- a/ko/resources/changelogs/cloud/release-status.mdx +++ b/ko/resources/changelogs/cloud/release-status.mdx @@ -43,7 +43,7 @@ ClickHouse Cloud는 안정성, 새로운 기능에 대한 접근성, 업그레 아래에 표시된 날짜는 ClickHouse가 각 릴리스 채널에 **롤아웃을 시작하는 시점**을 나타내며, 개별 서비스가 업그레이드되는 시점을 의미하지는 않습니다. * 롤아웃은 자동으로 수행되며, 여러 주에 걸쳐 점진적으로 진행됩니다 - * 예약된 업그레이드 윈도우가 구성된 서비스는 채널 롤아웃이 종료된 다음 주의 예약된 윈도우 동안 업그레이드됩니다 (월요일 00:00 UTC 시작) + * 윈도우가 구성된 서비스는 채널 롤아웃이 종료된 다음 주의 윈도우 동안 업그레이드됩니다 (월요일 00:00 UTC 시작) * 롤아웃 일시 중지(예: 휴일 중 동결) 또는 상태 모니터링으로 인해 롤아웃 완료가 지연될 수 있습니다 프로덕션 업그레이드 전에 사전 테스트를 하려면 비프로덕션 서비스에는 Fast 또는 Regular 채널을 사용하고, 프로덕션 서비스에는 Slow 채널을 사용하십시오. @@ -51,19 +51,32 @@ ClickHouse Cloud는 안정성, 새로운 기능에 대한 접근성, 업그레 >\" será usado.", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato da origem Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role da origem Kafka. Use com autenticação por IAM role. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para uma conexão privada segura com a origem Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Tópicos da origem Kafka.", + "type": "string" + }, + "type": { + "description": "Tipo da origem Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "Método de autenticação a ser usado com o stream do Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Formato do stream do Kinesis.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Função do IAM a ser usada para autenticação. Obrigatório se IAM_ROLE for usado.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Tipo de iterador a ser usado ao ler do stream do Kinesis. Se AT_TIMESTAMP for usado, o campo de timestamp deverá ser fornecido.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Região da AWS do stream do Kinesis.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Nome do stream do Kinesis.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Timestamp Unix para iniciar a leitura do stream do Kinesis. Obrigatório se iteratorType for AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Use o enhanced fan-out para o stream do Kinesis.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "Colunas da tabela de destino. Campo obrigatório para todos os tipos de pipe, exceto Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "Banco de dados de destino.", + "type": "string" + }, + "managedTable": { + "description": "A tabela é gerenciada pelo ClickPipes? Campo obrigatório para todos os tipos de pipe, exceto Postgres.", + "type": "boolean" + }, + "roles": { + "description": "O ClickPipe criará um usuário do ClickHouse com estas funções. Adicione aqui suas funções personalizadas, se necessário.", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "Tabela de destino. Campo obrigatório para todos os tipos de pipe, exceto Postgres.", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Tipo de autenticação do schema registry.", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados em PEM para validar o certificado do schema registry.", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "URL do schema. HTTPS é obrigatório.", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "Banco de dados da instância do Postgres à qual se conectar.", + "type": "string" + }, + "host": { + "description": "Host da instância do Postgres à qual se conectar.", + "type": "string" + }, + "port": { + "description": "Porta da instância do Postgres à qual se conectar.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Mapeamentos de tabela para o pipe do Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "Método de autenticação. CONNECTION_STRING é para Azure Blob Storage. IAM_ROLE e IAM_USER são para AWS S3/GCS/DigitalOcean. Se não for fornecido, nenhuma autenticação será usada.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nome do container do Azure Blob Storage. Obrigatório quando type é azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Algoritmo de compressão usado nos arquivos.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "String de conexão para autenticação do Azure Blob Storage. Obrigatória quando authentication é CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Delimitador usado nos arquivos.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato dos arquivos.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "Função do IAM a ser usada com a autenticação por função do IAM. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Se definido como true, o pipe lerá continuamente novos arquivos da source. Se definido como false, o pipe lerá os arquivos apenas uma vez. Os novos arquivos precisam ser enviados em ordem lexicográfica.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Caminho para o(s) arquivo(s) dentro do container do Azure. Usado para sources do Azure Blob Storage. Você pode especificar vários arquivos usando wildcards no estilo bash. Para mais informações, consulte a documentação sobre o uso de wildcards em path: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL da fila SQS para ingestão contínua baseada em eventos. Quando fornecida, os arquivos são ingeridos com base em notificações de eventos do S3, em vez da ordem lexicográfica. Aplicável somente quando isContinuous é true e a autenticação não é public.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo da source do ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Forneça um caminho para o(s) arquivo(s) que deseja ingerir. Você pode especificar vários arquivos usando wildcards no estilo bash. Para mais informações, consulte a documentação sobre o uso de wildcards em path: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "Colunas da tabela de destino. Isso não atualizará o schema da tabela, apenas a configuração do ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Método de autenticação da origem Kafka. Métodos de autenticação compatíveis: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados em PEM para validar o certificado do broker.", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Credenciais da origem Kafka. Escolha uma das opções compatíveis com o método de autenticação.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "IAM role da origem Kafka. Use com autenticação por IAM role. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para uma conexão privada segura com a origem Kafka.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticação a ser usado com o stream do Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "Função do IAM a ser usada para autenticação. Obrigatório se IAM_ROLE for usado.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticação. CONNECTION_STRING é para Azure Blob Storage. IAM_ROLE e IAM_USER são para AWS S3/GCS/DigitalOcean. Se não for fornecido, nenhuma autenticação será usada.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nome do container do Azure Blob Storage. Obrigatório quando o tipo é azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Connection string para autenticação do Azure Blob Storage. Obrigatória quando authentication for CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "IAM role a ser usada com autenticação por IAM role. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Caminho para o(s) arquivo(s) dentro do Azure container. Usado para sources do Azure Blob Storage. Você pode especificar vários arquivos usando wildcards no estilo bash. Para mais informações, consulte a documentação sobre o uso de wildcards no caminho: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "Nome do schema de origem.", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "Nome da tabela de origem.", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "motor de tabela a ser usado na tabela de destino.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "Nome da tabela de destino.", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "Número de linhas a extrair em cada lote.", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Intervalo, em segundos, para sincronizar dados do Postgres.", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "Banco de dados da instância do Postgres à qual se conectar.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "Host da instância do Postgres à qual se conectar.", + "nullable": true, + "type": "string" + }, + "port": { + "description": "Porta da instância do Postgres à qual se conectar.", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "Mapeamentos de tabela a serem adicionados ao pipe do Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "Mapeamentos de tabela a serem removidos do pipe do Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "Mapeamentos de campos do ClickPipe. Isso não atualizará o esquema da tabela, apenas a configuração do ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Nome do ClickPipe.", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "Valida amostras de dados recebidas da fonte de dados. Isso validará a conexão, a disponibilidade e a correção dos dados. Se não estiver habilitado, somente a conexão será validada. Isso não tem efeito nos pipes do Postgres; eles sempre validam somente a conexão e as definições de tabela. Isto é experimental e poderá ser removido no futuro.", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Método de autenticação da origem Kafka. Métodos de autenticação compatíveis: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Brokers da origem Kafka.", + "type": "string" + }, + "caCertificate": { + "description": "Certificados de CA codificados em PEM para validar o certificado do broker.", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Grupo de consumidores da origem Kafka. Se não for fornecido, \"clickpipes-<>\" será usado.", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Credenciais da origem Kafka. Escolha uma das opções compatíveis com o método de autenticação.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Formato da origem Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role da origem Kafka. Use com autenticação por IAM role. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUIDs de Reverse Private Endpoint usados para uma conexão privada segura com a origem Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Tópicos da origem Kafka.", + "type": "string" + }, + "type": { + "description": "Tipo da origem Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticação a ser usado com o stream do Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Formato do stream do Kinesis.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Função do IAM a ser usada para autenticação. Obrigatório se IAM_ROLE for usado.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Tipo de iterador a ser usado ao ler do stream do Kinesis. Se AT_TIMESTAMP for usado, o campo de timestamp deverá ser fornecido.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Região da AWS do stream do Kinesis.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Nome do stream do Kinesis.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Timestamp Unix para iniciar a leitura do stream do Kinesis. Obrigatório se iteratorType for AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Use o enhanced fan-out para o stream do Kinesis.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Método de autenticação. CONNECTION_STRING é para Azure Blob Storage. IAM_ROLE e IAM_USER são para AWS S3/GCS/DigitalOcean. Se não for fornecido, nenhuma autenticação será usada.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Nome do container do Azure Blob Storage. Obrigatório quando o tipo é azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Algoritmo de compressão usado nos arquivos.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Connection string para autenticação do Azure Blob Storage. Obrigatória quando authentication for CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Delimitador usado nos arquivos.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Formato dos arquivos.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "IAM role a ser usada com autenticação por IAM role. Leia mais na documentação do ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Se definido como true, o pipe lerá continuamente novos arquivos da origem. Se definido como false, o pipe lerá os arquivos apenas uma vez. Os novos arquivos precisam ser enviados em ordem lexicográfica.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Caminho para o(s) arquivo(s) dentro do Azure container. Usado para sources do Azure Blob Storage. Você pode especificar vários arquivos usando wildcards no estilo bash. Para mais informações, consulte a documentação sobre o uso de wildcards no caminho: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL da fila SQS para ingestão contínua baseada em eventos. Quando fornecida, os arquivos são ingeridos com base em notificações de eventos do S3, em vez de ordem lexicográfica. Aplicável somente quando isContinuous é true e a autenticação não é public.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo da source do ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Forneça o caminho para o(s) arquivo(s) do(s) qual(is) você deseja fazer a ingestão. Você pode especificar vários arquivos usando wildcards no estilo bash. Para mais informações, consulte a documentação sobre o uso de wildcards no caminho: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "Mapeamentos de campos do ClickPipe. Observe que todas as colunas de destino devem ser incluídas nos mapeamentos.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Nome do ClickPipe.", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "Valida amostras de dados recebidas da fonte de dados. Isso validará a conexão, a disponibilidade e a correção dos dados. Se não estiver habilitado, somente a conexão será validada. Isso não tem efeito nos pipes do Postgres; eles sempre validam somente a conexão e as definições de tabela. Isto é experimental e poderá ser removido no futuro.", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "Permitir colunas Nullable na tabela de destino.", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "Ativar failover para o slot de replicação criado. Exige que um slot de replicação NÃO esteja definido.", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "Número de tabelas paralelas para sincronizar durante a carga inicial.", + "type": "number" + }, + "publicationName": { + "description": "Nome da publication a ser usada para replicação.", + "type": "string" + }, + "pullBatchSize": { + "description": "Número de linhas a extrair em cada lote.", + "type": "number" + }, + "replicationMode": { + "description": "Modo de replicação a ser usado para o pipe.", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "Nome do slot de replicação a ser usado para replicação.", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "Número de linhas para snapshot por partição.", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "Número de tabelas paralelas para snapshot.", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Intervalo, em segundos, para sincronizar dados do Postgres.", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "Colunas a excluir da tabela de destino.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "Lista ordenada de colunas a ser usada como chave de ordenação da tabela de destino.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "Nome do schema de origem.", + "type": "string" + }, + "sourceTable": { + "description": "Nome da tabela de origem.", + "type": "string" + }, + "tableEngine": { + "description": "motor de tabela a ser usado na tabela de destino.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "Nome da tabela de destino.", + "type": "string" + }, + "useCustomSortingKey": { + "description": "Se deve usar uma chave de ordenação personalizada para a tabela de destino.", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "Banco de dados da instância do Postgres à qual se conectar.", + "type": "string" + }, + "host": { + "description": "Host da instância do Postgres à qual se conectar.", + "type": "string" + }, + "port": { + "description": "Porta da instância do Postgres à qual se conectar.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Mapeamentos de tabela para o pipe do Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "Nível desejado de concorrência. Somente para pipes S3. Se definido como 0, a concorrência é ajustada automaticamente com base na memória do cluster.", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU em millicores para cada réplica. Somente para pipes de streaming.", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memória em GB para cada réplica. Somente para pipes de streaming.", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "Número desejado de réplicas. Somente para pipes escaláveis.", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "Nível de concorrência para escalar. Use para escalar pipes do S3.", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU em millicores para cada réplica. Use para escalar pipes de streaming.", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memória em GB para cada réplica. Use para escalar pipes de streaming.", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "Número de réplicas para escalar. Use para escalar pipes do Kafka.", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de threads de download. Número máximo de threads simultâneas de download", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de threads de insert. Número máximo de threads simultâneas de insert", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de threads. Número máximo de threads simultâneas para processamento de arquivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamanho mínimo em bytes do bloco de insert. Tamanho mínimo do bloco de dados para insert (em bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Configuração de parallel distributed insert select. Configuração de parallel distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "processamento paralelo de views. Define se o envio para views attached será habilitado simultaneamente em vez de de forma sequencial", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concorrência do armazenamento de objetos. Número de threads simultâneas para processamento de arquivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Número máximo de arquivos. Número máximo de arquivos a processar em um único lote de insert", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por insert. Número de bytes a processar em um único lote de insert", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de polling do armazenamento de objetos. Configura o intervalo de atualização para consultar a ingestão contínua em busca de novos dados no armazenamento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "usar função de cluster. Define se a função de cluster do ClickHouse será usada para processamento distribuído", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tempo máximo de espera para insert em streaming. Configura o tempo máximo de espera antes de inserir dados no ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de threads de download. Número máximo de threads simultâneas de download", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de threads de insert. Número máximo de threads simultâneas de insert", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de threads. Número máximo de threads simultâneas para processamento de arquivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamanho mínimo do bloco de insert em bytes. Tamanho mínimo do bloco de dados para insert (em bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Parallel distributed insert select. Configuração de parallel distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "processamento paralelo de views. Se deve habilitar o envio para views anexadas simultaneamente em vez de sequencialmente", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concorrência de armazenamento de objetos. Número de threads simultâneas para processamento de arquivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Número máximo de arquivos. Número máximo de arquivos a processar em um único lote de insert", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por insert. Número de bytes a processar em um único lote de insert", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de polling do armazenamento de objetos. Configura o intervalo de atualização para consultar a ingestão contínua em busca de novos dados no armazenamento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "usar função cluster. Se deve usar a função cluster do ClickHouse para processamento distribuído", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tempo máximo de espera para insert em streaming. Configura o período máximo de espera antes de inserir dados no ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Máximo de threads de download. Número máximo de threads simultâneas de download", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Máximo de threads de insert. Número máximo de threads simultâneas de insert", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Máximo de threads. Número máximo de threads simultâneas para processamento de arquivos", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Tamanho mínimo do bloco de insert em bytes. Tamanho mínimo do bloco de dados para insert (em bytes)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Parallel distributed insert select. Configuração de parallel distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "processamento paralelo de views. Se deve habilitar o envio para views anexadas simultaneamente em vez de sequencialmente", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Concorrência de armazenamento de objetos. Número de threads simultâneas para processamento de arquivos", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Número máximo de arquivos. Número máximo de arquivos a processar em um único lote de insert", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Máximo de bytes por insert. Número de bytes a processar em um único lote de insert", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Intervalo de polling do armazenamento de objetos. Configura o intervalo de atualização para consultar a ingestão contínua em busca de novos dados no armazenamento de objetos", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "usar função cluster. Se deve usar a função cluster do ClickHouse para processamento distribuído", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Tempo máximo de espera para insert em streaming. Configura o período máximo de espera antes de inserir dados no ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "Comando para alterar o estado: 'start', 'stop', 'resync'.", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU em milicores para DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memória em GiB para DB ClickPipes. Deve ser 4× a contagem de núcleos da CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU em millicores para DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Memória em GiB para DB ClickPipes. Deve ser 4× o número de núcleos de CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Descrição do endpoint privado reverso. Comprimento máximo de 255 caracteres.", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "Tipo de autenticação do cluster MSK. Obrigatório para o tipo MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN do cluster MSK. Obrigatório para o tipo MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Tipo do endpoint privado reverso.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Nome do serviço de endpoint da VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID da configuração do recurso de VPC. Obrigatório para o tipo VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN do compartilhamento de recurso da VPC. Obrigatório para o tipo VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "ID da chave de acesso (chave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Caminho do bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Provedor do bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "ID exclusivo do bucket de backup", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "ID da chave de acesso (chave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Caminho do bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Provedor do bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Chave de acesso secreta (chave secreta HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "ID da chave de acesso (chave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Caminho do bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Provedor do bucket", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Secret Access Key (chave secreta HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "ID da chave de acesso (chave HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Caminho do bucket", + "type": "string" + }, + "bucketProvider": { + "description": "Provedor do bucket", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Provedor de Cloud no qual o endpoint privado está localizado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descrição do endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador do endpoint privado", + "type": "string" + }, + "region": { + "description": "Região em que o endpoint privado está localizado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "Elementos a adicionar. Executado após o processamento da parte \"remove\".", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "Elementos a remover. Executado antes do processamento da parte \"add\".", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "As origens permitidas, como uma lista de domínios separada por vírgulas", + "type": "string" + }, + "openApiKeys": { + "description": "A versão do endpoint de consulta do serviço", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "As roles", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "Timestamp de criação do convite. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "E-mail do usuário convidado. Somente um usuário com esse e-mail pode entrar usando o convite. O e-mail é armazenado em letras minúsculas.", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "Timestamp de expiração do convite. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "ID exclusivo do convite.", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "Função do membro na organização.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "E-mail do usuário convidado. Somente um usuário com este e-mail pode entrar usando o convite. O e-mail é armazenado em minúsculas.", + "format": "email", + "type": "string" + }, + "role": { + "description": "Papel do membro na organização.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "Descrição opcional do endereço IPv4 ou CIDR IPv4 a partir do qual permitir o acesso", + "type": "string" + }, + "source": { + "description": "IP ou CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "Elementos a adicionar. Executado após o processamento da parte \"remove\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "Elementos a remover. Executado antes do processamento da parte \"add\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "E-mail do membro, conforme definido no perfil pessoal do usuário.", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "Timestamp em que o membro entrou na organização. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "Nome do membro, conforme definido em um perfil pessoal de usuário.", + "type": "string" + }, + "role": { + "description": "Função do membro na organização.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "ID exclusivo do usuário. Se um usuário for membro de várias organizações, esse ID permanecerá o mesmo.", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "Papel do membro na organização.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "ID da chave de acesso IAM.", + "type": "string" + }, + "secretKey": { + "description": "Chave secreta do IAM.", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "Configuração BYOC da organização", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "O timestamp em que a organização foi criada. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "ID exclusivo da organização.", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "Nome da organização.", + "type": "string" + }, + "privateEndpoints": { + "description": "Lista de endpoints privados da organização", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Identificador único do endpoint de interface que você criou na sua VPC com o recurso AWS(Service Name) ou GCP(Target Service)", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "provedor de Cloud em que o endpoint privado está localizado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descrição opcional do endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador do endpoint privado", + "type": "string" + }, + "region": { + "description": "Região em que o endpoint privado está localizado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "Nome da organização.", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "provedor de Cloud em que o endpoint privado está localizado", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Descrição do endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador do endpoint privado", + "type": "string" + }, + "region": { + "description": "Região em que o endpoint privado está localizado", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "Elementos a serem adicionados. Executado após o processamento da parte \"remove\". Em vez disso, use o endpoint `Update Service Basic Details` para modificar os endpoints privados.", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "Elementos a serem removidos. Executado antes do processamento da parte \"add\".", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "Senha.", + "type": "string" + }, + "username": { + "description": "Nome de usuário.", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Identificador exclusivo do endpoint de interface que você criou na sua VPC com o recurso AWS(Service Name), GCP(Target Service) ou AZURE (Private Link Service)", + "type": "string" + }, + "privateDnsHostname": { + "description": "Hostname DNS privado da VPC que você criou", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Descrição do endpoint privado reverso. O tamanho máximo é de 255 caracteres.", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "Nomes DNS internos do endpoint privado reverso.", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "Endpoint ID do endpoint privado reverso.", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "ID do endpoint privado reverso.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "Tipo de autenticação do cluster MSK. Obrigatório para o tipo MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN do cluster MSK. Obrigatório para o tipo MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "Nomes DNS privados do endpoint privado reverso.", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "ID do serviço ClickHouse ao qual o endpoint privado reverso está associado.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Status do endpoint privado reverso.", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "Tipo de endpoint privado reverso.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Nome do serviço de endpoint da VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID da configuração do recurso de VPC. Obrigatório para o tipo VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN do compartilhamento do recurso de VPC. Obrigatório para o tipo VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "Descrição do endpoint privado", + "type": "string" + }, + "id": { + "description": "Identificador do endpoint privado", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Lista de IDs de private endpoints disponíveis que podem ser associados ao serviço", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Este é o ID retornado após configurar uma região para Bring Your Own Cloud (BYOC). Quando o parâmetro byocId é especificado, os parâmetros minReplicaMemoryGb e maxReplicaGb também são obrigatórios, com valores entre os seguintes tamanhos: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Versão do ClickHouse do serviço.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de compliance regulatória do serviço.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Timestamp de criação do serviço. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Data warehouse que contém este serviço", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Role opcional a ser usada para criptografia de disk", + "type": "string" + }, + "encryptionKey": { + "description": "Chave de criptografia de disk fornecida pelo cliente, opcional", + "type": "string" + }, + "encryptionRoleId": { + "description": "O ID da IAM role usada para criptografia. Disponível apenas se hasTransparentDataEncryption for true.", + "type": "string" + }, + "endpoints": { + "description": "Lista de todos os endpoints do serviço.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "true se o serviço deve ter o Transparent Data Encryption (TDE) enabled. O TDE está disponível apenas para tiers de organizações ENTERPRISE e só pode ser enabled na criação do serviço.", + "type": "boolean" + }, + "iamRole": { + "description": "IAM role usada para acessar objetos no S3", + "type": "string" + }, + "id": { + "description": "ID exclusivo do serviço.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Quando definido como true, o serviço pode reduzir a escala até zero quando estiver idle. true por padrão.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Define o timeout mínimo de idling (em minutos). Deve ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de endereços IP com permissão para acessar o serviço", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "true se este serviço for o primary service no data warehouse", + "type": "boolean" + }, + "isReadonly": { + "description": "true se este serviço for read-only. Ele só pode ser read-only se um dataWarehouseId for fornecido.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memória total máxima de cada réplica durante o scaling automático, em Gb. Deve ser um múltiplo de 4 e menor ou igual a 120* para serviços não pagos ou 356* para serviços pagos. * - o tamanho máximo da réplica está sujeito à disponibilidade de hardware do provedor de Cloud na região selecionada.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números de réplicas fora do padrão. Memória máxima de três workers durante o scaling automático, em Gb. Disponível apenas para serviços 'production'. Deve ser um múltiplo de 12 e menor ou igual a 360 para serviços não pagos ou 1068 para serviços pagos.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memória total mínima de cada réplica durante o scaling automático, em Gb. Deve ser um múltiplo de 4 e maior ou igual a 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números de réplicas fora do padrão. Memória mínima de três workers durante o scaling automático, em Gb. Disponível apenas para serviços 'production'. Deve ser um múltiplo de 12 e maior ou igual a 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nome do serviço. String alfanumérica com espaços em branco de até 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas do serviço. O número de réplicas deve estar entre 2 e 20 para o primeiro serviço em um warehouse. Serviços criados em um warehouse existente podem ter número de réplicas tão baixo quanto 1. Restrições adicionais podem se aplicar com base no tier da sua organização. O padrão é 1 para o tier BASIC e 3 para os tiers SCALE e ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Lista de private endpoints", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Profile de instância personalizado. Disponível apenas para tiers de organização ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "provedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Região do serviço.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Selecione fast se quiser receber novos lançamentos do ClickHouse assim que estiverem disponíveis. Você receberá novos recursos mais rapidamente, mas com maior risco de bugs. Selecione slow se quiser adiar os lançamentos para ter mais tempo para testar. Este recurso está disponível apenas para serviços production. O padrão é o regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Estado atual do serviço.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "DEPRECATED para os tiers de organização BASIC, SCALE e ENTERPRISE. Tier do serviço: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Os serviços Production têm scaling, enquanto os Development têm tamanho fixo. Os serviços do Azure não oferecem suporte ao tier Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "O ID da chave de Transparent Data Encryption usada para o serviço. Disponível apenas se hasTransparentDataEncryption for true.", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "Nome do host do serviço", + "type": "string" + }, + "port": { + "description": "Porta numérica", + "type": "number" + }, + "protocol": { + "description": "Protocolo do endpoint: 'https', 'nativesecure', 'mysql'.", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "Nome de usuário opcional para o endpoint", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "Ativar ou desativar o endpoint", + "type": "boolean" + }, + "protocol": { + "description": "Protocolo do endpoint", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "Hash de senha double SHA1 opcional para o protocol MySQL. Se newPasswordHash não for fornecido, esta chave será ignorada e a senha gerada será usada. Algoritmo: echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "Hash de senha opcional. Usado para evitar a transmissão da senha pela rede. Se não for fornecido, uma nova senha será gerada e retornada na resposta. Caso contrário, este hash será usado. Algoritmo: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "Nova senha do serviço. Fornecida apenas se não houver 'newPasswordHash' na solicitação", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "Lista de endpoints do serviço a serem alterados", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "Nome do serviço. String alfanumérica com espaços em branco de até 50 caracteres.", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "Selecione fast se quiser receber novos lançamentos do ClickHouse assim que estiverem disponíveis. Você receberá novos recursos mais rapidamente, mas com maior risco de bugs. Selecione slow se quiser adiar os lançamentos para ter mais tempo para testar. Esse recurso está disponível apenas para serviços de production. default é o canal de lançamento regular.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "O id da chave a ser rotacionada", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "ID de backup opcional usado como estado inicial para o novo serviço. Quando usado, a região e o tier da nova instância devem ser os mesmos da instância original.", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "Este é o ID retornado após configurar uma região para Bring Your Own Cloud (BYOC). Quando o parâmetro byocId é especificado, os parâmetros minReplicaMemoryGb e maxReplicaGb também são obrigatórios, com valores entre os seguintes tamanhos: 48, 116, 172, 232.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de conformidade regulatória do serviço.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "Warehouse de dados que contém este serviço", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Role opcional a ser usada para criptografia de disco", + "type": "string" + }, + "encryptionKey": { + "description": "Chave opcional de criptografia de disco fornecida pelo cliente", + "type": "string" + }, + "endpoints": { + "description": "Lista de endpoints de serviço para habilitar ou desabilitar", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "True se o serviço deve ter o Transparent Data Encryption (TDE) habilitado. O TDE está disponível apenas para tiers de organização ENTERPRISE e só pode ser habilitado na criação do serviço.", + "type": "boolean" + }, + "idleScaling": { + "description": "Quando definido como true, o serviço pode ser reduzido a zero quando estiver idle. True por padrão.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Defina o timeout mínimo de idling (em minutos). Deve ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de endereços IP autorizados a acessar o serviço", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "True se este serviço for read-only. Ele só poderá ser read-only se um dataWarehouseId for fornecido.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memória total máxima de cada réplica durante o scaling automático em Gb. Deve ser um múltiplo de 4 e menor ou igual a 120* para serviços não pagos ou 356* para serviços pagos.* - o tamanho máximo da réplica está sujeito à disponibilidade de hardware do provedor de Cloud na região selecionada. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "Deprecated - impreciso para serviços com números não padrão de réplicas. Memória máxima de três workers durante o scaling automático em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e menor ou igual a 360 para serviços não pagos ou 1068 para serviços pagos.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memória total mínima de cada réplica durante o scaling automático em Gb. Deve ser um múltiplo de 4 e maior ou igual a 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "Deprecated - impreciso para serviços com números não padrão de réplicas. Memória mínima de três workers durante o scaling automático em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e maior ou igual a 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nome do serviço. String alfanumérica com espaços em branco de até 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas do serviço. O número de réplicas deve estar entre 2 e 20 para o primeiro serviço em um warehouse. Os serviços criados em um warehouse existente podem ter apenas 1 réplica. Outras restrições podem se aplicar com base no tier da sua organização. O padrão é 1 para o tier Basic e 3 para os tiers Scale e Enterprise.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "Para associar o serviço a private endpoints, primeiro crie o serviço e depois use o endpoint `Update Service Basic Details` para modificar os private endpoints.", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "Aceite os terms and conditions da private preview. Isso só é necessário ao criar o primeiro serviço na organização, no caso de uma private preview", + "type": "boolean" + }, + "profile": { + "description": "Perfil de instância personalizado. Disponível apenas para tiers de organização ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "provedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Região do serviço.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Selecione fast se quiser receber novos lançamentos do ClickHouse assim que estiverem disponíveis. Você receberá novos recursos mais rapidamente, mas com maior risco de bugs. Selecione slow se quiser adiar os lançamentos para ter mais tempo para testar. Esse recurso está disponível apenas para serviços de production. O padrão é o regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "Deprecated para os tiers de organização BASIC, SCALE e ENTERPRISE. Tier do serviço: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Os serviços de production têm scaling, enquanto os de Development têm tamanho fixo. Os serviços do Azure não oferecem suporte ao tier Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "Senha do serviço recém-criado.", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "As origens permitidas, como uma lista de domínios separados por vírgula", + "type": "string" + }, + "id": { + "description": "O ID do endpoint de consulta do serviço", + "type": "string" + }, + "openApiKeys": { + "description": "Lista de chaves OpenAPI que podem acessar o endpoint de consulta do serviço", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "Lista de roles que podem acessar o endpoint de consulta do serviço", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Quando definido como true, o serviço pode ser reduzido a zero quando estiver idle. true por padrão.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Define o timeout mínimo de idling (em minutos). Deve ser >= 5 minutos.", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "Memória máxima de auto scaling em Gb para uma única réplica. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 4 e menor ou igual a 120 para serviços não pagos ou 356 para serviços pagos.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memória mínima de auto scaling em Gb para uma única réplica. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 4 e maior ou igual a 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "Número de réplicas do serviço. O número de réplicas deve estar entre 2 e 20 para o primeiro serviço em um warehouse. Serviços criados em um warehouse existente podem ter apenas 1 réplica. Restrições adicionais podem se aplicar com base no tier da sua organização. O padrão é 1 para o tier BASIC e 3 para os tiers SCALE e ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Quando definido como true, o serviço pode reduzir a escala até zero quando estiver ocioso. True por padrão.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Define o timeout mínimo de ociosidade (em minutos). Deve ser >= 5 minutos.", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números não padrão de réplicas. Memória máxima de três workers durante o auto-scaling em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e menor ou igual a 360 para serviços não pagos ou 1068 para serviços pagos.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números não padrão de réplicas. Memória mínima de três workers durante o auto-scaling em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e maior ou igual a 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "Número de réplicas do serviço. O número de réplicas deve estar entre 2 e 20 para o primeiro serviço em um warehouse. Serviços criados em um warehouse existente podem ter apenas 1 réplica. Restrições adicionais podem se aplicar com base no tier da sua organização. O padrão é 1 para o tier Basic e 3 para os tiers Scale e Enterprise.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Lista de IDs de endpoints privados disponíveis que podem ser associados ao serviço", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Este é o ID retornado após configurar uma Region para Bring Your Own Cloud (BYOC). Quando o parâmetro byocId é especificado, os parâmetros minReplicaMemoryGb e maxReplicaGb também são obrigatórios, com valores entre os seguintes tamanhos: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Versão do ClickHouse do serviço.", + "type": "string" + }, + "complianceType": { + "description": "Tipo de compliance regulatória do serviço.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Timestamp de criação do serviço. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Warehouse de dados que contém este serviço", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Role opcional a ser usada para criptografia de disk", + "type": "string" + }, + "encryptionKey": { + "description": "Chave opcional de criptografia de disk fornecida pelo cliente", + "type": "string" + }, + "encryptionRoleId": { + "description": "O ID da IAM role usada para criptografia. Isso está disponível apenas se hasTransparentDataEncryption for true.", + "type": "string" + }, + "endpoints": { + "description": "Lista de todos os endpoints do serviço.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "true se o serviço deve ter o Transparent Data Encryption (TDE) enabled. O TDE está disponível apenas para tiers de organizações ENTERPRISE e só pode ser enabled na criação do serviço.", + "type": "boolean" + }, + "iamRole": { + "description": "IAM role usada para acessar objetos no S3", + "type": "string" + }, + "id": { + "description": "ID exclusivo do serviço.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Quando definido como true, o serviço pode reduzir a escala até zero quando estiver ocioso. True por padrão.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Define o timeout mínimo de ociosidade (em minutos). Deve ser >= 5 minutos.", + "type": "number" + }, + "ipAccessList": { + "description": "Lista de endereços IP com permissão para acessar o serviço", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "true se este serviço for o serviço primário no warehouse de dados", + "type": "boolean" + }, + "isReadonly": { + "description": "true se este serviço for read-only. Ele só pode ser read-only se um dataWarehouseId for fornecido.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Memória máxima de auto-scaling em Gb para uma única réplica. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 4 e menor ou igual a 120 para serviços não pagos ou 356 para serviços pagos.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números não padrão de réplicas. Memória máxima de três workers durante o auto-scaling em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e menor ou igual a 360 para serviços não pagos ou 1068 para serviços pagos.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Memória mínima de auto-scaling em Gb para uma única réplica. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 4 e maior ou igual a 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "DEPRECATED - impreciso para serviços com números não padrão de réplicas. Memória mínima de três workers durante o auto-scaling em Gb. Disponível apenas para serviços de 'production'. Deve ser um múltiplo de 12 e maior ou igual a 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Nome do serviço. String alfanumérica com espaços em branco de até 50 caracteres.", + "type": "string" + }, + "numReplicas": { + "description": "Número de réplicas do serviço. O número de réplicas deve estar entre 2 e 20 para o primeiro serviço em um warehouse. Serviços criados em um warehouse existente podem ter apenas 1 réplica. Restrições adicionais podem se aplicar com base no tier da sua organização. O padrão é 1 para o tier Basic e 3 para os tiers Scale e Enterprise.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Lista de endpoints privados", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Profile de instância personalizado. Disponível apenas para tiers de organização ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "provedor de Cloud", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Região do serviço.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Selecione fast se quiser receber novos lançamentos do ClickHouse assim que estiverem disponíveis. Você receberá novos recursos mais rapidamente, mas com maior risco de bugs. Selecione slow se quiser adiar os lançamentos para ter mais tempo para testar. Esse recurso está disponível apenas para serviços de production. O padrão é o regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Estado atual do serviço.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "DEPRECATED para tiers de organização BASIC, SCALE e ENTERPRISE. Tier do serviço: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Serviços de production têm scaling; os de Development têm tamanho fixo. Serviços do Azure não oferecem suporte ao tier Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "O ID da chave do Transparent Data Encryption usada para o serviço. Isso está disponível apenas se hasTransparentDataEncryption for true.", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "Comando para alterar o estado: 'start', 'stop'.", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "Custo total geral de uso em ClickHouse Credits (CHCs).", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "Custo de backup em ClickHouse Credits (CHCs). Aplica-se a entidades dataWarehouse.", + "type": "number" + }, + "computeCHC": { + "description": "Custo de compute em ClickHouse Credits (CHCs). Aplica-se a entidades service e clickpipe.", + "type": "number" + }, + "dataTransferCHC": { + "description": "Custo de transferência de dados em ClickHouse Credits (CHCs). Aplica-se a entidades clickpipe.", + "type": "number" + }, + "initialLoadCHC": { + "description": "Custo de carga inicial e ressincronizações em ClickHouse Credits (CHCs). Aplica-se a entidades clickpipe.", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "Custo da transferência de dados entre regiões da tier1 em ClickHouse Credits (CHCs). Aplica-se a entidades service.", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "Custo da transferência de dados entre regiões da tier2 em ClickHouse Credits (CHCs). Aplica-se a entidades service.", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "Custo da transferência de dados entre regiões da tier3 em ClickHouse Credits (CHCs). Aplica-se a entidades service.", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "Custo da transferência de dados entre regiões da tier4 em ClickHouse Credits (CHCs). Aplica-se a entidades service.", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "Custo de transferência de dados em ClickHouse Credits (CHCs). Aplica-se a entidades service.", + "type": "number" + }, + "storageCHC": { + "description": "Custo de armazenamento em ClickHouse Credits (CHCs). Aplica-se a entidades dataWarehouse.", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "ID do dataWarehouse ao qual esta entidade pertence (ou é).", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "Date de Usage. Data ISO-8601, com base no fuso horário UTC.", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "ID exclusivo da entidade.", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "Nome da entidade.", + "type": "string" + }, + "entityType": { + "description": "Tipo da entidade.", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "Quando true, o registro é imutável. Registros desbloqueados podem sofrer alterações até serem bloqueados.", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "ID do service ao qual esta entidade pertence (ou é). Definido como null para entidades dataWarehouse.", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "Custo total de uso em ClickHouse Credits (CHCs) para esta entidade.", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "Use o ID da chave e o segredo da chave obtidos no console do ClickHouse Cloud: https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "Retorna uma lista com uma única organização associada à API key na solicitação.", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter a lista de organizações disponíveis", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "Retorna os detalhes de uma organização específica. Para obter esses detalhes, a chave de autenticação deve pertencer à organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo que é considerado um erro do cliente." + } + }, + "summary": "Obter detalhes da organização", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "Atualiza os campos da organização. Requer a Role ADMIN da chave de autenticação.", + "parameters": [ + { + "description": "ID da organização a ser atualizada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo que é considerado um erro do cliente." + } + }, + "summary": "Atualizar detalhes da organização", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "Retorna uma lista de todas as atividades da organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Uma data de início para a busca", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Uma data de término para a busca", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é percebido como um erro do cliente." + } + }, + "summary": "Lista de atividades da organização", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "Retorna uma atividade da organização por ID.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da atividade solicitada.", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atividade da organização", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "Cria uma nova infraestrutura BYOC na organização. Retorna a configuração da infraestrutura recém-criada", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Criar infraestrutura BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "Remove uma infraestrutura BYOC da organização", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da infraestrutura BYOC solicitada", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Remover uma infraestrutura BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "Retorna a lista de todos os convites da organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Listar todos os convites", + "tags": [ + "User management" + ] + }, + "post": { + "description": "Cria um convite para a organização.", + "parameters": [ + { + "description": "ID da organização para a qual um usuário será convidado.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Criar um convite", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "Exclui um convite individual da organização.", + "parameters": [ + { + "description": "ID da organização que tem o convite.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é percebido como um erro do cliente." + } + }, + "summary": "Excluir convite da organização", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Retorna os detalhes de um único convite da organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é percebido como um erro do cliente." + } + }, + "summary": "Obter detalhes do convite", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "Retorna uma lista de todas as chaves da organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter a lista de todas as chaves", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "Cria uma nova API key.", + "parameters": [ + { + "description": "ID da organização proprietária da chave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Criar chave", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "Exclui a chave de API. Apenas uma chave não usada para autenticar a solicitação ativa pode ser excluída.", + "parameters": [ + { + "description": "ID da organização que possui a chave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da chave a ser excluída.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Excluir chave", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "Retorna os detalhes de uma única chave.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da chave solicitada.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter detalhes da chave", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "Atualiza as propriedades da API key.", + "parameters": [ + { + "description": "ID da organização proprietária da chave.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID da chave a ser atualizada.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atualizar chave", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "Retorna uma lista de todos os membros da organização.", + "parameters": [ + { + "description": "ID da organização requisitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Listar membros da organização", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "Remove um usuário da organização", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do usuário solicitado.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Remover um membro da organização", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Retorna os detalhes de um único membro da organização.", + "parameters": [ + { + "description": "ID da organização da qual o membro faz parte.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do usuário requisitado.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter detalhes do membro", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "Atualiza o papel (função) do membro na organização.", + "parameters": [ + { + "description": "ID da organização da qual o membro faz parte.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do usuário a ser alterado", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Atualizar membro da organização", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "Obsoleto. Siga a [documentação](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list) para o processo atualizado.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Identificador do provedor de Cloud. Um entre aws, gcp ou azure.", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Identificador da Region em provedores de Cloud específicos.", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Obter a configuração de endpoint privado para a região no provedor de Cloud de uma organização", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "Retorna métricas do Prometheus para todos os serviços de uma organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Retorna uma lista filtrada de métricas do Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo que é considerado um erro do cliente." + } + }, + "summary": "Obter métricas da organização", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "Retorna uma lista de todos os serviços da organização.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Critérios de filtro a serem aplicados ao recuperar o resource. No momento, há suporte apenas à filtragem por tags do resource.", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo que é considerado um erro do cliente." + } + }, + "summary": "Listar serviços da organização", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Cria um novo serviço na organização e retorna o estado atual do serviço e uma senha para acessá-lo. O serviço é iniciado de forma assíncrona.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Criar novo serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "Exclui o serviço. O serviço deve estar no estado interrompido e é excluído de forma assíncrona após essa chamada de método.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço a ser excluído.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que considera ser um erro do cliente." + } + }, + "summary": "Excluir serviço", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Retorna um serviço pertencente à organização", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter detalhes do serviço", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "Atualiza detalhes básicos do serviço, como o nome do serviço ou a lista de acesso por IP.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço a ser atualizado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atualizar detalhes básicos do serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "Retorna a configuração de backup do serviço.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo interpretado como um erro do cliente." + } + }, + "summary": "Obter a configuração de backup do serviço", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "Atualiza a configuração de backup do serviço. Requer a função ADMIN da chave de autenticação. Definir as propriedades com valor nulo redefinirá as propriedades para seus valores padrão.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo interpretado como um erro do cliente." + } + }, + "summary": "Atualizar a configuração de backup do serviço", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "Retorna uma lista de todos os backups do serviço. Os backups mais recentes aparecem primeiro na lista.", + "parameters": [ + { + "description": "ID da organização proprietária do backup.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço a partir do qual o backup foi criado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo interpretado como um erro do cliente." + } + }, + "summary": "Listar backups do serviço", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "Retorna as informações de um único backup.", + "parameters": [ + { + "description": "ID da organização proprietária do backup.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço a partir do qual o backup foi criado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do backup solicitado.", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo interpretado como um erro do cliente." + } + }, + "summary": "Obter detalhes do backup", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas alterações incompatíveis no futuro.

Retorna uma lista de ClickPipes.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Listar ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas alterações incompatíveis no futuro.

Cria um novo ClickPipe.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para o qual o ClickPipe será criado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Criar ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas mudanças incompatíveis no futuro.

Exclui o ClickPipe especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe a ser excluído.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é percebido como um erro do client." + } + }, + "summary": "Excluir ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas mudanças incompatíveis no futuro.

Retorna o ClickPipe especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe solicitado.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é percebido como um erro do client." + } + }, + "summary": "Obter ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas mudanças incompatíveis no futuro.

Atualiza o ClickPipe especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para o qual o ClickPipe será criado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe solicitado.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é percebido como um erro do client." + } + }, + "summary": "Atualizar ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas alterações incompatíveis no futuro.

Altere as configurações de escalonamento do ClickPipe especificado.", + "parameters": [ + { + "description": "ID da organização à qual o serviço pertence.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual o ClickPipe pertence.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe cujas configurações de escalonamento devem ser atualizadas.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Escalonamento do ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas mudanças incompatíveis no futuro.

Retorna as configurações avançadas do ClickPipe especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual o ClickPipe pertence.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe cujas configurações devem ser consultadas.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Obter configurações do ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas alterações incompatíveis no futuro.

Atualize as configurações avançadas do ClickPipe especificado. Envie pares chave-valor em que os valores podem ser strings, números ou booleanos.", + "parameters": [ + { + "description": "ID da organização à qual o serviço pertence.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual o ClickPipe pertence.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe cujas configurações devem ser atualizadas.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não irá processar a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Atualizar configurações do ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas alterações incompatíveis no futuro.

Inicie, pare ou ressincronize o ClickPipe. Parar um ClickPipe interromperá o processo de ingestão em qualquer estado. Iniciar é permitido para ClickPipes no estado \"Stopped\" ou com estado \"Failed\". A ressincronização é compatível apenas com pipes do Postgres e pode ser feita a partir de qualquer estado.", + "parameters": [ + { + "description": "ID da organização à qual o serviço pertence.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual o ClickPipe pertence.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do ClickPipe cujo estado deve ser atualizado.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Atualizar estado do ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Obtenha as configurações de scaling dos DB ClickPipes.\n\nA infraestrutura é compartilhada entre todos os DB ClickPipes no serviço, tanto para a carga inicial quanto para CDC. Para fins de billing, 2 CPU cores e 8 GB de RAM [correspondem](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) a uma compute unit.\n\n**Este endpoint fica disponível assim que pelo menos um DB ClickPipe for provisionado.**", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Obter escalonamento de ClickPipes CDC", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Atualize as configurações de scaling dos DB ClickPipes.\n\nA infraestrutura é compartilhada entre todos os DB ClickPipes no serviço, tanto para a carga inicial quanto para CDC. As configurações de scaling podem levar alguns minutos para serem propagadas por completo.\n\nPara fins de billing, 2 CPU cores e 8 GB de RAM [correspondem](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) a uma compute unit. Se o organization tier da sua organização mudar, os DB ClickPipes serão [redimensionados](https://clickhouse.com/docs/cloud/manage/billing/overview#compute) adequadamente.\n\n**Este endpoint fica disponível assim que pelo menos um DB ClickPipe for provisionado.**", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Atualizar escalonamento de ClickPipes CDC", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Retorna uma lista de reverse private endpoints do serviço especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não processará a solicitação devido a algo que é interpretado como um erro do cliente." + } + }, + "summary": "Listar endpoints privados reversos", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Cria um novo reverse private endpoint.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço proprietário do Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Criar endpoint privado reverso", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Exclui o Reverse Private Endpoint com o ID especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual pertence o Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do Reverse Private Endpoint a ser excluído.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Excluir endpoint privado reverso", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Este endpoint está em beta.** O contrato da API é estável, e não são esperadas breaking changes no futuro.

Retorna o Reverse Private Endpoint com o ID especificado.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço ao qual pertence o Reverse Private Endpoint.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do Reverse Private Endpoint a ser obtido.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não vai processar a solicitação devido a algo considerado um erro do cliente." + } + }, + "summary": "Obter endpoint privado reverso", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "Define uma nova senha para o serviço", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para atualização da senha.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é considerado um erro do client." + } + }, + "summary": "Atualizar a senha do serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "Cria um novo endpoint privado. O endpoint privado será associado a este serviço e a esta organização", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é considerado um erro do client." + } + }, + "summary": "Criar um Private Endpoint", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "Informações necessárias para configurar um Private Endpoint", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que considera ser um erro do cliente." + } + }, + "summary": "Obter a configuração do Private Endpoint", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "Retorna métricas do Prometheus para um serviço.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Retorna uma lista filtrada de métricas do Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que é considerado um erro do client." + } + }, + "summary": "Obter métricas do serviço", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "Atualiza os limites mínimo e máximo de memória por réplica e o comportamento de scaling no modo inativo do serviço. As configurações de memória estão disponíveis apenas para serviços de \"produção\" e devem ser múltiplos de 4 a partir de 8GB. Entre em contato com o suporte para habilitar o ajuste de numReplicas.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para atualizar os parâmetros de scaling.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não consegue ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atualizar as configurações de autoescalonamento do serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "Atualiza os limites mínimo e máximo de memória total e o comportamento de scaling no modo inativo do serviço. As configurações de memória estão disponíveis apenas para serviços de \"produção\" e devem ser múltiplos de 12 a partir de 24GB. Entre em contato com o suporte para habilitar o ajuste de numReplicas.", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para atualizar os parâmetros de scaling.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não consegue ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atualizar as configurações de autoescalonamento do serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "Este é um recurso experimental. Entre em contato com o suporte para ativá-lo.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que considera ser um erro do cliente." + } + }, + "summary": "Excluir o endpoint de consulta do serviço para uma instância específica", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Este é um recurso experimental. Entre em contato com o suporte para ativá-lo.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo que considera ser um erro do cliente." + } + }, + "summary": "Obter o endpoint de consulta do serviço para uma instância específica", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Este é um recurso experimental. Entre em contato com o suporte para ativá-lo.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço solicitado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não consegue ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Criar ou atualizar o endpoint de consulta do serviço para uma instância específica", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "Inicia ou interrompe o serviço", + "parameters": [ + { + "description": "ID da organização proprietária do serviço.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID do serviço para atualizar o estado.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID exclusivo atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não consegue ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Atualizar o estado do serviço", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "Retorna um total geral e uma lista de registros diários de custo de uso da organização, por entidade, para a organização no período consultado (máximo de 31 dias). Todos os dias, tanto na solicitação quanto na resposta, são avaliados com base no fuso horário UTC.", + "parameters": [ + { + "description": "ID da organização solicitada.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Data de início do relatório, por exemplo, 2024-12-19.", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Data de término (inclusive) do relatório, por exemplo, 2024-12-20. Essa data não pode ser superior a 30 dias após from_date (para um período máximo consultado de 31 dias).", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "ID único atribuído a cada solicitação. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "Código de status HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Resposta bem-sucedida" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Descrição detalhada do erro.", + "type": "string" + }, + "status": { + "description": "Código de status HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "O servidor não pode ou não quer processar a solicitação devido a algo percebido como um erro do cliente." + } + }, + "summary": "Obter custos de uso da organização", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/pt-BR/_specs/hyperdx-openapi.json b/pt-BR/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..d69b3a473 --- /dev/null +++ b/pt-BR/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "Função de agregação a ser usada nos dados", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "Campo a ser agregado", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "Campos pelos quais os resultados serão agrupados", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "Tipo de dado da métrica", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "Nome da métrica (para fontes de dados de métricas)", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "ID da fonte de dados desta série", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "Condição de filtro na sintaxe de consulta do Lucene", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "Linguagem de consulta usada na cláusula WHERE", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "Valores de agrupamento, se groupBy tiver sido especificado", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "Valor da primeira série", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "Valor da segunda série", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "Timestamp do ponto de dados (horário de início do bucket)", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "Timestamp final em milissegundos", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "Tamanho do bucket de tempo para agregações", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "Array de configurações de séries", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "Formato dos dados retornados", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "Timestamp inicial em milissegundos", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "API para gerenciar alertas e dashboards do HyperDX", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "Retorna uma lista de todos os alertas da equipe autenticada", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "Lista de alertas", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "Alertas recuperados com sucesso" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + } + }, + "summary": "Listar alertas", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "Cria um novo alerta", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "Criar um alerta baseado em tile", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta criado com sucesso" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Erro do servidor ou falha na validação" + } + }, + "summary": "Criar alerta", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "Exclui um alerta", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "ID do alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Alerta excluído com sucesso" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta não encontrado" + } + }, + "summary": "Excluir alerta", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "Recupera um alerta específico pelo ID", + "operationId": "getAlert", + "parameters": [ + { + "description": "ID do alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "Resposta de um único alerta", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta recuperado com sucesso" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta não encontrado" + } + }, + "summary": "Obter alerta", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "Atualiza um alerta existente", + "operationId": "updateAlert", + "parameters": [ + { + "description": "ID do alerta", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "Atualizar propriedades do alerta", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Alerta atualizado com sucesso" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Alerta não encontrado" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Erro no servidor ou falha de validação" + } + }, + "summary": "Atualizar alerta", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "Retorna dados de séries temporais com base nos parâmetros de série configurados", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "Consulta básica de séries temporais", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "Série de dados de métricas", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "Múltiplas séries com group by", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "Séries de múltiplas fontes de dados", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "Dados de séries temporais agrupados", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "Pontos de dados de séries temporais", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "Dados de séries temporais recuperados com sucesso" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Parâmetros da solicitação inválidos" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Fonte de dados não encontrada" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Erro do servidor" + } + }, + "summary": "Consultar dados de séries do gráfico", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "Retorna uma lista de todos os dashboards da equipe autenticada", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "Dashboards recuperados com sucesso" + }, + "401": { + "description": "Não autorizado" + } + }, + "summary": "Listar dashboards", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "Cria um novo dashboard", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "Dashboard com múltiplos tipos de gráfico", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "Dashboard com gráfico de séries temporais", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "Resposta do dashboard criado", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard criado com sucesso" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Erro do servidor ou falha na validação" + } + }, + "summary": "Criar dashboard", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "Exclui um dashboard", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "ID do dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Dashboard excluído com sucesso" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Dashboard não encontrado" + } + }, + "summary": "Excluir dashboard", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "Retorna um dashboard específico por ID", + "operationId": "getDashboard", + "parameters": [ + { + "description": "ID do dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "Resposta de um único dashboard", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard recuperado com sucesso" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Dashboard não encontrado" + } + }, + "summary": "Obter dashboard", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "Atualiza um dashboard existente", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "ID do dashboard", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "Atualizar propriedades e tiles do dashboard", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "Resposta do dashboard atualizado", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Dashboard atualizado com sucesso" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Não autorizado" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Dashboard não encontrado" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Erro do servidor ou falha na validação" + } + }, + "summary": "Atualizar dashboard", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "Servidor de API de produção", + "url": "https://api.hyperdx.io" + }, + { + "description": "Servidor atual", + "url": "/" + } + ], + "tags": [ + { + "description": "Endpoints para gerenciar dashboards e suas visualizações", + "name": "Dashboards" + }, + { + "description": "Endpoints para gerenciar alertas de monitoramento", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/pt-BR/clickstack/features/dashboards/overview.mdx b/pt-BR/clickstack/features/dashboards/overview.mdx index 74e894ce3..3d7666f21 100644 --- a/pt-BR/clickstack/features/dashboards/overview.mdx +++ b/pt-BR/clickstack/features/dashboards/overview.mdx @@ -31,7 +31,7 @@ Cada visualização começa com a seleção de uma **fonte de dados**, seguida d Por exemplo, você pode criar um gráfico do número de erros (`count()`) agrupados por nome do serviço. -Nos exemplos abaixo, usamos o conjunto de dados remoto disponível em [sql.clickhouse.com](https://sql.clickhouse.com), descrito no guia ["Remote Demo Dataset"](/pt-BR/clickstack/example-datasets/remote-demo-data). **Você também pode reproduzir esses exemplos acessando [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).** +Nos exemplos abaixo, usamos o conjunto de dados remoto disponível em [sql.clickhouse.com](https://sql.clickhouse.com), descrito no guia ["Dataset de demonstração remoto"](/pt-BR/clickstack/example-datasets/remote-demo-data). **Você também pode reproduzir esses exemplos acessando [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).** @@ -59,10 +59,14 @@ Nos exemplos abaixo, usamos o conjunto de dados remoto disponível em [sql.click Observe que você pode filtrar eventos usando uma cláusula SQL `WHERE` ou a sintaxe Lucene e definir o intervalo de tempo em que os eventos devem ser visualizados. Também há suporte para múltiplas séries. - Por exemplo, filtre pelo serviço `frontend` adicionando o filtro `ServiceName:"frontend"`. Adicione uma segunda série para a contagem de eventos ao longo do tempo com o alias `Count` clicando em `Add Series`. + Por exemplo, filtre pelo serviço `frontend` adicionando o filtro `ServiceName:\"frontend\"`. Adicione uma segunda série para a contagem de eventos ao longo do tempo com o alias `Count` clicando em `Add Series`. Visualização simples 2 + Para criar uma série semelhante a uma já existente, você pode duplicá-la em vez de começar do zero. Clique no ícone de cópia (`Duplicate series`) em uma linha de série para inserir uma cópia diretamente abaixo. A cópia mantém as configurações da série de origem, como a métrica, a coluna e o filtro. Depois, você altera apenas os campos que forem diferentes (por exemplo, a agregação) e dá à cópia seu próprio alias. A duplicação está disponível em todos os contextos em que há suporte para múltiplas séries. Ela fica oculta para tipos de visualização que permitem apenas uma série, como `Number`, `Pie` e `Heatmap`. + + O ícone de cópia Duplicate series e sua dica de ferramenta em uma linha de série de gráfico + As visualizações podem ser criadas a partir de qualquer fonte de dados — métricas, traces ou logs. O ClickStack trata todos eles como eventos do tipo wide. Qualquer **coluna numérica** pode ser representada em gráfico ao longo do tempo, e colunas **string**, **date** ou **numéricas** podem ser usadas em agrupamentos. diff --git a/pt-BR/clickstack/ingesting-data/collector.mdx b/pt-BR/clickstack/ingesting-data/collector.mdx index 1716132d5..05d9a46aa 100644 --- a/pt-BR/clickstack/ingesting-data/collector.mdx +++ b/pt-BR/clickstack/ingesting-data/collector.mdx @@ -42,7 +42,7 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam - Recomendamos usar a distribuição oficial do coletor do ClickStack (/clickstack/deployment/hyperdx-only#otel-collector) na função de gateway ao enviar para o Managed ClickStack, sempre que possível. Se você optar por trazer o seu próprio, certifique-se de que ele inclua o [exportador ClickHouse](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter). + Recomendamos [usar a distribuição oficial do coletor do ClickStack](/pt-BR/clickstack/deployment/hyperdx-only#otel-collector) na função de gateway ao enviar para o Managed ClickStack, sempre que possível. Se você optar por trazer o seu próprio, certifique-se de que ele inclua o [exportador ClickHouse](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter). O collector pode ser implantado via Helm (recomendado para Kubernetes) ou via Docker. O [chart do Helm do ClickStack](https://github.com/ClickHouse/ClickStack-helm-charts) oficial incorpora o [chart do Helm do OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-helm-charts) upstream como um subchart com a imagem da distribuição ClickStack pré-configurada — consulte o [guia de implantação do ClickStack via Helm](/pt-BR/clickstack/deployment/helm) se quiser instalar a stack completa, incluindo o HyperDX. Para uma implantação standalone do collector, o chart upstream pode ser usado diretamente com a imagem do ClickStack, conforme mostrado abaixo. @@ -104,7 +104,7 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam - A instância de destino do ClickHouse é configurada por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` e `CLICKHOUSE_PASSWORD`. O `CLICKHOUSE_ENDPOINT` deve ser o endpoint HTTP completo do ClickHouse Cloud, incluindo o protocolo e a porta — por exemplo, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. + A instância de destino do ClickHouse é configurada por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD`. O `CLICKHOUSE_ENDPOINT` deve ser o endpoint HTTP completo do ClickHouse Cloud, incluindo o protocolo e a porta — por exemplo, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. Para obter detalhes sobre como recuperar suas credenciais do Managed ClickStack, consulte [aqui](/pt-BR/products/cloud/guides/sql-console/connection-details). @@ -118,7 +118,7 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam #### Configuração da instância Managed ClickStack - O OpenTelemetry collector pode ser configurado para usar uma instância do Managed ClickStack por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` e `CLICKHOUSE_PASSWORD`. A forma como essas variáveis são definidas depende do método de implantação utilizado: + O OpenTelemetry collector pode ser configurado para usar uma instância do Managed ClickStack por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD`. A forma como essas variáveis são definidas depende do método de implantação utilizado: @@ -159,10 +159,10 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam #### Docker Compose - No Docker Compose, modifique a configuração do collector usando as mesmas variáveis de ambiente mencionadas acima: + Com o Docker Compose, modifique a configuração do collector usando as mesmas variáveis de ambiente mencionadas acima: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # extensão health_check - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # extensão de métricas + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,21 +261,21 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam - A instância de destino do ClickHouse é configurada por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` e `CLICKHOUSE_PASSWORD`. O `CLICKHOUSE_ENDPOINT` deve ser o endpoint HTTP completo do ClickHouse, incluindo o protocolo e a porta — por exemplo, `http://localhost:8123`. + A instância de destino do ClickHouse é configurada por meio das variáveis de ambiente `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD`. O `CLICKHOUSE_ENDPOINT` deve ser o endpoint HTTP completo do ClickHouse, incluindo o protocolo e a porta — por exemplo, `http://localhost:8123`. **Essas variáveis de ambiente podem ser usadas com qualquer uma das distribuições Docker que incluem o conector.** **Usuário de produção** - Em produção, use um usuário com as [credenciais adequadas](/pt-BR/clickstack/ingesting-data/collector#creating-an-ingestion-user). + Você deve usar um usuário com as [credenciais adequadas](/pt-BR/clickstack/ingesting-data/collector#creating-an-ingestion-user) em produção. ### Modificando a configuração #### Configurando a instância do ClickHouse - O OpenTelemetry collector pode ser configurado para usar uma instância do ClickHouse por meio das variáveis de ambiente `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` e `CLICKHOUSE_PASSWORD`. A forma como essas variáveis são definidas depende do método de implantação escolhido: + O OpenTelemetry collector pode ser configurado para usar uma instância do ClickHouse por meio das variáveis de ambiente `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD`. A forma como essas variáveis são definidas depende do método de implantação escolhido: @@ -322,7 +322,7 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam Com o Docker Compose, modifique a configuração do collector usando as mesmas variáveis de ambiente mencionadas acima: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ Os usuários que implantam OTel collectors na função de agent normalmente usam CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # extensão health_check - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # extensão de métricas + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/pt-BR/clickstack/mcp.mdx b/pt-BR/clickstack/mcp.mdx index 76e57406a..6d5f6f2a0 100644 --- a/pt-BR/clickstack/mcp.mdx +++ b/pt-BR/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'Servidor MCP do ClickStack' sidebarTitle: 'Servidor MCP' description: 'Conecte assistentes de IA ao ClickStack usando o servidor do Model Context Protocol (MCP)' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'IA', 'observabilidade', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'IA', 'observabilidade', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -23,108 +23,218 @@ O servidor MCP está disponível nos seguintes tipos de implantação do ClickSt | ------------------------------------------------- | ----------- | | **Open Source ClickStack** | Disponível | | **BYOC (Bring Your Own Cloud)** | Disponível | -| **Managed ClickStack** | Em breve | +| **ClickStack no ClickHouse Cloud** | Disponível | | **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Sem suporte | - - **Managed ClickStack** + + **Configuração diferente para ClickHouse Cloud vs OSS/BYOC** - O suporte ao servidor MCP para o Managed ClickStack está em desenvolvimento e estará disponível em breve. As instruções nesta página se aplicam às implantações Open Source ClickStack e BYOC. - + O ClickStack no ClickHouse Cloud usa um endpoint e um método de autenticação diferentes das implantações Open Source e BYOC. Consulte a seção [ClickStack no ClickHouse Cloud](#managed-clickstack) abaixo para a configuração específica do Cloud. + -
- ## Pré-requisitos +
+ ## ClickStack no ClickHouse Cloud
-Antes de conectar um cliente MCP, você precisa de: +O ClickStack no ClickHouse Cloud se conecta por meio do endpoint MCP do ClickHouse Cloud em `https://mcp.clickhouse.cloud/clickstack` e usa autenticação OAuth 2.0. A autenticação com API key não tem suporte nesse endpoint. -* Uma instância do ClickStack em execução (consulte [Implantação](/pt-BR/clickstack/deployment/overview) para ver as opções de configuração) -* Uma **Personal API Access Key** — encontre a sua no HyperDX em **Team Settings → API Keys → Personal API Access Key** +
+ ### Pré-requisitos +
-Personal API Access Key em Team Settings +* Um serviço do ClickHouse Cloud em execução com o [ClickStack ativado](/pt-BR/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud) +* [MCP ativado](/pt-BR/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) no serviço — abra o console do Cloud, clique em **Connect**, selecione **Connect with MCP** e ative-o - - A Personal API Access Key é diferente da **API key de ingestão** encontrada em Team Settings, que é usada para autenticar dados de telemetria enviados ao coletor OpenTelemetry. - +
+ ### Endpoint +
+ +```text +https://mcp.clickhouse.cloud/clickstack +``` -
- ## Endpoint +A autenticação usa OAuth 2.0. Quando seu cliente MCP se conecta pela primeira vez, ele abre uma janela do navegador para que você faça login com suas credenciais do ClickHouse Cloud. Não é necessária nenhuma chave de API. + +
+ ### Conectar um cliente MCP
-O servidor MCP está disponível no caminho `/api/mcp` na URL de frontend do seu ClickStack: +Cada cliente gerencia automaticamente o fluxo OAuth ao se conectar pela primeira vez. -Por exemplo, com uma implantação local padrão: + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -Substitua `localhost:8080` pelo host e pela porta da sua instância se você tiver alterado os valores padrão. + Abra o Claude Code e execute `/mcp`; depois, selecione `clickstack-cloud` para concluir o fluxo OAuth. + - - Os exemplos nesta página usam a URL do app de frontend (porta `8080` por padrão). Você também pode acessar o servidor MCP diretamente pelo backend em `/mcp`, mas nem todas as implantações expõem o backend, por isso esta documentação usa o caminho do frontend. - + + Adicione o seguinte a `.cursor/mcp.json`: -O servidor MCP usa o transporte **Streamable HTTP** com autenticação por **token Bearer**. + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Adicione o seguinte a `.vscode/mcp.json`: + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Adicione o seguinte a `opencode.json`: + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Qualquer cliente MCP com suporte a **Streamable HTTP** com OAuth pode se conectar. Configure-o com: -
- ## Como conectar um cliente MCP + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### Direcionando para um serviço específico
-Os exemplos abaixo mostram como configurar clientes MCP populares. Substitua `` pela URL da sua instância (por exemplo, `http://localhost:8080`) e `` pela sua Personal API Access Key. +Sem o cabeçalho `x-service-id`, as solicitações são direcionadas por padrão ao primeiro serviço ClickStack provisionado e usado pela sua conta. Para direcionar as solicitações a outro serviço, passe `x-service-id: ` como cabeçalho na configuração do seu cliente MCP. -
- ### Claude code +
+ ## Open Source e BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +As implantações Open Source e BYOC usam o endpoint MCP integrado da sua instância do ClickStack com autenticação via token Bearer. -
- ### Cursor +
+ ### Pré-requisitos
-Adicione o seguinte ao `.cursor/mcp.json` do seu projeto ou às configurações globais do Cursor: +* Uma instância do ClickStack em execução (consulte [Implantação](/pt-BR/clickstack/deployment/overview) para ver as opções de configuração) +* Uma **Personal API Access Key** — encontre a sua no HyperDX em **Team Settings → API Keys → Personal API Access Key** -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Personal API Access Key em Team Settings + + + A Personal API Access Key é diferente da **API key de ingestão** encontrada em Team Settings, que é usada para autenticar dados de telemetria enviados ao coletor OpenTelemetry. + -
- ### OpenCode +
+ ### Endpoint
-Adicione o seguinte à configuração do seu `opencode.json`: +O servidor MCP está disponível no caminho `/api/mcp` na URL de frontend do seu ClickStack. Por exemplo, com uma implantação local padrão, a URL é `http://localhost:8080/api/mcp`. Substitua `localhost:8080` pelo host e pela porta da sua instância se você tiver alterado os valores padrão. -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + Os exemplos nesta página usam a URL do app de frontend (porta `8080` por padrão). Você também pode acessar o servidor MCP diretamente pelo backend em `/mcp`, mas nem todas as implantações expõem o backend, por isso esta documentação usa o caminho do frontend. + + +O servidor MCP usa o transporte **Streamable HTTP** com autenticação por **token Bearer**. -
- ### Outros clientes +
+ ### Conectar um cliente MCP
-Qualquer cliente MCP com suporte ao transporte **Streamable HTTP** pode se conectar. Configure-o com: +Substitua `` pela URL da sua instância (por exemplo, `http://localhost:8080`) e `` pela sua Personal API Access Key. + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + Adicione o seguinte a `.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Adicione o seguinte a `.vscode/mcp.json`: + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + Adicione o seguinte a `opencode.json`: + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Qualquer cliente MCP com suporte a **Streamable HTTP** pode se conectar. Configure-o com: -* **URL:** `/api/mcp` -* **Cabeçalho:** `Authorization: Bearer ` + * **URL:** `/api/mcp` + * **Cabeçalho:** `Authorization: Bearer ` + +
## O que você pode fazer com o MCP? @@ -143,9 +253,11 @@ Depois de se conectar, seu assistente de IA tem acesso a várias ferramentas que O conjunto específico de ferramentas pode se expandir com o tempo. Seu cliente MCP descobrirá automaticamente as ferramentas disponíveis ao se conectar.
- ## Uso por múltiplas equipes + ## Uso por múltiplas equipes (OSS/BYOC)
+Isso se aplica apenas a implantações Open Source e BYOC. Para o ClickStack no ClickHouse Cloud, consulte [Direcionar para um serviço específico](#managed-service-override). + Por padrão, as solicitações MCP operam no contexto da sua equipe primária. Se você pertence a várias equipes, pode direcionar a solicitação para uma equipe específica incluindo o cabeçalho `x-hdx-team` com o ID da equipe junto com o cabeçalho `Authorization`. Se o cabeçalho for omitido, sua equipe primária será usada. Se você especificar uma equipe da qual não faz parte, a solicitação será rejeitada com um erro `401`. Use a ferramenta de listagem de equipes do seu cliente MCP para descobrir a quais equipes você tem acesso e qual delas está ativa. @@ -154,6 +266,29 @@ Use a ferramenta de listagem de equipes do seu cliente MCP para descobrir a quai ## Solução de problemas
+
+ ### ClickStack no ClickHouse Cloud +
+ + + * Confirme que seu cliente MCP oferece suporte a OAuth 2.0. Clients que oferecem suporte apenas a token Bearer ou ao transporte stdio não conseguem se autenticar com o endpoint do Cloud. + * Verifique se o navegador não está bloqueando o pop-up ou o redirecionamento do OAuth. + * Verifique se sua conta do ClickHouse Cloud tem acesso à organização e ao serviço. + + + + * Confirme que você está usando o endpoint do ClickStack (`https://mcp.clickhouse.cloud/clickstack`), e não o endpoint MCP geral do Cloud (`https://mcp.clickhouse.cloud/mcp`). + * Verifique se o [MCP está habilitado](/pt-BR/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) no serviço no console do Cloud. + + + + Sem o header `x-service-id`, as solicitações são direcionadas por padrão para o primeiro serviço do ClickStack provisionado e usado pela sua conta. Envie o header para direcioná-las a um serviço específico. Consulte [Direcionar para um serviço específico](#managed-service-override). + + +
+ ### Open Source e BYOC +
+ * Verifique se você está usando a **Personal API Access Key** (não a API key de ingestão). * Confirme se a chave está incluída como um token `Bearer` no cabeçalho `Authorization`. diff --git a/pt-BR/clickstack/navigation.json b/pt-BR/clickstack/navigation.json index 75561f468..b1a7be3d1 100644 --- a/pt-BR/clickstack/navigation.json +++ b/pt-BR/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "pt-BR/_specs/hyperdx-openapi.json", "root": "pt-BR/clickstack/api-reference" } ] diff --git a/pt-BR/concepts/features/operations/update/replacing-merge-tree.mdx b/pt-BR/concepts/features/operations/update/replacing-merge-tree.mdx index b86a81cc1..9d700a9d4 100644 --- a/pt-BR/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/pt-BR/concepts/features/operations/update/replacing-merge-tree.mdx @@ -1,10 +1,10 @@ --- slug: /guides/replacing-merge-tree -title: 'Trabalhando com o mecanismo ReplacingMergeTree' -description: 'Guia sobre como usar o mecanismo ReplacingMergeTree no ClickHouse' +title: 'Trabalhando com o motor ReplacingMergeTree' +description: 'Guia sobre como usar o motor ReplacingMergeTree no ClickHouse' keywords: ['replacingmergetree', 'inserções', 'desduplicação'] doc_type: 'guide' -sidebarTitle: 'Trabalhando com o mecanismo ReplacingMergeTree' +sidebarTitle: 'Trabalhando com o motor ReplacingMergeTree' --- import { Image } from "/snippets/components/Image.jsx"; @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --selecionar 100 linhas aleatórias +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --selecionar 100 linhas aleatórias +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -O resultado das operações acima será de 16.000 linhas, ou seja, 10.000 + 5.000 + 1.000. O total correto aqui é que, na realidade, deveríamos ter apenas 1.000 linhas a menos do que o total original, ou seja, 10.000 - 1.000 = 9.000. +O resultado das operações acima será de 16.000 linhas, ou seja, 10.000 + 5.000 + 1.000. Na realidade, deveríamos ter apenas 1.000 linhas a menos do que o total original, ou seja, 10.000 - 1.000 = 9.000. ```sql SELECT count() @@ -207,10 +207,10 @@ FROM posts_updateable ┌─count()─┐ │ 10000 │ └─────────┘ -1 linha no conjunto. Elapsed: 0.002 sec. +1 row in set. Elapsed: 0.002 sec. ``` -Seus resultados vão variar aqui dependendo das mesclagens que já ocorreram. Podemos ver que o total aqui é diferente porque temos linhas duplicadas. Aplicar `FINAL` à tabela retorna o resultado correto. +Seus resultados vão variar dependendo das mesclagens que já ocorreram. Podemos ver que o total é diferente por causa de linhas duplicadas. Aplicar `FINAL` à tabela retorna o resultado correto. ```sql SELECT count() @@ -359,11 +359,11 @@ Como discutido em Exploiting Partitions with ReplacingMergeTree, recomendamos o ### Ajustando mesclagens para melhorar o desempenho das consultas
-Por padrão, min_age_to_force_merge_seconds e min_age_to_force_merge_on_partition_only são definidos como 0 e false, respectivamente, o que desativa esses recursos. Nessa configuração, o ClickHouse aplicará o comportamento padrão de mesclagem, sem forçar mesclagens com base na idade da partição. +Por padrão, `min_age_to_force_merge_seconds` e `min_age_to_force_merge_on_partition_only` são definidos como 0 e false, respectivamente, o que desativa esses recursos. Nessa configuração, o ClickHouse aplicará o comportamento padrão de mesclagem, sem forçar mesclagens com base na idade da partição. -Se um valor for especificado para min_age_to_force_merge_seconds, o ClickHouse ignorará as heurísticas normais de mesclagem para partes mais antigas do que o período especificado. Embora isso geralmente só seja eficaz quando o objetivo é minimizar o número total de partes, pode melhorar o desempenho das consultas no ReplacingMergeTree ao reduzir o número de partes que precisam ser mescladas no momento da consulta. +Se um valor for especificado para `min_age_to_force_merge_seconds`, o ClickHouse ignorará as heurísticas normais de mesclagem para partes mais antigas do que o período especificado. Embora isso geralmente só seja eficaz quando o objetivo é minimizar o número total de partes, pode melhorar o desempenho das consultas no ReplacingMergeTree ao reduzir o número de partes que precisam ser mescladas no momento da consulta. -Esse comportamento pode ser ajustado ainda mais definindo min_age_to_force_merge_on_partition_only=true, o que exige que todas as partes da partição sejam mais antigas do que min_age_to_force_merge_seconds para que ocorra uma mesclagem agressiva. Essa configuração permite que partições mais antigas sejam gradualmente mescladas até se tornarem uma única parte, o que consolida os dados e mantém o desempenho das consultas. +Esse comportamento pode ser ajustado ainda mais definindo `min_age_to_force_merge_on_partition_only=true`, o que exige que todas as partes da partição sejam mais antigas do que `min_age_to_force_merge_seconds` para que ocorra uma mesclagem agressiva. Essa configuração permite que partições mais antigas sejam gradualmente mescladas até se tornarem uma única parte, o que consolida os dados e mantém o desempenho das consultas. * Os parâmetros do snapshot não podem ser editados após a criação do ClickPipe. Se você quiser alterá-los, terá que criar um novo ClickPipe. -* Ao adicionar tabelas a um ClickPipe existente, você não pode alterar os parâmetros do snapshot. O ClickPipe usará os parâmetros existentes para as novas tabelas. -* A coluna da chave de partição não deve conter `NULL`, pois esses valores são ignorados pela lógica de particionamento. \ No newline at end of file +* Ao adicionar tabelas a um ClickPipe existente, você não pode alterar os parâmetros do snapshot. O ClickPipe usará os parâmetros existentes para as novas tabelas. \ No newline at end of file diff --git a/pt-BR/integrations/language-clients/go/config-reference.mdx b/pt-BR/integrations/language-clients/go/config-reference.mdx index b0bdd1f71..7ad6a6883 100644 --- a/pt-BR/integrations/language-clients/go/config-reference.mdx +++ b/pt-BR/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### Timeouts
-| Opção | Tipo | Padrão | Parâmetro DSN | Descrição | Prática recomendada | Quando mal configurado | -| ------------- | --------------- | ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Tempo máximo para estabelecer uma nova conexão. Também controla o tempo de espera para obter uma conexão do pool quando `MaxOpenConns` é atingido. | 5-10s em LAN, 15-30s em WAN/Cloud. Nunca abaixo de 1s. | Curto demais: `"clickhouse: acquire conn timeout"` durante congestionamento. Longo demais (> 60s): a aplicação fica travada durante indisponibilidades. | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Tempo máximo de espera por uma resposta do servidor em cada chamada de leitura. É aplicado por bloco, não à consulta inteira. O deadline do contexto tem precedência. | 10-30s para consultas interativas curtas; 5-30m para consultas analíticas longas. | Curto demais: `"i/o timeout"` ou `"read: connection reset by peer"` no meio da consulta; o servidor continua executando. Longo demais: conexões inativas não são detectadas. | +| Opção | Tipo | Padrão | Parâmetro DSN | Descrição | Prática recomendada | Quando mal configurado | +| ------------- | --------------- | ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Tempo máximo para estabelecer uma nova conexão. Também controla o tempo de espera para obter uma conexão do pool quando `MaxOpenConns` é atingido. | 5-10s em LAN, 15-30s em WAN/Cloud, 1-2m ao se conectar a um serviço pausado do ClickHouse Cloud. Nunca abaixo de 1s. | Curto demais: `"clickhouse: acquire conn timeout"` durante congestionamento, ou falha de conexão antes que um serviço Cloud pausado termine de reativar. Longo demais (> 60s): a aplicação fica travada durante indisponibilidades. | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Tempo máximo de espera por uma resposta do servidor em cada chamada de leitura. É aplicado por bloco, não à consulta inteira. O deadline do contexto tem precedência. | 10-30s para consultas interativas curtas; 5-30m para consultas analíticas longas. | Curto demais: `"i/o timeout"` ou `"read: connection reset by peer"` no meio da consulta; o servidor continua executando. Longo demais: conexões inativas não são detectadas. | + + + Um serviço do ClickHouse Cloud que ficou ocioso é pausado e reativado na primeira conexão recebida. A reativação normalmente leva algumas dezenas de segundos, período durante o qual a tentativa de conexão fica bloqueada. Se `DialTimeout` for menor que o tempo de reativação, a primeira consulta após um período de ociosidade falha com timeout de conexão em vez de ser executada. + + Defina `DialTimeout` como `1m`–`2m` para clientes que possam ser os primeiros a acessar um serviço pausado. A contrapartida é uma detecção de falha mais lenta durante uma indisponibilidade real — as tentativas de conexão ficam bloqueadas até o timeout completo antes de retornar erro — portanto, prefira limitar o timeout maior à primeira conexão ou usar deadlines de contexto em consultas individuais para limitar a latência de ponta a ponta. + *** diff --git a/pt-BR/integrations/language-clients/go/configuration.mdx b/pt-BR/integrations/language-clients/go/configuration.mdx index 875146c46..e73326aa6 100644 --- a/pt-BR/integrations/language-clients/go/configuration.mdx +++ b/pt-BR/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: 'reference' Ao abrir uma conexão, uma struct `Options` pode ser usada para controlar o comportamento do cliente. As configurações a seguir estão disponíveis: -| Parâmetro | Tipo | Padrão | Descrição | -| ---------------------- | -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `Protocol` | `Protocol` | `Native` | Protocolo de transporte: `Native` (TCP) ou `HTTP`. Consulte [TCP vs HTTP](#tcp-vs-http). | -| `Addr` | `[]string` | — | Lista de endereços `host:port`. Para vários nós, consulte [Conectando-se a vários nós](#connecting-to-multiple-nodes). | -| `Auth` | `Auth` | — | Credenciais de autenticação (`Database`, `Username`, `Password`). Consulte [Autenticação](#authentication). | -| `TLS` | `*tls.Config` | `nil` | Configuração de TLS. Um valor diferente de nil habilita TLS. Consulte [TLS](#using-tls). | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Função de dial personalizada para controlar como as conexões TCP são estabelecidas. | -| `DialTimeout` | `time.Duration` | `30s` | Tempo máximo de espera ao abrir uma nova conexão. | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Número máximo de conexões abertas a qualquer momento. | -| `MaxIdleConns` | `int` | `5` | Número de conexões ociosas mantidas no pool. | -| `ConnMaxLifetime` | `time.Duration` | `1h` | Tempo máximo de vida de uma conexão no pool. Consulte [Pool de conexões](#connection-pooling). | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Estratégia para escolher um nó de `Addr`. Consulte [Conectando-se a vários nós](#connecting-to-multiple-nodes). | -| `BlockBufferSize` | `uint8` | `2` | Número de blocos a decodificar em paralelo. Valores mais altos aumentam a taxa de transferência, com maior uso de memória. Pode ser substituído por consulta via context. | -| `Settings` | `Settings` | — | map de configurações do ClickHouse aplicadas a cada consulta. Consultas individuais podem sobrescrevê-las por meio de [context](/pt-BR/integrations/language-clients/go/clickhouse-api#using-context). | -| `Compression` | `*Compression` | `nil` | Compressão no nível de bloco. Consulte [Compressão](#compression). | -| `ReadTimeout` | `time.Duration` | — | Tempo máximo de espera por uma leitura do servidor em uma única chamada. | -| `FreeBufOnConnRelease` | `bool` | `false` | Se true, libera o buffer de memória da conexão de volta para o pool a cada consulta. Reduz o uso de memória com um pequeno custo de CPU. | -| `Logger` | `*slog.Logger` | `nil` | Logger estruturado (Go `log/slog`). Consulte [Logging](#logging). | -| `Debug` | `bool` | `false` | **Obsoleto.** Use `Logger`. Habilita a saída legada de depuração em stdout. | -| `Debugf` | `func(string, ...any)` | — | **Obsoleto.** Use `Logger`. Função personalizada de log de depuração. Requer `Debug: true`. | -| `GetJWT` | `GetJWTFunc` | — | Callback que retorna um token JWT para autenticação no ClickHouse Cloud (somente HTTPS). | -| `HttpHeaders` | `map[string]string` | — | Cabeçalhos HTTP adicionais enviados em cada requisição (somente transporte HTTP). | -| `HttpUrlPath` | `string` | — | Caminho de URL adicional anexado às requisições HTTP (somente transporte HTTP). | -| `HttpMaxConnsPerHost` | `int` | — | Sobrescreve `MaxConnsPerHost` no `http.Transport` subjacente (somente transporte HTTP). | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Fábrica personalizada de transporte HTTP. O transporte padrão é passado para permitir sobrescritas seletivas (somente transporte HTTP). | -| `HTTPProxyURL` | `*url.URL` | — | URL de proxy HTTP para todas as requisições (somente transporte HTTP). | +| Parâmetro | Tipo | Padrão | Descrição | +| ---------------------- | -------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Protocol` | `Protocol` | `Native` | Protocolo de transporte: `Native` (TCP) ou `HTTP`. Consulte [TCP vs HTTP](#tcp-vs-http). | +| `Addr` | `[]string` | — | Lista de endereços `host:port`. Para vários nós, consulte [Conectando-se a vários nós](#connecting-to-multiple-nodes). | +| `Auth` | `Auth` | — | Credenciais de autenticação (`Database`, `Username`, `Password`). Consulte [Autenticação](#authentication). | +| `TLS` | `*tls.Config` | `nil` | Configuração de TLS. Um valor diferente de nil habilita TLS. Consulte [TLS](#using-tls). | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Função de dial personalizada para controlar como as conexões TCP são estabelecidas. | +| `DialTimeout` | `time.Duration` | `30s` | Tempo máximo de espera ao abrir uma nova conexão. Aumente para `1m`–`2m` ao se conectar a um ClickHouse Cloud service que possa estar ocioso — consulte [Timeouts](/pt-BR/integrations/language-clients/go/config-reference#timeouts). | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Número máximo de conexões abertas a qualquer momento. | +| `MaxIdleConns` | `int` | `5` | Número de conexões ociosas mantidas no pool. | +| `ConnMaxLifetime` | `time.Duration` | `1h` | Tempo máximo de vida de uma conexão no pool. Consulte [Pool de conexões](#connection-pooling). | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Estratégia para escolher um nó de `Addr`. Consulte [Conectando-se a vários nós](#connecting-to-multiple-nodes). | +| `BlockBufferSize` | `uint8` | `2` | Número de blocos a decodificar em paralelo. Valores mais altos aumentam a taxa de transferência, com maior uso de memória. Pode ser substituído por consulta via context. | +| `Settings` | `Settings` | — | map de configurações do ClickHouse aplicadas a cada consulta. Consultas individuais podem sobrescrevê-las por meio de [context](/pt-BR/integrations/language-clients/go/clickhouse-api#using-context). | +| `Compression` | `*Compression` | `nil` | Compressão no nível de bloco. Consulte [Compressão](#compression). | +| `ReadTimeout` | `time.Duration` | — | Tempo máximo de espera por uma leitura do servidor em uma única chamada. | +| `FreeBufOnConnRelease` | `bool` | `false` | Se true, libera o buffer de memória da conexão de volta para o pool a cada consulta. Reduz o uso de memória com um pequeno custo de CPU. | +| `Logger` | `*slog.Logger` | `nil` | Logger estruturado (Go `log/slog`). Consulte [Logging](#logging). | +| `Debug` | `bool` | `false` | **Obsoleto.** Use `Logger`. Habilita a saída legada de depuração em stdout. | +| `Debugf` | `func(string, ...any)` | — | **Obsoleto.** Use `Logger`. Função personalizada de log de depuração. Requer `Debug: true`. | +| `GetJWT` | `GetJWTFunc` | — | Callback que retorna um token JWT para autenticação no ClickHouse Cloud (somente HTTPS). | +| `HttpHeaders` | `map[string]string` | — | Cabeçalhos HTTP adicionais enviados em cada requisição (somente transporte HTTP). | +| `HttpUrlPath` | `string` | — | Caminho de URL adicional anexado às requisições HTTP (somente transporte HTTP). | +| `HttpMaxConnsPerHost` | `int` | — | Sobrescreve `MaxConnsPerHost` no `http.Transport` subjacente (somente transporte HTTP). | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Fábrica personalizada de transporte HTTP. O transporte padrão é passado para permitir sobrescritas seletivas (somente transporte HTTP). | +| `HTTPProxyURL` | `*url.URL` | — | URL de proxy HTTP para todas as requisições (somente transporte HTTP). | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/pt-BR/products/cloud/guides/index.mdx b/pt-BR/products/cloud/guides/index.mdx index a2c06e2bb..83ab95dba 100644 --- a/pt-BR/products/cloud/guides/index.mdx +++ b/pt-BR/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['guias do Cloud', 'documentação', 'guias práticos', 'funcionalidad | [Gerenciar minha conta](/pt-BR/products/cloud/guides/security/cloud-access-management/manage-my-account) | Esta página descreve como você pode aceitar convites, gerenciar configurações de MFA e redefinir senhas | | [Gerenciar atribuições de função do SQL Console](/pt-BR/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | Guia que mostra como gerenciar atribuições de função do SQL Console | | [Gerenciando limites de serviço e quotas da AWS](/pt-BR/products/bring-your-own-cloud/reference/aws-service-limits) | Quotas de serviço da AWS para verificar antes do onboarding do BYOC, como solicitar aumentos e o que monitorar à medida que os serviços escalam | -| [Migrando do CMEK v1 para o v2](/pt-BR/products/cloud/guides/security/cmek-migration) | Instruções de migração para passar do CMEK legado para a versão 2 | | [Multilocação](/pt-BR/products/cloud/guides/best-practices/multitenancy) | Melhores práticas para implementar multilocação | | [Otimizando conversas do agente ClickHouse Assistant com uma camada semântica](/pt-BR/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | Guia para usar AGENTS.md para fornecer lógica de negócios personalizada e instruções específicas de dados ao agente de chat do ClickHouse Assistant | | [Visão geral](/pt-BR/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | Implante o ClickHouse na sua própria infraestrutura de nuvem | diff --git a/pt-BR/products/cloud/guides/security/cmek-migration.mdx b/pt-BR/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index f777ea943..000000000 --- a/pt-BR/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: 'Migração de CMEK legado' -slug: /cloud/security/cmek-migration -title: 'Migração do CMEK v1 para o v2' -description: 'Instruções de migração para passar do CMEK legado para a versão 2' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', 'encryption', 'CMEK'] ---- - -Estamos aprimorando a segurança dos serviços com chaves de criptografia gerenciadas pelo cliente (CMEK). Agora, todos os serviços são configurados com uma AWS Role exclusiva por serviço para autorizar o uso de chaves do cliente na criptografia e descriptografia dos serviços. Essa nova função é exibida apenas na tela de configuração do serviço. - -OpenAPI e Terraform são compatíveis com esse novo processo. Para mais informações, consulte nossa documentação ([Criptografia aprimorada](/pt-BR/products/cloud/guides/security/cmek), [API da Cloud](/pt-BR/products/cloud/features/admin-features/api/api-overview), [Provider oficial do Terraform](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)). - - - Clientes que utilizam CMEK v1 devem migrar os serviços até, no máximo, 1º de junho de 2026. Após essa data, as chaves gerenciadas pelo cliente serão rotacionadas por padrão para chaves gerenciadas pela ClickHouse. Os clientes poderão voltar a usar chaves gerenciadas pelo cliente após a migração padrão. - - -
- ## Migração manual -
- -Conclua as etapas a seguir para migrar para o novo processo: - -1. Faça login em https://console.clickhouse.cloud -2. Clique no serviço criptografado -3. Clique em Service Settings, à esquerda -4. Role até o fim da tela e expanda View service details -5. Copie o ID da função de criptografia (IAM) -6. Acesse sua chave do KMS na AWS e atualize a Key Policy para adicionar o seguinte: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. No ClickHouse Cloud, abra um chamado de suporte para nos informar que podemos habilitar o novo método. Essa alteração exige a reinicialização do serviço; informe-nos se há algum dia/horário mais adequado para reiniciá-lo. -8. Depois que reiniciarmos o serviço, acesse sua chave do KMS na AWS e remova o seguinte da Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. A atualização foi concluída! - -
- ## Migração do Terraform -
- -1. Atualize para a [versão 3.5.0 ou superior do Terraform](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) -2. Aplique o Terraform sem alterações. Um novo campo para transparent_data_encryption aparecerá no state do Terraform. Anote o role_id. -3. Acesse sua chave KMS na AWS e atualize a Key Policy para adicionar o seguinte: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. No ClickHouse Cloud, abra um chamado de suporte com o nome do serviço para nos informar que podemos habilitar o novo método. Essa alteração exige a reinicialização do serviço; informe-nos se há algum dia/horário mais adequado para reiniciá-lo. -5. Depois que reiniciarmos o serviço, você poderá atualizar a configuração transparent_data_encryption.enabled para ‘True’, remover a configuração tier no Terraform e aplicar. Isso não resultará em nenhuma alteração. -6. Acesse sua chave KMS na AWS e remova o seguinte da Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. A atualização foi concluída! \ No newline at end of file diff --git a/pt-BR/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/pt-BR/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index 869337b68..6cb8c861b 100644 --- a/pt-BR/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/pt-BR/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ Para restringir o acesso aos seus serviços do ClickHouse Cloud exclusivamente p * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 diff --git a/pt-BR/products/cloud/navigation.json b/pt-BR/products/cloud/navigation.json index 38d9f0918..31d3b9327 100644 --- a/pt-BR/products/cloud/navigation.json +++ b/pt-BR/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "pt-BR/products/cloud/guides/security/data-masking", - "pt-BR/products/cloud/guides/security/cmek", - "pt-BR/products/cloud/guides/security/cmek-migration" + "pt-BR/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "pt-BR/_specs/cloud-openapi.json" } ] }, diff --git a/pt-BR/products/kubernetes-operator/guides/configuration.mdx b/pt-BR/products/kubernetes-operator/guides/configuration.mdx index bbdb989dc..4e76764a1 100644 --- a/pt-BR/products/kubernetes-operator/guides/configuration.mdx +++ b/pt-BR/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: Configure CPU e memória para os contêineres do ClickHouse: ```yaml -# valores padrão +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -321,6 +321,10 @@ spec: ## Configuração de TLS/SSL
+Para ver um exemplo de ponta a ponta — emitindo certificados com cert-manager, conectando +clientes por portas seguras e criptografando o tráfego do Keeper — consulte o +guia [Protegendo com TLS](/pt-BR/products/kubernetes-operator/guides/tls). +
### Configure endpoints seguros
@@ -371,6 +375,323 @@ spec: key: ``` +
+ ## Secret externo +
+ +Por padrão, o operador cria e controla um Secret que contém as credenciais internas do cluster (senha entre servidores, senha de gerenciamento, identidade do Keeper, Secret do cluster, chave de named-collections). O Secret recebe o nome do cluster e fica no espaço de nomes do cluster. + +Se você quiser gerenciar essas credenciais por conta própria — por exemplo, obtendo-as do HashiCorp Vault, AWS Secrets Manager ou [External Secrets Operator](https://external-secrets.io/) — aponte o operador para um Secret pré-existente usando `spec.externalSecret`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + O Secret referenciado deve estar no **mesmo espaço de nomes** que o ClickHouseCluster. O operador nunca exclui um Secret que não criou. + + +
+ ### Chaves obrigatórias +
+ +O Secret deve conter as seguintes chaves: + +| Chave | Formato | Quando é obrigatória | +| ----------------------- | ---------------------------------------------------------------------------- | -------------------------------- | +| `interserver-password` | senha em texto puro | Sempre | +| `management-password` | senha em texto puro | Sempre | +| `keeper-identity` | `clickhouse:` | Sempre | +| `cluster-secret` | senha em texto puro | Sempre | +| `named-collections-key` | chave AES de 16 bytes codificada em hexadecimal (32 caracteres hexadecimais) | Somente no ClickHouse `>= 25.12` | + +Um Secret completo fica assim: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### Política: Observe vs Manage +
+ +`spec.externalSecret.policy` controla como o operador lida com chaves obrigatórias ausentes: + +| Política | Comportamento quando faltam chaves | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Observe` (padrão) | A reconciliação fica **bloqueada** até que todas as chaves obrigatórias estejam presentes. O operador informa cada chave ausente — e a respectiva dica de formato — por meio da condição `ExternalSecretValid` (com o motivo `ExternalSecretInvalid`) e de um evento `Warning`. | +| `Manage` | O operador **gera** quaisquer chaves obrigatórias ausentes e as grava de volta no mesmo Secret. Útil para bootstrap: crie um Secret vazio, deixe o operador preenchê-lo e depois, se quiser, restrinja o acesso. Ainda assim, o operador nunca exclui o Secret. | + + + Mesmo com `policy: Manage`, o Secret já deve existir no espaço de nomes — o operador nunca cria o próprio Secret; ele apenas grava chaves geradas em um Secret existente. Se o Secret referenciado estiver ausente, a reconciliação será bloqueada com o motivo `ExternalSecretNotFound`, independentemente da política. + + +Escolha `Observe` quando um sistema externo (Vault, ESO, sealed-secrets, GitOps) for a fonte de verdade e você quiser que o operador falhe claramente em caso de configuração incorreta. Escolha `Manage` quando quiser um bootstrap autossuficiente, mas ainda quiser manter a propriedade do próprio objeto Secret (por exemplo, para fazer backup dele). + +
+ ### Condição de status e solução de problemas +
+ +O operador expõe a condição `ExternalSecretValid` em `ClickHouseCluster.status.conditions`. Verifique-a quando a reconciliação parecer travada: + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +Possíveis motivos: + +| `reason` | Significado | Correção | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | +| `ExternalSecretNotFound` | O Secret referenciado não existe no espaço de nomes. | Crie o Secret ou corrija `spec.externalSecret.name`. | +| `ExternalSecretInvalid` | O Secret existe, mas não contém as chaves obrigatórias (apenas com `Observe`). A mensagem lista cada chave ausente junto com o formato esperado. | Adicione as chaves ausentes ou mude para `policy: Manage`. | +| `ExternalSecretValid` | Todas as chaves obrigatórias estão presentes, e o operador está usando o Secret. | — | + +O operador coloca a reconciliação de volta na fila enquanto o Secret é inválido, então, assim que você adicionar as chaves ausentes, a próxima reconciliação as detectará automaticamente — não é necessário reiniciar os pods. + + + O conjunto de chaves obrigatórias depende da versão do ClickHouse em execução. `named-collections-key` só é validada quando a sonda de versão do operador detecta o ClickHouse `25.12` ou mais recente. Em versões anteriores, a chave pode não estar presente no Secret. + + +
+ ## Portas adicionais +
+ +O operador expõe um conjunto fixo de portas em cada pod do Kubernetes do ClickHouse e em seu Service headless: `8123` HTTP, `9000` native, `9009` interserver, `9001` management, `9363` métricas do Prometheus e as variantes TLS `8443`/`9440` quando o TLS estiver habilitado. Para fazer o ClickHouse aceitar conexões em protocolos adicionais — MySQL, PostgreSQL, gRPC ou qualquer porta personalizada — declare-as em `spec.additionalPorts`: + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +O operador adiciona essas portas às `containerPorts` do pod do Kubernetes e ao Service headless. O exemplo completo está em [`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml). + + + `additionalPorts` apenas abre as portas no lado do Kubernetes. Isso **não** configura o servidor ClickHouse para escutar nessas portas. Você também precisa habilitar o protocolo correspondente em `spec.settings.extraConfig.protocols`. Sem isso, a porta fica aberta no Service, mas nada dentro do pod do Kubernetes está respondendo. + + +
+ ### Exemplo completo: MySQL wire protocol +
+ +Para expor o ClickHouse pelo MySQL wire protocol na porta `9004`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +Depois de aplicar, verifique de dentro do cluster: + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### Restrições de campo +
+ +| Campo | Regra | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Deve corresponder ao padrão DNS_LABEL `^[a-z]([-a-z0-9]*[a-z0-9])?$`, com no máximo 63 caracteres. A unicidade é imposta pela CRD usando esse campo como chave de list-map. | +| `port` | Inteiro em `[1, 65535]`. O webhook rejeita números de porta duplicados na lista. | + +
+ ### Portas e nomes reservados +
+ +O webhook de validação rejeita entradas de `additionalPorts` que entrariam em conflito com portas usadas pelo próprio operator. Todas as portas relacionadas a TLS são reservadas **incondicionalmente** para que habilitar `spec.settings.tls.enabled` mais tarde não possa invalidar um cluster que antes era válido. + +| Porta | Reservada para | +| ------ | ------------------- | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | TCP nativo | +| `9440` | TLS nativo | +| `9009` | interserver | +| `9001` | gerenciamento | +| `9363` | métricas Prometheus | + +Os nomes a seguir também são rejeitados — eles são os identificadores internos do operator para tipos de protocolo (não os aliases legíveis por pessoas): + +| Nome | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +Uma solicitação rejeitada gera um erro como: + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## Sonda de versão e canal de upgrade +
+ +O operador faz duas coisas independentes com as versões do cluster: + +1. **Sonda de versão** — um `Job` do Kubernetes que executa a imagem de contêiner uma vez para detectar a versão em execução do ClickHouse / Keeper. A versão detectada é registrada em `.status.version` e usada por outras etapas de reconciliação (por exemplo, a chave de named-collections do `Secret externo` só é exigida a partir do ClickHouse `25.12`). +2. **Canal de upgrade** — uma verificação periódica no feed público de lançamentos do ClickHouse (`https://clickhouse.com/data/version_date.tsv`). O operador informa se há uma versão mais recente disponível por meio da condição de status `VersionUpgraded`. Ele nunca faz upgrade do cluster por conta própria — o usuário controla a tag da imagem. + +
+ ### Escolhendo um canal de lançamento +
+ +`spec.upgradeChannel` seleciona com qual conjunto de lançamentos upstream o operador faz a comparação. O mesmo campo existe tanto em `ClickHouseCluster` quanto em `KeeperCluster`. + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +Valores permitidos (validados pelo CRD com o padrão `^(lts|stable|\d+\.\d+)?$`): + +| Valor | Comportamento | +| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *empty* (padrão) | O operador propõe apenas atualizações de **patch** dentro da linha major.minor em execução no momento. Um cluster em `25.8.3.1` será notificado sobre `25.8.4.x`, mas não sobre `25.9.x`. | +| `stable` | Acompanha o canal `stable` upstream — o lançamento mais recente que a ClickHouse Inc. sinaliza como estável na linha principal de lançamentos. Recebe upgrades de versão principal antes do canal `lts`. | +| `lts` | Acompanha o canal `lts` upstream — lançamentos com suporte de longo prazo. Recebe upgrades de versão principal com menos frequência, com janelas de suporte mais longas. | +| `25.8` (ou qualquer `.`) | Fixa o canal em uma linha major.minor específica. Upgrades de versão principal além dela não são propostos, mesmo que exista uma versão mais nova no upstream. | + +Para produção, em geral é preferível fixar o canal em um `.` explícito (por exemplo, `25.8`). Isso mantém o cluster na linha de lançamento principal pretendida e permite que o operador exiba um aviso `WrongReleaseChannel` se alguma réplica, por algum motivo, acabar em uma major diferente — o que é especialmente importante quando a imagem é referenciada por um digest (`@sha256:...`) em vez de por uma tag legível por humanos. O padrão vazio é adequado para clusters de desenvolvimento em que saltos de versão principal não são uma preocupação. + +
+ ### Condições de status +
+ +Duas condições mostram o resultado da sonda e da verificação de atualização: + +| Condição | Motivo | Significado | +| ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionInSync` | `VersionMatch` | Todas as réplicas informam a mesma versão da imagem | +| `VersionInSync` | `VersionMismatch` | As réplicas estão executando versões diferentes. O evento de aviso é suprimido durante uma atualização rolling planejada. Isso normalmente ocorre quando uma tag de imagem mutável foi fixada (por exemplo, `latest` ou uma versão sem o patch, como `26.3`) e o registry subjacente mudou entre os pulls, fazendo com que réplicas diferentes acabem usando patches diferentes da mesma tag. | +| `VersionInSync` | `VersionPending` | O Job da sonda de versão ainda não foi concluído | +| `VersionInSync` | `VersionProbeFailed` | O Job da sonda falhou; o operador não consegue determinar a versão em execução | +| `VersionUpgraded` | `UpToDate` | O cluster está na versão mais recente disponível no canal selecionado | +| `VersionUpgraded` | `MinorUpdateAvailable` | Há um patch mais recente disponível na mesma linha `major.minor` | +| `VersionUpgraded` | `MajorUpdateAvailable` | Há um `major.minor` mais recente disponível no canal escolhido | +| `VersionUpgraded` | `VersionOutdated` | A versão em execução está desatualizada e não receberá mais correções do canal selecionado — normalmente porque a linha principal foi removida do `lts` ou `stable` upstream | +| `VersionUpgraded` | `WrongReleaseChannel` | A imagem em execução não pertence ao `upgradeChannel` selecionado. Exemplo: um cluster executando `26.5` com `upgradeChannel: lts`, já que `26.5` não faz parte da linha `lts` upstream. | +| `VersionUpgraded` | `UpgradeCheckFailed` | O operador não conseguiu acessar o feed de lançamentos upstream | + +Inspecione-as com: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### Sobrescrevendo o Job da sonda de versão +
+ +A sonda é implementada como um `Job` padrão do Kubernetes. Se o seu cluster tiver políticas de admissão que exijam `Tolerations` específicas, seletores de nó, contextos de segurança ou se você quiser limitar por quanto tempo os Jobs de sonda concluídos permanecem, sobrescreva o template por meio de `spec.versionProbeTemplate`: + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +O nome do contêiner `version-probe` é o nome padrão usado pelo operador — a entrada em `containers:` corresponde a ele pelo nome, então o operador faz um merge profundo dos campos fornecidos pelo usuário sobre os valores padrão. + +
+ ### Controles gerais do operador +
+ +Duas flags no gerenciador do operador controlam globalmente o loop de verificação de upgrade: + +| Flag | Padrão | Efeito | +| --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | Com que frequência o operador busca novamente a lista de versões upstream | +| `--disable-version-update-checks` | `false` | Desabilita completamente a verificação de upgrade. A condição `VersionUpgraded` não é definida, e nenhum tráfego HTTP de saída para `clickhouse.com` é gerado | + +Defina `--disable-version-update-checks=true` em ambientes isolados da internet ou quando a saída para `clickhouse.com` não for permitida. +
## Configurações do ClickHouse
@@ -485,6 +806,49 @@ spec: Quando ativado, o operator sincroniza as tabelas Replicated e de integração para novas réplicas. +
+ ### Logging do servidor +
+ +Configure o log do servidor ClickHouse por meio de `spec.settings.logger`. Todos os campos são opcionais e têm um padrão seguro, então mesmo um cluster sem nenhuma alteração já registra em `trace` tanto no console do contêiner quanto em um arquivo em disco com rotação. + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| Campo | Padrão | Descrição | +| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `logToFile` | `true` | Quando `false`, o operador remove os destinos de arquivo e o servidor grava logs apenas no console do contêiner. | +| `jsonLogs` | `false` | Quando `true`, o operador adiciona `formatting.type: json` para que cada linha seja um objeto JSON. | +| `level` | `trace` | Nível de verbosidade do log. Um de `test`, `trace`, `debug`, `information`, `notice`, `warning`, `error`, `critical`, `fatal`. | +| `size` | `1000M` | Tamanho máximo de um único arquivo de log antes da rotação. | +| `count` | `50` | Número de arquivos de log rotacionados que o servidor mantém. | + +O operador sempre mantém o log no console ativado para que `kubectl logs` funcione, e também adiciona o log em arquivo quando `logToFile` é `true`. Um cluster com os valores padrão gera este bloco `logger`: + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +O mesmo bloco `spec.settings.logger` também se aplica a um `KeeperCluster`; nesse caso, o operador grava seus arquivos em `/var/log/clickhouse-keeper/`. + + + O logging no console permanece ativado independentemente de `logToFile`, então `kubectl logs` continua funcionando mesmo quando você desativa o logging em arquivo. Defina `jsonLogs: true` quando enviar logs para um sistema de armazenamento de logs estruturados que processa JSON. + +
## Configuração personalizada
diff --git a/pt-BR/products/kubernetes-operator/guides/introduction.mdx b/pt-BR/products/kubernetes-operator/guides/introduction.mdx index 199d3efff..999d0abd4 100644 --- a/pt-BR/products/kubernetes-operator/guides/introduction.mdx +++ b/pt-BR/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: Para remover completamente o armazenamento: ```bash -# Excluir cluster +# Delete cluster kubectl delete clickhousecluster my-cluster -# Aguardar o encerramento dos pods -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# Excluir PVCs -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/pt-BR/products/kubernetes-operator/guides/monitoring.mdx b/pt-BR/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..60002c0ac --- /dev/null +++ b/pt-BR/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,420 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: Monitoramento do ClickHouse Operator +keywords: ['kubernetes', 'prometheus', 'monitoramento', 'métricas'] +description: 'Como coletar, proteger e usar as métricas do operador e os endpoints de integridade.' +doc_type: 'guide' +--- + +O operador expõe métricas compatíveis com o Prometheus e sondas de integridade do Kubernetes para que você possa observar sua atividade de reconciliação, detectar controladores travados e gerar alertas em caso de falhas. + +Este guia aborda o que o operador expõe, como coletar essas métricas e quais consultas são úteis no dia a dia. + + + Este guia trata do **próprio processo do operador** (o controller manager). Para métricas do ClickHouse server (consultas, partes, defasagem de replicação), use o [Prometheus endpoint no ClickHouse](/pt-BR/reference/settings/server-settings/settings#prometheus) para coletá-las separadamente. + + +
+ ## Endpoints +
+ +O processo do operador expõe dois endpoints HTTP dentro do pod do Kubernetes do gerenciador: + +| Endpoint | Porta padrão | Caminho | Finalidade | +| -------------------- | ---------------------------------------------------- | --------------------- | ---------------------------------- | +| Métricas | `8080` (Helm) / `0` desabilitado (padrão do binário) | `/metrics` | Formato de exposição do Prometheus | +| Sonda de integridade | `8081` | `/healthz`, `/readyz` | liveness e readiness do Kubernetes | + +O endpoint de métricas fica **desativado por padrão** ao executar o binário do operador diretamente (`--metrics-bind-address=0`). O Chart do Helm o ativa com `metrics.enable: true` e `metrics.port: 8080`. + +O endpoint da sonda de integridade está sempre ativado; o modelo de Implantação vincula `/healthz` e `/readyz` às sondas de liveness e readiness do pod do Kubernetes na porta `8081`. + +
+ ## Flags do binário do operator +
+ +As flags relevantes do `manager` (definidas em [`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go)): + +| Flag | Default | Description | +| ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--metrics-bind-address` | `0` (desabilitado) | Endereço de bind do endpoint de métricas. Defina como `:8443` para HTTPS ou `:8080` para HTTP. Deixe como `0` para desabilitar o servidor de métricas. | +| `--metrics-secure` | `true` | Expõe métricas via HTTPS com authn/authz. Defina como `false` para HTTP sem criptografia. | +| `--metrics-cert-path` | vazio | Diretório que contém os arquivos de certificado TLS (`tls.crt`, `tls.key`) do servidor de métricas. | +| `--metrics-cert-name` | `tls.crt` | Nome do arquivo de certificado em `--metrics-cert-path`. | +| `--metrics-cert-key` | `tls.key` | Nome do arquivo de chave em `--metrics-cert-path`. | +| `--enable-http2` | `false` | Habilita HTTP/2 para os servidores de métricas **e webhook**. Fica desabilitado por padrão para mitigar CVE-2023-44487 / CVE-2023-39325. | +| `--leader-elect` | `false` (binário) / `true` (Chart do Helm) | Habilita a eleição de líder para que apenas uma réplica reconcilie por vez. O Chart do Helm define essa flag em `manager.args` por padrão. | +| `--health-probe-bind-address` | `:8081` | Endereço de bind de `/healthz` e `/readyz`. | + + + A convenção `8443` (HTTPS) / `8080` (HTTP) no texto de ajuda da flag é apenas uma indicação. O Chart do Helm expõe HTTPS em `8080` porque define tanto `metrics.port: 8080` quanto `metrics.secure: true`. Não há detecção de modo com base na porta — `--metrics-secure` é o que seleciona HTTPS ou HTTP. + + +
+ ## Habilite métricas via Helm +
+ +O chart já cria um `Service` para a porta de métricas e, opcionalmente, um `ServiceMonitor` para o prometheus-operator. + +O endpoint de métricas em si já vem ativado por padrão (`metrics.enable: true`, porta `8080`, disponibilizado via HTTPS com `metrics.secure: true`). A única configuração que você normalmente precisa alterar é `prometheus.enable`, para que o chart crie um `ServiceMonitor` para você: + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +Se você não usar cert-manager, defina também `certManager.enable: false`, e o ServiceMonitor fará o scrape com `insecureSkipVerify: true`, baseando-se apenas em autenticação por bearer token. + +O conjunto completo de valores padrão relacionados a métricas é: + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +Aplicar: + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +Após a instalação, o chart cria: + +* `Service/-metrics-service` — expõe a porta `8080` (HTTPS quando `metrics.secure: true`). +* `ServiceMonitor/-controller-manager-metrics-monitor` — quando `prometheus.enable: true`. +* `Função de cluster/-metrics-reader` — URL sem recurso `/metrics` com o verbo `get`. + +
+ ## Protegendo o endpoint de métricas +
+ +Quando `metrics.secure: true`, o servidor de métricas impõe TLS **e** autenticação/autorização do Kubernetes em cada coleta. Os scrapers devem: + +1. Apresentar um Bearer token válido do Kubernetes. +2. Pertencer a uma ServiceAccount vinculada a uma Função de cluster que conceda `get` à URL não associada a recurso `/metrics`. + +O chart já inclui essa Função de cluster: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +Vincule-o à ServiceAccount usada pelo seu coletor (normalmente, o Prometheus): + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + Se você vir `401 Unauthorized` ou `403 Forbidden` no endpoint de métricas, o scraper está usando HTTPS, mas não tem um Bearer token do Kubernetes, não está autorizado a usá-lo, ou a ServiceAccount dele não tem o binding acima. Desabilitar a segurança definindo `metrics.secure: false` **não é recomendado** em clusters compartilhados, porque qualquer pessoa com acesso de rede ao pod do Kubernetes poderia coletar métricas desse endpoint. + + +
+ ## Referência do ServiceMonitor +
+ +O chart gera um ServiceMonitor com este formato quando `prometheus.enable: true`: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +Se a sua instância do Prometheus não estiver executando o cert-manager, defina `tlsConfig.insecureSkipVerify: true` e use apenas a autenticação com bearer token — o chart já faz isso quando `certManager.enable: false`. + +
+ ## Exemplo independente do Prometheus +
+ +Se você não usa o kube-prometheus-stack, o repositório fornece um exemplo independente em [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml). Ele cria uma ServiceAccount, o RBAC necessário e um CR `Prometheus` que seleciona o ServiceMonitor do operador. + +
+ ## Endpoints de sondas de integridade +
+ +| Caminho | Usado por | Retorna | +| ---------- | -------------------------------- | -------------------------------------------------------- | +| `/healthz` | sonda de liveness do Kubernetes | `200 OK` desde que o servidor da sonda esteja escutando. | +| `/readyz` | sonda de prontidão do Kubernetes | `200 OK` desde que o servidor da sonda esteja escutando. | + +Ambos os endpoints são registrados com a mesma verificação simples de ping (`healthz.Ping` de `sigs.k8s.io/controller-runtime`). Portanto, uma sonda com falha significa "o processo do manager não está servindo HTTP em `:8081`" — não "os controllers estão com falha". Para detectar problemas no nível do controller, use as [métricas de reconciliação](#reconciliation-activity). + +Por padrão, ambos os endpoints são servidos na porta `8081`. Eles são conectados à Implantação da seguinte forma: + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +Uma probe que falha repetidamente geralmente significa que o próprio servidor da probe nunca chegou a iniciar — por exemplo, o manager foi encerrado prematuramente durante a inicialização. Verifique os logs do manager em busca de `unable to start manager`, falhas de RBAC ou erros `cache did not sync`. + +
+ ## Catálogo de métricas +
+ +O operador não registra coletores personalizados do Prometheus. Tudo a seguir é exposto pelas bibliotecas subjacentes `controller-runtime` e `client-go`. As séries mais úteis, agrupadas por finalidade: + +
+ ### Atividade de reconciliação +
+ +| Métrica | Tipo | Labels | +| -------------------------------------------------- | --------- | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | counter | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | counter | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | histogram | `controller` | +| `controller_runtime_active_workers` | gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | gauge | `controller` | + +O label `controller` é derivado pelo `controller-runtime` a partir do tipo de recurso registrado com `For(...)`. Com o código atual em `internal/controller/clickhouse` e `internal/controller/keeper`, isso resulta em `clickhousecluster` e `keepercluster`, respectivamente. Se você tiver personalizado o operator, confirme com um scrape único de `/metrics`. + +
+ ### Fila de trabalho +
+ +| Métrica | Tipo | Labels | +| --------------------------------------------- | --------- | -------------------------------- | +| `workqueue_depth` | gauge | `name`, `controller`, `priority` | +| `workqueue_adds_total` | counter | `name`, `controller` | +| `workqueue_retries_total` | counter | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | gauge | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | gauge | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | histogram | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | histogram | `name`, `controller` | + +Os labels `name` e `controller` têm o mesmo valor (o nome do controller). + +
+ ### Tráfego do servidor de API +
+ +| Métrica | Tipo | Labels | +| ---------------------------- | ------- | ------------------------ | +| `rest_client_requests_total` | counter | `code`, `method`, `host` | + +
+ ### Eleição de líder +
+ +| Métrica | Tipo | Rótulos | +| ------------------------------- | ----- | ------------------------------------ | +| `leader_election_master_status` | gauge | `name` (= `d4ceba06.clickhouse.com`) | + +O Chart do Helm habilita `--leader-elect` por padrão, portanto essa métrica está presente nas instalações padrão com Helm. Ao executar o binário diretamente sem a opção, a métrica não é exibida. + +
+ ### Runtime +
+ +Coletores padrão do processo Go e do runtime — `go_goroutines`, `go_memstats_*`, `process_cpu_seconds_total`, `process_resident_memory_bytes`, etc. + +
+ ## Consultas úteis em PromQL +
+ +
+ ### Visão geral da saúde +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### Detecção de acúmulo +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### Limitação de taxa e sobrecarga na API +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### Status do líder (implantação de HA) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## Alertas sugeridos +
+ +Um ponto de partida para uma PrometheusRule (ajuste os limiares para o seu ambiente): + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +A última regra só faz sentido quando a eleição de líder está ativada. + +
+ ## Verificando a configuração +
+ +Uma verificação rápida de ponta a ponta, supondo que o chart tenha sido instalado em `clickhouse-operator-system`: + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +Se a coleta retornar métricas no formato de exposição do Prometheus, o endpoint e o RBAC estarão corretamente conectados. + + + +* [Instalação](/pt-BR/products/kubernetes-operator/install/helm) — values do Helm relevantes para o monitoramento. +* [Configuração](/pt-BR/products/kubernetes-operator/guides/configuration) — configuração de TLS compartilhada com o servidor de métricas. \ No newline at end of file diff --git a/pt-BR/products/kubernetes-operator/guides/scaling.mdx b/pt-BR/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..baeeae19f --- /dev/null +++ b/pt-BR/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,109 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: Escalonamento de clusters +keywords: ['kubernetes', 'escalonamento', 'réplicas', 'shards', 'keeper', 'quórum'] +description: 'Como escalar réplicas e shards do ClickHouse e membros do quórum do Keeper, e o que o operador faz automaticamente.' +doc_type: 'guide' +--- + +Você escala um cluster editando as contagens de réplicas e shards no recurso personalizado. O operador reconcilia o cluster em execução com a nova topologia: cria ou remove os StatefulSets de cada réplica, mantém o esquema sincronizado e mostra o progresso por meio das condições de status. + +Este guia explica como escalar réplicas e shards de `ClickHouseCluster`, como escalar com segurança o quórum de um `KeeperCluster` e quais condições observar enquanto uma operação de escalonamento está em andamento. + + + Um `ClickHouseCluster` sempre precisa de um Keeper, referenciado pelo campo obrigatório `spec.keeperClusterRef` — o operador coordena o cluster por meio dele, independentemente do tamanho. Para executar mais de uma réplica por shard, os dados também precisam estar em tabelas `ReplicatedMergeTree`, já que é a replicação que permite que uma segunda réplica atenda as mesmas linhas. + + +
+ ## Escalonamento de réplicas +
+ +`spec.replicas` define o número de réplicas em cada shard. Cada réplica roda em seu próprio StatefulSet chamado `-clickhouse--`, portanto, um cluster com `shards: 2` e `replicas: 3` executa seis StatefulSets. + +Aumente ou diminua a quantidade diretamente: + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +Ao aumentar a escala, o operador cria os novos StatefulSets por réplica, aguarda que cada pod do Kubernetes fique pronto e, em seguida, sincroniza o esquema com as novas réplicas (consulte [Sincronização automática de esquema](#automatic-schema-sync)). Ao reduzir a escala, ele remove os StatefulSets excedentes e limpa os registros obsoletos de réplica do banco de dados replicado deixados pelas réplicas removidas. + +
+ ## Escalonamento de shards +
+ +`spec.shards` define o número de shards. Cada novo shard adiciona um conjunto completo de StatefulSets por réplica, e o operador cria um [PodDisruptionBudget por shard](/pt-BR/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) para que uma interrupção em um shard não seja contabilizada em outro. + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +Cada shard contém uma porção distinta dos dados, e o operador não copia nem move linhas entre shards. Uma tabela `Distributed` ou um esquema de roteamento explícito decide em qual shard uma linha ficará, de modo que adicionar um shard dá às novas escritas um lugar para serem direcionadas sem mexer nas linhas já armazenadas nos shards existentes. + +
+ ## Sincronização automática de esquema +
+ +Quando `spec.settings.enableDatabaseSync` é `true` (o padrão), o operador mantém o esquema alinhado conforme a topologia muda: + +* **Ao aumentar a escala** — assim que pelo menos duas réplicas estiverem prontas, o operador replica as definições do banco de dados para as réplicas recém-criadas, para que uma nova réplica entre com os mesmos bancos de dados `Replicated` e de integração que o restante do cluster. +* **Ao reduzir a escala** — antes que uma réplica desapareça, o operador remove o registro da réplica de cada banco de dados `Replicated` com `SYSTEM DROP DATABASE REPLICA`, para que o cluster reduzido não fique aguardando uma réplica de banco de dados `Replicated` que não existe mais. + +Isso cobre bancos de dados `Replicated` e motores de banco de dados de integração. Isso não move dados de tabela — os dados de linha ficam em tabelas `ReplicatedMergeTree` e são replicados por meio do Keeper, independentemente dessa sincronização de esquema. Com apenas uma réplica pronta, não há nada para replicar, então o operador pula esse passo e registra em log que não há destino. + +Defina `enableDatabaseSync: false` para desativar esse comportamento, por exemplo, quando uma ferramenta externa é responsável pela propagação do esquema. O operador então informa o motivo `SchemaSyncDisabled` na condição `SchemaInSync`. + +
+ ## Condições para acompanhar +
+ +Acompanhe o progresso do recurso personalizado enquanto a operação de escalonamento estiver em execução: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| Condição | Motivo | Significado | +| -------------------- | ---------------------- | --------------------------------------------------------------------------------------------- | +| `ClusterSizeAligned` | `UpToDate` | O número de réplicas em execução corresponde à topologia solicitada | +| `ClusterSizeAligned` | `ScalingUp` | O operador está adicionando réplicas | +| `ClusterSizeAligned` | `ScalingDown` | O operador está removendo réplicas | +| `SchemaInSync` | `ReplicasInSync` | Os bancos de dados existem em todas as réplicas e os metadados desatualizados foram removidos | +| `SchemaInSync` | `DatabasesNotCreated` | O operador ainda não terminou de criar os bancos de dados nas novas réplicas | +| `SchemaInSync` | `ReplicasNotCleanedUp` | Os metadados desatualizados das réplicas após uma redução de escala ainda não foram removidos | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync` é `false` | +| `Ready` | `AllShardsReady` | Todo shard tem uma réplica pronta | +| `Ready` | `SomeShardsNotReady` | Pelo menos um shard não tem nenhuma réplica pronta | + +Uma operação de escala é concluída quando `ClusterSizeAligned` informa `UpToDate`, `SchemaInSync` informa `ReplicasInSync` e `Ready` informa `AllShardsReady`. + +
+ ## Escalonamento do Keeper +
+ +Um `KeeperCluster` opera com um quórum RAFT, portanto o operador altera seus membros **uma réplica por vez** e apenas enquanto o cluster estiver em um estado estável. Isso protege o quórum: um cluster `2F+1` tolera `F` membros indisponíveis, então um cluster de 3 nós continua funcionando com um membro ausente, e um cluster de 5 nós, com dois. + +```yaml +spec: + replicas: 5 # was 3 +``` + +Ao aumentar a escala, o operador adiciona ao quórum o menor ID de réplica livre; ao reduzir a escala, remove o maior ID. Cada etapa espera o quórum se estabilizar antes de a próxima começar. O [PodDisruptionBudget do Keeper](/pt-BR/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) usa por padrão `maxUnavailable: replicas/2` para preservar o quórum durante interrupções voluntárias. + +A condição `ScaleAllowed` informa se o quórum pode mudar sua composição neste momento: + +| Reason | Meaning | +| -------------------------- | ---------------------------------------------------------------------- | +| `ReadyToScale` | O quórum está estável e o operador pode adicionar ou remover um membro | +| `ReplicaHasPendingChanges` | Uma réplica ainda tem uma alteração de configuração pendente | +| `ReplicaNotReady` | Uma réplica não está pronta, então as mudanças na composição aguardam | +| `NoQuorum` | O cluster não tem quórum e não pode mudar sua composição com segurança | +| `WaitingFollowers` | O operador está aguardando os seguidores se atualizarem | + +Escale o Keeper um passo por vez e deixe `ScaleAllowed` voltar para `ReadyToScale` entre as mudanças. Pular vários membros de uma vez não contorna a reconciliação de um por vez — o operador ainda percorre o quórum com um membro por etapa. \ No newline at end of file diff --git a/pt-BR/products/kubernetes-operator/guides/tls.mdx b/pt-BR/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..a328cf4c9 --- /dev/null +++ b/pt-BR/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,338 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: Protegendo um cluster com TLS +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'security', 'certificates'] +description: 'Como proteger um cluster do ClickHouse com TLS usando cert-manager, incluindo conexões de cliente e criptografia do Keeper.' +doc_type: 'guide' +--- + +Este guia mostra como criptografar um cluster do ClickHouse de ponta a ponta: emitir um +certificado com [cert-manager](https://cert-manager.io/), habilitar TLS no +cluster, conectar um cliente pelas portas seguras e estender a criptografia ao +tráfego de coordenação do Keeper. + +Este guia é orientado a tarefas. Para a referência campo a campo de `spec.settings.tls`, consulte +[Configuration → TLS/SSL configuration](/pt-BR/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +e a [API Reference](/pt-BR/products/kubernetes-operator/reference/api-reference#clustertlsspec). + +
+ ## Pré-requisitos +
+ +* Um cluster ClickHouse em execução gerenciado pelo operator (consulte a [Introdução](/pt-BR/products/kubernetes-operator/guides/introduction)). +* [cert-manager](https://cert-manager.io/docs/installation/) instalado no cluster. +* Acesso ao `kubectl` no espaço de nomes do cluster. + +O operator não gera certificados por conta própria — ele usa um +`Secret` do Kubernetes fornecido por você. O cert-manager é a forma recomendada de gerar e +rotacionar esse Secret, mas qualquer ferramenta que grave um Secret no formato esperado funciona. + +
+ ## Como o operator espera os certificados +
+ +O TLS é habilitado ao apontar `spec.settings.tls.serverCertSecret` para um Secret que +contém três chaves: + +| Chave do Secret | Conteúdo | +| --------------- | ---------------------------------------------- | +| `tls.crt` | certificado do servidor codificado em PEM | +| `tls.key` | chave privada codificada em PEM | +| `ca.crt` | cadeia de certificados da CA codificada em PEM | + +Esse é exatamente o layout que o cert-manager grava para um recurso `Certificate`, portanto não é +necessária nenhuma conversão. O operator monta esses arquivos em cada pod do Kubernetes em +`/etc/clickhouse-server/tls/` e os conecta à configuração `openSSL` do ClickHouse. + + + `serverCertSecret` é **obrigatório** quando `tls.enabled: true`. O webhook de + validação rejeita um cluster que habilita TLS sem ele e rejeita `required: true` + a menos que `enabled: true`. + + +
+ ## Passo 1 — Faça o Bootstrap de uma CA com cert-manager +
+ +A configuração mais fácil de reproduzir é usar uma CA autoassinada que depois assina o +certificado do servidor. Isso fornece um `ca.crt` estável em que os clientes podem confiar. + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +Em produção, substitua o Bootstrap autoassinado pela sua autoridade emissora real (uma +CA corporativa, Vault, ACME etc.). Apenas o Passo 2 muda — a configuração do cluster é +idêntica. + +
+ ## Passo 2 — Emitir o certificado do servidor +
+ +Solicite um certificado de entidade final ao emissor da CA. Os `dnsNames` devem cobrir a forma como +os clientes endereçam os pods. O operator cria um único Service **headless** chamado +`-clickhouse-headless`, e cada pod do Kubernetes de réplica pode ser endereçado em +`-clickhouse---0.-clickhouse-headless..svc.cluster.local`. +Um curinga no domínio do Service headless cobre todas as réplicas: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + O operador **não** cria um Service para todo o cluster (com balanceamento de carga). Se você + quiser um único endpoint estável ao qual se conectar, crie seu próprio Service `ClusterIP` + selecionando os pods do Kubernetes do cluster e adicione o nome DNS dele a `dnsNames` acima. + + +O cert-manager cria o Secret `clickhouse-cert` com `tls.crt`, `tls.key` e +`ca.crt` e o atualiza antes de expirar. Verifique se ele existe: + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## Passo 3 — Habilite o TLS no cluster +
+ +Configure o cluster para usar o Secret: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### O que o operator faz +
+ +Quando `tls.enabled: true`, o operator: + +* **Abre as portas seguras** em cada pod do Kubernetes e no Service headless: `9440` + (TLS nativo) e `8443` (HTTPS). Elas são adicionadas além das portas existentes. +* **Monta o Secret** em `/etc/clickhouse-server/tls/` e gera o bloco `openSSL` do + ClickHouse com `verificationMode: relaxed`, + `disableProtocols: sslv2,sslv3` e `preferServerCiphers: true`. Esses são os + valores padrão — consulte [Personalizando as configurações de TLS](#custom-tls-settings) para alterá-los. + +Quando você também define `required: true`, o operator ainda: + +* **Remove as portas inseguras** `9000` (nativa) e `8123` (HTTP) — apenas as variantes + com TLS permanecem, então clientes em texto simples não conseguem mais se conectar. +* **Altera a sonda de liveness do pod do Kubernetes** para a porta nativa segura `9440`, para que a verificação + de integridade continue funcionando sem um listener em texto simples. + + + As portas TLS `8443` e `9440` são reservadas pelo webhook **incondicionalmente**, + mesmo quando o TLS está desativado, portanto ativar `tls.enabled` mais tarde nunca entra em conflito com uma + entrada de `spec.additionalPorts`. Veja + [Configuration → `additionalPorts`](/pt-BR/products/kubernetes-operator/guides/configuration#additional-ports). + + +
+ ## Etapa 4 — Conecte-se via TLS +
+ +Com `required: true`, os clientes devem usar as portas seguras e confiar na CA. Acesse +um pod do Kubernetes de réplica específico por meio do Service headless (ou do seu próprio `ClusterIP` +Service, se tiver criado um). + +**Protocolo nativo** (`clickhouse-client`, porta `9440`): + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (porta `8443`): + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +Extraia `ca.crt` diretamente do Secret para testes locais: + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## Criptografando o tráfego do Keeper +
+ +Ativar TLS no cluster do ClickHouse **não** criptografa a conexão com o Keeper. +Ative-o no `KeeperCluster` separadamente — emita um certificado para o +serviço do Keeper (Etapas 1–2 com os `dnsNames` do serviço do Keeper) e faça referência a ele: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +O Keeper expõe sua porta segura de cliente em `2281`. Quando o TLS está habilitado no Keeper, **o +cluster do ClickHouse se conecta a ele por TLS automaticamente** — sem necessidade de configuração extra no +lado do ClickHouseCluster. O ClickHouse verifica o certificado do Keeper usando seu próprio +bundle `ca.crt` quando o TLS está habilitado; caso contrário, usa o bundle de CAs padrão do sistema. + +
+ ## Bundle de CA personalizado +
+ +Se o ClickHouse precisar confiar em uma CA diferente da que está no certificado do servidor (por +exemplo, Keeper assinado por uma CA separada), forneça um `caBundle`: + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +O operator monta esse bundle de CA e faz a verificação `openSSL` do lado do cliente apontar para +ele, em vez de usar o próprio `ca.crt` do certificado. + +
+ ## Personalizando as configurações de TLS +
+ +O bloco `openSSL` que o operator gera é o padrão, não um limite. Ele é gravado +na configuração principal do servidor; tudo o que estiver em `spec.settings.extraConfig` é renderizado em +`config.d/99-extra-config.yaml`, que o ClickHouse mescla **por último** — portanto, substitui os +valores gerados. + +Para reforçar os padrões — por exemplo, exigir verificação estrita de peer e elevar o +protocolo mínimo para TLS 1.2 — defina as chaves de `openSSL.server` que você deseja alterar: + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +A mesclagem é por chave: somente os valores que você define são substituídos, e as chaves geradas que forem +omitidas (caminhos de certificado, configuração de CA) são preservadas. Consulte as +[`openSSL` configurações do servidor](/pt-BR/reference/settings/server-settings/settings#openssl) +para ver as opções disponíveis e +[Configuração → Configuração extra embutida](/pt-BR/products/kubernetes-operator/guides/configuration#embedded-extra-configuration) +para entender como `extraConfig` é mesclado. + +
+ ## Verifique e solucione problemas +
+ +**Confirme se as portas seguras estão em funcionamento no Service headless:** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**Confirme se o certificado está montado no pod do Kubernetes:** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| Sintoma | Causa provável | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Pods do Kubernetes não iniciam / erro de montagem de volume após habilitar TLS | O Secret referenciado está ausente ou não contém `tls.crt`/`tls.key`/`ca.crt`. O operator não valida o conteúdo do Secret — chaves ausentes aparecem como falha na montagem do volume do pod do Kubernetes, não como uma condição de status específica. Inspecione o pod do Kubernetes com `kubectl describe pod`. | +| Webhook rejeita o cluster | `required: true` definido sem `enabled: true`, ou `enabled: true` sem `serverCertSecret`. | +| Cliente `certificate verify failed` | O cliente não está confiando na CA. Forneça o `ca.crt` do Secret ou verifique se os `dnsNames` no certificado cobrem o host ao qual você está se conectando. | +| Um cliente em texto simples de repente não consegue se conectar | `required: true` removeu as portas `9000`/`8123`. Altere o cliente para `9440`/`8443` ou defina `required: false` para manter as portas inseguras abertas durante a migração. | + +
+ ## Veja também +
+ +* [Configuração → Configuração de TLS/SSL](/pt-BR/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — referência de campos +* [Configuração → `additionalPorts`](/pt-BR/products/kubernetes-operator/guides/configuration#additional-ports) — portas reservadas +* [Referência da API → ClusterTLSSpec](/pt-BR/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [configurações do servidor `openSSL`](/pt-BR/reference/settings/server-settings/settings#openssl) — opções de TLS que você pode sobrescrever via `extraConfig` \ No newline at end of file diff --git a/pt-BR/products/kubernetes-operator/install/helm.mdx b/pt-BR/products/kubernetes-operator/install/helm.mdx index 0904e940f..387520bb5 100644 --- a/pt-BR/products/kubernetes-operator/install/helm.mdx +++ b/pt-BR/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ Instalar uma versão específica do operador helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/pt-BR/products/kubernetes-operator/install/kubectl.mdx b/pt-BR/products/kubernetes-operator/install/kubectl.mdx index 970d8ef16..f86527d0c 100644 --- a/pt-BR/products/kubernetes-operator/install/kubectl.mdx +++ b/pt-BR/products/kubernetes-operator/install/kubectl.mdx @@ -105,7 +105,7 @@ Se quiser configurar as opções de implantação do operator, siga as etapas ab ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/pt-BR/products/kubernetes-operator/navigation.json b/pt-BR/products/kubernetes-operator/navigation.json index d41619115..a58806647 100644 --- a/pt-BR/products/kubernetes-operator/navigation.json +++ b/pt-BR/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "pt-BR/products/kubernetes-operator/guides/introduction", - "pt-BR/products/kubernetes-operator/guides/configuration" + "pt-BR/products/kubernetes-operator/guides/configuration", + "pt-BR/products/kubernetes-operator/guides/monitoring", + "pt-BR/products/kubernetes-operator/guides/scaling", + "pt-BR/products/kubernetes-operator/guides/tls" ] }, { diff --git a/pt-BR/products/kubernetes-operator/overview.mdx b/pt-BR/products/kubernetes-operator/overview.mdx index c6aaf9952..3ffcbb120 100644 --- a/pt-BR/products/kubernetes-operator/overview.mdx +++ b/pt-BR/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ Escolha o método de instalação de sua preferência: * **[Introdução](/pt-BR/products/kubernetes-operator/guides/introduction)** - Visão geral dos conceitos do ClickHouse Operator * **[Guia de Configuração](/pt-BR/products/kubernetes-operator/guides/configuration)** - Configure clusters do ClickHouse e do Keeper -* **[Monitoramento](/pt-BR/products/kubernetes-operator/guides/introduction)** - Monitore o clickhouse-operator usando métricas do Prometheus +* **[Monitoramento](/pt-BR/products/kubernetes-operator/guides/monitoring)** - Métricas do Prometheus e sondas de integridade para o operador +* **[Escalonamento](/pt-BR/products/kubernetes-operator/guides/scaling)** - Escalone réplicas, shards e o quórum do Keeper +* **[Protegendo com TLS](/pt-BR/products/kubernetes-operator/guides/tls)** - Criptografe clusters de ponta a ponta com cert-manager
## Referência diff --git a/pt-BR/products/kubernetes-operator/reference/api-reference.mdx b/pt-BR/products/kubernetes-operator/reference/api-reference.mdx index c391f656f..dd9320547 100644 --- a/pt-BR/products/kubernetes-operator/reference/api-reference.mdx +++ b/pt-BR/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'Referência da API' Este documento fornece uma referência detalhada da API dos recursos personalizados do ClickHouse Operator. +
+ ## AdditionalPort +
+ +AdditionalPort declara uma porta TCP adicional a ser exposta no pod do Kubernetes do ClickHouse e no Service headless gerenciado pelo operador. + +| Campo | Tipo | Descrição | Obrigatório | Padrão | +| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------ | +| `name` | string | O nome identifica a porta de forma exclusiva na lista. Usado tanto como nome da porta do contêiner quanto como nome da porta do Service.
Deve ser um DNS_LABEL. | true | | +| `port` | integer | `port` é o número da porta TCP a ser exposta. | true | | + +Aparece em: + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec define o estado desejado do ClickHouseCluster. -| Campo | Tipo | Descrição | Obrigatório | Padrão | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------- | -| `replicas` | integer | Número de réplicas no shard único. | false | 3 | -| `shards` | integer | Número de shards no cluster. | false | 1 | -| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Referência ao KeeperCluster usado para a coordenação do ClickHouse.
Quando o espaço de nomes é omitido, o espaço de nomes do ClickHouseCluster é usado. | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parâmetros passados para a especificação do pod do Kubernetes do ClickHouse. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parâmetros passados para a especificação do contêiner do ClickHouse. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificação do armazenamento persistente para os dados do ClickHouse. | false | | -| `labels` | object (keys:string, values:string) | Rótulos adicionais adicionados aos recursos. | false | | -| `annotations` | object (keys:string, values:string) | Anotações adicionais adicionadas aos recursos. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura o PDB criado para cada shard.
Quando não definido, o operador usa por padrão maxUnavailable=1 para
shards com uma única réplica e minAvailable=1 para shards com múltiplas réplicas. | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | Parâmetros de configuração do servidor ClickHouse. | false | | -| `clusterDomain` | string | ClusterDomain é o sufixo de domínio do cluster do Kubernetes usado para resolução de DNS. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel especifica o canal de lançamento para verificações de upgrade de versão principal.
Quando vazio, apenas atualizações menores serão propostas. Os valores permitidos são: stable, lts ou uma versão major.minor específica (por exemplo, 25.8). | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescritas de VersionProbeTemplate para o Job de detecção de versão. | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret é uma referência opcional a um Secret gerenciado externamente que contém segredos do cluster.
O Secret deve estar no mesmo espaço de nomes que o cluster. | false | | +| Campo | Tipo | Descrição | Obrigatório | Padrão | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | +| `replicas` | integer | Número de réplicas no shard único. | false | 3 | +| `shards` | integer | Número de shards no cluster. | false | 1 | +| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Referência ao KeeperCluster usado para a coordenação do ClickHouse.
Quando o espaço de nomes é omitido, o espaço de nomes do ClickHouseCluster é usado. | true | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Parâmetros passados para a especificação do pod do Kubernetes do ClickHouse. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Parâmetros passados para a especificação do contêiner do ClickHouse. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificação do armazenamento persistente para os dados do ClickHouse. | false | | +| `labels` | object (keys:string, values:string) | Rótulos adicionais adicionados aos recursos. | false | | +| `annotations` | object (keys:string, values:string) | Anotações adicionais adicionadas aos recursos. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura o PDB criado para cada shard.
Quando não definido, o operador usa por padrão maxUnavailable=1 para
shards com uma única réplica e minAvailable=1 para shards com múltiplas réplicas. | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | Parâmetros de configuração do servidor ClickHouse. | false | | +| `clusterDomain` | string | ClusterDomain é o sufixo de domínio do cluster do Kubernetes usado para resolução de DNS. | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel especifica o canal de lançamento para verificações de upgrade de versão principal.
Quando vazio, apenas atualizações menores serão propostas. Os valores permitidos são: stable, lts ou uma versão major.minor específica (por exemplo, 25.8). | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescritas de VersionProbeTemplate para o Job de detecção de versão. | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret é uma referência opcional a um Secret gerenciado externamente que contém segredos do cluster.
O Secret deve estar no mesmo espaço de nomes que o cluster. | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) array | AdditionalPorts declara portas TCP extras para expor no pod do Kubernetes do ClickHouse e no Service headless gerenciado pelo operador.
O operador apenas adiciona as portas aos recursos do Kubernetes; ele não configura o servidor ClickHouse para escutar nelas. | false | | Aparece em: @@ -180,9 +196,9 @@ ContainerTemplateSpec descreve as sobrescritas de configuração dos contêinere | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------ | | `image` | [ContainerImage](#containerimage) | Image é a imagem de contêiner a ser implantada. | true | | | `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | ImagePullPolicy da imagem, cujo padrão é IfNotPresent. | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources define os requisitos de recursos do contêiner do servidor.
Mesclados recursivamente com os padrões do operador via SMP. Limites e solicitações individuais sobrescrevem apenas as
chaves correspondentes; campos não definidos preservam os padrões do operador. | false | | -| `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts é a lista de montagens de volume do contêiner.
Concatenada com as montagens geradas pelo operador. Entradas que compartilham um `mountPath` com uma montagem do operador
são mescladas em um volume projetado. | false | | -| `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env é a lista de variáveis de ambiente a serem definidas no contêiner.
Mesclada com os padrões do operador por nome. | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources define os requisitos de recursos do contêiner do servidor.
Aplicados como um todo: os padrões do operador são usados somente quando todos os campos de recurso estão vazios. | false | | +| `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts é a lista de montagens de volume do contêiner.
Concatenada com as montagens geradas pelo operador. Entradas que compartilham um `mountPath` com uma montagem do operador
são mescladas em um volume projetado. | false | | +| `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env é a lista de variáveis de ambiente a serem definidas no contêiner.
Mesclada com os padrões do operador por nome. | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | SecurityContext define as opções de segurança com que o contêiner deve ser executado.
Um SecurityContext não nulo substitui integralmente os padrões do operador; o usuário passa a ser responsável por toda a
estrutura. Quando nulo, os padrões do operador são preservados.
Mais informações: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | | `livenessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | LivenessProbe sobrescreve a sonda de liveness padrão do operador. | false | | | `readinessProbe` | [Probe](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#probe-v1-core) | ReadinessProbe sobrescreve a sonda de prontidão padrão do operador. | false | | @@ -310,9 +326,9 @@ KeeperClusterSpec define o estado desejado do KeeperCluster. | `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Especificação do armazenamento persistente para os dados do ClickHouse Keeper. | false | | | `labels` | object (keys:string, values:string) | Rótulos adicionais adicionados aos recursos. | false | | | `annotations` | object (keys:string, values:string) | Anotações adicionais adicionadas aos recursos. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura o PDB criado para o cluster do Keeper.
Quando não definido, o operador usa por padrão maxUnavailable=replicas/2
(preservando o quórum em um cluster 2F+1). | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget configura o PDB criado para o cluster do Keeper.
Quando não definido, o operador usa por padrão maxUnavailable=replicas/2
(preservando o quórum em um cluster 2F+1); clusters com uma única réplica usam maxUnavailable=1. | false | | | `settings` | [KeeperSettings](#keepersettings) | Parâmetros de configuração do servidor ClickHouse Keeper. | false | | -| `clusterDomain` | string | ClusterDomain é o sufixo de domínio do cluster Kubernetes usado para a resolução de DNS. | false | cluster.local | +| `clusterDomain` | string | ClusterDomain é o sufixo de domínio do cluster do Kubernetes usado para a resolução de DNS. | false | cluster.local | | `upgradeChannel` | string | UpgradeChannel especifica o canal de lançamento para verificações de upgrade de versão principal.
Quando vazio, apenas atualizações secundárias serão propostas. Os valores permitidos são: stable, lts ou uma versão major.minor específica (por exemplo, 25.8). | false | | | `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Sobrescritas de VersionProbeTemplate para o Job de detecção de versão. | false | | @@ -333,7 +349,7 @@ KeeperClusterStatus define o estado observado de KeeperCluster. | `configurationRevision` | string | ConfigurationRevision indica a revisão de configuração de destino para cada réplica. | true | | | `statefulSetRevision` | string | StatefulSetRevision indica a revisão de StatefulSet de destino para cada réplica. | true | | | `currentRevision` | string | CurrentRevision indica a revisão de spec do KeeperCluster aplicada mais recentemente. | true | | -| `updateRevision` | string | CurrentRevision indica a revisão de spec do KeeperCluster solicitada mais recentemente. | true | | +| `updateRevision` | string | UpdateRevision indica a revisão de spec do KeeperCluster solicitada mais recentemente. | true | | | `observedGeneration` | integer | ObservedGeneration indica a geração mais recente observada pelo controlador. | true | | | `version` | string | Version indica a versão informada pela imagem do contêiner. | false | | | `versionProbeRevision` | string | VersionProbeRevision é o hash da imagem da última verificação de versão bem-sucedida.
Quando isso corresponde ao hash da imagem atual, a Version em cache é usada diretamente. | false | | diff --git a/pt-BR/resources/changelogs/cloud/release-status.mdx b/pt-BR/resources/changelogs/cloud/release-status.mdx index e581dcf5d..7eecc3453 100644 --- a/pt-BR/resources/changelogs/cloud/release-status.mdx +++ b/pt-BR/resources/changelogs/cloud/release-status.mdx @@ -34,7 +34,7 @@ O ClickHouse Cloud oferece diferentes canais de lançamento para atender às dif Janelas de upgrade programadas estão disponíveis em todos os canais de lançamento para serviços no tier Enterprise. Esse recurso permite configurar uma janela de horário em um determinado dia da semana para upgrades.
- ## Cronograma de lançamentos + ## Cronograma de lançamento
@@ -43,22 +43,35 @@ Janelas de upgrade programadas estão disponíveis em todos os canais de lançam As datas mostradas abaixo indicam quando o ClickHouse **inicia o rollout** em cada canal de lançamento, não quando o seu serviço específico será atualizado. * Os rollouts são automatizados e ocorrem gradualmente ao longo de várias semanas - * Serviços com janelas de upgrade agendadas são atualizados durante a janela agendada na semana seguinte ao fim do rollout do canal (a partir de segunda-feira às 00:00 UTC) - * A conclusão do rollout pode ser adiada devido a pausas no rollout (por exemplo, congelamentos em feriados) ou monitoramento de integridade + * Serviços com janelas de upgrade programadas são atualizados durante a janela agendada na semana seguinte ao fim do rollout do canal (a partir de segunda-feira às 00:00 UTC) + * A conclusão do rollout pode ser adiada devido a pausas no rollout (por exemplo, congelamentos em feriados) ou ao monitoramento de integridade Para testes antecipados antes dos upgrades em produção, use o canal Fast ou Regular para serviços que não sejam de produção e o canal Slow para serviços de produção. >\".", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Формат источника Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM для источника Kafka. Используйте с аутентификацией по роли IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUID обратных частных конечных точек, используемых для безопасного частного подключения к источнику Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Топики источника Kafka.", + "type": "string" + }, + "type": { + "description": "Тип источника Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "Метод аутентификации, используемый с потоком Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Формат потока Kinesis.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM для аутентификации. Обязательно, если используется IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Тип итератора, используемого при чтении из потока Kinesis. Если используется AT_TIMESTAMP, необходимо указать поле временной метки.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Регион AWS для потока Kinesis.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Имя потока Kinesis.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Unix-временная метка, с которой следует начать чтение из потока Kinesis. Обязательно, если iteratorType имеет значение AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Использовать enhanced fan-out для потока Kinesis.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "Столбцы целевой таблицы. Обязательное поле для всех типов пайпов, кроме Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "Целевая база данных.", + "type": "string" + }, + "managedTable": { + "description": "Управляется ли таблица через ClickPipes? Обязательное поле для всех типов пайпов, кроме Postgres.", + "type": "boolean" + }, + "roles": { + "description": "ClickPipe создаст пользователя ClickHouse с этими ролями. При необходимости добавьте здесь свои пользовательские роли.", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "Целевая таблица. Обязательное поле для всех типов пайпов, кроме Postgres.", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Тип аутентификации реестра схем.", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "CA‑сертификаты в кодировке PEM для проверки сертификата реестра схем.", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "URL схемы. Требуется HTTPS.", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "База данных экземпляра Postgres, к которой нужно подключиться.", + "type": "string" + }, + "host": { + "description": "Хост экземпляра Postgres, к которому нужно подключиться.", + "type": "string" + }, + "port": { + "description": "Порт экземпляра Postgres, к которому нужно подключиться.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Сопоставления таблиц для пайпа Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "Метод аутентификации. CONNECTION_STRING используется для Azure Blob Storage. IAM_ROLE и IAM_USER — для AWS S3/GCS/DigitalOcean. Если не указан, аутентификация не используется.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Имя контейнера для Azure Blob Storage. Обязательно, если type имеет значение azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Алгоритм сжатия, используемый для файлов.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Строка подключения для аутентификации Azure Blob Storage. Обязательно, если для authentication указано CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Разделитель, используемый в файлах.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Формат файлов.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM, используемая при аутентификации через роль IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Если установлено значение true, пайп будет непрерывно читать новые файлы из источника. Если установлено значение false, пайп прочитает файлы только один раз. Новые файлы должны загружаться в лексикографическом порядке.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Путь к файлу или файлам внутри контейнера Azure. Используется для источников Azure Blob Storage. Можно указать несколько файлов, используя bash-подобные подстановочные шаблоны. Подробнее см. в документации по использованию подстановочных шаблонов в пути: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL очереди SQS для событийной непрерывной ингестии. Если указан, файлы ингестируются на основе уведомлений о событиях S3, а не в лексикографическом порядке. Применяется только если isContinuous имеет значение true и аутентификация не public.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Тип источника ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Укажите путь к файлу или файлам, которые нужно загрузить. Можно указать несколько файлов, используя bash-подобные подстановочные шаблоны. Подробнее см. в документации по использованию подстановочных шаблонов в пути: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "Столбцы целевой таблицы. Это не обновит схему таблицы, а только конфигурацию ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Метод аутентификации источника Kafka. Поддерживаемые методы аутентификации: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "CA‑сертификаты в кодировке PEM для проверки сертификата брокера.", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Учётные данные для источника Kafka. Выберите один из вариантов, поддерживаемых методом аутентификации.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "Роль IAM для источника Kafka. Используйте с аутентификацией по роли IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "UUID обратных частных конечных точек, используемых для безопасного частного подключения к источнику Kafka.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Метод аутентификации, используемый с потоком Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "Роль IAM для аутентификации. Обязательно, если используется IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Метод аутентификации. CONNECTION_STRING используется для Azure Blob Storage. IAM_ROLE и IAM_USER используются для AWS S3/GCS/DigitalOcean. Если не указан, аутентификация не используется.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Имя контейнера для Azure Blob Storage. Обязательно, если type имеет значение azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Строка подключения для аутентификации Azure Blob Storage. Обязательна, если authentication имеет значение CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "Роль IAM, используемая при аутентификации по роли IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Путь к файлу или файлам внутри контейнера Azure. Используется для источников Azure Blob Storage. Можно указать несколько файлов, используя bash-подобные подстановочные шаблоны. Подробнее см. в документации по использованию подстановочных шаблонов в пути: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "Имя исходной схемы.", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "Имя исходной таблицы.", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "Движок таблицы для целевой таблицы.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "Имя целевой таблицы.", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "Количество строк, извлекаемых в каждом батче.", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Интервал в секундах для синхронизации данных из Postgres.", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "База данных экземпляра Postgres, к которой нужно подключиться.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "Хост экземпляра Postgres, к которому нужно подключиться.", + "nullable": true, + "type": "string" + }, + "port": { + "description": "Порт экземпляра Postgres, к которому нужно подключиться.", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "Сопоставления таблиц, которые нужно добавить в пайп Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "Сопоставления таблиц, которые нужно удалить из пайпа Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "Сопоставления полей ClickPipe. Это не обновит схему таблицы, а только конфигурацию ClickPipe.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Имя ClickPipe.", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "Проверять образцы данных, полученные из источника данных. Будут проверены соединение, доступность данных и их корректность. Если параметр не включен, будет проверено только соединение. Для пайпов Postgres это не имеет эффекта: для них всегда проверяются только соединение и определения таблиц. Эта возможность экспериментальная и в будущем может быть удалена.", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Метод аутентификации источника Kafka. Поддерживаемые методы аутентификации: kafka: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, msk: SCRAM-SHA-512, IAM_ROLE, IAM_USER, MUTUAL_TLS, confluent: PLAIN, MUTUAL_TLS, warpstream: PLAIN, azureeventhub: PLAIN, redpanda: SCRAM-SHA-256, SCRAM-SHA-512, MUTUAL_TLS, dokafka: SCRAM-SHA-256, MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Брокеры источника Kafka.", + "type": "string" + }, + "caCertificate": { + "description": "CA‑сертификаты в кодировке PEM для проверки сертификата брокера.", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Группа потребителей источника Kafka. Если не указана, будет использоваться \"clickpipes-<>\".", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Учётные данные для источника Kafka. Выберите один из вариантов, поддерживаемых методом аутентификации.", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Формат источника Kafka.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM для источника Kafka. Используйте с аутентификацией по роли IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "UUID обратных частных конечных точек, используемых для безопасного частного подключения к источнику Kafka.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Топики источника Kafka.", + "type": "string" + }, + "type": { + "description": "Тип источника Kafka.", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Метод аутентификации, используемый с потоком Kinesis.", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Формат потока Kinesis.", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM для аутентификации. Обязательно, если используется IAM_ROLE.", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "Тип итератора, используемого при чтении из потока Kinesis. Если используется AT_TIMESTAMP, необходимо указать поле временной метки.", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Регион AWS для потока Kinesis.", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Имя потока Kinesis.", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "Unix-временная метка, с которой следует начать чтение из потока Kinesis. Обязательно, если iteratorType имеет значение AT_TIMESTAMP.", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "Использовать enhanced fan-out для потока Kinesis.", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "Метод аутентификации. CONNECTION_STRING используется для Azure Blob Storage. IAM_ROLE и IAM_USER используются для AWS S3/GCS/DigitalOcean. Если не указан, аутентификация не используется.", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Имя контейнера для Azure Blob Storage. Обязательно, если type имеет значение azureblobstorage.", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "Алгоритм сжатия, используемый для файлов.", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "Строка подключения для аутентификации Azure Blob Storage. Обязательна, если authentication имеет значение CONNECTION_STRING.", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "Разделитель, используемый в файлах.", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Формат файлов.", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "Роль IAM, используемая при аутентификации по роли IAM. Подробнее см. в документации ClickPipes: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "Если установлено значение true, пайп будет непрерывно считывать новые файлы из источника. Если установлено значение false, пайп считает файлы только один раз. Новые файлы должны загружаться в лексикографическом порядке.", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Путь к файлу или файлам внутри контейнера Azure. Используется для источников Azure Blob Storage. Можно указать несколько файлов, используя bash-подобные подстановочные шаблоны. Подробнее см. в документации по использованию подстановочных шаблонов в пути: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "URL очереди SQS для событийной непрерывной ингестии. Если указан, файлы принимаются на основе уведомлений о событиях S3, а не в лексикографическом порядке. Применимо только если isContinuous имеет значение true и аутентификация не Public.", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Тип источника ObjectStorage.", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "Укажите путь к файлу или файлам, которые нужно принять. Можно указать несколько файлов, используя bash-подобные подстановочные шаблоны. Подробнее см. в документации по использованию подстановочных шаблонов в пути: https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "Сопоставления полей ClickPipe. Обратите внимание, что сопоставления должны включать все столбцы пункта назначения.", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "Имя ClickPipe.", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "Проверять образцы данных, полученные из источника данных. Будут проверены соединение, доступность данных и их корректность. Если параметр не включен, будет проверено только соединение. Для пайпов Postgres это не имеет эффекта: для них всегда проверяются только соединение и определения таблиц. Эта возможность экспериментальная и в будущем может быть удалена.", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "Разрешить столбец с типом Nullable в целевой таблице.", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "Включить failover для созданного слота репликации. Требуется, чтобы слот репликации НЕ был задан.", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "Количество таблиц, синхронизируемых параллельно во время первоначальной загрузки.", + "type": "number" + }, + "publicationName": { + "description": "Имя публикации, используемой для репликации.", + "type": "string" + }, + "pullBatchSize": { + "description": "Количество строк, извлекаемых в каждом батче.", + "type": "number" + }, + "replicationMode": { + "description": "Режим репликации для этого пайпа.", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "Имя слота репликации, используемого для репликации.", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "Количество строк в снимке для каждой партиции.", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "Количество таблиц, для которых снимок создаётся параллельно.", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "Интервал в секундах для синхронизации данных из Postgres.", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "Столбцы, которые нужно исключить из целевой таблицы.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "Упорядоченный список столбцов, используемых в качестве ключа сортировки целевой таблицы.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "Имя исходной схемы.", + "type": "string" + }, + "sourceTable": { + "description": "Имя исходной таблицы.", + "type": "string" + }, + "tableEngine": { + "description": "Движок таблицы для целевой таблицы.", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "Имя целевой таблицы.", + "type": "string" + }, + "useCustomSortingKey": { + "description": "Использовать ли пользовательский ключ сортировки для целевой таблицы.", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "База данных экземпляра Postgres, к которой нужно подключиться.", + "type": "string" + }, + "host": { + "description": "Хост экземпляра Postgres, к которому нужно подключиться.", + "type": "string" + }, + "port": { + "description": "Порт экземпляра Postgres, к которому нужно подключиться.", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Сопоставления таблиц для пайпа Postgres.", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "Желаемая степень параллелизма. Только для пайпов S3. Если задано значение 0, параллелизм автоматически масштабируется в зависимости от памяти кластера.", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU в миллиядрах для каждой реплики. Только для стриминговых пайпов.", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Память в ГБ для каждой реплики. Только для стриминговых пайпов.", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "Желаемое количество реплик. Только для масштабируемых пайпов.", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "Уровень параллелизма, до которого нужно масштабировать. Используется для масштабирования пайпов S3.", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "CPU в миллиядрах для каждой реплики. Используется для масштабирования стриминг-пайпов.", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Память в ГБ для каждой реплики. Используется для масштабирования стриминг-пайпов.", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "Количество реплик, до которого нужно масштабировать. Используется для масштабирования пайпов Kafka.", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Максимальное число потоков загрузки. Максимальное количество параллельных потоков загрузки", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Максимальное число потоков вставки. Максимальное количество параллельных потоков вставки", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Максимальное число потоков. Максимальное количество параллельных потоков для обработки файлов", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Минимальный размер блока вставки в байтах. Минимальный размер блока данных для вставки (в байтах)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Параллельный distributed insert select. Настройка параллельного distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "параллельная обработка представлений. Следует ли включить параллельную отправку в attached-представления вместо последовательной", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Параллелизм объектного хранилища. Количество потоков для параллельной обработки файлов", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Максимальное число файлов. Максимальное количество файлов для обработки в одном батче вставки", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Максимальный объём вставки в байтах. Количество байтов для обработки в одном батче вставки", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Интервал опроса объектного хранилища. Настраивает интервал обновления для проверки наличия новых данных в объектном хранилище при непрерывном приёме", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "использовать функцию cluster. Следует ли использовать функцию cluster в ClickHouse для распределённой обработки", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Максимальное время ожидания вставки для стриминга. Настраивает максимальный период ожидания перед вставкой данных в ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Максимальное число потоков загрузки. Максимальное количество параллельных потоков загрузки", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Максимальное число потоков вставки. Максимальное количество параллельных потоков вставки", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Максимальное число потоков. Максимальное количество параллельных потоков для обработки файлов", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Минимальный размер блока вставки в байтах. Минимальный размер блока данных для вставки (в байтах)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Параллельный distributed insert select. Настройка параллельного distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "Параллельная обработка представлений. Определяет, следует ли включить параллельную отправку в подключённые представления вместо последовательной", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Параллелизм объектного хранилища. Количество потоков для параллельной обработки файлов", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Максимальное число файлов. Максимальное количество файлов для обработки в одном батче вставки", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Максимальный объём вставки в байтах. Количество байтов для обработки в одном батче вставки", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Интервал опроса объектного хранилища. Настраивает интервал обновления для проверки наличия новых данных в объектном хранилище при непрерывном приёме", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "Использовать функцию cluster. Определяет, использовать ли функцию cluster в ClickHouse для распределённой обработки", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Максимальное время ожидания вставки для стриминга. Настраивает максимальный период ожидания перед вставкой данных в ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "Максимальное число потоков загрузки. Максимальное количество параллельных потоков загрузки", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "Максимальное число потоков вставки. Максимальное количество параллельных потоков вставки", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "Максимальное число потоков. Максимальное количество параллельных потоков для обработки файлов", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "Минимальный размер блока вставки в байтах. Минимальный размер блока данных для вставки (в байтах)", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "Параллельный distributed insert select. Настройка параллельного distributed insert select", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "Параллельная обработка представлений. Определяет, следует ли включить параллельную отправку в подключённые представления вместо последовательной", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "Параллелизм объектного хранилища. Количество потоков для параллельной обработки файлов", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "Максимальное число файлов. Максимальное количество файлов для обработки в одном батче вставки", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "Максимальный объём вставки в байтах. Количество байтов для обработки в одном батче вставки", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "Интервал опроса объектного хранилища. Настраивает интервал обновления для проверки наличия новых данных в объектном хранилилище при непрерывном приёме", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "Использовать функцию cluster. Определяет, использовать ли функцию cluster в ClickHouse для распределённой обработки", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "Максимальное время ожидания вставки для стриминга. Настраивает максимальный период ожидания перед вставкой данных в ClickHouse.", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "Команда для изменения состояния: 'start', 'stop', 'resync'.", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU в милликорах для DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Память в ГиБ для DB ClickPipes. Должна в 4 раза превышать количество ядер CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "CPU в миллиядрах для DB ClickPipes.", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "Память в GiB для DB ClickPipes. Должна в 4 раза превышать количество ядер CPU.", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Описание обратной частной конечной точки. Максимальная длина — 255 символов.", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "Тип аутентификации кластера MSK. Обязательно для типа MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN кластера MSK. Обязательно для типа MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Тип обратной частной конечной точки.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Service name сервиса конечной точки VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID конфигурации ресурса VPC. Обязательно для типа VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN общего ресурса VPC. Обязательно для типа VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "Идентификатор ключа доступа (ключ HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Путь к бакету", + "type": "string" + }, + "bucketProvider": { + "description": "Провайдер бакета", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "Уникальный идентификатор бакета резервной копии", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "ID ключа доступа (ключ HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Путь к бакету", + "type": "string" + }, + "bucketProvider": { + "description": "Провайдер бакета", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Секретный ключ доступа (секретный ключ HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "Идентификатор ключа доступа (ключ HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Путь к бакету", + "type": "string" + }, + "bucketProvider": { + "description": "Провайдер бакета", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "Секретный ключ доступа (секретный ключ HMAC)", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "Идентификатор ключа доступа (ключ HMAC)", + "type": "string" + }, + "bucketPath": { + "description": "Путь к бакету", + "type": "string" + }, + "bucketProvider": { + "description": "Провайдер бакета", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Cloud Provider, в котором находится частная конечная точка", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Описание частной конечной точки", + "type": "string" + }, + "id": { + "description": "Идентификатор частной конечной точки", + "type": "string" + }, + "region": { + "description": "Region, в котором находится частная конечная точка", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "Элементы для добавления. Выполняется после обработки части \"remove\".", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "Элементы для удаления. Выполняется до обработки части \"add\".", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "Разрешённые источники в виде списка доменов, разделённых запятыми", + "type": "string" + }, + "openApiKeys": { + "description": "Версия эндпоинта запроса сервиса", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "Роли", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "Временная метка создания приглашения. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "Email приглашенного пользователя. Только пользователь с этим email может присоединиться по приглашению. Email хранится в нижнем регистре.", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "Временная метка истечения срока действия приглашения. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Уникальный ID приглашения.", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "Роль участника в организации.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "Адрес электронной почты приглашенного пользователя. Присоединиться по приглашению может только пользователь с этим адресом электронной почты. Адрес электронной почты хранится в нижнем регистре.", + "format": "email", + "type": "string" + }, + "role": { + "description": "Роль участника в организации.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "Необязательное описание IPv4-адреса или IPv4 CIDR, с которого разрешён доступ", + "type": "string" + }, + "source": { + "description": "IP или CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "Элементы для добавления. Выполняется после обработки части \"remove\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "Элементы для удаления. Выполняется до обработки части \"add\".", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "Email участника, заданный в личном профиле пользователя.", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "Временная метка присоединения участника к организации. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "Имя участника, заданное в личном профиле пользователя.", + "type": "string" + }, + "role": { + "description": "Роль участника в организации.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "Уникальный ID пользователя. Если пользователь состоит в нескольких организациях, этот ID останется неизменным.", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "Роль участника в организации.", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "ID ключа доступа IAM.", + "type": "string" + }, + "secretKey": { + "description": "Секретный ключ IAM.", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "Конфигурация BYOC для организации", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "Временная метка создания организации. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Уникальный Organization ID.", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "Название организации.", + "type": "string" + }, + "privateEndpoints": { + "description": "Список частных конечных точек организации", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Уникальный идентификатор интерфейсной конечной точки, которую вы создали в своём VPC с ресурсом AWS(Service Name) или GCP(Target Service)", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Cloud Provider, в котором находится частная конечная точка", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Необязательное описание частной конечной точки", + "type": "string" + }, + "id": { + "description": "Идентификатор частной конечной точки", + "type": "string" + }, + "region": { + "description": "Region, в котором находится частная конечная точка", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "Имя организации.", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "Cloud Provider, в котором находится частная конечная точка", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "Описание частной конечной точки", + "type": "string" + }, + "id": { + "description": "Идентификатор частной конечной точки", + "type": "string" + }, + "region": { + "description": "Region, в котором находится частная конечная точка", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "Элементы для добавления. Выполняется после обработки части \"remove\". Чтобы изменить частные конечные точки, используйте вместо этого конечную точку `Update Service Basic Details`.", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "Элементы для удаления. Выполняется перед обработкой части \"add\".", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "Пароль.", + "type": "string" + }, + "username": { + "description": "Имя пользователя.", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "Уникальный идентификатор интерфейсной конечной точки, созданной в вашей VPC с использованием ресурса AWS (Service Name), GCP (Target Service) или AZURE (Private Link Service)", + "type": "string" + }, + "privateDnsHostname": { + "description": "Имя хоста Private DNS созданной вами VPC", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Описание обратной частной конечной точки. Максимальная длина — 255 символов.", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "Внутренние DNS-имена обратной частной конечной точки.", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "Endpoint ID обратной частной конечной точки.", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "ID обратной частной конечной точки.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "Тип аутентификации кластера MSK. Обязательно для типа MSK_MULTI_VPC.", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "ARN кластера MSK. Обязательно для типа MSK_MULTI_VPC.", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "Частные DNS-имена обратной частной конечной точки.", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "ID сервиса ClickHouse, с которым связана обратная частная конечная точка.", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Статус обратной частной конечной точки.", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "Тип обратной частной конечной точки.", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "Service name сервиса конечной точки VPC.", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "ID конфигурации ресурса VPC. Обязательно для типа VPC_RESOURCE.", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "ARN общего ресурса VPC. Обязательно для типа VPC_RESOURCE.", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "Описание частной конечной точки", + "type": "string" + }, + "id": { + "description": "Идентификатор частной конечной точки", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Список идентификаторов доступных частных конечных точек, которые можно подключить к сервису", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Это идентификатор, возвращаемый после настройки региона для Bring Your Own Cloud (BYOC). Если указан параметр byocId, также обязательны параметры minReplicaMemoryGb и maxReplicaGb со значениями из следующего набора размеров: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Версия ClickHouse сервиса.", + "type": "string" + }, + "complianceType": { + "description": "Тип нормативного соответствия для сервиса.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Временная метка создания сервиса. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Хранилище данных, содержащее этот сервис", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Необязательная роль для шифрования диска", + "type": "string" + }, + "encryptionKey": { + "description": "Необязательный предоставленный клиентом ключ шифрования диска", + "type": "string" + }, + "encryptionRoleId": { + "description": "Идентификатор роли IAM, используемой для шифрования. Доступно только если hasTransparentDataEncryption имеет значение true.", + "type": "string" + }, + "endpoints": { + "description": "Список всех конечных точек сервиса.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "Значение true, если для сервиса должно быть включено прозрачное шифрование данных (TDE). TDE доступно только для уровней организации ENTERPRISE и может быть включено только при создании сервиса.", + "type": "boolean" + }, + "iamRole": { + "description": "Роль IAM, используемая для доступа к объектам в S3", + "type": "string" + }, + "id": { + "description": "Уникальный идентификатор сервиса.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Если установлено значение true, сервис может масштабироваться до нуля при бездействии. По умолчанию — true.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Задайте минимальный тайм-аут бездействия (в минутах). Должен быть >= 5 минут.", + "type": "number" + }, + "ipAccessList": { + "description": "Список IP-адресов, которым разрешен доступ к сервису", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "Значение true, если этот сервис является основным сервисом в хранилище данных", + "type": "boolean" + }, + "isReadonly": { + "description": "Значение true, если этот сервис находится в режиме только для чтения. Он может быть в режиме только для чтения только при указании dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Максимальный общий объем памяти каждой реплики при автомасштабировании, в ГБ. Должен быть кратен 4 и не больше 120* для бесплатных сервисов или 356* для платных сервисов. * — максимальный размер реплики зависит от доступности оборудования у облачного провайдера в выбранном вами регионе. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с нестандартным количеством реплик. Максимальный объем памяти трех воркеров при автомасштабировании, в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и не больше 360 для бесплатных сервисов или 1068 для платных сервисов.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Минимальный общий объем памяти каждой реплики при автомасштабировании, в ГБ. Должен быть кратен 4 и не меньше 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с нестандартным количеством реплик. Минимальный объем памяти трех воркеров при автомасштабировании, в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и не меньше 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Имя сервиса. Буквенно-цифровая строка с пробелами длиной до 50 символов.", + "type": "string" + }, + "numReplicas": { + "description": "Количество реплик для сервиса. Количество реплик должно быть от 2 до 20 для первого сервиса в хранилище. Сервисы, создаваемые в существующем хранилище, могут иметь от 1 реплики. В зависимости от уровня вашей организации могут действовать дополнительные ограничения. По умолчанию используется 1 для уровня BASIC и 3 для уровней SCALE и ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Список частных конечных точек", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Пользовательский профиль экземпляра. Доступно только для уровней организации ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Облачный провайдер", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Регион сервиса.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Выберите fast, если хотите получать новые релизы ClickHouse сразу после их выхода. Новые возможности будут доступны быстрее, но с более высоким риском ошибок. Выберите slow, если хотите отложить получение релизов, чтобы у вас было больше времени на тестирование. Эта возможность доступна только для сервисов production. По умолчанию используется обычный канал релизов.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Текущее состояние сервиса.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "УСТАРЕЛО для уровней организации BASIC, SCALE и ENTERPRISE. Уровень сервиса: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Сервисы уровня Production масштабируются, а уровня Development имеют фиксированный размер. Сервисы Azure не поддерживают уровень Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "Идентификатор ключа прозрачного шифрования данных, используемого для сервиса. Доступно только если hasTransparentDataEncryption имеет значение true.", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "Имя хоста сервиса", + "type": "string" + }, + "port": { + "description": "Номер порта", + "type": "number" + }, + "protocol": { + "description": "Протокол конечной точки: 'https', 'nativesecure', 'mysql'.", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "Необязательное имя пользователя для конечной точки", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "Включить или отключить конечную точку", + "type": "boolean" + }, + "protocol": { + "description": "Протокол конечной точки", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "Необязательный двойной хэш SHA1 пароля для протокола MySQL. Если newPasswordHash не указан, этот ключ будет проигнорирован и будет использован сгенерированный пароль. Algorithm: echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "Необязательный хэш пароля. Используется, чтобы избежать передачи пароля по сети. Если не указан, генерируется новый пароль и возвращается в ответе. В противном случае используется этот хэш. Algorithm: echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "Новый пароль сервиса. Предоставляется только если в запросе не было 'newPasswordHash'", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "Список конечных точек сервиса для изменения", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "Имя сервиса. Буквенно-цифровая строка с пробелами длиной до 50 символов.", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "Выберите fast, если хотите получать новые релизы ClickHouse сразу после их выхода. Новые возможности будут доступны быстрее, но и риск ошибок будет выше. Выберите slow, если хотите отложить получение релизов, чтобы оставить себе больше времени на тестирование. Эта возможность доступна только для сервисов 'production'. Значение по умолчанию — regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "Идентификатор ключа для ротации", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "Необязательный идентификатор резервной копии, используемый как начальное состояние для нового сервиса. При использовании регион и уровень нового экземпляра должны совпадать со значениями исходного экземпляра.", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "Это идентификатор, возвращаемый после настройки региона для BYOC (Собственное облако). Если указан параметр byocId, параметры minReplicaMemoryGb и maxReplicaGb также обязательны, а их значения должны быть выбраны из следующих размеров: 48, 116, 172, 232.", + "type": "string" + }, + "complianceType": { + "description": "Тип соответствия нормативным требованиям для сервиса.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "Хранилище данных, содержащее этот сервис", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Необязательная роль для шифрования диска", + "type": "string" + }, + "encryptionKey": { + "description": "Необязательный предоставленный клиентом ключ шифрования диска", + "type": "string" + }, + "endpoints": { + "description": "Список конечных точек сервиса, которые нужно включить или отключить", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "Значение true, если для сервиса должно быть включено прозрачное шифрование данных (TDE). TDE доступно только для организаций уровня ENTERPRISE и может быть включено только при создании сервиса.", + "type": "boolean" + }, + "idleScaling": { + "description": "Если установлено значение true, сервис может масштабироваться до нуля в состоянии простоя. По умолчанию используется true.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Задайте минимальный тайм-аут перехода в состояние простоя (в минутах). Должен быть >= 5 минут.", + "type": "number" + }, + "ipAccessList": { + "description": "Список IP-адресов, которым разрешён доступ к сервису", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "Значение true, если этот сервис только для чтения. Сервис может быть только для чтения, только если указан dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Максимальный общий объём памяти каждой реплики при автомасштабировании в ГБ. Должен быть кратен 4 и меньше или равен 120* для бесплатных сервисов или 356* для платных сервисов.* — максимальный размер реплики зависит от доступности оборудования у облачного провайдера в выбранном вами регионе. ", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Максимальный объём памяти трёх воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и меньше или равно 360 для бесплатных сервисов или 1068 для платных сервисов.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Минимальный общий объём памяти каждой реплики при автомасштабировании в ГБ. Должен быть кратен 4 и больше или равен 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Минимальный объём памяти трёх воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и больше или равно 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Имя сервиса. Буквенно-цифровая строка с пробелами длиной до 50 символов.", + "type": "string" + }, + "numReplicas": { + "description": "Количество реплик для сервиса. Количество реплик должно быть от 2 до 20 для первого сервиса в хранилище. Сервисы, создаваемые в существующем хранилище, могут иметь количество реплик вплоть до 1. В зависимости от уровня вашей организации могут действовать дополнительные ограничения. По умолчанию используется 1 для уровня BASIC и 3 для уровней SCALE и ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "Чтобы связать сервис с частными конечными точками, сначала создайте сервис, затем используйте эндпоинт `Update Service Basic Details` для изменения частных конечных точек.", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "Примите условия закрытой предварительной версии. Это требуется только при создании первого сервиса в организации в случае закрытой предварительной версии", + "type": "boolean" + }, + "profile": { + "description": "Пользовательский профиль инстанса. Доступно только для уровней организации ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Облачный провайдер", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Регион сервиса.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Выберите fast, если хотите получать новые релизы ClickHouse сразу после их выхода. Вы будете быстрее получать новые возможности, но с более высоким риском ошибок. Выберите slow, если хотите отложить получение релизов, чтобы дать себе больше времени на тестирование. Эта возможность доступна только для сервисов production. По умолчанию используется обычный канал релизов.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "УСТАРЕЛО для уровней организации BASIC, SCALE и ENTERPRISE. Уровень сервиса: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Сервисы уровня Production поддерживают масштабирование, а Development имеют фиксированный размер. Сервисы Azure не поддерживают уровень Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "Пароль для вновь созданного сервиса.", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "Разрешённые источники в виде списка доменов, разделённых запятыми", + "type": "string" + }, + "id": { + "description": "Идентификатор эндпоинта запроса сервиса", + "type": "string" + }, + "openApiKeys": { + "description": "Список ключей OpenAPI, у которых есть доступ к эндпоинту запроса сервиса", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "Список ролей, у которых есть доступ к эндпоинту запроса сервиса", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Если задано значение true, сервису разрешается масштабироваться до нуля при бездействии. По умолчанию используется true.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Задайте минимальный тайм-аут бездействия (в минутах). Должен быть >= 5 минут.", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "Максимальный объем памяти для автомасштабирования в ГБ для одной реплики. Доступно только для сервисов 'production'. Значение должно быть кратно 4 и не превышать 120 для бесплатных сервисов или 356 для платных сервисов.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Минимальный объем памяти для автомасштабирования в ГБ для одной реплики. Доступно только для сервисов 'production'. Значение должно быть кратно 4 и не меньше 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "Количество реплик для сервиса. Для первого сервиса в хранилище количество реплик должно быть от 2 до 20. Сервисы, создаваемые в существующем хранилище, могут иметь всего 1 реплику. В зависимости от уровня вашей организации могут действовать дополнительные ограничения. По умолчанию используется 1 для уровня BASIC и 3 для уровней SCALE и ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "Если задано значение true, сервис может масштабироваться до нуля в состоянии бездействия. По умолчанию — true.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Задает минимальный тайм-аут бездействия (в минутах). Должен быть >= 5 минут.", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Максимальный объем памяти трех воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и меньше или равно 360 для бесплатных сервисов или 1068 для платных сервисов.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Минимальный объем памяти трех воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и больше или равно 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "Количество реплик для сервиса. Число реплик должно быть от 2 до 20 для первого сервиса в хранилище. Сервисы, созданные в существующем хранилище, могут иметь количество реплик от 1. В зависимости от уровня вашей организации могут действовать дополнительные ограничения. По умолчанию используется 1 для уровня BASIC и 3 для уровней SCALE и ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "Список идентификаторов доступных частных конечных точек, которые можно подключить к сервису", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "Это ID, возвращаемый после настройки региона для Собственное облако (BYOC). Если указан параметр byocId, параметры minReplicaMemoryGb и maxReplicaGb также обязательны, а их значения должны быть выбраны из следующих размеров: 48, 116, 172, 232.", + "type": "string" + }, + "clickhouseVersion": { + "description": "Версия ClickHouse для сервиса.", + "type": "string" + }, + "complianceType": { + "description": "Тип соответствия нормативным требованиям для сервиса.", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "Временная метка создания сервиса. ISO-8601.", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "Хранилище данных, содержащее этот сервис", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "Необязательная роль для шифрования диска", + "type": "string" + }, + "encryptionKey": { + "description": "Необязательный предоставляемый клиентом ключ шифрования диска", + "type": "string" + }, + "encryptionRoleId": { + "description": "ID роли IAM, используемой для шифрования. Доступно только если hasTransparentDataEncryption имеет значение true.", + "type": "string" + }, + "endpoints": { + "description": "Список всех конечных точек сервиса.", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "True, если для сервиса должно быть включено прозрачное шифрование данных (TDE). TDE доступно только для организаций уровня ENTERPRISE и может быть включено только при создании сервиса.", + "type": "boolean" + }, + "iamRole": { + "description": "роль IAM, используемая для доступа к объектам в S3", + "type": "string" + }, + "id": { + "description": "Уникальный идентификатор сервиса.", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "Если задано значение true, сервис может масштабироваться до нуля в состоянии бездействия. По умолчанию — true.", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "Задает минимальный тайм-аут бездействия (в минутах). Должен быть >= 5 минут.", + "type": "number" + }, + "ipAccessList": { + "description": "Список IP-адресов, которым разрешен доступ к сервису", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "True, если этот сервис является основным сервисом в хранилище данных", + "type": "boolean" + }, + "isReadonly": { + "description": "True, если этот сервис доступен только для чтения. Это возможно только при указании dataWarehouseId.", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "Максимальный объем памяти для автомасштабирования в ГБ для одной реплики. Доступно только для сервисов 'production'. Должно быть кратно 4 и меньше или равно 120 для бесплатных сервисов или 356 для платных сервисов.", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Максимальный объем памяти трех воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и меньше или равно 360 для бесплатных сервисов или 1068 для платных сервисов.", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "Минимальный объем памяти для автомасштабирования в ГБ для одной реплики. Доступно только для сервисов 'production'. Должно быть кратно 4 и больше или равно 8.", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "УСТАРЕЛО — неточно для сервисов с количеством реплик, отличным от значения по умолчанию. Минимальный объем памяти трех воркеров при автомасштабировании в ГБ. Доступно только для сервисов 'production'. Должно быть кратно 12 и больше или равно 24.", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "Имя сервиса. Буквенно-цифровая строка с пробелами длиной до 50 символов.", + "type": "string" + }, + "numReplicas": { + "description": "Количество реплик для сервиса. Число реплик должно быть от 2 до 20 для первого сервиса в хранилище. Сервисы, созданные в существующем хранилище, могут иметь количество реплик от 1. В зависимости от уровня вашей организации могут действовать дополнительные ограничения. По умолчанию используется 1 для уровня BASIC и 3 для уровней SCALE и ENTERPRISE.", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "Список частных конечных точек", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "Пользовательский профиль инстанса. Доступно только для организаций уровня ENTERPRISE.", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "Облачный провайдер", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "Регион сервиса.", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "Выберите fast, если хотите получать новые релизы ClickHouse сразу после их выхода. Так вы быстрее получите новые возможности, но и риск ошибок будет выше. Выберите slow, если хотите отложить получение релизов, чтобы у вас было больше времени на тестирование. Эта возможность доступна только для сервисов в продакшн. По умолчанию используется regular release channel.", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "Текущее состояние сервиса.", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "УСТАРЕЛО для уровней организации BASIC, SCALE и ENTERPRISE. Уровень сервиса: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Сервисы Production поддерживают масштабирование, Development имеют фиксированный размер. Сервисы Azure не поддерживают уровень Development", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "ID ключа прозрачного шифрования данных, используемого для сервиса. Доступно только если hasTransparentDataEncryption имеет значение true.", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "Команда для изменения состояния: 'start', 'stop'.", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "Общая стоимость использования в ClickHouse Credits (CHCs).", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "Стоимость резервного копирования в ClickHouse Credits (CHCs). Применяется к сущностям dataWarehouse.", + "type": "number" + }, + "computeCHC": { + "description": "Стоимость вычислительных ресурсов в ClickHouse Credits (CHCs). Применяется к сущностям service и clickpipe.", + "type": "number" + }, + "dataTransferCHC": { + "description": "Стоимость передачи данных в ClickHouse Credits (CHCs). Применяется к сущностям clickpipe.", + "type": "number" + }, + "initialLoadCHC": { + "description": "Стоимость initial load и resync в ClickHouse Credits (CHCs). Применяется к сущностям clickpipe.", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "Стоимость межрегиональной передачи данных уровня tier1 в ClickHouse Credits (CHCs). Применяется к сущностям service.", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "Стоимость межрегиональной передачи данных уровня tier2 в ClickHouse Credits (CHCs). Применяется к сущностям service.", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "Стоимость межрегиональной передачи данных уровня tier3 в ClickHouse Credits (CHCs). Применяется к сущностям service.", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "Стоимость межрегиональной передачи данных уровня tier4 в ClickHouse Credits (CHCs). Применяется к сущностям service.", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "Стоимость передачи данных в ClickHouse Credits (CHCs). Применяется к сущностям service.", + "type": "number" + }, + "storageCHC": { + "description": "Стоимость хранилища в ClickHouse Credits (CHCs). Применяется к сущностям dataWarehouse.", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "Идентификатор dataWarehouse, к которому относится эта сущность (или которым она является).", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "Дата использования. Дата в формате ISO-8601 на основе часового пояса UTC.", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "Уникальный идентификатор сущности.", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "Имя сущности.", + "type": "string" + }, + "entityType": { + "description": "Тип сущности.", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "Если true, запись неизменяема. Разблокированные записи могут изменяться до блокировки.", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "Идентификатор сервиса, к которому относится эта сущность (или которым она является). Для сущностей dataWarehouse установлено значение null.", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "Общая стоимость использования в ClickHouse Credits (CHCs) для этой сущности.", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "Используйте идентификатор ключа и секрет ключа, полученные в консоли ClickHouse Cloud: https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "Возвращает список с одной организацией, связанной с API key в запросе.", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Получить список доступных организаций", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "Возвращает сведения о конкретной организации. Чтобы получить эти сведения, ключ аутентификации должен принадлежать этой организации.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Получить сведения об организации", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "Обновляет поля организации. Требуется роль ключа аутентификации ADMIN.", + "parameters": [ + { + "description": "Идентификатор организации, которую нужно обновить.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Обновить сведения об организации", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "Возвращает список всех действий в организации.", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Начальная дата поиска", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Конечная дата поиска", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, воспринимаемой как ошибка client." + } + }, + "summary": "Список действий организации", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "Возвращает действие в организации по ID.", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного действия.", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибка клиента." + } + }, + "summary": "Действие организации", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "Создает новую инфраструктуру BYOC в организации. Возвращает конфигурацию вновь созданной инфраструктуры", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибочный со стороны клиента." + } + }, + "summary": "Создать инфраструктуру BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "Удаляет инфраструктуру BYOC из организации", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенной инфраструктуры BYOC", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибочный со стороны клиента." + } + }, + "summary": "Удалить инфраструктуру BYOC", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "Возвращает список всех приглашений в организацию.", + "parameters": [ + { + "description": "Идентификатор запрошенной organization.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Список всех приглашений", + "tags": [ + "User management" + ] + }, + "post": { + "description": "Создает приглашение в организацию.", + "parameters": [ + { + "description": "Идентификатор организации, в которую нужно пригласить пользователя.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Создать приглашение", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "Удаляет одно приглашение в организацию.", + "parameters": [ + { + "description": "ID организации, к которой относится приглашение.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, воспринимаемой как ошибка client." + } + }, + "summary": "Удалить приглашение в организацию", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Возвращает сведения о приглашении в организацию.", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, воспринимаемой как ошибка client." + } + }, + "summary": "Получить сведения о приглашении", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "Возвращает список всех ключей в организации.", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Получить список всех ключей", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "Создает новый API-ключ.", + "parameters": [ + { + "description": "ID организации, которой будет принадлежать ключ.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Создать ключ", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "Удаляет API key. Удалить можно только тот ключ, который не используется для аутентификации текущего запроса.", + "parameters": [ + { + "description": "ID organization, которой принадлежит ключ.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ключа, который нужно удалить.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он расценивается как ошибочный со стороны клиента." + } + }, + "summary": "Удалить ключ", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "Возвращает сведения об одном ключе.", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного ключа.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Получить сведения о ключе", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "Обновляет свойства API-ключа.", + "parameters": [ + { + "description": "ID организации, которой принадлежит ключ.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ключа, который нужно обновить.", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он расценивается как ошибочный со стороны клиента." + } + }, + "summary": "Обновить ключ", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "Возвращает список всех участников organization.", + "parameters": [ + { + "description": "ID запрошенной organization.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он расценивается как ошибочный со стороны клиента." + } + }, + "summary": "Список участников организации", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "Удаляет пользователя из организации", + "parameters": [ + { + "description": "Идентификатор запрошенной organization.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенного пользователя.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Удалить участника организации", + "tags": [ + "User management" + ] + }, + "get": { + "description": "Возвращает сведения об одном участнике organization.", + "parameters": [ + { + "description": "ID organization, в которую входит участник.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного пользователя.", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он расценивается как ошибочный со стороны клиента." + } + }, + "summary": "Получить сведения об участнике", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "Обновляет роль участника organization.", + "parameters": [ + { + "description": "ID organization, в которую входит участник.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID пользователя, данные которого нужно изменить", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Обновить участника организации", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "Устарело. Пожалуйста, воспользуйтесь [документацией](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list), чтобы выполнить обновленную процедуру.", + "parameters": [ + { + "description": "Идентификатор запрошенной organization.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор облачного провайдера. Одно из значений: aws, gcp или azure.", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Идентификатор региона в рамках конкретного облачного провайдера.", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Получить конфигурацию частной конечной точки для региона у облачного провайдера для организации", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "Возвращает метрики Prometheus для всех сервисов организации.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Возвращает отфильтрованный список метрик Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Получить метрики организации", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "Возвращает список всех сервисов организации.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Критерии фильтрации, применяемые при получении ресурса. В настоящее время поддерживается фильтрация только по тегам ресурса.", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Список сервисов организации", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Создает новый сервис в организации и возвращает текущее состояние сервиса и пароль для доступа к нему. Сервис запускается асинхронно.", + "parameters": [ + { + "description": "ID организации, которой будет принадлежать сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая расценивается как ошибка клиента." + } + }, + "summary": "Создать новый сервис", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "Удаляет сервис. Сервис должен находиться в остановленном состоянии и удаляется асинхронно после вызова этого метода.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, который нужно удалить.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или отказывается обработать запрос из-за ошибки со стороны клиента." + } + }, + "summary": "Удалить сервис", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Возвращает сервис, принадлежащий организации", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая расценивается как ошибка клиента." + } + }, + "summary": "Получить сведения о сервисе", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "Обновляет основные сведения о сервисе, такие как имя сервиса или IP Access List.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, который нужно обновить.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая расценивается как ошибка клиента." + } + }, + "summary": "Обновить основные сведения о сервисе", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "Возвращает конфигурацию резервного копирования сервиса.", + "parameters": [ + { + "description": "Идентификатор organization, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он воспринимается как ошибка на стороне клиента." + } + }, + "summary": "Получить конфигурацию резервного копирования сервиса", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "Обновляет конфигурацию резервного копирования сервиса. Требуется роль ключа аутентификации Admin. Если задать свойствам значение NULL, они будут сброшены к значениям по умолчанию.", + "parameters": [ + { + "description": "Идентификатор organization, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он воспринимается как ошибка на стороне клиента." + } + }, + "summary": "Обновить конфигурацию резервного копирования сервиса", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "Возвращает список всех резервных копий сервиса. Самые новые резервные копии отображаются первыми в списке.", + "parameters": [ + { + "description": "ID организации, которой принадлежит резервная копия.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, из которого была создана резервная копия.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он воспринимается как ошибка на стороне клиента." + } + }, + "summary": "Список резервных копий сервиса", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "Возвращает информацию об одной резервной копии.", + "parameters": [ + { + "description": "Идентификатор organization, которой принадлежит резервная копия.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, из которого была создана резервная копия.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенной резервной копии.", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он воспринимается как ошибка на стороне клиента." + } + }, + "summary": "Получить сведения о резервной копии", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Возвращает список ClickPipes.", + "parameters": [ + { + "description": "Идентификатор организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибка клиента." + } + }, + "summary": "Список ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Создает новый ClickPipe.", + "parameters": [ + { + "description": "Идентификатор организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, для которого нужно создать ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибка клиента." + } + }, + "summary": "Создать ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**Эта конечная точка доступна в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Удаляет указанный ClickPipe.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ClickPipe, который нужно удалить.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Удалить ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Эта конечная точка доступна в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Возвращает указанный ClickPipe.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного ClickPipe.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Получить ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Эта конечная точка доступна в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Обновляет указанный ClickPipe.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, для которого создаётся ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного ClickPipe.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за проблемы, которая считается ошибкой клиента." + } + }, + "summary": "Обновить ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается несовместимых изменений.

Измените настройки масштабирования для указанного ClickPipe.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ClickPipe, для которого нужно обновить настройки масштабирования.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный ID, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Масштабирование ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**Эта конечная точка доступна в бета-версии.** Контракт API стабилен, и в будущем не ожидается обратно несовместимых изменений.

Возвращает расширенные настройки для указанного ClickPipe.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ClickPipe, для которого нужно получить настройки.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный ID, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Получить настройки ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается несовместимых изменений.

Обновите расширенные настройки для указанного ClickPipe. Передавайте пары ключ-значение, где значениями могут быть строки, числа или булевы значения.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ClickPipe, для которого нужно обновить настройки.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный ID, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за ошибки на стороне клиента." + } + }, + "summary": "Обновить настройки ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается несовместимых изменений.

Запустите, остановите или выполните повторную синхронизацию ClickPipe. Остановка ClickPipe прекращает процесс ингестии из любого состояния. Запуск разрешён для ClickPipe в состоянии \"Stopped\" или со статусом \"Failed\". Повторная синхронизация доступна только для пайпов Postgres и может быть выполнена из любого состояния.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID ClickPipe, для которого нужно обновить состояние.", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Обновить состояние ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается breaking changes.

Получить настройки масштабирования для DB ClickPipes.\n\nИнфраструктура является общей для всех DB ClickPipes в сервисе — как для initial load, так и для CDC. Для целей billing 2 CPU cores и 8 ГБ оперативной памяти [соответствуют](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) одной compute unit.\n\n**Эта конечная точка становится доступной после подготовки хотя бы одного DB ClickPipe.**", + "parameters": [ + { + "description": "Идентификатор organization, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Получить параметры масштабирования CDC ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается breaking changes.

Обновить настройки масштабирования для DB ClickPipes.\n\nИнфраструктура является общей для всех DB ClickPipes в сервисе — как для initial load, так и для CDC. Полное применение настроек масштабирования может занять несколько минут.\n\nДля целей billing 2 CPU cores и 8 ГБ оперативной памяти [соответствуют](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) одной compute unit. Если изменится organization tier, DB ClickPipes будут соответствующим образом [масштабированы](https://clickhouse.com/docs/cloud/manage/billing/overview#compute).\n\n**Эта конечная точка становится доступной после подготовки хотя бы одного DB ClickPipe.**", + "parameters": [ + { + "description": "Идентификатор organization, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, которому принадлежит ClickPipe.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Обновить параметры масштабирования CDC ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается несовместимых изменений.

Возвращает список обратных частных конечных точек для указанного сервиса.", + "parameters": [ + { + "description": "Идентификатор организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, которому принадлежит обратная частная конечная точка.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибочный со стороны клиента." + } + }, + "summary": "Список обратных частных конечных точек", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**Эта конечная точка находится в бета-версии.** Контракт API стабилен, и в будущем не ожидается несовместимых изменений.

Создает новую обратную частную конечную точку.", + "parameters": [ + { + "description": "Идентификатор организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор сервиса, которому принадлежит обратная частная конечная точка.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Создать обратную частную конечную точку", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**Эта конечная точка находится в бета-статусе.** Контракт API стабилен, и в будущем не ожидается breaking changes.

Удаляет обратную частную конечную точку с указанным ID.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит обратная частная конечная точка.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID обратной частной конечной точки, которую требуется удалить.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Удалить обратную частную конечную точку", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**Эта конечная точка находится в бета-статусе.** Контракт API стабилен, и в будущем не ожидается breaking changes.

Возвращает обратную частную конечную точку с указанным ID.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, которому принадлежит обратная частная конечная точка.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID обратной частной конечной точки, которую требуется получить.", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он считается ошибочным со стороны клиента." + } + }, + "summary": "Получить обратную частную конечную точку", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "Устанавливает новый пароль для сервиса", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, для которого обновляется пароль.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за причины, которая считается ошибкой клиента." + } + }, + "summary": "Обновить пароль сервиса", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "Создает новую частную конечную точку. Частная конечная точка будет связана с этим сервисом и организацией", + "parameters": [ + { + "description": "ID запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, назначаемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за причины, которая считается ошибкой клиента." + } + }, + "summary": "Создать частную конечную точку", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "Сведения, необходимые для настройки частной конечной точки", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или отказывается обработать запрос из-за ошибки со стороны клиента." + } + }, + "summary": "Получить конфигурацию частной конечной точки", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "Возвращает метрики Prometheus для сервиса.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Возвращает отфильтрованный список метрик Prometheus.", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не хочет обработать запрос из-за причины, которая считается ошибкой клиента." + } + }, + "summary": "Получить метрики сервиса", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "Обновляет минимальные и максимальные лимиты памяти на реплику и поведение масштабирования в режиме бездействия для сервиса. Настройки памяти доступны только для сервисов в \"продакшн\" и должны быть кратны 4, начиная с 8GB. Чтобы включить возможность настройки numReplicas, необходимо обратиться в службу поддержки.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, для которого нужно обновить параметры масштабирования.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Обновить настройки автомасштабирования сервиса", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "Обновляет минимальные и максимальные общие лимиты памяти и поведение масштабирования в режиме бездействия для сервиса. Настройки памяти доступны только для сервисов в \"продакшн\" и должны быть кратны 12, начиная с 24GB. Чтобы включить возможность настройки numReplicas, необходимо обратиться в службу поддержки.", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, для которого нужно обновить параметры масштабирования.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Обновить настройки автомасштабирования сервиса", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "Это экспериментальная возможность. Чтобы включить её, обратитесь в службу поддержки.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или отказывается обработать запрос из-за ошибки со стороны клиента." + } + }, + "summary": "Удалить эндпоинт запроса сервиса для указанного экземпляра", + "tags": [ + "Service" + ] + }, + "get": { + "description": "Это экспериментальная возможность. Чтобы включить её, обратитесь в службу поддержки.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Идентификатор запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код состояния HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или отказывается обработать запрос из-за ошибки со стороны клиента." + } + }, + "summary": "Получить эндпоинт запроса сервиса для указанного экземпляра", + "tags": [ + "Service" + ] + }, + "post": { + "description": "Это экспериментальная возможность. Чтобы включить её, обратитесь в службу поддержки.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID запрошенного сервиса.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Создать или обновить эндпоинт запроса сервиса для указанного экземпляра", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "Запускает или останавливает сервис", + "parameters": [ + { + "description": "ID организации, которой принадлежит сервис.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "ID сервиса, состояние которого нужно обновить.", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за причины, которая воспринимается как ошибка клиента." + } + }, + "summary": "Обновить состояние сервиса", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "Возвращает общую сумму и список ежедневных записей о стоимости использования организации по сущностям за запрошенный период времени (максимум 31 день). Все дни как в запросе, так и в ответе рассчитываются по часовому поясу UTC.", + "parameters": [ + { + "description": "Идентификатор запрошенной организации.", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "Дата начала отчета, например 2024-12-19.", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "Дата окончания отчета (включительно), например 2024-12-20. Эта дата не может быть более чем на 30 дней позже from_date (максимальная длительность запрашиваемого периода — 31 день).", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "Уникальный идентификатор, присваиваемый каждому запросу. UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Успешный ответ" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "Подробное описание ошибки.", + "type": "string" + }, + "status": { + "description": "Код статуса HTTP.", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "Сервер не может или не будет обрабатывать запрос из-за того, что он распознается как ошибка клиента." + } + }, + "summary": "Получить расходы организации на использование", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/ru/_specs/hyperdx-openapi.json b/ru/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..0f83ea388 --- /dev/null +++ b/ru/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "Функция агрегации, используемая для данных", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "Поле для агрегирования", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "Поля, по которым группируются результаты", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "Тип данных метрики", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "Имя метрики (для источников данных метрик)", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "ID источника данных для этой серии", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "Условие фильтра в синтаксисе запросов Lucene", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "Язык запросов, используемый в предложении WHERE", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "Значения группировки, если указан groupBy", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "Значение для первой серии", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "Значение для второй серии", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "Временная метка точки данных (время начала бакета)", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "Конечная временная метка в миллисекундах", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "Размер временного бакета для агрегаций", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "Массив конфигураций серий", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "Формат возвращаемых данных", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "Начальная временная метка в миллисекундах", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "API для управления оповещениями и панелями мониторинга HyperDX", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "Возвращает список всех оповещений для прошедшей проверку подлинности команды", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "Список оповещений", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "Оповещения успешно получены" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Unauthorized" + } + }, + "summary": "Список оповещений", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "Создает новое оповещение", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "Создать оповещение на основе плитки", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Оповещение успешно создано" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Unauthorized" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Ошибка сервера или ошибка валидации" + } + }, + "summary": "Создать оповещение", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "Удаляет оповещение", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "ID оповещения", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Оповещение успешно удалено" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Нет авторизации" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Оповещение не найдено" + } + }, + "summary": "Удалить оповещение", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "Возвращает конкретное оповещение по ID", + "operationId": "getAlert", + "parameters": [ + { + "description": "ID оповещения", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "Ответ с одним оповещением", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Оповещение успешно получено" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Нет авторизации" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Оповещение не найдено" + } + }, + "summary": "Получить оповещение", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "Обновляет существующее оповещение", + "operationId": "updateAlert", + "parameters": [ + { + "description": "ID оповещения", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "Обновить свойства оповещения", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "Оповещение успешно обновлено" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Нет авторизации" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Оповещение не найдено" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Ошибка сервера или ошибка валидации" + } + }, + "summary": "Обновить оповещение", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "Возвращает данные временных рядов на основе настроенных параметров серий", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "Базовый запрос временного ряда", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "Серия данных метрики", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "Несколько серий с группировкой", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "Серии из нескольких источников", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "Сгруппированные данные временного ряда", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "Точки данных временного ряда", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "Данные временных рядов успешно получены" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Недопустимые параметры запроса" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Unauthorized" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Источник не найден" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "Ошибка сервера" + } + }, + "summary": "Запрос данных серий диаграммы", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "Возвращает список всех панелей мониторинга для прошедшей проверку подлинности команды", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "Панели мониторинга успешно получены" + }, + "401": { + "description": "Unauthorized" + } + }, + "summary": "Список панелей мониторинга", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "Создает новую панель мониторинга", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "Панель мониторинга с несколькими типами диаграмм", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "Панель мониторинга с диаграммой временного ряда", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "Ответ с созданной панелью мониторинга", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Панель мониторинга успешно создана" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Unauthorized" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Ошибка сервера или ошибка валидации" + } + }, + "summary": "Создать панель мониторинга", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "Удаляет панель мониторинга", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "Идентификатор панели мониторинга", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "Панель мониторинга успешно удалена" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Нет авторизации" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Панель мониторинга не найдена" + } + }, + "summary": "Удалить панель мониторинга", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "Возвращает конкретную панель мониторинга по ID", + "operationId": "getDashboard", + "parameters": [ + { + "description": "ID панели мониторинга", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "Ответ с одной панелью мониторинга", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Панель мониторинга успешно получена" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Unauthorized" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Панель мониторинга не найдена" + } + }, + "summary": "Получить панель мониторинга", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "Обновляет существующую панель мониторинга", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "ID панели мониторинга", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "Обновить свойства панели мониторинга и плитки", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "Ответ с обновлённой панелью мониторинга", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "Панель мониторинга успешно обновлена" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Unauthorized" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Панель мониторинга не найдена" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Ошибка сервера или ошибка валидации" + } + }, + "summary": "Обновить панель мониторинга", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "Продакшн API-сервер", + "url": "https://api.hyperdx.io" + }, + { + "description": "Текущий сервер", + "url": "/" + } + ], + "tags": [ + { + "description": "Конечные точки для управления панелями мониторинга и их визуализациями", + "name": "Dashboards" + }, + { + "description": "Конечные точки для управления оповещениями мониторинга", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/ru/clickstack/features/dashboards/overview.mdx b/ru/clickstack/features/dashboards/overview.mdx index 16f890bd2..1b327e56e 100644 --- a/ru/clickstack/features/dashboards/overview.mdx +++ b/ru/clickstack/features/dashboards/overview.mdx @@ -59,10 +59,14 @@ ClickStack поддерживает визуализацию событий со Обратите внимание: события можно фильтровать либо с помощью SQL-условия `WHERE`, либо с помощью синтаксиса Lucene, а также задавать временной диапазон, за который они должны отображаться. Также поддерживается несколько серий. - Например, можно отфильтровать данные по сервису `frontend`, добавив фильтр `ServiceName:\"frontend\"`. Нажмите `Add Series`, чтобы добавить вторую серию для количества событий по времени с псевдонимом `Count`. + Например, можно отфильтровать данные по сервису `frontend`, добавив фильтр `ServiceName:"frontend"`. Нажмите `Add Series`, чтобы добавить вторую серию для количества событий по времени с псевдонимом `Count`. Простая визуализация 2 + Чтобы создать серию, похожую на уже существующую, её можно дублировать вместо того, чтобы начинать с нуля. Нажмите значок копирования (`Duplicate series`) в строке серии, чтобы вставить копию прямо под ней. Копия сохраняет настройки исходной серии, такие как метрика, столбец и фильтр. Затем нужно изменить только те поля, которые отличаются (например, агрегацию), и задать копии собственный псевдоним. Дублирование доступно везде, где поддерживается несколько серий. Оно скрыто для типов визуализации, в которых допускается только одна серия, например `Number`, `Pie` и `Heatmap`. + + Значок копирования Duplicate series и его всплывающая подсказка в строке серии графика + Визуализации можно создавать из любого источника данных — метрик, трассировок или журналов. ClickStack обрабатывает всё это как события в широком формате. Любой **числовой столбец** можно отображать на графике во времени, а **строковые**, **числовые** столбцы и столбцы с **датами** можно использовать для группировки. diff --git a/ru/clickstack/ingesting-data/collector.mdx b/ru/clickstack/ingesting-data/collector.mdx index 904bb2a41..c249e05d8 100644 --- a/ru/clickstack/ingesting-data/collector.mdx +++ b/ru/clickstack/ingesting-data/collector.mdx @@ -104,7 +104,7 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; - Целевой экземпляр ClickHouse настраивается через переменные среды `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` и `CLICKHOUSE_PASSWORD`. Переменная `CLICKHOUSE_ENDPOINT` должна содержать полный HTTP-адрес конечной точки ClickHouse Cloud, включая протокол и порт — например, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. + Целевой экземпляр ClickHouse настраивается через переменные среды `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` и `CLICKHOUSE_PASSWORD`. Переменная `CLICKHOUSE_ENDPOINT` должна содержать полный HTTP-адрес конечной точки ClickHouse Cloud, включая протокол и порт — например, `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`. Подробнее о получении учётных данных Управляемого ClickStack см. [здесь](/ru/products/cloud/guides/sql-console/connection-details). @@ -118,7 +118,7 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; #### Настройка экземпляра Управляемого ClickStack - OpenTelemetry Collector можно настроить для использования экземпляра Управляемого ClickStack с помощью переменных окружения `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` и `CLICKHOUSE_PASSWORD`. Способ их настройки зависит от метода развертывания: + OpenTelemetry Collector можно настроить для использования экземпляра Управляемого ClickStack с помощью переменных окружения `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` и `CLICKHOUSE_PASSWORD`. Способ их настройки зависит от метода развертывания: @@ -162,7 +162,7 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; При использовании Docker Compose измените конфигурацию коллектора, используя те же переменные среды, что указаны выше: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # расширение health_check - - '24225:24225' # приёмник fluentd - - '4317:4317' # приёмник OTLP gRPC - - '4318:4318' # приёмник OTLP HTTP - - '8888:8888' # расширение метрик + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver + - '4317:4317' # OTLP gRPC receiver + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,7 +261,7 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; - Целевой экземпляр ClickHouse настраивается через переменные среды `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` и `CLICKHOUSE_PASSWORD`. Переменная `CLICKHOUSE_ENDPOINT` должна содержать полный HTTP-адрес конечной точки ClickHouse, включая протокол и порт — например, `http://localhost:8123`. + Целевой экземпляр ClickHouse настраивается через переменные среды `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` и `CLICKHOUSE_PASSWORD`. Переменная `CLICKHOUSE_ENDPOINT` должна содержать полный HTTP-адрес конечной точки ClickHouse, включая протокол и порт — например, `http://localhost:8123`. **Эти переменные окружения можно использовать с любым из дистрибутивов Docker, в состав которых входит коннектор.** @@ -275,7 +275,7 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; #### Настройка экземпляра ClickHouse - OpenTelemetry Collector можно настроить для работы с экземпляром ClickHouse с помощью переменных среды `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USERNAME` и `CLICKHOUSE_PASSWORD`. Способ их задания зависит от выбранного метода развёртывания: + OpenTelemetry Collector можно настроить для работы с экземпляром ClickHouse с помощью переменных среды `OPAMP_SERVER_URL`, `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` и `CLICKHOUSE_PASSWORD`. Способ их задания зависит от выбранного метода развёртывания: @@ -319,10 +319,10 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; #### Docker Compose - При использовании Docker Compose измените конфигурацию коллектора с помощью тех же переменных среды, что указаны выше: + При использовании Docker Compose измените конфигурацию коллектора, используя те же переменные среды, что указаны выше: ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ import ExtendingConfig from '/snippets/ru/_extending_config.mdx'; CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # расширение health_check - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # расширение метрик + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/ru/clickstack/mcp.mdx b/ru/clickstack/mcp.mdx index 8394e6886..9268f838c 100644 --- a/ru/clickstack/mcp.mdx +++ b/ru/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'MCP-сервер ClickStack' sidebarTitle: 'MCP-сервер' description: 'Подключайте ИИ-ассистентов к ClickStack с помощью сервера Model Context Protocol (MCP)' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'обсервабилити', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', 'обсервабилити', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -19,112 +19,222 @@ ClickStack включает встроенный сервер [Model Context Pro MCP-сервер доступен в следующих типах развертывания ClickStack: -| Развертывание | Статус | -| ------------------------------------------------- | -------------------- | -| **Open Source ClickStack** | Доступно | -| **BYOC (Собственное облако)** | Доступно | -| **Управляемый ClickStack** | Скоро будет доступно | -| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Не поддерживается | +| Развертывание | Статус | +| ------------------------------------------------- | ----------------- | +| **Open Source ClickStack** | Доступно | +| **BYOC (Собственное облако)** | Доступно | +| **ClickStack в ClickHouse Cloud** | Доступно | +| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Не поддерживается | - - **Управляемый ClickStack** + + **Разная настройка для ClickHouse Cloud и OSS/BYOC** - Поддержка MCP-сервера для Управляемого ClickStack находится в активной разработке и скоро станет доступна. Инструкции на этой странице относятся к развертываниям Open Source ClickStack и BYOC. - + ClickStack в ClickHouse Cloud использует другую конечную точку и другой метод аутентификации, чем развертывания Open Source и BYOC. См. раздел [ClickStack в ClickHouse Cloud](#managed-clickstack) ниже с инструкциями по настройке для Cloud. + -
- ## Предварительные требования +
+ ## ClickStack в ClickHouse Cloud
-Перед подключением MCP-клиента вам потребуется: +ClickStack в ClickHouse Cloud подключается через конечную точку Cloud MCP по адресу `https://mcp.clickhouse.cloud/clickstack` и использует аутентификацию OAuth 2.0. Аутентификация с помощью API-ключа для этой конечной точки не поддерживается. -* запущенный экземпляр ClickStack (варианты развертывания см. в разделе [Развертывание](/ru/clickstack/deployment/overview)) -* **Personal API Access Key** — его можно найти в HyperDX: **Team Settings → API Keys → Personal API Access Key** +
+ ### Предварительные требования +
-Personal API Access Key в разделе Team Settings +* Запущенный сервис ClickHouse Cloud с [включенным ClickStack](/ru/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud) +* [Включенный MCP](/ru/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) на сервисе — откройте консоль Cloud, нажмите **Connect**, выберите **Connect with MCP** и включите его - - Personal API Access Key отличается от **Ingestion API Key** в Team Settings, который используется для аутентификации телеметрических данных, отправляемых в OpenTelemetry Collector. - +
+ ### Конечная точка +
+ +```text +https://mcp.clickhouse.cloud/clickstack +``` + +Для аутентификации используется OAuth 2.0. Когда ваш MCP-клиент подключается впервые, откроется окно браузера, в котором нужно войти с учетными данными ClickHouse Cloud. Ключ API не требуется. -
- ## Конечная точка +
+ ### Подключение MCP-клиента
-MCP-сервер доступен по пути `/api/mcp` в URL фронтенда ClickStack: +При первом подключении каждый клиент автоматически выполняет OAuth-авторизацию. -Например, для локального развертывания с настройками по умолчанию: + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -Замените `localhost:8080` на хост и порт вашего экземпляра, если вы изменили стандартные значения. + Запустите Claude Code и выполните `/mcp`, затем выберите `clickstack-cloud`, чтобы завершить OAuth-авторизацию. + - - В примерах на этой странице используется URL фронтенд-приложения (по умолчанию порт `8080`). Вы также можете обращаться к MCP-серверу напрямую через бэкенд по адресу `/mcp`, но не во всех развертываниях бэкенд доступен извне, поэтому в этой документации используется путь через фронтенд. - + + Добавьте следующее в `.cursor/mcp.json`: -MCP-сервер использует транспорт **Streamable HTTP** с аутентификацией по **Bearer token**. + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Добавьте следующее в `.vscode/mcp.json`: + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Добавьте следующее в `opencode.json`: + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + Подключиться может любой MCP-клиент с поддержкой **Streamable HTTP** и OAuth. Настройте его следующим образом: -
- ## Подключение MCP-клиента + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### Указание конкретного сервиса
-В примерах ниже показано, как настроить популярные MCP-клиенты. Замените `` URL-адресом вашего экземпляра (например, `http://localhost:8080`), а `` — вашим Personal API Access Key. +Без заголовка `x-service-id` запросы по умолчанию направляются в первый сервис ClickStack, созданный в вашем аккаунте. Чтобы обратиться к другому сервису, передайте `x-service-id: ` в качестве заголовка в конфигурации вашего MCP-клиента. -
- ### Claude code +
+ ## Open Source и BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +Развертывания Open Source и BYOC используют встроенную конечную точку MCP экземпляра ClickStack с аутентификацией по Bearer-токену. -
- ### Cursor +
+ ### Предварительные требования
-Добавьте следующее в файл `.cursor/mcp.json` вашего проекта или в глобальные настройки Cursor: +* запущенный экземпляр ClickStack (варианты развертывания см. в разделе [Развертывание](/ru/clickstack/deployment/overview)) +* **Personal API Access Key** — его можно найти в HyperDX: **Team Settings → API Keys → Personal API Access Key** -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Personal API Access Key в разделе Team Settings + + + Personal API Access Key отличается от **ключ API для приёма данных API key** в Team Settings, который используется для аутентификации телеметрических данных, отправляемых в OpenTelemetry Collector. + -
- ### OpenCode +
+ ### Конечная точка
-Добавьте следующее в файл конфигурации `opencode.json`: +MCP-сервер доступен по пути `/api/mcp` в URL фронтенда ClickStack. Например, для локального развертывания с настройками по умолчанию URL: `http://localhost:8080/api/mcp`. Замените `localhost:8080` на хост и порт вашего экземпляра, если вы изменили стандартные значения. -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + В примерах на этой странице используется URL фронтенд-приложения (по умолчанию порт `8080`). Вы также можете обращаться к MCP-серверу напрямую через бэкенд по адресу `/mcp`, но не во всех развертываниях бэкенд доступен извне, поэтому в этой документации используется путь через фронтенд. + + +MCP-сервер использует транспорт **Streamable HTTP** с аутентификацией по **Bearer token**. -
- ### Другие клиенты +
+ ### Подключение MCP-клиента
-Подключиться может любой MCP-клиент, поддерживающий транспорт **Streamable HTTP**. Настройте его следующим образом: +Замените `` на URL вашего экземпляра (например, `http://localhost:8080`), а `` — на ваш Personal API Access Key. + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + Добавьте следующее в файл `.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Добавьте следующее в файл `.vscode/mcp.json`: + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + Добавьте следующее в файл `opencode.json`: + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + Подключиться может любой MCP-клиент с поддержкой **Streamable HTTP**. Укажите: -* **URL:** `/api/mcp` -* **Заголовок:** `Authorization: Bearer ` + * **URL:** `/api/mcp` + * **Заголовок:** `Authorization: Bearer ` + +
## Что можно делать с MCP? @@ -143,9 +253,11 @@ claude mcp add --transport http hyperdx /api/mcp \ Со временем набор инструментов может расширяться. Ваш MCP-клиент автоматически обнаружит доступные инструменты при подключении.
- ## Использование в нескольких командах + ## Использование в нескольких командах (OSS/BYOC)
+Это относится только к развертываниям с открытым исходным кодом и BYOC. Для ClickStack в ClickHouse Cloud см. [указание конкретного сервиса](#managed-service-override). + По умолчанию запросы MCP выполняются в контексте вашей основной команды. Если вы состоите в нескольких командах, можно обратиться к конкретной команде, передав заголовок `x-hdx-team` с ID команды вместе с заголовком `Authorization`. Если этот заголовок не указан, используется ваша основная команда. Если указать команду, в которую вы не входите, запрос будет отклонён с ошибкой `401`. Используйте в своём MCP-клиенте инструмент вывода списка команд, чтобы узнать, к каким командам у вас есть доступ и какая из них активна. @@ -154,8 +266,31 @@ claude mcp add --transport http hyperdx /api/mcp \ ## Устранение неполадок
+
+ ### ClickStack в ClickHouse Cloud +
+ + + * Убедитесь, что ваш MCP-клиент поддерживает OAuth 2.0. Клиенты, поддерживающие только Bearer-токен или транспорт `stdio`, не могут пройти аутентификацию через конечную точку Cloud. + * Проверьте, не блокирует ли браузер всплывающее окно OAuth или перенаправление. + * Убедитесь, что у вашего аккаунта ClickHouse Cloud есть доступ к организации и сервису. + + + + * Убедитесь, что вы используете конечную точку ClickStack (`https://mcp.clickhouse.cloud/clickstack`), а не общую конечную точку Cloud MCP (`https://mcp.clickhouse.cloud/mcp`). + * Убедитесь, что [MCP включен](/ru/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server) для сервиса в консоли Cloud. + + + + Без заголовка `x-service-id` запросы по умолчанию направляются в первый подготовленный сервис ClickStack, к которому обращался ваш аккаунт. Передайте этот заголовок, чтобы указать конкретный сервис. См. [указание конкретного сервиса](#managed-service-override). + + +
+ ### Open Source и BYOC +
+ - * Убедитесь, что вы используете **Personal API Access Key** (а не ключ API для приёма данных). + * Убедитесь, что вы используете **Personal API Access Key** (а не ключ API для приёма данных API key). * Убедитесь, что ключ передаётся как токен `Bearer` в заголовке `Authorization`. * Проверьте, что ваш экземпляр ClickStack запущен и доступен по указанному URL. diff --git a/ru/clickstack/navigation.json b/ru/clickstack/navigation.json index ed6ebbbfa..1f21fa8bc 100644 --- a/ru/clickstack/navigation.json +++ b/ru/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "ru/_specs/hyperdx-openapi.json", "root": "ru/clickstack/api-reference" } ] diff --git a/ru/concepts/features/operations/update/replacing-merge-tree.mdx b/ru/concepts/features/operations/update/replacing-merge-tree.mdx index 021fde93f..83f8a9201 100644 --- a/ru/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/ru/concepts/features/operations/update/replacing-merge-tree.mdx @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --выбрать 100 случайных строк +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --выбрать 100 случайных строк +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -Результатом описанных выше операций будет 16 000 строк, то есть 10 000 + 5000 + 1000. Однако правильный итог здесь другой: в действительности строк должно быть всего на 1000 меньше исходного количества, то есть 10 000 - 1000 = 9000. +Результатом описанных выше операций будет 16 000 строк, то есть 10 000 + 5000 + 1000. В действительности строк должно быть всего на 1000 меньше исходного количества, то есть 10 000 - 1000 = 9000. ```sql SELECT count() @@ -207,10 +207,10 @@ FROM posts_updateable ┌─count()─┐ │ 10000 │ └─────────┘ -1 строка в наборе. Elapsed: 0.002 sec. +1 row in set. Elapsed: 0.002 sec. ``` -Ваши результаты здесь будут различаться в зависимости от того, какие слияния уже произошли. Мы видим, что общее количество здесь отличается, поскольку у нас есть дублирующиеся строки. Применение `FINAL` к таблице дает правильный результат. +Ваши результаты будут различаться в зависимости от того, какие слияния уже произошли. Мы видим, что общее количество отличается из-за дублирующихся строк. Применение `FINAL` к таблице дает правильный результат. ```sql SELECT count() @@ -359,11 +359,11 @@ ORDER BY year ASC ### Настройка слияний для повышения производительности запросов
-По умолчанию для min_age_to_force_merge_seconds и min_age_to_force_merge_on_partition_only установлены значения 0 и false соответственно, поэтому эти возможности отключены. В такой конфигурации ClickHouse использует стандартное поведение слияния и не принудительно запускает слияния на основе возраста партиции. +По умолчанию `min_age_to_force_merge_seconds` и `min_age_to_force_merge_on_partition_only` имеют значения 0 и false соответственно, поэтому эти возможности отключены. В такой конфигурации ClickHouse использует стандартное поведение слияния и не запускает принудительные слияния на основе возраста партиции. -Если задано значение min_age_to_force_merge_seconds, ClickHouse будет игнорировать обычные эвристики слияния для частей старше указанного периода. Хотя обычно это имеет смысл только тогда, когда цель — минимизировать общее число частей, в ReplacingMergeTree это может повысить производительность запросов за счёт уменьшения числа частей, которые нужно сливать во время выполнения запроса. +Если задано значение `min_age_to_force_merge_seconds`, ClickHouse будет игнорировать обычные эвристики слияния для частей старше указанного периода. Хотя обычно это имеет смысл только тогда, когда цель — минимизировать общее число частей, в ReplacingMergeTree это может повысить производительность запросов за счёт уменьшения числа частей, которые нужно сливать во время выполнения запроса. -Это поведение можно дополнительно настроить, установив min_age_to_force_merge_on_partition_only=true: тогда для агрессивного слияния все части в партиции должны быть старше, чем min_age_to_force_merge_seconds. Такая конфигурация позволяет старым партициям со временем сливаться в одну часть, что консолидирует данные и помогает поддерживать производительность запросов. +Это поведение можно дополнительно настроить, установив `min_age_to_force_merge_on_partition_only=true`: тогда для агрессивного слияния все части в партиции должны быть старше `min_age_to_force_merge_seconds`. Такая конфигурация позволяет старым партициям со временем сливаться в одну часть, что консолидирует данные и помогает поддерживать производительность запросов. * Параметры снимка нельзя изменить после создания пайпа. Если вы хотите их поменять, потребуется создать новый ClickPipe. -* При добавлении таблиц в существующий ClickPipe изменить параметры снимка нельзя. Для новых таблиц ClickPipe будет использовать уже заданные параметры. -* Столбец ключа партиционирования не должен содержать `NULL`, так как такие значения пропускаются логикой партиционирования. \ No newline at end of file +* При добавлении таблиц в существующий ClickPipe изменить параметры снимка нельзя. Для новых таблиц ClickPipe будет использовать уже заданные параметры. \ No newline at end of file diff --git a/ru/integrations/language-clients/go/config-reference.mdx b/ru/integrations/language-clients/go/config-reference.mdx index 748f8075d..fd2c42c80 100644 --- a/ru/integrations/language-clients/go/config-reference.mdx +++ b/ru/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### Тайм-ауты
-| Параметр | Тип | По умолчанию | Параметр DSN | Описание | Рекомендация | При неправильной настройке | -| ------------- | --------------- | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Максимальное время на установку нового соединения. Также задаёт время ожидания получения соединения из пула, если достигнут предел `MaxOpenConns`. | 5-10s в LAN, 15-30s в WAN/cloud. Никогда не меньше 1s. | Слишком короткий: `"clickhouse: acquire conn timeout"` при перегрузке. Слишком длинный (> 60s): приложение зависает во время сбоев. | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Максимальное время ожидания ответа сервера для каждого вызова чтения. Применяется к каждому блоку, а не ко всему запросу. Приоритет имеет deadline контекста. | 10-30s для коротких интерактивных запросов; 5-30m для длительных аналитических запросов. | Слишком короткий: `"i/o timeout"` или `"read: connection reset by peer"` в середине запроса; сервер продолжает выполнение. Слишком длинный: разорванные соединения не обнаруживаются. | +| Параметр | Тип | По умолчанию | Параметр DSN | Описание | Рекомендация | При неправильной настройке | +| ------------- | --------------- | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Максимальное время на установку нового соединения. Также задаёт время ожидания получения соединения из пула, если достигнут предел `MaxOpenConns`. | 5-10s в LAN, 15-30s в WAN/cloud, 1-2m при подключении к приостановленному сервису ClickHouse Cloud. Никогда не меньше 1s. | Слишком короткий: `"clickhouse: acquire conn timeout"` при перегрузке или сбой соединения до того, как приостановленный сервис Cloud завершит пробуждение. Слишком длинный (> 60s): приложение зависает во время сбоев. | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Максимальное время ожидания ответа сервера для каждого вызова чтения. Применяется к каждому блоку, а не ко всему запросу. Приоритет имеет дедлайн контекста. | 10-30s для коротких интерактивных запросов; 5-30m для длительных аналитических запросов. | Слишком короткий: `"i/o timeout"` или `"read: connection reset by peer"` в середине запроса; сервер продолжает выполнение. Слишком длинный: разорванные соединения не обнаруживаются. | + + + Сервис ClickHouse Cloud, который некоторое время не использовался, приостанавливается и пробуждается при первом входящем соединении. Пробуждение обычно занимает несколько десятков секунд, в течение которых попытка подключения блокируется. Если `DialTimeout` меньше времени пробуждения, первый запрос после периода простоя завершается ошибкой тайм-аута подключения вместо выполнения. + + Установите `DialTimeout` в `1m`–`2m` для клиентов, которые могут первыми обратиться к приостановленному сервису. Компромисс в том, что при реальном сбое обнаружение ошибки будет медленнее — попытка подключения будет блокироваться на весь тайм-аут перед возвратом ошибки, — поэтому лучше ограничить увеличенный тайм-аут только первым подключением или использовать дедлайны контекста для отдельных запросов, чтобы ограничить сквозную задержку. + *** diff --git a/ru/integrations/language-clients/go/configuration.mdx b/ru/integrations/language-clients/go/configuration.mdx index a1d35d083..78255ea05 100644 --- a/ru/integrations/language-clients/go/configuration.mdx +++ b/ru/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: 'reference' При открытии соединения для управления поведением клиента можно использовать структуру `Options`. Доступны следующие настройки: -| Параметр | Тип | По умолчанию | Описание | -| ---------------------- | -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `Protocol` | `Protocol` | `Native` | Транспортный протокол: `Native` (TCP) или `HTTP`. См. [TCP и HTTP](#tcp-vs-http). | -| `Addr` | `[]string` | — | Срез адресов в формате `host:port`. О подключении к нескольким узлам см. [Подключение к нескольким узлам](#connecting-to-multiple-nodes). | -| `Auth` | `Auth` | — | Учетные данные для аутентификации (`Database`, `Username`, `Password`). См. [Аутентификация](#authentication). | -| `TLS` | `*tls.Config` | `nil` | Настройка TLS. Значение, отличное от `nil`, включает TLS. См. [TLS](#using-tls). | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Пользовательская функция dial для управления установкой TCP-соединений. | -| `DialTimeout` | `time.Duration` | `30s` | Максимальное время ожидания при открытии нового соединения. | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Максимальное число одновременно открытых соединений. | -| `MaxIdleConns` | `int` | `5` | Количество бездействующих соединений, сохраняемых в пуле. | -| `ConnMaxLifetime` | `time.Duration` | `1h` | Максимальное время жизни соединения в пуле. См. [Пул соединений](#connection-pooling). | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Стратегия выбора узла из `Addr`. См. [Подключение к нескольким узлам](#connecting-to-multiple-nodes). | -| `BlockBufferSize` | `uint8` | `2` | Количество блоков, декодируемых параллельно. Более высокие значения повышают пропускную способность за счет памяти. Можно переопределить для каждого запроса через контекст. | -| `Settings` | `Settings` | — | Карта настроек ClickHouse, применяемых ко всем запросам. Отдельные запросы могут переопределять их через [контекст](/ru/integrations/language-clients/go/clickhouse-api#using-context). | -| `Compression` | `*Compression` | `nil` | Сжатие на уровне блоков. См. [Сжатие](#compression). | -| `ReadTimeout` | `time.Duration` | — | Максимальное время ожидания чтения с сервера за один вызов. | -| `FreeBufOnConnRelease` | `bool` | `false` | Если установлено `true`, буфер памяти соединения возвращается в пул после каждого запроса. Снижает использование памяти ценой небольшой дополнительной нагрузки на CPU. | -| `Logger` | `*slog.Logger` | `nil` | Структурированный логгер (Go `log/slog`). См. [Логирование](#logging). | -| `Debug` | `bool` | `false` | **Устарело.** Используйте `Logger`. Включает устаревший отладочный вывод в stdout. | -| `Debugf` | `func(string, ...any)` | — | **Устарело.** Используйте `Logger`. Пользовательская функция отладочного логирования. Требует `Debug: true`. | -| `GetJWT` | `GetJWTFunc` | — | Функция обратного вызова, возвращающая JWT-токен для аутентификации в ClickHouse Cloud (только HTTPS). | -| `HttpHeaders` | `map[string]string` | — | Дополнительные HTTP-заголовки, отправляемые с каждым запросом (только HTTP-транспорт). | -| `HttpUrlPath` | `string` | — | Дополнительный путь URL, добавляемый к HTTP-запросам (только HTTP-транспорт). | -| `HttpMaxConnsPerHost` | `int` | — | Переопределяет `MaxConnsPerHost` в базовом `http.Transport` (только HTTP-транспорт). | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Пользовательская фабрика HTTP-транспорта. Транспорт по умолчанию передается для выборочного переопределения (только HTTP-транспорт). | -| `HTTPProxyURL` | `*url.URL` | — | URL HTTP-прокси для всех запросов (только HTTP-транспорт). | +| Параметр | Тип | По умолчанию | Описание | +| ---------------------- | -------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Protocol` | `Protocol` | `Native` | Транспортный протокол: `Native` (TCP) или `HTTP`. См. [TCP и HTTP](#tcp-vs-http). | +| `Addr` | `[]string` | — | Срез адресов в формате `host:port`. О подключении к нескольким узлам см. [Подключение к нескольким узлам](#connecting-to-multiple-nodes). | +| `Auth` | `Auth` | — | Учетные данные для аутентификации (`Database`, `Username`, `Password`). См. [Аутентификация](#authentication). | +| `TLS` | `*tls.Config` | `nil` | Настройка TLS. Значение, отличное от `nil`, включает TLS. См. [TLS](#using-tls). | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Пользовательская функция dial для управления установкой TCP-соединений. | +| `DialTimeout` | `time.Duration` | `30s` | Максимальное время ожидания при открытии нового соединения. Увеличьте до `1m`–`2m` при подключении к сервису ClickHouse Cloud, который может находиться в неактивном состоянии — см. [Тайм-ауты](/ru/integrations/language-clients/go/config-reference#timeouts). | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Максимальное число одновременно открытых соединений. | +| `MaxIdleConns` | `int` | `5` | Количество бездействующих соединений, сохраняемых в пуле. | +| `ConnMaxLifetime` | `time.Duration` | `1h` | Максимальное время жизни соединения в пуле. См. [Пул соединений](#connection-pooling). | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | Стратегия выбора узла из `Addr`. См. [Подключение к нескольким узлам](#connecting-to-multiple-nodes). | +| `BlockBufferSize` | `uint8` | `2` | Количество блоков, декодируемых параллельно. Более высокие значения повышают пропускную способность за счет памяти. Можно переопределить для каждого запроса через контекст. | +| `Settings` | `Settings` | — | Карта настроек ClickHouse, применяемых ко всем запросам. Отдельные запросы могут переопределять их через [контекст](/ru/integrations/language-clients/go/clickhouse-api#using-context). | +| `Compression` | `*Compression` | `nil` | Сжатие на уровне блоков. См. [Сжатие](#compression). | +| `ReadTimeout` | `time.Duration` | — | Максимальное время ожидания чтения с сервера за один вызов. | +| `FreeBufOnConnRelease` | `bool` | `false` | Если установлено `true`, буфер памяти соединения возвращается в пул после каждого запроса. Снижает использование памяти ценой небольшой дополнительной нагрузки на CPU. | +| `Logger` | `*slog.Logger` | `nil` | Структурированный логгер (Go `log/slog`). См. [Логирование](#logging). | +| `Debug` | `bool` | `false` | **Устарело.** Используйте `Logger`. Включает устаревший отладочный вывод в stdout. | +| `Debugf` | `func(string, ...any)` | — | **Устарело.** Используйте `Logger`. Пользовательская функция отладочного логирования. Требует `Debug: true`. | +| `GetJWT` | `GetJWTFunc` | — | Функция обратного вызова, возвращающая JWT-токен для аутентификации в ClickHouse Cloud (только HTTPS). | +| `HttpHeaders` | `map[string]string` | — | Дополнительные HTTP-заголовки, отправляемые с каждым запросом (только HTTP-транспорт). | +| `HttpUrlPath` | `string` | — | Дополнительный путь URL, добавляемый к HTTP-запросам (только HTTP-транспорт). | +| `HttpMaxConnsPerHost` | `int` | — | Переопределяет `MaxConnsPerHost` в базовом `http.Transport` (только HTTP-транспорт). | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | Пользовательская фабрика HTTP-транспорта. Транспорт по умолчанию передается для выборочного переопределения (только HTTP-транспорт). | +| `HTTPProxyURL` | `*url.URL` | — | URL HTTP-прокси для всех запросов (только HTTP-транспорт). | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/ru/products/cloud/guides/index.mdx b/ru/products/cloud/guides/index.mdx index d855c2c24..d212623fd 100644 --- a/ru/products/cloud/guides/index.mdx +++ b/ru/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['руководства ClickHouse Cloud', 'документация' | [Управление учетной записью](/ru/products/cloud/guides/security/cloud-access-management/manage-my-account) | На этой странице описано, как принимать приглашения, управлять настройками MFA и сбрасывать пароли | | [Управление назначениями ролей в консоли SQL](/ru/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | Руководство по управлению назначениями ролей в консоли SQL | | [Управление лимитами и квотами сервисов AWS](/ru/products/bring-your-own-cloud/reference/aws-service-limits) | Квоты сервисов AWS, которые нужно проверить перед онбордингом BYOC, способы запросить их увеличение и то, что следует отслеживать по мере масштабирования сервисов | -| [Миграция с CMEK v1 на v2](/ru/products/cloud/guides/security/cmek-migration) | Инструкции по миграции с устаревшего CMEK на версию 2 | | [Мультитенантность](/ru/products/cloud/guides/best-practices/multitenancy) | Рекомендации по реализации мультитенантности | | [Оптимизация диалогов агента ClickHouse Assistant с помощью семантического слоя](/ru/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | Руководство по использованию AGENTS.md для передачи агенту чата ClickHouse Assistant пользовательской бизнес-логики и инструкций, специфичных для данных | | [Обзор](/ru/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | Разверните ClickHouse в собственной облачной инфраструктуре | diff --git a/ru/products/cloud/guides/security/cmek-migration.mdx b/ru/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index 51313e13d..000000000 --- a/ru/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: 'Миграция с устаревшего CMEK' -slug: /cloud/security/cmek-migration -title: 'Миграция с CMEK v1 на v2' -description: 'Инструкции по миграции с устаревшего CMEK на версию 2' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', 'шифрование', 'CMEK'] ---- - -Мы повышаем безопасность сервисов с ключами шифрования, управляемыми клиентом (CMEK). Теперь для каждого сервиса настраивается уникальная роль AWS, которая авторизует использование клиентских ключей для шифрования и расшифровки данных сервиса. Эта новая роль отображается только на экране конфигурации сервиса. - -Для этого нового процесса поддерживаются OpenAPI и Terraform. Подробнее см. в нашей документации ([Улучшенное шифрование](/ru/products/cloud/guides/security/cmek), [Cloud API](/ru/products/cloud/features/admin-features/api/api-overview), [Официальный Terraform-провайдер](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)). - - - Клиенты, использующие CMEK v1, должны выполнить миграцию сервисов не позднее 1 июня 2026 года. После этой даты ключи, управляемые клиентом, по умолчанию будут заменены на ключи, управляемые ClickHouse. После такой миграции клиенты смогут снова перейти на ключи, управляемые клиентом. - - -
- ## Ручная миграция -
- -Выполните следующие шаги, чтобы перейти на новую процедуру: - -1. Войдите в https://console.clickhouse.cloud -2. Нажмите на сервис с включённым шифрованием -3. Выберите слева Service Settings -4. Прокрутите страницу вниз и раскройте View service details -5. Скопируйте Encryption Role ID (IAM) -6. Перейдите к своему ключу KMS в AWS и обновите Key Policy, добавив следующее: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. В ClickHouse Cloud создайте обращение в поддержку, чтобы сообщить нам, что можно включить новый метод. Это изменение требует перезапуска сервиса, поэтому, пожалуйста, сообщите, есть ли предпочтительный день/время для перезапуска сервиса. -8. После того как мы перезапустим сервис, перейдите к своему ключу KMS в AWS и удалите следующее из Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. Обновление завершено! - -
- ## Миграция Terraform -
- -1. Обновите Terraform до [версии 3.5.0 или выше](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) -2. Примените Terraform без изменений. В состоянии Terraform появится новое поле `transparent_data_encryption`. Запишите `role_id`. -3. Перейдите к своему ключу KMS в AWS и обновите Key Policy, добавив следующее: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. В ClickHouse Cloud откройте обращение в поддержку, указав имя сервиса, чтобы сообщить нам, что мы можем включить новый метод. Это изменение требует перезапуска сервиса, поэтому, пожалуйста, сообщите, есть ли день/время, когда сервис лучше всего перезапустить. -5. После того как мы перезапустим сервис, вы сможете обновить настройку transparent_data_encryption.enabled до ‘True’, удалить настройку tier в Terraform и выполнить apply. Это не приведет ни к каким изменениям. -6. Перейдите к своему ключу KMS в AWS и удалите следующее из Key Policy: - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. Обновление завершено! \ No newline at end of file diff --git a/ru/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/ru/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index 333e9be10..190401870 100644 --- a/ru/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/ru/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ import ScalePlanFeatureBadge from "/snippets/components/ScalePlanFeatureBadge/Sc * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 diff --git a/ru/products/cloud/navigation.json b/ru/products/cloud/navigation.json index 630a3318e..40039e52b 100644 --- a/ru/products/cloud/navigation.json +++ b/ru/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "ru/products/cloud/guides/security/data-masking", - "ru/products/cloud/guides/security/cmek", - "ru/products/cloud/guides/security/cmek-migration" + "ru/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "ru/_specs/cloud-openapi.json" } ] }, diff --git a/ru/products/kubernetes-operator/guides/configuration.mdx b/ru/products/kubernetes-operator/guides/configuration.mdx index b07a9db52..a2ddf84e3 100644 --- a/ru/products/kubernetes-operator/guides/configuration.mdx +++ b/ru/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: Настройте CPU и память для контейнеров ClickHouse: ```yaml -# значения по умолчанию +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -318,9 +318,13 @@ spec:
- ## Настройка TLS/SSL + ## Конфигурация TLS/SSL
+Полный пример — выпуск сертификатов с помощью cert-manager, подключение +клиентов через защищённые порты и шифрование трафика Keeper — см. в руководстве +[Защита с помощью TLS](/ru/products/kubernetes-operator/guides/tls). +
### Настройка защищённых конечных точек
@@ -371,6 +375,323 @@ spec: key: ``` +
+ ## External Secret +
+ +По умолчанию оператор создает Secret с внутренними учетными данными кластера и управляет им (межсерверный пароль, пароль управления, идентификатор Keeper, секрет кластера, ключ named-collections). Secret получает имя кластера и находится в его пространстве имен. + +Если вы хотите управлять этими учетными данными самостоятельно — например, получать их из HashiCorp Vault, AWS Secrets Manager или [External Secrets Operator](https://external-secrets.io/) — укажите оператору уже существующий Secret с помощью `spec.externalSecret`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + Указанный Secret должен находиться в **том же пространстве имен**, что и ClickHouseCluster. Оператор никогда не удаляет Secret, если не создавал его сам. + + +
+ ### Обязательные ключи +
+ +Secret должен содержать следующие ключи: + +| Ключ | Формат | Когда требуется | +| ----------------------- | --------------------------------------------------------------------------- | -------------------------------- | +| `interserver-password` | пароль в открытом виде | Всегда | +| `management-password` | пароль в открытом виде | Всегда | +| `keeper-identity` | `clickhouse:` | Всегда | +| `cluster-secret` | пароль в открытом виде | Всегда | +| `named-collections-key` | 16-байтный ключ AES в шестнадцатеричном виде (32 шестнадцатеричных символа) | Только для ClickHouse `>= 25.12` | + +Полный Secret выглядит так: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### Политика: Observe или Manage +
+ +`spec.externalSecret.policy` определяет, как оператор обрабатывает отсутствие обязательных ключей: + +| Политика | Поведение при отсутствии ключей | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Observe` (по умолчанию) | Реконсиляция **блокируется**, пока не появятся все обязательные ключи. Оператор сообщает о каждом отсутствующем ключе — и подсказке по его формату — через условие `ExternalSecretValid` (с причиной `ExternalSecretInvalid`) и событие `Warning`. | +| `Manage` | Оператор **генерирует** все отсутствующие обязательные ключи и записывает их обратно в тот же Secret. Полезно для начальной инициализации: создайте пустой Secret, позвольте оператору заполнить его, а затем при необходимости ограничьте доступ. При этом оператор по-прежнему никогда не удаляет Secret. | + + + Даже при `policy: Manage` Secret уже должен существовать в пространстве имен — оператор никогда не создает сам Secret, а только записывает сгенерированные ключи в уже существующий. Если указанный Secret отсутствует, реконсиляция блокируется с причиной `ExternalSecretNotFound` независимо от политики. + + +Выбирайте `Observe`, если внешний источник (Vault, ESO, sealed-secrets, GitOps) является источником истины и вы хотите, чтобы оператор явно сигнализировал об ошибке конфигурации. Выбирайте `Manage`, если вам нужна самодостаточная начальная инициализация, но при этом вы хотите сохранить контроль над самим объектом Secret (например, чтобы делать его резервную копию). + +
+ ### Состояние и устранение неполадок +
+ +Оператор выставляет состояние `ExternalSecretValid` в `ClickHouseCluster.status.conditions`. Проверьте его, если кажется, что реконсиляция зависла: + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +Возможные причины: + +| `reason` | Значение | Исправление | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| `ExternalSecretNotFound` | Указанный Secret не существует в пространстве имен. | Создайте Secret или исправьте `spec.externalSecret.name`. | +| `ExternalSecretInvalid` | Secret существует, но в нем отсутствуют обязательные ключи (только при `Observe`). В сообщении перечислены все отсутствующие ключи и ожидаемый для них формат. | Добавьте отсутствующие ключи или переключитесь на `policy: Manage`. | +| `ExternalSecretValid` | Все обязательные ключи присутствуют, и оператор использует этот Secret. | — | + +Пока Secret недействителен, оператор повторно ставит реконсиляцию в очередь, поэтому после добавления отсутствующих ключей следующая реконсиляция автоматически их подхватит — перезапускать поды не нужно. + + + Набор обязательных ключей зависит от запущенной версии ClickHouse. `named-collections-key` проверяется только после того, как проверка версии оператора обнаружит ClickHouse `25.12` или новее. В более старых версиях этот ключ может отсутствовать в Secret. + + +
+ ## Дополнительные порты +
+ +Оператор предоставляет фиксированный набор портов на каждом поде ClickHouse и в его headless Service: `8123` HTTP, `9000` native, `9009` interserver, `9001` management, `9363` метрики Prometheus, а также варианты с TLS `8443`/`9440`, если TLS включен. Чтобы ClickHouse прослушивал дополнительные протоколы — MySQL, PostgreSQL, gRPC — или любой пользовательский порт, объявите их в `spec.additionalPorts`: + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +Оператор добавляет эти порты в `containerPorts` пода и в headless Service. Полный пример приведён в [`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml). + + + `additionalPorts` открывает порты только на стороне Kubernetes. Он **не** настраивает сервер ClickHouse на прослушивание этих портов. Также нужно включить соответствующий протокол в `spec.settings.extraConfig.protocols`. Иначе порт будет открыт на Service, но внутри пода на нём ничего не будет отвечать. + + +
+ ### Полный пример: протокол MySQL +
+ +Чтобы предоставить доступ к ClickHouse по протоколу MySQL на порту `9004`: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +После применения проверьте, находясь внутри кластера: + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### Ограничения для полей +
+ +| Поле | Правило | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Должно соответствовать шаблону регулярного выражения DNS_LABEL `^[a-z]([-a-z0-9]*[a-z0-9])?$`; максимальная длина — 63 символа. Уникальность обеспечивается CRD за счёт ключа list-map. | +| `port` | Целое число в диапазоне `[1, 65535]`. вебхук отклоняет повторяющиеся номера портов в пределах списка. | + +
+ ### Зарезервированные порты и имена +
+ +Валидирующий вебхук отклоняет записи `additionalPorts`, которые пересекаются с портами, используемыми самим оператором. Все порты, связанные с TLS, зарезервированы **безусловно**, чтобы последующее включение `spec.settings.tls.enabled` не нарушило работу ранее корректного кластера. + +| Порт | Зарезервирован для | +| ------ | ------------------ | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | нативный TCP | +| `9440` | нативный TLS | +| `9009` | interserver | +| `9001` | management | +| `9363` | метрики Prometheus | + +Следующие имена также отклоняются — это внутренние идентификаторы типов протоколов оператора (а не человекочитаемые псевдонимы): + +| Имя | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +Отклонённый запрос приводит к ошибке вида: + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## Проверка версии и канал обновления +
+ +Оператор выполняет две независимые функции, связанные с версиями кластера: + +1. **Проверка версии** — Kubernetes `Job`, который однократно запускает контейнерный образ, чтобы определить версию ClickHouse / Keeper. Определённая версия записывается в `.status.version` и используется другими этапами реконсиляции (например, ключ named-collections для `External Secret` требуется только начиная с ClickHouse `25.12`). +2. **Канал обновления** — периодическая проверка публичной ленты релизов ClickHouse (`https://clickhouse.com/data/version_date.tsv`). Оператор сообщает о наличии более новой версии через условие состояния `VersionUpgraded`. Самостоятельно кластер он никогда не обновляет — тег образа контролирует пользователь. + +
+ ### Выбор канала обновления +
+ +`spec.upgradeChannel` задаёт, с каким набором апстримных релизов сверяется оператор. Такое же поле есть и в `ClickHouseCluster`, и в `KeeperCluster`. + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +Допустимые значения (проверяются CRD по шаблону `^(lts|stable|\d+\.\d+)?$`): + +| Значение | Поведение | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| *empty* (default) | Оператор предлагает только **минорные** обновления в пределах текущей ветки major.minor. Кластеру на `25.8.3.1` будет предложено `25.8.4.x`, но не `25.9.x`. | +| `stable` | Отслеживает вышестоящий канал `stable` — последний релиз, который ClickHouse Inc. помечает как стабильный в основной ветке релизов. Получает мажорные обновления раньше, чем канал `lts`. | +| `lts` | Отслеживает вышестоящий канал `lts` — релизы с долгосрочной поддержкой. Получает мажорные обновления реже, а окна поддержки у них дольше. | +| `25.8` (или любой `.`) | Закрепляет канал за конкретной веткой major.minor. Мажорные обновления за её пределами не предлагаются, даже если вышестоящая версия новее. | + +Для продакшн обычно предпочтительнее явно закрепить канал на значении `.` (например, `25.8`). Это фиксирует кластер на нужной ветке мажорных релизов и позволяет оператору выдавать предупреждение `WrongReleaseChannel`, если какая-либо реплика по какой-то причине перейдёт на другой мажорный релиз, — что особенно важно, когда image указан по дайджесту (`@sha256:...`), а не по человекочитаемому тегу. Пустое значение по умолчанию подходит для Development-clusters, где переходы между мажорными версиями не критичны. + +
+ ### Состояния +
+ +Два состояния показывают результат проверки версии и проверки обновления: + +| Состояние | Причина | Значение | +| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionInSync` | `VersionMatch` | Все реплики сообщают ту же версию, что и образ | +| `VersionInSync` | `VersionMismatch` | Реплики работают на разных версиях. Предупреждающее событие подавляется во время запланированного поэтапного обновления. Обычно это происходит, когда закреплён изменяемый тег образа (например, `latest` или просто мажорная версия, такая как `26.3`), а содержимое в реестре между загрузками изменилось, поэтому разные реплики оказались на разных патч-версиях одного и того же тега. | +| `VersionInSync` | `VersionPending` | Задача проверки версии ещё не завершилась | +| `VersionInSync` | `VersionProbeFailed` | Задача probe завершилась с ошибкой; оператор не может определить запущенную версию | +| `VersionUpgraded` | `UpToDate` | Кластер использует последнюю версию, доступную в выбранном канале | +| `VersionUpgraded` | `MinorUpdateAvailable` | В той же ветке `major.minor` доступен более новый патч | +| `VersionUpgraded` | `MajorUpdateAvailable` | В рамках выбранного канала доступна более новая версия `major.minor` | +| `VersionUpgraded` | `VersionOutdated` | Запущенная версия устарела и больше не будет получать исправления из выбранного канала — обычно потому, что эта мажорная ветка больше не поддерживается в upstream `lts` или `stable` | +| `VersionUpgraded` | `WrongReleaseChannel` | Запущенный образ не относится к выбранному `upgradeChannel`. Пример: кластер работает на `26.5` с `upgradeChannel: lts`, поскольку `26.5` не входит в upstream-ветку `lts`. | +| `VersionUpgraded` | `UpgradeCheckFailed` | Оператор не смог получить доступ к upstream-источнику сведений о релизах | + +Проверьте их с помощью: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### Переопределение Job проверки версии +
+ +Проверка реализована как обычный Kubernetes `Job`. Если в вашем кластере действуют политики допуска, требующие определённых Tolerations, селекторов узлов или контекстов безопасности, либо вы хотите ограничить время, в течение которого завершённые Job проверки остаются в системе, переопределите шаблон через `spec.versionProbeTemplate`: + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +Имя контейнера `version-probe` задано в операторе по умолчанию — запись в `containers:` совпадает с ним по имени, поэтому оператор выполняет глубокое слияние пользовательских полей со значениями по умолчанию. + +
+ ### Глобальные настройки оператора +
+ +Два флага в менеджере оператора глобально управляют циклом проверки обновлений: + +| Флаг | По умолчанию | Эффект | +| --------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | Как часто оператор повторно получает список версий из внешнего источника | +| `--disable-version-update-checks` | `false` | Полностью отключает проверку обновлений. Условие `VersionUpgraded` не устанавливается, и исходящий HTTP-трафик на `clickhouse.com` не создаётся | + +Установите `--disable-version-update-checks=true` в полностью изолированных средах или если исходящий трафик на `clickhouse.com` не разрешён. +
## Настройки ClickHouse
@@ -485,6 +806,49 @@ spec: Когда эта настройка включена, оператор синхронизирует таблицы Replicated и интеграционные таблицы на новые реплики. +
+ ### Логирование сервера +
+ +Настройте логирование сервера ClickHouse через `spec.settings.logger`. Все поля необязательны и имеют безопасные значения по умолчанию, поэтому даже кластер, который вы ни разу не изменяли, уже пишет журналы уровня `trace` и в консоль контейнера, и в ротируемый файл на диске. + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| Поле | По умолчанию | Описание | +| ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `logToFile` | `true` | Если `false`, оператор отключает вывод в файлы, и сервер пишет журнал только в консоль контейнера. | +| `jsonLogs` | `false` | Если `true`, оператор добавляет `formatting.type: json`, так что каждая строка становится объектом JSON. | +| `level` | `trace` | Уровень подробности журнала. Один из `test`, `trace`, `debug`, `information`, `notice`, `warning`, `error`, `critical`, `fatal`. | +| `size` | `1000M` | Максимальный размер одного файла журнала до ротации. | +| `count` | `50` | Количество файлов журнала после ротации, которые сервер сохраняет. | + +Оператор всегда оставляет логирование в консоль включённым, чтобы работал `kubectl logs`, а при `logToFile` со значением `true` дополнительно включает файловый журнал. В кластере с настройками по умолчанию получается такой блок `logger`: + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +Тот же блок `spec.settings.logger` применяется и к `KeeperCluster`; в этом случае оператор записывает файлы в каталог `/var/log/clickhouse-keeper/`. + + + Вывод в консоль остается включенным независимо от `logToFile`, поэтому `kubectl logs` продолжает работать, даже если вы отключите логирование в файл. Установите `jsonLogs: true`, если отправляете журналы в систему хранения структурированных журналов, которая разбирает JSON. + +
## Пользовательская конфигурация
diff --git a/ru/products/kubernetes-operator/guides/introduction.mdx b/ru/products/kubernetes-operator/guides/introduction.mdx index 9ad470724..d0c2b37bb 100644 --- a/ru/products/kubernetes-operator/guides/introduction.mdx +++ b/ru/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: Чтобы полностью удалить хранилище: ```bash -# Удалить кластер +# Delete cluster kubectl delete clickhousecluster my-cluster -# Дождаться завершения подов -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# Удалить PVC -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/ru/products/kubernetes-operator/guides/monitoring.mdx b/ru/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..01567c5bc --- /dev/null +++ b/ru/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,420 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: Мониторинг ClickHouse Operator +keywords: ['kubernetes', 'prometheus', 'мониторинг', 'метрики'] +description: 'Как собирать, защищать и использовать метрики оператора и конечные точки проверки работоспособности.' +doc_type: 'guide' +--- + +Оператор предоставляет совместимые с Prometheus метрики и пробы работоспособности Kubernetes, чтобы вы могли отслеживать процесс его реконсиляции, обнаруживать зависшие контроллеры и настраивать оповещения о сбоях. + +В этом руководстве описано, какие данные предоставляет оператор, как их собирать и какие запросы полезны в повседневной работе. + + + Это руководство посвящено **самому процессу оператора** (controller manager). Для метрик ClickHouse server (запросы, части, задержка репликации) используйте [конечную точку Prometheus в ClickHouse](/ru/reference/settings/server-settings/settings#prometheus), чтобы собирать их отдельно. + + +
+ ## Конечные точки +
+ +Процесс оператора предоставляет две HTTP-конечные точки в поде manager: + +| Конечная точка | Порт по умолчанию | Путь | Назначение | +| ------------------ | ------------------------------------------------------------------ | --------------------- | ------------------------------------------ | +| Метрики | `8080` (Helm) / `0` — отключено (по умолчанию для бинарного файла) | `/metrics` | Формат экспозиции Prometheus | +| Проверка состояния | `8081` | `/healthz`, `/readyz` | Проверки работоспособности и готовности в Kubernetes | + +Конечная точка метрик **по умолчанию отключена**, если запускать бинарный файл оператора напрямую (`--metrics-bind-address=0`). Helm-чарт включает её с помощью `metrics.enable: true` и `metrics.port: 8080`. + +Конечная точка проверки состояния всегда включена; шаблон развертывания связывает `/healthz` и `/readyz` с проверками работоспособности и готовности пода на порту `8081`. + +
+ ## Флаги бинарного файла оператора +
+ +Соответствующие флаги `manager` (определены в [`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go)): + +| Flag | Default | Description | +| ----------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--metrics-bind-address` | `0` (отключено) | Адрес привязки для конечной точки метрик. Укажите `:8443` для HTTPS или `:8080` для HTTP. Оставьте `0`, чтобы отключить сервер метрик. | +| `--metrics-secure` | `true` | Отдавать метрики по HTTPS с аутентификацией и авторизацией. Установите `false`, чтобы использовать обычный HTTP. | +| `--metrics-cert-path` | пусто | Каталог с файлами TLS-сертификата (`tls.crt`, `tls.key`) для сервера метрик. | +| `--metrics-cert-name` | `tls.crt` | Имя файла сертификата внутри `--metrics-cert-path`. | +| `--metrics-cert-key` | `tls.key` | Имя файла ключа внутри `--metrics-cert-path`. | +| `--enable-http2` | `false` | Включить HTTP/2 для серверов метрик **и вебхука**. По умолчанию отключено для снижения риска CVE-2023-44487 / CVE-2023-39325. | +| `--leader-elect` | `false` (бинарный файл) / `true` (Helm-чарт) | Включить выбор лидера, чтобы в каждый момент времени только одна реплика выполняла сверку состояния. Helm-чарт по умолчанию задаёт этот флаг в `manager.args`. | +| `--health-probe-bind-address` | `:8081` | Адрес привязки для `/healthz` и `/readyz`. | + + + Соглашение `8443` (HTTPS) / `8080` (HTTP) в тексте справки для флага — лишь подсказка. Helm-чарт обслуживает HTTPS на `8080`, потому что задаёт и `metrics.port: 8080`, и `metrics.secure: true`. Автоопределения режима по порту нет — HTTP или HTTPS выбирается через `--metrics-secure`. + + +
+ ## Включение метрик через Helm +
+ +Чарт уже создаёт `Service` для порта метрик и, при необходимости, `ServiceMonitor` для prometheus-operator. + +Сама конечная точка метрик включена по умолчанию (`metrics.enable: true`, порт `8080`, доступна по HTTPS через `metrics.secure: true`). Обычно достаточно изменить только параметр `prometheus.enable`, чтобы чарт создал `ServiceMonitor` за вас: + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +Если вы не используете cert-manager, дополнительно задайте `certManager.enable: false`, и тогда ServiceMonitor будет собирать метрики с `insecureSkipVerify: true`, полагаясь только на аутентификацию по bearer-токену. + +Полный набор связанных с метриками значений по умолчанию: + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +Применить: + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +После установки чарт создаёт: + +* `Service/-metrics-service` — предоставляет порт `8080` (HTTPS, если `metrics.secure: true`). +* `ServiceMonitor/-controller-manager-metrics-monitor` — если `prometheus.enable: true`. +* `ClusterRole/-metrics-reader` — нересурсный URL `/metrics` с правом `get`. + +
+ ## Защита конечной точки метрик +
+ +Если задано `metrics.secure: true`, сервер метрик требует TLS **и** аутентификацию/авторизацию Kubernetes при каждом опросе. Scraper'ы должны: + +1. Предъявлять действительный Kubernetes Bearer-токен. +2. Использовать ServiceAccount, привязанный к РольКластера, которая предоставляет `get` для нересурсного URL `/metrics`. + +В chart входит такая РольКластера: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +Привяжите его к ServiceAccount, который использует ваш скрейпер (обычно Prometheus): + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + Если вы видите `401 Unauthorized` или `403 Forbidden` от конечной точки метрик, значит, сборщик использует HTTPS, но у него отсутствует Bearer-токен Kubernetes или нет прав на его использование, либо у его ServiceAccount нет привязки, указанной выше. Отключать защиту, установив `metrics.secure: false`, **не рекомендуется** в общих кластерах, поскольку любой, у кого есть сетевой доступ к поду, сможет собирать метрики с этой конечной точки. + + +
+ ## Справочник по ServiceMonitor +
+ +Чарт создаёт ServiceMonitor следующего вида, если `prometheus.enable: true`: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +Если в вашем экземпляре Prometheus не запущен cert-manager, установите `tlsConfig.insecureSkipVerify: true` и используйте только аутентификацию по bearer-токену — чарт уже делает это, когда `certManager.enable: false`. + +
+ ## Автономный пример Prometheus +
+ +Если вы не используете kube-prometheus-stack, в репозитории доступен автономный пример: [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml). Он создаёт ServiceAccount, необходимые объекты RBAC и ресурс `Prometheus` (CR), который выбирает ServiceMonitor оператора. + +
+ ## Конечные точки проверки состояния +
+ +| Path | Используется для | Возвращает | +| ---------- | ------------------------------------- | --------------------------------------------- | +| `/healthz` | проверки работоспособности Kubernetes | `200 OK`, пока сервер проб прослушивает порт. | +| `/readyz` | проверки готовности Kubernetes | `200 OK`, пока сервер проб прослушивает порт. | + +Обе конечные точки регистрируются с одной и той же простой ping-проверкой (`healthz.Ping` из `sigs.k8s.io/controller-runtime`). Поэтому сбой пробы означает "процесс manager не обслуживает HTTP на `:8081`", а не "с контроллерами что-то не так". Чтобы выявлять проблемы на уровне контроллеров, используйте вместо этого [метрики реконсиляции](#reconciliation-activity). + +Обе конечные точки по умолчанию доступны на порту `8081`. Они подключены к развертыванию следующим образом: + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +Постоянно завершающаяся с ошибкой probe обычно означает, что сам probe-сервер так и не запустился — например, менеджер завершил работу на раннем этапе запуска. Проверьте журналы менеджера на наличие `unable to start manager`, сбоев RBAC или ошибок `cache did not sync`. + +
+ ## Каталог метрик +
+ +Оператор не регистрирует пользовательские коллекторы Prometheus. Всё перечисленное ниже экспортируется библиотеками `controller-runtime` и `client-go`, лежащими в основе оператора. Ниже приведены наиболее полезные серии, сгруппированные по назначению: + +
+ ### Активность реконсиляции +
+ +| Метрика | Тип | Метки | +| -------------------------------------------------- | --------- | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | counter | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | counter | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | histogram | `controller` | +| `controller_runtime_active_workers` | gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | gauge | `controller` | + +Метка `controller` определяется в `controller-runtime` на основе типа ресурса, зарегистрированного через `For(...)`. В текущем коде в `internal/controller/clickhouse` и `internal/controller/keeper` это будут `clickhousecluster` и `keepercluster` соответственно. Если вы изменяли оператор, проверьте это с помощью однократного сбора `/metrics`. + +
+ ### Рабочая очередь +
+ +| Метрика | Тип | Метки | +| --------------------------------------------- | --------- | -------------------------------- | +| `workqueue_depth` | gauge | `name`, `controller`, `priority` | +| `workqueue_adds_total` | counter | `name`, `controller` | +| `workqueue_retries_total` | counter | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | gauge | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | gauge | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | histogram | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | histogram | `name`, `controller` | + +Метки `name` и `controller` имеют одно и то же значение (имя контроллера). + +
+ ### Трафик API-сервера +
+ +| Метрика | Тип | Метки | +| ---------------------------- | ------- | ------------------------ | +| `rest_client_requests_total` | Counter | `code`, `method`, `host` | + +
+ ### Выбор лидера +
+ +| Метрика | Тип | Метки | +| ------------------------------- | ----- | ------------------------------------ | +| `leader_election_master_status` | gauge | `name` (= `d4ceba06.clickhouse.com`) | + +В Helm-чарте флаг `--leader-elect` включён по умолчанию, поэтому эта метрика присутствует в стандартных установках через Helm. При запуске бинарного файла напрямую без этого флага метрика отсутствует. + +
+ ### Среда выполнения +
+ +Стандартные коллекторы метрик процесса Go и среды выполнения — `go_goroutines`, `go_memstats_*`, `process_cpu_seconds_total`, `process_resident_memory_bytes` и т. д. + +
+ ## Полезные запросы PromQL +
+ +
+ ### Обзор состояния +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### Выявление накопления очереди +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### Троттлинг и нагрузка на API +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### Статус лидера (HA-развертывание) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## Рекомендуемые оповещения +
+ +Отправная точка для PrometheusRule (настройте пороговые значения под свою среду): + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +Последнее правило имеет смысл, только если включен механизм выбора лидера. + +
+ ## Проверка установки +
+ +Краткая сквозная проверка, если чарт установлен в `clickhouse-operator-system`: + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +Если при скрейпинге возвращаются метрики в формате экспозиции Prometheus, конечная точка и RBAC настроены правильно. + + + +* [Установка](/ru/products/kubernetes-operator/install/helm) — значения Helm для мониторинга. +* [Конфигурация](/ru/products/kubernetes-operator/guides/configuration) — настройка TLS, общая с сервером метрик. \ No newline at end of file diff --git a/ru/products/kubernetes-operator/guides/scaling.mdx b/ru/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..eb8377c5f --- /dev/null +++ b/ru/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,109 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: Масштабирование кластеров +keywords: ['kubernetes', 'масштабирование', 'реплики', 'сегменты', 'keeper', 'кворум'] +description: 'Как масштабировать реплики и сегменты ClickHouse, а также участников кворума Keeper, и что оператор делает автоматически.' +doc_type: 'guide' +--- + +Чтобы масштабировать кластер, измените количество реплик и сегментов в пользовательском ресурсе. Оператор приводит работающий кластер к новой топологии: создает или удаляет StatefulSet для каждой реплики, синхронизирует схему и отражает ход выполнения в состояниях статуса. + +В этом руководстве описано, как масштабировать реплики и сегменты `ClickHouseCluster`, как безопасно масштабировать кворум `KeeperCluster` и за какими состояниями нужно следить во время операции масштабирования. + + + Для `ClickHouseCluster` всегда требуется Keeper, на который ссылается обязательное поле `spec.keeperClusterRef` — оператор координирует кластер через него независимо от размера. Чтобы запускать более одной реплики на сегмент, данные также должны храниться в таблицах `ReplicatedMergeTree`, поскольку именно репликация позволяет второй реплике обслуживать те же строки. + + +
+ ## Масштабирование реплик +
+ +`spec.replicas` задаёт количество реплик в каждом сегменте. Каждая реплика запускается в собственном StatefulSet с именем `-clickhouse--`, поэтому в кластере с `shards: 2` и `replicas: 3` будет запущено шесть StatefulSets. + +Увеличьте или уменьшите это количество прямо в существующей конфигурации: + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +При масштабировании вверх оператор создает новые StatefulSets для каждой реплики, ждет, пока каждый под перейдет в состояние Ready, а затем синхронизирует схему с новыми репликами (см. [Автоматическая синхронизация схемы](#automatic-schema-sync)). При масштабировании вниз он удаляет лишние StatefulSets и очищает устаревшие записи о репликах реплицируемой базы данных, оставшиеся после удаления реплик. + +
+ ## Масштабирование сегментов +
+ +`spec.shards` задаёт количество сегментов. Каждый новый сегмент добавляет полный набор StatefulSet для каждой реплики, а оператор создаёт один [PodDisruptionBudget на сегмент](/ru/products/kubernetes-operator/guides/configuration#pod-disruption-budgets), чтобы сбой в одном сегменте не учитывался при расчёте для другого. + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +Каждый сегмент хранит отдельную часть данных, и оператор не копирует и не перемещает строки между сегментами. Таблица `Distributed` или явная схема маршрутизации определяет, в какой сегмент попадёт строка, поэтому добавление сегмента просто даёт новым записям новое место для записи, не затрагивая строки, уже хранящиеся в существующих сегментах. + +
+ ## Автоматическая синхронизация схемы +
+ +Когда `spec.settings.enableDatabaseSync` имеет значение `true` (по умолчанию), оператор поддерживает согласованность схемы при изменении топологии: + +* **При масштабировании вверх** — как только готовы как минимум две реплики, оператор реплицирует определения баз данных на вновь созданные реплики, чтобы новая реплика присоединилась с теми же базами данных `Replicated` и базами данных интеграций, что и остальные узлы кластера. +* **При масштабировании вниз** — прежде чем реплика исчезнет, оператор удаляет регистрацию этой реплики из каждой базы данных `Replicated` с помощью `SYSTEM DROP DATABASE REPLICA`, чтобы уменьшенный кластер не ожидал реплику базы данных `Replicated`, которой больше не существует. + +Это относится к базам данных `Replicated` и движкам баз данных интеграций. Табличные данные при этом не перемещаются — данные строк хранятся в таблицах `ReplicatedMergeTree` и реплицируются через Keeper независимо от этой синхронизации схемы. Если готова только одна реплика, реплицировать некуда, поэтому оператор пропускает этот шаг и записывает в журнал, что целевой реплики нет. + +Установите `enableDatabaseSync: false`, чтобы отключить это поведение, например если за распространение схемы отвечает внешний инструмент. В этом случае оператор указывает причину `SchemaSyncDisabled` в условии `SchemaInSync`. + +
+ ## Состояния, за которыми стоит следить +
+ +Проверяйте состояние пользовательского ресурса во время операции масштабирования: + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| Условие | Причина | Значение | +| -------------------- | ---------------------- | ------------------------------------------------------------------------- | +| `ClusterSizeAligned` | `UpToDate` | Число запущенных реплик соответствует запрошенной топологии | +| `ClusterSizeAligned` | `ScalingUp` | Оператор добавляет реплики | +| `ClusterSizeAligned` | `ScalingDown` | Оператор удаляет реплики | +| `SchemaInSync` | `ReplicasInSync` | Базы данных есть на всех репликах, а устаревшие метаданные удалены | +| `SchemaInSync` | `DatabasesNotCreated` | Оператор еще не завершил создание баз данных на новых репликах | +| `SchemaInSync` | `ReplicasNotCleanedUp` | Устаревшие метаданные реплик после уменьшения числа реплик еще не удалены | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync` имеет значение `false` | +| `Ready` | `AllShardsReady` | В каждом сегменте есть готовая реплика | +| `Ready` | `SomeShardsNotReady` | Как минимум в одном сегменте нет готовой реплики | + +Операция масштабирования считается завершенной, когда `ClusterSizeAligned` имеет значение `UpToDate`, `SchemaInSync` — `ReplicasInSync`, а `Ready` — `AllShardsReady`. + +
+ ## Масштабирование Keeper +
+ +`KeeperCluster` работает с RAFT-кворумом, поэтому оператор изменяет его состав **по одной реплике за раз** и только когда кластер находится в стабильном состоянии. Это защищает кворум: кластер `2F+1` допускает отказ `F` участников, поэтому кластер из 3 узлов продолжает работать при отсутствии одного участника, а кластер из 5 узлов — двух. + +```yaml +spec: + replicas: 5 # was 3 +``` + +При масштабировании вверх оператор добавляет в кворум реплику с наименьшим свободным ID; при масштабировании вниз — удаляет реплику с наибольшим ID. На каждом шаге оператор ждёт, пока кворум стабилизируется, прежде чем начинать следующий. Для [Keeper PodDisruptionBudget](/ru/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) по умолчанию задано `maxUnavailable: replicas/2`, чтобы сохранять кворум во время плановых прерываний. + +Условие `ScaleAllowed` показывает, может ли кворум изменить состав прямо сейчас: + +| Причина | Значение | +| -------------------------- | ------------------------------------------------------------------ | +| `ReadyToScale` | Кворум стабилен, и оператор может добавить или удалить участника | +| `ReplicaHasPendingChanges` | У реплики всё ещё есть ожидающее применения изменение конфигурации | +| `ReplicaNotReady` | Реплика не готова, поэтому изменение состава откладывается | +| `NoQuorum` | В кластере нет кворума, и безопасно изменить состав нельзя | +| `WaitingFollowers` | Оператор ждёт, пока followers догонят лидера | + +Масштабируйте Keeper по одному шагу и давайте `ScaleAllowed` вернуться к `ReadyToScale` между изменениями. Переход сразу на несколько участников не отменяет пошаговое согласование — оператор всё равно изменяет кворум по одному участнику за шаг. \ No newline at end of file diff --git a/ru/products/kubernetes-operator/guides/tls.mdx b/ru/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..1b4401ab2 --- /dev/null +++ b/ru/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,335 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: Защита кластера с помощью TLS +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'security', 'certificates'] +description: 'Как защитить кластер ClickHouse с помощью TLS и cert-manager, включая клиентские подключения и шифрование Keeper.' +doc_type: 'guide' +--- + +В этом руководстве пошагово показано, как настроить сквозное шифрование кластера ClickHouse: выпустить +сертификат с помощью [cert-manager](https://cert-manager.io/), включить TLS в +кластере, подключить клиент через защищённые порты и распространить шифрование на +трафик координации Keeper. + +Руководство носит практический характер. Подробное справочное описание `spec.settings.tls` по каждому полю см. в +[Configuration → TLS/SSL configuration](/ru/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +и в [API Reference](/ru/products/kubernetes-operator/reference/api-reference#clustertlsspec). + +
+ ## Предварительные требования +
+ +* Работающий кластер ClickHouse под управлением оператора (см. [Введение](/ru/products/kubernetes-operator/guides/introduction)). +* Установленный в кластере [cert-manager](https://cert-manager.io/docs/installation/). +* Доступ к пространству имен кластера через `kubectl`. + +Оператор не генерирует сертификаты самостоятельно — он использует Kubernetes +`Secret`, который вы предоставляете. cert-manager — рекомендуемый способ создать и +обновлять этот `Secret`, но подойдет любой инструмент, который записывает Secret в ожидаемом формате. + +
+ ## В каком виде оператор ожидает сертификаты +
+ +TLS включается путём указания `spec.settings.tls.serverCertSecret` на объект Secret, +который содержит три ключа: + +| Ключ Secret | Содержимое | +| ----------- | ---------------------------------------- | +| `tls.crt` | PEM-кодированный сертификат сервера | +| `tls.key` | PEM-кодированный закрытый ключ | +| `ca.crt` | PEM-кодированная цепочка CA‑сертификатов | + +Именно такую структуру cert-manager записывает для ресурса `Certificate`, поэтому +никакого преобразования не требуется. Оператор монтирует их в каждый под по пути +`/etc/clickhouse-server/tls/` и подключает к конфигурации `openSSL` в ClickHouse. + + + `serverCertSecret` **обязателен**, если `tls.enabled: true`. Валидирующий + вебхук отклоняет кластер, в котором TLS включен без него, а также отклоняет `required: true`, + если не задано `enabled: true`. + + +
+ ## Шаг 1 — Инициализируйте CA с помощью cert-manager +
+ +Наиболее воспроизводимый вариант настройки — самоподписанный центр сертификации (CA), который затем подписывает сертификат сервера. +Это даёт вам стабильный `ca.crt`, которому могут доверять клиенты. + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +В продакшне замените самоподписанный bootstrap на реальный центр сертификации (корпоративный CA, Vault, ACME и т. д.). Меняется только Step 2 — конфигурация кластера +остается той же. + +
+ ## Шаг 2 — Выпустите сертификат сервера +
+ +Запросите конечный сертификат у CA. Значения `dnsNames` должны охватывать все способы, +которыми клиенты обращаются к подам. Оператор создает один **headless** Service с именем +`-clickhouse-headless`, и каждый под реплики доступен по адресу +`-clickhouse---0.-clickhouse-headless..svc.cluster.local`. +Подстановочный знак для домена headless Service покрывает все реплики: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + Оператор **не** создаёт общекластерный Service (с балансировкой нагрузки). Если вам + нужна единая стабильная конечная точка для подключения, создайте собственный Service `ClusterIP`, + выбирающий поды кластера, и добавьте его DNS-имя в `dnsNames` выше. + + +cert-manager создаёт Secret `clickhouse-cert` с `tls.crt`, `tls.key` и +`ca.crt` и обновляет его до истечения срока действия. Убедитесь, что он существует: + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## Шаг 3 — Включите TLS в кластере +
+ +Укажите Secret для кластера: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### Что делает оператор +
+ +Когда `tls.enabled: true`, оператор: + +* **Открывает защищенные порты** на каждом поде и в headless Service: `9440` + (native TLS) и `8443` (HTTPS). Они добавляются наряду с уже существующими портами. +* **Монтирует Secret** в `/etc/clickhouse-server/tls/` и генерирует + блок ClickHouse `openSSL` с `verificationMode: relaxed`, + `disableProtocols: sslv2,sslv3` и `preferServerCiphers: true`. Это + настройки по умолчанию — чтобы переопределить их, см. [Настройка параметров TLS](#custom-tls-settings). + +Если также задать `required: true`, оператор дополнительно: + +* **Удаляет незащищенные порты** `9000` (native) и `8123` (HTTP) — остаются только TLS-варианты, поэтому клиенты без TLS больше не смогут подключаться. +* **Переключает liveness probe пода** на защищенный native-порт `9440`, чтобы проверка + работоспособности продолжала работать без plaintext listener. + + + Порты TLS `8443` и `9440` резервируются вебхуком **безусловно**, + даже когда TLS отключен, поэтому последующее переключение `tls.enabled` никогда не приводит к конфликту с + элементом `spec.additionalPorts`. См. + [Configuration → `additionalPorts`](/ru/products/kubernetes-operator/guides/configuration#additional-ports). + + +
+ ## Шаг 4 — Подключение по TLS +
+ +При `required: true` клиенты должны использовать защищённые порты и доверять CA. Обращайтесь +к конкретному поду реплики через headless Service (или через собственный Service +типа `Кластерный IP`, если вы его создали). + +**Собственный протокол** (`clickhouse-client`, порт `9440`): + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (порт `8443`): + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +Получите `ca.crt` напрямую из объекта Secret для локального тестирования: + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## Шифрование трафика Keeper +
+ +Включение TLS в кластере ClickHouse **не** шифрует соединение с Keeper. +Включите TLS для `KeeperCluster` отдельно — выпустите сертификат для сервиса Keeper +(шаги 1–2 с `dnsNames` сервиса Keeper) и укажите его: + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +Keeper использует защищённый клиентский порт `2281`. После включения TLS в Keeper **кластер +ClickHouse автоматически подключается к нему по TLS** — на стороне +ClickHouseCluster не требуется никаких дополнительных настроек. Если в ClickHouse +включен TLS, он проверяет сертификат Keeper с помощью собственного набора +`ca.crt`; в противном случае используется системный набор CA по умолчанию. + +
+ ## Собственный набор сертификатов CA +
+ +Если ClickHouse должен доверять центру сертификации (CA), отличному от того, который используется в сертификате сервера (например, если Keeper подписан отдельным CA), укажите `caBundle`: + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +Оператор монтирует этот набор и настраивает клиентскую проверку `openSSL` так, чтобы она использовала +его вместо собственного `ca.crt` сертификата. + +
+ ## Настройка параметров TLS +
+ +Блок `openSSL`, который генерирует оператор, — это конфигурация по умолчанию, а не жёсткое ограничение. Он записывается +в основную конфигурацию сервера; всё, что указано в `spec.settings.extraConfig`, добавляется в +`config.d/99-extra-config.yaml`, который ClickHouse обрабатывает **в последнюю очередь** — поэтому он переопределяет +сгенерированные значения. + +Чтобы усилить настройки по умолчанию — например, включить строгую проверку peer и повысить +минимальную версию протокола до TLS 1.2, — задайте ключи `openSSL.server`, которые хотите изменить: + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +Слияние выполняется по каждому ключу: заменяются только те значения, которые вы задаёте, а сгенерированные ключи, которые вы +не указываете (пути к сертификатам, конфигурация CA), сохраняются. Доступные параметры см. в +[настройках сервера `openSSL`](/ru/reference/settings/server-settings/settings#openssl), +а сведения о том, как объединяется `extraConfig`, — в разделе +[Configuration → Встроенная дополнительная конфигурация](/ru/products/kubernetes-operator/guides/configuration#embedded-extra-configuration). + +
+ ## Проверка и устранение неполадок +
+ +**Убедитесь, что защищённые порты доступны в headless-сервисе:** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**Убедитесь, что сертификат смонтирован в под:** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| Симптом | Вероятная причина | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Поды не запускаются / ошибка монтирования тома после включения TLS | Указанный Secret отсутствует или не содержит `tls.crt`/`tls.key`/`ca.crt`. Оператор не проверяет содержимое Secret'а — отсутствие ключей проявляется как ошибка монтирования тома в поде, а не как отдельное условие status. Проверьте под командой `kubectl describe pod`. | +| Вебхук отклоняет кластер | Указано `required: true` без `enabled: true` или `enabled: true` без `serverCertSecret`. | +| У клиента ошибка `certificate verify failed` | Клиент не доверяет CA. Передайте `ca.crt` из Secret или проверьте, что `dnsNames` в сертификате включают хост, к которому вы подключаетесь. | +| Клиент без шифрования внезапно не может подключиться | `required: true` отключил порты `9000`/`8123`. Переключите клиент на `9440`/`8443` или задайте `required: false`, чтобы небезопасные порты оставались открытыми во время миграции. | + +
+ ## См. также +
+ +* [Конфигурация → Конфигурация TLS/SSL](/ru/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — справочник полей +* [Конфигурация → `additionalPorts`](/ru/products/kubernetes-operator/guides/configuration#additional-ports) — зарезервированные порты +* [Справочник по API → ClusterTLSSpec](/ru/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [настройки сервера `openSSL`](/ru/reference/settings/server-settings/settings#openssl) — параметры TLS, которые можно переопределить через `extraConfig` \ No newline at end of file diff --git a/ru/products/kubernetes-operator/install/helm.mdx b/ru/products/kubernetes-operator/install/helm.mdx index 286d554df..d68f5e150 100644 --- a/ru/products/kubernetes-operator/install/helm.mdx +++ b/ru/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-man helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/ru/products/kubernetes-operator/install/kubectl.mdx b/ru/products/kubernetes-operator/install/kubectl.mdx index 4b72e14de..7b5cf5f0a 100644 --- a/ru/products/kubernetes-operator/install/kubectl.mdx +++ b/ru/products/kubernetes-operator/install/kubectl.mdx @@ -105,7 +105,7 @@ keeperclusters.clickhouse.com 2025-01-06T00:00:00Z ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/ru/products/kubernetes-operator/navigation.json b/ru/products/kubernetes-operator/navigation.json index c5e580bbd..a54e2bc3b 100644 --- a/ru/products/kubernetes-operator/navigation.json +++ b/ru/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "ru/products/kubernetes-operator/guides/introduction", - "ru/products/kubernetes-operator/guides/configuration" + "ru/products/kubernetes-operator/guides/configuration", + "ru/products/kubernetes-operator/guides/monitoring", + "ru/products/kubernetes-operator/guides/scaling", + "ru/products/kubernetes-operator/guides/tls" ] }, { diff --git a/ru/products/kubernetes-operator/overview.mdx b/ru/products/kubernetes-operator/overview.mdx index c9975c783..559cab3d1 100644 --- a/ru/products/kubernetes-operator/overview.mdx +++ b/ru/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ ClickHouse Operator — это Kubernetes-оператор, который ав * **[Введение](/ru/products/kubernetes-operator/guides/introduction)** - Общий обзор концепций ClickHouse Operator * **[Руководство по настройке](/ru/products/kubernetes-operator/guides/configuration)** - Настройка кластеров ClickHouse и Keeper -* **[Мониторинг](/ru/products/kubernetes-operator/guides/introduction)** - Мониторинг clickhouse-operator с использованием метрик Prometheus +* **[Мониторинг](/ru/products/kubernetes-operator/guides/monitoring)** - Метрики Prometheus и проверки работоспособности оператора +* **[Масштабирование](/ru/products/kubernetes-operator/guides/scaling)** - Масштабирование реплик, сегментов и кворума Keeper +* **[Защита с помощью TLS](/ru/products/kubernetes-operator/guides/tls)** - Сквозное шифрование кластеров с cert-manager
## Справочник diff --git a/ru/products/kubernetes-operator/reference/api-reference.mdx b/ru/products/kubernetes-operator/reference/api-reference.mdx index f4d4a2c45..c4a81d296 100644 --- a/ru/products/kubernetes-operator/reference/api-reference.mdx +++ b/ru/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'Справочник по API' В этом документе содержится подробный справочник по API пользовательских ресурсов ClickHouse Operator. +
+ ## AdditionalPort +
+ +AdditionalPort задаёт один дополнительный TCP-порт, который будет открыт на поде ClickHouse и в headless Service, управляемом оператором. + +| Поле | Тип | Описание | Обязательно | По умолчанию | +| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------ | +| `name` | string | Имя однозначно идентифицирует порт в списке. Используется и как имя порта контейнера, и как имя порта сервиса.
Должно быть значением DNS_LABEL. | true | | +| `port` | integer | Порт — это номер TCP-порта, который будет открыт. | true | | + +Встречается в: + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec определяет желаемое состояние ClickHouseCluster. -| Поле | Тип | Описание | Обязательно | По умолчанию | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | -| `replicas` | integer | Количество реплик в одном сегменте. | false | 3 | -| `shards` | integer | Количество сегментов в кластере. | false | 1 | -| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Ссылка на KeeperCluster, используемый для координации ClickHouse.
Если пространство имен не указано, используется пространство имен ClickHouseCluster. | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Параметры, передаваемые в спецификацию пода ClickHouse. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Параметры, передаваемые в спецификацию контейнера ClickHouse. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Спецификация постоянного хранилища для данных ClickHouse. | false | | -| `labels` | object (keys:string, values:string) | Дополнительные метки, добавляемые к ресурсам. | false | | -| `annotations` | object (keys:string, values:string) | Дополнительные аннотации, добавляемые к ресурсам. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget настраивает PDB, создаваемый для каждого сегмента.
Если значение не задано, оператор по умолчанию использует maxUnavailable=1 для сегментов
с одной репликой и minAvailable=1 для сегментов с несколькими репликами. | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | Параметры конфигурации для сервера ClickHouse. | false | | -| `clusterDomain` | string | ClusterDomain — это суффикс домена кластера Kubernetes, используемый для DNS-разрешения. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel задает канал выпуска для проверок обновлений мажорных версий.
Если значение пустое, будут предлагаться только минорные обновления. Допустимые значения: stable, lts или конкретная версия major.minor (например, 25.8). | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Переопределения VersionProbeTemplate для задачи определения версии. | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret — это необязательная ссылка на Secret под внешним управлением, содержащий секреты кластера.
Этот Secret должен находиться в том же пространстве имен, что и кластер. | false | | +| Поле | Тип | Описание | Обязательно | По умолчанию | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | +| `replicas` | integer | Количество реплик в одном сегменте. | false | 3 | +| `shards` | integer | Количество сегментов в кластере. | false | 1 | +| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | Ссылка на KeeperCluster, используемый для координации ClickHouse.
Если пространство имен не указано, используется пространство имен ClickHouseCluster. | true | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Параметры, передаваемые в спецификацию пода ClickHouse. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Параметры, передаваемые в спецификацию контейнера ClickHouse. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Спецификация постоянного хранилища для данных ClickHouse. | false | | +| `labels` | object (keys:string, values:string) | Дополнительные метки, добавляемые к ресурсам. | false | | +| `annotations` | object (keys:string, values:string) | Дополнительные аннотации, добавляемые к ресурсам. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget настраивает PDB, создаваемый для каждого сегмента.
Если значение не задано, оператор по умолчанию использует maxUnavailable=1 для сегментов
с одной репликой и minAvailable=1 для сегментов с несколькими репликами. | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | Параметры конфигурации для сервера ClickHouse. | false | | +| `clusterDomain` | string | ClusterDomain — это суффикс домена кластера Kubernetes, используемый для DNS-разрешения. | false | cluster.local | +| `upgradeChannel` | string | Канал релизов задает канал выпуска для проверок обновлений мажорных версий.
Если значение пустое, будут предлагаться только минорные обновления. Допустимые значения: stable, lts или конкретная версия major.minor (например, 25.8). | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Переопределения VersionProbeTemplate для задачи определения версии. | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret — это необязательная ссылка на Secret под внешним управлением, содержащий секреты кластера.
Этот Secret должен находиться в том же пространстве имен, что и кластер. | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) array | AdditionalPorts объявляет дополнительные TCP-порты, которые нужно открыть в поде ClickHouse и headless Service, управляемом оператором.
Оператор только добавляет порты в ресурсы Kubernetes, но не настраивает сервер ClickHouse на прослушивание этих портов. | false | | Встречается в: @@ -180,7 +196,7 @@ ContainerTemplateSpec описывает переопределения конф | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------ | | `image` | [ContainerImage](#containerimage) | `Image` — образ контейнера, который будет развернут. | true | | | `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | `ImagePullPolicy` для образа; по умолчанию используется `IfNotPresent`. | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | `Resources` — требования к ресурсам для контейнера сервера.
Рекурсивно объединяются со значениями оператора по умолчанию через SMP. Отдельные `limits` и `requests` переопределяют только совпадающие
ключи; для незаданных полей сохраняются значения по умолчанию оператора. | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | `Resources` — требования к ресурсам для контейнера сервера.
Применяются как единое целое: значения оператора по умолчанию используются только тогда, когда все поля ресурсов пусты. | false | | | `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | `VolumeMounts` — список монтирований томов для контейнера.
Конкатенируется с монтированиями, сгенерированными оператором. Записи с тем же `mountPath`, что и у монтирования
оператора, объединяются в projected volume. | false | | | `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | `Env` — список переменных окружения, задаваемых в контейнере.
Объединяется со значениями оператора по умолчанию по имени. | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | `SecurityContext` определяет параметры безопасности, с которыми должен запускаться контейнер.
Ненулевой `SecurityContext` полностью заменяет значения оператора по умолчанию; пользователь управляет
всей структурой целиком. Если значение `nil`, сохраняются значения оператора по умолчанию.
Подробнее: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | @@ -302,19 +318,19 @@ KeeperClusterReference указывает на KeeperCluster, используе KeeperClusterSpec определяет желаемое состояние KeeperCluster. -| Поле | Тип | Описание | Обязательное | По умолчанию | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- | -| `replicas` | integer | Количество реплик в кластере | false | 3 | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Параметры, передаваемые в спецификацию пода Keeper. | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Параметры, передаваемые в спецификацию контейнера Keeper. | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Спецификация постоянного хранилища для данных ClickHouse Keeper. | false | | -| `labels` | object (keys:string, values:string) | Дополнительные метки, добавляемые к ресурсам. | false | | -| `annotations` | object (keys:string, values:string) | Дополнительные аннотации, добавляемые к ресурсам. | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget настраивает PDB, создаваемый для кластера Keeper.
Если не задан, оператор по умолчанию использует maxUnavailable=replicas/2
(сохраняя кворум для кластера 2F+1). | false | | -| `settings` | [KeeperSettings](#keepersettings) | Параметры конфигурации для сервера ClickHouse Keeper. | false | | -| `clusterDomain` | string | ClusterDomain — это суффикс домена кластера Kubernetes, используемый для DNS-разрешения. | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel задаёт канал релизов для проверки обновлений мажорной версии.
Если значение пустое, будут предлагаться только минорные обновления. Допустимые значения: stable, lts или конкретная версия major.minor (например, 25.8). | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Переопределения VersionProbeTemplate для задачи определения версии. | false | | +| Поле | Тип | Описание | Обязательное | По умолчанию | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ------------- | +| `replicas` | integer | Количество реплик в кластере | false | 3 | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | Параметры, передаваемые в спецификацию пода Keeper. | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | Параметры, передаваемые в спецификацию контейнера Keeper. | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | Спецификация постоянного хранилища для данных ClickHouse Keeper. | false | | +| `labels` | object (keys:string, values:string) | Дополнительные метки, добавляемые к ресурсам. | false | | +| `annotations` | object (keys:string, values:string) | Дополнительные аннотации, добавляемые к ресурсам. | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget настраивает PDB, создаваемый для кластера Keeper.
Если не задан, оператор по умолчанию использует maxUnavailable=replicas/2
(сохраняя кворум для кластера 2F+1); для кластеров с одной репликой используется maxUnavailable=1. | false | | +| `settings` | [KeeperSettings](#keepersettings) | Параметры конфигурации для сервера ClickHouse Keeper. | false | | +| `clusterDomain` | string | ClusterDomain — это суффикс домена кластера Kubernetes, используемый для DNS-разрешения. | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel задаёт канал релизов для проверки обновлений мажорной версии.
Если значение пустое, будут предлагаться только минорные обновления. Допустимые значения: stable, lts или конкретная версия major.minor (например, 25.8). | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | Переопределения VersionProbeTemplate для задачи определения версии. | false | | Встречается в: @@ -336,7 +352,7 @@ KeeperClusterStatus определяет наблюдаемое состояни | `updateRevision` | string | UpdateRevision указывает последнюю запрошенную ревизию спецификации KeeperCluster. | true | | | `observedGeneration` | integer | ObservedGeneration указывает последнее поколение, зафиксированное контроллером. | true | | | `version` | string | Version указывает версию, которую сообщает образ контейнера. | false | | -| `versionProbeRevision` | string | VersionProbeRevision — хеш образа последней успешной проверки версии.
Когда он совпадает с текущим хешем образа, кэшированное значение Version используется напрямую. | false | | +| `versionProbeRevision` | string | VersionProbeRevision — хэш образа последней успешной проверки версии.
Когда он совпадает с текущим хэшом образа, кэшированное значение Version используется напрямую. | false | | Встречается в: diff --git a/ru/resources/changelogs/cloud/release-status.mdx b/ru/resources/changelogs/cloud/release-status.mdx index 973b67050..fe78b3366 100644 --- a/ru/resources/changelogs/cloud/release-status.mdx +++ b/ru/resources/changelogs/cloud/release-status.mdx @@ -51,60 +51,73 @@ ClickHouse Cloud предлагает разные каналы релизов, \ No newline at end of file diff --git a/zh/_specs/cloud-openapi.json b/zh/_specs/cloud-openapi.json new file mode 100644 index 000000000..7ea7d357f --- /dev/null +++ b/zh/_specs/cloud-openapi.json @@ -0,0 +1,8933 @@ +{ + "components": { + "schemas": { + "Activity": { + "properties": { + "actorDetails": { + "description": "有关 actor 的附加信息。", + "type": "string" + }, + "actorId": { + "description": "唯一的 actor ID。", + "type": "string" + }, + "actorIpAddress": { + "description": "actor 的 IP 地址。仅为 'user' 和 'api' 类型的 actor 定义。", + "type": "string" + }, + "actorType": { + "description": "actor 的类型：'user'、'support'、'system'、'api'。", + "enum": [ + "user", + "support", + "system", + "api" + ], + "type": "string" + }, + "createdAt": { + "description": "活动的时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "唯一的活动 ID。", + "type": "string" + }, + "organizationId": { + "description": "活动范围：与此活动相关联的 Organization ID。", + "type": "string" + }, + "serviceId": { + "description": "活动范围：此活动关联的服务 ID。", + "type": "string" + }, + "type": { + "description": "活动的类型。", + "enum": [ + "create_organization", + "organization_update_name", + "transfer_service_in", + "transfer_service_out", + "save_payment_method", + "marketplace_subscription", + "migrate_marketplace_billing_details_in", + "migrate_marketplace_billing_details_out", + "organization_update_tier", + "organization_invite_create", + "organization_invite_delete", + "organization_member_join", + "organization_member_add", + "organization_member_leave", + "organization_member_delete", + "organization_member_update_role", + "organization_member_update_mfa_method", + "user_login", + "user_login_failed", + "user_logout", + "key_create", + "key_delete", + "openapi_key_update", + "service_create", + "service_start", + "service_stop", + "service_awaken", + "service_partially_running", + "service_delete", + "service_update_name", + "service_update_ip_access_list", + "service_update_autoscaling_memory", + "service_update_autoscaling_idling", + "service_update_password", + "service_update_autoscaling_replicas", + "service_update_max_allowable_replicas", + "service_update_backup_configuration", + "service_restore_backup", + "service_update_release_channel", + "service_update_gpt_usage_consent", + "service_update_private_endpoints", + "service_import_to_organization", + "service_export_from_organization", + "service_maintenance_start", + "service_maintenance_end", + "service_update_core_dump", + "backup_delete" + ], + "type": "string" + }, + "userAgent": { + "description": "Actor 的 User-Agent", + "type": "string" + } + } + }, + "ApiKey": { + "properties": { + "createdAt": { + "description": "密钥的创建时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "expireAt": { + "description": "密钥过期时间戳。如果该字段不存在、为 `null` 或为空，则该密钥永不过期。ISO-8601。", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "id": { + "description": "唯一 API key ID。", + "format": "uuid", + "type": "string" + }, + "ipAccessList": { + "description": "允许使用此密钥访问 API 的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "keySuffix": { + "description": "密钥的后 4 个字符。", + "type": "string" + }, + "name": { + "description": "密钥名称", + "type": "string" + }, + "roles": { + "description": "分配给该密钥的角色列表。至少包含 1 个元素。", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "密钥状态：‘enabled’、‘disabled’。", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + }, + "usedAt": { + "description": "密钥上次使用的时间戳。如果该字段不存在，则该密钥从未使用过。ISO-8601。", + "format": "date-time", + "type": "string" + } + } + }, + "ApiKeyHashData": { + "properties": { + "keyIdHash": { + "description": "密钥 ID 的哈希值。", + "type": "string" + }, + "keyIdSuffix": { + "description": "密钥 ID 的后 4 位数字。算法：echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + }, + "keySecretHash": { + "description": "密钥 secret 的哈希值。算法：echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ApiKeyPatchRequest": { + "properties": { + "expireAt": { + "description": "该密钥的过期时间戳。如果为 `null` 或为空，则该密钥永不过期。ISO-8601。", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "ipAccessList": { + "description": "允许使用此密钥访问 API 的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "name": { + "description": "密钥名称", + "type": "string" + }, + "roles": { + "description": "分配给该密钥的角色列表。至少包含 1 个元素。", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "密钥状态：'enabled'、'disabled'。", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + } + } + }, + "ApiKeyPostRequest": { + "properties": { + "expireAt": { + "description": "key 的过期时间戳。如果未提供、为 `null` 或为空，则该 key 永不过期。ISO-8601。", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "hashData": { + "$ref": "#/components/schemas/ApiKeyHashData" + }, + "ipAccessList": { + "description": "允许使用此 key 访问 API 的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "name": { + "description": "key 的名称。", + "type": "string" + }, + "roles": { + "description": "分配给该 key 的 role 列表。至少包含 1 个元素。", + "items": { + "enum": [ + "admin", + "developer", + "query_endpoints" + ], + "type": "string" + }, + "type": "array" + }, + "state": { + "description": "key 的初始状态：'enabled'、'disabled'。如果未提供，则新 key 的状态为 'enabled'。", + "enum": [ + "enabled", + "disabled" + ], + "type": "string" + } + } + }, + "ApiKeyPostResponse": { + "properties": { + "key": { + "$ref": "#/components/schemas/ApiKey" + }, + "keyId": { + "description": "生成的 key ID。仅当请求中没有 'hashData' 时提供。", + "type": "string" + }, + "keySecret": { + "description": "生成的 key secret。仅当请求中没有 'hashData' 时提供。", + "type": "string" + } + } + }, + "AwsBackupBucket": { + "properties": { + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "AWS Role ARN", + "type": "string" + }, + "iamRoleSessionName": { + "description": "AWS Role 会话名称", + "type": "string" + }, + "id": { + "description": "唯一的备份存储桶 ID", + "format": "uuid", + "type": "string" + } + } + }, + "AwsBackupBucketPatchRequestV1": { + "properties": { + "bucketPath": { + "description": "bucket 路径", + "type": "string" + }, + "bucketProvider": { + "description": "bucket 提供商", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "AWS Role ARN", + "type": "string" + }, + "iamRoleSessionName": { + "description": "AWS IAM Role 会话名称", + "nullable": true, + "type": "string" + } + } + }, + "AwsBackupBucketPostRequestV1": { + "properties": { + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "AWS Role ARN", + "type": "string" + }, + "iamRoleSessionName": { + "description": "AWS Role 会话名称", + "type": "string" + } + } + }, + "AwsBackupBucketProperties": { + "properties": { + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AWS" + ], + "type": "string" + }, + "iamRoleArn": { + "description": "AWS IAM Role", + "type": "string" + }, + "iamRoleSessionName": { + "description": "AWS IAM Role", + "type": "string" + } + } + }, + "AzureBackupBucket": { + "properties": { + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "containerName": { + "description": "容器名称", + "type": "string" + }, + "id": { + "description": "唯一的备份存储桶 ID。", + "format": "uuid", + "type": "string" + } + } + }, + "AzureBackupBucketPatchRequestV1": { + "properties": { + "bucketProvider": { + "description": "bucket 提供商", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "connectionString": { + "description": "连接字符串", + "type": "string" + }, + "containerName": { + "description": "Container 名称", + "type": "string" + } + } + }, + "AzureBackupBucketPostRequestV1": { + "properties": { + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "connectionString": { + "description": "连接字符串", + "type": "string" + }, + "containerName": { + "description": "Container 名称", + "type": "string" + } + } + }, + "AzureBackupBucketProperties": { + "properties": { + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "AZURE" + ], + "type": "string" + }, + "containerName": { + "description": "容器名称", + "type": "string" + } + } + }, + "AzureEventHub": { + "properties": { + "connectionString": { + "description": "Azure EventHub 源的连接字符串。", + "type": "string" + } + } + }, + "Backup": { + "properties": { + "backupName": { + "description": "外部备份 bucket 中的备份名称。", + "type": "string" + }, + "bucket": { + "description": "存储该备份的备份 bucket。", + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketProperties" + } + ] + }, + "durationInSeconds": { + "description": "执行备份所耗费的时间（以秒为单位）。如果状态仍为 in_progress，则表示从备份开始到当前经过的秒数。", + "type": "number" + }, + "finishedAt": { + "description": "备份完成时间戳。ISO-8601。仅适用于已完成的备份", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "唯一备份 ID。", + "format": "uuid", + "type": "string" + }, + "serviceId": { + "description": "名称 ", + "type": "string" + }, + "sizeInBytes": { + "description": "备份大小（以字节为单位）。", + "type": "number" + }, + "startedAt": { + "description": "备份开始时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "status": { + "description": "备份状态：'done'、'error'、'in_progress'。", + "enum": [ + "done", + "error", + "in_progress" + ], + "type": "string" + }, + "type": { + "description": "备份类型（\"full\" 或 \"增量\"）。", + "enum": [ + "full", + "incremental" + ], + "type": "string" + } + } + }, + "BackupBucket": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucket" + }, + { + "$ref": "#/components/schemas/GcpBackupBucket" + }, + { + "$ref": "#/components/schemas/AzureBackupBucket" + } + ] + }, + "BackupBucketPatchRequest": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketPatchRequestV1" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketPatchRequestV1" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketPatchRequestV1" + } + ] + }, + "BackupBucketPostRequest": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketPostRequestV1" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketPostRequestV1" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketPostRequestV1" + } + ] + }, + "BackupBucketProperties": { + "oneOf": [ + { + "$ref": "#/components/schemas/AwsBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/GcpBackupBucketProperties" + }, + { + "$ref": "#/components/schemas/AzureBackupBucketProperties" + } + ] + }, + "BackupConfiguration": { + "properties": { + "backupPeriodInHours": { + "description": "每次备份之间的时间间隔（以小时为单位）。", + "type": "number" + }, + "backupRetentionPeriodInHours": { + "description": "备份的最短可用时长（以小时为单位）。", + "type": "number" + }, + "backupStartTime": { + "description": "执行备份的时间，格式为 HH:MM（按 UTC 时区计算）。定义后，备份周期将重置为每 24 小时一次。", + "type": "string" + } + } + }, + "BackupConfigurationPatchRequest": { + "properties": { + "backupPeriodInHours": { + "description": "每次 Backup 之间的时间间隔（小时）。", + "type": "number" + }, + "backupRetentionPeriodInHours": { + "description": "backups 的最短可用时长（小时）。", + "type": "number" + }, + "backupStartTime": { + "description": "执行 Backup 的时间，格式为 HH:MM（按 UTC timezone 计算）。定义后，备份周期将重置为每 24 小时一次。", + "type": "string" + } + } + }, + "ByocConfig": { + "properties": { + "accountName": { + "description": "账户名称", + "type": "string" + }, + "cloudProvider": { + "description": "该区域的云提供商", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "id": { + "description": "BYOC 配置的唯一标识符", + "type": "string" + }, + "regionId": { + "description": "BYOC 已配置且可创建服务的区域", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "state": { + "description": "基础设施的状态", + "enum": [ + "infra-ready", + "infra-provisioning", + "infra-terminated" + ], + "type": "string" + } + } + }, + "ByocInfrastructurePostRequest": { + "properties": { + "accountId": { + "description": "为其配置 BYOC 基础设施的云账户 ID", + "type": "string" + }, + "availabilityZoneSuffixes": { + "description": "可用区后缀列表", + "items": { + "enum": [ + "a", + "b", + "c", + "d", + "e", + "f" + ], + "type": "string" + }, + "type": "array" + }, + "regionId": { + "description": "BYOC 基础设施所在的区域", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "vpcCidrRange": { + "description": "VPC 的 CIDR 范围", + "type": "string" + } + } + }, + "ClickPipe": { + "properties": { + "createdAt": { + "description": "ClickPipe 的创建日期。", + "type": "string" + }, + "destination": { + "$ref": "#/components/schemas/ClickPipeDestination" + }, + "fieldMappings": { + "description": "ClickPipe 的字段映射。请注意，所有目标列都必须包含在映射中。", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "id": { + "description": "唯一的 ClickPipe ID。", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "ClickPipe 的名称。", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "serviceId": { + "description": "此 ClickPipe 所属服务的 ID。", + "format": "uuid", + "type": "string" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipeSource" + }, + "state": { + "description": "ClickPipe 的当前状态。", + "type": "string" + }, + "updatedAt": { + "description": "ClickPipe 的最后更新时间。", + "type": "string" + } + } + }, + "ClickPipeDestination": { + "properties": { + "columns": { + "description": "目标表的列。除 Postgres 外，所有管道类型的必填字段。", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "目标端数据库。", + "type": "string" + }, + "managedTable": { + "description": "该表是否由 ClickPipes 管理？除 Postgres 外，所有管道类型的必填字段。", + "type": "boolean" + }, + "table": { + "description": "目标表。除 Postgres 外，所有管道类型的必填字段。", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeDestinationColumn": { + "properties": { + "name": { + "description": "列名。", + "type": "string" + }, + "type": { + "description": "列类型。", + "type": "string" + } + } + }, + "ClickPipeDestinationTableDefinition": { + "properties": { + "engine": { + "$ref": "#/components/schemas/ClickPipeDestinationTableEngine" + }, + "partitionBy": { + "description": "分区键 SQL 表达式。", + "type": "string" + }, + "primaryKey": { + "description": "主键 SQL 表达式。", + "type": "string" + }, + "sortingKey": { + "description": "目标端表的排序键，即列列表。", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipeDestinationTableEngine": { + "properties": { + "columnIds": { + "description": "用于 SummingMergeTree 引擎求和的列名。", + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "description": "目标端表的引擎类型。", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "SummingMergeTree", + "Null" + ], + "type": "string" + }, + "versionColumnId": { + "description": "用作 ReplacingMergeTree 引擎版本列的列名。", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipeFieldMapping": { + "properties": { + "destinationField": { + "description": "目标字段名称。", + "type": "string" + }, + "sourceField": { + "description": "源字段名称。", + "type": "string" + } + } + }, + "ClickPipeKafkaOffset": { + "properties": { + "strategy": { + "description": "Offset 策略。", + "enum": [ + "from_beginning", + "from_latest", + "from_timestamp" + ], + "type": "string" + }, + "timestamp": { + "description": "作为起始点的分钟精度 UTC 时间戳。“from_timestamp” 策略必需。", + "example": "2021-01-01T00:00", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipeKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Schema Registry 的身份验证类型。", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "用于验证 Schema Registry 证书的 PEM 编码 CA 证书。", + "nullable": true, + "type": "string" + }, + "url": { + "description": "schema URL。必须使用 HTTPS。", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeKafkaSchemaRegistryCredentials": { + "properties": { + "password": { + "description": "Schema Registry 的密码。", + "type": "string" + }, + "username": { + "description": "Schema Registry 的用户名。", + "type": "string" + } + } + }, + "ClickPipeKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka 源的身份验证方法。支持的身份验证方法：kafka: PLAIN、SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，msk: SCRAM-SHA-512、IAM_ROLE、IAM_USER、MUTUAL_TLS，confluent: PLAIN、MUTUAL_TLS，warpstream: PLAIN，azureeventhub: PLAIN，redpanda: SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，dokafka: SCRAM-SHA-256、MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Kafka 源的消息代理。", + "type": "string" + }, + "caCertificate": { + "description": "用于验证 broker 证书的 PEM 编码 CA 证书。", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Kafka 源的消费者组。如果未提供，则使用 \"clickpipes-<>\"。", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "format": { + "description": "Kafka 源的格式。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka 源的 IAM role。与 IAM role 身份验证配合使用。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "用于与 Kafka 源建立安全私网连接的反向专用终结点 UUIDs。", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka 源的 topic。", + "type": "string" + }, + "type": { + "description": "Kafka 源的类型。", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipeKinesisSource": { + "properties": { + "authentication": { + "description": "用于 Kinesis stream 的身份验证方法。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis stream 的格式。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "用于身份验证的 IAM role。如果使用 IAM_ROLE，则此项为必填。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "从 Kinesis stream 读取时使用的迭代器类型。如果使用 AT_TIMESTAMP，则必须提供 timestamp 字段。", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis stream 所在的 AWS 区域。", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis stream 的名称。", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "开始从 Kinesis stream 读取的 Unix timestamp。如果 iteratorType 为 AT_TIMESTAMP，则此项为必填。", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "是否对 Kinesis stream 使用增强型扇出。", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipeMutateDestination": { + "properties": { + "columns": { + "description": "目标表的列。除 Postgres 外，所有管道类型的必填字段。", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + }, + "database": { + "description": "目标数据库。", + "type": "string" + }, + "managedTable": { + "description": "该表是否由 ClickPipes 管理？除 Postgres 外，所有管道类型的必填字段。", + "type": "boolean" + }, + "roles": { + "description": "ClickPipe 将使用这些 roles 创建一个 ClickHouse 用户。如有需要，请在此添加你的自定义 roles。", + "items": { + "type": "string" + }, + "type": "array" + }, + "table": { + "description": "目标表。除 Postgres 外，所有管道类型的必填字段。", + "type": "string" + }, + "tableDefinition": { + "$ref": "#/components/schemas/ClickPipeDestinationTableDefinition" + } + } + }, + "ClickPipeMutateKafkaSchemaRegistry": { + "properties": { + "authentication": { + "description": "Schema Registry 的身份验证类型。", + "enum": [ + "PLAIN" + ], + "type": "string" + }, + "caCertificate": { + "description": "用于验证 Schema Registry 证书的 PEM 编码 CA 证书。", + "nullable": true, + "type": "string" + }, + "credentials": { + "$ref": "#/components/schemas/ClickPipeKafkaSchemaRegistryCredentials" + }, + "url": { + "description": "Schema URL。必须使用 HTTPS。", + "example": "https://psrc-aa00.us-east-2.aws.confluent.cloud/schemas/ids/100004", + "type": "string" + } + } + }, + "ClickPipeMutatePostgresSource": { + "properties": { + "credentials": { + "$ref": "#/components/schemas/PLAIN" + }, + "database": { + "description": "要连接的 Postgres 实例的数据库。", + "type": "string" + }, + "host": { + "description": "要连接的 Postgres 实例的主机。", + "type": "string" + }, + "port": { + "description": "要连接的 Postgres 实例的端口。", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgres 管道的表映射。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeObjectStorageSource": { + "properties": { + "authentication": { + "description": "身份验证方法。CONNECTION_STRING 用于 Azure Blob 存储。IAM_ROLE 和 IAM_USER 用于 AWS S3/GCS/DigitalOcean。如果未提供，则不使用身份验证。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob 存储的 Container 名称。当 type 为 azureblobstorage 时，此项为必填。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "文件使用的压缩算法。", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "用于 Azure Blob 存储身份验证的 connection string。当身份验证为 CONNECTION_STRING 时，此项为必填。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "文件中使用的分隔符。", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "文件格式。", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "与 IAM role 身份验证配合使用的 IAM role。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "如果设为 true，管道会持续从源中读取新文件。如果设为 false，管道只会读取一次文件。新文件必须按词典序顺序上传。", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure container 中文件的路径。用于 Azure Blob 存储源。你可以使用类似 bash 的通配符指定多个文件。更多信息请参阅路径中使用通配符的相关文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "用于基于事件的持续摄取的 SQS queue URL。提供后，文件将根据 S3 事件通知进行摄取，而不是按词典序处理。仅在 isContinuous 为 true 且身份验证不是公网时适用。", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage source 的类型。", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "提供要摄取的文件路径。你可以使用类似 bash 的通配符指定多个文件。更多信息请参阅路径中使用通配符的相关文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePatchDestination": { + "properties": { + "columns": { + "description": "目标表的列。这不会更新表 schema，只会更新 ClickPipe 配置。", + "items": { + "$ref": "#/components/schemas/ClickPipeDestinationColumn" + }, + "type": "array" + } + } + }, + "ClickPipePatchKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka 源的身份验证方法。支持的身份验证方法：kafka: PLAIN、SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，msk: SCRAM-SHA-512、IAM_ROLE、IAM_USER、MUTUAL_TLS，confluent: PLAIN、MUTUAL_TLS，warpstream: PLAIN，azureeventhub: PLAIN，redpanda: SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，dokafka: SCRAM-SHA-256、MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "nullable": true, + "type": "string" + }, + "caCertificate": { + "description": "用于验证 broker 证书的 PEM 编码 CA 证书。", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka 源的凭据。请选择身份验证方法支持的一种。", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "iamRole": { + "description": "Kafka 源的 IAM role。与 IAM role 身份验证配合使用。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "reversePrivateEndpointIds": { + "description": "用于与 Kafka 源建立安全私网连接的反向专用终结点 UUIDs。", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "ClickPipePatchKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "用于 Kinesis stream 的身份验证方法。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "用于身份验证的 IAM role。如果使用 IAM_ROLE，则此项为必填。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "身份验证方法。CONNECTION_STRING 用于 Azure Blob 存储。IAM_ROLE 和 IAM_USER 用于 AWS S3/GCS/DigitalOcean。如果未提供，则不使用身份验证。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob 存储的 Container 名称。当 type 为 azureblobstorage 时必填。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "用于 Azure Blob 存储身份验证的 connection string。当 authentication 为 CONNECTION_STRING 时必填。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "iamRole": { + "description": "与 IAM role 身份验证配合使用的 IAM role。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "path": { + "description": "Azure container 内文件的路径。用于 Azure Blob 存储源。您可以使用类 bash 通配符指定多个文件。更多信息请参阅有关在路径中使用通配符的文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeRemoveTableMapping": { + "properties": { + "sourceSchemaName": { + "description": "源 schema 名称。", + "nullable": true, + "type": "string" + }, + "sourceTable": { + "description": "源表名称。", + "nullable": true, + "type": "string" + }, + "tableEngine": { + "description": "用于目标表的表引擎。", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "nullable": true, + "type": "string" + }, + "targetTable": { + "description": "目标表名称。", + "nullable": true, + "type": "string" + } + } + }, + "ClickPipePatchPostgresPipeSettings": { + "properties": { + "pullBatchSize": { + "description": "每个批次拉取的行数。", + "nullable": true, + "type": "number" + }, + "syncIntervalSeconds": { + "description": "从 Postgres 同步数据的时间间隔（秒）。", + "nullable": true, + "type": "number" + } + } + }, + "ClickPipePatchPostgresSource": { + "properties": { + "credentials": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + } + ] + }, + "database": { + "description": "要连接的 Postgres 实例的数据库。", + "nullable": true, + "type": "string" + }, + "host": { + "description": "要连接的 Postgres 实例的主机。", + "nullable": true, + "type": "string" + }, + "port": { + "description": "要连接的 Postgres 实例的端口。", + "nullable": true, + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeSettings" + }, + "tableMappingsToAdd": { + "description": "要添加到 Postgres 管道的表映射。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + }, + "tableMappingsToRemove": { + "description": "要从 Postgres 管道中移除的表映射。", + "items": { + "$ref": "#/components/schemas/ClickPipePatchPostgresPipeRemoveTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipePatchRequest": { + "properties": { + "destination": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchDestination" + } + ] + }, + "fieldMappings": { + "description": "ClickPipe 的字段映射。这不会更新表 schema，只会更新 ClickPipe 配置。", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe 的名称。", + "nullable": true, + "type": "string" + }, + "settings": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeSettings" + } + ] + }, + "source": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchSource" + } + ] + } + } + }, + "ClickPipePatchSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePatchObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipePatchPostgresSource" + }, + "validateSamples": { + "description": "验证从数据源接收的数据样本。将验证连接，以及数据的可用性和正确性。若未启用，则仅验证连接。此设置对 Postgres 管道无效，因为它们始终只验证连接和表定义。此功能为 Experimental，未来可能会被移除。", + "type": "boolean" + } + } + }, + "ClickPipePostKafkaSource": { + "properties": { + "authentication": { + "description": "Kafka 源的身份验证方法。支持的身份验证方法：kafka: PLAIN、SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，msk: SCRAM-SHA-512、IAM_ROLE、IAM_USER、MUTUAL_TLS，confluent: PLAIN、MUTUAL_TLS，warpstream: PLAIN，azureeventhub: PLAIN，redpanda: SCRAM-SHA-256、SCRAM-SHA-512、MUTUAL_TLS，dokafka: SCRAM-SHA-256、MUTUAL_TLS", + "enum": [ + "PLAIN", + "SCRAM-SHA-256", + "SCRAM-SHA-512", + "IAM_ROLE", + "IAM_USER", + "MUTUAL_TLS" + ], + "type": "string" + }, + "brokers": { + "description": "Kafka 源的消息代理。", + "type": "string" + }, + "caCertificate": { + "description": "用于验证 broker 证书的 PEM 编码 CA 证书。", + "nullable": true, + "type": "string" + }, + "consumerGroup": { + "description": "Kafka 源的消费者组。如果未提供，则使用 \"clickpipes-<>\"。", + "example": "my-clickpipe-consumer-group", + "nullable": true, + "type": "string" + }, + "credentials": { + "description": "Kafka 源的凭据。请选择身份验证方法支持的一种。", + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/PLAIN" + }, + { + "$ref": "#/components/schemas/MskIamUser" + }, + { + "$ref": "#/components/schemas/AzureEventHub" + } + ] + }, + "format": { + "description": "Kafka 源的格式。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "Kafka 源的 IAM role。与 IAM role 身份验证配合使用。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/kafka#iam", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "offset": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaOffset" + } + ] + }, + "reversePrivateEndpointIds": { + "description": "用于与 Kafka 源建立安全私网连接的反向专用终结点 UUIDs。", + "items": { + "type": "string" + }, + "type": "array" + }, + "schemaRegistry": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeMutateKafkaSchemaRegistry" + } + ] + }, + "topics": { + "description": "Kafka 源的 topic。", + "type": "string" + }, + "type": { + "description": "Kafka 源的类型。", + "enum": [ + "kafka", + "redpanda", + "msk", + "confluent", + "warpstream", + "azureeventhub", + "dokafka" + ], + "type": "string" + } + } + }, + "ClickPipePostKinesisSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "用于 Kinesis stream 的身份验证方法。", + "enum": [ + "IAM_ROLE", + "IAM_USER" + ], + "type": "string" + }, + "format": { + "description": "Kinesis stream 的格式。", + "enum": [ + "JSONEachRow", + "Avro", + "AvroConfluent" + ], + "type": "string" + }, + "iamRole": { + "description": "用于身份验证的 IAM role。如果使用 IAM_ROLE，则此项为必填。", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "iteratorType": { + "description": "从 Kinesis stream 读取时使用的迭代器类型。如果使用 AT_TIMESTAMP，则必须提供 timestamp 字段。", + "enum": [ + "TRIM_HORIZON", + "LATEST", + "AT_TIMESTAMP" + ], + "type": "string" + }, + "region": { + "description": "Kinesis stream 所在的 AWS 区域。", + "example": "us-east-1", + "type": "string" + }, + "streamName": { + "description": "Kinesis stream 的名称。", + "example": "my-stream", + "type": "string" + }, + "timestamp": { + "description": "开始从 Kinesis stream 读取的 Unix timestamp。如果 iteratorType 为 AT_TIMESTAMP，则此项为必填。", + "example": 1615766400, + "nullable": true, + "type": "integer" + }, + "useEnhancedFanOut": { + "description": "是否对 Kinesis stream 使用增强型扇出。", + "nullable": true, + "type": "boolean" + } + } + }, + "ClickPipePostObjectStorageSource": { + "properties": { + "accessKey": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/MskIamUser" + } + ] + }, + "authentication": { + "description": "身份验证方法。CONNECTION_STRING 用于 Azure Blob 存储。IAM_ROLE 和 IAM_USER 用于 AWS S3/GCS/DigitalOcean。如果未提供，则不使用身份验证。", + "enum": [ + "IAM_ROLE", + "IAM_USER", + "CONNECTION_STRING" + ], + "nullable": true, + "type": "string" + }, + "azureContainerName": { + "description": "Azure Blob 存储的 Container 名称。当 type 为 azureblobstorage 时必填。", + "example": "mycontainer", + "nullable": true, + "type": "string" + }, + "compression": { + "description": "文件使用的压缩算法。", + "enum": [ + "gzip", + "gz", + "brotli", + "br", + "xz", + "LZMA", + "zstd", + "auto" + ], + "example": "auto", + "nullable": true, + "type": "string" + }, + "connectionString": { + "description": "用于 Azure Blob 存储身份验证的 connection string。当 authentication 为 CONNECTION_STRING 时必填。", + "example": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net", + "nullable": true, + "type": "string" + }, + "delimiter": { + "description": "文件中使用的分隔符。", + "example": ",", + "nullable": true, + "type": "string" + }, + "format": { + "description": "文件格式。", + "enum": [ + "JSONEachRow", + "JSONAsObject", + "CSV", + "CSVWithNames", + "Parquet", + "Avro" + ], + "type": "string" + }, + "iamRole": { + "description": "与 IAM role 身份验证配合使用的 IAM role。更多信息请参阅 ClickPipes 文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#authentication", + "example": "arn:aws:iam::123456789012:role/MyRole", + "nullable": true, + "type": "string" + }, + "isContinuous": { + "description": "如果设置为 true，管道将持续从源端读取新文件。如果设置为 false，管道只会读取这些文件一次。新文件必须按词典序上传。", + "nullable": true, + "type": "boolean" + }, + "path": { + "description": "Azure container 内文件的路径。用于 Azure Blob 存储源。您可以使用类 bash 通配符指定多个文件。更多信息请参阅有关在路径中使用通配符的文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "data/logs/*.json", + "nullable": true, + "type": "string" + }, + "queueUrl": { + "description": "用于基于事件的持续摄取的 SQS 队列 URL。提供后，文件将根据 S3 事件通知进行摄取，而不是按词典序处理。仅当 isContinuous 为 true 且身份验证不是 Public 时适用。", + "example": "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue", + "nullable": true, + "type": "string" + }, + "type": { + "description": "ObjectStorage source 的类型。", + "enum": [ + "s3", + "gcs", + "dospaces", + "azureblobstorage" + ], + "type": "string" + }, + "url": { + "description": "提供要摄取的文件路径。您可以使用类 bash 通配符指定多个文件。更多信息请参阅有关在路径中使用通配符的文档：https://clickhouse.com/docs/en/integrations/clickpipes/object-storage#limitations", + "example": "https://datasets-documentation.s3.eu-west-3.amazonaws.com/http/**.ndjson.gz", + "type": "string" + } + } + }, + "ClickPipePostRequest": { + "properties": { + "destination": { + "$ref": "#/components/schemas/ClickPipeMutateDestination" + }, + "fieldMappings": { + "description": "ClickPipe 的字段映射。请注意，映射中必须包含所有目标端列。", + "items": { + "$ref": "#/components/schemas/ClickPipeFieldMapping" + }, + "type": "array" + }, + "name": { + "description": "ClickPipe 的名称。", + "type": "string" + }, + "scaling": { + "$ref": "#/components/schemas/ClickPipeScaling" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipeSettings" + }, + "source": { + "$ref": "#/components/schemas/ClickPipePostSource" + } + } + }, + "ClickPipePostSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostObjectStorageSource" + } + ] + }, + "postgres": { + "$ref": "#/components/schemas/ClickPipeMutatePostgresSource" + }, + "validateSamples": { + "description": "验证从数据源接收的数据样本。将验证连接，以及数据的可用性和正确性。若未启用，则仅验证连接。此设置对 Postgres 管道无效，因为它们始终只验证连接和表定义。此功能为 Experimental，未来可能会被移除。", + "type": "boolean" + } + } + }, + "ClickPipePostgresPipeSettings": { + "properties": { + "allowNullableColumns": { + "description": "允许目标表使用 Nullable 列。", + "type": "boolean" + }, + "enableFailoverSlots": { + "description": "为已创建的 replication slot 启用故障转移。要求不要设置 replication slot。", + "type": "boolean" + }, + "initialLoadParallelism": { + "description": "初始加载期间并行同步的表数量。", + "type": "number" + }, + "publicationName": { + "description": "用于复制的 publication 名称。", + "type": "string" + }, + "pullBatchSize": { + "description": "每个批次拉取的行数。", + "type": "number" + }, + "replicationMode": { + "description": "管道使用的复制模式。", + "enum": [ + "cdc", + "snapshot", + "cdc_only" + ], + "type": "string" + }, + "replicationSlotName": { + "description": "用于复制的 replication slot 名称。", + "type": "string" + }, + "snapshotNumRowsPerPartition": { + "description": "每个分区执行 snapshot 时的行数。", + "type": "number" + }, + "snapshotNumberOfParallelTables": { + "description": "并行执行 snapshot 的表数量。", + "type": "number" + }, + "syncIntervalSeconds": { + "description": "从 Postgres 同步数据的时间间隔（秒）。", + "type": "number" + } + } + }, + "ClickPipePostgresPipeTableMapping": { + "properties": { + "excludedColumns": { + "description": "要从目标表中排除的列。", + "items": { + "type": "string" + }, + "type": "array" + }, + "sortingKeys": { + "description": "用作目标表排序键的有序列列表。", + "items": { + "type": "string" + }, + "type": "array" + }, + "sourceSchemaName": { + "description": "源 schema 名称。", + "type": "string" + }, + "sourceTable": { + "description": "源表名称。", + "type": "string" + }, + "tableEngine": { + "description": "用于目标表的表引擎。", + "enum": [ + "MergeTree", + "ReplacingMergeTree", + "Null" + ], + "type": "string" + }, + "targetTable": { + "description": "目标表名称。", + "type": "string" + }, + "useCustomSortingKey": { + "description": "是否对目标表使用自定义 sorting key。", + "type": "boolean" + } + } + }, + "ClickPipePostgresSource": { + "properties": { + "database": { + "description": "要连接的 Postgres 实例的数据库。", + "type": "string" + }, + "host": { + "description": "要连接的 Postgres 实例的主机。", + "type": "string" + }, + "port": { + "description": "要连接的 Postgres 实例的端口。", + "type": "number" + }, + "settings": { + "$ref": "#/components/schemas/ClickPipePostgresPipeSettings" + }, + "tableMappings": { + "description": "Postgres 管道的表映射。", + "items": { + "$ref": "#/components/schemas/ClickPipePostgresPipeTableMapping" + }, + "type": "array" + } + } + }, + "ClickPipeScaling": { + "properties": { + "concurrency": { + "deprecated": true, + "description": "期望的并发数。仅适用于 S3 管道。若设置为 0，则会根据集群内存自动调整并发数。", + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "每个副本的 CPU（毫核）。仅适用于流式管道。", + "maximum": 2000, + "minimum": 125, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "每个副本的内存（GB）。仅适用于流式管道。", + "maximum": 8, + "minimum": 0.5, + "type": "number" + }, + "replicas": { + "description": "期望的副本数。仅适用于可扩缩管道。", + "type": "integer" + } + } + }, + "ClickPipeScalingPatchRequest": { + "properties": { + "concurrency": { + "description": "要扩缩容到的并发数。用于扩缩 S3 管道。", + "maximum": 34, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "replicaCpuMillicores": { + "description": "每个副本的 CPU（以毫核为单位）。用于扩缩流式管道。", + "maximum": 2000, + "minimum": 125, + "nullable": true, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "每个副本的内存（以 GB 为单位）。用于扩缩流式管道。", + "maximum": 8, + "minimum": 0.5, + "nullable": true, + "type": "number" + }, + "replicas": { + "description": "要扩缩容到的副本数。用于扩缩 Kafka 管道。", + "maximum": 10, + "minimum": 1, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettings": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大下载线程数。最大并发下载线程数", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大 insert 线程数。最大并发 insert 线程数", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大线程数。文件处理的最大并发线程数", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小 insert 数据块大小（字节）。insert 的最小数据块大小（以字节为单位）", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "并行 Distributed insert select。并行 Distributed insert select 设置", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "并行视图处理。是否启用并发推送到 attached 视图，而不是按顺序推送", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "对象存储并发数。并发处理文件的线程数", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大文件数。单个 insert 批次中处理的最大文件数", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大 insert 字节数。单个 insert 批次中处理的字节数", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "对象存储轮询间隔。配置连续摄取查询新对象存储数据时的刷新间隔", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "使用 cluster 函数。是否使用 ClickHouse cluster 函数进行分布式处理", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "流式最大 insert 等待时间。配置将数据插入 ClickHouse 之前的最长等待时间。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsGetResponse": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大下载线程数。最大并发下载线程数。", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大插入线程数。最大并发插入线程数。", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大线程数。文件处理的最大并发线程数。", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小插入块大小（字节）。插入时数据块的最小大小（以字节为单位）。", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "并行分布式 insert select。并行分布式 insert select 设置。", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "并行视图处理。是否启用并发推送到已附加视图，而不是按顺序推送。", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "对象存储并发数。并发文件处理线程数。", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大文件数。单个插入批次中处理的最大文件数。", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大插入字节数。单个插入批次中处理的字节数。", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "对象存储轮询时间间隔。配置连续摄取查询新对象存储数据的刷新间隔。", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "使用 cluster 函数。是否使用 ClickHouse cluster 函数进行分布式处理。", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "流式最大插入等待时间。配置将数据插入 ClickHouse 之前的最长等待时间。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSettingsPutRequest": { + "properties": { + "clickhouse_max_download_threads": { + "description": "最大下载线程数。最大并发下载线程数。", + "example": 4, + "maximum": 32, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_insert_threads": { + "description": "最大插入线程数。最大并发插入线程数。", + "example": 1, + "maximum": 16, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_max_threads": { + "description": "最大线程数。文件处理的最大并发线程数。", + "example": 8, + "maximum": 64, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_min_insert_block_size_bytes": { + "description": "最小插入块大小（字节）。插入时数据块的最小大小（以字节为单位）。", + "example": 1073741824, + "maximum": 10737418240, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_distributed_insert_select": { + "description": "并行分布式 insert select。并行分布式 insert select 设置。", + "example": 2, + "maximum": 2, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "clickhouse_parallel_view_processing": { + "description": "并行视图处理。是否启用并发推送到已附加视图，而不是按顺序推送。", + "example": false, + "nullable": true, + "type": "boolean" + }, + "object_storage_concurrency": { + "description": "对象存储并发数。并发文件处理线程数。", + "example": 1, + "maximum": 35, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_file_count": { + "description": "最大文件数。单个插入批次中处理的最大文件数。", + "example": 100, + "maximum": 10000, + "minimum": 1, + "nullable": true, + "type": "integer" + }, + "object_storage_max_insert_bytes": { + "description": "最大插入字节数。单个插入批次中处理的字节数。", + "example": 10737418240, + "maximum": 53687091200, + "minimum": 10485760, + "nullable": true, + "type": "integer" + }, + "object_storage_polling_interval_ms": { + "description": "对象存储轮询时间间隔。配置连续摄取查询新对象存储数据的刷新间隔。", + "example": 30000, + "maximum": 3600000, + "minimum": 100, + "nullable": true, + "type": "integer" + }, + "object_storage_use_cluster_function": { + "description": "使用 cluster 函数。是否使用 ClickHouse cluster 函数进行分布式处理。", + "example": true, + "nullable": true, + "type": "boolean" + }, + "streaming_max_insert_wait_ms": { + "description": "流式最大插入等待时间。配置将数据插入 ClickHouse 之前的最长等待时间。", + "example": 5000, + "maximum": 60000, + "minimum": 500, + "nullable": true, + "type": "integer" + } + } + }, + "ClickPipeSource": { + "properties": { + "kafka": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKafkaSource" + } + ] + }, + "kinesis": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeKinesisSource" + } + ] + }, + "objectStorage": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipeObjectStorageSource" + } + ] + }, + "postgres": { + "nullable": true, + "oneOf": [ + { + "$ref": "#/components/schemas/ClickPipePostgresSource" + } + ] + } + } + }, + "ClickPipeStatePatchRequest": { + "properties": { + "command": { + "description": "用于更改状态的命令：'start'、'stop'、'resync'。", + "enum": [ + "start", + "stop", + "resync" + ], + "type": "string" + } + } + }, + "ClickPipesCdcScaling": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes 的 CPU（毫核）。", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes 的内存（GiB）。必须为 CPU 核心数的 4 倍。", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "ClickPipesCdcScalingPatchRequest": { + "properties": { + "replicaCpuMillicores": { + "description": "DB ClickPipes 的 CPU（以毫核为单位）。", + "example": 2000, + "maximum": 24000, + "minimum": 1000, + "multipleOf": 1000, + "type": "integer" + }, + "replicaMemoryGb": { + "description": "DB ClickPipes 的内存（以 GiB 为单位）。必须为 CPU 核心数的 4 倍。", + "example": 8, + "maximum": 96, + "minimum": 4, + "multipleOf": 4, + "type": "number" + } + } + }, + "CreateReversePrivateEndpoint": { + "properties": { + "description": { + "description": "Reverse private endpoint 描述。最大长度为 255 个字符。", + "example": "My reverse private endpoint", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK 集群身份验证类型。MSK_MULTI_VPC 类型必填。", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK 集群 ARN。MSK_MULTI_VPC 类型必填。", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "type": { + "description": "Reverse private endpoint 类型。", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC endpoint service 名称。", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC 资源配置 ID。VPC_RESOURCE 类型必填。", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC 资源共享 ARN。VPC_RESOURCE 类型必填。", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "GcpBackupBucket": { + "properties": { + "accessKeyId": { + "description": "访问密钥 ID（HMAC 密钥）", + "type": "string" + }, + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "GCP" + ], + "type": "string" + }, + "id": { + "description": "唯一的备份存储桶 ID", + "format": "uuid", + "type": "string" + } + } + }, + "GcpBackupBucketPatchRequestV1": { + "properties": { + "accessKeyId": { + "description": "访问密钥 ID（HMAC Key）", + "type": "string" + }, + "bucketPath": { + "description": "bucket 路径", + "type": "string" + }, + "bucketProvider": { + "description": "bucket 提供商", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "秘密访问密钥（HMAC secret key）", + "type": "string" + } + } + }, + "GcpBackupBucketPostRequestV1": { + "properties": { + "accessKeyId": { + "description": "访问密钥 ID（HMAC 密钥）", + "type": "string" + }, + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "GCP" + ], + "type": "string" + }, + "secretAccessKey": { + "description": "秘密访问密钥（HMAC 密钥）", + "type": "string" + } + } + }, + "GcpBackupBucketProperties": { + "properties": { + "accessKeyId": { + "description": "访问密钥 ID（HMAC 密钥）", + "type": "string" + }, + "bucketPath": { + "description": "存储桶路径", + "type": "string" + }, + "bucketProvider": { + "description": "存储桶提供商", + "enum": [ + "GCP" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "该专用终结点所在的云提供商", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "专用终结点描述", + "type": "string" + }, + "id": { + "description": "专用终结点标识符", + "type": "string" + }, + "region": { + "description": "该专用终结点所在的区域", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "InstancePrivateEndpointsPatch": { + "properties": { + "add": { + "description": "要添加的元素。在处理完“remove”部分后执行。", + "items": { + "type": "string" + }, + "type": "array" + }, + "remove": { + "description": "要移除的元素。在处理“add”部分之前执行。", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "InstanceServiceQueryApiEndpointsPostRequest": { + "properties": { + "allowedOrigins": { + "description": "允许的来源，以逗号分隔的域名列表", + "type": "string" + }, + "openApiKeys": { + "description": "服务查询端点的版本", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "角色", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "Invitation": { + "properties": { + "createdAt": { + "description": "邀请的创建时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "email": { + "description": "被邀请用户的电子邮箱。只有使用此电子邮箱的用户才能通过该邀请加入。该电子邮箱以小写形式存储。", + "format": "email", + "type": "string" + }, + "expireAt": { + "description": "邀请过期的时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "唯一邀请 ID。", + "format": "uuid", + "type": "string" + }, + "role": { + "description": "成员在组织中的角色。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "InvitationPostRequest": { + "properties": { + "email": { + "description": "受邀用户的电子邮箱。只有使用该电子邮箱的用户才能通过邀请加入。该电子邮箱将以小写形式存储。", + "format": "email", + "type": "string" + }, + "role": { + "description": "成员在组织中的角色。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "IpAccessListEntry": { + "properties": { + "description": { + "description": "允许从其访问的 IPv4 地址或 IPv4 CIDR 的可选描述", + "type": "string" + }, + "source": { + "description": "IP 或 CIDR", + "type": "string" + } + } + }, + "IpAccessListPatch": { + "properties": { + "add": { + "description": "要添加的元素。在处理完“remove”部分后执行。", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "remove": { + "description": "要移除的元素。在处理“add”部分之前执行。", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + } + } + }, + "Member": { + "properties": { + "email": { + "description": "成员在个人用户 profile 中设置的电子邮箱。", + "format": "email", + "type": "string" + }, + "joinedAt": { + "description": "成员加入组织的时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "成员在个人用户 profile 中设置的名称。", + "type": "string" + }, + "role": { + "description": "成员在组织中的角色。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + }, + "userId": { + "description": "唯一用户 ID。如果用户属于多个组织，此 ID 也保持不变。", + "type": "string" + } + } + }, + "MemberPatchRequest": { + "properties": { + "role": { + "description": "成员在组织中的角色。", + "enum": [ + "admin", + "developer" + ], + "type": "string" + } + } + }, + "MskIamUser": { + "properties": { + "accessKeyId": { + "description": "IAM 访问密钥 ID。", + "type": "string" + }, + "secretKey": { + "description": "IAM 密钥。", + "type": "string" + } + } + }, + "Organization": { + "properties": { + "byocConfig": { + "description": "organization 的 BYOC 配置", + "items": { + "$ref": "#/components/schemas/ByocConfig" + }, + "type": "array" + }, + "createdAt": { + "description": "organization 的创建时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "唯一的 Organization ID。", + "format": "uuid", + "type": "string" + }, + "name": { + "description": "organization 的名称。", + "type": "string" + }, + "privateEndpoints": { + "description": "organization 的专用终结点列表", + "items": { + "$ref": "#/components/schemas/OrganizationPrivateEndpoint" + }, + "type": "array" + } + } + }, + "OrganizationCloudRegionPrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "您在 VPC 中使用 AWS（Service Name）或 GCP（Target Service）资源创建的 interface endpoint 的唯一标识符", + "type": "string" + } + } + }, + "OrganizationPatchPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "专用终结点所在的云提供商", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "专用终结点的可选描述", + "type": "string" + }, + "id": { + "description": "专用终结点标识符", + "type": "string" + }, + "region": { + "description": "专用终结点所在的区域", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPatchRequest": { + "properties": { + "name": { + "description": "组织名称。", + "type": "string" + }, + "privateEndpoints": { + "$ref": "#/components/schemas/OrganizationPrivateEndpointsPatch" + } + } + }, + "OrganizationPrivateEndpoint": { + "properties": { + "cloudProvider": { + "description": "专用终结点所在的云提供商", + "enum": [ + "gcp", + "aws", + "azure" + ], + "type": "string" + }, + "description": { + "description": "专用终结点的描述", + "type": "string" + }, + "id": { + "description": "专用终结点标识符", + "type": "string" + }, + "region": { + "description": "专用终结点所在的区域", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + } + } + }, + "OrganizationPrivateEndpointsPatch": { + "properties": { + "add": { + "deprecated": true, + "description": "要添加的元素。在处理完“remove”部分后执行。如需修改专用终结点，请改用 `Update Service Basic Details` 端点。", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + }, + "remove": { + "description": "要移除的元素。在处理“add”部分之前执行。", + "items": { + "$ref": "#/components/schemas/OrganizationPatchPrivateEndpoint" + }, + "type": "array" + } + } + }, + "PLAIN": { + "properties": { + "password": { + "description": "密码。", + "type": "string" + }, + "username": { + "description": "用户名。", + "type": "string" + } + } + }, + "PrivateEndpointConfig": { + "properties": { + "endpointServiceId": { + "description": "您在 VPC 中使用 AWS（Service Name）、GCP（Target Service）或 AZURE（Private Link Service）资源创建的接口端点的唯一标识符", + "type": "string" + }, + "privateDnsHostname": { + "description": "您创建的 VPC 的私有 DNS 主机名", + "type": "string" + } + } + }, + "ReversePrivateEndpoint": { + "properties": { + "description": { + "description": "反向私网端点描述。最大长度为 255 个字符。", + "example": "My reverse private endpoint", + "type": "string" + }, + "dnsNames": { + "description": "反向私网端点的内部 DNS name 列表。", + "items": { + "type": "string" + }, + "type": "array" + }, + "endpointId": { + "description": "反向私网端点的 Endpoint ID。", + "example": "vpce-12345678901234567", + "type": "string" + }, + "id": { + "description": "反向私网端点 ID。", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "mskAuthentication": { + "description": "MSK 集群身份验证类型。MSK_MULTI_VPC 类型必填。", + "enum": [ + "SASL_IAM", + "SASL_SCRAM" + ], + "example": "SASL_IAM", + "nullable": true, + "type": "string" + }, + "mskClusterArn": { + "description": "MSK 集群 ARN。MSK_MULTI_VPC 类型必填。", + "example": "arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster", + "nullable": true, + "type": "string" + }, + "privateDnsNames": { + "description": "反向私网端点的 private DNS name 列表。", + "items": { + "type": "string" + }, + "type": "array" + }, + "serviceId": { + "description": "与反向私网端点关联的 ClickHouse 服务 ID。", + "example": "12345678-1234-1234-1234-123456789012", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "反向私网端点状态。", + "enum": [ + "Unknown", + "Provisioning", + "Deleting", + "Ready", + "Failed", + "PendingAcceptance", + "Rejected", + "Expired" + ], + "example": "Ready", + "type": "string" + }, + "type": { + "description": "反向私网端点类型。", + "enum": [ + "VPC_ENDPOINT_SERVICE", + "VPC_RESOURCE", + "MSK_MULTI_VPC" + ], + "example": "VPC_ENDPOINT_SERVICE", + "type": "string" + }, + "vpcEndpointServiceName": { + "description": "VPC endpoint service 名称。", + "example": "com.amazonaws.vpce.us-east-1.vpce-svc-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceConfigurationId": { + "description": "VPC 资源配置 ID。VPC_RESOURCE 类型必填。", + "example": "rcfg-12345678901234567", + "nullable": true, + "type": "string" + }, + "vpcResourceShareArn": { + "description": "VPC 资源共享 ARN。VPC_RESOURCE 类型必填。", + "example": "arn:aws:ram:us-east-1:123456789012:resource-share/share-12345678901234567", + "nullable": true, + "type": "string" + } + } + }, + "ServicPrivateEndpointePostRequest": { + "properties": { + "description": { + "description": "私网端点说明", + "type": "string" + }, + "id": { + "description": "私网端点标识符", + "type": "string" + } + } + }, + "Service": { + "properties": { + "availablePrivateEndpointIds": { + "description": "可附加到该服务的可用私网端点 ID 列表", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "这是为自备 Cloud (BYOC) 设置区域后返回的 ID。指定 byocId 参数时，还必须同时提供 minReplicaMemoryGb 和 maxReplicaGb 参数，并且其值必须为以下规格之一：48、116、172、232。", + "type": "string" + }, + "clickhouseVersion": { + "description": "服务的 ClickHouse 版本。", + "type": "string" + }, + "complianceType": { + "description": "服务的监管合规类型。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "服务创建时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "包含此服务的数据仓库", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "用于磁盘加密的可选 Role", + "type": "string" + }, + "encryptionKey": { + "description": "可选的客户提供磁盘加密密钥", + "type": "string" + }, + "encryptionRoleId": { + "description": "用于加密的 IAM role ID。仅当 hasTransparentDataEncryption 为 true 时可用。", + "type": "string" + }, + "endpoints": { + "description": "所有服务端点的列表。", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "如果服务应启用 Transparent Data Encryption (TDE)，则为 true。TDE 仅适用于 ENTERPRISE organization 层级，并且只能在创建服务时启用。", + "type": "boolean" + }, + "iamRole": { + "description": "用于访问 S3 中对象的 IAM role", + "type": "string" + }, + "id": { + "description": "服务的唯一 ID。", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "如果设置为 true，则服务在空闲时允许缩容至零。默认为 true。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "设置最小空闲超时时间（分钟）。必须 >= 5 分钟。", + "type": "number" + }, + "ipAccessList": { + "description": "允许访问该服务的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "如果此服务是数据仓库中的主服务，则为 true", + "type": "boolean" + }, + "isReadonly": { + "description": "如果此服务为只读，则为 true。仅当提供 dataWarehouseId 时，才可以为只读。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "自动扩缩容期间每个副本的最大总内存（Gb）。必须是 4 的倍数；对于非付费服务，小于或等于 120*；对于付费服务，小于或等于 356*。* - 最大副本大小取决于所选区域中云提供商硬件的可用性。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "已弃用——对于副本数量不是默认值的服务，此值并不准确。自动扩缩容期间三个工作线程的最大内存（Gb）。仅适用于 'production' 服务。对于非付费服务，必须是 12 的倍数且小于或等于 360；对于付费服务，小于或等于 1068。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "自动扩缩容期间每个副本的最小总内存（Gb）。必须是 4 的倍数，且大于或等于 8。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "已弃用——对于副本数量不是默认值的服务，此值并不准确。自动扩缩容期间三个工作线程的最小内存（Gb）。仅适用于 'production' 服务。必须是 12 的倍数，且大于或等于 24。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "服务名称。可包含空格的字母数字字符串，最长 50 个字符。", + "type": "string" + }, + "numReplicas": { + "description": "服务的副本数量。对于仓库中的第一个服务，副本数量必须在 2 到 20 之间。在现有仓库中创建的服务，副本数量最低可以为 1。根据您的 organization 层级，还可能存在其他限制。BASIC 层级默认为 1，SCALE 和 ENTERPRISE 层级默认为 3。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "私网端点列表", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "自定义实例 profile。仅适用于 ENTERPRISE organization 层级。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "云提供商", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "服务所在区域。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "如果您希望在新的 ClickHouse 发行版发布后尽快获取，请选择 fast。这样您会更快获得新功能，但出现 bug 的风险也更高。如果您希望延后接收发行版，以便有更多时间进行测试，请选择 slow。此功能仅适用于 production 服务。默认值为常规发布渠道。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "服务的当前状态。", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "对于 BASIC、SCALE 和 ENTERPRISE organization 层级，此字段已弃用。服务层级：'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'、'dedicated_standard_n2d_standard_32_16SSD'、'dedicated_standard_n2d_standard_64_24SSD'。Production 服务支持扩缩容，Development 服务为固定大小。Azure 服务不支持 Development 层级。", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "服务使用的 Transparent Data Encryption 密钥 ID。仅当 hasTransparentDataEncryption 为 true 时可用。", + "type": "string" + } + } + }, + "ServiceEndpoint": { + "properties": { + "host": { + "description": "服务主机名", + "type": "string" + }, + "port": { + "description": "端口号", + "type": "number" + }, + "protocol": { + "description": "端点协议：'https'、'nativesecure'、'mysql'。", + "enum": [ + "https", + "nativesecure", + "mysql" + ], + "example": "mysql", + "type": "string" + }, + "username": { + "description": "端点的可选用户名", + "nullable": true, + "type": "string" + } + } + }, + "ServiceEndpointChange": { + "properties": { + "enabled": { + "description": "启用或禁用该端点", + "type": "boolean" + }, + "protocol": { + "description": "端点协议", + "enum": [ + "mysql" + ], + "example": "mysql", + "type": "string" + } + } + }, + "ServicePasswordPatchRequest": { + "properties": { + "newDoubleSha1Hash": { + "description": "MySQL protocol 使用的可选 double SHA1 密码哈希。如果未提供 newPasswordHash，则会忽略此 key，并使用生成的密码。算法：echo -n \"yourpassword\" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'", + "type": "string" + }, + "newPasswordHash": { + "description": "可选的密码哈希。用于避免通过网络传输密码。如果未提供，则会生成一个新密码，并在响应中返回。否则将使用此哈希。算法：echo -n \"yourpassword\" | sha256sum | tr -d '-' | xxd -r -p | base64", + "type": "string" + } + } + }, + "ServicePasswordPatchResponse": { + "properties": { + "password": { + "description": "新的服务密码。仅当请求中没有 'newPasswordHash' 时提供", + "type": "string" + } + } + }, + "ServicePatchRequest": { + "properties": { + "endpoints": { + "description": "要更改的服务端点列表", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "ipAccessList": { + "$ref": "#/components/schemas/IpAccessListPatch" + }, + "name": { + "description": "服务名称。最多 50 个字符的字母数字字符串，可包含空格。", + "type": "string" + }, + "privateEndpointIds": { + "$ref": "#/components/schemas/InstancePrivateEndpointsPatch" + }, + "releaseChannel": { + "description": "如果希望在新的 ClickHouse 发行版发布后立即获取，请选择 fast。这样你会更快用上新功能，但出现 bug 的风险也更高。如果希望延后接收发行版，以便有更多时间进行测试，请选择 slow。此功能仅适用于 'production' 服务。默认值为 regular release channel。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "要轮换的密钥 ID", + "type": "string" + } + } + }, + "ServicePostRequest": { + "properties": { + "backupId": { + "description": "可选的 backup ID，用作新服务的初始状态。使用时，新实例的区域和层级必须与原始实例的值相同。", + "format": "uuid", + "type": "string" + }, + "byocId": { + "description": "这是为自备 Cloud (BYOC) 设置区域后返回的 ID。指定 byocId 参数时，还必须同时提供 minReplicaMemoryGb 和 maxReplicaGb 参数，且其值必须为以下规格之一：48、116、172、232。", + "type": "string" + }, + "complianceType": { + "description": "服务的监管合规类型。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "dataWarehouseId": { + "description": "包含此服务的数据仓库", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "用于磁盘加密的可选角色", + "type": "string" + }, + "encryptionKey": { + "description": "可选的客户提供磁盘加密密钥", + "type": "string" + }, + "endpoints": { + "description": "要启用或禁用的服务端点列表", + "items": { + "$ref": "#/components/schemas/ServiceEndpointChange" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "如果服务应启用 Transparent Data Encryption (TDE)，则为 true。TDE 仅适用于 ENTERPRISE 组织层级，且只能在创建服务时启用。", + "type": "boolean" + }, + "idleScaling": { + "description": "设置为 true 时，服务在空闲时可缩容至零。默认为 true。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "设置最小空闲超时时间（分钟）。必须 >= 5 分钟。", + "type": "number" + }, + "ipAccessList": { + "description": "允许访问该服务的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isReadonly": { + "description": "如果此服务为只读，则为 true。仅当提供 dataWarehouseId 时，服务才能为只读。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "自动扩缩容期间每个副本的最大总内存（单位：Gb）。必须是 4 的倍数；对于非付费服务，小于或等于 120*；对于付费服务，小于或等于 356*。* - 最大副本大小取决于所选区域中云提供商的硬件可用性。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于副本数不是默认值的服务，此值不准确。自动扩缩容期间三个工作线程的最大内存（单位：Gb）。仅适用于 'production' 服务。对于非付费服务，必须是 12 的倍数且小于或等于 360；对于付费服务，小于或等于 1068。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "自动扩缩容期间每个副本的最小总内存（单位：Gb）。必须是 4 的倍数，且大于或等于 8。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于副本数不是默认值的服务，此值不准确。自动扩缩容期间三个工作线程的最小内存（单位：Gb）。仅适用于 'production' 服务。必须是 12 的倍数，且大于或等于 24。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "服务名称。由字母、数字和空格组成，最多 50 个字符。", + "type": "string" + }, + "numReplicas": { + "description": "服务的副本数。对于仓库中的第一个服务，副本数必须介于 2 到 20 之间。在现有仓库中创建的服务，副本数最少可为 1。根据组织的层级，可能还会有进一步限制。基础版层级默认值为 1，SCALE 和 ENTERPRISE 层级默认值为 3。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "deprecated": true, + "description": "要将服务与专用终结点关联，请先创建服务，然后使用 `Update Service Basic Details` 端点修改专用终结点。", + "items": { + "type": "string" + }, + "type": "array" + }, + "privatePreviewTermsChecked": { + "description": "接受私有预览条款和条件。仅在私有预览情况下，为组织创建第一个服务时才需要这样做", + "type": "boolean" + }, + "profile": { + "description": "自定义实例 profile。仅适用于 ENTERPRISE 组织层级。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "云提供商", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "服务区域。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "如果希望在新的 ClickHouse 发行版一经推出就尽快获取，请选择 fast。这样可以更快获得新功能，但出现 bug 的风险也更高。如果希望延后接收发行版，以留出更多测试时间，请选择 slow。此功能仅适用于生产服务。默认值为常规发布渠道。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "对于基础版、SCALE 和 ENTERPRISE 组织层级，此字段已弃用。服务层级：'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'、'dedicated_standard_n2d_standard_32_16SSD'、'dedicated_standard_n2d_standard_64_24SSD'。'production' 服务支持扩缩容，'development' 为固定大小。Azure 服务不支持 Development 层级", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + } + } + }, + "ServicePostResponse": { + "properties": { + "password": { + "description": "新创建服务的密码。", + "type": "string" + }, + "service": { + "$ref": "#/components/schemas/Service" + } + } + }, + "ServiceQueryAPIEndpoint": { + "properties": { + "allowedOrigins": { + "description": "允许的来源，以逗号分隔的域名列表形式表示", + "type": "string" + }, + "id": { + "description": "服务查询端点的 ID", + "type": "string" + }, + "openApiKeys": { + "description": "可访问服务查询端点的 OpenAPI 密钥列表", + "items": { + "type": "string" + }, + "type": "array" + }, + "roles": { + "description": "可访问服务查询端点的角色列表", + "items": { + "enum": [ + "sql_console_read_only", + "sql_console_admin" + ], + "type": "string" + }, + "type": "array" + } + } + }, + "ServiceReplicaScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "设为 true 时，服务在空闲时可缩容至零。默认为 True。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "设置最小空闲超时时间（分钟）。必须 >= 5 分钟。", + "type": "number" + }, + "maxReplicaMemoryGb": { + "description": "单个副本的最大自动扩缩容内存（Gb）。仅适用于 'production' 服务。对于非付费服务，必须是 4 的倍数且小于或等于 120；对于付费服务，则必须小于或等于 356。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "单个副本的最小自动扩缩容内存（Gb）。仅适用于 'production' 服务。必须是 4 的倍数，且大于或等于 8。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "numReplicas": { + "description": "服务的副本数。对于仓库中的第一个服务，副本数必须在 2 到 20 之间。在现有仓库中创建的服务，副本数最低可为 1。根据您 organization 的层级，还可能存在其他限制。默认情况下，BASIC 层级为 1，SCALE 和 ENTERPRISE 层级为 3。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchRequest": { + "properties": { + "idleScaling": { + "description": "设置为 true 时，服务在空闲时可缩容至零。默认为 true。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "设置最小空闲超时时间（分钟）。必须 >= 5 分钟。", + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于使用非默认副本数的服务，此值不准确。自动扩缩容期间三个工作线程的最大内存（GB）。仅适用于 'production' 服务。对于非付费服务，必须是 12 的倍数且小于等于 360；对于付费服务，必须小于等于 1068。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于使用非默认副本数的服务，此值不准确。自动扩缩容期间三个工作线程的最小内存（GB）。仅适用于 'production' 服务。必须是 12 的倍数，且大于等于 24。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "numReplicas": { + "description": "服务的副本数。对于仓库中的第一个服务，副本数必须介于 2 到 20 之间。在现有仓库中创建的服务，副本数最低可为 1。根据你的组织层级，可能还会有其他限制。BASIC 层级默认值为 1，SCALE 和 ENTERPRISE 层级默认值为 3。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + } + } + }, + "ServiceScalingPatchResponse": { + "properties": { + "availablePrivateEndpointIds": { + "description": "可附加到该服务的可用私网端点 ID 列表", + "items": { + "type": "string" + }, + "type": "array" + }, + "byocId": { + "description": "这是为自备 Cloud (BYOC) 设置区域后返回的 ID。指定 byocId 参数时，还必须同时提供 minReplicaMemoryGb 和 maxReplicaGb 参数，且其值必须为以下规格之一：48、116、172、232。", + "type": "string" + }, + "clickhouseVersion": { + "description": "服务的 ClickHouse 版本。", + "type": "string" + }, + "complianceType": { + "description": "服务的监管合规类型。", + "enum": [ + "hipaa", + "pci" + ], + "type": "string" + }, + "createdAt": { + "description": "服务创建时间戳。ISO-8601。", + "format": "date-time", + "type": "string" + }, + "dataWarehouseId": { + "description": "包含该服务的数据仓库", + "type": "string" + }, + "encryptionAssumedRoleIdentifier": { + "description": "用于磁盘加密的可选角色", + "type": "string" + }, + "encryptionKey": { + "description": "可选的客户提供磁盘加密密钥", + "type": "string" + }, + "encryptionRoleId": { + "description": "用于加密的 IAM role ID。仅当 hasTransparentDataEncryption 为 true 时可用。", + "type": "string" + }, + "endpoints": { + "description": "所有服务端点的列表。", + "items": { + "$ref": "#/components/schemas/ServiceEndpoint" + }, + "type": "array" + }, + "hasTransparentDataEncryption": { + "description": "如果该服务应启用透明数据加密 (TDE)，则为 True。TDE 仅适用于 ENTERPRISE organization 层级，并且只能在创建服务时启用。", + "type": "boolean" + }, + "iamRole": { + "description": "用于访问 S3 中对象的 IAM role", + "type": "string" + }, + "id": { + "description": "唯一的服务 ID。", + "format": "uuid", + "type": "string" + }, + "idleScaling": { + "description": "设置为 true 时，服务在空闲时可缩容至零。默认为 true。", + "type": "boolean" + }, + "idleTimeoutMinutes": { + "description": "设置最小空闲超时时间（分钟）。必须 >= 5 分钟。", + "type": "number" + }, + "ipAccessList": { + "description": "允许访问该服务的 IP 地址列表", + "items": { + "$ref": "#/components/schemas/IpAccessListEntry" + }, + "type": "array" + }, + "isPrimary": { + "description": "如果该服务是数据仓库中的主服务，则为 True", + "type": "boolean" + }, + "isReadonly": { + "description": "如果该服务为只读，则为 True。只有在提供了 dataWarehouseId 时，该服务才能设为只读。", + "type": "boolean" + }, + "maxReplicaMemoryGb": { + "description": "单个副本自动扩缩容的最大内存（GB）。仅适用于 'production' 服务。对于非付费服务，必须是 4 的倍数且小于等于 120；对于付费服务，必须小于等于 356。", + "example": 120, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "maxTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于使用非默认副本数的服务，此值不准确。自动扩缩容期间三个工作线程的最大内存（GB）。仅适用于 'production' 服务。对于非付费服务，必须是 12 的倍数且小于等于 360；对于付费服务，必须小于等于 1068。", + "example": 360, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "minReplicaMemoryGb": { + "description": "单个副本自动扩缩容的最小内存（GB）。仅适用于 'production' 服务。必须是 4 的倍数，且大于等于 8。", + "example": 16, + "maximum": 356, + "minimum": 8, + "multipleOf": 4, + "type": "number" + }, + "minTotalMemoryGb": { + "deprecated": true, + "description": "已弃用 - 对于使用非默认副本数的服务，此值不准确。自动扩缩容期间三个工作线程的最小内存（GB）。仅适用于 'production' 服务。必须是 12 的倍数，且大于等于 24。", + "example": 48, + "maximum": 1068, + "minimum": 24, + "multipleOf": 12, + "type": "number" + }, + "name": { + "description": "服务名称。最多 50 个字符的字母数字字符串，可包含空格。", + "type": "string" + }, + "numReplicas": { + "description": "服务的副本数。对于仓库中的第一个服务，副本数必须介于 2 到 20 之间。在现有仓库中创建的服务，副本数最低可为 1。根据你的组织层级，可能还会有其他限制。BASIC 层级默认值为 1，SCALE 和 ENTERPRISE 层级默认值为 3。", + "example": 3, + "maximum": 20, + "minimum": 1, + "type": "number" + }, + "privateEndpointIds": { + "description": "私网端点列表", + "items": { + "type": "string" + }, + "type": "array" + }, + "profile": { + "description": "自定义实例 profile。仅适用于 ENTERPRISE organization 层级。", + "enum": [ + "v1-default", + "v1-highmem-xs", + "v1-highmem-s", + "v1-highmem-m", + "v1-highmem-l", + "v1-highmem-xl", + "v1-highcpu-s", + "v1-highcpu-m", + "v1-highcpu-l", + "v1-highcpu-xl" + ], + "type": "string" + }, + "provider": { + "description": "云提供商", + "enum": [ + "aws", + "gcp", + "azure" + ], + "type": "string" + }, + "region": { + "description": "服务区域。", + "enum": [ + "ap-northeast-1", + "ap-south-1", + "ap-southeast-1", + "ap-southeast-2", + "eu-central-1", + "eu-west-1", + "eu-west-2", + "me-central-1", + "us-east-1", + "us-east-2", + "us-west-2", + "us-east1", + "us-central1", + "europe-west4", + "asia-southeast1", + "eastus", + "eastus2", + "westus3", + "germanywestcentral" + ], + "type": "string" + }, + "releaseChannel": { + "description": "如果您希望在新的 ClickHouse 发行版一经发布即可获取，请选择 fast。这样您可以更快使用新功能，但出现 bug 的风险也更高。如果您希望延后接收发行版，以便有更多时间进行测试，请选择 slow。此功能仅适用于 production 服务。default 为常规发布渠道。", + "enum": [ + "slow", + "default", + "fast" + ], + "type": "string" + }, + "state": { + "description": "服务的当前状态。", + "enum": [ + "starting", + "stopping", + "terminating", + "awaking", + "partially_running", + "provisioning", + "running", + "stopped", + "terminated", + "degraded", + "failed", + "idle" + ], + "type": "string" + }, + "tier": { + "deprecated": true, + "description": "已弃用，仅适用于 BASIC、SCALE 和 ENTERPRISE 组织层级。服务层级：'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'、'dedicated_standard_n2d_standard_32_16SSD'、'dedicated_standard_n2d_standard_64_24SSD'。Production 服务支持扩缩容，Development 为固定大小。Azure 服务不支持 Development 层级", + "enum": [ + "development", + "production", + "dedicated_high_mem", + "dedicated_high_cpu", + "dedicated_standard", + "dedicated_standard_n2d_standard_4", + "dedicated_standard_n2d_standard_8", + "dedicated_standard_n2d_standard_32", + "dedicated_standard_n2d_standard_128", + "dedicated_standard_n2d_standard_32_16SSD", + "dedicated_standard_n2d_standard_64_24SSD" + ], + "type": "string" + }, + "transparentDataEncryptionKeyId": { + "description": "该服务使用的透明数据加密密钥 ID。仅当 hasTransparentDataEncryption 为 true 时可用。", + "type": "string" + } + } + }, + "ServiceStatePatchRequest": { + "properties": { + "command": { + "description": "用于更改状态的命令：'start'、'stop'。", + "enum": [ + "start", + "stop" + ], + "type": "string" + } + } + }, + "UsageCost": { + "properties": { + "costs": { + "$ref": "#/components/schemas/UsageCostRecord" + }, + "grandTotalCHC": { + "description": "以 ClickHouse Credits (CHCs) 计的总使用成本。", + "type": "number" + } + } + }, + "UsageCostMetrics": { + "properties": { + "backupCHC": { + "description": "以 ClickHouse Credits（CHCs）计的备份成本。适用于 dataWarehouse 实体。", + "type": "number" + }, + "computeCHC": { + "description": "以 ClickHouse Credits（CHCs）计的计算成本。适用于 service 和 clickpipe 实体。", + "type": "number" + }, + "dataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的数据传输成本。适用于 clickpipe 实体。", + "type": "number" + }, + "initialLoadCHC": { + "description": "以 ClickHouse Credits（CHCs）计的初始加载和重新同步成本。适用于 clickpipe 实体。", + "type": "number" + }, + "interRegionTier1DataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的 tier1 跨区域数据传输成本。适用于 service 实体。", + "type": "number" + }, + "interRegionTier2DataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的 tier2 跨区域数据传输成本。适用于 service 实体。", + "type": "number" + }, + "interRegionTier3DataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的 tier3 跨区域数据传输成本。适用于 service 实体。", + "type": "number" + }, + "interRegionTier4DataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的 tier4 跨区域数据传输成本。适用于 service 实体。", + "type": "number" + }, + "publicDataTransferCHC": { + "description": "以 ClickHouse Credits（CHCs）计的数据传输成本。适用于 service 实体。", + "type": "number" + }, + "storageCHC": { + "description": "以 ClickHouse Credits（CHCs）计的存储成本。适用于 dataWarehouse 实体。", + "type": "number" + } + } + }, + "UsageCostRecord": { + "properties": { + "dataWarehouseId": { + "description": "此实体所属的 dataWarehouse 的 ID（或该实体本身的 ID）。", + "format": "uuid", + "type": "string" + }, + "date": { + "description": "使用日期。ISO-8601 日期，基于 UTC 时区。", + "format": "date", + "type": "string" + }, + "entityId": { + "description": "实体的唯一 ID。", + "format": "uuid", + "type": "string" + }, + "entityName": { + "description": "实体名称。", + "type": "string" + }, + "entityType": { + "description": "实体类型。", + "enum": [ + "datawarehouse", + "service", + "clickpipe" + ], + "type": "string" + }, + "locked": { + "description": "为 true 时，该记录不可变。未锁定的记录在被锁定前仍可能发生变化。", + "type": "boolean" + }, + "metrics": { + "$ref": "#/components/schemas/UsageCostMetrics" + }, + "serviceId": { + "description": "此实体所属的 service 的 ID（或该实体本身的 ID）。对于 dataWarehouse 实体，该值设为 null。", + "format": "uuid", + "nullable": true, + "type": "string" + }, + "totalCHC": { + "description": "此实体以 ClickHouse Credits (CHCs) 计的总使用成本。", + "type": "number" + } + } + } + }, + "securitySchemes": { + "basicAuth": { + "description": "使用从 ClickHouse Cloud 控制台获取的 key ID 和 key secret：https://clickhouse.com/docs/cloud/manage/openapi", + "scheme": "basic", + "type": "http" + } + } + }, + "info": { + "contact": { + "email": "support@clickhouse.com", + "name": "ClickHouse Support", + "url": "https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-299828" + }, + "title": "OpenAPI spec for ClickHouse Cloud", + "version": "1.0" + }, + "openapi": "3.0.1", + "paths": { + "/v1/organizations": { + "get": { + "description": "返回一个列表，其中仅包含与请求中 API key 关联的组织。", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Organization" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的情况，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取可用的组织列表", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}": { + "get": { + "description": "返回单个组织的详细信息。要获取这些详细信息，auth key 必须属于该组织。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取组织详情", + "tags": [ + "Organization" + ] + }, + "patch": { + "description": "更新组织字段。需要具有 ADMIN auth key role。", + "parameters": [ + { + "description": "要更新的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Organization" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "更新组织详情", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities": { + "get": { + "description": "返回所有组织活动的列表。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "搜索的开始日期", + "in": "query", + "name": "from_date", + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "搜索的结束日期", + "in": "query", + "name": "to_date", + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Activity" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "组织活动列表", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/activities/{activityId}": { + "get": { + "description": "按 ID 返回单个组织活动。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求活动的 ID。", + "in": "path", + "name": "activityId", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Activity" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的原因，server 无法或不愿处理该请求。" + } + }, + "summary": "组织活动", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure": { + "post": { + "description": "在组织中创建新的 BYOC 基础设施。返回新创建基础设施的配置。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ByocInfrastructurePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ByocConfig" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "创建 BYOC 基础设施", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}": { + "delete": { + "description": "从组织中移除 BYOC 基础设施", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求的 BYOC 基础设施 ID", + "in": "path", + "name": "byocInfrastructureId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "删除 BYOC 基础设施", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/invitations": { + "get": { + "description": "返回所有 organization 邀请的列表。", + "parameters": [ + { + "description": "所请求 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Invitation" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细error描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "列出所有邀请", + "tags": [ + "User management" + ] + }, + "post": { + "description": "创建 organization 邀请。", + "parameters": [ + { + "description": "要邀请用户加入的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvitationPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细error描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "创建邀请", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/invitations/{invitationId}": { + "delete": { + "description": "删除单个组织邀请。", + "parameters": [ + { + "description": "拥有该邀请的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "删除组织邀请", + "tags": [ + "User management" + ] + }, + "get": { + "description": "返回单个 organization 邀请的详细信息。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "invitationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Invitation" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "获取邀请详情", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/keys": { + "get": { + "description": "返回该 organization 中所有密钥的列表。", + "parameters": [ + { + "description": "请求的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ApiKey" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取所有密钥列表", + "tags": [ + "OpenAPI" + ] + }, + "post": { + "description": "创建新的 API key。", + "parameters": [ + { + "description": "将拥有该密钥的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKeyPostResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "创建密钥", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/keys/{keyId}": { + "delete": { + "description": "删除 API key。只能删除未用于对当前活动请求进行身份验证的 key。", + "parameters": [ + { + "description": "拥有该 key 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要删除的 key 的 ID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP status 代码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP status 代码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "删除密钥", + "tags": [ + "OpenAPI" + ] + }, + "get": { + "description": "返回单个密钥的详细信息。", + "parameters": [ + { + "description": "请求的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "请求的密钥 ID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取密钥详情", + "tags": [ + "OpenAPI" + ] + }, + "patch": { + "description": "更新 API key 的属性。", + "parameters": [ + { + "description": "拥有该密钥的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新的密钥 ID。", + "in": "path", + "name": "keyId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ApiKey" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP status 代码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "更新密钥", + "tags": [ + "OpenAPI" + ] + } + }, + "/v1/organizations/{organizationId}/members": { + "get": { + "description": "返回 organization 中所有成员的列表。", + "parameters": [ + { + "description": "请求的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Member" + }, + "type": "array" + }, + "status": { + "description": "HTTP status 代码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP status 代码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "列出组织成员", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/members/{userId}": { + "delete": { + "description": "从 organization 中移除用户", + "parameters": [ + { + "description": "所请求 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求用户的 ID。", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细error描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "移除组织成员", + "tags": [ + "User management" + ] + }, + "get": { + "description": "返回单个 organization 成员的详细信息。", + "parameters": [ + { + "description": "该成员所属的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "请求的用户 ID。", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTP status 代码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP status 代码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "获取成员详情", + "tags": [ + "User management" + ] + }, + "patch": { + "description": "更新 organization 成员的 Role。", + "parameters": [ + { + "description": "该成员所属的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要修补的用户 ID", + "in": "path", + "name": "userId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Member" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细error描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "更新组织成员", + "tags": [ + "User management" + ] + } + }, + "/v1/organizations/{organizationId}/privateEndpointConfig": { + "get": { + "deprecated": true, + "description": "已弃用。请按照[文档](https://clickhouse.com/docs/manage/security/aws-privatelink#add-endpoint-id-to-services-allow-list)中的更新流程进行操作。", + "parameters": [ + { + "description": "所请求的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "云提供商标识符。取值为 aws、gcp 或 azure 之一。", + "in": "query", + "name": "cloud_provider", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "特定云提供商内的区域标识符。", + "in": "query", + "name": "region_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/OrganizationCloudRegionPrivateEndpointConfig" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取组织在云提供商某个区域中的专用终结点配置", + "tags": [ + "Organization" + ] + } + }, + "/v1/organizations/{organizationId}/prometheus": { + "get": { + "description": "返回组织中所有 service 的 Prometheus 指标。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "返回经过过滤的 Prometheus 指标列表。", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取组织指标", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services": { + "get": { + "description": "返回组织中所有 service 的列表。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "检索 resource 时要应用的过滤条件。目前仅支持按 resource 标签过滤。", + "example": "tag:Environment=Production&filter=tag:Department=Engineering&filter=tag:isActive", + "in": "query", + "name": "filter", + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Service" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "组织服务列表", + "tags": [ + "Service" + ] + }, + "post": { + "description": "在 organization 中创建一个新的 service，并返回当前 service 状态以及用于访问该 service 的密码。该 service 会异步启动。", + "parameters": [ + { + "description": "将拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePostResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client 错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "创建新服务", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}": { + "delete": { + "description": "删除该 service。该 service 必须处于已停止状态，并会在调用此 method 后异步删除。", + "parameters": [ + { + "description": "拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要删除的 service 的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "删除服务", + "tags": [ + "Service" + ] + }, + "get": { + "description": "返回属于该 organization 的 service", + "parameters": [ + { + "description": "拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求 service 的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client 错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取服务详情", + "tags": [ + "Service" + ] + }, + "patch": { + "description": "更新 service 的基本信息，例如 service 名称或 IP Access List。", + "parameters": [ + { + "description": "拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新的 service 的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细 error 描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client 错误的问题，server 无法或不会处理该请求。" + } + }, + "summary": "更新服务基础信息", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration": { + "get": { + "description": "返回服务的备份配置。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取服务备份配置", + "tags": [ + "Backup" + ] + }, + "patch": { + "description": "更新服务的备份配置。需要 ADMIN auth key role。将属性设置为 null 值时，这些属性会重置为其默认值。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BackupConfigurationPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/BackupConfiguration" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新服务备份配置", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups": { + "get": { + "description": "返回该服务的所有备份列表。列表中最新的备份排在最前面。", + "parameters": [ + { + "description": "拥有该备份的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "创建该备份时所属的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/Backup" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "服务备份列表", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId}": { + "get": { + "description": "返回单个备份的信息。", + "parameters": [ + { + "description": "拥有该备份的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "创建该备份的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "请求的备份 ID。", + "in": "path", + "name": "backupId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Backup" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取备份详情", + "tags": [ + "Backup" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes": { + "get": { + "description": "**此端点处于 Beta 阶段。** API 契约已稳定，预计未来不会有任何 breaking changes。

返回 ClickPipes 列表。", + "parameters": [ + { + "description": "拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的 service 的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ClickPipe" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的原因，server 无法或不愿处理该请求。" + } + }, + "summary": "列出 ClickPipes", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**此端点处于 Beta 阶段。** API 契约已稳定，预计未来不会有任何 breaking changes。

创建新的 ClickPipe。", + "parameters": [ + { + "description": "拥有该 service 的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要为其创建 ClickPipe 的 service 的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的原因，server 无法或不愿处理该请求。" + } + }, + "summary": "创建 ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}": { + "delete": { + "description": "**此端点为 Beta 版本。** API 契约已稳定，预计未来不会出现任何破坏性变更。

删除指定的 ClickPipe。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要删除的 ClickPipe 的 ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client error 的问题，server 无法或不会处理该请求。" + } + }, + "summary": "删除 ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**此端点为 Beta 版本。** API 契约已稳定，预计未来不会出现任何破坏性变更。

返回指定的 ClickPipe。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求的 ClickPipe 的 ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client error 的问题，server 无法或不会处理该请求。" + } + }, + "summary": "获取 ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**此端点为 Beta 版本。** API 契约已稳定，预计未来不会出现任何破坏性变更。

更新指定的 ClickPipe。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要为其创建 ClickPipe 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求的 ClickPipe 的 ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为 client error 的问题，server 无法或不会处理该请求。" + } + }, + "summary": "更新 ClickPipe", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling": { + "patch": { + "description": "**此端点处于 Beta 阶段。** API 契约稳定，预计未来不会有任何破坏性变更。

更改指定 ClickPipe 的扩缩容设置。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新扩缩容设置的 ClickPipe ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "调整 ClickPipe 扩缩容", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/settings": { + "get": { + "description": "**此端点为 Beta 版本。** API 契约已稳定，预计未来不会出现任何破坏性变更。

返回指定 ClickPipe 的高级设置。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要获取设置的 ClickPipe ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "获取 ClickPipe 设置", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "put": { + "description": "**此端点处于 Beta 阶段。** API 契约稳定，预计未来不会有任何破坏性变更。

更新指定 ClickPipe 的高级设置。发送键值对，其中值可以是字符串、数字或布尔值。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新设置的 ClickPipe ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeSettingsPutRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipeSettingsGetResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "更新 ClickPipe 设置", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state": { + "patch": { + "description": "**此端点处于 Beta 阶段。** API 契约稳定，预计未来不会有任何破坏性变更。

启动、停止或重新同步 ClickPipe。停止 ClickPipe 会在任何状态下停止摄取过程。处于“Stopped”或“Failed”状态的 ClickPipes 可以启动。重新同步仅适用于 Postgres 管道，且可在任何状态下执行。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新状态的 ClickPipe ID。", + "in": "path", + "name": "clickPipeId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipeStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipe" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新 ClickPipe 状态", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesCdcScaling": { + "get": { + "description": "**此端点处于 Beta 阶段。** API 契约稳定，预计未来不会出现任何不兼容变更。

获取 DB ClickPipes 的扩缩容设置。\n\n该基础设施由服务中的所有 DB ClickPipes 共享，初始加载和 CDC 均使用这套共享基础设施。按计费规则，2 个 CPU 核心和 8 GB 的 RAM [对应](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) 1 个 compute unit。\n\n**此端点仅在至少预配了一个 DB ClickPipe 后可用。**", + "parameters": [ + { + "description": "拥有该服务的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取 CDC ClickPipes 扩缩容配置", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "patch": { + "description": "**此端点处于 Beta 阶段。** API 契约稳定，预计未来不会出现任何不兼容变更。

更新 DB ClickPipes 的扩缩容设置。\n\n该基础设施由服务中的所有 DB ClickPipes 共享，初始加载和 CDC 均使用这套共享基础设施。扩缩容设置可能需要几分钟才能完全生效。\n\n按计费规则，2 个 CPU 核心和 8 GB 的 RAM [对应](https://clickhouse.com/docs/cloud/manage/billing/overview#clickpipes-for-postgres-cdc) 1 个 compute unit。如果您的 organization tier 发生变化，DB ClickPipes 将相应地[重新扩缩容](https://clickhouse.com/docs/cloud/manage/billing/overview#compute)。\n\n**此端点仅在至少预配了一个 DB ClickPipe 后可用。**", + "parameters": [ + { + "description": "拥有该服务的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 ClickPipe 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClickPipesCdcScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ClickPipesCdcScaling" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新 CDC ClickPipes 扩缩容配置", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints": { + "get": { + "description": "**此端点处于 Beta 阶段。** API 接口约定已稳定，预计未来不会出现破坏性变更。

返回指定服务的反向专用终结点列表。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该反向专用终结点的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "items": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "type": "array" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "列出反向专用终结点", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "post": { + "description": "**此端点处于 Beta 阶段。** API 接口约定已稳定，预计未来不会出现破坏性变更。

创建新的反向专用终结点。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该反向专用终结点的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReversePrivateEndpoint" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "创建反向专用终结点", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId}": { + "delete": { + "description": "**此端点处于 Beta 阶段。** API 合约稳定，预计未来不会出现任何破坏性变更。

删除具有指定 ID 的反向专用终结点。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 Reverse Private Endpoint 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要删除的反向专用终结点 ID。", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "删除反向专用终结点", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + }, + "get": { + "description": "**此端点处于 Beta 阶段。** API 合约稳定，预计未来不会出现任何破坏性变更。

返回具有指定 ID 的反向专用终结点。", + "parameters": [ + { + "description": "拥有该 service 的 organization ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "拥有该 Reverse Private Endpoint 的 service ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要获取的反向专用终结点 ID。", + "in": "path", + "name": "reversePrivateEndpointId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ReversePrivateEndpoint" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，server 无法或不愿处理该请求。" + } + }, + "summary": "获取反向专用终结点", + "tags": [ + "ClickPipes" + ], + "x-badges": [ + { + "name": "Beta", + "position": "after" + } + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/password": { + "patch": { + "description": "为服务设置新密码", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新密码的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicePasswordPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServicePasswordPatchResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "更新服务密码", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint": { + "post": { + "description": "创建新的专用终结点。该专用终结点将与此服务和组织相关联", + "parameters": [ + { + "description": "所请求的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServicPrivateEndpointePostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/InstancePrivateEndpoint" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "创建专用终结点", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig": { + "get": { + "description": "设置专用终结点所需的信息", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求服务的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/PrivateEndpointConfig" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取专用终结点配置", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/prometheus": { + "get": { + "description": "返回服务的 Prometheus 指标。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "返回经过过滤的 Prometheus 指标列表。", + "in": "query", + "name": "filtered_metrics", + "schema": { + "format": "boolean", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不会处理该请求。" + } + }, + "summary": "获取服务指标", + "tags": [ + "Prometheus" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling": { + "patch": { + "description": "更新服务每个副本的最小和最大内存限制，以及空闲模式下的扩缩容行为。内存设置仅适用于“production”服务，且必须为不小于 8GB 的 4GB 倍数。如需启用 numReplicas 调整，请联系支持团队。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新扩缩容参数的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceReplicaScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceScalingPatchResponse" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新服务自动扩缩容设置", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/scaling": { + "patch": { + "deprecated": true, + "description": "更新服务的最小和最大总内存限制，以及空闲模式下的扩缩容行为。内存设置仅适用于“production”服务，且必须为不小于 24GB 的 12GB 倍数。如需启用 numReplicas 调整，请联系支持团队。", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新扩缩容参数的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceScalingPatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "错误详细信息。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新服务自动扩缩容设置", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint": { + "delete": { + "description": "这是一个 Experimental 功能。请联系支持团队以启用此功能。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求服务的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "删除指定实例的服务查询端点", + "tags": [ + "Service" + ] + }, + "get": { + "description": "这是一个 Experimental 功能。请联系支持团队以启用此功能。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求服务的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误说明。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "获取指定实例的服务查询端点", + "tags": [ + "Service" + ] + }, + "post": { + "description": "这是一个 Experimental 功能。请联系支持团队以启用此功能。", + "parameters": [ + { + "description": "所请求组织的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "所请求服务的 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ServiceQueryAPIEndpoint" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "错误详细信息。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "为指定实例更新或创建服务查询端点", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/services/{serviceId}/state": { + "patch": { + "description": "启动或停止服务", + "parameters": [ + { + "description": "拥有该服务的组织 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "要更新状态的服务 ID。", + "in": "path", + "name": "serviceId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceStatePatchRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "为每个请求分配的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/Service" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "错误详细信息。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于请求存在被视为客户端错误的问题，服务器无法或不愿处理该请求。" + } + }, + "summary": "更新服务状态", + "tags": [ + "Service" + ] + } + }, + "/v1/organizations/{organizationId}/usageCost": { + "get": { + "description": "返回查询时间范围内该 organization 的总费用，以及按天、按 entity 划分的 organization 用量成本记录列表（最长 31 天）。请求和响应中的所有日期均按 UTC timezone 计算。", + "parameters": [ + { + "description": "所请求的 organization 的 ID。", + "in": "path", + "name": "organizationId", + "required": true, + "schema": { + "format": "uuid", + "type": "string" + } + }, + { + "description": "报告的开始日期，例如 2024-12-19。", + "in": "query", + "name": "from_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + }, + { + "description": "报告的结束日期（含当日），例如 2024-12-20。该日期不能晚于 from_date 后 30 天（即最长查询周期为 31 天）。", + "in": "query", + "name": "to_date", + "required": true, + "schema": { + "format": "date-time", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "requestId": { + "description": "分配给每个请求的唯一 ID。UUIDv4", + "format": "uuid", + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/UsageCost" + }, + "status": { + "description": "HTTP 状态码。", + "example": 200, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "成功响应" + }, + "400": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "description": "详细错误描述。", + "type": "string" + }, + "status": { + "description": "HTTP 状态码。", + "example": 400, + "type": "number" + } + }, + "type": "object" + } + } + }, + "description": "由于存在被视为客户端错误的原因，server 无法或不愿处理该请求。" + } + }, + "summary": "获取组织使用成本", + "tags": [ + "Billing" + ] + } + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "servers": [ + { + "url": "https://api.clickhouse.cloud" + } + ], + "tags": [ + { + "name": "Organization" + }, + { + "name": "User management" + }, + { + "name": "Billing" + }, + { + "name": "Service" + }, + { + "name": "Backup" + }, + { + "name": "OpenAPI" + }, + { + "name": "Prometheus" + }, + { + "name": "ClickPipes" + } + ], + "x-tagGroups": [ + { + "name": "Organization", + "tags": [ + "Organization", + "Billing", + "User management" + ] + }, + { + "name": "Service", + "tags": [ + "Service", + "Backup" + ] + }, + { + "name": "OpenAPI", + "tags": [ + "OpenAPI" + ] + }, + { + "name": "Prometheus", + "tags": [ + "Prometheus" + ] + }, + { + "name": "ClickPipes", + "tags": [ + "ClickPipes" + ] + } + ] +} \ No newline at end of file diff --git a/zh/_specs/hyperdx-openapi.json b/zh/_specs/hyperdx-openapi.json new file mode 100644 index 000000000..9e111e2cb --- /dev/null +++ b/zh/_specs/hyperdx-openapi.json @@ -0,0 +1,1785 @@ +{ + "components": { + "schemas": { + "Alert": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "createdAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + }, + "dashboard": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "groupBy": { + "nullable": true, + "type": "string" + }, + "id": { + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "interval": { + "example": "15m", + "type": "string" + }, + "message": { + "example": "Error rate exceeds threshold", + "type": "string" + }, + "name": { + "example": "High Error Rate", + "type": "string" + }, + "savedSearch": { + "nullable": true, + "type": "string" + }, + "silenced": { + "nullable": true, + "type": "boolean" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "state": { + "example": "inactive", + "type": "string" + }, + "team": { + "example": "65f5e4a3b9e77c001a345678", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "updatedAt": { + "example": "2023-01-01T00:00:00.000Z", + "format": "date-time", + "type": "string" + } + }, + "type": "object" + }, + "AlertResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Alert" + } + }, + "type": "object" + }, + "AlertsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Alert" + }, + "type": "array" + } + }, + "type": "object" + }, + "ChartSeries": { + "properties": { + "aggFn": { + "description": "对数据使用的聚合函数", + "enum": [ + "avg", + "count", + "count_distinct", + "last_value", + "max", + "min", + "quantile", + "sum" + ], + "example": "count", + "type": "string" + }, + "dataSource": { + "enum": [ + "events", + "metrics" + ], + "example": "events", + "type": "string" + }, + "field": { + "description": "要聚合的字段", + "example": "duration", + "type": "string" + }, + "groupBy": { + "description": "用于对结果分组的字段", + "example": [ + "service", + "host" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "metricDataType": { + "description": "指标数据类型", + "enum": [ + "sum", + "gauge", + "histogram" + ], + "example": "gauge", + "type": "string" + }, + "metricName": { + "description": "指标名称（用于指标数据源）", + "example": "http_requests_total", + "type": "string" + }, + "sourceId": { + "description": "此序列的数据源 ID", + "example": "65f5e4a3b9e77c001a123456", + "type": "string" + }, + "type": { + "enum": [ + "time", + "table", + "number", + "histogram", + "search", + "markdown" + ], + "example": "time", + "type": "string" + }, + "where": { + "description": "采用 Lucene 查询语法的过滤条件", + "example": "level:error", + "type": "string" + }, + "whereLanguage": { + "description": "WHERE 子句中使用的查询语言", + "enum": [ + "lucene", + "sql" + ], + "example": "lucene", + "type": "string" + } + }, + "required": [ + "sourceId", + "aggFn", + "where", + "groupBy" + ], + "type": "object" + }, + "CreateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Test Alert Message", + "type": "string" + }, + "name": { + "example": "Test Alert", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 100, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "required": [ + "threshold", + "interval", + "source", + "thresholdType", + "channel" + ], + "type": "object" + }, + "CreateDashboardRequest": { + "properties": { + "name": { + "example": "New Dashboard", + "type": "string" + }, + "tags": { + "example": [ + "development" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Dashboard": { + "properties": { + "id": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "name": { + "example": "Service Overview", + "type": "string" + }, + "tags": { + "example": [ + "production", + "monitoring" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + }, + "DashboardResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "type": "object" + }, + "DashboardsListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/Dashboard" + }, + "type": "array" + } + }, + "type": "object" + }, + "EmptyResponse": { + "properties": {}, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + } + }, + "type": "object" + }, + "SeriesDataPoint": { + "properties": { + "group": { + "description": "如果指定了 groupBy，则为分组后的值", + "example": [ + "api", + "prod-host-1" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "series_0.data": { + "description": "第一个序列的值", + "example": 42, + "type": "number" + }, + "series_1.data": { + "description": "第二个序列的值", + "example": 18, + "type": "number" + }, + "ts_bucket": { + "description": "数据点的时间戳（桶起始时间）", + "example": 1647014400000, + "type": "number" + } + }, + "type": "object" + }, + "SeriesQueryRequest": { + "properties": { + "endTime": { + "description": "结束时间戳（毫秒）", + "example": 1647100800000, + "type": "number" + }, + "granularity": { + "description": "聚合的时间桶大小", + "enum": [ + "30s", + "1m", + "5m", + "10m", + "15m", + "30m", + "1h", + "2h", + "6h", + "12h", + "1d", + "2d", + "7d", + "30d", + "auto" + ], + "example": "1h", + "type": "string" + }, + "series": { + "description": "序列配置数组", + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "maxItems": 5, + "minItems": 1, + "type": "array" + }, + "seriesReturnType": { + "description": "返回数据的格式", + "enum": [ + "ratio", + "column" + ], + "example": "column", + "type": "string" + }, + "startTime": { + "description": "起始时间戳（毫秒）", + "example": 1647014400000, + "type": "number" + } + }, + "required": [ + "series", + "startTime", + "endTime" + ], + "type": "object" + }, + "SeriesResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/SeriesDataPoint" + }, + "type": "array" + } + }, + "type": "object" + }, + "Tile": { + "properties": { + "asRatio": { + "example": false, + "type": "boolean" + }, + "h": { + "example": 3, + "type": "integer" + }, + "id": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + }, + "name": { + "example": "Error Rate", + "type": "string" + }, + "series": { + "items": { + "$ref": "#/components/schemas/ChartSeries" + }, + "type": "array" + }, + "w": { + "example": 6, + "type": "integer" + }, + "x": { + "example": 0, + "type": "integer" + }, + "y": { + "example": 0, + "type": "integer" + } + }, + "type": "object" + }, + "UpdateAlertRequest": { + "properties": { + "channel": { + "properties": { + "type": { + "example": "webhook", + "type": "string" + }, + "webhookId": { + "example": "65f5e4a3b9e77c001a789012", + "type": "string" + } + }, + "type": "object" + }, + "dashboardId": { + "example": "65f5e4a3b9e77c001a567890", + "type": "string" + }, + "interval": { + "example": "1h", + "type": "string" + }, + "message": { + "example": "Updated message", + "type": "string" + }, + "name": { + "example": "Updated Alert Name", + "type": "string" + }, + "source": { + "enum": [ + "tile", + "search" + ], + "example": "tile", + "type": "string" + }, + "threshold": { + "example": 500, + "type": "number" + }, + "thresholdType": { + "enum": [ + "above", + "below" + ], + "example": "above", + "type": "string" + }, + "tileId": { + "example": "65f5e4a3b9e77c001a901234", + "type": "string" + } + }, + "type": "object" + }, + "UpdateDashboardRequest": { + "properties": { + "name": { + "example": "Updated Dashboard Name", + "type": "string" + }, + "tags": { + "example": [ + "production", + "updated" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "tiles": { + "items": { + "$ref": "#/components/schemas/Tile" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "securitySchemes": { + "BearerAuth": { + "bearerFormat": "API Key", + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "用于管理 HyperDX 告警和仪表盘的 API", + "title": "HyperDX External API", + "version": "2.0.0" + }, + "openapi": "3.0.0", + "paths": { + "/api/v2/alerts": { + "get": { + "description": "获取已认证团队的所有告警列表", + "operationId": "listAlerts", + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertsList": { + "summary": "告警列表", + "value": { + "data": [ + { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-01-01T00:00:00.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "15m", + "message": "Error rate exceeds threshold", + "name": "High Error Rate", + "source": "tile", + "state": "inactive", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-01-01T00:00:00.000Z" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertsListResponse" + } + } + }, + "description": "已成功获取告警" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + } + }, + "summary": "获取告警列表", + "tags": [ + "Alerts" + ] + }, + "post": { + "description": "创建新告警", + "operationId": "createAlert", + "requestBody": { + "content": { + "application/json": { + "examples": { + "tileAlert": { + "summary": "创建基于卡片的告警", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Error rate has exceeded 100 in the last hour", + "name": "Error Spike Alert", + "source": "tile", + "threshold": 100, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "已成功创建告警" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "服务器错误或验证失败" + } + }, + "summary": "创建告警", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/alerts/{id}": { + "delete": { + "description": "删除告警", + "operationId": "deleteAlert", + "parameters": [ + { + "description": "告警 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "已成功删除告警" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到告警" + } + }, + "summary": "删除告警", + "tags": [ + "Alerts" + ] + }, + "get": { + "description": "按 ID 检索特定告警", + "operationId": "getAlert", + "parameters": [ + { + "description": "告警 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "alertResponse": { + "summary": "单个告警响应", + "value": { + "data": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "createdAt": "2023-03-15T10:20:30.000Z", + "dashboard": "65f5e4a3b9e77c001a567890", + "id": "65f5e4a3b9e77c001a123456", + "interval": "5m", + "message": "CPU usage is above 80%", + "name": "CPU Usage Alert", + "source": "tile", + "state": "active", + "team": "65f5e4a3b9e77c001a345678", + "threshold": 80, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234", + "updatedAt": "2023-03-15T14:25:10.000Z" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "已成功检索告警" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到告警" + } + }, + "summary": "获取告警", + "tags": [ + "Alerts" + ] + }, + "put": { + "description": "更新现有告警", + "operationId": "updateAlert", + "parameters": [ + { + "description": "告警 ID", + "example": "65f5e4a3b9e77c001a123456", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateAlert": { + "summary": "更新告警属性", + "value": { + "channel": { + "type": "webhook", + "webhookId": "65f5e4a3b9e77c001a789012" + }, + "dashboardId": "65f5e4a3b9e77c001a567890", + "interval": "1h", + "message": "Updated threshold and interval", + "name": "Updated Alert Name", + "source": "tile", + "threshold": 500, + "thresholdType": "above", + "tileId": "65f5e4a3b9e77c001a901234" + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateAlertRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AlertResponse" + } + } + }, + "description": "已成功更新告警" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到告警" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "服务器错误或验证失败" + } + }, + "summary": "更新告警", + "tags": [ + "Alerts" + ] + } + }, + "/api/v2/charts/series": { + "post": { + "description": "根据已配置的序列参数获取时间序列数据", + "operationId": "queryChartSeries", + "requestBody": { + "content": { + "application/json": { + "examples": { + "basicTimeSeries": { + "summary": "基本时间序列查询", + "value": { + "endTime": 1647100800000, + "granularity": "1h", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "metricSeries": { + "summary": "指标数据序列", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + }, + "multiSeriesWithGroupBy": { + "summary": "使用 group by 的多个序列", + "value": { + "endTime": 1647100800000, + "granularity": "15m", + "series": [ + { + "aggFn": "count", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "field": "duration", + "groupBy": [ + "service" + ], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + } + ], + "startTime": 1647014400000 + } + }, + "multiSourceSeries": { + "summary": "来自多个数据源的序列", + "value": { + "endTime": 1647100800000, + "granularity": "5m", + "series": [ + { + "aggFn": "count", + "groupBy": [], + "sourceId": "65f5e4a3b9e77c001a123456", + "where": "SeverityText:error" + }, + { + "aggFn": "avg", + "groupBy": [], + "metricDataType": "gauge", + "metricName": "http_requests_total", + "sourceId": "65f5e4a3b9e77c001a789012", + "where": "service:api" + } + ], + "startTime": 1647014400000 + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesQueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "groupedTimeSeriesData": { + "summary": "分组后的时间序列数据", + "value": { + "data": [ + { + "group": [ + "api" + ], + "series_0.data": 15, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "frontend" + ], + "series_0.data": 8, + "ts_bucket": 1647014400000 + }, + { + "group": [ + "api" + ], + "series_0.data": 22, + "ts_bucket": 1647018000000 + } + ] + } + }, + "timeSeriesData": { + "summary": "时间序列数据点", + "value": { + "data": [ + { + "series_0.data": 42, + "ts_bucket": 1647014400000 + }, + { + "series_0.data": 37, + "ts_bucket": 1647018000000 + }, + { + "series_0.data": 53, + "ts_bucket": 1647021600000 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/SeriesResponse" + } + } + }, + "description": "已成功获取时间序列数据" + }, + "400": { + "content": { + "application/json": { + "examples": { + "invalidParams": { + "value": { + "error": "All series must have the same groupBy fields" + } + }, + "invalidTimestamp": { + "value": { + "error": "Timestamp must be in milliseconds" + } + } + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "请求参数无效" + }, + "403": { + "content": { + "application/json": { + "example": { + "error": "Team context missing" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "example": { + "error": "Source not found" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "未找到数据源" + }, + "500": { + "content": { + "application/json": { + "example": { + "error": "Internal server error" + }, + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "description": "服务器错误" + } + }, + "summary": "查询图表序列数据", + "tags": [ + "Charts" + ] + } + }, + "/api/v2/dashboards": { + "get": { + "description": "获取已认证团队的所有仪表盘列表", + "operationId": "listDashboards", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardsListResponse" + } + } + }, + "description": "已成功获取仪表盘" + }, + "401": { + "description": "未授权" + } + }, + "summary": "获取仪表盘列表", + "tags": [ + "Dashboards" + ] + }, + "post": { + "description": "创建新仪表盘", + "operationId": "createDashboard", + "requestBody": { + "content": { + "application/json": { + "examples": { + "complexDashboard": { + "summary": "包含多种图表类型的仪表盘", + "value": { + "name": "Service Health Overview", + "tags": [ + "service-health", + "production" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "Request Count", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:backend" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "Error Distribution", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [ + "errorType" + ], + "sortOrder": "desc", + "type": "table", + "where": "level:error" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + }, + "simpleTimeSeriesDashboard": { + "summary": "包含时间序列图表的仪表盘", + "value": { + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CreateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "createdDashboard": { + "summary": "创建仪表盘的响应", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "API Monitoring Dashboard", + "tags": [ + "api", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "API Request Volume", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "service:api" + } + ], + "w": 6, + "x": 0, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "已成功创建仪表盘" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Dashboard validation failed: name is required" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "服务器错误或验证失败" + } + }, + "summary": "创建仪表盘", + "tags": [ + "Dashboards" + ] + } + }, + "/api/v2/dashboards/{id}": { + "delete": { + "description": "删除仪表盘", + "operationId": "deleteDashboard", + "parameters": [ + { + "description": "仪表盘 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "example": {}, + "schema": { + "$ref": "#/components/schemas/EmptyResponse" + } + } + }, + "description": "已成功删除仪表盘" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到仪表盘" + } + }, + "summary": "删除仪表盘", + "tags": [ + "Dashboards" + ] + }, + "get": { + "description": "根据 ID 获取指定仪表盘", + "operationId": "getDashboard", + "parameters": [ + { + "description": "仪表盘 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "dashboard": { + "summary": "单个仪表盘响应", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Infrastructure Monitoring", + "tags": [ + "infrastructure", + "monitoring" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Server CPU", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "cpu.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901235", + "name": "Memory Usage", + "series": [ + { + "aggFn": "avg", + "dataSource": "metrics", + "field": "memory.usage", + "groupBy": [], + "type": "time", + "where": "host:server-01" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "已成功获取仪表盘" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到仪表盘" + } + }, + "summary": "获取仪表盘", + "tags": [ + "Dashboards" + ] + }, + "put": { + "description": "更新现有仪表盘", + "operationId": "updateDashboard", + "parameters": [ + { + "description": "仪表盘 ID", + "example": "65f5e4a3b9e77c001a567890", + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "updateDashboard": { + "summary": "更新仪表盘属性和卡片", + "value": { + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/UpdateDashboardRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "updatedDashboard": { + "summary": "更新仪表盘后的响应", + "value": { + "data": { + "id": "65f5e4a3b9e77c001a567890", + "name": "Updated Dashboard Name", + "tags": [ + "production", + "updated" + ], + "tiles": [ + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901234", + "name": "Updated Time Series Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "groupBy": [], + "type": "time", + "where": "level:error" + } + ], + "w": 6, + "x": 0, + "y": 0 + }, + { + "asRatio": false, + "h": 3, + "id": "65f5e4a3b9e77c001a901236", + "name": "New Number Chart", + "series": [ + { + "aggFn": "count", + "dataSource": "events", + "type": "number", + "where": "level:info" + } + ], + "w": 6, + "x": 6, + "y": 0 + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/DashboardResponse" + } + } + }, + "description": "已成功更新仪表盘" + }, + "401": { + "content": { + "application/json": { + "example": { + "message": "Unauthorized access. API key is missing or invalid." + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未授权" + }, + "404": { + "content": { + "application/json": { + "example": { + "message": "Dashboard not found" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "未找到仪表盘" + }, + "500": { + "content": { + "application/json": { + "example": { + "message": "Invalid dashboard configuration" + }, + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "服务器错误或验证失败" + } + }, + "summary": "更新仪表盘", + "tags": [ + "Dashboards" + ] + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "servers": [ + { + "description": "生产环境 API 服务器", + "url": "https://api.hyperdx.io" + }, + { + "description": "当前服务器", + "url": "/" + } + ], + "tags": [ + { + "description": "用于管理仪表盘及其可视化内容的端点", + "name": "Dashboards" + }, + { + "description": "用于管理监控告警的端点", + "name": "Alerts" + } + ] +} \ No newline at end of file diff --git a/zh/clickstack/features/dashboards/overview.mdx b/zh/clickstack/features/dashboards/overview.mdx index 10af7e733..ca75eb921 100644 --- a/zh/clickstack/features/dashboards/overview.mdx +++ b/zh/clickstack/features/dashboards/overview.mdx @@ -45,7 +45,7 @@ HyperDX 中的 **Chart Explorer** 界面可让你按时间维度将指标、链 ### 创建可视化 - 在下面的示例中，我们绘制按服务名称区分的平均请求耗时随时间变化的图表。这要求用户指定一个指标、一个列 (可以是 SQL 表达式) 以及一个聚合字段。 + 在下面的示例中，我们绘制按服务名称区分的平均请求耗时随时间变化的图表。这要求用户指定一个指标、一列 (可以是 SQL 表达式) 以及一个聚合字段。 从顶部菜单中选择 `Line/Bar` 可视化类型，然后选择 `Traces` 数据集 (如果使用 [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)，则选择 `Demo Traces`) 。填写以下值： @@ -63,6 +63,10 @@ HyperDX 中的 **Chart Explorer** 界面可让你按时间维度将指标、链 Simple visualization 2 + 若要基于现有 series 创建一个类似的新 series，你可以直接复制，而不必从头开始。点击某个 series 行上的复制图标 (`Duplicate series`) ，即可在其正下方插入一个副本。副本会保留原 series 的设置，例如指标、列和过滤器。然后你只需修改不同的字段 (例如聚合方式) ，并为副本设置自己的别名。在所有支持多个 series 的地方都可以使用复制功能。对于仅允许一个 series 的可视化类型，例如 `Number`、`Pie` 和 `Heatmap`，则会隐藏该功能。 + + The Duplicate series copy icon and its tooltip on a chart series row + 可以基于任何数据源创建可视化——无论是指标、链路追踪还是日志。ClickStack 将这些统一视为宽事件。任何**数值列**都可以按时间绘制成图，而**字符串**、**日期**或**数值**列都可用于分组。 diff --git a/zh/clickstack/ingesting-data/collector.mdx b/zh/clickstack/ingesting-data/collector.mdx index cd06034f2..e9a009451 100644 --- a/zh/clickstack/ingesting-data/collector.mdx +++ b/zh/clickstack/ingesting-data/collector.mdx @@ -104,7 +104,7 @@ OpenTelemetry collectors 可部署为两种主要角色： - 目标 ClickHouse 实例通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME` 和 `CLICKHOUSE_PASSWORD` 进行配置。`CLICKHOUSE_ENDPOINT` 应为完整的 ClickHouse Cloud HTTP 端点，包含协议和端口，例如 `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`。 + 目标 ClickHouse 实例通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD` 进行配置。`CLICKHOUSE_ENDPOINT` 应为完整的 ClickHouse Cloud HTTP 端点，包含协议和端口，例如 `https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443`。 有关如何获取托管 ClickStack 凭据的详细信息，请参阅[此处](/zh/products/cloud/guides/sql-console/connection-details)。 @@ -118,7 +118,7 @@ OpenTelemetry collectors 可部署为两种主要角色： #### 配置托管 ClickStack 实例 - 可以通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME` 和 `CLICKHOUSE_PASSWORD` 将 OpenTelemetry collector 配置为使用托管 ClickStack 实例。这些变量的设置方式取决于您所采用的部署方式： + 可以通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD` 将 OpenTelemetry collector 配置为使用托管 ClickStack 实例。这些变量的设置方式取决于您所采用的部署方式： @@ -162,7 +162,7 @@ OpenTelemetry collectors 可部署为两种主要角色： 使用 Docker Compose 时，通过与上述相同的环境变量修改 collector 配置： ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -171,11 +171,11 @@ OpenTelemetry collectors 可部署为两种主要角色： CLICKHOUSE_PASSWORD: 'password' CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml' ports: - - '13133:13133' # health_check 扩展 - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # 指标扩展 + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension volumes: - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro restart: always @@ -261,7 +261,7 @@ OpenTelemetry collectors 可部署为两种主要角色： - 目标 ClickHouse 实例通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME` 和 `CLICKHOUSE_PASSWORD` 进行配置。`CLICKHOUSE_ENDPOINT` 应为完整的 ClickHouse HTTP 端点，包含协议和端口，例如 `http://localhost:8123`。 + 目标 ClickHouse 实例通过环境变量 `CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD` 进行配置。`CLICKHOUSE_ENDPOINT` 应为完整的 ClickHouse HTTP 端点，包含协议和端口，例如 `http://localhost:8123`。 **这些环境变量可用于任何包含该连接器的 Docker 发行版。** @@ -275,7 +275,7 @@ OpenTelemetry collectors 可部署为两种主要角色： #### 配置 ClickHouse 实例 - OpenTelemetry collector 可通过环境变量 `OPAMP_SERVER_URL`、`CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USERNAME` 和 `CLICKHOUSE_PASSWORD` 配置为使用 ClickHouse 实例。这些变量的具体设置方式取决于您的部署方式： + OpenTelemetry collector 可通过环境变量 `OPAMP_SERVER_URL`、`CLICKHOUSE_ENDPOINT`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD` 配置为使用 ClickHouse 实例。这些变量的具体设置方式取决于您的部署方式： @@ -322,7 +322,7 @@ OpenTelemetry collectors 可部署为两种主要角色： 使用 Docker Compose 时，通过与上述相同的环境变量修改 collector 配置： ```yaml - otel-collector: + otel-collector: image: hyperdx/hyperdx-otel-collector environment: CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443' @@ -331,11 +331,11 @@ OpenTelemetry collectors 可部署为两种主要角色： CLICKHOUSE_PASSWORD: 'password' OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}' ports: - - '13133:13133' # health_check 扩展 - - '24225:24225' # Fluentd receiver + - '13133:13133' # health_check extension + - '24225:24225' # fluentd receiver - '4317:4317' # OTLP gRPC receiver - - '4318:4318' # OTLP HTTP receiver - - '8888:8888' # 指标扩展 + - '4318:4318' # OTLP http receiver + - '8888:8888' # metrics extension restart: always networks: - internal diff --git a/zh/clickstack/mcp.mdx b/zh/clickstack/mcp.mdx index 5e95b1e98..a44aafb08 100644 --- a/zh/clickstack/mcp.mdx +++ b/zh/clickstack/mcp.mdx @@ -4,7 +4,7 @@ title: 'ClickStack MCP 服务器' sidebarTitle: 'MCP 服务器' description: '通过 Model Context Protocol (MCP) 服务器将 AI 助手连接到 ClickStack' doc_type: 'guide' -keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', '可观测性', 'HyperDX', 'Claude', 'Cursor'] +keywords: ['ClickStack', 'MCP', 'Model Context Protocol', 'AI', '可观测性', 'HyperDX', 'Claude', 'Cursor', 'ClickHouse Cloud', 'OAuth'] --- import { Image } from "/snippets/components/Image.jsx"; @@ -19,112 +19,222 @@ ClickStack 内置了 [Model Context Protocol (MCP)](https://modelcontextprotocol MCP 服务器可用于以下 ClickStack 部署类型： -| 部署 | 状态 | -| ------------------------------------------------- | ---- | -| **开源 ClickStack** | 可用 | -| **BYOC (自备 Cloud)** | 可用 | -| **托管 ClickStack** | 即将推出 | -| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | 不支持 | +| 部署 | 状态 | +| ------------------------------------------------- | --- | +| **开源 ClickStack** | 可用 | +| **BYOC (自备 Cloud)** | 可用 | +| **ClickHouse Cloud 上的 ClickStack** | 可用 | +| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | 不支持 | - - **托管 ClickStack** + + **ClickHouse Cloud 与 OSS/BYOC 的设置差异** - 托管 ClickStack 对 MCP 服务器的支持正在积极开发中，很快即可提供。本页中的说明适用于开源和 BYOC 部署。 - + ClickHouse Cloud 上的 ClickStack 使用的端点和身份验证方法与开源和 BYOC 部署不同。有关 Cloud 专用设置，请参阅下方的 [ClickHouse Cloud 上的 ClickStack](#managed-clickstack) 部分。 + -
- ## 前置条件 +
+ ## ClickHouse Cloud 上的 ClickStack
-在连接 MCP 客户端 之前，您需要： +ClickHouse Cloud 上的 ClickStack 通过 Cloud MCP 端点 `https://mcp.clickhouse.cloud/clickstack` 连接，并使用 OAuth 2.0 进行身份验证。该端点不支持 API key 身份验证。 -* 一个正在运行的 ClickStack 实例 (有关设置选项，请参见[部署](/zh/clickstack/deployment/overview)) -* 一个 **Personal API Access Key** — 您可以在 HyperDX 的 **Team Settings → API Keys → Personal API Access Key** 中找到 +
+ ### 前置条件 +
-Team Settings 中的 Personal API Access Key +* 一个正在运行且已[启用 ClickStack](/zh/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud)的 ClickHouse Cloud 服务 +* 服务上已[启用 MCP](/zh/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server)——打开 Cloud 控制台，点击 **Connect**，选择 **Connect with MCP**，然后将其切换为开启状态 - - Personal API Access Key 与 **摄取 API key** 不同；后者也可在 Team Settings 中找到，用于验证发送到 OpenTelemetry Collector 的遥测数据。 - +
+ ### 端点 +
+ +```text +https://mcp.clickhouse.cloud/clickstack +``` -
- ## 端点 +身份验证采用 OAuth 2.0。首次连接时，MCP 客户端会打开浏览器窗口，供你使用 ClickHouse Cloud 凭据登录。无需 API 密钥。 + +
+ ### 连接 MCP 客户端
-可通过 ClickStack 前端 URL 上的 `/api/mcp` 路径访问 MCP 服务器： +每个客户端在首次连接时都会自动处理 OAuth 流程。 -例如，使用默认本地部署时： + + + ```shell + claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack + ``` -如果你修改了默认设置，请将 `localhost:8080` 替换为你的实例主机和端口。 + 启动 Claude Code 并运行 `/mcp`，然后选择 `clickstack-cloud` 以完成 OAuth 流程。 + - - 本页中的示例使用前端应用 URL (默认端口为 `8080`) 。你也可以通过后端的 `/mcp` 直接访问 MCP 服务器，但并非所有部署都会暴露后端，因此本文档使用前端路径。 - + + 将以下内容添加到 `.cursor/mcp.json`： -MCP 服务器 使用 **Streamable HTTP** 传输和 **Bearer token** 身份验证。 + ```json + { + "mcpServers": { + "clickstack-cloud": { + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 将以下内容添加到 `.vscode/mcp.json`： + + ```json + { + "servers": { + "clickstack-cloud": { + "type": "http", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 将以下内容添加到 `opencode.json`： + + ```json + { + "mcp": { + "clickstack-cloud": { + "type": "remote", + "url": "https://mcp.clickhouse.cloud/clickstack" + } + } + } + ``` + + + + 任何支持 **Streamable HTTP** 和 OAuth 的 MCP 客户端都可以连接。请按以下方式配置： -
- ## 连接 MCP 客户端 + * **URL:** `https://mcp.clickhouse.cloud/clickstack` + + + +
+ ### 指定特定服务
-下面的示例说明了如何配置常用的 MCP 客户端。请将 `` 替换为你的实例 URL (例如 `http://localhost:8080`) ，并将 `` 替换为你的 Personal API Access Key。 +如果未提供 `x-service-id` 请求头，请求默认会发送到你账户中第一个已预配并使用的 ClickStack 服务。若要指定其他服务，请在 MCP 客户端配置中将 `x-service-id: ` 作为请求头传入。 -
- ### Claude Code +
+ ## 开源和 BYOC
-```shell -claude mcp add --transport http hyperdx /api/mcp \ - --header "Authorization: Bearer " -``` +开源和 BYOC 部署使用您的 ClickStack 实例内置的 MCP 端点，并采用 Bearer 令牌身份验证。 -
- ### Cursor +
+ ### 前置条件
-将以下内容添加到项目的 `.cursor/mcp.json` 文件中，或添加到全局 Cursor 设置中： +* 一个正在运行的 ClickStack 实例 (有关设置选项，请参见[部署](/zh/clickstack/deployment/overview)) +* 一个 **Personal API Access Key** — 您可以在 HyperDX 的 **Team Settings → API Keys → Personal API Access Key** 中找到 -```json -{ - "mcpServers": { - "hyperdx": { - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +Team Settings 中的 Personal API Access Key + + + Personal API Access Key 与 **摄取 API key** 不同；后者也可在 Team Settings 中找到，用于验证发送到 OpenTelemetry Collector 的遥测数据。 + -
- ### OpenCode +
+ ### 端点
-将以下内容添加到 `opencode.json` 配置文件中： +可通过 ClickStack 前端 URL 上的 `/api/mcp` 路径访问 MCP 服务器。例如，使用默认本地部署时，URL 为 `http://localhost:8080/api/mcp`。如果你修改了默认设置，请将 `localhost:8080` 替换为你的实例主机和端口。 -```json -{ - "mcp": { - "hyperdx": { - "type": "http", - "url": "/api/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` + + 本页中的示例使用前端应用 URL (默认端口为 `8080`) 。你也可以通过后端的 `/mcp` 直接访问 MCP 服务器，但并非所有部署都会暴露后端，因此本文档使用前端路径。 + + +MCP 服务器 使用 **Streamable HTTP** 传输和 **Bearer token** 身份验证。 -
- ### 其他客户端 +
+ ### 连接 MCP 客户端
-任何支持 **Streamable HTTP** 传输方式的 MCP 客户端都可以连接。请按以下方式进行配置： +将 `` 替换为你的实例 URL (例如 `http://localhost:8080`) ，并将 `` 替换为你的 Personal API Access Key。 + + + + ```shell + claude mcp add --transport http hyperdx /api/mcp \ + --header "Authorization: Bearer " + ``` + + + + 将以下内容添加到 `.cursor/mcp.json`： + + ```json + { + "mcpServers": { + "hyperdx": { + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + 将以下内容添加到 `.vscode/mcp.json`： + + ```json + { + "mcp": { + "servers": { + "hyperdx": { + "type": "http", + "url": "/api/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + } + ``` + + + + 将以下内容添加到 `opencode.json`： + + ```json + { + "mcp": { + "hyperdx": { + "type": "remote", + "url": "/api/mcp", + "oauth": false, + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + + + 任何支持 **Streamable HTTP** 的 MCP 客户端都可以连接。按以下方式配置： -* **URL:** `/api/mcp` -* **请求头:** `Authorization: Bearer ` + * **URL：** `/api/mcp` + * **请求头：** `Authorization: Bearer ` + +
## 你可以用 MCP 做什么？ @@ -143,9 +253,11 @@ claude mcp add --transport http hyperdx /api/mcp \ 具体可用的工具集可能会随时间不断扩展。MCP 客户端 会在连接时自动发现可用工具。
- ## 多团队使用 + ## 多团队使用 (OSS/BYOC)
+这仅适用于 开源和 BYOC 部署。对于 ClickHouse Cloud 上的 ClickStack，请参阅[指定特定服务](#managed-service-override)。 + 默认情况下，MCP 请求会在你的主团队上下文中处理。如果你属于多个团队，可以在传递 `Authorization` 请求头的同时，添加一个值为该团队 ID 的 `x-hdx-team` 请求头，以指定特定团队。如果省略该请求头，则会使用你的主团队。如果你指定了一个自己不属于的团队，请求会被拒绝，并返回 `401` 错误。 使用 MCP 客户端 中的团队列表工具，查看你可以访问哪些团队以及当前处于活动状态的是哪个团队。 @@ -154,6 +266,29 @@ claude mcp add --transport http hyperdx /api/mcp \ ## 故障排查
+
+ ### ClickHouse Cloud 上的 ClickStack +
+ + + * 确认您的 MCP client 支持 OAuth 2.0。仅支持 Bearer 令牌或 stdio 传输的客户端无法通过 Cloud 端点进行身份验证。 + * 检查您的浏览器是否拦截了 OAuth 弹窗或重定向。 + * 确认您的 ClickHouse Cloud 账户有权访问相应的 organization 和 service。 + + + + * 确认您使用的是 ClickStack 端点 (`https://mcp.clickhouse.cloud/clickstack`) ，而不是通用的 Cloud MCP 端点 (`https://mcp.clickhouse.cloud/mcp`) 。 + * 确认该 service 已在 Cloud 控制台 中[启用 MCP](/zh/use-cases/AI/MCP/remote_mcp#enable-remote-mcp-server)。 + + + + 如果未提供 `x-service-id` 请求头，请求默认会发送到您账户中预配并使用的第一个 ClickStack service。传递该请求头即可指定特定的目标 service。请参见[指定特定 service](#managed-service-override)。 + + +
+ ### 开源和 BYOC +
+ * 请确认你使用的是 **Personal API Access Key** (而不是摄取 API key) 。 * 确认该密钥已作为 `Bearer` 令牌包含在 `Authorization` 请求头中。 @@ -161,7 +296,7 @@ claude mcp add --transport http hyperdx /api/mcp \ - MCP 服务器 对每位用户实施 **每分钟 600 次请求** 的速率限制。如果超过此限制，请求将被暂时拒绝。请降低请求频率，或等待后再重试。 + MCP 服务器 对每位用户实施 **每分钟 600 次请求** 的速率限制。如果超过此限制，请求会被暂时拒绝。请降低请求频率，或等待后再重试。 diff --git a/zh/clickstack/navigation.json b/zh/clickstack/navigation.json index 45026cb1f..01c8e37f8 100644 --- a/zh/clickstack/navigation.json +++ b/zh/clickstack/navigation.json @@ -233,7 +233,7 @@ { "expanded": true, "group": "API reference", - "openapi": "_specs/hyperdx-openapi.json", + "openapi": "zh/_specs/hyperdx-openapi.json", "root": "zh/clickstack/api-reference" } ] diff --git a/zh/concepts/features/operations/update/replacing-merge-tree.mdx b/zh/concepts/features/operations/update/replacing-merge-tree.mdx index f558df745..e4fe446ca 100644 --- a/zh/concepts/features/operations/update/replacing-merge-tree.mdx +++ b/zh/concepts/features/operations/update/replacing-merge-tree.mdx @@ -103,9 +103,9 @@ ORDER BY (PostTypeId, toDate(CreationDate), CreationDate, Id) ## 查询 ReplacingMergeTree
-在 merge 期间，ReplacingMergeTree 会识别重复行，将 `ORDER BY` 列的值用作唯一标识符，并且要么只保留最高版本，要么在最新版本表示删除时移除所有重复项。然而，这只能提供最终一致的正确性——并不能保证行一定会被去重，因此不应依赖它。因此，由于查询时会将更新行和删除行也纳入考虑，查询结果可能不正确。 +在合并时，ReplacingMergeTree 会识别重复行，将 `ORDER BY` 列的值用作唯一标识符，并且要么只保留最高版本，要么在最新版本表示删除时移除所有重复项。然而，这只能提供最终一致的正确性——并不能保证行一定会被去重，因此不应依赖它。因此，由于查询时会将更新行和删除行也纳入考虑，查询结果可能不正确。 -要获得正确结果，你需要结合 background merges，并在 query time 执行去重和删除移除。这可以通过使用 `FINAL` 运算符来实现。 +要获得正确结果，你需要结合 background merges，并在查询时执行去重和删除移除。这可以通过使用 `FINAL` 运算符来实现。 以上面的 posts 表为例。我们可以使用加载该数据集的常规方法，但额外指定 deleted 列和 version 列，并将它们的值设为 0。为了便于演示，这里我们只加载 10000 行。 @@ -125,7 +125,7 @@ SELECT count() FROM stackoverflow.posts_updateable │ 10000 │ └─────────┘ -1 行，耗时 0.002 秒。 +1 row in set. Elapsed: 0.002 sec. ``` 我们现在更新回答后的帖子统计信息。我们不直接更新这些值，而是插入 5000 行的新副本，并将它们的版本号加一 (这意味着表中将有 150 行) 。我们可以用一个简单的 `INSERT INTO SELECT` 来模拟这一过程： @@ -156,7 +156,7 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --随机选取100行 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 LIMIT 5000 @@ -191,14 +191,14 @@ INSERT INTO posts_updateable SELECT ParentId, CommunityOwnedDate, ClosedDate -FROM posts_updateable --随机选取 100 行 +FROM posts_updateable --select 100 random rows WHERE (Id % toInt32(floor(randUniform(1, 11)))) = 0 AND AnswerCount > 0 LIMIT 1000 0 rows in set. Elapsed: 0.166 sec. Processed 135.53 thousand rows, 212.65 MB (816.30 thousand rows/s., 1.28 GB/s.) ``` -上述操作的结果将是 16,000 行，即 10,000 + 5000 + 1000。而这里实际正确的总数应仅比原始总数少 1000 行，即 10,000 - 1000 = 9000。 +上述操作后，结果将是 16,000 行，即 10,000 + 5000 + 1000。实际上，正确的总数应该只比原始总数少 1000 行，即 10,000 - 1000 = 9000。 ```sql SELECT count() @@ -210,7 +210,7 @@ FROM posts_updateable 1 row in set. Elapsed: 0.002 sec. ``` -这里的结果会因已发生的合并而有所不同。我们可以看到，这里的总数不一样，因为存在重复行。对表应用 `FINAL` 可得到正确结果。 +结果会因已发生的合并而有所不同。我们可以看到，由于存在重复行，总数会有所不同。对表应用 `FINAL` 可得到正确结果。 ```sql SELECT count() @@ -359,11 +359,11 @@ ClickHouse 中的 ReplacingMergeTree 引擎经过优化，可通过合并 parts ### 调优合并以提升查询性能
-默认情况下，min_age_to_force_merge_seconds 和 min_age_to_force_merge_on_partition_only 分别设置为 0 和 false，因此这些功能默认处于禁用状态。在这种配置下，ClickHouse 会采用标准的合并行为，不会根据分区的时间强制执行合并。 +默认情况下，`min_age_to_force_merge_seconds` 和 `min_age_to_force_merge_on_partition_only` 分别设置为 0 和 false，因此这些功能默认处于禁用状态。在这种配置下，ClickHouse 会采用标准的合并行为，不会根据分区的时间强制执行合并。 -如果为 min_age_to_force_merge_seconds 指定了值，ClickHouse 将对早于该时间阈值的 parts 忽略常规的合并启发式规则。虽然这种做法通常只在目标是尽量减少 parts 总数时才有明显效果，但在 ReplacingMergeTree 中，它可以通过减少查询时需要合并的 parts 数量来提升查询性能。 +如果为 `min_age_to_force_merge_seconds` 指定了值，ClickHouse 将对早于该时间阈值的 parts 忽略常规的合并启发式规则。虽然这种做法通常只在目标是尽量减少 parts 总数时才有明显效果，但在 ReplacingMergeTree 中，它可以通过减少查询时需要合并的 parts 数量来提升查询性能。 -还可以通过设置 min_age_to_force_merge_on_partition_only=true 进一步调优这一行为。这样一来，只有当分区中的所有 parts 都早于 min_age_to_force_merge_seconds 时，才会执行更激进的合并。这种配置可使较旧的分区随着时间推移逐步合并为单个 part，从而整合数据并维持查询性能。 +还可以通过设置 `min_age_to_force_merge_on_partition_only=true` 进一步调优这一行为。这样一来，只有当分区中的所有 parts 都早于 `min_age_to_force_merge_seconds` 时，才会执行更激进的合并。这种配置可使较旧的分区随着时间推移逐步合并为单个 part，从而整合数据并维持查询性能。 * 管道创建后，无法再编辑快照参数。如需更改这些参数，必须创建一个新的 ClickPipe。 -* 向现有 ClickPipe 添加表时，无法更改快照参数。新表将沿用现有参数。 -* 分区键列不应包含 `NULL` 值，因为分区逻辑会跳过这些值。 \ No newline at end of file +* 向现有 ClickPipe 添加表时，无法更改快照参数。新表将沿用现有参数。 \ No newline at end of file diff --git a/zh/integrations/language-clients/go/config-reference.mdx b/zh/integrations/language-clients/go/config-reference.mdx index 004905cd6..e3086a04c 100644 --- a/zh/integrations/language-clients/go/config-reference.mdx +++ b/zh/integrations/language-clients/go/config-reference.mdx @@ -109,10 +109,16 @@ GetJWT: func(ctx context.Context) (string, error) { ### 超时
-| 选项 | 类型 | 默认值 | DSN 参数 | 说明 | 最佳实践 | 配置不当时 | -| ------------- | --------------- | ----------- | -------------- | -------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------- | -| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 建立新连接的最长等待时间。达到 `MaxOpenConns` 时，它也控制从连接池获取连接的等待时间。 | LAN 环境下为 5-10 秒，WAN/云环境下为 15-30 秒。切勿低于 1 秒。 | 过短：拥塞期间出现 `"clickhouse: acquire conn timeout"`。过长 (> 60 秒) ：故障期间应用会一直挂起。 | -| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 单次 read 调用等待服务器响应的最长时间。按每个块生效，而非整个查询。`Context` 截止时间优先生效。 | 较短的交互式查询设为 10-30 秒；较长的分析型查询设为 5-30 分钟。 | 过短：查询中途出现 `"i/o timeout"` 或 `"read: connection reset by peer"`；服务器仍会继续执行。过长：无法及时检测失效连接。 | +| 选项 | 类型 | 默认值 | DSN 参数 | 说明 | 最佳实践 | 配置不当时 | +| ------------- | --------------- | ----------- | -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | 建立新连接的最长等待时间。达到 `MaxOpenConns` 时，它也控制从连接池获取连接的等待时间。 | LAN 环境下为 5-10 秒，WAN/云环境下为 15-30 秒；如果连接到已休眠的 ClickHouse Cloud 服务，则为 1-2 分钟。切勿低于 1 秒。 | 过短：拥塞期间出现 `"clickhouse: acquire conn timeout"`，或在已休眠的 Cloud 服务完成唤醒前连接失败。过长 (> 60 秒)：故障期间应用会一直挂起。 | +| `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | 单次 read 调用等待服务器响应的最长时间。按每个块生效，而非整个查询。`Context deadline` 优先生效。 | 较短的交互式查询设为 10-30 秒；较长的分析型查询设为 5-30 分钟。 | 过短：查询中途出现 `"i/o timeout"` 或 `"read: connection reset by peer"`；服务器仍会继续执行。过长：无法及时检测失效连接。 | + + + 已空闲的 ClickHouse Cloud 服务会被暂停，并在收到第一个传入连接时唤醒。唤醒通常需要几十秒，在此期间拨号会阻塞。如果 `DialTimeout` 低于唤醒时间，则空闲一段时间后的第一次查询会因拨号超时而失败，而不是正常执行。 + + 对于可能是第一个访问已休眠服务的 client，请将 `DialTimeout` 设为 `1m`–`2m`。代价是在真实故障期间检测失败会更慢——拨号会一直阻塞到完整超时时间后才报错——因此更建议只对首次连接应用较高的超时，或在单个查询上使用 Context deadline 来限制端到端耗时。 + *** diff --git a/zh/integrations/language-clients/go/configuration.mdx b/zh/integrations/language-clients/go/configuration.mdx index cdfb02b65..5afebb668 100644 --- a/zh/integrations/language-clients/go/configuration.mdx +++ b/zh/integrations/language-clients/go/configuration.mdx @@ -17,32 +17,32 @@ doc_type: '参考' 打开连接时，可以使用 `Options` 结构体来控制客户端行为。可用设置如下： -| 参数 | 类型 | 默认值 | 说明 | -| ---------------------- | -------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- | -| `Protocol` | `Protocol` | `Native` | 传输协议：`Native` (TCP) 或 `HTTP`。请参阅 [TCP 与 HTTP](#tcp-vs-http)。 | -| `Addr` | `[]string` | — | `host:port` 地址切片。有关多个节点的配置，请参阅 [连接到多个节点](#connecting-to-multiple-nodes)。 | -| `Auth` | `Auth` | — | 身份验证凭据 (`Database`、`Username`、`Password`) 。请参阅 [身份验证](#authentication)。 | -| `TLS` | `*tls.Config` | `nil` | TLS 配置。非 `nil` 值会启用 TLS。请参阅 [TLS](#using-tls)。 | -| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | 自定义拨号函数，用于控制 TCP 连接的建立方式。 | -| `DialTimeout` | `time.Duration` | `30s` | 打开新连接时的最大等待时间。 | -| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 任意时刻允许打开的最大连接数。 | -| `MaxIdleConns` | `int` | `5` | 连接池中保留的空闲连接数。 | -| `ConnMaxLifetime` | `time.Duration` | `1h` | 连接池中连接的最大存活时间。请参阅 [连接池](#connection-pooling)。 | -| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | 从 `Addr` 中选择节点的策略。请参阅 [连接到多个节点](#connecting-to-multiple-nodes)。 | -| `BlockBufferSize` | `uint8` | `2` | 并行解码的块数。值越高，吞吐量越高，但内存开销也会增加。可通过上下文按查询覆盖。 | -| `Settings` | `Settings` | — | 应用于每个查询的 ClickHouse 设置映射。单个查询可通过 [context](/zh/integrations/language-clients/go/clickhouse-api#using-context) 覆盖。 | -| `Compression` | `*Compression` | `nil` | 块级压缩。请参阅 [压缩](#compression)。 | -| `ReadTimeout` | `time.Duration` | — | 单次调用中，从服务器读取数据时的最大等待时间。 | -| `FreeBufOnConnRelease` | `bool` | `false` | 如果为 true，则每次查询时都会将该连接的内存缓冲区释放回池中。可降低内存使用，但会带来少量 CPU 开销。 | -| `Logger` | `*slog.Logger` | `nil` | 结构化日志记录器 (Go `log/slog`) 。请参阅 [日志](#logging)。 | -| `Debug` | `bool` | `false` | **已弃用。** 请改用 `Logger`。启用向 stdout 输出旧版调试信息。 | -| `Debugf` | `func(string, ...any)` | — | **已弃用。** 请改用 `Logger`。自定义调试日志函数。需要 `Debug: true`。 | -| `GetJWT` | `GetJWTFunc` | — | 返回用于 ClickHouse Cloud 身份验证的 JWT 令牌的回调 (仅 HTTPS) 。 | -| `HttpHeaders` | `map[string]string` | — | 每个请求都会发送的附加 HTTP 请求头 (仅 HTTP 传输) 。 | -| `HttpUrlPath` | `string` | — | 附加到 HTTP 请求中的额外 URL 路径 (仅 HTTP 传输) 。 | -| `HttpMaxConnsPerHost` | `int` | — | 覆盖底层 `http.Transport` 中的 `MaxConnsPerHost` (仅 HTTP 传输) 。 | -| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | 自定义 HTTP 传输工厂。会传入默认 `transport` 以便有选择地进行覆盖 (仅 HTTP 传输) 。 | -| `HTTPProxyURL` | `*url.URL` | — | 所有请求使用的 HTTP 代理 URL (仅 HTTP 传输) 。 | +| 参数 | 类型 | 默认值 | 说明 | +| ---------------------- | -------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `Protocol` | `Protocol` | `Native` | 传输协议：`Native` (TCP) 或 `HTTP`。请参阅 [TCP 与 HTTP](#tcp-vs-http)。 | +| `Addr` | `[]string` | — | `host:port` 地址切片。有关多个节点的配置，请参阅 [连接到多个节点](#connecting-to-multiple-nodes)。 | +| `Auth` | `Auth` | — | 身份验证凭据 (`Database`、`Username`、`Password`) 。请参阅 [身份验证](#authentication)。 | +| `TLS` | `*tls.Config` | `nil` | TLS 配置。非 `nil` 值会启用 TLS。请参阅 [TLS](#using-tls)。 | +| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | 自定义拨号函数，用于控制 TCP 连接的建立方式。 | +| `DialTimeout` | `time.Duration` | `30s` | 打开新连接时的最大等待时间。连接到可能处于空闲状态的 ClickHouse Cloud 服务时，请将其提高到 `1m`–`2m`——请参阅 [超时](/zh/integrations/language-clients/go/config-reference#timeouts)。 | +| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 任意时刻允许打开的最大连接数。 | +| `MaxIdleConns` | `int` | `5` | 连接池中保留的空闲连接数。 | +| `ConnMaxLifetime` | `time.Duration` | `1h` | 连接池中连接的最大存活时间。请参阅 [连接池](#connection-pooling)。 | +| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | 从 `Addr` 中选择节点的策略。请参阅 [连接到多个节点](#connecting-to-multiple-nodes)。 | +| `BlockBufferSize` | `uint8` | `2` | 并行解码的块数。值越高，吞吐量越高，但内存开销也会增加。可通过上下文按查询覆盖。 | +| `Settings` | `Settings` | — | 应用于每个查询的 ClickHouse 设置映射。单个查询可通过 [context](/zh/integrations/language-clients/go/clickhouse-api#using-context) 覆盖。 | +| `Compression` | `*Compression` | `nil` | 块级压缩。请参阅 [压缩](#compression)。 | +| `ReadTimeout` | `time.Duration` | — | 单次调用中，从服务器读取数据时的最大等待时间。 | +| `FreeBufOnConnRelease` | `bool` | `false` | 如果为 true，则每次查询时都会将该连接的内存缓冲区释放回池中。可降低内存使用，但会带来少量 CPU 开销。 | +| `Logger` | `*slog.Logger` | `nil` | 结构化日志记录器 (Go `log/slog`) 。请参阅 [日志](#logging)。 | +| `Debug` | `bool` | `false` | **已弃用。** 请改用 `Logger`。启用向 stdout 输出旧版调试信息。 | +| `Debugf` | `func(string, ...any)` | — | **已弃用。** 请改用 `Logger`。自定义调试日志函数。需要 `Debug: true`。 | +| `GetJWT` | `GetJWTFunc` | — | 返回用于 ClickHouse Cloud 身份验证的 JWT 令牌的回调 (仅 HTTPS) 。 | +| `HttpHeaders` | `map[string]string` | — | 每个请求都会发送的附加 HTTP 请求头 (仅 HTTP 传输) 。 | +| `HttpUrlPath` | `string` | — | 附加到 HTTP 请求中的额外 URL 路径 (仅 HTTP 传输) 。 | +| `HttpMaxConnsPerHost` | `int` | — | 覆盖底层 `http.Transport` 中的 `MaxConnsPerHost` (仅 HTTP 传输) 。 | +| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | 自定义 HTTP 传输工厂。会传入默认 `transport` 以便有选择地进行覆盖 (仅 HTTP 传输) 。 | +| `HTTPProxyURL` | `*url.URL` | — | 所有请求使用的 HTTP 代理 URL (仅 HTTP 传输) 。 | ```go conn, err := clickhouse.Open(&clickhouse.Options{ diff --git a/zh/products/cloud/guides/index.mdx b/zh/products/cloud/guides/index.mdx index fb30adbc2..2c614a2bb 100644 --- a/zh/products/cloud/guides/index.mdx +++ b/zh/products/cloud/guides/index.mdx @@ -62,7 +62,6 @@ keywords: ['cloud guides', 'documentation', 'how-to', 'cloud features', 'tutoria | [管理我的账户](/zh/products/cloud/guides/security/cloud-access-management/manage-my-account) | 本页介绍如何接受邀请、管理 MFA 设置和重置密码 | | [管理 SQL 控制台角色分配](/zh/products/cloud/guides/security/cloud-access-management/manage-sql-console-role-assignments) | 介绍如何管理 SQL 控制台角色分配的指南 | | [管理 AWS 服务限制和配额](/zh/products/bring-your-own-cloud/reference/aws-service-limits) | 介绍 BYOC 接入前需要核查的 AWS 服务配额、如何申请提高配额，以及随着服务扩展需要监控的内容 | -| [从 CMEK v1 迁移到 v2](/zh/products/cloud/guides/security/cmek-migration) | 从旧版 CMEK 迁移到版本 2 的说明 | | [多租户](/zh/products/cloud/guides/best-practices/multitenancy) | 实施多租户的最佳实践 | | [使用语义层优化 ClickHouse Assistant agent 对话](/zh/products/cloud/features/ai-ml/aichat/customizing-semantic-layer) | 介绍如何使用 AGENTS.md 为 ClickHouse Assistant 聊天 agent 提供自定义业务逻辑和数据专属说明的指南 | | [概览](/zh/products/cloud/guides/infrastructure/deployment-options/byoc/overview) | 在您自己的云基础设施上部署 ClickHouse | diff --git a/zh/products/cloud/guides/security/cmek-migration.mdx b/zh/products/cloud/guides/security/cmek-migration.mdx deleted file mode 100644 index 8b9278ab1..000000000 --- a/zh/products/cloud/guides/security/cmek-migration.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebarTitle: '旧版 CMEK 迁移' -slug: /cloud/security/cmek-migration -title: '从 CMEK v1 迁移到 v2' -description: '从旧版 CMEK 迁移到版本 2 的说明' -doc_type: 'guide' -keywords: ['ClickHouse Cloud', '加密', 'CMEK'] ---- - -我们正在提升采用客户管理加密密钥 (CMEK) 的服务的安全性。现在，所有服务都已为每个服务配置唯一的 AWS Role，用于授权使用客户密钥对服务进行加密和解密。这个新角色仅会显示在服务配置界面中。 - -这一新流程同时支持 OpenAPI 和 Terraform。更多信息，请参阅我们的文档 ([增强加密](/zh/products/cloud/guides/security/cmek)、[Cloud API](/zh/products/cloud/features/admin-features/api/api-overview)、[官方 Terraform Provider](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)) 。 - - - 使用 CMEK v1 的客户必须最迟在 2026 年 6 月 1 日前完成服务迁移。超过该日期后，客户管理密钥将默认轮换为 ClickHouse 管理密钥。完成默认迁移后，客户仍可再轮换回客户管理密钥。 - - -
- ## 手动迁移 -
- -完成以下步骤以迁移到新流程： - -1. 登录 https://console.clickhouse.cloud -2. 点击已加密的服务 -3. 点击左侧的“服务设置” -4. 滚动到页面底部并展开“查看服务详情” -5. 复制加密 Role ID (IAM) -6. 前往 AWS 中的 KMS 密钥，并更新 Key Policy，添加以下内容： - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -7. 在 ClickHouse Cloud 中，提交一个支持工单，告知我们可以启用这一新方法。此更改需要重启服务；如果您有最适合重启服务的日期/时间，请告知我们。 -8. 在我们重启服务后，前往 AWS 中的 KMS 密钥，并从 Key Policy 中移除以下内容： - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -9. 更新完成！ - -
- ## Terraform 迁移 -
- -1. 升级到 [Terraform 3.5.0 或更高版本](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) -2. 在不做任何修改的情况下运行 Terraform apply。Terraform state 中会出现一个新的 transparent_data_encryption 字段。请记下此处的 role_id。 -3. 前往 AWS 中的 KMS 密钥，并更新 Key Policy，添加以下内容： - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": ["Encryption role ID (ARN)"] - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:DescribeKey" - ], - "Resource": "*" -} -``` - -4. 在 ClickHouse Cloud 中，附上服务 name 提交一个支持工单，告知我们启用这种新方法。此更改需要重启服务；如果您有最适合重启服务的日期/时间，请告知我们。 -5. 在我们重启服务后，您可以将 transparent_data_encryption.enabled 设置更新为‘True’，并在 Terraform 中移除层级设置后应用。这将不会产生任何变更。 -6. 前往 AWS 中的 KMS 密钥，并从 Key Policy 中移除以下内容： - -```json -{ - "Sid": "Allow ClickHouse Access", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role" - }, - "Action": ["kms:GetPublicKey", - "kms:Decrypt", - "kms:GenerateDataKeyPair", - "kms:Encrypt", - "kms:GetKeyRotationStatus", - "kms:GenerateDataKey", - "kms:DescribeKey"], - "Resource": "*" -} -``` - -7. 更新已完成！ \ No newline at end of file diff --git a/zh/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx b/zh/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx index 9d4e67e01..f449e4745 100644 --- a/zh/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx +++ b/zh/products/cloud/guides/security/connectivity/private-networking/aws-privatelink.mdx @@ -21,6 +21,7 @@ import ScalePlanFeatureBadge from "/snippets/components/ScalePlanFeatureBadge/Sc * sa-east-1 * il-central-1 * me-south-1 + * mx-central-1 * eu-central-2 * eu-north-1 * eu-south-2 @@ -51,10 +52,10 @@ import ScalePlanFeatureBadge from "/snippets/components/ScalePlanFeatureBadge/Sc **请完成以下步骤以启用 AWS PrivateLink**： -1. 获取 Endpoint "Service name"。 -2. 创建 AWS Endpoint。 -3. 将 "Endpoint ID" 添加到 ClickHouse Cloud 组织。 -4. 将 "Endpoint ID" 添加到 ClickHouse 服务允许列表。 +1. 获取端点 "Service name"。 +2. 创建 AWS 端点。 +3. 将 "端点 ID" 添加到 ClickHouse Cloud organization。 +4. 将 "端点 ID" 添加到 ClickHouse 服务允许列表。 可在[此处](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/)找到 Terraform 示例。 diff --git a/zh/products/cloud/navigation.json b/zh/products/cloud/navigation.json index fc9c1c67c..19bff0f7c 100644 --- a/zh/products/cloud/navigation.json +++ b/zh/products/cloud/navigation.json @@ -320,8 +320,7 @@ "group": "Data security", "pages": [ "zh/products/cloud/guides/security/data-masking", - "zh/products/cloud/guides/security/cmek", - "zh/products/cloud/guides/security/cmek-migration" + "zh/products/cloud/guides/security/cmek" ] }, { @@ -339,7 +338,7 @@ }, { "group": "API reference", - "openapi": "_specs/cloud-openapi.json" + "openapi": "zh/_specs/cloud-openapi.json" } ] }, diff --git a/zh/products/kubernetes-operator/guides/configuration.mdx b/zh/products/kubernetes-operator/guides/configuration.mdx index 679da68e0..fa28752b8 100644 --- a/zh/products/kubernetes-operator/guides/configuration.mdx +++ b/zh/products/kubernetes-operator/guides/configuration.mdx @@ -267,16 +267,16 @@ spec: 为 ClickHouse 容器配置 CPU 和内存： ```yaml -# 默认值 +# default values spec: containerTemplate: resources: requests: cpu: "250m" - memory: "256Mi" + memory: "512Mi" limits: cpu: "1" - memory: "1Gi" + memory: "512Mi" ```
@@ -321,6 +321,8 @@ spec: ## TLS/SSL 配置
+如需查看端到端示例 (包括使用 cert-manager 签发证书、通过安全端口连接客户端，以及加密 Keeper 流量) ，请参阅 [使用 TLS 进行安全防护](/zh/products/kubernetes-operator/guides/tls) 指南。 +
### 配置安全端点
@@ -371,6 +373,323 @@ spec: key: ``` +
+ ## 外部 Secret +
+ +默认情况下，operator 会创建并管理一个 Secret，其中包含集群的内部凭据 (interserver 密码、管理密码、Keeper 身份、集群 secret、named-collections 密钥) 。该 Secret 以集群名称命名，并位于集群所在的命名空间中。 + +如果你想自行管理这些凭据——例如从 HashiCorp Vault、AWS Secrets Manager 或 [External Secrets Operator](https://external-secrets.io/) 获取——可以使用 `spec.externalSecret` 将 operator 指向一个预先创建的 Secret： + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 2 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 10Gi + externalSecret: + name: my-clickhouse-credentials + policy: Observe +``` + + + 这里引用的 Secret 必须与 ClickHouseCluster 位于**同一命名空间**。该 operator 绝不会删除并非由其创建的 Secret。 + + +
+ ### 必需的键 +
+ +Secret 必须包含以下键： + +| Key | Format | When required | +| ----------------------- | ----------------------------------- | -------------------------- | +| `interserver-password` | 明文密码 | 始终需要 | +| `management-password` | 明文密码 | 始终需要 | +| `keeper-identity` | `clickhouse:` | 始终需要 | +| `cluster-secret` | 明文密码 | 始终需要 | +| `named-collections-key` | 以十六进制编码的 16 字节 AES 密钥 (32 个十六进制字符) | 仅适用于 ClickHouse `>= 25.12` | + +一个完整的 Secret 如下所示： + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-clickhouse-credentials + namespace: sample +type: Opaque +stringData: + interserver-password: "a-strong-random-password" + management-password: "another-strong-password" + keeper-identity: "clickhouse:keeper-auth-password" + cluster-secret: "cluster-internal-secret" + named-collections-key: "0123456789abcdef0123456789abcdef" # 32 hex chars = 16 bytes +``` + +
+ ### 策略：Observe 与 Manage +
+ +`spec.externalSecret.policy` 用于控制 Operator 如何处理缺失的必需键： + +| Policy | 键缺失时的行为 | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `Observe` (默认) | 在所有必需键都存在之前，协调会被**阻塞**。Operator 会通过 `ExternalSecretValid` 条件 (reason 为 `ExternalSecretInvalid`) 和一个 `Warning` 事件，报告每个缺失的键及其对应的格式提示。 | +| `Manage` | Operator 会**生成**所有缺失的必需键，并将它们写回同一个 Secret。适用于引导场景：先创建一个空 Secret，让 Operator 将其补齐，然后再按需收紧访问权限。Operator 仍然绝不会删除该 Secret。 | + + + 即使设置了 `policy: Manage`，该 Secret 也必须已存在于命名空间中——Operator 绝不会自行创建 Secret，它只会将生成的键写入现有的 Secret。 如果引用的 Secret 不存在，则无论采用哪种 policy，协调都会因 `ExternalSecretNotFound` 而被阻塞。 + + +当外部系统 (Vault、ESO、sealed-secrets、GitOps) 是事实来源，且你希望 Operator 在配置错误时明确报错时，请选择 `Observe`。当你希望实现自给自足的引导，同时仍保留对 Secret 对象本身的所有权 (例如为了备份) 时，请选择 `Manage`。 + +
+ ### 状态条件和故障排查 +
+ +Operator 会在 `ClickHouseCluster.status.conditions` 中暴露 `ExternalSecretValid` 条件。协调过程看起来卡住时，请检查它： + +```bash +# Plain kubectl — works out of the box +kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p' + +# Same data as YAML +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' + +# Pretty-printed JSON (requires jq) +kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq +``` + +可能的原因： + +| `reason` | 含义 | 处理方式 | +| ------------------------ | -------------------------------------------------------- | ------------------------------------------ | +| `ExternalSecretNotFound` | 被引用的 Secret 在该命名空间中不存在。 | 创建该 Secret，或修正 `spec.externalSecret.name`。 | +| `ExternalSecretInvalid` | Secret 存在，但缺少必需的键 (仅在使用 `Observe` 时) 。消息会列出每个缺失的键及其预期格式。 | 添加缺失的键，或切换为 `policy: Manage`。 | +| `ExternalSecretValid` | 所有必需的键都已存在，并且 operator 正在使用该 Secret。 | — | + +当 Secret 无效时，operator 会将协调重新入队，因此一旦补齐缺失的键，下一次协调就会自动生效——无需重启 Pod (容器组) 。 + + + 所需键的集合取决于当前运行的 ClickHouse 版本。只有在 operator 的版本探测检测到 ClickHouse `25.12` 或更高版本后，才会校验 `named-collections-key`。在较旧版本中，Secret 可以不包含该键。 + + +
+ ## 附加端口 +
+ +该 Operator 会在每个 ClickHouse pod (容器组) 及其无头 Service 上暴露一组固定端口：`8123` HTTP、`9000` native、`9009` interserver、`9001` management、`9363` Prometheus 指标，以及启用 TLS 时对应的 `8443`/`9440` TLS 端口变体。若要让 ClickHouse 监听更多协议 (如 MySQL、PostgreSQL、gRPC 或其他自定义端口) ，请在 `spec.additionalPorts` 中声明： + +```yaml +spec: + additionalPorts: + - name: mysql + port: 9004 + - name: postgres + port: 9005 + - name: grpc + port: 9100 +``` + +operator 会将这些端口添加到 Pod 的 `containerPorts` 和无头 Service 中。完整示例见 [`examples/custom_protocols.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/custom_protocols.yaml)。 + + + `additionalPorts` 只会在 Kubernetes 这一侧开放端口。它**不会**配置 ClickHouse 服务器 在这些端口上监听。你还需要在 `spec.settings.extraConfig.protocols` 中启用对应的协议。否则，虽然 Service 上的端口已开放，但 pod (容器组) 内部不会有任何程序响应。 + + +
+ ### 端到端示例：MySQL wire 协议 +
+ +要通过 MySQL wire 协议在端口 `9004` 上对外暴露 ClickHouse： + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: sample +spec: + replicas: 1 + keeperClusterRef: + name: sample + dataVolumeClaimSpec: + resources: + requests: + storage: 2Gi + + # 1) Open the port on the Pod and the headless Service. + additionalPorts: + - name: mysql + port: 9004 + + # 2) Tell ClickHouse server to actually listen on it. + settings: + extraConfig: + protocols: + mysql: + type: mysql + port: 9004 + description: "MySQL wire protocol" +``` + +应用完成后，在集群内部验证： + +```bash +kubectl exec sample-clickhouse-0-0-0 -- \ + clickhouse-client --port 9004 --query "SELECT 1" +``` + +
+ ### 字段约束 +
+ +| 字段 | 规则 | +| ------ | -------------------------------------------------------------------------------------------- | +| `name` | 必须匹配 DNS_LABEL 模式 `^[a-z]([-a-z0-9]*[a-z0-9])?$`，最长 63 个字符。CRD 会将其作为 list-map 键来强制保证唯一性。 | +| `port` | `[1, 65535]` 范围内的整数。webhook 会拒绝列表中重复的端口号。 | + +
+ ### 保留端口和名称 +
+ +validating webhook 会拒绝与 operator 自身绑定端口发生冲突的 `additionalPorts` 条目。所有与 TLS 相关的端口都会被**无条件**保留，以确保后续切换 `spec.settings.tls.enabled` 时，不会破坏原本有效的集群。 + +| Port | 保留用途 | +| ------ | ------------- | +| `8123` | HTTP | +| `8443` | HTTPS | +| `9000` | native TCP | +| `9440` | native TLS | +| `9009` | interserver | +| `9001` | management | +| `9363` | Prometheus 指标 | + +以下名称也会被拒绝——它们是 operator 的内部协议类型标识符 (而非便于人工阅读的别名) ： + +| Name | +| ------------- | +| `http` | +| `http-secure` | +| `tcp` | +| `tcp-secure` | +| `interserver` | +| `management` | +| `prometheus` | + +被拒绝的请求会产生如下错误： + +``` +spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port +spec.additionalPorts[0].name: "http" is reserved by the operator +``` + +
+ ## 版本探测与升级通道 +
+ +operator 会针对 cluster 版本执行两项彼此独立的操作： + +1. **版本探测** — 一个 Kubernetes `Job`，会将容器镜像运行一次，以检测当前运行的 ClickHouse / Keeper 版本。检测到的版本会记录到 `.status.version` 中，并用于其他协调步骤 (例如，名为 `外部 Secret` 的 named-collections key 仅在 ClickHouse `25.12` 及以上版本中才需要) 。 +2. **升级通道** — 定期检查公开的 ClickHouse 发布源 (`https://clickhouse.com/data/version_date.tsv`) 。operator 会通过 `VersionUpgraded` status condition 报告是否有新版本可用。它绝不会自行升级 cluster——镜像标签始终由用户控制。 + +
+ ### 选择发布渠道 +
+ +`spec.upgradeChannel` 用于指定 operator 要对照比较的上游发行版集合。`ClickHouseCluster` 和 `KeeperCluster` 都有这个相同的字段。 + +```yaml +spec: + upgradeChannel: lts # or "stable", or "25.8", or omitted +``` + +允许的值 (由 CRD 按模式 `^(lts|stable|\d+\.\d+)?$` 验证) ： + +| Value | Behavior | +| --------------------------------- | ----------------------------------------------------------------------------------------------------- | +| *empty* (default) | Operator 只会在当前运行的 major.minor 版本线上提示 **次版本** 更新。运行 `25.8.3.1` 的集群会收到 `25.8.4.x` 的更新提示，但不会收到 `25.9.x`。 | +| `stable` | 跟踪上游 `stable` 通道——即 ClickHouse Inc. 在主发行线上标记为稳定版本的最新 release。与 `lts` 通道相比，它会更早接收 major 升级。 | +| `lts` | 跟踪上游 `lts` 通道——即长期支持发行版。接收 major 升级的频率较低，但支持周期更长。 | +| `25.8` (or any `.`) | 将通道固定在特定的 major.minor 版本线上。即使上游已有更新版本，也不会提示超出该版本线的 major 升级。 | + +对于生产环境，通常更建议将通道固定为明确的 `.` (例如 `25.8`) 。这样可以把集群锁定在预期的 major 发行线上，并且当某个副本因某种原因漂移到其他 major 版本时，Operator 会显示 `WrongReleaseChannel` 警告——这一点在镜像通过摘要 (`@sha256:...`) 而不是便于人类阅读的标签引用时尤其重要。对于不担心 major 版本跳变的开发集群，默认的空值也完全适用。 + +
+ ### 状态条件 +
+ +两个 conditions 会体现探测和升级检查的结果： + +| Condition | Reason | Meaning | +| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionInSync` | `VersionMatch` | 所有副本报告的版本都与镜像一致 | +| `VersionInSync` | `VersionMismatch` | 各副本运行的版本不同。在计划内的滚动升级期间，该告警事件会被抑制。通常这会在可变镜像标签被固定时出现 (例如 `latest` 或仅指定主次版本的 `26.3`) ，且底层 registry 在多次拉取之间发生了变化，导致不同副本最终落在同一标签对应的不同补丁版本上。 | +| `VersionInSync` | `VersionPending` | 版本探测 Job 尚未完成 | +| `VersionInSync` | `VersionProbeFailed` | 探测 Job 失败；operator 无法确定当前运行的版本 | +| `VersionUpgraded` | `UpToDate` | 该集群使用的是所选通道中当前可用的最新版本 | +| `VersionUpgraded` | `MinorUpdateAvailable` | 同一 `major.minor` 系列中有更新的补丁版本可用 | +| `VersionUpgraded` | `MajorUpdateAvailable` | 所选通道中有更新的 `major.minor` 版本可用 | +| `VersionUpgraded` | `VersionOutdated` | 当前运行的版本已过时，不会再从所选通道接收修复——通常是因为该主版本系列已被上游从 `lts` 或 `stable` 中移除 | +| `VersionUpgraded` | `WrongReleaseChannel` | 当前运行的镜像不属于所选的 `upgradeChannel`。例如：某个运行 `26.5` 且设置了 `upgradeChannel: lts` 的集群，因为 `26.5` 不属于上游 `lts` 系列。 | +| `VersionUpgraded` | `UpgradeCheckFailed` | operator 无法访问上游发布源 | + +可使用以下方式检查它们： + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +
+ ### 覆盖版本探测 Job +
+ +该探测是通过一个常规的 Kubernetes `Job` 实现的。如果你的集群设置了准入策略，要求指定的 Tolerations、节点选择器或安全上下文，或者你想限制已完成的探测 Job 保留的时间，可以通过 `spec.versionProbeTemplate` 覆盖该模板： + +```yaml +spec: + versionProbeTemplate: + spec: + ttlSecondsAfterFinished: 600 # delete completed probe Jobs 10 minutes after completion + template: + spec: + nodeSelector: + kubernetes.io/arch: amd64 + tolerations: + - key: dedicated + operator: Equal + value: clickhouse + effect: NoSchedule + containers: + - name: version-probe + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +容器名称 `version-probe` 是 operator 的默认名称——`containers:` 下对应的条目会按名称与其匹配，因此 operator 会在默认配置的基础上，将用户提供的字段深度合并进去。 + +
+ ### Operator 级别的控制 +
+ +Operator 管理器上的两个标志可在全局范围内控制升级检查循环： + +| Flag | Default | Effect | +| --------------------------------- | ------- | -------------------------------------------------------------------------- | +| `--version-update-interval` | `24h` | Operator 重新拉取上游版本列表的频率 | +| `--disable-version-update-checks` | `false` | 完全禁用升级检查器。不会设置 `VersionUpgraded` 条件，也不会产生任何发往 `clickhouse.com` 的出站 HTTP 流量 | + +在隔离网络环境中，或者不允许访问 `clickhouse.com` 出站流量时，请设置 `--disable-version-update-checks=true`。 +
## ClickHouse 设置
@@ -485,6 +804,49 @@ spec: 启用后，该 Operator 会将 Replicated 表和集成表同步到新副本。 +
+ ### 服务器日志 +
+ +通过 `spec.settings.logger` 配置 ClickHouse 服务器日志。每个字段都是可选的，并且都有安全的默认值，因此即使你从未改动过，集群也会默认以 `trace` 级别同时将日志输出到容器控制台和磁盘上的轮转文件。 + +```yaml +spec: + settings: + logger: + logToFile: true # Default: true. Set false to log only to the console + jsonLogs: false # Default: false. Set true for structured JSON log lines + level: trace # Default: trace + size: 1000M # Default: 1000M. Rotate a log file once it reaches this size + count: 50 # Default: 50. Number of rotated files to keep +``` + +| 字段 | 默认值 | 描述 | +| ----------- | ------- | ------------------------------------------------------------------------------------------------ | +| `logToFile` | `true` | 当为 `false` 时，operator 会移除文件输出目标，server 只向容器控制台输出日志。 | +| `jsonLogs` | `false` | 当为 `true` 时，operator 会添加 `formatting.type: json`，使每一行都成为一个 JSON 对象。 | +| `level` | `trace` | 日志详细级别。可选值包括 `test`、`trace`、`debug`、`information`、`notice`、`warning`、`error`、`critical`、`fatal`。 | +| `size` | `1000M` | 单个日志文件在轮转前的最大大小。 | +| `count` | `50` | server 保留的轮转后日志文件数量。 | + +operator 始终会保持控制台日志开启，以确保 `kubectl logs` 可用；当 `logToFile` 为 `true` 时，还会额外启用文件日志。使用默认值的集群会生成如下 `logger` 块： + +```yaml +logger: + console: true + level: trace + log: /var/log/clickhouse-server/clickhouse-server.log + errorlog: /var/log/clickhouse-server/clickhouse-server.err.log + size: 1000M + count: 50 +``` + +同样的 `spec.settings.logger` 块也适用于 `KeeperCluster`；不过，operator 会改为将日志文件写入 `/var/log/clickhouse-keeper/`。 + + + 无论 `logToFile` 如何设置，控制台日志始终保持开启，因此即使禁用文件日志，`kubectl logs` 仍可正常使用。将日志发送到可解析 JSON 的结构化日志存储时，请设置 `jsonLogs: true`。 + +
## 自定义配置
diff --git a/zh/products/kubernetes-operator/guides/introduction.mdx b/zh/products/kubernetes-operator/guides/introduction.mdx index 052df677e..79d4551f9 100644 --- a/zh/products/kubernetes-operator/guides/introduction.mdx +++ b/zh/products/kubernetes-operator/guides/introduction.mdx @@ -202,14 +202,14 @@ spec: 如需彻底删除存储： ```bash -# 删除集群 +# Delete cluster kubectl delete clickhousecluster my-cluster -# 等待 Pod（容器组）终止 -kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster +# Wait for pods to terminate +kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse -# 删除 PVC -kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse ```
diff --git a/zh/products/kubernetes-operator/guides/monitoring.mdx b/zh/products/kubernetes-operator/guides/monitoring.mdx new file mode 100644 index 000000000..c58d09756 --- /dev/null +++ b/zh/products/kubernetes-operator/guides/monitoring.mdx @@ -0,0 +1,420 @@ +--- +position: 3 +slug: /clickhouse-operator/guides/monitoring +title: 监控 ClickHouse Operator +keywords: ['kubernetes', 'prometheus', '监控', '指标'] +description: '如何抓取、保护和使用 operator 的指标与健康检查端点。' +doc_type: 'guide' +--- + +operator 会暴露与 Prometheus 兼容的指标以及 Kubernetes 健康探针，以便你观测其协调活动、发现卡住的控制器，并在发生故障时发出告警。 + +本指南将介绍 operator 暴露了哪些内容、如何抓取这些内容，以及哪些查询在日常使用中最实用。 + + + 本指南介绍的是 **operator 进程本身** (controller manager) 。对于 ClickHouse server 指标 (查询、parts、复制延迟) ，请使用 [ClickHouse 中的 Prometheus 端点](/zh/reference/settings/server-settings/settings#prometheus) 单独进行抓取。 + + +
+ ## 端点 +
+ +operator 进程会在 manager pod (容器组) 内暴露两个 HTTP 端点： + +| 端点 | 默认端口 | 路径 | 用途 | +| ---- | --------------------------------- | --------------------- | -------------------- | +| 指标 | `8080` (Helm) / `0` 已禁用 (二进制默认值) | `/metrics` | Prometheus 指标暴露格式 | +| 健康探针 | `8081` | `/healthz`, `/readyz` | Kubernetes 存活性和就绪性检查 | + +直接运行 operator 二进制文件时，指标端点**默认关闭** (`--metrics-bind-address=0`) 。Helm 图表会通过 `metrics.enable: true` 和 `metrics.port: 8080` 启用它。 + +健康探针端点始终启用；部署模板会将 `/healthz` 和 `/readyz` 配置为该 pod (容器组) 在端口 `8081` 上的存活探针和就绪探针。 + +
+ ## Operator 二进制参数 +
+ +相关的 `manager` 参数 (定义在 [`cmd/main.go`](https://github.com/ClickHouse/clickhouse-operator/blob/main/cmd/main.go) 中) ： + +| 标志 | 默认值 | 说明 | +| ----------------------------- | ----------------------------------- | ---------------------------------------------------------------------- | +| `--metrics-bind-address` | `0` (禁用) | 指标端点的绑定地址。设为 `:8443` 以使用 HTTPS，设为 `:8080` 以使用 HTTP。保留为 `0` 可禁用指标服务器。 | +| `--metrics-secure` | `true` | 通过带身份验证/授权的 HTTPS 提供指标服务。设为 `false` 可使用纯 HTTP。 | +| `--metrics-cert-path` | 空 | 存放指标服务器 TLS 证书文件 (`tls.crt`、`tls.key`) 的目录。 | +| `--metrics-cert-name` | `tls.crt` | `--metrics-cert-path` 中的证书文件名。 | +| `--metrics-cert-key` | `tls.key` | `--metrics-cert-path` 中的密钥文件名。 | +| `--enable-http2` | `false` | 为指标**和 webhook**服务器启用 HTTP/2。默认关闭，以缓解 CVE-2023-44487 / CVE-2023-39325。 | +| `--leader-elect` | `false` (二进制程序) / `true` (Helm 图表) | 启用 leader 选举，以确保同一时间只有一个副本执行协调。Helm 图表默认会在 `manager.args` 中设置此参数。 | +| `--health-probe-bind-address` | `:8081` | `/healthz` 和 `/readyz` 的绑定地址。 | + + + 该参数帮助文本中的 `8443` (HTTPS) / `8080` (HTTP) 约定仅作提示。Helm 图表会在 `8080` 上提供 HTTPS，因为它同时设置了 `metrics.port: 8080` 和 `metrics.secure: true`。这里不会根据端口检测模式——选择 HTTPS 还是 HTTP 取决于 `--metrics-secure`。 + + +
+ ## 通过 Helm 启用指标 +
+ +该 Helm 图表 已为指标端口创建了一个 `Service`，并且还可选择为 prometheus-operator 创建 `ServiceMonitor`。 + +指标端点默认已启用 (`metrics.enable: true`、端口 `8080`，并通过 `metrics.secure: true` 以 HTTPS 方式提供服务) 。通常你唯一需要修改的设置是 `prometheus.enable`，这样 Helm 图表 就会为你创建一个 `ServiceMonitor`： + +```yaml +# values.yaml — minimal override +prometheus: + enable: true +``` + +如果不使用 cert-manager，还需要设置 `certManager.enable: false`。此时，ServiceMonitor 将以 `insecureSkipVerify: true` 抓取指标，仅依赖 bearer-token 身份验证。 + +完整的指标相关默认配置如下： + +```yaml +metrics: + enable: true + port: 8080 + secure: true # HTTPS with authn/authz enforced on every scrape + +certManager: + enable: true # Issues the metrics server certificate + +prometheus: + enable: false # Set to true to render the ServiceMonitor + scraping_annotations: false # Alternative: prometheus.io/scrape pod annotations +``` + +应用： + +```bash +helm upgrade --install clickhouse-operator \ + oci://ghcr.io/clickhouse/clickhouse-operator-helm \ + -n clickhouse-operator-system --create-namespace \ + -f values.yaml +``` + +安装后，Helm 图表 会创建： + +* `Service/-metrics-service` — 暴露端口 `8080` (当 `metrics.secure: true` 时使用 HTTPS) 。 +* `ServiceMonitor/-controller-manager-metrics-monitor` — 在 `prometheus.enable: true` 时创建。 +* `ClusterRole/-metrics-reader` — 为非资源 URL `/metrics` 授予 `get` 权限。 + +
+ ## 保护指标端点 +
+ +当 `metrics.secure: true` 时，指标服务器会对每次抓取都强制启用 TLS **和** Kubernetes 身份验证/授权。抓取器必须： + +1. 提供有效的 Kubernetes Bearer 令牌。 +2. 使用一个绑定到集群角色的 ServiceAccount，且该集群角色被授予对非资源 URL `/metrics` 执行 `get` 的权限。 + +该 Helm 图表 附带了这样一个集群角色： + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: clickhouse-operator-metrics-reader +rules: + - nonResourceURLs: + - /metrics + verbs: + - get +``` + +将其绑定到抓取器 (通常为 Prometheus) 使用的 ServiceAccount： + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: prometheus-clickhouse-operator-metrics-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: clickhouse-operator-metrics-reader +subjects: + - kind: ServiceAccount + name: + namespace: +``` + + + 如果指标端点返回 `401 Unauthorized` 或 `403 Forbidden`，则说明抓取器正在使用 HTTPS，但缺少 Kubernetes Bearer 令牌、该令牌未获授权，或者其 ServiceAccount 缺少上述绑定。在共享集群中，**不建议**通过设置 `metrics.secure: false` 来禁用安全性，因为任何能够通过网络访问该 pod (容器组) 的人都可能抓取该端点。 + + +
+ ## ServiceMonitor 参考 +
+ +当 `prometheus.enable: true` 时，该 Helm 图表 会渲染出如下形态的 ServiceMonitor： + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: -controller-manager-metrics-monitor + namespace: + labels: + control-plane: controller-manager +spec: + selector: + matchLabels: + control-plane: controller-manager + endpoints: + - path: /metrics + port: https # "http" when metrics.secure: false + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + serverName: -metrics-service..svc + ca: + secret: + name: metrics-server-cert + key: ca.crt + cert: + secret: + name: metrics-server-cert + key: tls.crt + keySecret: + name: metrics-server-cert + key: tls.key +``` + +如果你的 Prometheus 实例未运行 cert-manager，请设置 `tlsConfig.insecureSkipVerify: true`，并仅依赖 bearer-token 身份验证——当 `certManager.enable: false` 时，该 chart 已默认这样做。 + +
+ ## 独立 Prometheus 示例 +
+ +如果您未使用 kube-prometheus-stack，该仓库在 [`examples/prometheus_secure_metrics_scraper.yaml`](https://github.com/ClickHouse/clickhouse-operator/blob/main/examples/prometheus_secure_metrics_scraper.yaml) 中提供了一个完整的独立示例。它会创建一个 ServiceAccount、所需的 RBAC，以及一个用于选取该 operator 的 ServiceMonitor 的 `Prometheus` CR。 + +
+ ## 健康探针端点 +
+ +| Path | 用途 | 返回值 | +| ---------- | --------------- | --------------------------- | +| `/healthz` | Kubernetes 存活探针 | 只要探针服务器处于监听状态，就返回 `200 OK`。 | +| `/readyz` | Kubernetes 就绪探针 | 只要探针服务器处于监听状态，就返回 `200 OK`。 | + +这两个端点都注册了同一个简单的 Ping 检查 (`sigs.k8s.io/controller-runtime` 中的 `healthz.Ping`) 。因此，探针失败表示“manager 进程未在 `:8081` 上提供 HTTP 服务”，而不是“控制器不健康”。要检测控制器级别的问题，请改用[协调指标](#reconciliation-activity)。 + +默认情况下，这两个端点都通过端口 `8081` 提供服务。它们接入部署的方式如下： + +```yaml +livenessProbe: + httpGet: + path: /healthz + port: 8081 + initialDelaySeconds: 15 + periodSeconds: 20 +readinessProbe: + httpGet: + path: /readyz + port: 8081 + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +探针反复失败通常意味着探针服务本身根本没有启动起来——例如，manager 在启动过程中提前退出。请检查 manager 日志，查看是否有 `unable to start manager`、RBAC 失败或 `cache did not sync` 错误。 + +
+ ## 指标目录 +
+ +该 Operator 不会注册自定义的 Prometheus 收集器。以下内容均由底层的 `controller-runtime` 和 `client-go` 库暴露。按用途分组后，最有用的序列包括： + +
+ ### 协调活动 +
+ +| 指标 | 类型 | 标记 | +| -------------------------------------------------- | --------- | -------------------------------------------------------------------------- | +| `controller_runtime_reconcile_total` | counter | `controller`, `result` (`success` / `error` / `requeue` / `requeue_after`) | +| `controller_runtime_reconcile_errors_total` | counter | `controller` | +| `controller_runtime_reconcile_time_seconds_bucket` | histogram | `controller` | +| `controller_runtime_active_workers` | gauge | `controller` | +| `controller_runtime_max_concurrent_reconciles` | gauge | `controller` | + +`controller` 标记是 `controller-runtime` 根据通过 `For(...)` 注册的资源类型推导出来的。按当前 `internal/controller/clickhouse` 和 `internal/controller/keeper` 中的代码，它们分别对应 `clickhousecluster` 和 `keepercluster`。如果你自定义了 operator，请对 `/metrics` 执行一次性抓取以进行验证。 + +
+ ### 工作队列 +
+ +| 指标 | 类型 | 标记 | +| --------------------------------------------- | --------- | -------------------------------- | +| `workqueue_depth` | gauge | `name`, `controller`, `priority` | +| `workqueue_adds_total` | counter | `name`, `controller` | +| `workqueue_retries_total` | counter | `name`, `controller` | +| `workqueue_unfinished_work_seconds` | gauge | `name`, `controller` | +| `workqueue_longest_running_processor_seconds` | gauge | `name`, `controller` | +| `workqueue_queue_duration_seconds_bucket` | histogram | `name`, `controller` | +| `workqueue_work_duration_seconds_bucket` | histogram | `name`, `controller` | + +`name` 和 `controller` 这两个标记的值相同 (即控制器名称) 。 + +
+ ### API 服务器流量 +
+ +| 指标 | 类型 | 标记 | +| ---------------------------- | --- | ------------------------ | +| `rest_client_requests_total` | counter | `code`, `method`, `host` | + +
+ ### Leader 选举 +
+ +| 指标 | 类型 | 标记 | +| ------------------------------- | ----- | ------------------------------------ | +| `leader_election_master_status` | gauge | `name` (= `d4ceba06.clickhouse.com`) | + +Helm 图表默认启用 `--leader-elect`，因此在标准 Helm 安装中会提供此指标。若直接运行该二进制文件且未使用此标志，则不会提供该指标。 + +
+ ### 运行时 +
+ +标准 Go 进程和运行时采集器——`go_goroutines`、`go_memstats_*`、`process_cpu_seconds_total`、`process_resident_memory_bytes` 等。 + +
+ ## 常用 PromQL 查询 +
+ +
+ ### 健康总览 +
+ +```promql +# Reconciliation rate per controller +sum by (controller) (rate(controller_runtime_reconcile_total[5m])) + +# Error rate per controller (alert if > 0 sustained) +sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) + +# p99 reconcile latency +histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m])) +) +``` + +
+ ### 积压检测 +
+ +```promql +# Pending items in the work queue — a sustained value > 0 indicates a backlog, +# but short spikes during large reconciles are normal. +avg_over_time(workqueue_depth[10m]) + +# Reconciles that have been running for a long time +workqueue_longest_running_processor_seconds > 60 +``` + +
+ ### 限流与 API 压力 +
+ +```promql +# Throttled requests to the API server +sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m])) +``` + +
+ ### Leader 状态 (HA 部署) +
+ +```promql +# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default) +sum(leader_election_master_status{name="d4ceba06.clickhouse.com"}) +``` + +
+ ## 建议的告警 +
+ +PrometheusRule 的参考起点 (请根据你的环境调整阈值) ： + +```yaml +groups: + - name: clickhouse-operator + rules: + - alert: ClickHouseOperatorReconcileErrors + # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts. + expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1 + for: 15m + labels: + severity: warning + annotations: + summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}' + + - alert: ClickHouseOperatorWorkqueueBacklog + # avg_over_time avoids alerting on transient bursts during large reconciles. + expr: avg_over_time(workqueue_depth[10m]) > 5 + for: 30m + labels: + severity: warning + annotations: + summary: 'Operator work queue backlog sustained for 30m' + + - alert: ClickHouseOperatorReconcileSlow + expr: | + histogram_quantile( + 0.99, + sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m])) + ) > 30 + for: 15m + labels: + severity: warning + annotations: + summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s' + + - alert: ClickHouseOperatorNoLeader + expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1 + for: 5m + labels: + severity: critical + annotations: + summary: 'No leader for the ClickHouse operator (HA deployment)' +``` + +只有在启用 leader 选举时，最后一条规则才有意义。 + +
+ ## 验证设置 +
+ +下面进行一次快速的端到端检查，假设该 Helm 图表 安装在 `clickhouse-operator-system` 中： + +```bash +NS=clickhouse-operator-system + +# The metrics Service exists and selects the manager pod +kubectl -n $NS get svc -l control-plane=controller-manager + +# The ServiceMonitor exists (only with prometheus.enable=true) +kubectl -n $NS get servicemonitor -l control-plane=controller-manager + +# Manager pod is Ready (readiness probe answers) +kubectl -n $NS get pod -l control-plane=controller-manager + +# Direct scrape from inside the cluster (with the metrics-reader binding) +kubectl -n $NS run curl-metrics --rm -it --restart=Never \ + --image=curlimages/curl:8.10.1 -- sh -c ' + TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) + curl -sk -H "Authorization: Bearer $TOKEN" \ + https://-metrics-service.'$NS'.svc:8080/metrics \ + | head -20 + ' +``` + +如果抓取返回的是 Prometheus 指标暴露格式的指标，则说明端点和 RBAC 已正确配置。 + + + +* [安装](/zh/products/kubernetes-operator/install/helm) — 与监控相关的 Helm 配置值。 +* [配置](/zh/products/kubernetes-operator/guides/configuration) — 与指标服务器共享的 TLS 配置。 \ No newline at end of file diff --git a/zh/products/kubernetes-operator/guides/scaling.mdx b/zh/products/kubernetes-operator/guides/scaling.mdx new file mode 100644 index 000000000..ee95b633a --- /dev/null +++ b/zh/products/kubernetes-operator/guides/scaling.mdx @@ -0,0 +1,111 @@ +--- +position: 4 +slug: /clickhouse-operator/guides/scaling +title: 集群扩缩容 +keywords: ['kubernetes', '扩缩容', '副本', '分片', 'Keeper', 'quorum'] +description: '介绍如何扩缩容 ClickHouse 的副本和分片以及 Keeper 的 quorum 成员，以及 operator 会自动执行哪些操作。' +doc_type: 'guide' +--- + +你可以通过修改自定义资源中的副本数和分片数来扩缩容集群。operator 会将正在运行的集群逐步调整到新的拓扑：创建或删除按副本划分的 StatefulSets，保持 schema 同步，并通过状态条件反映进度。 + +本指南介绍如何扩缩容 `ClickHouseCluster` 的副本和分片，如何安全地扩缩容 `KeeperCluster` 的 quorum，以及在扩缩容操作进行过程中应关注哪些状态条件。 + + + `ClickHouseCluster` 始终需要一个 Keeper，并通过必填的 `spec.keeperClusterRef` 字段引用它——无论集群规模如何，operator 都会通过它来协调集群。若要让每个分片运行多个副本，数据还必须存储在 `ReplicatedMergeTree` 表中，因为只有复制机制才能让第二个副本提供相同的行。 + + +
+ ## 副本扩缩容 +
+ +`spec.replicas` 用于设置每个分片中的副本数量。每个副本都在各自的 StatefulSet 中运行，其名称为 `-clickhouse--`，因此一个配置为 `shards: 2` 和 `replicas: 3` 的集群会运行六个 StatefulSet。 + +直接就地增减副本数： + +```yaml +spec: + replicas: 3 # was 1 + keeperClusterRef: + name: my-keeper +``` + +扩容时，operator 会为每个新增副本创建对应的 StatefulSets，等待每个 pod (容器组) 就绪，然后将 schema 同步到这些新副本 (参见 [自动 schema 同步](#automatic-schema-sync)) 。缩容时，它会移除多余的 StatefulSets，并清理已删除副本遗留的过期 replicated-database 副本注册信息。 + +
+ ## 分片扩缩容 +
+ +`spec.shards` 用于设置分片数量。每新增一个分片，都会增加一整套按副本划分的 StatefulSets；此外，operator 还会[为每个分片创建一个 PodDisruptionBudget](/zh/products/kubernetes-operator/guides/configuration#pod-disruption-budgets)，以确保某个分片发生中断时，不会影响其他分片的计算。 + +```yaml +spec: + shards: 3 # was 1 + replicas: 2 +``` + +每个分片都保存着一部分互不重叠的数据，Operator 不会在分片之间复制或移动行。`Distributed` 表或显式路由方案决定一行数据会落到哪个分片上，因此新增一个分片时，新写入的数据就有了新的落点，而无需改动现有分片中已存储的行。 + +
+ ## 自动 schema 同步 +
+ +当 `spec.settings.enableDatabaseSync` 为 `true` (默认值) 时，operator 会在拓扑变化时保持 schema 同步： + +* **扩容时** — 一旦至少有两个副本就绪，operator 就会将 database 定义复制到新创建的副本，使新副本加入后与集群中其余副本拥有相同的 `Replicated` 和集成 database。 +* **缩容时** — 在某个副本消失之前，operator 会使用 `SYSTEM DROP DATABASE REPLICA` 从每个 `Replicated` database 中删除该副本的注册信息，这样缩容后的集群就不会再等待一个已不存在的 `Replicated` database 副本。 + +这涵盖 `Replicated` databases 和集成 database 引擎。它不会迁移表数据——行数据保存在 `ReplicatedMergeTree` 表中，并通过 Keeper 独立于此 schema 同步机制进行复制。当只有一个就绪副本时，没有可复制的目标，因此 operator 会跳过此步骤，并记录没有可用目标。 + +将 `enableDatabaseSync: false` 设为关闭此行为，例如当 schema 传播由外部工具负责时。此后，operator 会在 `SchemaInSync` 状态条件上报告 `SchemaSyncDisabled` 原因。 + +
+ ## 需关注的状态条件 +
+ +在执行扩缩容操作期间，查看自定义资源的进度情况： + +```bash +kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p' +``` + +| Condition | Reason | Meaning | +| -------------------- | ---------------------- | ------------------------------ | +| `ClusterSizeAligned` | `UpToDate` | 正在运行的副本数量与请求的拓扑一致 | +| `ClusterSizeAligned` | `ScalingUp` | Operator 正在添加副本 | +| `ClusterSizeAligned` | `ScalingDown` | Operator 正在移除副本 | +| `SchemaInSync` | `ReplicasInSync` | 所有副本上都已存在数据库，且过期元数据已清理 | +| `SchemaInSync` | `DatabasesNotCreated` | Operator 尚未在新副本上完成数据库创建 | +| `SchemaInSync` | `ReplicasNotCleanedUp` | 缩容后遗留的过期副本元数据尚未移除 | +| `SchemaInSync` | `SchemaSyncDisabled` | `enableDatabaseSync` 为 `false` | +| `Ready` | `AllShardsReady` | 每个分片都有一个就绪的副本 | +| `Ready` | `SomeShardsNotReady` | 至少有一个分片没有就绪的副本 | + +当 `ClusterSizeAligned` 报告 `UpToDate`、`SchemaInSync` 报告 `ReplicasInSync`，且 `Ready` 报告 `AllShardsReady` 时，一次扩缩容操作即完成。 + +
+ ## Keeper 的扩缩容 +
+ +`KeeperCluster` 运行的是 RAFT quorum，因此 operator 只有在集群处于稳定状态时，才会**一次只变更一个副本**的成员资格。 + +这样可以保护 quorum：`2F+1` 的集群可容忍 `F` 个成员宕机，因此 3 节点集群即使缺少 1 个成员仍可继续运行，5 节点集群即使缺少 2 个成员也是如此。 + +```yaml +spec: + replicas: 5 # was 3 +``` + +扩容时，Operator 会将当前可用的最小副本 ID 加入 quorum；缩容时，则会移除最大的 ID。每一步都会等待 quorum 稳定后，下一步才会开始。[Keeper PodDisruptionBudget](/zh/products/kubernetes-operator/guides/configuration#pod-disruption-budgets) 默认设置为 `maxUnavailable: replicas/2`，以在自愿性中断期间维持 quorum。 + +`ScaleAllowed` 状态条件会报告当前 quorum 是否可以变更成员： + +| Reason | Meaning | +| -------------------------- | --------------------------- | +| `ReadyToScale` | quorum 已稳定，Operator 可以添加或移除成员 | +| `ReplicaHasPendingChanges` | 某个副本仍有待处理的配置变更 | +| `ReplicaNotReady` | 某个副本尚未就绪，因此成员变更会等待 | +| `NoQuorum` | 集群当前没有 quorum，因此无法安全地变更成员 | +| `WaitingFollowers` | Operator 正在等待跟随者追上进度 | + +请按单步方式对 Keeper 进行扩缩容，并在每次变更之间等待 `ScaleAllowed` 恢复为 `ReadyToScale`。一次性跳过多个成员并不会绕过逐个执行 reconcile 的机制——Operator 仍会按每步一个成员的方式逐步调整 quorum。 \ No newline at end of file diff --git a/zh/products/kubernetes-operator/guides/tls.mdx b/zh/products/kubernetes-operator/guides/tls.mdx new file mode 100644 index 000000000..f9f20aabf --- /dev/null +++ b/zh/products/kubernetes-operator/guides/tls.mdx @@ -0,0 +1,329 @@ +--- +position: 5 +slug: /clickhouse-operator/guides/tls +title: 使用 TLS 保护集群 +keywords: ['kubernetes', 'tls', 'ssl', 'cert-manager', 'security', 'certificates'] +description: '介绍如何使用 cert-manager 通过 TLS 保护 ClickHouse 集群，包括客户端连接和 Keeper 加密。' +doc_type: 'guide' +--- + +本指南将逐步介绍如何对 ClickHouse 集群进行端到端加密：使用 [cert-manager](https://cert-manager.io/) 签发证书、在集群上启用 TLS、让客户端通过安全端口连接，以及将加密扩展到 Keeper 协调流量。 + +本指南以任务为导向。有关 `spec.settings.tls` 的按字段参考说明，请参阅 +[配置 → TLS/SSL 配置](/zh/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) +和 [API 参考文档](/zh/products/kubernetes-operator/reference/api-reference#clustertlsspec)。 + +
+ ## 前置条件 +
+ +* 由 Operator 管理的正在运行中的 ClickHouse 集群 (参见 [简介](/zh/products/kubernetes-operator/guides/introduction)) 。 +* 集群中已安装 [cert-manager](https://cert-manager.io/docs/installation/)。 +* 具有访问集群命名空间的 `kubectl` 权限。 + +Operator 本身不会生成证书——它使用的是你提供的 Kubernetes +`Secret`。推荐使用 cert-manager 生成并轮换该 `Secret`，但任何能够按预期格式写入 `Secret` 的工具都可以。 + +
+ ## operator 要求的证书格式 +
+ +通过将 `spec.settings.tls.serverCertSecret` 指向一个包含以下三个键的 Secret，即可启用 TLS： + +| Secret 键 | 内容 | +| --------- | -------------- | +| `tls.crt` | PEM 编码的服务器证书 | +| `tls.key` | PEM 编码的私钥 | +| `ca.crt` | PEM 编码的 CA 证书链 | + +这正是 cert-manager 为 `Certificate` 资源写入的布局，因此 +无需进行转换。operator 会将这些内容挂载到每个 pod (容器组) 的 +`/etc/clickhouse-server/tls/` 路径下，并将其配置到 ClickHouse 的 `openSSL` 中。 + + + 当 `tls.enabled: true` 时，`serverCertSecret` 是**必填**项。验证 + webhook 会拒绝启用了 TLS 却未设置该项的集群，也会在 + 未设置 `enabled: true` 的情况下拒绝 `required: true`。 + + +
+ ## 步骤 1 — 使用 cert-manager 引导 CA +
+ +最便于复现的配置方式是先创建一个自签名 CA，再由它为服务器 +证书签名。这样，你就能获得一个稳定的、客户端可验证的 `ca.crt`。 + +```yaml +# A self-signed issuer used only to mint the CA certificate +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-bootstrap + namespace: +spec: + selfSigned: {} +--- +# The CA certificate itself +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-ca + namespace: +spec: + isCA: true + commonName: clickhouse-ca + secretName: clickhouse-ca + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-bootstrap + kind: Issuer +--- +# A CA issuer that signs leaf certificates from the CA above +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: clickhouse-ca-issuer + namespace: +spec: + ca: + secretName: clickhouse-ca +``` + +在生产环境中，请将自签名的引导配置替换为实际的签发方 (企业 +CA、Vault、ACME 等) 。只有第 2 步需要变更——集群连接配置 +完全相同。 + +
+ ## 步骤 2 — 签发服务器证书 +
+ +从 CA 签发方申请一个叶子证书。`dnsNames` 必须覆盖 +客户端访问这些 pod (容器组) 时使用的地址。Operator 会创建一个名为 +`-clickhouse-headless` 的单个 **无头** Service，并且每个副本 pod (容器组) 都可通过 +`-clickhouse---0.-clickhouse-headless..svc.cluster.local` 进行访问。 +对该无头 Service 域名使用通配符即可覆盖所有副本： + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: clickhouse-server + namespace: +spec: + secretName: clickhouse-cert # <-- the Secret the operator will read + duration: 8760h # 1 year + renewBefore: 720h # rotate 30 days early + issuerRef: + name: clickhouse-ca-issuer + kind: Issuer + dnsNames: + - "*.-clickhouse-headless..svc" + - "*.-clickhouse-headless..svc.cluster.local" + - "localhost" +``` + + + Operator **不会**创建集群级 (负载均衡) 的 Service。如果你 + 想要一个可供连接的稳定单一端点，请自行创建一个选择该集群的 Pod (容器组) 的 `ClusterIP` Service， + 并将其 DNS name 添加到上面的 `dnsNames` 中。 + + +cert-manager 会创建名为 `clickhouse-cert` 的 Secret，其中包含 `tls.crt`、`tls.key` 和 +`ca.crt`，并会在证书到期前刷新它。请确认它已存在： + +```bash +kubectl -n get secret clickhouse-cert -o jsonpath='{.data}' | jq 'keys' +# ["ca.crt","tls.crt","tls.key"] +``` + +
+ ## 步骤 3 — 为集群启用 TLS +
+ +让集群引用该 Secret： + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: ClickHouseCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true # disable the insecure ports entirely + serverCertSecret: + name: clickhouse-cert +``` + +
+ ### Operator 的作用 +
+ +当 `tls.enabled: true` 时，operator 会： + +* **在每个 pod (容器组) 和无头 Service 上开放安全端口**：`9440` + (原生 TLS) 和 `8443` (HTTPS) 。这些端口会在现有端口之外一并添加。 +* **将 Secret 挂载到** `/etc/clickhouse-server/tls/`，并生成带有 + `verificationMode: relaxed`、 + `disableProtocols: sslv2,sslv3` 和 `preferServerCiphers: true` 的 ClickHouse `openSSL` 配置块。这些都是 + 默认值——如需覆盖，请参见[自定义 TLS 设置](#custom-tls-settings)。 + +如果你同时设置 `required: true`，operator 还会： + +* **移除不安全端口** `9000` (原生) 和 `8123` (HTTP) ——仅保留 TLS + 版本，因此明文客户端将无法再连接。 +* **将 pod (容器组) 的存活探针切换** 到安全的原生端口 `9440`，这样即使没有明文监听器， + 健康检查也能继续工作。 + + + TLS 端口 `8443` 和 `9440` 会被 webhook **无条件**预留， + 即使 TLS 已关闭也是如此，因此之后切换 `tls.enabled` 时，永远不会与 + `spec.additionalPorts` 条目发生冲突。参见 + [Configuration → `additionalPorts`](/zh/products/kubernetes-operator/guides/configuration#additional-ports)。 + + +
+ ## 第 4 步——通过 TLS 连接 +
+ +设置 `required: true` 后，客户端必须使用安全端口，并信任 CA。请通过无头 Service 访问特定的副本 pod (容器组) (如果你创建了自己的 `集群IP` +Service，也可以使用它) 。 + +**原生协议** (`clickhouse-client`，端口 `9440`) ： + +```bash +clickhouse-client --secure \ + --host -clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local \ + --port 9440 \ + --ca-certificate /path/to/ca.crt \ + --query "SELECT 1" +``` + +**HTTPS** (端口 `8443`) ： + +```bash +curl --cacert /path/to/ca.crt \ + "https://-clickhouse-0-0-0.-clickhouse-headless..svc.cluster.local:8443/?query=SELECT%201" +``` + +直接从 Secret 中获取 `ca.crt`，用于本地测试： + +```bash +kubectl -n get secret clickhouse-cert \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt +``` + +
+ ## 加密 Keeper 流量 +
+ +在 ClickHouse 集群上启用 TLS **不会** 加密与 Keeper 之间的连接。 +需要在 `KeeperCluster` 上单独启用——为 Keeper +service 签发证书 (步骤 1–2，使用 Keeper service 的 `dnsNames`) ，并引用该证书： + +```yaml +apiVersion: clickhouse.com/v1alpha1 +kind: KeeperCluster +metadata: + name: + namespace: +spec: + settings: + tls: + enabled: true + required: true + serverCertSecret: + name: keeper-cert +``` + +Keeper 在 `2281` 上开放其安全客户端端口。一旦 Keeper 启用 TLS，**ClickHouse 集群 +会自动通过 TLS 连接到它**——无需在 +ClickHouseCluster 端进行额外设置。启用 TLS 时，ClickHouse 会使用自身的 +`ca.crt` CA 证书包来验证 Keeper 证书；否则使用系统默认的 CA 证书包。 + +
+ ## 自定义 CA 证书包 +
+ +如果 ClickHouse 需要信任与其服务器证书所使用的 CA 不同的 CA (例如，由单独 CA 签发的 Keeper) ，请提供 `caBundle`： + +```yaml +spec: + settings: + tls: + enabled: true + serverCertSecret: + name: clickhouse-cert + caBundle: + name: + key: ca.crt +``` + +该 operator 会挂载此捆绑包，并将客户端侧的 `openSSL` 验证指向 +它，而不是证书本身的 `ca.crt`。 + +
+ ## 自定义 TLS 设置 +
+ +operator 生成的 `openSSL` 块只是默认配置，并非上限。它会被写入主 server configuration；`spec.settings.extraConfig` 下的任何内容都会渲染到 +`config.d/99-extra-config.yaml`，而 ClickHouse 会在**最后**进行 merge——因此会覆盖 +生成的值。 + +如果要进一步加固这些默认设置——例如，要求严格的对等端验证，并将 +最低 protocol 提高到 TLS 1.2——请设置你想修改的 `openSSL.server` 配置项： + +```yaml +spec: + settings: + extraConfig: + openSSL: + server: + verificationMode: strict + disableProtocols: "sslv2,sslv3,tlsv1,tlsv1_1" +``` + +合并是按键逐项进行的：只会替换你设置的值，而你 +省略的自动生成键 (证书路径、CA 配置) 会予以保留。可用选项请参阅 +[`openSSL` 服务器设置](/zh/reference/settings/server-settings/settings#openssl) +，`extraConfig` 的合并方式请参阅 +[Configuration → 嵌入式额外配置](/zh/products/kubernetes-operator/guides/configuration#embedded-extra-configuration)。 + +
+ ## 验证与排查故障 +
+ +**确认无头 Service 上的安全端口已正常开放：** + +```bash +kubectl -n get svc -clickhouse-headless \ + -o jsonpath='{.spec.ports[*].name}' +# expect: ... tcp-secure http-secure (and NO tcp/http when required: true) +``` + +**确认该证书已挂载到 pod (容器组) 中：** + +```bash +kubectl -n exec -- ls /etc/clickhouse-server/tls/ +# ca-bundle.crt clickhouse-server.crt clickhouse-server.key +``` + +| 症状 | 可能原因 | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 启用 TLS 后 Pod (容器组) 无法启动 / 卷挂载报错 | 引用的 Secret 不存在，或缺少 `tls.crt`/`tls.key`/`ca.crt`。Operator 不会校验 Secret 的内容——缺失这些键时，表现为 pod (容器组) 卷挂载失败，而不是专门的 status 条件。请使用 `kubectl describe pod` 检查该 pod (容器组) 。 | +| Webhook 拒绝该集群 | 设置了 `required: true` 但未设置 `enabled: true`，或设置了 `enabled: true` 但未设置 `serverCertSecret`。 | +| Client `certificate verify failed` | Client 不信任该 CA。传入 Secret 中的 `ca.crt`，或检查证书中的 `dnsNames` 是否覆盖了你连接使用的 host。 | +| 明文 client 突然无法连接 | `required: true` 关闭了端口 `9000`/`8123`。请将 client 切换到 `9440`/`8443`，或设置 `required: false`，以在迁移期间保持不安全端口开放。 | + +
+ ## 另请参阅 +
+ +* [配置 → TLS/SSL 配置](/zh/products/kubernetes-operator/guides/configuration#tls-ssl-configuration) — 字段参考 +* [配置 → `additionalPorts`](/zh/products/kubernetes-operator/guides/configuration#additional-ports) — 保留端口 +* [API 参考文档 → ClusterTLSSpec](/zh/products/kubernetes-operator/reference/api-reference#clustertlsspec) +* [`openSSL` 服务器设置](/zh/reference/settings/server-settings/settings#openssl) — 可通过 `extraConfig` 覆盖的 TLS 选项 \ No newline at end of file diff --git a/zh/products/kubernetes-operator/install/helm.mdx b/zh/products/kubernetes-operator/install/helm.mdx index 139602ade..941c53aef 100644 --- a/zh/products/kubernetes-operator/install/helm.mdx +++ b/zh/products/kubernetes-operator/install/helm.mdx @@ -63,7 +63,7 @@ helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-man helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \ --create-namespace \ -n clickhouse-operator-system \ - --set-json="manager.container.tag= + --set manager.image.tag= ```
diff --git a/zh/products/kubernetes-operator/install/kubectl.mdx b/zh/products/kubernetes-operator/install/kubectl.mdx index a5a94758e..88ba98cfa 100644 --- a/zh/products/kubernetes-operator/install/kubectl.mdx +++ b/zh/products/kubernetes-operator/install/kubectl.mdx @@ -105,7 +105,7 @@ keeperclusters.clickhouse.com 2025-01-06T00:00:00Z ```bash make build-installer VERSION= [IMG=] - kubectl apply -k dist/install.yaml + kubectl apply -f dist/install.yaml ``` \ No newline at end of file diff --git a/zh/products/kubernetes-operator/navigation.json b/zh/products/kubernetes-operator/navigation.json index 9102a137f..c7d382b6b 100644 --- a/zh/products/kubernetes-operator/navigation.json +++ b/zh/products/kubernetes-operator/navigation.json @@ -17,7 +17,10 @@ "group": "Guides", "pages": [ "zh/products/kubernetes-operator/guides/introduction", - "zh/products/kubernetes-operator/guides/configuration" + "zh/products/kubernetes-operator/guides/configuration", + "zh/products/kubernetes-operator/guides/monitoring", + "zh/products/kubernetes-operator/guides/scaling", + "zh/products/kubernetes-operator/guides/tls" ] }, { diff --git a/zh/products/kubernetes-operator/overview.mdx b/zh/products/kubernetes-operator/overview.mdx index 9460142bb..76f82d51d 100644 --- a/zh/products/kubernetes-operator/overview.mdx +++ b/zh/products/kubernetes-operator/overview.mdx @@ -40,7 +40,9 @@ ClickHouse Operator 是一个 Kubernetes Operator，可在 Kubernetes 上自动 * **[简介](/zh/products/kubernetes-operator/guides/introduction)** - ClickHouse Operator 概念概览 * **[配置指南](/zh/products/kubernetes-operator/guides/configuration)** - 配置 ClickHouse 和 Keeper 集群 -* **[监控](/zh/products/kubernetes-operator/guides/introduction)** - 使用 Prometheus 指标监控 clickhouse-operator +* **[监控](/zh/products/kubernetes-operator/guides/monitoring)** - operator 的 Prometheus 指标和健康探针 +* **[扩缩容](/zh/products/kubernetes-operator/guides/scaling)** - 扩缩容副本、分片和 Keeper 仲裁数 +* **[使用 TLS 保护](/zh/products/kubernetes-operator/guides/tls)** - 使用 cert-manager 对集群进行端到端加密
## 参考 diff --git a/zh/products/kubernetes-operator/reference/api-reference.mdx b/zh/products/kubernetes-operator/reference/api-reference.mdx index be99cbdc2..024a777fa 100644 --- a/zh/products/kubernetes-operator/reference/api-reference.mdx +++ b/zh/products/kubernetes-operator/reference/api-reference.mdx @@ -10,6 +10,21 @@ sidebarTitle: 'API 参考文档' 本文档提供 ClickHouse Operator 自定义资源的详细 API 参考。 +
+ ## AdditionalPort +
+ +AdditionalPort 声明了一个额外的 TCP 端口，用于在 ClickHouse pod (容器组) 和由 operator 管理的无头 Service 上暴露。 + +| 字段 | 类型 | 描述 | 必填 | 默认值 | +| ------ | ------- | ----------------------------------------------------------------------- | ---- | --- | +| `name` | string | `name` 在列表中唯一标识该端口，同时用作容器端口名称和 Service 端口名称。
它必须是一个 DNS_LABEL。 | true | | +| `port` | integer | `port` 是要暴露的 TCP 端口号。 | true | | + +出现于： + +* [ClickHouseClusterSpec](#clickhouseclusterspec) +
## ClickHouseCluster
@@ -59,22 +74,23 @@ kind: ClickHouseClusterList ClickHouseClusterSpec 定义了 ClickHouseCluster 的期望状态。 -| 字段 | 类型 | 描述 | 必填 | 默认值 | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | -| `replicas` | integer | 单个分片中的副本数量。 | false | 3 | -| `shards` | integer | 集群中的分片数量。 | false | 1 | -| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | 对用于 ClickHouse 协调的 KeeperCluster 的引用。
省略命名空间时，将使用 ClickHouseCluster 所在的命名空间。 | true | | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | 传递给 ClickHouse pod (容器组) 规范的参数。 | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | 传递给 ClickHouse 容器规范的参数。 | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse 数据持久化存储的规格。 | false | | -| `labels` | object (keys:string, values:string) | 添加到资源上的附加标记。 | false | | -| `annotations` | object (keys:string, values:string) | 添加到资源上的附加注解。 | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget 用于配置为每个分片创建的 PDB。
未设置时，Operator 对单副本
分片默认使用 maxUnavailable=1，对多副本分片默认使用 minAvailable=1。 | false | | -| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse server 的配置参数。 | false | | -| `clusterDomain` | string | ClusterDomain 是 Kubernetes 集群中用于 DNS 解析的集群域名后缀。 | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel 指定用于主版本升级检查的发布渠道。
为空时，仅会建议次版本更新。允许的值包括：stable、lts 或特定的 major.minor 版本 (例如 25.8) 。 | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 用于版本检测 Job 的 VersionProbeTemplate 覆盖配置。 | false | | -| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret 是一个可选引用，指向外部管理的、包含集群敏感信息的 Secret。
该 Secret 必须与集群位于同一命名空间中。 | false | | +| 字段 | 类型 | 描述 | 必填 | 默认值 | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------------- | +| `replicas` | integer | 单个分片中的副本数量。 | false | 3 | +| `shards` | integer | 集群中的分片数量。 | false | 1 | +| `keeperClusterRef` | [KeeperClusterReference](#keeperclusterreference) | 对用于 ClickHouse 协调的 KeeperCluster 的引用。
省略命名空间时，将使用 ClickHouseCluster 所在的命名空间。 | true | | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | 传递给 ClickHouse pod (容器组) 规范的参数。 | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | 传递给 ClickHouse 容器规范的参数。 | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse 数据持久化存储的规格。 | false | | +| `labels` | object (keys:string, values:string) | 添加到资源上的附加标记。 | false | | +| `annotations` | object (keys:string, values:string) | 添加到资源上的附加注解。 | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget 用于配置为每个分片创建的 PDB。
未设置时，Operator 对单副本
分片默认使用 maxUnavailable=1，对多副本分片默认使用 minAvailable=1。 | false | | +| `settings` | [ClickHouseSettings](#clickhousesettings) | ClickHouse 服务器 的配置参数。 | false | | +| `clusterDomain` | string | ClusterDomain 是 Kubernetes 集群中用于 DNS 解析的集群域名后缀。 | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel 指定用于主版本升级检查的发布渠道。
为空时，仅会建议次版本更新。允许的值包括：stable、lts 或特定的 major.minor 版本 (例如 25.8) 。 | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | 用于版本检测 Job 的 VersionProbeTemplate 覆盖配置。 | false | | +| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret 是一个可选引用，指向外部管理的、包含集群敏感信息的 Secret。
该 Secret 必须与集群位于同一命名空间中。 | false | | +| `additionalPorts` | [AdditionalPort](#additionalport) array | AdditionalPorts 声明了要在 ClickHouse Pod（容器组） 和由 Operator 管理的无头 Service 上暴露的额外 TCP 端口。
Operator 仅会将这些端口添加到 Kubernetes 资源中，不会配置 ClickHouse 服务器 在这些端口上监听。 | false | | 出现于： @@ -180,7 +196,7 @@ ContainerTemplateSpec 描述了集群中各容器的容器配置覆盖项。 | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | | `image` | [ContainerImage](#containerimage) | Image 是要部署的容器镜像。 | true | | | `imagePullPolicy` | [PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#pullpolicy-v1-core) | 镜像的 ImagePullPolicy，默认为 IfNotPresent。 | false | | -| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources 是 server 容器的资源需求。
通过 SMP 与 operator 默认值进行深度合并。各个 limits 和 requests 仅覆盖匹配的
键；未设置的字段会保留 operator 默认值。 | false | | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) | Resources 是 server 容器的资源需求。
作为整体应用：仅当所有资源字段都为空时，才会使用 operator 默认值。 | false | | | `volumeMounts` | [VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volumemount-v1-core) array | VolumeMounts 是容器的卷挂载列表。
会与 operator 生成的挂载项拼接。与 operator 挂载共享 `mountPath` 的条目
会合并到同一个 projected volume 中。 | false | | | `env` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array | Env 是要在容器中设置的环境变量列表。
按名称与 operator 默认值合并。 | false | | | `securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core) | SecurityContext 定义了容器运行时应使用的安全选项。
非 nil 的 SecurityContext 会完全替换 operator 默认值；整个
结构体都由用户负责。为 nil 时，会保留 operator 默认值。
更多信息：https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false | | @@ -302,19 +318,19 @@ KeeperClusterReference 用于标识 ClickHouseCluster 所使用的 KeeperCluster KeeperClusterSpec 定义了 KeeperCluster 的期望状态。 -| Field | Type | Description | Required | Default | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | ------------- | -| `replicas` | integer | 集群中的副本数 | false | 3 | -| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | 传递给 Keeper pod (容器组) 规范的参数。 | false | | -| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | 传递给 Keeper 容器规范的参数。 | false | | -| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper 数据持久化存储的规格。 | false | | -| `labels` | object (keys:string, values:string) | 添加到资源的附加标记。 | false | | -| `annotations` | object (keys:string, values:string) | 添加到资源的附加注解。 | false | | -| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget 用于配置为 Keeper 集群创建的 PDB。
未设置时，operator 默认使用 maxUnavailable=replicas/2
(为 2F+1 集群保留 quorum)。 | false | | -| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper server 的配置参数。 | false | | -| `clusterDomain` | string | ClusterDomain 是 Kubernetes 集群用于 DNS 解析的域名后缀。 | false | cluster.local | -| `upgradeChannel` | string | UpgradeChannel 指定用于主版本升级检查的发布渠道。
为空时，只会建议次版本更新。允许的值包括：stable、lts 或特定的 major.minor 版本 (例如 25.8) 。 | false | | -| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | VersionProbeTemplate 用于覆盖版本检测 Job 的配置。 | false | | +| Field | Type | Description | Required | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | +| `replicas` | integer | 集群中的副本数 | false | 3 | +| `podTemplate` | [PodTemplateSpec](#podtemplatespec) | 传递给 Keeper pod (容器组) 规范的参数。 | false | | +| `containerTemplate` | [ContainerTemplateSpec](#containertemplatespec) | 传递给 Keeper 容器规范的参数。 | false | | +| `dataVolumeClaimSpec` | [PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#persistentvolumeclaimspec-v1-core) | ClickHouse Keeper 数据持久化存储的规格。 | false | | +| `labels` | object (keys:string, values:string) | 添加到资源的附加标记。 | false | | +| `annotations` | object (keys:string, values:string) | 添加到资源的附加注解。 | false | | +| `podDisruptionBudget` | [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) | PodDisruptionBudget 用于配置为 Keeper 集群创建的 PDB。
未设置时，operator 默认使用 maxUnavailable=replicas/2
(为 2F+1 集群保留 quorum)；单副本集群使用 maxUnavailable=1。 | false | | +| `settings` | [KeeperSettings](#keepersettings) | ClickHouse Keeper server 的配置参数。 | false | | +| `clusterDomain` | string | ClusterDomain 是 Kubernetes 集群用于 DNS 解析的域名后缀。 | false | cluster.local | +| `upgradeChannel` | string | UpgradeChannel 指定用于主版本升级检查的发布渠道。
为空时，只会建议次版本更新。允许的值包括：stable、lts 或特定的 major.minor 版本 (例如 25.8) 。 | false | | +| `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | VersionProbeTemplate 用于覆盖版本检测 Job 的配置。 | false | | 出现在： diff --git a/zh/resources/changelogs/cloud/release-status.mdx b/zh/resources/changelogs/cloud/release-status.mdx index be59322eb..a6eaedf59 100644 --- a/zh/resources/changelogs/cloud/release-status.mdx +++ b/zh/resources/changelogs/cloud/release-status.mdx @@ -43,7 +43,7 @@ ClickHouse Cloud 提供不同的发布渠道，以满足不同用户对稳定性 下方显示的日期表示 ClickHouse **开始在各发布渠道中滚动发布**的时间，并非您的具体服务实际升级的时间。 * 滚动发布为自动执行，并会在数周内逐步完成 - * 已配置计划升级窗口的服务，会在该发布渠道滚动发布结束后的下一周，按其计划窗口进行升级 (从周一 00:00 UTC 开始) + * 已配置计划升级时间窗口的服务，会在该发布渠道滚动发布结束后的下一周，按其计划窗口进行升级 (从周一 00:00 UTC 开始) * 由于滚动发布暂停 (例如节假日冻结) 或健康监测，滚动发布完成时间可能会延后 如果希望在生产环境升级前提前测试，请将 Fast 或 Regular 渠道用于非生产服务，将 Slow 渠道用于生产服务。 @@ -51,60 +51,73 @@ ClickHouse Cloud 提供不同的发布渠道，以满足不同用户对稳定性 \ No newline at end of file