Clickhouse

Prerequisites¶

A Kubernetes cluster with the operator installed using helm, kubectl or kind (for local development).
A Kubernetes Secret with an Aiven authentication token.

Required permissions¶

To create and manage this resource, you must have the appropriate roles or permissions. See the Aiven documentation for details on managing permissions.

This resource uses the following API operations, and for each operation, any of the listed permissions is sufficient:

Operation	Permissions
ProjectKmsGetCA	`organization:projects:write`
ProjectServiceTagsReplace	`service:configuration:write`
ServiceBackupsGet	`service:configuration:write`
ServiceCreate	`project:services:write` or `role:services:recover`
ServiceDelete	`project:services:write`
ServiceGet	`service:secrets:read`
ServiceUpdate	`project:services:write` or `role:services:maintenance`, or `role:services:recover`, or `service:configuration:write`

Usage example¶

apiVersion: aiven.io/v1alpha1
kind: Clickhouse
metadata:
  name: my-clickhouse
spec:
  authSecretRef:
    name: aiven-token
    key: token

  connInfoSecretTarget:
    name: my-clickhouse
    annotations:
      foo: bar
    labels:
      baz: egg

  tags:
    env: test
    instance: foo

  userConfig:
    ip_filter:
      - network: 0.0.0.0/32
        description: bar
      - network: 10.20.0.0/16

  project: my-aiven-project
  cloudName: google-europe-west1
  plan: startup-16

  maintenanceWindowDow: friday
  maintenanceWindowTime: 23:00:00

Apply the resource with:

kubectl apply -f example.yaml

Verify the newly created Clickhouse:

kubectl get clickhouses my-clickhouse

The output is similar to the following:

Name             Project             Region                 Plan          State      
my-clickhouse    my-aiven-project    google-europe-west1    startup-16    RUNNING

To view the details of the Secret, use the following command:

kubectl describe secret my-clickhouse

You can use the jq to quickly decode the Secret:

kubectl get secret my-clickhouse -o json | jq '.data | map_values(@base64d)'

The output is similar to the following:

{
    "CLICKHOUSE_HOST": "<secret>",
    "CLICKHOUSE_PORT": "<secret>",
    "CLICKHOUSE_USER": "<secret>",
    "CLICKHOUSE_PASSWORD": "<secret>",
}

Clickhouse¶

Clickhouse is the Schema for the clickhouses API.

Exposes secret keys

CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD.

Required

apiVersion (string). Value aiven.io/v1alpha1.
kind (string). Value Clickhouse.
metadata (object). Data that identifies the object, including a name string and optional namespace.
spec (object). ClickhouseSpec defines the desired state of Clickhouse. See below for nested schema.

spec¶

Appears on Clickhouse.

ClickhouseSpec defines the desired state of Clickhouse.

Required

plan (string, MaxLength: 128). Subscription plan.
project (string, Immutable, Pattern: ^[a-zA-Z0-9_-]+$, MaxLength: 63). Identifies the project this resource belongs to.

Optional

authSecretRef (object). Authentication reference to Aiven token in a secret. See below for nested schema.
cloudName (string, MaxLength: 256). Cloud the service runs in.
connInfoSecretTarget (object). Secret configuration. See below for nested schema.
connInfoSecretTargetDisabled (boolean, Immutable). When true, the secret containing connection information will not be created, defaults to false. This field cannot be changed after resource creation.
disk_space (string, Pattern: (?i)^[1-9][0-9]*(GiB|G)?$). The disk space of the service, possible values depend on the service type, the cloud provider and the project. Reducing will result in the service re-balancing. The removal of this field does not change the value.
maintenanceWindowDow (string, Enum: monday, tuesday, wednesday, thursday, friday, saturday, sunday). Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
maintenanceWindowTime (string, MaxLength: 8). Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.
powered (boolean, Default value: true). Determines the power state of the service. When true (default), the service is running. When false, the service is powered off. For more information please see Aiven documentation. Note that:
- When set to false the annotation controllers.aiven.io/instance-is-running is also set to false.
- Services cannot be created in a powered off state. The value is ignored during creation.
- It is highly recommended to not run dependent resources when the service is powered off. Creating a new resource or updating an existing resource that depends on a powered off service will result in an error. Existing resources will need to be manually recreated after the service is powered on.
- Existing secrets will not be updated or removed when the service is powered off.
- For Kafka services with backups: Topic configuration, schemas and connectors are all backed up, but not the data in topics. All topic data is lost on power off.
- For Kafka services without backups: Topic configurations including all topic data is lost on power off.
projectVPCRef (object). ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically. See below for nested schema.
projectVpcId (string, MaxLength: 36). Identifier of the VPC the service should be in, if any.
serviceIntegrations (array of objects, Immutable, MaxItems: 1). Service integrations to specify when creating a service. Not applied after initial service creation. See below for nested schema.
tags (object, AdditionalProperties: string). Tags are key-value pairs that allow you to categorize services.
technicalEmails (array of objects, MaxItems: 10). Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability. See below for nested schema.
terminationProtection (boolean). Prevent service from being deleted. It is recommended to have this enabled for all services.
userConfig (object). OpenSearch specific user configuration options. See below for nested schema.

