Merge pull request #938 from scottilee/examples

#884: Cleanup examples folder

README.md

@@ -68,7 +68,7 @@ More examples can be found in [examples](examples/) folder. To run examples, run
 python -m examples.example1
 ```
 
-(replace example1 with the example base filename)
+(replace example1 with one of the filenames in the examples folder)
 
 ## Documentation
 
@@ -166,4 +166,4 @@ Specifically check `ipaddress` and `urllib3` package versions to make sure they
 
 Starting from 4.0 release, we do not support directly calling exec or attach calls. you should use stream module to call them. so instead
 of `resp = api.connect_get_namespaced_pod_exec(name, ...` you should call `resp = stream(api.connect_get_namespaced_pod_exec, name, ...`.
-See more at [exec example](examples/exec.py).
+See more at [exec example](examples/pod_exec.py).

examples/README.md

@@ -0,0 +1,17 @@
+# Python Client Examples
+
+This directory contains various examples of how to use the Python client.
+Please read the description at the top of each example for more information
+about what the script does and any prequisites. Most scripts also include
+comments throughout the code.
+
+## Setup
+
+These scripts require Python 2.7 or 3.5+ and the Kubernetes client which can be
+installed following the directions
+[here](https://github.com/kubernetes-client/python#installation).
+
+## Contributions
+
+If you find a problem please file an
+[issue](https://github.com/kubernetes-client/python/issues).

examples/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Empty init file to make examples folder a python module.
+# Empty init file to make examples folder a python module

examples/example3.py → examples/api_discovery.py

@@ -12,6 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Reads the list of available API versions and prints them. Similar to running
+`kubectl api-versions`.
+"""
+
 from kubernetes import client, config
 
 

examples/custom_object.py

@@ -12,37 +12,38 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This example use an example CRD from this tutorial:
-# https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
-#
-# The following yaml manifest has to be applied first:
-#
-# apiVersion: apiextensions.k8s.io/v1beta1
-# kind: CustomResourceDefinition
-# metadata:
-#   name: crontabs.stable.example.com
-# spec:
-#   group: stable.example.com
-#   versions:
-#     - name: v1
-#       served: true
-#       storage: true
-#   scope: Namespaced
-#   names:
-#     plural: crontabs
-#     singular: crontab
-#     kind: CronTab
-#     shortNames:
-#     - ct
+"""
+Uses a Custom Resource Definition (CRD) to create a custom object, in this case
+a CronTab. This example use an example CRD from this tutorial:
+https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
 
+The following yaml manifest has to be applied first:
+
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: crontabs.stable.example.com
+spec:
+  group: stable.example.com
+  versions:
+    - name: v1
+      served: true
+      storage: true
+  scope: Namespaced
+  names:
+    plural: crontabs
+    singular: crontab
+    kind: CronTab
+    shortNames:
+    - ct
+"""
 
 from pprint import pprint
 
 from kubernetes import client, config
 
 
 def main():
-
     config.load_kube_config()
 
     api = client.CustomObjectsApi()

examples/deployment_examples.py → examples/deployment_crud.py

@@ -13,8 +13,7 @@
 # limitations under the License.
 
 """
-This example shows how to work with AppsV1Api to create, modify and delete
-deployments
+Creates, updates, and deletes a deployment using AppsV1Api.
 """
 
 from kubernetes import client, config

examples/in_cluster_config.py

@@ -12,47 +12,46 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Simple example to show loading config from the cluster
-#
-# It works only from a pod. You can start an image with Python
-# (for example python:latest), exec into the pod, install the library,
-# then try out this example.
-#
-# If you get 403 errors from API server you will have to configure
-# RBAC to add the permission to list pods.
-#
-# ---
-# kind: ClusterRole
-# apiVersion: rbac.authorization.k8s.io/v1
-# metadata:
-#   name: pods-list
-# rules:
-# - apiGroups: [""]
-#   resources: ["pods"]
-#   verbs: ["list"]
-# ---
-# kind: ClusterRoleBinding
-# apiVersion: rbac.authorization.k8s.io/v1
-# metadata:
-#   name: pods-list
-# subjects:
-# - kind: ServiceAccount
-#   name: default
-#   namespace: default
-# roleRef:
-#   kind: ClusterRole
-#   name: pods-list
-#   apiGroup: rbac.authorization.k8s.io
-# ---
-#
-# Doc: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
+"""
+Shows how to load a Kubernetes config from within a cluster. This script
+must be run within a pod. You can start a pod with a Python image (for
+example, `python:latest`), exec into the pod, install the library, then run
+this example.
+
+If you get 403 errors from the API server you will have to configure RBAC to
+add permission to list pods by applying the following manifest:
+
+---
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: pods-list
+rules:
+- apiGroups: [""]
+  resources: ["pods"]
+  verbs: ["list"]
+
+---
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: pods-list
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: default
+roleRef:
+  kind: ClusterRole
+  name: pods-list
+  apiGroup: rbac.authorization.k8s.io
+
+Documentation: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
+"""
 
 from kubernetes import client, config
 
 
 def main():
-
-    # it works only if this script is run by K8s as a POD
     config.load_incluster_config()
 
     v1 = client.CoreV1Api()

examples/ingress-example.py → examples/ingress_create.py

@@ -12,6 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Creates deployment, service, and ingress objects. The ingress allows external
+network access to the cluster.
+"""
+
 from kubernetes import client, config
 
 
@@ -73,7 +78,7 @@ def create_ingress(networking_v1_beta1_api):
         }),
         spec=client.NetworkingV1beta1IngressSpec(
             rules=[client.NetworkingV1beta1IngressRule(
-                host="boddulabs.com",
+                host="example.com",
                 http=client.NetworkingV1beta1HTTPIngressRuleValue(
                     paths=[client.NetworkingV1beta1HTTPIngressPath(
                         path="/",

examples/job_examples.py → examples/job_crud.py

@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Creates, updates, and deletes a job object.
+"""
+
 from os import path
 
 import yaml
@@ -46,7 +50,6 @@ def create_job_object():
 
 
 def create_job(api_instance, job):
-    # Create job
     api_response = api_instance.create_namespaced_job(
         body=job,
         namespace="default")
@@ -56,7 +59,6 @@ def create_job(api_instance, job):
 def update_job(api_instance, job):
     # Update container image
     job.spec.template.spec.containers[0].image = "perl"
-    # Update the job
     api_response = api_instance.patch_namespaced_job(
         name=JOB_NAME,
         namespace="default",
@@ -65,7 +67,6 @@ def update_job(api_instance, job):
 
 
 def delete_job(api_instance):
-    # Delete job
     api_response = api_instance.delete_namespaced_job(
         name=JOB_NAME,
         namespace="default",

examples/multiple_clusters.py

@@ -12,14 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Allows you to pick a context and then lists all pods in the chosen context.
+
+Please install the pick library before running this example.
+"""
+
 from kubernetes import client, config
-# install pick using "pip install pick". It is not included
-# as a dependency because it only used in examples
-from pick import pick
+from kubernetes.client import configuration
+from pick import pick  # install pick using `pip install pick`
 
 
 def main():
-
     contexts, active_context = config.list_kube_config_contexts()
     if not contexts:
         print("Cannot find any context in kube-config file.")