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.
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.mdexplaining the purpose of the interface and the protocol - a
schema.pyfile containing pydantic models that specify the app and unit databag model for either side of the interface. charms.yamlfile consisting of a list of anyprovidersandrequirersknown to adhere to the specification.- a
interface_testsdirectory in which you can put python files containing interface tests. Read more about interface tests here
- a
- under
docs/, the json schemas generated from the pydantic schemas. You can use commandtox -e build-json-schemasto 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.
| 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 |
|
| Category | Interface | Status |
|---|---|---|
| Metadata | k8s-service |
|
| Metadata | kubeflow-dashboard-sidebar |
|
| Category | Interface | Status |
|---|---|---|
| Identity | hydra_endpoints |
|
kratos_external_idp |
|
|
kratos_endpoints |
|
|
login_ui_endpoints |
|
| Category | Interface | Status |
|---|---|---|
| Observability | cos_agent |
|
| 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.
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.