+ build/

+ venv/

+ # Minimal makefile for Sphinx documentation

+ #

+ 

+ # You can set these variables from the command line, and also

+ # from the environment for the first two.

+ SPHINXOPTS    ?=

+ SPHINXBUILD   ?= sphinx-build

+ SOURCEDIR     = source

+ 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)

+ # Fedora KubeDev Onboarding

+ An onboarding documentation repository written in sphinx.

+ @ECHO OFF

+ 

+ pushd %~dp0

+ 

+ REM Command file for Sphinx documentation

+ 

+ if "%SPHINXBUILD%" == "" (

+ 	set SPHINXBUILD=sphinx-build

+ )

+ set SOURCEDIR=source

+ set BUILDDIR=build

+ 

+ if "%1" == "" goto help

+ 

+ %SPHINXBUILD% >NUL 2>NUL

+ if errorlevel 9009 (

+ 	echo.

+ 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

+ 	echo.installed, then set the SPHINXBUILD environment variable to point

+ 	echo.to the full path of the 'sphinx-build' executable. Alternatively you

+ 	echo.may add the Sphinx directory to PATH.

+ 	echo.

+ 	echo.If you don't have Sphinx installed, grab it from

+ 	echo.http://sphinx-doc.org/

+ 	exit /b 1

+ )

+ 

+ %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+ goto end

+ 

+ :help

+ %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+ 

+ :end

+ popd

+ alabaster==0.7.12

+ Babel==2.9.0

+ certifi==2020.12.5

+ chardet==4.0.0

+ docutils==0.16

+ idna==2.10

+ imagesize==1.2.0

+ Jinja2==2.11.2

+ MarkupSafe==1.1.1

+ packaging==20.8

+ Pygments==2.7.3

+ pyparsing==2.4.7

+ pytz==2020.5

+ requests==2.25.1

+ snowballstemmer==2.0.0

+ Sphinx==3.4.1

+ sphinx-rtd-theme==0.5.0

+ sphinxcontrib-applehelp==1.0.2

+ sphinxcontrib-devhelp==1.0.2

+ sphinxcontrib-htmlhelp==1.0.3

+ sphinxcontrib-jsmath==1.0.1

+ sphinxcontrib-qthelp==1.0.3

+ sphinxcontrib-serializinghtml==1.1.4

+ urllib3==1.26.2

+ # Configuration file for the Sphinx documentation builder.

+ #

+ # This file only contains a selection of the most common options. For a full

+ # list see the documentation:

+ # https://www.sphinx-doc.org/en/master/usage/configuration.html

+ 

+ # -- 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('.'))

+ import sphinx_rtd_theme

+ 

+ 

+ # -- Project information -----------------------------------------------------

+ 

+ project = 'Fedora KubeDev SIG'

+ copyright = '2020, Leonardo Rossetti'

+ author = 'Leonardo Rossetti'

+ 

+ # The full version, including alpha/beta/rc tags

+ release = '0.1.0'

+ 

+ 

+ # -- General configuration ---------------------------------------------------

+ 

+ # 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_rtd_theme",

+ ]

+ 

+ # Add any paths that contain templates here, relative to this directory.

+ templates_path = ['_templates']

+ 

+ # 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 = []

+ 

+ 

+ # -- 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'

+ 

+ html_theme_options = {

+     'collapse_navigation': True,

+     'sticky_navigation': True,

+     'navigation_depth': -1,

+     'includehidden': True,

+     'titles_only': False

+ }

+ 

+ # 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'] 

+ .. Fedora KubeDev documentation master file, created by

+    sphinx-quickstart on Fri Dec 25 10:50:49 2020.

+    You can adapt this file completely to your liking, but it should at least

+    contain the root `toctree` directive.

+ 

+ Welcome to Fedora KubeDev's documentation!

+ ==========================================

+ 

+ This documentation has the purpose of being a "getting started" guide for those

+ interested in extending or building software on top of Kubernetes.

+ 

+ .. toctree::

+    :caption: Contents:

+ 

+    local-env

+    programming-kubernetes

+    samples

+    references

+ 

+ 

+ 

+ Indices and tables

+ ==================

+ 

+ * :ref:`genindex`

+ * :ref:`modindex`

+ * :ref:`search`

+ Local Environment

+ =================

+ 

+ The most basic tooling needed for running kubernetes locally is minikube and kubectl, both are upstream Google projects.

+ 

+ Minikube

+ --------

+ 

+ Upstream Documentation: https://minikube.sigs.k8s.io/docs/start/

+ 

+ Minikube is a tool which enables you to run a single kubernetes node locally, usually isolated in a VM, but it can run in a container runtime as well.

+ 

+ There is no minikube RPM in fedora repositories but we have an open issue to work on it if you are interested: https://pagure.io/kube/fedora-kube/issue/1

+ 

+ Minkube has a few configuration paramaters which can be listed by running ``minikube config``.

+ 

+ It is a good idea to set the following if you want to:

+ 

+ * driver: sets the default driver to run minikube: ``minikube config set driver kvm2`` (vm-driver still works but it is outdated)

+ * cpus: the amount of CPUs for minikube to use: ``minikube config set cpus 4``

