kubernetes-client / kubernetes-client/python
Documentation creates steep learning curve.
- Dominant language
- Python
- Stars
- 7.7k
- Forks
- 3.5k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 18
Description
My guess is that most of those who use settle on python as their k8s client are doing so due to python being their dominant language. The clean programming pattern for this client appears to be relying on the structs of each component needed to build request bodies and not combining structs with python dicts to generate requests. There are a lot of structs to choose from. Point being: the pythonic way of implementing the client is not necessarily obvious and users can benefit from documentation that points them to a clean programming pattern.
My request is to break out documentation into a similar format to k8s concepts docs https://kubernetes.io/docs/concepts/ and subtopic the same resources and have tutorials to manage said resources. As an example:
If I were looking to use the python client to create a job programmatically, I could navigate to:
```
Workloads
|___Controllers
|___ Jobs
```
Where there is a clean tutorial that can show you how to build a job using only the structs required.
For example, to build the jobs in the k8s documentation https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
```
apiVersion: batch/v1
kind: Job
metadata:
name: pi
spec:
template:
spec:
containers:
- name: pi
image: perl
command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: Never
backoffLimit: 4
```
The tutorial can show code like so:
```
from kubernetes import client
container = client.V1Container(name="pi")
container.image = "perl"
container.command = ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
temp_spec = client.V1PodSpec(containers=[container])
temp_spec.restart_policy = "Never"
template = client.V1beta1JobTemplateSpec()
template.spec = temp_spec
spec = client.V1JobSpec(template=template)
spec.backoff_limit = 4
job = client.V1Job()
job.spec = spec
meta = client.V1ObjectMeta()
meta.name = "pi"
job.metadata = meta
```
Contributor guide
Research direction
Start by reviewing the Kubernetes concepts documentation and the Python client’s existing documentation structure. Use the Jobs example in the issue as the first tutorial target, documenting the required client structs and the resource hierarchy. Done means users can find a Job tutorial and follow it to construct the shown resource.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100