scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-01 19:17:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document secrets sync LIST request modifications (#23975)

Browse Source 
* * document list request adjustments

---------

Co-authored-by: Robert <17119716+robmonte@users.noreply.github.com>
This commit is contained in:
Max Coulombe
2023-11-10 09:04:26 -05:00
committed by GitHub
parent eb54346f41
commit af46b954f6
1 changed files with 177 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
website/content/api-docs/system/secrets-sync.mdx
View File

@@ -38,17 +38,59 @@ $ curl \
"lease_duration": 0,
"data": {
"key_info": {
"aws-sm": [
"aws-sm/": [
"my-dest-1"
],
"gh": [
"gh/": [
"my-dest-1"
]
},
"keys": [
"aws-sm",
"gh"
]
"aws-sm/",
"gh/"
],
"total_destinations": 2
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## List destinations by type
This endpoint lists all configured sync destination names for a given type.
| Method | Path |
|:-------|:-------------------------------|
| `LIST` | `/sys/sync/destinations/:type` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"keys": [
"my-dest-1"
],
"total_destinations": 1
},
"wrap_info": null,
"warnings": null,
@@ -341,8 +383,7 @@ $ curl \
http://127.0.0.1:8200/v1/sys/sync/destinations/vercel-project/my-store-1
```
## Read Associations
## Read associations
This endpoint returns all existing associations for a given destination. An association references the mount via its accessor.
Associations also contain the latest sync status for the secret they represent.
@@ -399,7 +440,7 @@ $ curl \
}
```
## Set Association
## Set association
The set endpoint links a secret to an existing destination using the secret name
and mount path and triggers a sync operation. If the secret is already
@@ -474,7 +515,7 @@ $ curl \
}
```
## Remove Association
## Remove association
The remove endpoint unlinks a secret from an existing destination based on the
secret name and mount path, and triggers an unsync operation. Unsync
@@ -541,3 +582,130 @@ $ curl \
"auth": null
}
```
## List associations
This endpoint lists all secrets referenced by at least one association. Each secret can be associated with multiple
destinations, so the total number of associations can be greater than the total number of synced secrets.
| Method | Path |
|:-------|:-------------------------|
| `LIST` | `/sys/sync/associations` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/associations
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key_info": {
"my-kv-1/my-secret-1": [
{
"mount": "my-kv-1/",
"secret_path": "my-secret-1"
}
],
"my/kv/1/my/secret/1": [
{
"mount": "my/kv/1/",
"secret_path": "my/secret/1"
}
]
},
"keys": [
"my/kv/1/my/secret/1",
"my-kv-1/my-secret-1"
],
"total_associations": 4,
"total_secrets": 2
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Read destinations by secret
This endpoint returns all destinations associated with the provided secret reference.
<Note>
The request is available either with path parameters or request parameters to support
mounts or secrets with forward slash characters (`/`).
</Note>
| Method | Path |
|:-------|:--------------------------------------|
| `GET` | `/sys/sync/associations/:mount/:name` |
| Method | Path |
|:-------|:---------------------------------------------------------------------|
| `GET` | `/sys/sync/associations/destinations?mount=:mount&secret_name=:name` |
### Parameters
- `mount` `(string: <required>)` - Specifies the mount where the secret is located. For example, if you can read a secret
with `vault kv get -mount=my-kv my-secret-1`, the mount name is `my-kv`.
- `name` `(string: <required>)` - Specifies the name of the synchronized secret. For example, if you can read a secret
with `vault kv get -mount=my-kv my-secret-1`, the secret name is `my-secret-1`.
### Sample requests
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/associations/my-kv-1/my-secret-1
```
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/associations/destinations?mount=my-kv-1&secret_name=my-secret-1
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"associated_destinations": {
"aws-sm/my-dest-1": {
"type": "aws-sm",
"name": "my-dest-1",
"sync_status": "UNSYNCED",
"updated_at": "2023-11-02T14:24:24.07391144-04:00"
},
"gh/my-dest-1": {
"type": "gh",
"name": "my-dest-1",
"sync_status": "SYNCED",
"updated_at": "2023-11-02T14:24:28.719833506-04:00"
}
}
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```