Add Document about Informers and Listers #2579

govargo · 2022-05-14T07:30:08Z

What this PR does / Why we need it:

/kind documentation
/kind feature

This PR add document about Kubernetes Informers and Listers.

Which issue(s) this PR fixes:

Closes #1260

Special notes for your reviewer:

This is my first contribution for Agones.
Please let me know if you have any advices.

Thanks in advance.

govargo · 2022-05-14T07:31:34Z

/assign @pooneh-m

agones-bot · 2022-05-14T07:56:52Z

Build Succeeded 👏

Build Id: 9a07247d-3160-41e0-a5c8-8163c97fbe71

The following development artifacts have been built, and will exist for the next 30 days:

image: gcr.io/agones-images/agones-controller:1.24.0-fe5a886-amd64
image: gcr.io/agones-images/agones-ping:1.24.0-fe5a886
Linux C++ SDK (build): agonessdk-1.24.0-fe5a886-linux-arch_64.tar.gz
SDK Server: agonessdk-server-1.24.0-fe5a886.zip

A preview of the website (the last 30 builds are retained):

https://fe5a886-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/2579/head:pr_2579 && git checkout pr_2579
helm install ./install/helm/agones --namespace agones-system --name agones --set agones.image.tag=1.24.0-fe5a886-amd64

agones-bot · 2022-05-14T12:04:46Z

Build Succeeded 👏

Build Id: 53da8dc4-ba66-42f5-a782-52b2a2e52495

The following development artifacts have been built, and will exist for the next 30 days:

image: gcr.io/agones-images/agones-controller:1.24.0-7473513-amd64
image: gcr.io/agones-images/agones-ping:1.24.0-7473513
Linux C++ SDK (build): agonessdk-1.24.0-7473513-linux-arch_64.tar.gz
SDK Server: agonessdk-server-1.24.0-7473513.zip

A preview of the website (the last 30 builds are retained):

https://7473513-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/2579/head:pr_2579 && git checkout pr_2579
helm install ./install/helm/agones --namespace agones-system --name agones --set agones.image.tag=1.24.0-7473513-amd64

markmandel

Thanks for submitting this - I suggested some changes of english - let me know what you think.

markmandel · 2022-05-20T22:15:13Z

site/content/en/docs/Guides/access-api.md