+ * memory: the amount of available memory in the instance/VM (Mbs): ``minikube config set memory 4000``

+ * storage: the amount of available storage: ``minikube config set storage 100GB``

+ 

+ There is a known issue where a pod won't be able to reach its own service by using the service name but there is a manual fix for it:

+ 

+ .. code-block:: bash

+ 

+   minikube ssh

+   sudo ip link set docker0 promisc on

+ 

+ 

+ KubeCTL

+ -------

+ 

+ KubeCTL is the kubernetes CLI tool to interact with a kubernetes cluster, you can download it from the upstream kubernetes website: https://kubernetes.io/docs/tasks/tools/install-kubectl/

+ 

+ You tell kubetl which configfile to use by changing the value of the `KUBECONFIG` env var, it will use `$HOME/.kube.config` if this env variable is not set (minikube will update your default config file with the proper url/credentials). 

+ Programming Kubernetes

+ ======================

+ 

+ Kubernetes Rest API

+ -------------------

+ 

+ Kubernetes has a REST API which can be used when creating tooling to work with Kubernetes.

+ 

+ Authentication

+ ^^^^^^^^^^^^^^

+ 

+ The following command will retrieve the token from service account in the "default" namespace:

+ 

+ .. code-block:: bash

+ 

+   $ kubectl get secrets -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='default')].data.token}"|base64 --decode

+ 

+ 

+ That token can be used in HTTP requests by using it as a bearer token:

+ 

+ .. code-block:: bash

+ 

+   $ export TOKEN=$(kubectl get secrets -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='default')].data.token}"|base64 --decode)

+   $ curl -X GET https://$API_SERVER_HOST:$API_SERVER_PORT/api --header "Authorization: Bearer $TOKEN" --insecure

+ 

+ 

+ Listing all pods from the default namespace:

+ 

+ .. code-block:: bash

+ 

+   $ curl \

+   -k \

+   -X GET \

+   --header "Authorization: Bearer $TOKEN" \

+   https://$API_SERVER_HOST/api/v1/namespaces/default/pods

+ 

+ You can list all availables openapi methods by running:

+ 

+ .. code-block:: bash

+ 

+   $ curl \

+   -k \

+   -X GET \

+   --header "Authorization: Bearer $TOKEN" \

+   https://$API_SERVER_HOST/openapi/v2

+ 

+ 

+ The PATH format follow the following criteria: /api/v1/namespaces/$NAMESPACE/$GROUP/$VERSION/$KIND (both $GROUP nd $VERSION can be omitted if it is a "core" component such as a `pod`).

+ 

+ 

+ When send POST data for a given resource, such as creating a POD, all you need to do is to transform the YAML resource definiton into json and send it in a POST request.

+ 

+ Kubernetes Controllers

+ ----------------------

+ 

+ The Operator SDK

+ ^^^^^^^^^^^^^^^^

+ 

+ URL: https://sdk.operatorframework.io/

+ 

+ The Operator SDK is a tool created and maintained by the CoreOS team.

+ 

+ The SDK faciliates the development of a custom kubernetes controller, including CRD management.

+ 

+ The SDK will create a pre-defined project structure for your operator (controller) and any CRD.

+ 

+ The Status Sub-Resource

+ ^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ You will notice that either your operator code or your CRDs will refer to the CR "status" as a sub-resource.

+ 

+ This means that the user provisioning that particular CR won't be able to change the CR status, just the `spec`.

+ 

+ This is done this way so the status can only be changed by the operator (kuberntes will return an permission error if the user tries to change it).

+ 

+ This way the CR `spec` is where the user should input data while the CR `status` is where the operator should write its data based on what's happenning the reconcile loop for that CR.

+ 

+ There are a few recommendations on what properties should be used in the `status` object from the upstream kubernetes community that is worth reading: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

+ 

+ 

+ KubeCTL Plugins

+ ---------------

+ 

+ URL: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/

+ 

+ One can also create kubectl CLI plugins, this is useful in case you want to wrap a particular kubernetes integration in kubectl.

+ 

+ A plugin can be written in any languague as long as it can be executed (such as added in your `PATH`) and uses the following name format: `kubectl-$plugin-subcommand`.

+ 

+ Kubernetes will run `kubectl-$plugin-subcommand` when invoked as `kubectl $plugin-subcommand`, forwarding all arguments that were provided by the user.

+ References

+ ==========

+ 

+ - Kubernetes Basics: https://kubernetes.io/docs/tutorials/kubernetes-basics/

+ - KubeCTL: https://kubernetes.io/docs/tasks/tools/install-kubectl/

+ - Minikube: https://minikube.sigs.k8s.io/docs/start/

+ - Kubernetes API Conventions: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md

+ - Operator SDK Docs: https://sdk.operatorframework.io/

+ - KubeCTL Plugins: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/

+ Samples

+ =======

+ 

+ Sample projects for learning purposes.

+ 

+ Telegram Operator

+ -----------------

+ 

+ URL: https://github.com/odra/telegram-operator

+ 

+ A simple operator that sends a message to a channel using Telegram's bot API.

+ 

+ It will create a pod, mounting a secret as environment variables to send the message for each

+ created custom resource, uptating the custom resource status accordingly.