Skip to content

Commit

Permalink
Add doc for Handling Restored File Ownership
Browse files Browse the repository at this point in the history 
Signed-off-by: Anisur Rahman <[email protected]>
  • Loading branch information
@anisurrahman75
anisurrahman75 committed Feb 20, 2024
1 parent 3433495 commit e062917
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 44 deletions.
Binary file added docs/guides/platforms/minio/images/minio.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
87 changes: 43 additions & 44 deletions docs/guides/use-cases/ownership/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
title: File Ownership | Stash
description: Handling Restored File Ownership in Stash
title: File Ownership | KubeStash
description: Handling Restored File Ownership in KubeStash
menu:
docs_{{ .version }}:
identifier: file-ownership-stash
identifier: file-ownership-kubestash
name: File Ownership
parent: use-cases
weight: 40
Expand All @@ -12,33 +12,32 @@ menu_name: docs_{{ .version }}
section_menu_id: guides
---

# Handling Restored File Ownership in Stash
# Handling Restored File Ownership in KubeStash

Stash preserves permission bits of the restored files. However, it may change ownership (owner `uid` and `gid`) of the restored files in some cases. This tutorial will explain when and how ownership of the restored files can be changed. Then, we are going to explain how we can avoid or resolve this problem.
KubeStash preserves permission bits of the restored files. However, it may change ownership (owner `uid` and `gid`) of the restored files in some cases. This tutorial will explain when and how ownership of the restored files can be changed. Then, we are going to explain how we can avoid or resolve this problem.

## Understanding Backup and Restore Behaviour

At first, let's understand how backup and restore behaves in different scenario. A table with some possible backup and restore scenario is given below. We have run the containers as different user in different scenario using [SecurityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).

| Case | Original File Owner | Backup `sidecar` User | Backup Succeed? | Restore `init-container` User | Restore Succeed? | Restored File Owner | Restored File Editable to Original Owner? |
| :---: | :-----------------: | :-------------------: | :-------------: | :---------------------------: | :-----------------------: | :-----------------: | :---------------------------------------: |
| 1 | root | stash (1005) | &#10003; | stash(1005) | &#10003; | 1005 | &#10003; |
| 2 | 2000 | stash(1005) | &#10003; | stash(1005) | &#10003; | 1005 | &#10007; |
| 3 | 2000 | root | &#10003; | root | &#10003; | 2000 | &#10003; |
| 4 | 2000 | root | &#10003; | stash(1005) | &#10003; (remote backend) | 1005 | &#10007; |
| 5 | 2000 | root | &#10003; | stash(1005) | &#10007; (local backend) | - | - |
| 6 | 2000 | 3000 | &#10003; | stash(1005) | &#10003; (remote backend) | 1005 | &#10007; |
| 7 | 2000 | 3000 | &#10003; | stash(1005) | &#10007; (local backend) | - | - |
| 8 | 2000 | 3000 | &#10003; | root | &#10003; | 2000 | &#10003; |
| 9 | 2000 | 3000 | &#10003; | 3000 | &#10003; | 3000 | &#10007; |
| Case | Original File Owner | Backup `Job` User | Backup Succeed? | Restore `Job` User | Restore Succeed? | Restored File Owner | Restored File Editable to Original Owner? |
|:----:|:-------------------:|:-----------------:|:---------------:|:------------------:|:----------------:|:-------------------:|:-----------------------------------------:|
| 1 | root | kubestash(65534) | &#10003; | kubstash(root) | &#10003; | root | &#10003; |
| 2 | root | kubestash(65534) | &#10003; | 65534 | &#10003; | root | &#10007; |
| 4 | 2000 | kubestash(65534) | &#10003; | kubestash(root) | &#10003; | 2000 | &#10003; |
| 4 | 2000 | kubestash(65534) | &#10003; | 65534 | &#10003; | 65534 | &#10007; |
| 5 | 2000 | root | &#10003; | 65534 | &#10003; | 65534 | &#10007; |
| 6 | 2000 | 3000 | &#10003; | kubestash(root) | &#10003; | 2000 | &#10003; |
| 7 | 2000 | 3000 | &#10003; | 65534 | &#10003; | 65534 | &#10007; |
| 8 | 2000 | 3000 | &#10003; | 3000 | &#10003; | 3000 | &#10007; |

