Add README with CLI usage descriptions #20

kota2and3kan · 2023-12-06T11:16:33Z

Description

This PR adds a README. At this time, it includes descriptions about the CLI tool only.
This is because I need the document of the CLI tool itself to create a new document on the Helm Chart side.
I think we can add descriptions about the Java library if we need it in the future.

Related issues and/or PRs

N/A

Changes made

Add README.

Checklist

I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes.
Any remaining open issues linked to this PR are documented and up-to-date (Jira, GitHub, etc.).
Tests (unit, integration, etc.) have been added for the changes.
My changes generate no new warnings.
Any dependent changes in other PRs have been merged and published.

Additional notes (optional)

At the moment, I think we do NOT need to add this README to the document side.
This is because we assume that users use Helm Chart to run the Scalar Admin k8s instead of running the CLI tool directly.

In the future, I will create the document how to run Scalar Admin k8s by using Helm Chart in the Helm Chart repository and the document how to perform the backup operation by using Scalar Admin k8s in the scalar-kubernetes repository.
These two documents can help users to run the backup operation. So, I think these documents should be added to the doc site in the future instead of this README.

kota2and3kan · 2023-12-06T11:20:54Z

README.md

@@ -0,0 +1,110 @@
+# Scalar Admin k8s
+
+## Usage of the CLI tool


This is an output of the scalar-admin-k8s CLI. I think there is no document that describes each flag of scalar-admin-k8s. This is the main purpose of this PR.

This section describes the scalar-admin-k8s options and I can link to this document in the document of Helm Chart to explain the flags of scalar-admin-k8s.

kota2and3kan · 2023-12-06T11:22:07Z

README.md

+                               zone ID is case sensitive. Etc/UTC by default.
+```
+
+## Run the CLI tool on a Kubernetes environment


This section explains how to run the scalar-admin-k8s CLI tool manually.
However, I think there are almost no users to use this way.
We assume that users use Helm Chart instead of that.

kota2and3kan · 2023-12-06T11:23:29Z

README.md

+           - <TIMEZONE>
+     ```
+
+## Run the CLI tool on a Kubernetes environment by using Helm Chart


After I release the Helm Chart, I will update this section (add a link to the document of Helm Chart) in the future.
We assume that almost all users use this way for backup operations.

choplin

LGTM! I left one minor comment. Please take a look.

choplin · 2023-12-06T12:49:29Z

README.md

+  -n, --namespace=<namespace>
+                             Namespace that Scalar products you want to pause
+                               are deployed. `default` by default.
+  -r, --release-name=<helmReleaseName>


To be clear, only -r is required, correct? If so, I think it would be helpful to note that this parameter is required in the parameter description here.

To be clear, only -r is required, correct?

Yes. You are right.

If so, I think it would be helpful to note that this parameter is required in the parameter description here.

I see. I agree with adding a note.
I will do it in another PR.
Thank you for your suggestion!

supl

LGTM.
Thank you!

josh-wong

I've added some comments and suggestions. PTAL!

README.md

josh-wong · 2023-12-07T11:16:44Z

README.md

+
+## Run the CLI tool on a Kubernetes environment
+
+The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:


Depending on what we call the product (as mentioned in my previous comment), the product mentions in this paragraph might need to be updated.

Suggested change

The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:

The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and then do the following:

@josh-wong
Thank you for your suggestion!

In practice, the content of this section is a steps to deploy Scalar Admin for Kubernetes CLI on the Kubernetes environment. In other words, run CLI tool as a pod is included in the steps. So, I feel and then is a bit not fit in this section.

So, how about the following sentence?

Suggested change

The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:

The `scalar-admin-for-kubernetes` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-for-kubernetes` CLI tool as a pod on the Kubernetes environment by following to below steps.

@kota2and3kan Thank you for clarifying that! I assumed the steps were separate from the you must run part since we use and to introduce the steps.

In this case, let's use the following:

Suggested change

The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:

The `scalar-admin-for-kubernetes` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-for-kubernetes` CLI tool as a pod on the Kubernetes environment by following the steps below:

@josh-wong
Thank you for your suggestion!
I applied it in 8d5d2a4 .

README.md

feeblefakie

Overall, looking good!
Left one suggestion. PTAL!

feeblefakie · 2023-12-08T00:53:33Z

README.md

@@ -0,0 +1,110 @@
+# Scalar Admin k8s
+


Can you add a few sentences describing what this is?
I think it's helpful even for internal developers.
Something like the following.

scalar-admin-k8s is a tool that creates a paused state for Scalar products (e.g., ScalarDB and ScalarDL) in a Kubernetes environment. We can use such a paused state to take backups easily and consistently across multiple diverse databases.

