docs: update external docs with a better structure #14718
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
parth-gr
force-pushed
the
external-doc-structure
branch
from
c35ee0f to
0674d17
Compare
parth-gr
force-pushed
the
external-doc-structure
branch
from
0674d17 to
7d327d6
Compare
travisn
requested changes
Sep 13, 2024
|
|
||
| ### 1. Create all users and keys | ||
| * [Commands on the K8s consumer cluster](/Documentation/CRDs/Cluster/external-cluster/consumer-cluster.md) |
There was a problem hiding this comment.
Suggested change
| * [Commands on the K8s consumer cluster](/Documentation/CRDs/Cluster/external-cluster/consumer-cluster.md) | |
| 1. [Import config to the Rook consumer cluster](/Documentation/CRDs/Cluster/external-cluster/consumer-cluster.md). The configuration exported from the Ceph cluster is imported to Rook to provide the needed connection details. Steps are provided to validate the connection as well. |
|
|
||
| In order to configure an external Ceph cluster with Rook, we need to extract some information in order to connect to that cluster. | ||
| * [Extract data from Provider Ceph cluster](/Documentation/CRDs/Cluster/external-cluster/provider-cluster.md) |
There was a problem hiding this comment.
How about including a sentence or two with each of these links that describes the export action? Something like this?
Suggested change
| * [Extract data from Provider Ceph cluster](/Documentation/CRDs/Cluster/external-cluster/provider-cluster.md) | |
| 1. [Export config from the Provider Ceph cluster](/Documentation/CRDs/Cluster/external-cluster/provider-cluster.md). Configuration must be exported by the Ceph admin, such as a Ceph keyring and mon endpoints, that allows connection to the Ceph cluster. |
Also, let's make this a numbered list so it is clear the steps are ordered.
|
|
||
| Run the python script [create-external-cluster-resources.py](https://github.com/rook/rook/blob/master/deploy/examples/external/create-external-cluster-resources.py) for creating all users and keys. | ||
| * [Verify the cluster connection](/Documentation/CRDs/Cluster/external-cluster/consumer-cluster.md#cluster-verification) |
There was a problem hiding this comment.
This is part of the import in the previous step, so perhaps we don't need this step. It can be mentioned in the previously bullet.
| @@ -19,324 +19,26 @@ Create the desired types of storage in the provider Ceph cluster: | |||
| * [RBD pools](https://docs.ceph.com/en/latest/rados/operations/pools/#create-a-pool) | |||
| * [CephFS filesystem](https://docs.ceph.com/en/quincy/cephfs/createfs/) | |||
|
|
|||
| ## Commands on the source Ceph cluster | |||
| ## Steps to connect external Provider cluster to Consumer cluster | |||
There was a problem hiding this comment.
Suggested change
| ## Steps to connect external Provider cluster to Consumer cluster | |
| ## Connect the external Ceph Provider cluster to the Rook consumer cluster |
| ```console | ||
| python3 create-external-cluster-resources.py --rbd-data-pool-name <pool_name> --cephfs-filesystem-name <filesystem-name> --rgw-endpoint <rgw-endpoint> --namespace <namespace> --format bash | ||
| ``` | ||
| ## Advance Features |
There was a problem hiding this comment.
Suggested change
| ## Advance Features | |
| ## Advanced Options |
| @@ -0,0 +1,53 @@ | |||
| # Upgrade external cluster | |||
There was a problem hiding this comment.
Suggested change
| # Upgrade external cluster | |
| # External Cluster Upgrades |
| 1) An existing non-restricted user cannot be converted to a restricted user by upgrading. | ||
| 2) The upgrade flag should only be used to append new permissions to users. It shouldn't be used for changing a CSI user already applied permissions. For example, be careful not to change pools(s) that a user has access to. | ||
|
|
||
| # Upgrade cluster to utilize new feature |
There was a problem hiding this comment.
Suggested change
| # Upgrade cluster to utilize new feature | |
| ## Upgrade cluster to utilize a new feature |
|
|
||
| * arg: Exact arguments that were used for for processing the script. Argument that are decided using the Priority: command-line-args > config.ini file values > default values. | ||
|
|
||
| ## Example `external-cluster-user-command` ConfigMap: |
There was a problem hiding this comment.
Suggested change
| ## Example `external-cluster-user-command` ConfigMap: | |
| ### Example `external-cluster-user-command` ConfigMap: |
| @@ -1,3 +1,7 @@ | |||
| nav: | |||
| - external-cluster.md | |||
| - topology-for-external-mode.md | |||
| - advance-external.md | |||
There was a problem hiding this comment.
Let's have these topics match the order that the user will need to run them. I would think the following order, and possibly rename. Seems like the topology topic should be last in the list.
- external-cluster.md
- provider-cluster.md --> provider-export.md
- consumer-cluster.md --> consumer-import.md
- upgrade-external.md
- topology-for-external-mode.md
parth-gr
force-pushed
the
external-doc-structure
branch
from
7d327d6 to
e9c2c52
Compare
parth-gr
force-pushed
the
external-doc-structure
branch
from
e9c2c52 to
ad7457f
Compare
travisn
requested changes
Sep 16, 2024
|
|
||
| ### 1. Create all users and keys | ||
| 2) [Import config to the Rook consumer cluster](/Documentation/CRDs/Cluster/external-cluster/consumer-import.md). The configuration exported from the Ceph cluster is imported to Rook to provide the needed connection details. | ||
| [Verify the cluster connection](/Documentation/CRDs/Cluster/external-cluster/consumer-import.md#cluster-verification) steps are provided to validate the connection. |
There was a problem hiding this comment.
I'm still confused by mentioning the verification here. Can we just remove this line, and they can see the verification in the import topic?
| !!! warning | ||
| If the last-applied config is unavailable, run the current version of the script again using previously-applied config and CLI flags. | ||
| Failure to reuse the same configuration options when re-invoking the python script can result in unexpected changes when re-running the import script. | ||
| * [Utilize new feature with upgrade](/Documentation/CRDs/Cluster/external-cluster/upgrade-external.md#upgrade-cluster-to-utilize-new-feature) |
There was a problem hiding this comment.
Suggested change
| * [Utilize new feature with upgrade](/Documentation/CRDs/Cluster/external-cluster/upgrade-external.md#upgrade-cluster-to-utilize-new-feature) | |
| * [Utilize new features in upgrade](/Documentation/CRDs/Cluster/external-cluster/upgrade-external.md#upgrade-cluster-to-utilize-new-feature) |
|
|
||
| !!! note | ||
| You can use both config file and other arguments at the same time | ||
| Priority: command-line-args > config.ini file values > default values |
There was a problem hiding this comment.
Can you describe this instead of using the symbol >?
parth-gr
force-pushed
the
external-doc-structure
branch
from
ad7457f to
bcee3a6
Compare
travisn
reviewed
Sep 17, 2024
| @@ -0,0 +1,75 @@ | |||
| # Import Ceph configuration to the Rook consumer cluster | |||
|
|
|||
| ## Installation types: | |||
There was a problem hiding this comment.
nit, no need for : on headers
Suggested change
| ## Installation types: | |
| ## Installation types |
parth-gr
force-pushed
the
external-doc-structure
branch
from
bcee3a6 to
746b3bb
Compare
parth-gr
force-pushed
the
external-doc-structure
branch
from
746b3bb to
0b546fe
Compare
travisn
requested changes
Sep 19, 2024
| Upgrading external cluster is little tricky, We need to upgrade the Ceph cluster and Rook cluster seperalty with their new versions, Plus upgrading the versions we also need to update the external provider cluster connection to consumer Rook cluster. | ||
|
|
||
| To upgrade the provider ceph cluster to use the latest ceph user permissions, which will be required for the rook reconciliation, based on the new implementation added to the Rook. | ||
| ## Upgrade the cluster to consume latest ceph user caps(mandatory) |
There was a problem hiding this comment.
For proper rendering, we usually need a blank link before and after titles
Suggested change
| ## Upgrade the cluster to consume latest ceph user caps(mandatory) | |
| ## Upgrade the cluster to consume latest ceph user caps (mandatory) |
| @@ -0,0 +1,59 @@ | |||
| # External Cluster Upgrades | |||
|
|
|||
| Upgrading external cluster is little tricky, We need to upgrade the Ceph cluster and Rook cluster seperalty with their new versions, Plus upgrading the versions we also need to update the external provider cluster connection to consumer Rook cluster. | |||
There was a problem hiding this comment.
How about this?
Suggested change
| Upgrading external cluster is little tricky, We need to upgrade the Ceph cluster and Rook cluster seperalty with their new versions, Plus upgrading the versions we also need to update the external provider cluster connection to consumer Rook cluster. | |
| When upgrading an external cluster, Ceph and Rook versions will be updated independently. During the Rook update, we also need to update the external provider cluster connection with any settings and permissions for new features. |
|
|
||
| Upgrading external cluster is little tricky, We need to upgrade the Ceph cluster and Rook cluster seperalty with their new versions, Plus upgrading the versions we also need to update the external provider cluster connection to consumer Rook cluster. | ||
|
|
||
| To upgrade the provider ceph cluster to use the latest ceph user permissions, which will be required for the rook reconciliation, based on the new implementation added to the Rook. |
There was a problem hiding this comment.
Does my suggestion above also cover this concept of new permissions and properties? Then no need for this paragraph.
Suggested change
| To upgrade the provider ceph cluster to use the latest ceph user permissions, which will be required for the rook reconciliation, based on the new implementation added to the Rook. |
parth-gr
force-pushed
the
external-doc-structure
branch
from
0b546fe to
db91b61
Compare
travisn
reviewed
Sep 20, 2024
| @@ -0,0 +1,58 @@ | |||
| # External Cluster Upgrades | |||
|
|
|||
| When upgrading an external cluster, Ceph and Rook versions will be updated independently. During the Rook update, we also need to update the external provider cluster connection with any settings and permissions for new features. | |||
There was a problem hiding this comment.
nit: remove usage of "we"
Suggested change
| When upgrading an external cluster, Ceph and Rook versions will be updated independently. During the Rook update, we also need to update the external provider cluster connection with any settings and permissions for new features. | |
| When upgrading an external cluster, Ceph and Rook versions will be updated independently. During the Rook update, the external provider cluster connection also needs to be updated with any settings and permissions for new features. |
step1 to improve the external docs and make it more clear to end user Signed-off-by: parth-gr <partharora1010@gmail.com>
parth-gr
force-pushed
the
external-doc-structure
branch
from
db91b61 to
467578d
Compare
travisn
approved these changes
Sep 20, 2024
6 tasks
travisn
added a commit
that referenced
this pull request
Sep 20, 2024
docs: update external docs with a better structure (backport #14718)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
step1 to improve the external docs
and make it more clear to end user
Checklist: