document ResourceUsage and Metrics CR #975

caozhuozi · 2024-02-14T13:38:42Z

What type of PR is this?

/kind documentation

What this PR does / why we need it:

The PR tries to document ResourceUsage and Metrics CR.

Which issue(s) this PR fixes:

Fixes #942

Special notes for your reviewer:

Please feel free to leave comments.

Does this PR introduce a user-facing change?

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

netlify · 2024-02-14T13:38:47Z

✅ Deploy Preview for k8s-kwok ready!

Name	Link
🔨 Latest commit	`8d97842`
🔍 Latest deploy log	https://app.netlify.com/sites/k8s-kwok/deploys/65fab2dc21b04100089f64cb
😎 Deploy Preview	https://deploy-preview-975--k8s-kwok.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

k8s-ci-robot · 2024-02-14T13:38:52Z

Hi @caozhuozi. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

wzshiming · 2024-02-18T06:21:06Z

/ok-to-test

site/content/en/docs/user/resource-usage-configuration.md

site/content/en/docs/user/metrics-configuration.md

site/content/en/docs/user/resource-usage-configuration.md

site/content/en/docs/user/metrics-configuration.md

site/content/en/docs/user/resource-usage-configuration.md

site/content/en/docs/user/metrics-configuration.md

site/content/en/docs/user/resource-usage-configuration.md

site/content/en/docs/user/metrics-configuration.md

site/content/en/docs/user/kwok-in-cluster.md

site/content/en/docs/user/metrics-configuration.md

windsonsea

Pick some more nits

site/content/en/docs/user/metrics-configuration.md

site/content/en/docs/user/resource-usage-configuration.md

windsonsea · 2024-02-19T10:25:56Z

lgtm for the text and you can mark those comments Resolved and try to pass the ci test.

caozhuozi · 2024-02-22T10:56:54Z

@wzshiming Any new comments?

site/content/en/docs/user/kwok-in-cluster.md

wzshiming · 2024-03-01T03:52:34Z

site/content/en/docs/user/metrics-configuration.md

+The `metrics` field are used to customize the return body of the installed metrics endpoint.
+`metrics` is a list of specific configuration items, with each corresponding to a Prometheus style metric:
+* `name` defines the metric name.
+* `labels` defines the metric labels, with each item corresponding to a specific metric label.
+  - `name` is a const string that provides the label name.
+  - `value` is represented as a CEL expression that dynamically determines the label value.
+    For example: you can use `node.metadata.name` to reference the node name as the label value.
+* `help` defines the help string of a metric.
+* `kind` defines the type of the metric: `counter`, `guage` or `histogram`.
+* `dimension` defines where the data comes from. It could be `node`, `pod`, or `container`.
+* `value` is a CEL expression that defines the metric value if `kind` is `counter` or `guage`.
+  Please refer to [built-in CEL extension functions] for an exhausted list that you can use to simulate the metric value.
+* `buckets` is exclusively for customizing the data of the metric of kind `histogram`.
+  - `le`, which defines the histogram bucket’s upper threshold, has the same meaning as the one of Prometheus histogram bucket.
+    That is, each bucket contains values less than or equal to `le`.
+  - `value` is a CEL expression that provides the value of the bucket.
+  - `hidden` indicates whether to show the bucket in the metric.
+    But the value of the bucket will be calculated and cumulated into the next bucket.


This section feels redundant, as there is already automatically generated documentation from API, we should update the API comments.

wzshiming · 2024-03-01T04:00:56Z

site/content/en/docs/user/metrics-configuration.md

+## built-in CEL extension functions
+
+As `kwok` doesn't actually run containers, to simulate the resource usage data, `kwok` provides the following CEL
+extension functions you can use in a CEL expression to help calculate the simulation data flexibly and dynamically:
+* `Now()`: returns the current timestamp.
+* `Rand()`: returns a random `float64` value.
+* `SinceSecond()` returns the seconds elapsed since a resource (pod or node) was created.
+  For example: `pod.SinceSecond()`, `node.SinceSecond()`.
+* `UnixSecond()` returns the Unix time of a given time of type `time.Time`.
+  For example: , `UnixSecond(Now())`, `UnixSecond(node.metadata.creationTimestamp)`.
+* `Quantity()` returns a float64 value of a given Quantity value. For example: `Quantity("100m")`, `Quantity("10Mi")`.


Perhaps we should devote a new page to generic template functions, it also includes #836

wzshiming · 2024-03-01T04:10:04Z

site/content/en/docs/user/resource-usage-configuration.md

+To associate a ResourceUsage with a certain pod to be simulated, users must ensure `metadata.name` and `metadata.namespace` are inconsistent with the name and namespace of the target pod.
+
+The resource usages of a pod are specified via `usages` field.
+The `usages` field are organized by groups, with each corresponding to a collection of containers that shares a same resource usage simulation setting.
+Each group consists of a list of container names (`containers`) and the shared resource usage setting (`usage`).
+
+{{< hint "info" >}}
+If `containers` is not given in a group, the `usage` in that group will be applied to all containers of the target pod.
+{{< /hint >}}


Make this part of the description consistent with Exec, Logs, Attach, PortForward.

site/content/en/docs/user/resource-usage-configuration.md

caozhuozi · 2024-03-15T15:19:48Z

Hi, @wzshiming. I'm sorry for the late update.
In this new commit, I made the following change based on your comments:

add 2 separate pages for the go template and CEL expressions respectively.
replace resource usage demo and svg files.
add more description in "Set up default CRs of resource usage (optional) based on your comment: document ResourceUsage and Metrics CR #975 (comment)

For the comment "Make the writing consistent across pages“, I'm going to file a separate PR to do this because I think it would be more clear.

You can give comments and leave this PR unmerged until the PR for writing consistency is ready and get reviewed.

site/content/en/docs/user/metrics-configuration.md

site/config.yaml

site/content/en/docs/user/metrics-configuration.md

caozhuozi · 2024-03-19T14:56:42Z

Thank you for your great patience in reviewing and helping with modifications. @wzshiming @windsonsea

wzshiming · 2024-03-20T09:48:17Z

[*] Verifying ends newline...
Add a new line in ends for below files
./site/content/en/docs/user/cel-expressions.md
./site/content/en/docs/user/stages-configuration.md

caozhuozi · 2024-03-20T10:05:47Z

[*] Verifying ends newline...
Add a new line in ends for below files
./site/content/en/docs/user/cel-expressions.md
./site/content/en/docs/user/stages-configuration.md

I ignored the CI result as it seems like it has been always failing before. sry about this...

caozhuozi · 2024-03-21T01:30:29Z

I've checked the failed CI stage this time. The logs of the failed one: "test-kwokctl" seems not related to the documentation.

wzshiming · 2024-03-25T02:00:44Z

/approve
/lgtm
/label tide/merge-method-squash

k8s-ci-robot · 2024-03-25T02:00:52Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: caozhuozi, wzshiming

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [wzshiming]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Add docs

f8aac0f

k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/documentation Categorizes issue or PR as related to documentation. labels Feb 14, 2024

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Feb 14, 2024

k8s-ci-robot requested review from Huang-Wei and yibozhuang February 14, 2024 13:38

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Feb 14, 2024

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 14, 2024

caozhuozi force-pushed the docs/resource-usage branch 4 times, most recently from 2a2571c to 1a19492 Compare February 15, 2024 02:10

add ResourceUsage and Metrics document details

ef99428

caozhuozi force-pushed the docs/resource-usage branch from 1a19492 to ef99428 Compare February 17, 2024 04:37

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Feb 18, 2024

wzshiming reviewed Feb 18, 2024

View reviewed changes

windsonsea reviewed Feb 18, 2024

View reviewed changes

site/content/en/docs/user/kwok-in-cluster.md Outdated Show resolved Hide resolved

site/content/en/docs/user/metrics-configuration.md Outdated Show resolved Hide resolved

site/content/en/docs/user/metrics-configuration.md Outdated Show resolved Hide resolved

