NC | Upstream Docs Refactoring #8162
Conversation
romayalon
force-pushed
the
romy-nc-docs
branch
5 times, most recently
from
40e325c
to
d390f30
Compare
romayalon
requested review from
guymguym,
nimrod-becker,
tangledbytes,
shirady and
naveenpaul1
|
|
||
| ## NooBaa Non Containerized Solution | ||
|
|
||
| NooBaa Non Containerized is a lightweight deployment of NooBaa on Linux without depending on Kubernetes. NooBaa Non Containerized version includes NooBaa service that deploys S3 endpoints for handling S3 requests, the NooBaa CLI for managing accounts & buckets, and NooBaa Health CLI for performing system health analysis. |
There was a problem hiding this comment.
I think we can remove the word version
NooBaa Non Containerized version includes NooBaa service that deploys S3 endpoints
I think we can call them just endpoints (instead of "S3 endpoints")
deploys S3 endpoints
There was a problem hiding this comment.
removed the version but kept the S3, I want to make it clear for everyone the the endpoints are serving s3 requests.
There was a problem hiding this comment.
Sure, but in the next versions, it will be also for STS and IAM requests.
|
|
||
| NooBaa Non Containerized solution includes the following components - | ||
| 1. [NooBaa Service](#enable-noobaa-service) - Deploys NooBaa S3 endpoint for handling S3 requests. | ||
| 2. [NooBaa CLI](./NooBaaCLI.md) - Accounts and exported buckets management. |
There was a problem hiding this comment.
What are "exported buckets"?
Signed-off-by: Romy <[email protected]>
| Example - | ||
| ```sh | ||
| // 1. Create the storage underlying directory | ||
| // 2. Apply 777 permission to the directory (insecure) |
There was a problem hiding this comment.
Maybe we can add the "secure" step to do it?
And if not explain exactly what we did as bypass.
| * Configuration files generated under the `accounts/` or `buckets/` directories will have 600 permissions, granting read and write access exclusively to the owner of each configuration file. | ||
|
|
||
| Ownership | ||
| * Configuration file created by the NooBaa CLI tool will be owned by the user who ran the NooBaa CLI command. |
There was a problem hiding this comment.
yes but we need to remove this limitation
I didn't understand that, what is the plan?
|
|
||
| `certificates/` | ||
| * <u>Type</u>: Directory. | ||
| * <u>Required</u>: False. |
There was a problem hiding this comment.
I would also remove the dot of those keys ("No.", "File."), for a cleaner look.
|
|
||
| ## Introduction | ||
| A user can customize NooBaa Non Containerized by creation of config.json file under their config directory. | ||
| When a node is designated in the host_customization, Noobaa will combine the shared configuration with the node's configuration. If a configuration value is provided under the node's configuration, it will take precedence as the final configuration value applied to NooBaa service on that specific node. |
There was a problem hiding this comment.
Not sure the use of "is designated" is clear (in "When a node is designated in the host_customization").
| ## Introduction | ||
| A user can customize NooBaa Non Containerized by creation of config.json file under their config directory. | ||
| When a node is designated in the host_customization, Noobaa will combine the shared configuration with the node's configuration. If a configuration value is provided under the node's configuration, it will take precedence as the final configuration value applied to NooBaa service on that specific node. |
There was a problem hiding this comment.
I think it should take a step and explain the 2 options that we have in the config file:
- shared configuration
- node/host configuration
It seems that it jumps directly to the logic between them.
| * <u>Key</u>: `ENDPOINT_FORKS` | ||
| * <u>Type</u>: Number | ||
| * <u>Default</u>: 0 | ||
| * <u>Description</u>: Adjust the number of forks in order to increase the S3 endpoints number. This will enable NooBaa to handle a higher scale of S3 requests concurrently. |
There was a problem hiding this comment.
Where do we explain under the hood how the requests are handled between the endpoints?
| 1. ENDPOINT_PORT - S3 HTTP port | ||
| 2. ENDPOINT_SSL_PORT - S3 HTTPS port | ||
| 3. ENDPOINT_SSL_STS_PORT - STS HTTPS port | ||
| 4. EP_METRICS_SERVER_PORT - Prometheus metrics port |
There was a problem hiding this comment.
Maybe add a code line in each?
| 1. ENDPOINT_PORT - S3 HTTP port | |
| 2. ENDPOINT_SSL_PORT - S3 HTTPS port | |
| 3. ENDPOINT_SSL_STS_PORT - STS HTTPS port | |
| 4. EP_METRICS_SERVER_PORT - Prometheus metrics port | |
| 1. `ENDPOINT_PORT` - S3 HTTP port | |
| 2. `ENDPOINT_SSL_PORT` - S3 HTTPS port | |
| 3. `ENDPOINT_SSL_STS_PORT` - STS HTTPS port | |
| 4. `EP_METRICS_SERVER_PORT` - Prometheus metrics port |
| 1. ENDPOINT_PORT - S3 HTTP port | ||
| 2. ENDPOINT_SSL_PORT - S3 HTTPS port | ||
| 3. ENDPOINT_SSL_STS_PORT - STS HTTPS port | ||
| 4. EP_METRICS_SERVER_PORT - Prometheus metrics port |
There was a problem hiding this comment.
How do we use Prometheus in NC NSFS? You can add a link.
| * <u>Key</u>: `ENDPOINT_PROCESS_TITLE` | ||
| * <u>Type</u>: String | ||
| * <u>Default</u>: 'noobaa' | ||
| * <u>Description</u>: This flag will set NooBaa process title for letting GPFS to identify the NooBaa endpoint processes. See issue #8039. |
There was a problem hiding this comment.
We need to link the issue in GitHub.
| * <u>Description</u>: This flag will set NooBaa process title for letting GPFS to identify the NooBaa endpoint processes. See issue #8039. | |
| * <u>Description</u>: This flag will set NooBaa process title for letting GPFS identify the NooBaa endpoint processes. See issue [#8039](https://github.com/noobaa/noobaa-core/issues/8039). |
| * <u>Key</u>: `GPFS_DOWN_DELAY` | ||
| * <u>Type</u>: Number | ||
| * <u>Default</u>: 1000 | ||
| * <u>Description</u> Set delay (ms) of GPFS system calls when daemon is down, to hold client replies during failover, service restart required. |
There was a problem hiding this comment.
"during failover" - maybe fail over? failure?
| * <u>Key</u>: `LOG_TO_SYSLOG_ENABLED` | ||
| * <u>Type</u>: Boolean | ||
| * <u>Default</u>: true | ||
| * <u>Description</u>: This flag will enable syslog logging for the application. |
There was a problem hiding this comment.
Can we refer to more information about the syslog logging?
| ## Config.json File Examples | ||
| The following is an example of a config.json file - | ||
|
|
||
| ```sh |
There was a problem hiding this comment.
We can show the JSON with a JSON style ("```json").
Like in AWS CLI examples (for example in put-bucket-policy).
There was a problem hiding this comment.
General on this file:
- There are places where we write "service restart required" and add it in the step, and places where we just add the step, so we need to fix it. Can we add a "thumb rule" in which cases will we restart the service?
- They're places where we add the bytes example in different styles:
67108864 // 64MB = 64 * 1024 * 1024 vs 32MB = 33554432 bytes = 32 * 1024 * 1024 (I prefer the first one). - I would add to the number type the measurement explicitly and not just in the description (bytes, milliseconds, etc.).
Explain the changes
Issues: Fixed #xxx / Gap #xxx
Testing Instructions: