[DPE-3737] Add a zookeeper_client interface

docs/json_schemas/zookeeper/v0/provider.json

@@ -0,0 +1,82 @@
+{
+  "$defs": {
+    "BaseModel": {
+      "properties": {},
+      "title": "BaseModel",
+      "type": "object"
+    },
+    "ZooKeeperProviderAppData": {
+      "properties": {
+        "database": {
+          "description": "The parent chroot zNode granted to the requirer",
+          "examples": [
+            "/myappB"
+          ],
+          "title": "zNode",
+          "type": "string"
+        },
+        "endpoints": {
+          "description": "A comma-seperated list of ZooKeeper server and ports",
+          "examples": [
+            "10.141.78.133:2181,10.141.78.50:2181,10.141.78.45:2181"
+          ],
+          "title": "ZooKeeper endpoints",
+          "type": "string"
+        },
+        "secret-user": {
+          "description": "",
+          "examples": [
+            "secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub6vubg2s77p3nio0"
+          ],
+          "title": "Credentials Secret Name",
+          "type": "string"
+        },
+        "secret-tls": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The name of the TLS secret to use. Leaving this empty will configure a client with TLS disabled.",
+          "examples": [
+            "secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub7fubg2s77p3niog"
+          ],
+          "title": "TLS Secret Name"
+        }
+      },
+      "required": [
+        "database",
+        "endpoints",
+        "secret-user"
+      ],
+      "title": "ZooKeeperProviderAppData",
+      "type": "object"
+    }
+  },
+  "description": "The schema for the provider side of this interface.",
+  "properties": {
+    "unit": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BaseModel"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "app": {
+      "$ref": "#/$defs/ZooKeeperProviderAppData"
+    }
+  },
+  "required": [
+    "app"
+  ],
+  "title": "ProviderSchema",
+  "type": "object"
+}

docs/json_schemas/zookeeper/v0/requirer.json

@@ -0,0 +1,97 @@
+{
+  "$defs": {
+    "BaseModel": {
+      "properties": {},
+      "title": "BaseModel",
+      "type": "object"
+    },
+    "ZooKeeperRequirerAppData": {
+      "properties": {
+        "database": {
+          "description": "The parent chroot zNode requested by the requirer",
+          "examples": [
+            "/myappA"
+          ],
+          "title": "zNode",
+          "type": "string"
+        },
+        "extra-user-roles": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "ACL string representation for the parent chroot",
+          "examples": [
+            "cdrwa"
+          ],
+          "title": "User roles"
+        },
+        "requested-secrets": {
+          "description": "Any provider field which should be transfered as Juju Secret",
+          "examples": [
+            [
+              "username",
+              "password",
+              "tls-ca",
+              "uris"
+            ]
+          ],
+          "items": {
+            "type": "string"
+          },
+          "title": "Requested secrets",
+          "type": "array"
+        },
+        "secret-mtls": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The name of the mTLS secret to use. Leaving this empty will configure the provider to not use mTLS.",
+          "examples": [
+            "secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub7fubg2s77p3niog"
+          ],
+          "title": "mTLS Secret Name"
+        }
+      },
+      "required": [
+        "database",
+        "requested-secrets",
+        "secret-mtls"
+      ],
+      "title": "ZooKeeperRequirerAppData",
+      "type": "object"
+    }
+  },
+  "description": "The schema for the requirer side of this interface.",
+  "properties": {
+    "unit": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BaseModel"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "app": {
+      "$ref": "#/$defs/ZooKeeperRequirerAppData"
+    }
+  },
+  "required": [
+    "app"
+  ],
+  "title": "RequirerSchema",
+  "type": "object"
+}

interfaces/zookeeper/v0/README.md