@@ -134,6 +134,131 @@ kubectl logs create-gs-6wz86-7qsm5  --namespace agones-system
 ```
 You have just created a GameServer using Kubernetes Go Client.

+## What are Informers and Listers? How can I use these?


Suggested change

## What are Informers and Listers? How can I use these?

## Best Practice: Using Informers and Listers

markmandel · 2022-05-20T22:18:49Z

site/content/en/docs/Guides/access-api.md

+Informers and Listers are mechanism for Kubernetes.
+Almost all of the native Kubernetes controllers and custom controllers use these mechanisms.
+Kubernetes's control plane can be accessed via Kubernetes APIs, however,
+the load for control plane cannot be ignored when the client program accesses to the control plane every time.


Suggested change

Informers and Listers are mechanism for Kubernetes.

Almost all of the native Kubernetes controllers and custom controllers use these mechanisms.

Kubernetes's control plane can be accessed via Kubernetes APIs, however,

the load for control plane cannot be ignored when the client program accesses to the control plane every time.

Almost all Kubernetes' controllers and custom controllers utilise `Informers` and `Listers` to reduce the load on the.

Kubernetes's control plane.

Repetitive, direct access of the Kubernetes control plane API can significantly reduce the performance of the cluster -- and Informers and Listers help resolving that issue.

markmandel · 2022-05-20T22:22:12Z

site/content/en/docs/Guides/access-api.md

+Informers and Listers can reduce the load for the control plane by using the in-memory-cache.
+When Informes and Listers are created, the in-memory-cache called as the store are also created.
+The client program accesses and queries to the in-memory-cache, not control plane,
+which enables reducing the load.


Suggested change

Informers and Listers can reduce the load for the control plane by using the in-memory-cache.

When Informes and Listers are created, the in-memory-cache called as the store are also created.

The client program accesses and queries to the in-memory-cache, not control plane,

which enables reducing the load.

Informers and Listers reduce the load on the Kubernetes control plane by creating, using and maintaining and eventually consistent an in-memory-cache. This can be watched and also queried with zero cost, since it will only read against its in-memory model of the Kubernetes resources.

markmandel · 2022-05-20T22:25:03Z

site/content/en/docs/Guides/access-api.md

+The Informer is the mechanism for watching Kubernetes object's event.
+When the Kubernetes objects changes(e.g. CREATE,UPDATE,DELETE), the `Event` object will create.
+The Informer lists and watches the object's changes through `Event` from the control plane.
+When the `Event` happens, the informer will watch it and store objects to the in-memory-cache.


Suggested change

The Informer is the mechanism for watching Kubernetes object's event.

When the Kubernetes objects changes(e.g. CREATE,UPDATE,DELETE), the `Event` object will create.

The Informer lists and watches the object's changes through `Event` from the control plane.

When the `Event` happens, the informer will watch it and store objects to the in-memory-cache.

The Informer is the mechanism for watching a Kubernetes object's event.

When the Kubernetes objects changes(e.g. CREATE,UPDATE,DELETE), the Informer is informed, and can execute a callback with the relevant object as an argument.

This can be very useful for building event based systems against the Kubernetes API.

Changed the wording here, since it's not an Event object - it's the actual resource object that comes through.

markmandel · 2022-05-20T22:27:32Z

site/content/en/docs/Guides/access-api.md

+The Lister is the mechanism for listing Kubernetes object's.
+Users can list the Kubernetes objects by using Kubernetes APIs, however,
+if users use List API, it causes the load for the control plane.
+The Informer stores the cache of the object to the in-memory-cache.
+If users use the in-memory-cache, the load can be avoidable.
+The Lister provides the list method while using the in-memory-cache.


Suggested change

The Lister is the mechanism for listing Kubernetes object's.

Users can list the Kubernetes objects by using Kubernetes APIs, however,

if users use List API, it causes the load for the control plane.

The Informer stores the cache of the object to the in-memory-cache.

If users use the in-memory-cache, the load can be avoidable.

The Lister provides the list method while using the in-memory-cache.

The Lister is the mechanism for querying Kubernetes object's against the client side in-memory cache.

Users can list the Kubernetes objects by using Kubernetes APIs, however,

if users do so, it places load on the Kubernetes control plane.

Since an Lister stores objects in an in-memory cache, queries against a come at practically no cost.

govargo · 2022-05-23T09:11:56Z

Thank you for your review.
It looks good explanation, so I adopted it.

Thank you!

agones-bot · 2022-05-23T09:34:33Z

Build Succeeded 👏

Build Id: 3b75e8a8-8664-473e-82bd-97659b1c5d7d

The following development artifacts have been built, and will exist for the next 30 days:

image: gcr.io/agones-images/agones-controller:1.24.0-426941f-amd64
image: gcr.io/agones-images/agones-controller:1.24.0-426941f-arm64
image: gcr.io/agones-images/agones-ping:1.24.0-426941f
Linux C++ SDK (build): agonessdk-1.24.0-426941f-linux-arch_64.tar.gz
SDK Server: agonessdk-server-1.24.0-426941f.zip

A preview of the website (the last 30 builds are retained):

https://426941f-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/2579/head:pr_2579 && git checkout pr_2579
helm install ./install/helm/agones --namespace agones-system --name agones --set agones.image.tag=1.24.0-426941f-amd64

markmandel

Just doing another read through - found some typos, and some places I think can be tightened up. Please take a look!

markmandel · 2022-05-23T23:05:01Z

site/content/en/docs/Guides/access-api.md

+reduce the performance of the cluster -- and Informers and Listers help resolving that issue.
+
+Informers and Listers reduce the load on the Kubernetes control plane
+by creating, using and maintaining and eventually consistent an in-memory-cache.


Suggested change

by creating, using and maintaining and eventually consistent an in-memory-cache.

by creating, using and maintaining an eventually consistent an in-memory cache.

markmandel · 2022-05-23T23:06:15Z

site/content/en/docs/Guides/access-api.md

+The Informer is the mechanism for watching a Kubernetes object's event.
+
+When the Kubernetes objects changes(e.g. CREATE,UPDATE,DELETE), the Informer is informed,
+and can execute a callback with the relevant object as an argument.


Suggested change

The Informer is the mechanism for watching a Kubernetes object's event.

When the Kubernetes objects changes(e.g. CREATE,UPDATE,DELETE), the Informer is informed,

and can execute a callback with the relevant object as an argument.

An Informer is the mechanism for watching a Kubernetes object's event, such that when an Kubernetes object changes(e.g. CREATE,UPDATE,DELETE), the Informer is informed,

and can execute a callback with the relevant object as an argument.

markmandel · 2022-05-23T23:08:02Z

site/content/en/docs/Guides/access-api.md

+The Lister is the mechanism for querying Kubernetes object's against the client side in-memory cache.
+Users can list the Kubernetes objects by using Kubernetes APIs, however,
+if users do so, it places load on the Kubernetes control plane.
+
+Since an Lister stores objects in an in-memory cache, queries against a come at practically no cost.


Suggested change

The Lister is the mechanism for querying Kubernetes object's against the client side in-memory cache.

Users can list the Kubernetes objects by using Kubernetes APIs, however,

if users do so, it places load on the Kubernetes control plane.

Since an Lister stores objects in an in-memory cache, queries against a come at practically no cost.

Listers are a mechanism for querying Kubernetes object's against the client side in-memory cache.

Since an Lister stores objects in an in-memory cache, queries against a come at practically no cost.

I don't think we need to repeat the issue with direct acess.

Changed from Listers are a mechanism to A Lister is the mechanism according to An Informer is the mechanism.

govargo · 2022-05-24T08:12:36Z

Updated again.

agones-bot · 2022-05-24T08:27:47Z

Build Failed 😱

Build Id: efff862b-33a0-4a06-9e59-2f4a329a31ff

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

govargo · 2022-05-25T02:58:49Z

This PR has only documentation changes, however, the test of go agones.dev/agones/pkg/gameservers failed due to timed out.

I0524 08:18:03.016986   16921 trace.go:205] Trace[1145578265]: "Reflector ListAndWatch" name:k8s.io/client-go/informers/factory.go:134 (24-May-2022 08:17:34.297) (total time: 28719ms):
Trace[1145578265]: [28.719005799s] [28.719005799s] END
panic: test timed out after 10m0s

/retest

I'd like to retest but it looks I don't have any way to retest...

markmandel · 2022-05-25T20:40:58Z

Sounds like a weird test flake - not related to your change.

markmandel · 2022-05-25T20:46:19Z

site/content/en/docs/Guides/access-api.md

+	informerFactory.Start(wait.NeverStop)
+	agonesInformerFactory.Start(wait.NeverStop)
+	// Wait until finish caching with List API
+	informerFactory.WaitForCacheSync(wait.NeverStop)
+	agonesInformerFactory.WaitForCacheSync(wait.NeverStop)


🤔 do we want to use wait.NeverStop here, or do we want to drive people towards what they probably should do - which is have a context.Context (maybe cancellable? Might not matter, could just use context.Background), and pass in ctx.Done() into each of these?

Since it's likely better practice to use a Context. WDYT?

Also /cc @roberthbailey in case he has opinions.

changed using context.Background.

agones-bot · 2022-05-26T07:55:57Z

Build Failed 😱

Build Id: 5842b71b-312b-4e68-b830-fdc9240a670a

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

google-oss-prow · 2022-05-26T15:41:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: govargo, markmandel

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~~ [markmandel]

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

google-oss-prow · 2022-05-26T15:42:51Z

New changes are detected. LGTM label has been removed.

agones-bot · 2022-05-26T16:07:11Z

Build Succeeded 👏

Build Id: b4d340c8-3c1b-439b-8cd9-90b26deb3597

The following development artifacts have been built, and will exist for the next 30 days:

image: gcr.io/agones-images/agones-controller:1.24.0-baabe5f-amd64
image: gcr.io/agones-images/agones-controller:1.24.0-baabe5f-arm64
image: gcr.io/agones-images/agones-ping:1.24.0-baabe5f
Linux C++ SDK (build): agonessdk-1.24.0-baabe5f-linux-arch_64.tar.gz
SDK Server: agonessdk-server-1.24.0-baabe5f.zip

A preview of the website (the last 30 builds are retained):

https://baabe5f-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/2579/head:pr_2579 && git checkout pr_2579
helm install ./install/helm/agones --namespace agones-system --name agones --set agones.image.tag=1.24.0-baabe5f-amd64

agones-bot · 2022-05-26T17:13:19Z

Build Failed 😱

Build Id: 19a5682b-1fb9-4bfe-8257-474e2c07cbda

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2022-05-26T18:10:17Z

Build Failed 😱

Build Id: d7cd938a-1e7c-4254-8b41-57af5b790b92

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2022-05-26T18:38:36Z

Build Succeeded 👏

Build Id: 02fca755-5a3f-4686-8b9e-64c48fb72728

The following development artifacts have been built, and will exist for the next 30 days:

image: gcr.io/agones-images/agones-controller:1.24.0-6eb149a-amd64
image: gcr.io/agones-images/agones-controller:1.24.0-6eb149a-arm64
image: gcr.io/agones-images/agones-ping:1.24.0-6eb149a
Linux C++ SDK (build): agonessdk-1.24.0-6eb149a-linux-arch_64.tar.gz
SDK Server: agonessdk-server-1.24.0-6eb149a.zip

A preview of the website (the last 30 builds are retained):

https://6eb149a-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/2579/head:pr_2579 && git checkout pr_2579
helm install ./install/helm/agones --namespace agones-system --name agones --set agones.image.tag=1.24.0-6eb149a-amd64

google-oss-prow bot added the size/L label May 14, 2022

google-oss-prow bot requested review from cyriltovena and roberthbailey May 14, 2022 07:30

google-oss-prow bot assigned pooneh-m May 14, 2022

markmandel reviewed May 20, 2022

View reviewed changes

markmandel reviewed May 23, 2022

View reviewed changes

markmandel reviewed May 25, 2022

View reviewed changes

Add Document about Informers and Listers

b859367

markmandel approved these changes May 26, 2022

View reviewed changes

google-oss-prow bot assigned markmandel May 26, 2022

google-oss-prow bot added the lgtm label May 26, 2022

google-oss-prow bot added the approved label May 26, 2022

Merge branch 'main' into add-doc-informer-lister

baabe5f

google-oss-prow bot removed the lgtm label May 26, 2022

Merge branch 'main' into add-doc-informer-lister

4f71f23

Merge branch 'main' into add-doc-informer-lister

6eb149a

markmandel merged commit 8062a04 into googleforgames:main May 26, 2022

markmandel added kind/feature New features for Agones kind/documentation Documentation for Agones labels May 26, 2022

markmandel added this to the 1.24.0 milestone May 26, 2022

govargo deleted the add-doc-informer-lister branch June 4, 2022 07:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Document about Informers and Listers #2579

Add Document about Informers and Listers #2579

govargo commented May 14, 2022

govargo commented May 14, 2022

agones-bot commented May 14, 2022

agones-bot commented May 14, 2022

markmandel left a comment

markmandel May 20, 2022

markmandel May 20, 2022

markmandel May 20, 2022

markmandel May 20, 2022

markmandel May 20, 2022

govargo commented May 23, 2022

agones-bot commented May 23, 2022

markmandel left a comment

markmandel May 23, 2022

markmandel May 23, 2022

markmandel May 23, 2022

govargo May 24, 2022

govargo commented May 24, 2022

agones-bot commented May 24, 2022

govargo commented May 25, 2022 •

edited

Loading

markmandel commented May 25, 2022

markmandel May 25, 2022

govargo May 26, 2022

agones-bot commented May 26, 2022

google-oss-prow bot commented May 26, 2022

google-oss-prow bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

	## What are Informers and Listers? How can I use these?
	## Best Practice: Using Informers and Listers

	by creating, using and maintaining and eventually consistent an in-memory-cache.
	by creating, using and maintaining an eventually consistent an in-memory cache.

Add Document about Informers and Listers #2579

Add Document about Informers and Listers #2579

Conversation

govargo commented May 14, 2022

govargo commented May 14, 2022

agones-bot commented May 14, 2022

agones-bot commented May 14, 2022

markmandel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

govargo commented May 23, 2022

agones-bot commented May 23, 2022

markmandel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

govargo commented May 24, 2022

agones-bot commented May 24, 2022

govargo commented May 25, 2022 • edited Loading

markmandel commented May 25, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agones-bot commented May 26, 2022

google-oss-prow bot commented May 26, 2022

google-oss-prow bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

agones-bot commented May 26, 2022

govargo commented May 25, 2022 •

edited

Loading