(This might need to be checked by @josh-wong if it is used.)

I added such an explanation in 71c433e.

@josh-wong
Could you please also check this new sentence? Thank you!

I was unable to suggest changes to the sentence in a reply to this message, so I added a new comment with my suggestion to the updated sentence.

Co-authored-by: Josh Wong <[email protected]>

josh-wong

I've left a few minor suggestions. Other than that, LGTM! Thank you🙇🏻‍♂️

README.md

brfrn169

LGTM! Thank you!

Co-authored-by: Josh Wong <[email protected]>

feeblefakie

LGTM! Thank you!

Add README with CLI usage descriptions

766995f

kota2and3kan added the documentation Improvements or additions to documentation label Dec 6, 2023

kota2and3kan self-assigned this Dec 6, 2023

kota2and3kan commented Dec 6, 2023

View reviewed changes

kota2and3kan requested review from brfrn169, choplin, feeblefakie, supl and josh-wong December 6, 2023 11:25

choplin approved these changes Dec 6, 2023

View reviewed changes

supl approved these changes Dec 6, 2023

View reviewed changes

josh-wong requested changes Dec 7, 2023

View reviewed changes

feeblefakie reviewed Dec 8, 2023

View reviewed changes

supl mentioned this pull request Dec 21, 2023

Rename scalar-admin-k8s to scalar-admin-for-kubernetes #21

Merged

6 tasks

kota2and3kan and others added 4 commits December 25, 2023 15:03

Apply suggestions from code review

ddad824

Co-authored-by: Josh Wong <[email protected]>

Merge branch 'main' into add-readme

dbb17dd

Update product name

c3656bf

Apply suggestions from code review

71c433e

kota2and3kan requested review from feeblefakie and josh-wong December 25, 2023 06:38

josh-wong approved these changes Dec 25, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

brfrn169 approved these changes Dec 27, 2023

View reviewed changes

kota2and3kan and others added 4 commits December 27, 2023 19:27

Update README.md

6377a3c

Co-authored-by: Josh Wong <[email protected]>

Update README.md

af9596a

Co-authored-by: Josh Wong <[email protected]>

Update README.md

7a9ed87

Co-authored-by: Josh Wong <[email protected]>

Apply suggestion from code review

8d5d2a4

feeblefakie approved these changes Dec 29, 2023

View reviewed changes

feeblefakie merged commit ed9f18a into main Dec 29, 2023
5 checks passed

feeblefakie deleted the add-readme branch December 29, 2023 04:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add README with CLI usage descriptions #20

Add README with CLI usage descriptions #20

kota2and3kan commented Dec 6, 2023

kota2and3kan Dec 6, 2023

kota2and3kan Dec 6, 2023

kota2and3kan Dec 6, 2023

choplin left a comment

choplin Dec 6, 2023

kota2and3kan Dec 7, 2023

supl left a comment

josh-wong left a comment

josh-wong Dec 7, 2023 •

edited

Loading

kota2and3kan Dec 25, 2023 •

edited

Loading

josh-wong Dec 27, 2023

kota2and3kan Dec 27, 2023

feeblefakie left a comment

feeblefakie Dec 8, 2023

kota2and3kan Dec 25, 2023

josh-wong Dec 25, 2023 •

edited

Loading

josh-wong left a comment

brfrn169 left a comment

feeblefakie left a comment


		## Run the CLI tool on a Kubernetes environment

		The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:

	The `scalar-admin-k8s` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-k8s` CLI tool as a pod on the Kubernetes environment and you must:
	The `scalar-admin-for-kubernetes` CLI tool executes Kubernetes APIs in its internal processes. To run those Kubernetes APIs, you must run the `scalar-admin-for-kubernetes` CLI tool as a pod on the Kubernetes environment by following to below steps.

Add README with CLI usage descriptions #20

Add README with CLI usage descriptions #20

Conversation

kota2and3kan commented Dec 6, 2023

Description

Related issues and/or PRs

Changes made

Checklist

Additional notes (optional)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choplin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

supl left a comment

Choose a reason for hiding this comment

josh-wong left a comment

Choose a reason for hiding this comment

josh-wong Dec 7, 2023 • edited Loading

Choose a reason for hiding this comment

kota2and3kan Dec 25, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong Dec 25, 2023 • edited Loading

Choose a reason for hiding this comment

josh-wong left a comment

Choose a reason for hiding this comment

brfrn169 left a comment

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

josh-wong Dec 7, 2023 •

edited

Loading

kota2and3kan Dec 25, 2023 •

edited

Loading

josh-wong Dec 25, 2023 •

edited

Loading