commit 660a143774615b21af50ff7c167285ff13195ed4
parent 115006ccc03fad74cea22f18498cef3e98c78450
Author: MTRNord <mtrnord1@gmail.com>
Date: Fri, 8 Nov 2024 23:28:21 +0100
Use arara and lualatex and cleanup file slightly
Diffstat:
7 files changed, 413 insertions(+), 70 deletions(-)
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -13,13 +13,18 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- - name: Compile LaTeX document
- uses: xu-cheng/latex-action@v3
+ - name: Install texlive
+ run: sudo apt install -y texlive-full
+ - uses: actions/setup-java@v4
with:
- root_file: root.tex
- latexmk_use_xelatex: true
- latexmk_shell_escape: true
+ distribution: 'graalvm' # See 'Supported distributions' for available options
+ java-version: '21'
+ - name: Compile arara
+ run: ./compile.sh
+ - name: Compile LaTeX document
+ run: ./build.sh
- uses: actions/upload-artifact@v4
+ working-directory: build
with:
name: pdf
path: |
@@ -28,18 +33,31 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- - uses: docker://pandoc/core:3.5
+ - uses: actions/setup-java@v4
with:
- args: "-s root.tex -o root.md"
+ distribution: 'graalvm' # See 'Supported distributions' for available options
+ java-version: '21'
+ - name: Compile arara
+ run: ./compile.sh
- name: Install texlive
run: sudo apt install -y texlive-full
+ - name: Compile LaTeX document
+ run: ./build.sh
+ - uses: docker://pandoc/core:3.5
+ working-directory: build
+ with:
+ args: "-s root.tex -o root.md"
- name: Run make4ht
+ working-directory: build
run: make4ht -s -u -x --format odt --loglevel info -e build.mk4 root.tex || exit 0
- name: Install libreoffice
+ working-directory: build
run: sudo apt install -y libreoffice
- name: Convert to docx
+ working-directory: build
run: soffice --convert-to docx root.odt
- uses: actions/upload-artifact@v4
+ working-directory: build
with:
name: pandoc
path: |
diff --git a/.gitignore b/.gitignore
@@ -317,3 +317,6 @@ root.docx
*.odt
*.tmp
*.css
+
+build/
+arara/
diff --git a/bibliography.bib b/bibliography.bib
@@ -1,20 +1,25 @@
-@online{helm,
- title = {The Helm Webpage},
- urldate = {2024-10-24},
- url = {https://helm.sh},
- %shorthand={helm},
+@online{helmauthorsHelm,
+ title = {Helm},
+ author = {{Helm Authors} and {The Linux Foundation}},
+ url = {https://helm.sh/},
+ urldate = {2024-10-25},
+ abstract = {Helm - The Kubernetes Package Manager.},
+ langid = {english},
}
-@online{helm:functions_and_pipelines,
- title = {Template Functions and Pipelines},
- urldate = {2024-10-24},
+@online{helmauthorsTemplateFunctionsPipelines,
+ title = {Template {{Functions}} and {{Pipelines}}},
+ author = {{Helm Authors} and {The Linux Foundation}},
url = {https://helm.sh/docs/chart_template_guide/functions_and_pipelines/},
- %shorthand={helm functions and pipelines},
-}
+ urldate = {2024-10-25},
+ langid = {english},
+}
-@online{go_template,
- title = {Go "template" Standard Library},
- urldate = {2024-10-24},
+@online{thegoauthorsTemplatePackageText,
+ type = {documentation},
+ title = {Template Package - Text/Template - {{Go Packages}}},
+ author = {{The Go Authors}},
url = {https://pkg.go.dev/text/template},
- %shorthand={go template},
-}
-\ No newline at end of file
+ urldate = {2024-10-25},
+ langid = {english},
+}
diff --git a/build.sh b/build.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+
+rm -r build
+mkdir -p build
+cp root.tex build/root.tex
+cp bibliography.bib build/bibliography.bib
+cp style.sty build/style.sty
+
+pushd build
+java -jar ../arara/arara.jar -v ./root.tex
+popd
diff --git a/compile.sh b/compile.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+
+git clone https://gitlab.com/islandoftex/arara.git --depth 1
+pushd arara
+./gradlew :cli:build
+mv cli/build/libs/arara-cli-with-deps-*.jar arara.jar
+popd
diff --git a/root.tex b/root.tex
@@ -1,56 +1,28 @@
-\documentclass[english]{scrreprt}
-\usepackage[english]{babel}
-\usepackage{scrhack}
-\usepackage[headsepline,automark,autooneside=false]{scrlayer-scrpage}
-\usepackage{xcolor}
-\usepackage{hyperref}
-\usepackage{minted}
-\usepackage{csquotes}
-\usepackage{lastpage}
-\usepackage{tcolorbox}
-\usepackage{setspace}
-\usepackage[acronym,automake]{glossaries-extra}
-\usepackage[
- backend=biber,
- %style=alphabetic,
- sorting=ynt
-]{biblatex}
-\usepackage{comment}
+% arara: lualatex: { shell: yes, synctex: yes }
+% arara: biber
+% arara: makeglossaries if found('aux', '@istfilename')
+% arara: lualatex: { shell: yes, synctex: yes }
+% arara: lualatex: { shell: yes, synctex: yes }
+\documentclass[english]{scrbook}
+\input{style.sty}
+\usepackage[draft]{draftmark}
\addbibresource{bibliography.bib}
-\onehalfspacing
-
-% Setup hyperref
-\hypersetup{
- colorlinks=true,
- linkcolor=blue,
- urlcolor=blue
-}
-
-% Setup headers
-\clearpairofpagestyles
-\ihead{Helm - A Quickstart Guide and Styleguide}
-\ohead{\leftmark}
-\cfoot*{\pagemark\ of \pageref*{LastPage}}
-\setkomafont{pagenumber}{}
-\renewcommand\chapterpagestyle{scrheadings}
-
% Title Page
\title{Helm - A Quickstart Guide and Styleguide}
\subtitle{An opinionated starter to Helm Charts}
\author{Marcel Radzio}
-% Setup glossary
-\setabbreviationstyle[acronym]{long-short}
% Glossary definitions
-\newglossaryentry{k8s_resources}{
+\newglossaryentry{k8sResources}{
name={Kubernetes Resource},
description={A Kubernetes Resource is a YAML document defining a thing inside of a Kubernetes Cluster. This for example can be a Pod}
}
\newacronym{k8s}{k8s}{Kubernetes}
\newacronym{oci}{OCI}{Open Container Initiative}
\newacronym{ux}{UX}{User Experience}
+\newacronym{values}{values file}{values.yaml}
% Make it
\makeglossaries
@@ -59,12 +31,12 @@
\tableofcontents
\chapter{What is Helm?}
-Helm is a system for managing \Glspl{k8s_resources} and being able to deliver a simple to deploy bundle to administrators using \Gls{k8s} similar to Docker Compose or Ansible.
+Helm is a system for managing \Glspl{k8sResources} and being able to deliver a simple to deploy bundle to administrators using \Gls{k8s} similar to Docker Compose or Ansible.
It is one of the most used packaging systems in the \Gls{k8s} ecosystem and helps to provide a consistent \gls{ux} in the ecosystem.
\section{Helm as a packaging system}
-Helm itself describes itself as \enquote{The package manager for Kubernetes}\cite{helm}
+Helm itself describes itself as \enquote{The package manager for Kubernetes}\cite{helmauthorsHelm}
This means it's main goal and design is centered around being able to package an application, deal with dependencies and versioning.
As a result of this Helm is a generic way to define an application deployment.
@@ -75,13 +47,13 @@ In the typical Docker illustration style the Helm deployment would be a delivery
As part of being a package manager for Kubernetes it has to deal with definitions written in pure YAML.
Therefor it features a powerful template engine which works similar to how Ansible's template engine works.
-Under the hood this is archived by using the Go template language\cite{helm:functions_and_pipelines,go_template} as well as additional go functions provided to the users.
+Under the hood this is archived by using the Go template language\cite{helmauthorsTemplateFunctionsPipelines,thegoauthorsTemplatePackageText} as well as additional go functions provided to the users.
On top of the template language itself it also provides the option to print messages at the end of the installation or upgrade as well as nesting charts, having libraries for charts and using a global value context.
These are needed to provide consistent helm charts across a company or set of related charts and to ensure a nice \gls{ux} for those deploying said chart.
-\section{Features Helm gives us over pure \Glspl{k8s_resources}}
-Pure \Glspl{k8s_resources} come with multiple downsides over helm or similar packaging systems for \Gls{k8s}.
+\section{Features Helm gives us over pure \Glspl{k8sResources}}
+Pure \Glspl{k8sResources} come with multiple downsides over helm or similar packaging systems for \Gls{k8s}.
\Gls{k8s} brings no update management or atomic deployment management itself.
This means that an admin would need to ensure that they manually deploy each thing every time, possibly in the correct order and then has to ensure that it did not break.
@@ -105,10 +77,31 @@ Instead of then defining it themselves it can then depend on existing Charts and
\chapter{Structure of a Helm Package}
-\section{The Chart.yaml}
+A Helm Package follows a strict structure of files and folders.
+The typical structure looks like this\footnote{The test-connection.yaml file can be named anything.
+This is the default name you get in the official template.}:
+\dirtree{%
+ .1 .
+ .2 Chart.yaml.
+ .2 README.md.
+ .2 templates.
+ .3 \_helpers.yaml.
+ .3 NOTES.txt.
+ .3 tests.
+ .4 test-connection.yaml.
+ .2 values.yaml.
+}
+
+\section{The \enquote{Chart.yaml}}
+This is the file defining the metadata of the Helm Chart.
+Important fields are the name, description, type, version and appVersion fields.
+Most of these are self-explanatory.
+Below the special fields will be explained.
-\begin{comment}
-\begin{minted}[numbers=left, frame=lines]{yaml}
+\begin{figure}[!hp]
+\centering
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{yaml}
apiVersion: v2
name: matrix-neoboard-widget
description: A whiteboard widget for the Element messenger
@@ -117,11 +110,240 @@ version: 0.1.0
appVersion: "0.0.0"
home: https://github.com/nordeck/matrix-neoboard
\end{minted}
-\end{comment}
+\end{singlespace}
+\caption{A simple application Chart.yaml}\label{code:Chart.yaml}
+\end{figure}
+
+\subsection{The \emph{appVersion} field}
+
+\subsection{The \emph{maintainers} field}
+\subsection{Other available fields}
+
+
+\section{The \enquote{values.yaml}}
+
+\subsection{Images}
+
+The core of every application in Kubernetes is the image used for deploying it.
+This is being done in the \enquote{image} section of the \gls{values}.
+
+\begin{figure}[!hp]
+\centering
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{yaml}
+# This sets the container image more information can be found here: https://kubernetes.io/docs/concepts/containers/images/
+image:
+ repository: nginx
+ # This sets the pull policy for images.
+ pullPolicy: IfNotPresent
+ # Overrides the image tag whose default is the chart appVersion.
+ tag: ""
+# This is for the secretes for pulling an image from a private repository more information can be found here: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
+imagePullSecrets: []
+\end{minted}
+\end{singlespace}
+\caption{The \enquote{image} section of the \gls{values}}\label{code:image_section}
+\end{figure}
+
+Things to note here are the 3 fields it should contain:
+
+\begin{enumerate}
+ \item The repository which sets the image name. This would also include things like \enquote{ghcr.io} or other custom repositories used.
+ \item The \enquote{pullPolicy} which defines how often it is pulled. By default this should be \enquote{IfNotPresent}. For latest tags it automatically defaults however to \enquote{Always} which, as the name says, will always pull the image when a pod is started.
+ \item The \enquote{tag} field defines the value after the colon in a docker image. This should stay as an empty string by default since it will be pulled from the chart's \enquote{appVersion} field usually. It is meant to allow a consumer to change this if they need to.
+\end{enumerate}
+
+Additionally there is the \enquote{imagePullSecrets} field which allows you to pull from private repositories. For more information on this take a look at \url{https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/}
+
+\subsection{Service Account}
+
+\begin{figure}[!hp]
+\centering
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{yaml}
+#This section builds out the service account more information can be found here: https://kubernetes.io/docs/concepts/security/service-accounts/
+serviceAccount:
+ # Specifies whether a service account should be created
+ create: true
+ # Automatically mount a ServiceAccount's API credentials?
+ automount: true
+ # Annotations to add to the service account
+ annotations: {}
+ # The name of the service account to use.
+ # If not set and create is true, a name is generated using the fullname template
+ name: ""
+\end{minted}
+\end{singlespace}
+\caption{The \enquote{serviceAccount} section of the \gls{values}}\label{code:service_account_section}
+\end{figure}
+
+Service Accounts are required for accessing the resources of the \gls{k8s} Cluster itself.
+They are scoped accounts to the cluster and require most likely more setup in the templates to actually be useful.
+They are commonly used by operators or similar things which listen to or write to resources in the cluster.
+
+\subsection{\enquote{service} and \enquote{ingress}}
+
+\begin{figure}[!hp]
+\centering
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{yaml}
+service:
+ # This sets the service type more information can be found here: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
+ type: ClusterIP
+ # This sets the ports more information can be found here: https://kubernetes.io/docs/concepts/services-networking/service/#field-spec-ports
+ port: 80
+
+# This block is for setting up the ingress for more information can be found here: https://kubernetes.io/docs/concepts/services-networking/ingress/
+ingress:
+ enabled: false
+ className: ""
+ annotations: {}
+ # kubernetes.io/ingress.class: nginx
+ # kubernetes.io/tls-acme: "true"
+ hosts:
+ - host: chart-example.local
+ paths:
+ - path: /
+ pathType: ImplementationSpecific
+ tls: []
+ # - secretName: chart-example-tls
+ # hosts:
+ # - chart-example.local
+\end{minted}
+\end{singlespace}
+\caption{The \enquote{service} section and the \enquote{ingress} section of the \gls{values}}\label{code:service_and_ingress_section}
+\end{figure}
+
+\begingroup
+\centering
+\label{figure:values.yaml}
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{yaml}
+# This will set the replicaset count more information can be found here: https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/
+replicaCount: 1
+
+# This is to override the chart name.
+nameOverride: ""
+fullnameOverride: ""
+
+# This is for setting Kubernetes Annotations to a Pod.
+# For more information checkout: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/
+podAnnotations: {}
+# This is for setting Kubernetes Labels to a Pod.
+# For more information checkout: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
+podLabels: {}
+podSecurityContext: {}
+ # fsGroup: 2000
+
+securityContext: {}
+ # capabilities:
+ # drop:
+ # - ALL
+ # readOnlyRootFilesystem: true
+ # runAsNonRoot: true
+ # runAsUser: 1000
+ # This is for setting up a service more information can be found here: https://kubernetes.io/docs/concepts/services-networking/service/
+
+service:
+ # This sets the service type more information can be found here: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
+ type: ClusterIP
+ # This sets the ports more information can be found here: https://kubernetes.io/docs/concepts/services-networking/service/#field-spec-ports
+ port: 80
+
+# This block is for setting up the ingress for more information can be found here: https://kubernetes.io/docs/concepts/services-networking/ingress/
+ingress:
+ enabled: false
+ className: ""
+ annotations: {}
+ # kubernetes.io/ingress.class: nginx
+ # kubernetes.io/tls-acme: "true"
+ hosts:
+ - host: chart-example.local
+ paths:
+ - path: /
+ pathType: ImplementationSpecific
+ tls: []
+ # - secretName: chart-example-tls
+ # hosts:
+ # - chart-example.local
+
+resources: {}
+ # We usually recommend not to specify default resources and to leave this as a conscious
+ # choice for the user. This also increases chances charts run on environments with little
+ # resources, such as Minikube. If you do want to specify resources, uncomment the following
+ # lines, adjust them as necessary, and remove the curly braces after 'resources:'.
+ # limits:
+ # cpu: 100m
+ # memory: 128Mi
+ # requests:
+ # cpu: 100m
+ # memory: 128Mi
+
+# This is to setup the liveness and readiness probes more information can be found here: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
+livenessProbe:
+ httpGet:
+ path: /
+ port: http
+readinessProbe:
+ httpGet:
+ path: /
+ port: http
+
+#This section is for setting up autoscaling more information can be found here: https://kubernetes.io/docs/concepts/workloads/autoscaling/
+autoscaling:
+ enabled: false
+ minReplicas: 1
+ maxReplicas: 100
+ targetCPUUtilizationPercentage: 80
+ # targetMemoryUtilizationPercentage: 80
+
+# Additional volumes on the output Deployment definition.
+volumes: []
+# - name: foo
+# secret:
+# secretName: mysecret
+# optional: false
+# Additional volumeMounts on the output Deployment definition.
+
+volumeMounts: []
+# - name: foo
+# mountPath: "/etc/foo"
+# readOnly: true
+
+nodeSelector: {}
+
+tolerations: []
+
+affinity: {}
+\end{minted}
+\end{singlespace}
+\captionof{figure}{A simple application values.yaml}\label{code:values.yaml}
+\endgroup
+
+\section{The \enquote{NOTES.txt}}
+\begin{figure}[!hp]
+\centering
+\begin{singlespace}
+\begin{minted}[numbers=left, frame=lines,breaklines,breakanywhere,samepage=false]{text}
+apiVersion: v2
+name: matrix-neoboard-widget
+description: A whiteboard widget for the Element messenger
+type: application
+version: 0.1.0
+appVersion: "0.0.0"
+home: https://github.com/nordeck/matrix-neoboard
+\end{minted}
+\end{singlespace}
+\caption{A simple NOTES.txt}\label{code:NOTES.txt}
+\end{figure}
%%%%%%%%%%%%%%%%%%%%%%%%
+\cleardoublepage
+\appendix
\printglossaries
\nocite{*}
\printbibliography[heading=bibintoc,title={Sources}]
+
+\listoffigures
\end{document}
diff --git a/style.sty b/style.sty
@@ -0,0 +1,77 @@
+\usepackage[english]{babel}
+\usepackage{scrhack}
+\usepackage[headsepline,automark,autooneside=false]{scrlayer-scrpage}
+\usepackage{xcolor}
+\usepackage{hyperref}
+\usepackage{minted}
+\usepackage{csquotes}
+\usepackage{lastpage}
+\usepackage{tcolorbox}
+\usepackage{setspace}
+\usepackage{amsmath,amssymb,amsthm}
+\usepackage{booktabs}
+\usepackage{array}
+\usepackage{siunitx}
+\usepackage{graphicx}
+\usepackage{lmodern}
+\usepackage{dirtree}
+\usepackage[acronym]{glossaries-extra}
+\usepackage[
+backend=biber,
+style=ieee,
+defernumbers=true,
+]{biblatex}
+\usepackage{comment}
+\usepackage{mdframed}
+\usepackage{caption}
+
+% Fix for missing dates
+\usepackage{xpatch}
+\xpatchbibdriver{online}
+{\printtext[parens]{\usebibmacro{date}}}
+{\iffieldundef{year}
+ {}
+ {\printtext[parens]{\usebibmacro{date}}}}
+{}
+{\typeout{There was an error patching biblatex-ieee (specifically, ieee.bbx's @online driver)}}
+
+\onehalfspacing
+
+% Setup hyperref
+\hypersetup{
+ colorlinks=true,
+ linkcolor=blue,
+ urlcolor=blue
+}
+
+% Setup headers
+\clearpairofpagestyles
+\ihead{Helm - A Quickstart Guide and Styleguide}
+\ohead{\leftmark}
+\cfoot*{\pagemark\ of \pageref*{LastPage}}
+\setkomafont{pagenumber}{}
+\renewcommand\chapterpagestyle{scrheadings}
+
+% Setup nicer chapters
+\newcommand\titlerule[1][1pt]{\rule{\textwidth}{#1}}
+
+\RedeclareSectionCommand[innerskip=0pt]{chapter}
+
+\renewcommand\chapterlineswithprefixformat[3]{%
+ #2\nobreak%
+ \Ifstr{#2}{}{}{\kern-\dp\strutbox}%
+ \titlerule\par\nobreak%
+ #3%
+ \par\nobreak\titlerule%
+}
+
+\makeatletter
+\renewcommand\chapterlinesformat[3]{%
+ \titlerule\par\nobreak%
+ \@hangfrom{#2}{#3}%
+ \par\nobreak\titlerule%
+}
+\makeatother
+
+% Setup glossary
+\setabbreviationstyle[acronym]{long-short}
+\ No newline at end of file
