What am I missing in reading documentation?

Kubernetes
#1

Hello people! I am preparing to CKA exam and frustrate around fast search in documentation. I don’t understand is it me doing something wrong, is it common knowledge that I have to know or is it a bad documentation everywhere around??

Example of my latest frustration. I had a task to upgrade helm chart and I don’t remember the syntax.
I’ve decided to check help. And I see:

helm upgrade --help
....
Usage:
  helm upgrade [RELEASE] [CHART] [flags]
....

Then it describes a ton of flags but never explains what is RELEASE and CHART are supposed to be. Examples don’t always help me guess it as well.

In real life I would ask A.I. or google.
How am I supposed guess it?

Please share your tips.

#2

It always helps to read through the fantastic manual first and work in labs to understand the capabilities of the tool.

This gives you some context on what you can do with the tool.
Then --help, when piped to grep -i becomes a lifesaver.

#3

It doesn’t give me any clarity.
This site is the copy of the same documentation and it also doesn’t explain what is RELEASE and what is CHART.
So it remains unclear how to find this kind of info quickly during exam unless I memorize by rote all their terminology from every technology they expect me to know during exam which I find a waste of time and polluting my memory because it changes quickly.

#4

The help utility is a way of prompting your memory, but it isn’t a detailed description of how an API works. You get that context by following the lectures a bit, and doing things like using help and API docs during your labs, to familiarize yourself with what’s in those resources.

For your specific example, you can also use the course notes, which have a pretty good explanation of what the various arguments used in helm are:

  • a “release” is a label you give to an install on your cluster.
  • a “chart” is a reference to a chart that’s either part of a repo you installed with “helm repo add”, an OCI reference (a standalone sort of URL that points to a chart on the web), or a chart that’s sitting on a directory on disk. As an example from the upgrade command (this is in the notes page):
$ helm upgrade nginx-release bitnami/nginx
Release "nginx-release" has been upgraded. Happy Helming!
NAME: nginx-release
LAST DEPLOYED: Mon Nov 15 19:25:55 2021
NAMESPACE: default
STATUS: deployed
REVISION: 2
TEST SUITE: None
NOTES:
CHART NAME: nginx
CHART VERSION: 9.5.13
APP VERSION: 1.21.4

“nginx-release” is the release, and is the label that was used to mark the install of nginx when it was made to the cluster. “bitnami/nginx” is the nginx install that’s part of a repo that was added with the label “bitnami”.

Reviewing the lectures in the helm section should help you get these terms straight in your mind, which will help you make better use of the docs.

#5

you see, it is not intuitive to construct bitnami/nginx.
I cannot find this string in

helm list

but why not? it gives me the list of installed releases and i want to upgrade a release, correct?
It should be possible to get required info from helm release commands.

I should look for bitnami in
“helm repo list”
then put ‘/’ and then add CHART column from helm list and remove version from it because it is not really part of CHART. How am I gonna guess it if I didn’t google it outside of their docs?

I don’t understand their logic, too bad they believe it is obvious. Definitely they should make their CLI more consistent and improve explanations. They should get inspired by consistency and order of kubectl command

Also sad, that it is the only source we are allowed on the exam and it is added into exam while having such a poor user experience.

Sorry for this rant.

#6

It’s not surprising that “bitnami/nginx” is not listed in “helm list” – it’s not a release. It’s a package designation. You can run

“helm repo search nginx” to get that information:

controlplane ~ ➜  helm repo add bitnami https://charts.bitnami.com/bitnami
"bitnami" has been added to your repositories

controlplane ~ ➜  helm repo ls
NAME    URL                               
bitnami https://charts.bitnami.com/bitnami

controlplane ~ ➜  helm search repo nginx
NAME                                    CHART VERSION   APP VERSION     DESCRIPTION                                       
bitnami/nginx                           25.1.11         1.31.5          NGINX Open Source is a web server that can be a...
bitnami/nginx-ingress-controller        12.0.7          1.13.1          NGINX Ingress Controller is an Ingress controll...
bitnami/nginx-intel                     2.1.15          0.4.9           DEPRECATED NGINX Open Source for Intel is a lig...

Here the course’s lectures and labs can help you – they give you survey of how the API works so that you have a better idea how to navigate the docs. Knowing what the different CLI commands do in general helps you better find the specifics in the docs or via the help commands of the CLI itself. This is certainly true of helm, but it’s true of most K8s APIs too.

1 Like