Charm Relation Interfaces

A catalogue of opinionated and standardized interface specifications for charmed operator relations.

Purpose

The purpose of the repository is to outline the behavior and requirements for key interface names, ensuring that charms claiming to implement a certain interface actually are capable of being integrated with each other.

Contributing

To contribute a new interface specification, open a pull request containing:

a new directory: /interfaces/{your-interface-name}. In it, there should be:
- a README.md explaining the purpose of the interface and the protocol
- a schema.py file containing pydantic models that specify the app and unit databag model for either side of the interface.
- charms.yaml file consisting of a list of any providers and requirers known to adhere to the specification.
- a interface_tests directory in which you can put python files containing interface tests. Read more about interface tests here
under docs/, the json schemas generated from the pydantic schemas. You can use command tox -e build-json-schemas to generate them automatically. Do not edit those files manually.
in this repo's root README.md, add the interface to the table, if applicable.

To quickly get started, see the template interface for a template of what to include and how it should be structured.

Interfaces

Category	Interface	Status
Data	`mysql_client`
	`postgresql_client`
	`mongodb_client`
	`kafka_client`
	`opensearch_client`
	`database_backup`
Identity	`hydra_endpoints`
	`oauth`
	`openfga`
	`saml`
Observability	`grafana_auth`
	`prometheus_remote_write`
	`prometheus_scrape`
	`tracing`
Networking	`ingress/v1`
	`ingress/v2`
	`ingress_per_unit`
	`nginx_route`
	`ip_router`
Security	`certificate_transfer`
	`tls_certificates/v0`
	`tls_certificates/v1`
	`vault-kv`
Metadata	`k8s-service`
Storage	`s3`

Project-internal Interfaces

Charmed Kubeflow

Category	Interface	Status
Metadata	`k8s-service`
Metadata	`kubeflow-dashboard-sidebar`

Identity

Category	Interface	Status
Identity	`hydra_endpoints`
	`kratos_external_idp`
	`kratos_endpoints`
	`login_ui_endpoints`

Observability

Category	Interface	Status
Observability	`cos_agent`

Telco

Category	Interface	Status
Charmed 5G	`fiveg_gnb_identity`
	`fiveg_nrf`
	`fiveg_n2`
	`fiveg_n3`
	`fiveg_n4`
	`sdcore_management`

For a more detailed explanation of statuses and how they should be used, see the legend.

Relation interface testers

In order to automatically validate whether a charm satisfies a given relation interface, the relation interface maintainer(s) need to write one or more relation interface tests. A relation interface test is a scenario-based test case which checks that, given an intitial context, when a relation event is triggered, the charm will do what the interface specifies. For example, most interface testers will check that, on relation changed, the charm will write a certain value into its (app/unit) databag and that that value matches a certain (Pydantic) schema.

See the tester documentation for more.

patriciareinoso/charm-relation-interfaces