884: Cleanup examples folder

Author: Scott Lee

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
 
@@ -178,4 +178,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 how to use the Python client. Please
+read the description at the top of each script for more information about what
+it does and any prequisite steps. 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 via 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 renamed to 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 the 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/create_deployment.py renamed to examples/deployment_create.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/deployment_examples.py renamed to examples/deployment_crud.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/
+"""
+Showcases loading the Kubernetes config from within the 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 the 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/exec.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 within 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="/",