k8s-ci-robot added the kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API label Feb 18, 2024

caozhuozi force-pushed the docs/resource-usage branch 2 times, most recently from 8289da7 to 2d87b17 Compare February 19, 2024 01:42

revise based on comments

0f55e6e

caozhuozi force-pushed the docs/resource-usage branch from 2d87b17 to 0f55e6e Compare February 19, 2024 01:44

windsonsea reviewed Feb 19, 2024

View reviewed changes

revise based on comments

c12ffb6

wzshiming reviewed Mar 1, 2024

View reviewed changes

caozhuozi force-pushed the docs/resource-usage branch from 131b8da to 73424d7 Compare March 15, 2024 15:27

caozhuozi mentioned this pull request Mar 17, 2024

docs: keep writing consistent across pages #1000

Merged

revise based on comments

2d469d9

caozhuozi force-pushed the docs/resource-usage branch from 73424d7 to 2d469d9 Compare March 17, 2024 16:26

wzshiming reviewed Mar 18, 2024

View reviewed changes

site/content/en/docs/user/metrics-configuration.md Outdated Show resolved Hide resolved

site/config.yaml Show resolved Hide resolved

site/content/en/docs/user/metrics-configuration.md Show resolved Hide resolved

revise based on comments

2a2e7dc

wzshiming reviewed Mar 19, 2024

View reviewed changes

site/content/en/docs/user/metrics-configuration.md Outdated Show resolved Hide resolved

site/content/en/docs/user/metrics-configuration.md Outdated Show resolved Hide resolved

revise based on comments

260c20c

revise based on comments

8d97842

k8s-ci-robot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Mar 25, 2024

k8s-ci-robot assigned wzshiming Mar 25, 2024

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 25, 2024

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 25, 2024

k8s-ci-robot merged commit 5c13cee into kubernetes-sigs:main Mar 25, 2024
27 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

document ResourceUsage and Metrics CR #975

document ResourceUsage and Metrics CR #975

caozhuozi commented Feb 14, 2024

netlify bot commented Feb 14, 2024 •

edited

Loading

k8s-ci-robot commented Feb 14, 2024

wzshiming commented Feb 18, 2024

windsonsea left a comment

windsonsea commented Feb 19, 2024

caozhuozi commented Feb 22, 2024

wzshiming Mar 1, 2024

wzshiming Mar 1, 2024

wzshiming Mar 1, 2024

caozhuozi commented Mar 15, 2024 •

edited

Loading

caozhuozi commented Mar 19, 2024

wzshiming commented Mar 20, 2024

caozhuozi commented Mar 20, 2024

caozhuozi commented Mar 21, 2024 •

edited

Loading

wzshiming commented Mar 25, 2024

k8s-ci-robot commented Mar 25, 2024

document ResourceUsage and Metrics CR #975

document ResourceUsage and Metrics CR #975

Conversation

caozhuozi commented Feb 14, 2024

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

netlify bot commented Feb 14, 2024 • edited Loading

✅ Deploy Preview for k8s-kwok ready!

k8s-ci-robot commented Feb 14, 2024

wzshiming commented Feb 18, 2024

windsonsea left a comment

Choose a reason for hiding this comment

windsonsea commented Feb 19, 2024

caozhuozi commented Feb 22, 2024

wzshiming Mar 1, 2024

Choose a reason for hiding this comment

wzshiming Mar 1, 2024

Choose a reason for hiding this comment

wzshiming Mar 1, 2024

Choose a reason for hiding this comment

caozhuozi commented Mar 15, 2024 • edited Loading

caozhuozi commented Mar 19, 2024

wzshiming commented Mar 20, 2024

caozhuozi commented Mar 20, 2024

caozhuozi commented Mar 21, 2024 • edited Loading

wzshiming commented Mar 25, 2024

k8s-ci-robot commented Mar 25, 2024

netlify bot commented Feb 14, 2024 •

edited

Loading

caozhuozi commented Mar 15, 2024 •

edited

Loading

caozhuozi commented Mar 21, 2024 •

edited

Loading