Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add README with CLI usage descriptions #20

Merged
merged 9 commits into from
Dec 29, 2023
Merged

Add README with CLI usage descriptions #20

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
766995f
Add README with CLI usage descriptions
kota2and3kan Dec 6, 2023
ddad824
Apply suggestions from code review
kota2and3kan Dec 25, 2023
dbb17dd
Merge branch 'main' into add-readme
kota2and3kan Dec 25, 2023
c3656bf
Update product name
kota2and3kan Dec 25, 2023
71c433e
Apply suggestions from code review
kota2and3kan Dec 25, 2023
6377a3c
Update README.md
kota2and3kan Dec 27, 2023
af9596a
Update README.md
kota2and3kan Dec 27, 2023
7a9ed87
Update README.md
kota2and3kan Dec 27, 2023
8d5d2a4
Apply suggestion from code review
kota2and3kan Dec 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Scalar Admin k8s
kota2and3kan marked this conversation as resolved.
Show resolved Hide resolved

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added such an explanation in 71c433e.

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

Copy link
Member

@josh-wong josh-wong Dec 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

## Usage of the CLI tool
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


```console
Usage: scalar-admin-k8s-cli [-h] [-d=<pauseDuration>] [-n=<namespace>]
-r=<helmReleaseName> [-w=<maxPauseWaitTime>]
[-z=<zoneId>]
Scalar Admin pause tool for the Kubernetes environment
-d, --pause-duration=<pauseDuration>
The duration of the pause period by millisecond.
5000 (5 seconds) by default.
-h, --help Display the help message.
-n, --namespace=<namespace>
Namespace that Scalar products you want to pause
are deployed. `default` by default.
-r, --release-name=<helmReleaseName>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Helm's release name that you specify when you run
the `helm install <RELEASE_NAME>` command. You
can see the <RELEASE_NAME> by using the `helm
list` command.
-w, --max-pause-wait-time=<maxPauseWaitTime>
The max wait time (in milliseconds) until Scalar
products drain outstanding requests before they
pause. If omitting this option, the max wait
time will be the default value defined in the
products. Most Scalar products have the default
value of 30 seconds.
-z, --time-zone=<zoneId> Specify a time zone ID, e.g., Asia/Tokyo, to
output successful paused period. Note the time
zone ID is case sensitive. Etc/UTC by default.
```

## Run the CLI tool on a Kubernetes environment
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 marked this conversation as resolved.
Show resolved Hide resolved

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:
Copy link
Member

@josh-wong josh-wong Dec 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Collaborator Author

@kota2and3kan kota2and3kan Dec 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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:

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


1. Create three Kubernetes resources (`Role`, `RoleBinding`, and `ServiceAccount`).
* Role
kota2and3kan marked this conversation as resolved.
Show resolved Hide resolved

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: scalar-admin-k8s-role
namespace: <YOUR_NAMESPACE>
rules:
- apiGroups: ["", "apps"]
resources: ["pods", "deployments", "services"]
verbs: ["get", "list"]
```

* RoleBinding

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: scalar-admin-k8s-rolebinding
namespace: <YOUR_NAMESPACE>
subjects:
- kind: ServiceAccount
name: scalar-admin-k8s-sa
roleRef:
kind: Role
name: scalar-admin-k8s-role
apiGroup: rbac.authorization.k8s.io
```

* ServiceAccount

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: scalar-admin-k8s-sa
namespace: <YOUR_NAMESPACE>
```

1. Mount the `ServiceAccount` on the `scalar-admin-k8s` pod.
* Pod
kota2and3kan marked this conversation as resolved.
Show resolved Hide resolved

```yaml
apiVersion: v1
kind: Pod
metadata:
name: scalar-admin-k8s
namespace: <YOUR_NAMESPACE>
spec:
serviceAccountName: scalar-admin-k8s-sa
containers:
- name: scalar-admin-k8s
image: ghcr.io/scalar-labs/scalar-admin-k8s:1.0.0
command:
- java
- -jar
- /app.jar
- -r
- <HELM_RELEASE_NAME>
- -n
- <SCALAR_PRODUCT_NAMESPACE>
- -d
- <PAUSE_DURATION>
- -z
- <TIMEZONE>
```

## Run the CLI tool on a Kubernetes environment by using Helm Chart
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

kota2and3kan marked this conversation as resolved.
Show resolved Hide resolved

Coming soon.