From dc1fcb877db878c57f4f02c40af7757d2f4e95f0 Mon Sep 17 00:00:00 2001 From: lrossett Date: May 03 2021 15:56:36 +0000 Subject: [PATCH 1/2] 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. From c455663d542c851f25b55398e3cbe968df06692c Mon Sep 17 00:00:00 2001 From: lrossett Date: May 06 2021 19:28:39 +0000 Subject: [PATCH 2/2] first commit --- diff --git a/Makefile b/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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 deleted file mode 100644 index 1cbe806..0000000 --- a/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Fedora KubeDev Onboarding - -An onboarding documentation repository written in sphinx. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/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/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1cbe806 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# Fedora KubeDev Onboarding + +An onboarding documentation repository written in sphinx. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/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/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..e8b7dc7 --- /dev/null +++ b/docs/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/docs/source/community.rst b/docs/source/community.rst new file mode 100644 index 0000000..fcbef3d --- /dev/null +++ b/docs/source/community.rst @@ -0,0 +1,30 @@ +Community +========= + +Communication +------------- + ++----------------+-------------------------------------------------------+ +| | Channels | ++================+=======================================================+ +| Wiki | `SIGs/KubeDev`_ | ++----------------+-------------------------------------------------------+ +| Issue Tracker | `kube-sig/fedora-messaging-pub-operator/issues`_ | ++----------------+-------------------------------------------------------+ +| IRC | `#fedora-kube`_ channel in the (`freenode`_) network. | ++----------------+-------------------------------------------------------+ +| Mailing List | `fedora-kube`_ (`subscribe`_) | ++----------------+-------------------------------------------------------+ + +.. _SIGs/KubeDev: https://fedoraproject.org/wiki/SIGs/KubeDev +.. _kube-sig/fedora-messaging-pub-operator/issues: https://pagure.io/kube-sig/fedora-messaging-pub-operator/issues +.. _#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/ + + +Contributing +------------ + +The operator's source code can be found at: `https://pagure.io/kube-sig/fedora-messaging-pub-operator `_. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..303d860 --- /dev/null +++ b/docs/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 Messaing Pub Operator' +copyright = '2021, 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/docs/source/deployment.rst b/docs/source/deployment.rst new file mode 100644 index 0000000..785e78c --- /dev/null +++ b/docs/source/deployment.rst @@ -0,0 +1,7 @@ +Deployment +========== + +NOTE: this document is a draft and may change during the course +of this project's development. + +TBD \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..951ac87 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +.. 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 Messaging Pub Operator'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: + + overview + deployment + usage + community + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..b220ab7 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,15 @@ +Overview +======== + +This is a kubernetes operator that will publish messages to fedora-messaging +based on CR creation. + +The operator will create a POD that will send the actual message and update +the CR status accordingly. + + +Status +------ + +This project is a **DRAFT**, which means only its documentation is about +how the project should behave and operate but no actual code was developed is available. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..bba4fdb --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,81 @@ +Usage +===== + +NOTE: this document is a draft and may change during the course +of this project's development. + +Requirements +------------ + +A secret is required in the following format: + +.. code-block:: yaml + + apiBersion: v1 + kind: Secret + metadata: + name: fedora-messaging + data: + # env: prod + # vhost: /pubsub + username: changeme + ca.pem: "" # contents of fedora-messaging CA file + cert.pem: "" # contents of fedora-messaging cert file + key.pem: "" # contents of fedora-messaging key file + +NOTE: Secret data needs to be encoded as base64 string. + +NOTE: Commented fields are optional and use those values by default. + +The Message Custom Resource +--------------------------- + +The following resource should be created to publish a message: + +.. code-block:: yaml + + apiVersion: apps.fedoraproject.org/v1alpha1 + kind: Message + metadata: + name: hello + spec: + # secretRef: + # name: fedora-messaging + # image: quay.io/fedora/fedora-messaging-sender:latest + topic: org.fedoraproject.prod.buildsys.tag + data: # data will be parsed to json + field: something + valid: true + users: ["user1", "user 2"] + +NOTE: Commented fields are optional and use those values by default. + + +This will result in a POD being created that will the send above message +definition and update the CR status accordingly: + +.. code-block:: yaml + + apiVersion: apps.fedoraproject.org/v1alpha1 + kind: Message + metadata: + name: hello + annotations: + # sender pod json definition + apps.fedoraproject.org/pod: "{}" + # sender pod id for convenience + apps.fedoraproject.org/pod/id: "" + status: + type: MessageSent + status: True + reason: Sent + message: The message was successfully sent + lastHeartbeatTime: 2006-01-02 15:04:05 + lastTransitionTime: 2006-01-02 15:04:05 + spec: + image: quay.io/fedora/fedora-messaging-sender:latest + topic: org.fedoraproject.prod.buildsys.tag + data: # data will be parsed to json + field: something + valid: true + users: ["user1", "user 2"] \ No newline at end of file diff --git a/make.bat b/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@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 deleted file mode 100644 index e8b7dc7..0000000 --- a/requirements.txt +++ /dev/null @@ -1,24 +0,0 @@ -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 deleted file mode 100644 index 7bb99e3..0000000 --- a/source/community.rst +++ /dev/null @@ -1,22 +0,0 @@ -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 deleted file mode 100644 index 25e47c6..0000000 --- a/source/conf.py +++ /dev/null @@ -1,65 +0,0 @@ -# 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 deleted file mode 100644 index f8e9879..0000000 --- a/source/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. 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 deleted file mode 100644 index 9f52d2e..0000000 --- a/source/local-env.rst +++ /dev/null @@ -1,37 +0,0 @@ -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 deleted file mode 100644 index af5a9c9..0000000 --- a/source/programming-kubernetes.rst +++ /dev/null @@ -1,90 +0,0 @@ -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 deleted file mode 100644 index ccf8c3d..0000000 --- a/source/references.rst +++ /dev/null @@ -1,9 +0,0 @@ -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 deleted file mode 100644 index e5314d0..0000000 --- a/source/samples.rst +++ /dev/null @@ -1,14 +0,0 @@ -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.