authSecretRef¶

Appears on spec.

Authentication reference to Aiven token in a secret.

Required

key (string, MinLength: 1).
name (string, MinLength: 1).

connInfoSecretTarget¶

Appears on spec.

Secret configuration.

Required

name (string, Immutable). Name of the secret resource to be created. By default, it is equal to the resource name.

Optional

annotations (object, AdditionalProperties: string). Annotations added to the secret.
labels (object, AdditionalProperties: string). Labels added to the secret.
prefix (string). Prefix for the secret's keys. Added "as is" without any transformations. By default, is equal to the kind name in uppercase + underscore, e.g. KAFKA_, REDIS_, etc.

projectVPCRef¶

Appears on spec.

ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically.

Required

name (string, MinLength: 1).

Optional

namespace (string, MinLength: 1).

serviceIntegrations¶

Appears on spec.

Service integrations to specify when creating a service. Not applied after initial service creation.

Required

integrationType (string, Enum: read_replica).
sourceServiceName (string, MinLength: 1, MaxLength: 64).

technicalEmails¶

Appears on spec.

Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability.

Required

email (string). Email address.

userConfig¶

Appears on spec.

OpenSearch specific user configuration options.

Optional

additional_backup_regions (array of strings, MaxItems: 1). Deprecated. Additional Cloud Regions for Backup Replication.
backup_hour (integer, Minimum: 0, Maximum: 23). The hour of day (in UTC) when backup for the service is started. New backup is only started if previous backup has already completed.
backup_minute (integer, Minimum: 0, Maximum: 59). The minute of an hour when backup for the service is started. New backup is only started if previous backup has already completed.
enable_ipv6 (boolean). Register AAAA DNS records for the service, and allow IPv6 packets to service ports.
ip_filter (array of objects, MaxItems: 8000). Allow incoming connections from CIDR address block, e.g. 10.20.0.0/16. See below for nested schema.
private_access (object). Allow access to selected service ports from private networks. See below for nested schema.
privatelink_access (object). Allow access to selected service components through Privatelink. See below for nested schema.
project_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 63). Name of another project to fork a service from. This has effect only when a new service is being created.
public_access (object). Allow access to selected service ports from the public Internet. See below for nested schema.
recovery_basebackup_name (string, Pattern: ^[a-zA-Z0-9-_:.+]+$, MaxLength: 128). Name of the basebackup to restore in forked service.
service_log (boolean). Store logs for the service so that they are available in the HTTP API and console.
service_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 64). Name of another service to fork from. This has effect only when a new service is being created.
static_ips (boolean). Use static public IP addresses.

ip_filter¶

Appears on spec.userConfig.

CIDR address block, either as a string, or in a dict with an optional description field.

Required

network (string, MaxLength: 43). CIDR address block.

Optional

description (string, MaxLength: 1024). Description for IP filter list entry.

private_access¶

Appears on spec.userConfig.

Allow access to selected service ports from private networks.

Optional

clickhouse (boolean). Allow clients to connect to clickhouse with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.
clickhouse_https (boolean). Allow clients to connect to clickhouse_https with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.
clickhouse_mysql (boolean). Allow clients to connect to clickhouse_mysql with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.
prometheus (boolean). Allow clients to connect to prometheus with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.

privatelink_access¶

Appears on spec.userConfig.

Allow access to selected service components through Privatelink.

Optional

clickhouse (boolean). Enable clickhouse.
clickhouse_https (boolean). Enable clickhouse_https.
clickhouse_mysql (boolean). Enable clickhouse_mysql.
prometheus (boolean). Enable prometheus.

public_access¶

Appears on spec.userConfig.

Allow access to selected service ports from the public Internet.

Optional

clickhouse (boolean). Allow clients to connect to clickhouse from the public internet for service nodes that are in a project VPC or another type of private network.
clickhouse_https (boolean). Allow clients to connect to clickhouse_https from the public internet for service nodes that are in a project VPC or another type of private network.
clickhouse_mysql (boolean). Allow clients to connect to clickhouse_mysql from the public internet for service nodes that are in a project VPC or another type of private network.
prometheus (boolean). Allow clients to connect to prometheus from the public internet for service nodes that are in a project VPC or another type of private network.