a85d4fe128
* add mount move docs * add missed word * Update website/content/api-docs/system/remount.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * one clarification * docs changes from feedback * couple things i missed Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
124 lines
3.5 KiB
Plaintext
124 lines
3.5 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/remount - HTTP API
|
||
description: >-
|
||
The '/sys/remount' endpoint is used remount a mounted backend to a new
|
||
endpoint.
|
||
---
|
||
|
||
# Remount ( API )
|
||
|
||
The Remount documentation details the endpoints required to trigger and monitor the status of a remount operation.
|
||
|
||
## Move Backend
|
||
|
||
The `/sys/remount` endpoint moves an already-mounted backend to a new mount point. This process works for both secret
|
||
engines and auth methods.
|
||
|
||
The endpoint can be used to move the backend across namespaces as well, with the namespaces supplied as prefixes
|
||
on the path arguments. In this case, namespaces for both the source and destination mounts need to be
|
||
either the namespace in which the `/remount` endpoint is called, or the children of that namespace. Let us assume that
|
||
we have 3 namespaces ns1/, ns1/ns2/ and ns1/ns3. We want to move the mount `secret` from ns1/ns2/secret to ns1/ns3/secret.
|
||
This can be done in one of two ways. The first way is to invoke `/remount` from the root namespace with the `from` argument as ns1/ns2/secret
|
||
and `to` argument as ns1/ns3/new-secret. The second way is to invoke `/remount` from the namespace ns1/, with `from` as ns2/secret and `to`
|
||
as ns3/new-secret.
|
||
|
||
The remount operation can be a long-running operation, hence the invocation of /remount triggers the start of
|
||
the remount process, returning a migration ID to the user. The user may utlizie the migration ID to look up
|
||
the status of the mount migration.
|
||
|
||
~> Note: This endpoint requires a policy with both `sudo` and `update` capabilities to `sys/remount`
|
||
|
||
~> Note: A mount migration will revoke all leases for the secrets of a secrets backend or tokens of an auth backend,
|
||
depending on which type of backend is being moved.
|
||
|
||
|
||
| Method | Path |
|
||
| :----- | :------------- |
|
||
| `POST` | `/sys/remount` |
|
||
|
||
### Parameters
|
||
|
||
- `from` `(string: <required>)` – Specifies the previous mount point.
|
||
|
||
- `to` `(string: <required>)` – Specifies the new destination mount point.
|
||
|
||
### Sample Payload ( Cross Namespace )
|
||
|
||
```json
|
||
{
|
||
"from": "ns1/ns2/secret",
|
||
"to": "ns1/ns3/new-secret"
|
||
}
|
||
```
|
||
|
||
### Sample Payload ( Cross Namespace, Auth Mount )
|
||
|
||
```json
|
||
{
|
||
"from": "ns1/ns2/auth/approle",
|
||
"to": "ns1/ns3/auth/new-approle"
|
||
}
|
||
```
|
||
|
||
### Sample Payload ( Within Namespace )
|
||
|
||
```json
|
||
{
|
||
"from": "secret",
|
||
"to": "new-secret"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/remount
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"migration_id": "ef3ba21c-8be8-4e5f-8d00-cb46a532c665"
|
||
}
|
||
```
|
||
|
||
## Monitor Migration Status
|
||
|
||
This endpoint is used to monitor the status of a mount migration operation, using the ID returned in the response
|
||
of the `sys/remount` call. The response contains the passed-in ID, the source and target mounts, and a status field
|
||
that displays `in-progress`, `success` or `failure`.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------- |
|
||
| `GET` | `/sys/remount/status/:migration_id` |
|
||
|
||
### Parameters
|
||
|
||
- `migration_id` `(string: <required>)` – Specifies the id of the mount migration
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/remount/status/ef3ba21c-8be8-4e5f-8d00-cb46a532c665
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"migration_id": "ef3ba21c-8be8-4e5f-8d00-cb46a532c665",
|
||
"migration_info": {
|
||
"source_mount": "ns1/ns2/secret",
|
||
"target_mount": "ns1/ns3/new-secret",
|
||
"status": "in-progress",
|
||
}
|
||
}
|
||
``` |