diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 5128596..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api/modules.rst b/docs/api/modules.rst deleted file mode 100644 index 5859c1d..0000000 --- a/docs/api/modules.rst +++ /dev/null @@ -1,18 +0,0 @@ -API Modules -=========== - -Pykube exports its main classes on the package level, so you can do: - -.. code-block:: python - - from pykube import KubeConfig, HTTPClient, Pod - -* :class:`KubeConfig ` is the main configuration class to load ``~/.kube/config`` or from in-cluster service account -* :class:`HTTPClient ` represents the Kubernetes API client -* Kubernetes resource kinds (:class:`Pod `, etc) are defined in :mod:`pykube.objects` - - -.. toctree:: - :maxdepth: 4 - - pykube diff --git a/docs/api/pykube.rst b/docs/api/pykube.rst deleted file mode 100644 index 6d5b046..0000000 --- a/docs/api/pykube.rst +++ /dev/null @@ -1,78 +0,0 @@ -pykube package -============== - -Submodules ----------- - -pykube.config module --------------------- - -.. automodule:: pykube.config - :members: - :undoc-members: - :show-inheritance: - -pykube.console module ---------------------- - -.. automodule:: pykube.console - :members: - :undoc-members: - :show-inheritance: - -pykube.exceptions module ------------------------- - -.. automodule:: pykube.exceptions - :members: - :undoc-members: - :show-inheritance: - -pykube.http module ------------------- - -.. automodule:: pykube.http - :members: - :undoc-members: - :show-inheritance: - -pykube.mixins module --------------------- - -.. automodule:: pykube.mixins - :members: - :undoc-members: - :show-inheritance: - -pykube.objects module ---------------------- - -.. automodule:: pykube.objects - :members: - :undoc-members: - :show-inheritance: - -pykube.query module -------------------- - -.. automodule:: pykube.query - :members: - :undoc-members: - :show-inheritance: - -pykube.utils module -------------------- - -.. automodule:: pykube.utils - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pykube - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 49c1d8e..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,104 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config -# -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath("../")) - -from pykube import __version__ # noqa: E402 - - -# -- Project information ----------------------------------------------------- - -project = "Pykube" -copyright = "2019, Henning Jacobs" -author = "Henning Jacobs" - -# The short X.Y version -version = __version__ -# The full version, including alpha/beta/rc tags -release = __version__ - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx_autodoc_annotation", - "sphinx.ext.viewcode", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - -# -- Extension configuration ------------------------------------------------- diff --git a/docs/howtos/access-service-with-api-proxy.rst b/docs/howtos/access-service-with-api-proxy.rst deleted file mode 100644 index 3f84274..0000000 --- a/docs/howtos/access-service-with-api-proxy.rst +++ /dev/null @@ -1,15 +0,0 @@ -======================= -How to access a Service -======================= - -To access the service defined with your ``Service`` object, you can use the HTTP proxy provided by the API server. -There are convenience methods to do ``GET``, ``POST``, ``PUT`` and ``DELETE`` and the generic ``proxy_http_request`` version, -where you can pass any HTTP verb. - -.. code-block:: python - - service = pykube.Service.objects(api).filter(namespace="default").get(name="test") - res = service.proxy_http_get("my/path") - assert res is not None - assert res.content == b"it works" - assert res.status_code == 200 diff --git a/docs/howtos/find-pods-by-label.rst b/docs/howtos/find-pods-by-label.rst deleted file mode 100644 index a6d52be..0000000 --- a/docs/howtos/find-pods-by-label.rst +++ /dev/null @@ -1,14 +0,0 @@ -How to find Pods by label -========================= - -This section explains how to find Kubernetes pods by a set of known labels. - -Calling :func:`objects ` on the :class:`Pod ` class returns a :class:`Query ` object which provides the :func:`filter ` method. -The ``selector`` parameter can take a dictionary of label names and values to filter by: - -.. code-block:: python - - for pod in Pod.objects(api).filter(namespace=pykube.all, selector={'app': 'myapp'}): - print(pod.namespace, pod.name) - -Note that the special value of ``pykube.all`` needs to be passed, otherwise it would only return pods in the current namespace (i.e. usually "default"). diff --git a/docs/howtos/index.rst b/docs/howtos/index.rst deleted file mode 100644 index 65b70d4..0000000 --- a/docs/howtos/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -How Tos -======= - -.. toctree:: - :maxdepth: 2 - :glob: - - * diff --git a/docs/howtos/print-container-logs.rst b/docs/howtos/print-container-logs.rst deleted file mode 100644 index 20bd1eb..0000000 --- a/docs/howtos/print-container-logs.rst +++ /dev/null @@ -1,27 +0,0 @@ -=========================== -How to print container logs -=========================== - -To print the most recent logs for multiple pods and containers, you can use the ``timestamps`` parameter and sort log lines afterwards. -Note that this will not work correctly if your container logs contain newlines! - -.. code-block:: python - - tail_lines = 100 - - logs = [] - - for pod in pods: - for container in pod.obj["spec"]["containers"]: - container_log = pod.logs( - container=container["name"], - timestamps=True, - tail_lines=tail_lines, - ) - for line in container_log.split("\n"): - logs.append(line) - - logs.sort() - - for log in logs: - print(log) diff --git a/docs/howtos/update-deployment-image.rst b/docs/howtos/update-deployment-image.rst deleted file mode 100644 index d4d0547..0000000 --- a/docs/howtos/update-deployment-image.rst +++ /dev/null @@ -1,19 +0,0 @@ -================================ -How to update a Deployment image -================================ - -To update the Docker image for an existing deployment: - -.. code-block:: python - - from pykube import Deployment, HTTPClient, KubeConfig - - new_docker_image = "hjacobs/kube-web-view" - - api = HTTPClient(KubeConfig.from_file()) - deploy = Deployment.objects(api).get(name="mydeploy") - deploy.obj["spec"]["template"]["spec"]["containers"][0]["image"] = new_docker_image - deploy.update() - -Note that the call to ``deploy.update()`` might fail if the resource was modified between loading and updating. -In this case you need to retry. diff --git a/docs/howtos/use-interactive-console.rst b/docs/howtos/use-interactive-console.rst deleted file mode 100644 index 7d59c56..0000000 --- a/docs/howtos/use-interactive-console.rst +++ /dev/null @@ -1,32 +0,0 @@ -How to use the Interactive Console -================================== - -Pykube can be started as an interactive Python console: - -.. code-block:: bash - - python3 -m pykube - -The interactive console automatically loads the Kubernetes configuration from the default location (``~/.kube/config``) and -provides the objects ``api`` and ``config``: - -.. code-block:: python - - >>> api - - - >>> config - - -All standard classes from :ref:`pykube-package` are automatically imported, so you can use them, e.g.: - -.. code-block:: python - - >>> for deploy in Deployment.objects(api): - ... print(f'{deploy.name}: {deploy.replicas}') - -You can also pass a Python command via the ``-c`` option for non-interactive usage: - -.. code-block:: bash - - python3 -m pykube -c 'print(config.current_context, api.version)' diff --git a/docs/howtos/write-an-operator.rst b/docs/howtos/write-an-operator.rst deleted file mode 100644 index 4f0d339..0000000 --- a/docs/howtos/write-an-operator.rst +++ /dev/null @@ -1,152 +0,0 @@ -How to write an Operator -======================== - -Pykube can be used to implement Kubernetes Operators. Here is how to write a very simple operator which adds a label ``foo`` with value ``bar`` to every deployment object which has the ``pykube-test-operator`` annotation: - -.. code-block:: python - - # simplified example script, no error handling! - import pykube, time - - while True: - # loads in-cluster auth or local ~/.kube/config for testing - config = pykube.KubeConfig.from_env() - api = pykube.HTTPClient(config) - for deploy in pykube.Deployment.objects(api, namespace=pykube.all): - if 'pykube-test-operator' in deploy.annotations: - print(f'Updating deployment {deploy.namespace}/{deploy.name}..') - deploy.labels['foo'] = 'bar' - deploy.update() - time.sleep(15) - -Save the above Python script as ``main.py``. - -Testing -------- - -You can now test the script locally with Pipenv_ and Minikube_ (run ``minikube start`` first): - -.. code-block:: bash - - pipenv install new-pykube - pipenv run python3 main.py - -See the operator in action by creating a deployment with the right annotation: - -.. code-block:: bash - - kubectl run nginx --image=nginx - kubectl annotate deploy nginx pykube-test-operator=true - -The operator should should now assign the ``foo`` label to the ``nginx`` deployment. - -Building the Docker image -------------------------- - -Create a ``Dockerfile`` in the same directory as ``main.py``: - -.. code-block:: Dockerfile - - FROM python:3.7-alpine3.10 - - WORKDIR / - - RUN pip3 install new-pykube - - COPY main.py / - - ENTRYPOINT ["python3", "main.py"] - -Now build it: - -.. code-block:: bash - - docker build -t pykube-test-operator . - -You need to push the Docker image to some Docker registry before you can deploy it. - - -Deployment ----------- - -Now deploy the Docker image to your Kubernetes cluster using a service account with the necessary permissions (in this case to list and update deployments). -To create such an service account with the necessary RBAC rights create ``rbac.yaml`` with these contents: - -.. code-block:: yaml - - apiVersion: v1 - kind: ServiceAccount - metadata: - name: pykube-test-operator - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: pykube-test-operator - rules: - - apiGroups: - - apps - resources: - - deployments - verbs: - - get - - watch - - list - - update - - patch - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: pykube-test-operator - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: pykube-test-operator - subjects: - - kind: ServiceAccount - name: pykube-test-operator - namespace: default - -Apply the RBAC role via ``kubectl apply -f rbac.yaml``. - -Finally, the deployment of the operator would then look like (``deployment.yaml``): - -.. code-block:: yaml - - apiVersion: apps/v1 - kind: Deployment - metadata: - name: pykube-test-operator - spec: - replicas: 1 - selector: - matchLabels: - app: pykube-test-operator - template: - metadata: - labels: - app: pykube-test-operator - spec: - serviceAccountName: pykube-test-operator - containers: - - name: operator - # this image needs have been pushed to some Docker registry! - image: pykube-test-operator - resources: - limits: - memory: 50Mi - requests: - cpu: 5m - memory: 50Mi - securityContext: - readOnlyRootFilesystem: true - runAsNonRoot: true - runAsUser: 1000 - -Create the deployment via ``kubectl apply -f deployment.yaml``. - -You should now have a working operator deployment in your cluster. - -.. _Pipenv: https://pipenv.readthedocs.io/en/latest/ -.. _Minikube: https://github.com/kubernetes/minikube diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 3e0a1f3..0000000 --- a/docs/readme.rst +++ /dev/null @@ -1,56 +0,0 @@ -Pykube -====== - -.. image:: https://img.shields.io/pypi/v/new-pykube.svg - :target: https://pypi.python.org/pypi/new-pykube/ - -.. image:: https://img.shields.io/pypi/pyversions/new-pykube.svg - :target: https://pypi.python.org/pypi/new-pykube/ - -.. image:: https://img.shields.io/badge/license-apache-blue.svg - :target: https://pypi.python.org/pypi/new-pykube/ - -Pykube (new-pykube) is a lightweight Python 3+ client library for Kubernetes. - -Installation ------------- - -To install pykube, use pip:: - - pip install new-pykube - -Usage ------ - -Query for all ready pods in a custom namespace: - -.. code:: python - - import operator - import pykube - - api = pykube.HTTPClient(pykube.KubeConfig.from_file()) - pods = pykube.Pod.objects(api).filter(namespace="gondor-system") - ready_pods = filter(operator.attrgetter("ready"), pods) - -Documentation -------------- - -.. toctree:: - :maxdepth: 2 - :glob: - - howtos/index - api/modules - README - changelog - users - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 6b17d1f..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -# duplicate necessary dependencies to import pykube module (for autodoc) -requests -PyYAML -sphinx-autodoc-annotation