Added docs generator and getting started guide #1
Conversation
sivanov-nuodb
requested review from
kontaras,
adriansuarez,
jleslie85 and
agoelzer
| @@ -0,0 +1,13 @@ | |||
| --- | |||
| title: "NuoDB Control Plane: Distributed SQL Database at Scale" | |||
There was a problem hiding this comment.
Should this be "NuoDB DBaaS"? Or is "Control Plane" the right name in this context? I think of the product name as presented to customers as "NuoDB DBaaS" similar to other DBaaS products. I think of the CP as the architecture or component that provides DBaaS administrative management.
| --namespace nuodb-cp-system \ | ||
| --wait \ | ||
| --set cpOperator.webhooks.enabled=true \ | ||
| --set 'cpOperator.extraArgs[0]=--ingress-https-port=8443' # Enables connecting to databases with port-forwarding |
There was a problem hiding this comment.
Isn't this actually for the webhooks server?
EDIT: Sorry, this is for overriding 443.
|
@sivanov-nuodb The generated docs look awesome. |
There was a problem hiding this comment.
Is this to publish the static site as a CircleCI artifact? How is this different from the GitHub Actions workflow, or are there dependencies between the two, e.g. the GitHub Actions workflow deploys what this builds, or they are independent?
There was a problem hiding this comment.
They are independent workflows. This one builds, runs static code analysis using htmlproofer, and uploads the site as CircleCI artifact. This is only for internal consumption during PR review process.
The GitHub workflow, runs on merge to main, builds, and publishes the site to GitHub actions which will be the official public site.
layouts/index.html
Outdated
| </div> | ||
| <div class="col-lg-5"> | ||
| <h2 class="h4">Flexible</h2> | ||
| <p>Create reusable database configurations and policies that meet your organization need.</p> |
There was a problem hiding this comment.
How about "backup schedules with user-configured backup retention policies" instead of "policies"?
Also, how about, organization --> business?
There was a problem hiding this comment.
"Policies" term is used in a broader context here which may include any type of configuration that enforces organization rules and policies. I've updated your other suggestion.
There was a problem hiding this comment.
What uses this, or what does this enable?
There was a problem hiding this comment.
It was automatically generated for https://www.gitpod.io/ development environment which we don't use.
| <p>Create reusable database configurations and policies that meet your organization need.</p> | ||
| </div> | ||
| <div class="col-lg-5"> | ||
| <h2 class="h4">Read the docs</h2> |
There was a problem hiding this comment.
We could probably drop this line sine the next line covers it well.
| noindex: false # false (default) or true | ||
| --- | ||
|
|
||
| - Delete all custom resources that have been created in `nuodb-cp-system` namespace. |
There was a problem hiding this comment.
I know this content is being migrated over, but maybe we can have a section or version of this (i.e. separate tab) that shows how to delete everything using the REST API. But maybe this section is for administrators specifically, as the helm uninstall invocations suggest.
There was a problem hiding this comment.
I'll update the page to first remove the provisioned resources via REST API / curl and then uninstall the CP (optional).
There was a problem hiding this comment.
@sivanov-nuodb Looks awesome.
I had to skim the content and trust that the configuration files and scripting are correct (the generated site proves that they are).
| noindex: false # false (default) or true | ||
| --- | ||
|
|
||
| NuoDB Control Plane allows users to provision NuoDB databases on-demand remotely using REST services by exposing various predefined configuration options. |
There was a problem hiding this comment.
How about this to connect the use of the DBaaS and CP terms?
"NuoDB DBaaS uses a control-plane architecture to provide administrative management. The NuoDB Control Plane allows users ..."
There was a problem hiding this comment.
"control-plane architecture" doesn't actually mean anything. "Control Plane" is an arbitrary name we gave to the product that implements DBaaS.
"DBaaS" is ambiguous because it could refer to a running instance of the service or the product that implements the service.
"Control Plane" basically is the product that implements DBaaS.
There was a problem hiding this comment.
The documentation is targeted at the NuoDB Control Plane (as a product). The NuoDB CP has many more configuration options that may be exposed in an external offering.
|
|
||
| The NuoDB Control Plane REST API exposes access to resources in a hierarchical structure. | ||
|
|
||
| - An _organization_ contains several _projects_ and _users_. |
There was a problem hiding this comment.
| - An _organization_ contains several _projects_ and _users_. | |
| - An _organization_ contains one or more _projects_ and _users_. | |
There was a problem hiding this comment.
An organization may contain no projects or users.
Technically organization is an implicit entity that is just part of the fully-qualified name of other resources, but you can have an organization that has a user and no project, and vice versa. So it is misleading to say that it always contains a project or user.
|
|
||
| - An _organization_ contains several _projects_ and _users_. | ||
| - A _user_ is an entity that authenticates itself and issues requests to resources that it has been granted access to. | ||
| - A _project_ contains several _databases_ and enables both logical and physical separation between databases. |
There was a problem hiding this comment.
| - A _project_ contains several _databases_ and enables both logical and physical separation between databases. | |
| - A _project_ contains one or more _databases_ and enables both logical and physical separation between databases. | |
There was a problem hiding this comment.
A project can have no databases.
| For cluster-scoped deployments, the NuoDB SA and RBAC should be provisioned before hand in each namespace where NuoDB databases are created. | ||
| {{< /callout >}} | ||
|
|
||
| ## Database Injection |
There was a problem hiding this comment.
Not sure why, but this section doesn't allow reviewers to add comments.
There was a problem hiding this comment.
It is outside the diff?
There was a problem hiding this comment.
Right, the other content is not changed in the context of this PR.
You could leave a comment on the file itself or feel free to edit the page content as needed.
Changes
QuickStart.mdto getting started guideReview
Scaffolding is generated in commit 1abbeec. The main topic for this PR the
content/docspath.The docs from this build can be seen at here.
Publishing action and docs can be seen in a forked repo - here.