feedc0de/my-rook-config
1
0 Fork 0
forked from rook/rook
Code Pull Requests Activity

ci: use markdownlint to enforce mkdocs compatibility

Browse Source 
mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab
for detecting indentation levels, including ordered- and
unordered-lists. Since we cannot easily change the renderer, begin using
a markdown linter in CI that will fail if official docs do not adhere to
the spacing rules.

As a starting point, the markdownlint config does not begin with the
default set of checks, which might overwhelm attempts to fix them.
Instead, focus on list-tab-spacing rules and a few other highly useful
checks.

markdownlint also has some gaps in its abilities that allow common Rook
doc issues to pass acceptance. However, it allows creating custom
linting plugins. Create 2 such linting plugins to check 2 things:

- all doc lines (except code blocks) must be aligned to a 4-space
  boundary, without exception. This ensures that markdown will render
  correctly with mkdocs. This unfortunately makes it possible to create
  lists that are internally aligned strangely.
- admonitions must all follow the same format of
  ```
  !!! header
      body
  ```

For the strange lists, this is allowed and renders correctly, but it
looks strange:

```md
- first bullet
- second bullet
    still second bullet
- third bullet

    has a paragraph
    of text inside

- last bullet

Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>
(cherry picked from commit c9d99e01a0)
This commit is contained in:
Blaine Gardner committed 2024-05-01 13:52:39 -06:00
1 parent a4b4e7d319
commit 1391228b1d
55 files changed
+1134 -868
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-bucket-claim.md
+16 -16
View File
@@ -35,15 +35,15 @@ spec:
```
1. `name` of the `ObjectBucketClaim`. This name becomes the name of the Secret and ConfigMap.
1. `namespace`(optional) of the `ObjectBucketClaim`, which is also the namespace of the ConfigMap and Secret.
1. `bucketName` name of the `bucket`.
2. `namespace`(optional) of the `ObjectBucketClaim`, which is also the namespace of the ConfigMap and Secret.
3. `bucketName` name of the `bucket`.
**Not** recommended for new buckets since names must be unique within
an entire object store.
1. `generateBucketName` value becomes the prefix for a randomly generated name, if supplied then `bucketName` must be empty.
4. `generateBucketName` value becomes the prefix for a randomly generated name, if supplied then `bucketName` must be empty.
If both `bucketName` and `generateBucketName` are supplied then `BucketName` has precedence and `GenerateBucketName` is ignored.
If both `bucketName` and `generateBucketName` are blank or omitted then the storage class is expected to contain the name of an _existing_ bucket. It's an error if all three bucket related names are blank or omitted.
1. `storageClassName` which defines the StorageClass which contains the names of the bucket provisioner, the object-store and specifies the bucket retention policy.
1. `additionalConfig` is an optional list of key-value pairs used to define attributes specific to the bucket being provisioned by this OBC. This information is typically tuned to a particular bucket provisioner and may limit application portability. Options supported:
5. `storageClassName` which defines the StorageClass which contains the names of the bucket provisioner, the object-store and specifies the bucket retention policy.
6. `additionalConfig` is an optional list of key-value pairs used to define attributes specific to the bucket being provisioned by this OBC. This information is typically tuned to a particular bucket provisioner and may limit application portability. Options supported:
* `maxObjects`: The maximum number of objects in the bucket
* `maxSize`: The maximum size of the bucket, please note minimum recommended value is 4K.
@@ -69,10 +69,10 @@ status:
```
1. `namespace` where OBC got created.
1. `ObjectBucketName` generated OB name created using name space and OBC name.
1. the generated (in this case), unique `bucket name` for the new bucket.
1. name of the storage class from OBC got created.
1. phases of bucket creation:
2. `ObjectBucketName` generated OB name created using name space and OBC name.
3. the generated (in this case), unique `bucket name` for the new bucket.
4. name of the storage class from OBC got created.
5. phases of bucket creation:
* _Pending_: the operator is processing the request.
* _Bound_: the operator finished processing the request and linked the OBC and OB
* _Released_: the OB has been deleted, leaving the OBC unclaimed but unavailable.
@@ -98,8 +98,8 @@ spec:
```
1. use `env:` if mapping of the defined key names to the env var names used by the app is needed.
1. makes available to the pod as env variables: `BUCKET_HOST`, `BUCKET_PORT`, `BUCKET_NAME`
1. makes available to the pod as env variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
2. makes available to the pod as env variables: `BUCKET_HOST`, `BUCKET_PORT`, `BUCKET_NAME`
3. makes available to the pod as env variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
### StorageClass
@@ -119,11 +119,11 @@ reclaimPolicy: Delete [5]
```
1. `label`(optional) here associates this `StorageClass` to a specific provisioner.
1. `provisioner` responsible for handling `OBCs` referencing this `StorageClass`.
1. **all** `parameter` required.
1. `bucketName` is required for access to existing buckets but is omitted when provisioning new buckets.
Unlike greenfield provisioning, the brownfield bucket name appears in the `StorageClass`, not the `OBC`.
1. rook-ceph provisioner decides how to treat the `reclaimPolicy` when an `OBC` is deleted for the bucket. See explanation as [specified in Kubernetes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#retain)
2. `provisioner` responsible for handling `OBCs` referencing this `StorageClass`.
3. **all** `parameter` required.
4. `bucketName` is required for access to existing buckets but is omitted when provisioning new buckets.
Unlike greenfield provisioning, the brownfield bucket name appears in the `StorageClass`, not the `OBC`.
5. rook-ceph provisioner decides how to treat the `reclaimPolicy` when an `OBC` is deleted for the bucket. See explanation as [specified in Kubernetes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#retain)
* _Delete_ = physically delete the bucket.
* _Retain_ = do not physically delete the bucket.
Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-bucket-notifications.md
+39 -39
View File
@@ -68,38 +68,38 @@ spec:
```
1. `name` of the `CephBucketTopic`
* In case of AMQP endpoint, the name is used for the AMQP topic (“routing key” for a topic exchange)
* In case of Kafka endpoint, the name is used as the Kafka topic
1. `namespace`(optional) of the `CephBucketTopic`. Should match the namespace of the CephBucketNotification associated with this CephBucketTopic, and the OBC with the label referencing the CephBucketNotification
1. `objectStoreName` is the name of the object store in which the topic should be created. This must be the same object store used for the buckets associated with the notifications referencing this topic.
1. `objectStoreNamespace` is the namespace of the object store in which the topic should be created
1. `opaqueData` (optional) is added to all notifications triggered by a notifications associated with the topic
1. `persistent` (optional) indicates whether notifications to this endpoint are persistent (=asynchronous) or sent synchronously (“false” by default)
1. `endpoint` to which to send the notifications to. Exactly one of the endpoints must be defined: `http`, `amqp`, `kafka`
1. `http` (optional) hold the spec for an HTTP endpoint. The format of the URI would be: `http[s]://<fqdn>[:<port>][/<resource>]`
* port defaults to: 80/443 for HTTP/S accordingly
1. `disableVerifySSL` indicates whether the RGW is going to verify the SSL certificate of the HTTP server in case HTTPS is used ("false" by default)
1. `sendCloudEvents`: (optional) send the notifications with the [CloudEvents header](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md). Supported for Ceph Quincy (v17) or newer ("false" by default)
1. `amqp` (optional) hold the spec for an AMQP endpoint. The format of the URI would be: `amqp[s]://[<user>:<password>@]<fqdn>[:<port>][/<vhost>]`
* port defaults to: 5672/5671 for AMQP/S accordingly
* user/password defaults to: guest/guest
* user/password may only be provided if HTTPS is used with the RGW. If not, topic creation request will be rejected
* vhost defaults to: “/”
1. `disableVerifySSL` (optional) indicates whether the RGW is going to verify the SSL certificate of the AMQP server in case AMQPS is used ("false" by default)
1. `ackLevel` (optional) indicates what kind of ack the RGW is waiting for after sending the notifications:
* “none”: message is considered “delivered” if sent to broker
* “broker”: message is considered “delivered” if acked by broker (default)
* “routable”: message is considered “delivered” if broker can route to a consumer
1. `exchange` in the AMQP broker that would route the notifications. Different topics pointing to the same endpoint must use the same exchange
1. `kafka` (optional) hold the spec for a Kafka endpoint. The format of the URI would be: `kafka://[<user>:<password>@]<fqdn>[:<port]`
* port defaults to: 9092
* user/password may only be provided if HTTPS is used with the RGW. If not, topic creation request will be rejected
* user/password may only be provided together with `useSSL`, if not, the connection to the broker would fail
1. `disableVerifySSL` (optional) indicates whether the RGW is going to verify the SSL certificate of the Kafka server in case `useSSL` flag is used ("false" by default)
1. `ackLevel` (optional) indicates what kind of ack the RGW is waiting for after sending the notifications:
* “none”: message is considered “delivered” if sent to broker
* “broker”: message is considered “delivered” if acked by broker (default)
1. `useSSL` (optional) indicates that secure connection will be used for connecting with the broker (“false” by default)
+ In case of AMQP endpoint, the name is used for the AMQP topic (“routing key” for a topic exchange)
+ In case of Kafka endpoint, the name is used as the Kafka topic
2. `namespace`(optional) of the `CephBucketTopic`. Should match the namespace of the CephBucketNotification associated with this CephBucketTopic, and the OBC with the label referencing the CephBucketNotification
3. `objectStoreName` is the name of the object store in which the topic should be created. This must be the same object store used for the buckets associated with the notifications referencing this topic.
4. `objectStoreNamespace` is the namespace of the object store in which the topic should be created
5. `opaqueData` (optional) is added to all notifications triggered by a notifications associated with the topic
6. `persistent` (optional) indicates whether notifications to this endpoint are persistent (=asynchronous) or sent synchronously (“false” by default)
7. `endpoint` to which to send the notifications to. Exactly one of the endpoints must be defined: `http`, `amqp`, `kafka`
8. `http` (optional) hold the spec for an HTTP endpoint. The format of the URI would be: `http[s]://<fqdn>[:<port>][/<resource>]`
+ port defaults to: 80/443 for HTTP/S accordingly
9. `disableVerifySSL` indicates whether the RGW is going to verify the SSL certificate of the HTTP server in case HTTPS is used ("false" by default)
10. `sendCloudEvents`: (optional) send the notifications with the [CloudEvents header](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md). Supported for Ceph Quincy (v17) or newer ("false" by default)
11. `amqp` (optional) hold the spec for an AMQP endpoint. The format of the URI would be: `amqp[s]://[<user>:<password>@]<fqdn>[:<port>][/<vhost>]`
+ port defaults to: 5672/5671 for AMQP/S accordingly
+ user/password defaults to: guest/guest
+ user/password may only be provided if HTTPS is used with the RGW. If not, topic creation request will be rejected
+ vhost defaults to: “/”
12. `disableVerifySSL` (optional) indicates whether the RGW is going to verify the SSL certificate of the AMQP server in case AMQPS is used ("false" by default)
13. `ackLevel` (optional) indicates what kind of ack the RGW is waiting for after sending the notifications:
+ “none”: message is considered “delivered” if sent to broker
+ “broker”: message is considered “delivered” if acked by broker (default)
+ “routable”: message is considered “delivered” if broker can route to a consumer
14. `exchange` in the AMQP broker that would route the notifications. Different topics pointing to the same endpoint must use the same exchange
15. `kafka` (optional) hold the spec for a Kafka endpoint. The format of the URI would be: `kafka://[<user>:<password>@]<fqdn>[:<port]`
+ port defaults to: 9092
+ user/password may only be provided if HTTPS is used with the RGW. If not, topic creation request will be rejected
+ user/password may only be provided together with `useSSL`, if not, the connection to the broker would fail
16. `disableVerifySSL` (optional) indicates whether the RGW is going to verify the SSL certificate of the Kafka server in case `useSSL` flag is used ("false" by default)
17. `ackLevel` (optional) indicates what kind of ack the RGW is waiting for after sending the notifications:
+ “none”: message is considered “delivered” if sent to broker
+ “broker”: message is considered “delivered” if acked by broker (default)
18. `useSSL` (optional) indicates that secure connection will be used for connecting with the broker (“false” by default)
!!! note
In case of Kafka and AMQP, the consumer of the notifications is not required to ack the notifications, since the broker persists the messages before delivering them to their final destinations.
@@ -142,13 +142,13 @@ spec:
```
1. `name` of the `CephBucketNotification`
1. `namespace`(optional) of the `CephBucketNotification`. Should match the namespace of the CephBucketTopic referenced in [3], and the OBC with the label referencing the CephBucketNotification
1. `topic` to which the notifications should be sent
1. `filter` (optional) holds a list of filtering rules of different types. Only objects that match all the filters will trigger notification sending
1. `keyFilter` (optional) are filters based on the object key. There could be up to 3 key filters defined: `prefix`, `suffix` and `regex`
1. `metadataFilters` (optional) are filters based on the object metadata. All metadata fields defined as filters must exists in the object, with the values defined in the filter. Other metadata fields may exist in the object
1. `tagFilters` (optional) are filters based on object tags. All tags defined as filters must exists in the object, with the values defined in the filter. Other tags may exist in the object
1. `events` (optional) is a list of events that should trigger the notifications. By default all events should trigger notifications. Valid Events are:
2. `namespace`(optional) of the `CephBucketNotification`. Should match the namespace of the CephBucketTopic referenced in [3], and the OBC with the label referencing the CephBucketNotification
3. `topic` to which the notifications should be sent
4. `filter` (optional) holds a list of filtering rules of different types. Only objects that match all the filters will trigger notification sending
5. `keyFilter` (optional) are filters based on the object key. There could be up to 3 key filters defined: `prefix`, `suffix` and `regex`
6. `metadataFilters` (optional) are filters based on the object metadata. All metadata fields defined as filters must exists in the object, with the values defined in the filter. Other metadata fields may exist in the object
7. `tagFilters` (optional) are filters based on object tags. All tags defined as filters must exists in the object, with the values defined in the filter. Other tags may exist in the object
8. `events` (optional) is a list of events that should trigger the notifications. By default all events should trigger notifications. Valid Events are:
* s3:ObjectCreated:*
* s3:ObjectCreated:Put
* s3:ObjectCreated:Post
Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-multisite.md
+11 -7
View File
@@ -26,9 +26,9 @@ This guide assumes a Rook cluster as explained in the [Quickstart](../../Getting
If an admin wants to set up multisite on a Rook Ceph cluster, the following resources must be created:
1. A [realm](../../CRDs/Object-Storage/ceph-object-realm-crd.md#settings)
1. A [zonegroup](../../CRDs/Object-Storage/ceph-object-zonegroup-crd.md#settings)
1. A [zone](../../CRDs/Object-Storage/ceph-object-zone-crd.md#settings)
1. A ceph object store with the `zone` section
2. A [zonegroup](../../CRDs/Object-Storage/ceph-object-zonegroup-crd.md#settings)
3. A [zone](../../CRDs/Object-Storage/ceph-object-zone-crd.md#settings)
4. A ceph object store with the `zone` section
object-multisite.yaml in the [examples](https://github.com/rook/rook/blob/master/deploy/examples/) directory can be used to create the multisite CRDs.
@@ -45,6 +45,7 @@ The zone will create the pools for the object-store(s) that are in the zone to u
When one of the multisite CRs (realm, zone group, zone) is deleted the underlying ceph realm/zone group/zone is not deleted, neither are the pools created by the zone. See the "Multisite Cleanup" section for more information.
For more information on the multisite CRDs, see the related CRDs:
- [CephObjectRealm](../../CRDs/Object-Storage/ceph-object-realm-crd.md)
- [CephObjectZoneGroup](../../CRDs/Object-Storage/ceph-object-zonegroup-crd.md)
- [CephObjectZone](../../CRDs/Object-Storage/ceph-object-zone-crd.md)
@@ -56,7 +57,7 @@ If an admin wants to sync data from another cluster, the admin needs to pull a r
To begin doing this, the admin needs 2 pieces of information:
1. An endpoint from the realm being pulled from
1. The access key and the system key of the system user from the realm being pulled from.
2. The access key and the system key of the system user from the realm being pulled from.
### Getting the Pull Endpoint
@@ -176,9 +177,9 @@ kubectl create -f realm-a-keys.yaml
Once the admin knows the endpoint and the secret for the keys has been created, the admin should create:
1. A [CephObjectRealm](../../CRDs/Object-Storage/ceph-object-realm-crd.md#settings) matching to the realm on the other Ceph cluster, with an endpoint as described above.
1. A [CephObjectZoneGroup](../../CRDs/Object-Storage/ceph-object-zonegroup-crd.md#settings) matching the master zone group name or the master CephObjectZoneGroup from the cluster the realm was pulled from.
1. A [CephObjectZone](../../CRDs/Object-Storage/ceph-object-zone-crd.md#settings) referring to the CephObjectZoneGroup created above.
1. A CephObjectStore referring to the new CephObjectZone resource.
2. A [CephObjectZoneGroup](../../CRDs/Object-Storage/ceph-object-zonegroup-crd.md#settings) matching the master zone group name or the master CephObjectZoneGroup from the cluster the realm was pulled from.
3. A [CephObjectZone](../../CRDs/Object-Storage/ceph-object-zone-crd.md#settings) referring to the CephObjectZoneGroup created above.
4. A CephObjectStore referring to the new CephObjectZone resource.
object-multisite-pull-realm.yaml (with changes) in the [examples](https://github.com/rook/rook/blob/master/deploy/examples/) directory can be used to create the multisite CRDs.
@@ -346,6 +347,7 @@ Removing object store(s) from the master zone of the master zone group should be
## Configure an Existing Object Store for Multisite
When an object store is configured by Rook, it internally creates a zone, zone group, and realm with the same name as the object store. To enable multisite, you will need to create the corresponding zone, zone group, and realm CRs with the same name as the object store. For example, to create multisite CRs for an object store named `my-store`:
```yaml
apiVersion: ceph.rook.io/v1
kind: CephObjectRealm
@@ -398,11 +400,13 @@ spec:
#### Using custom names
If names different from the object store need to be set for the realm, zone, or zone group, first rename them in the backend via toolbox pod, then following the procedure above.
```console
radosgw-admin realm rename --rgw-realm=my-store --realm-new-name=<new-realm-name>
radosgw-admin zonegroup rename --rgw-zonegroup=my-store --zonegroup-new-name=<new-zonegroup-name> --rgw-realm=<new-realm-name>
radosgw-admin zone rename --rgw-zone=my-store --zone-new-name=<new-zone-name> --rgw-zonegroup=<new-zonegroup-name> --rgw-realm=<new-realm-name>
radosgw-admin period update --commit
```
!!! important
Renaming in the toolbox must be performed **before** creating the multisite CRs
Documentation/Storage-Configuration/Object-Storage-RGW/cosi.md
+1
View File
@@ -10,6 +10,7 @@ The Ceph COSI driver provisions buckets for object storage. This document instru
## Prerequisites
COSI requires:
1. A running Rook [object store](object-storage.md)
2. [COSI controller](https://github.com/kubernetes-sigs/container-object-storage-interface-controller#readme)