Charm Relation Interfaces

A catalogue of opinionated and standardized interface specifications for charmed operator relations. 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. 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
Observability	grafana_auth
	ingress
	ingress_per_unit
	prometheus_remote_write
	prometheus_scrape
Networking	ingress
	ingress_per_unit
Security	mutual_tls
	tls_certificates/v0
	tls_certificates/v1
Metadata	k8s-service
Storage	s3

Project-internal Interfaces

Charmed Kubeflow

Category	Interface	Status
Metadata	k8s-service

Identity

Category	Interface	Status
Identity	hydra_endpoints
	kratos_external_idp
	kratos_endpoints

Telco

Category	Interface	Status
Charmed 5G	fiveg_nrf

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.