From dc1fcb877db878c57f4f02c40af7757d2f4e95f0 Mon Sep 17 00:00:00 2001 From: lrossett Date: May 03 2021 15:56:36 +0000 Subject: first commit --- diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..417d0fb --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +build/ +venv/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..0acb29d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: source/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.6 + install: + - requirements: requirements.txt \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# 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) diff --git a/README.md b/README.md new file mode 100644 index 0000000..1cbe806 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# Fedora KubeDev Onboarding + +An onboarding documentation repository written in sphinx. diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@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 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e8b7dc7 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,24 @@ +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 diff --git a/source/community.rst b/source/community.rst new file mode 100644 index 0000000..7bb99e3 --- /dev/null +++ b/source/community.rst @@ -0,0 +1,22 @@ +Community +========= + +Communication +------------- + ++----------------+-------------------------------------------------------+ +| | Channels | ++================+=======================================================+ +| Wiki | `SIGs/KubeDev`_ | ++----------------+-------------------------------------------------------+ +| IRC | `#fedora-kube`_ channel in the (`freenode`_) network. | ++----------------+-------------------------------------------------------+ +| Mailing List | `fedora-kube`_ (`subscribe`_) | ++----------------+-------------------------------------------------------+ + +.. _SIGs/KubeDev: https://fedoraproject.org/wiki/SIGs/KubeDev +.. _#fedora-kube: https://webchat.freenode.net/?channels=fedora-kube +.. _freenode: http://freenode.net/ +.. _fedora-kube: https://lists.fedoraproject.org/archives/list/kube@lists.fedoraproject.org/ +.. _subscribe: https://lists.fedoraproject.org/admin/lists/kube.lists.fedoraproject.org/ + diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..25e47c6 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,65 @@ +# 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'] \ No newline at end of file diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 0000000..f8e9879 --- /dev/null +++ b/source/index.rst @@ -0,0 +1,26 @@ +.. 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 + community + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/source/local-env.rst b/source/local-env.rst new file mode 100644 index 0000000..9f52d2e --- /dev/null +++ b/source/local-env.rst @@ -0,0 +1,37 @@ +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). \ No newline at end of file diff --git a/source/programming-kubernetes.rst b/source/programming-kubernetes.rst new file mode 100644 index 0000000..af5a9c9 --- /dev/null +++ b/source/programming-kubernetes.rst @@ -0,0 +1,90 @@ +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. diff --git a/source/references.rst b/source/references.rst new file mode 100644 index 0000000..ccf8c3d --- /dev/null +++ b/source/references.rst @@ -0,0 +1,9 @@ +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/ diff --git a/source/samples.rst b/source/samples.rst new file mode 100644 index 0000000..e5314d0 --- /dev/null +++ b/source/samples.rst @@ -0,0 +1,14 @@ +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.