-
Notifications
You must be signed in to change notification settings - Fork 84
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
base: main
Are you sure you want to change the base?
Conversation
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]>
|
There was a problem hiding this 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?
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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. | |
| 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 | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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`) | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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) | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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) | |
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.
Related Issue(s):
harvester/harvester#7976