diff --git a/interfaces/cloudflared_route/v0/README.md b/interfaces/cloudflared_route/v0/README.md new file mode 100644 index 00000000..925d621b --- /dev/null +++ b/interfaces/cloudflared_route/v0/README.md @@ -0,0 +1,56 @@ +# `cloudflared_route` + +## Usage + +The `cloudflared_route` interface is designed to facilitate information exchange between the cloudflared tunnel configurator charm and the cloudflared tunnel charm. + +## Direction + +The `cloudflared_route` interface follows a provider/requirer pattern. The requirer is a charm that runs the cloudflared tunnel, and the provider is the charm that supplies configurations for the cloudflared tunnel. + +```mermaid +flowchart TD + Provider -- tunnel_token_secret_id,nameserver --> Requirer +``` + +## Behavior + +The following are the criteria that a Provider and Requirer need to adhere to in order to be compatible with this interface. + +### Provider + +- Is expected to provide a cloudflared tunnel token via a Juju secret. + - The Juju secret ID should be placed in the integration application databag with the name `tunnel_token_secret_id`. + - The Juju secret should be readable by the requirer charm. + - The Juju secret should contain one field, `tunnel-token`, with the cloudflared tunnel token as its content. +- Is expected to update the cloudflared tunnel token either by creating a new Juju secret and replacing the Juju secret ID in `tunnel_token_secret_id`, or by updating the content of the existing Juju secret ID. +- Is expected to optionally include a `nameserver` field in the integration databag. + - The `nameserver` field must be an IPv4 or IPv6 address of a DNS nameserver. + - The nameserver provided in this field must listen on port 53. + - The nameserver provided in this field must be able to resolve public domains. + - The nameserver provided in this field must be able to resolve any domain configured as the backend service for the cloudflared tunnel. + +### Requirer + +- Is expected to run a cloudflared tunnel instance with the provided tunnel token. +- Is expected to restart the cloudflared tunnel instance with a new tunnel token if the token changes in the integration. +- Is expected to run the cloudflared tunnel instance using the system's default nameserver if `nameserver` is not provided in the integration. +- Is expected to run the cloudflared tunnel instance with the specified `nameserver` if it is provided in the integration. + +## Relation Data + +### Provider + +[\[JSON Schema\]](./schemas/provider.json) + +The Provider provides the result of the requirer's request. It should be placed in the application databag. + +#### Example +```json + { + "application-data": { + "tunnel_token_secret_id": "secret:csn5caau557j9bojn7rg", + "nameserver": "1.1.1.1" + } + } +``` \ No newline at end of file diff --git a/interfaces/cloudflared_route/v0/interface.yaml b/interfaces/cloudflared_route/v0/interface.yaml new file mode 100644 index 00000000..cd9a37c6 --- /dev/null +++ b/interfaces/cloudflared_route/v0/interface.yaml @@ -0,0 +1,10 @@ +name: cloudflared_route +internal: false + +version: 0 +status: draft + +providers: [] +requirers: [] + +maintainer: is-charms diff --git a/interfaces/cloudflared_route/v0/schema.py b/interfaces/cloudflared_route/v0/schema.py new file mode 100644 index 00000000..c8a234c5 --- /dev/null +++ b/interfaces/cloudflared_route/v0/schema.py @@ -0,0 +1,28 @@ +# Copyright 2024 Canonical +# See LICENSE file for licensing details. +"""This file defines the schemas for the provider sides of the cloudflared_route interface. +It exposes the interfaces.schema_base.DataBagSchema subclasses called: +- ProviderSchema + +Examples: + ProviderSchema: + unit: + app: { + "tunnel_token_secret_id": "secret:csn5caau557j9bojn7rg", + "nameserver": "1.1.1.1" + } +""" + +from pydantic import IPvAnyAddress, BaseModel +from interface_tester.schema_base import DataBagSchema + + +class CloudflaredRouteProvider(BaseModel): + """List statuses for the DNS records informed by the requirer.""" + tunnel_token_secret_id: str + nameserver: IPvAnyAddress | None + + +class ProviderSchema(DataBagSchema): + """Provider schema for dns_record.""" + app: CloudflaredRouteProvider