---
title: Charmhub | vault-kv interface
description: Interfaces describe the relation between two charms. This interface shows
  opinionated, standardized interface specifications for charm relations.
url: https://charmhub.io/integrations/vault-kv
---

# vault-kv

## Usage

Some charms require a secure key value store. This relation interface describes the expected behavior of any charm claiming to interact with Vault Key Value stores.

## Direction

```
flowchart TD
    Requirer -- mount_suffix, nonce, egress_subnet, [wrap_ttl] --> Provider
    Provider -- vault_url, ca_certificate, mount, credentials --> Requirer
```

## Behavior

Both the Requirer and the Provider need to adhere to criteria to be considered compatible with the interface.

### Provider

Provider expectations

* Is expected to provide the vault url.
* Is expected to provide a ca certificate used to validate the vault server's certificate.
* Is expected to provide a key value mount, the mount name shall respect the following pattern: `charm-<requirer app>-<requirer provided suffix>`
* Is expected to create an approle restricted to the requiring unit's egress subnet.
* Is expected to create a Juju secret containing a role-id and role-secret-id for each unit. If `wrap_ttl` is requested by the Requirer, the Provider is expected to return a response-wrapping token instead of the `role-secret-id`. The response-wrapping token must contain the response of the POST `/auth/approle/role/:role_name/secret-id` API call. More information about wrapping tokens can be found in Vault [docs](https://developer.hashicorp.com/vault/docs/concepts/response-wrapping).
* Is expected to provide the Juju secret ID in the relation data, identified by the unit's nonce.
* Is expected to have out of date credentials when requirer unit's identity change, for some unspecified amount of time
  until new credentials have been generated. For example, during an upgrade-charm event.

### Requirer

Requirer expectations

* Is expected to provide a mount suffix.
* Is expected to provide the egress subnets for each unit requiring access to the vault key value store.
  The unit's egress\_subnet shall be used to restrict access to the secret backend.
  The egress\_subnet field should contain a string of all desired addresses separated by commas, using CIDR notation.
* Is expected to provide a nonce, i.e. a string uniquely identifying the unit.
* Is expected to optionally provide a `wrap_ttl` to request the `role-secret-id` being returned as a response-wrapping token with desired TTL.

## Relation Data

[[Pydantic Schema]](https://github.com/canonical/charmlibs/blob/main/interfaces/vault-kv/interface/vv0/schema.py)

### Example

```
provider:
  app:
    vault_url: http://10.152.183.104:8200
    mount: charm-barbican-secrets
```

## Charms implementing this interface

### Providers

### Requirers

## Other charms using this interface

### Providers

* [vault-k8s](https://charmhub.io/vault-k8s)
* [vault](https://charmhub.io/vault)

### Requirers

* [swift-storage](https://charmhub.io/swift-storage)
* [ceph-osd](https://charmhub.io/ceph-osd)
* [barbican-vault](https://charmhub.io/barbican-vault)
* [juju-jimm-k8s](https://charmhub.io/juju-jimm-k8s)
* [kubernetes-control-plane](https://charmhub.io/kubernetes-control-plane)
* [nova-compute](https://charmhub.io/nova-compute)
* [temporal-worker-k8s](https://charmhub.io/temporal-worker-k8s)