If we look at the table carefully, we are going to notice the following behaviors:

1. The user of the backup `sidecar` does not have any effect on backup. It just needs read permission of the target files.
2. If the restore container runs as `root` user then original ownership of the restored files are preserved.
3. If the restore container runs as `non-root` user then the ownership of the restored files is changed to restore container's user and restored files become read-only to the original user unless it was `root` user.
1. The user of the backup `job` does not have any effect on backup. It just needs read permission of the target files.
2. If the restore job runs as `root` user then original ownership of the restored files are preserved.
3. If the restore job runs as `non-root` user then the ownership of the restored files is changed to restore jobs's user and restored files become read-only to the original user unless it was `root` user.

So, we can see when we run restore container as `non-root` user, it raises some serious concerns as the restored files become read-only to the original user. Next section will discuss how we can avoid or fix this problem.
So, we can see when we run restore job as `non-root` user, it raises some serious concerns as the restored files become read-only to the original user. Next section will discuss how we can avoid or fix this problem.

## Avoid or Fix Ownership Issue

Expand All @@ -51,43 +50,43 @@ There could be two scenarios for the restored files user.

### Restored files user is the same as the original user

This is likely to be the most common scenario. Generally, the same application whose data was backed up will use the restored files after a restore. In this case, if your cluster supports running containers as `root` user, then it is fairly easy to avoid this issue. You just need to run the restore container as `root` user which Stash does by default. However, things get little more complicated when your cluster does not support running containers as `root` user. In this case, you can do followings:
This is likely to be the most common scenario. Generally, the same application whose data was backed up will use the restored files after a restore. In this case, if your cluster supports running containers as `root` user, then it is fairly easy to avoid this issue. You just need to run the restore job as `root` user which kubeStash does by default. However, things get little more complicated when your cluster does not support running containers as `root` user. In this case, you can do followings:

- Run restore container as the same user as the original container.
- Run restore job as the same user as the original job.
- Change the ownership of the restored files using `chown` after the restore is completed.

For the first method, we can achieve this configuring SecurityContext under `RuntimeSetting` of `RestoreSession` object. A sample `RestoreSession` objects configured SecurityContext to run as the same user as the original user (let original user is 2000) is shown below.
For the first method, we can achieve this configuring SecurityContext under `SecurityContext` of `RestoreSession.spec.addon.jobTemplate.spec` object. A sample `RestoreSession` objects configured SecurityContext to run as the same user as the original user (let original user is 2000) is shown below.

```yaml
apiVersion: stash.appscode.com/v1beta1
apiVersion: core.kubestash.com/v1alpha1
kind: RestoreSession
metadata:
name: deployment-restore
namespace: demo
spec:
repository:
name: local-repo
rules:
- paths:
- /source/data
target:
ref:
apiVersion: apps/v1
kind: Deployment
name: stash-demo
volumeMounts:
- name: source-data
mountPath: /source/data
runtimeSettings:
container:
securityContext:
runAsUser: 2000
runAsGroup: 2000
apiGroup:
kind: Deployment
name: kubestash-demo
namespace: demo
dataSource:
repository: deployment-demo-gcs
snapshot: latest
encryptionSecret:
name: encryption-secret # some addon may not support encryption
namespace: demo
addon:
name: workload-addon
tasks:
- name: logical-backup-restore
jobTemplate:
spec:
securityContext:
runAsUser: 2000
runAsGroup: 2000
```
>If you are using [local](/docs/guides/backends/local/index.md) backend to store backed up data, then the original container, backup container and restore container all of them must be run as same user. By default, Stash runs backup container as `stash(1005)` user. You can change this to match with the user of your original container using `securityContext` field under `runtimeSettings` of `BackupConfiguration` object.

The second method is necessary when the backup container was not run as the same user as the original container. This is similar to the process when the restored files user is different than the original user. In this case, you have to change the ownership of restored files using `chown` after restore.
The second method is necessary when the backup job was not run as the same user as the original job. This is similar to the process when the restored files user is different than the original user. In this case, you have to change the ownership of restored files using `chown` after restore.

### Restored file user is different than the original user

Expand Down

0 comments on commit e062917

Please sign in to comment.