@@ -0,0 +1,59 @@
+# `zookeeper`
+
+## Usage
+
+This relation interface describes the expected behavior of any charm claiming to be able to interface with a Zookeeper cluster.
+
+## Direction
+
+```mermaid
+flowchart TD
+    Requirer -- database, \nrequested-secrets --> Provider
+    Provider -- database, \nendpoints, \nsecret-user --> Requirer
+```
+
+## Behavior
+
+Both the Requirer and the Provider need to adhere to criteria to be considered compatible with the interface.
+
+### Provider
+
+- Is expected to create an application user inside the database cluster when the requirer provides the `database` field.
+- Is expected to provide credentials (`username` and `password`) in a Juju Secret whenever the Requirer supplies the `database` field.
+- Is expected to expose the Juju Secrets URI to the credentials through the `secret-user` field of the data bag.
+- Is expected to provide the `endpoints` field with a comma-separated list of server uris and zNode.
+- Is expected to provide the `database` field with the zNode that was actually created.
+- Is expected to provide the `version` field whenever database charm wants to communicate its database version.
+- Is expected to provide the CA chain in the `tls-ca` field of a Juju Secret, whenever the provider has TLS enabled (such as using the [TLS Certificates Operator](https://github.com/canonical/tls-certificates-operator)).
+- Is expected to share the TLS Juju Secret URI through the `secret-tls` field of the databag.
+- If the Requirer asks for additional secrets (via `requested-secrets`, see below) other than those stored in the `user` and `tls` secrets, Provider is expected to define a `secret-extra` field holding the URI of the Juju Secret containing all additional secret fields.
+- If the Requirer both requested the `tls-ca` and provided `secret-mtls`, the Provider should use enable mTLS.
+
+### Requirer
+
+- Is expected to provide `requested-secrets`, which is a list of field names that are not to be exposed on the relation databag, but handled within Juju Secrets. It should be JSON parsable array of strings, and correspond to valid Juju Secret keys (i.e. alphanumerical characters with a potential '-' (dash) character). Secret fields must contain `username` and `password` (and `tls-ca` in case TLS is enabled).
+- Is expected to provide a zNode in the `database` field.
+- Is expected to have unique credentials for each relation. Therefore, different instances of the same Charm (juju applications) will have different relations with different credentials.
+- Is expected to have different relations names on Requirer with the same interface name if Requirer needs access to multiple database charms.
+- Is expected to allow multiple different Juju applications to access the same zNode.
+- Is expected to tolerate that the Provider may ignore the `database` field in some cases and instead use the zNode received.
+- Can optionally provide the `extra-user-roles` field specifying a ACL string for the client application.
+- Can optionally provide the mTLS Juju Secret Uri through the `secret-mtls` field of the databag
+
+## Relation Data
+
+[\[Pydantic Schema\]](./schema.py)
+
+
+```yaml
+provider:
+  app: 
+    database: /myappB
+    endpoints: 10.141.78.133:2181,10.141.78.50:2181,10.141.78.45:2181
+    secret-user: secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub6vubg2s77p3nio0
+    secret-tls: secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub7fubg2s77p3niog
+requirer:
+  app: 
+    database: myappA
+    requested-secrets: ["username", "password", "tls-ca", "uris"]
+```

interfaces/zookeeper/v0/interface.yaml

@@ -0,0 +1,17 @@
+name: zookeeper
+version: 0
+status: draft
+
+providers:
+  - name: zookeeper
+    url: https://github.com/canonical/zookeeper-operator
+  - name: zookeeper-k8s
+    url: https://github.com/canonical/zookeeper-k8s-operator
+
+requirers:
+  - name: kafka
+    url: https://github.com/canonical/kafka-operator
+  - name: kafka-k8s
+    url: https://github.com/canonical/kafka-k8s-operator
+  - name: kyuubi-k8s-operator
+    url: https://github.com/canonical/kyuubi-k8s-operator

interfaces/zookeeper/v0/schema.py

@@ -0,0 +1,101 @@
+"""This file defines the schemas for the provider and requirer sides of the zookeeper_client interface.
+
+It must expose two interfaces.schema_base.DataBagSchema subclasses called:
+- ProviderSchema
+- RequirerSchema
+"""
+
+from typing import Annotated, TypeAlias
+
+from interface_tester.schema_base import DataBagSchema
+from pydantic import (
+    BaseModel,
+    Field,
+    IPvAnyAddress,
+    conint,
+)
+
+
+class Endpoint(BaseModel):
+    ip: IPvAnyAddress
+    port: conint(ge=0, le=65535) | None
+
+    def __init__(self, value: str) -> None:
+        ip, _, port = value.partition(":")
+        if not port:
+            port = None
+        super().__init__(ip=ip, port=port)
+
+
+Endpoints: TypeAlias = str
+
+
+class ZooKeeperProviderAppData(BaseModel):
+    database: str = Field(
+        description="The parent chroot zNode granted to the requirer",
+        examples=["/myappB"],
+        title="zNode",
+    )
+
+    endpoints: Endpoints = Field(
+        description="A comma-seperated list of ZooKeeper server and ports",
+        examples=["10.141.78.133:2181,10.141.78.50:2181,10.141.78.45:2181"],
+        title="ZooKeeper endpoints",
+    )
+
+    secret_user: str = Field(
+        alias="secret-user",
+        description="",
+        examples=["secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub6vubg2s77p3nio0"],
+        title="Credentials Secret Name",
+    )
+
+    secret_tls: str | None = Field(
+        None,
+        alias="secret-tls",
+        description="The name of the TLS secret to use. Leaving this empty will configure a client with TLS disabled.",
+        examples=["secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub7fubg2s77p3niog"],
+        title="TLS Secret Name",
+    )
+
+
+class ZooKeeperRequirerAppData(BaseModel):
+    database: str = Field(
+        description="The parent chroot zNode requested by the requirer",
+        examples=["/myappA"],
+        title="zNode",
+    )
+
+    extra_user_roles: str | None = Field(
+        None,
+        alias="extra-user-roles",
+        description="ACL string representation for the parent chroot",
+        examples=["cdrwa"],
+        title="User roles",
+    )
+
+    requested_secrets: list[str] = Field(
+        alias="requested-secrets",
+        description="Any provider field which should be transfered as Juju Secret",
+        examples=[["username", "password", "tls-ca", "uris"]],
+        title="Requested secrets",
+    )
+
+    secret_mtls: str | None = Field(
+        alias="secret-mtls",
+        description="The name of the mTLS secret to use. Leaving this empty will configure the provider to not use mTLS.",
+        examples=["secret://59060ecc-0495-4a80-8006-5f1fc13fd783/cjqub7fubg2s77p3niog"],
+        title="mTLS Secret Name",
+    )
+
+
+class ProviderSchema(DataBagSchema):
+    """The schema for the provider side of this interface."""
+
+    app: ZooKeeperProviderAppData
+
+
+class RequirerSchema(DataBagSchema):
+    """The schema for the requirer side of this interface."""
+
+    app: ZooKeeperRequirerAppData