Skip to content

docs: more specific backup target docs #816

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

m-ildefons
Copy link
Contributor

@m-ildefons m-ildefons commented Jul 7, 2025

Add more specific docs for configuring the backup target.

This commit includes screenshots as examples, parameter explanations for both S3 and NFS type backup targets and an explanation for the refresh interval parameter.

related-to: harvester/harvester#7976

Problem:

The refresh interval parameter for the backup target has some subtle and until now undocumented behaviors.
Additionally, the entire configuration dialogue for the backup target could be documented in greater detail.

Solution:

Add more detailed explanations for the backup target configuration, including screenshots showing examples and including all options.

Screenshot at 2025-07-07 12-04-54

Related Issue(s):

harvester/harvester#7976

Add more specific docs for configuring the backup target.

This commit includes screenshots as examples, parameter explanations
for both S3 and NFS type backup targets and an explanation for the
refresh interval parameter.

related-to: harvester/harvester#7976

Signed-off-by: Moritz Röhrich <[email protected]>
@m-ildefons m-ildefons self-assigned this Jul 7, 2025
@m-ildefons m-ildefons added the documentation Improvements or additions to documentation label Jul 7, 2025
@github-actions github-actions bot requested a review from akashraj4261 July 7, 2025 10:03
Copy link

github-actions bot commented Jul 7, 2025

Name Link
🔨 Latest commit 1b86056
😎 Deploy Preview https://686b9f6a4249dd14a47db2d4--harvester-preview.netlify.app

Copy link
Contributor

@jillian-maroket jillian-maroket left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review done.

I have major concerns about the text in the UI screenshots. It must be very clear that the backupstore stores backups, while the backup target is the endpoint used to access the backupstore. What exactly is the user configuring here?

Comment on lines +37 to +42
Common Parameters:

| Parameter | Type | Description |
| :--------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type | string | Choose S3 or NFS |
| Refresh Interval | integer | The interval at which the backups will be synced with the backup target. If `0`, backups will only be synced iff all backup volumes are in `ready` state. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Common Parameters:
| Parameter | Type | Description |
| :--------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type | string | Choose S3 or NFS |
| Refresh Interval | integer | The interval at which the backups will be synced with the backup target. If `0`, backups will only be synced iff all backup volumes are in `ready` state. |
The following table outlines the parameters that are common to all backup targets.
| Parameter | Type | Description |
| :--- | :--- | :--- |
| Type | string | Type of server that stores the backups of volumes used by virtual machines. You can select either `NFS` or `S3`. |
| Refresh Interval | integer | Number of seconds that Harvester waits before syncing backups with the backupstore. When the value is `0`, backups are synced only if all backup volumes are in the `Ready` state. |

Comment on lines +47 to +55
| Parameter | Type | Description |
| :----------------- | :----- | :--------------------------------------------------------------------------------------------- |
| Endpoint | string | A hostname or an IP address. It can be left empty for AWS S3. |
| BucketName | string | Name of the bucket |
| BucketRegion | string | Region of the bucket |
| AccessKeyID | string | A user-id that uniquely identifies your account |
| SecretAccessKey | string | The password to your account |
| Certificate | string | Paste to use a self-signed SSL certificate of your S3 server |
| VirtualHostedStyle | bool | Use virtual host style URLs of the form `bucket.example.com`; e.g., Alibaba Cloud (Aliyun) OSS |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Parameter | Type | Description |
| :----------------- | :----- | :--------------------------------------------------------------------------------------------- |
| Endpoint | string | A hostname or an IP address. It can be left empty for AWS S3. |
| BucketName | string | Name of the bucket |
| BucketRegion | string | Region of the bucket |
| AccessKeyID | string | A user-id that uniquely identifies your account |
| SecretAccessKey | string | The password to your account |
| Certificate | string | Paste to use a self-signed SSL certificate of your S3 server |
| VirtualHostedStyle | bool | Use virtual host style URLs of the form `bucket.example.com`; e.g., Alibaba Cloud (Aliyun) OSS |
| Parameter | Type | Description |
| :----------------- | :----- | :--------------------------------------------------------------------------------------------- |
| Endpoint | string | (Optional) Hostname or IP address of the endpoint used to access the S3 server |
| BucketName | string | Name of the S3 bucket |
| BucketRegion | string | AWS Region in which the S3 bucket was created |
| AccessKeyID | string | Unique identifier for the AWS account that you use to access S3 resources |
| SecretAccessKey | string | Password of the AWS account |
| Certificate | string | Self-signed SSL certificate of the S3 server |
| VirtualHostedStyle | bool | Option to use virtual-hosted–style URLs, wherein the bucket name is part of the domain name in the URL (`bucket.example.com`) |

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

| SecretAccessKey | string | Password of the AWS account |

This is wrong. The access key and secret access key are two parts of credentials that are used to authenticate a request.
They are different from account identifier and password.
An IAM user can have multiple access keys, each with its own secret access key.
For a service like S3 it's likely that there is no human user associated with the credentials, but rather a dedicated IAM user is used, as this allows reducing the permission scope to the bare minimum.

For self-hosted alternatives like Minio that utilize the S3 protocol, but aren't tied to AWS otherwise, the access key and secret key is often used synonymously with username/password, which is confusing.

I think we should adopt AWS terminology here and not mix account name and password with access key and secret access key.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for clarifying. I rewrote the descriptions for both AccessKeyID and SecretAccessKey based on the information on this page.

| AccessKeyID | string | First part of the access key you use to authenticate requests to AWS services (for example, AKIAIOSFODNN7EXAMPLE)
| SecretAccessKey | string | Second part of the access key you use to authenticate requests to AWS services (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY)

| SecretAccessKey | string | The password to your account |
| Certificate | string | Paste to use a self-signed SSL certificate of your S3 server |
| VirtualHostedStyle | bool | Use `VirtualHostedStyle` access only; e.g., Alibaba Cloud (Aliyun) OSS |
| Endpoint | string | The URL of the NFS server. [More info](https://longhorn.io/docs/1.6.0/snapshots-and-backups/backup-and-restore/set-backup-target/#set-up-nfs-backupstore) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Endpoint | string | The URL of the NFS server. [More info](https://longhorn.io/docs/1.6.0/snapshots-and-backups/backup-and-restore/set-backup-target/#set-up-nfs-backupstore) |
| Endpoint | string | URL of the [NFS server](https://longhorn.io/docs/1.8.0/snapshots-and-backups/backup-and-restore/set-backup-target/#set-up-nfs-backupstore) |

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants