Move to Antora for documentation

README.adoc

@@ -1,120 +1,7 @@
 = Stackable Agent
 
-== Purpose
 The Stackable Agent is an alternative to the Kubernetes Kubelet that executes Pods not in containers but using systemd as its backend.
-It is implemented in Rust as a https://github.com/deislabs/krustlet[Krustlet] provider.
 
-In principle this behavior is similar to that of the the https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet] project.
-More specifically the functionality of this agent closely resembles that of https://github.com/virtual-kubelet/systemk[systemk].
-The reason why both projects currently exist is simply that systemk was not around when we started Stackable and so we had to go and build our own.
-
-WARNING: We are currently evaluating whether or not we should instead use systemk and contribute to that project instead of building our own agent under https://github.com/stackabletech/agent/issues/42[issue #42]
-
-The agent registers itself as a node with a kube-apiserver and will be considered by the Kubernetes scheduler for workloads (pods).
-To avoid _normal_ Kubernetes pods being scheduled on the Stackable agent (it would not know what to do with these) the agent assigns the following taints to its node object:
-
-|===
-|Taint |Type|Value
-
-|kubernetes.io/arch
-|NoSchedule
-|stackable-linux
-
-|kubernetes.io/arch
-|NoExecute
-|stackable-linux
-|===
-
-These taints _suggest_ to the Kubernetes scheduler that only pods with matching tolerations should be scheduled on this node.
-
-== Installation
-=== Build from source
-Building from source is fairly straightforward if you have the rust toolchain installed, our CI chain tests against the latest stable version at the time the checks are run.
-If you need to install this, generally the recommended way is to use https://rustup.rs/[rustup].
-
-After rust is installed simply run
-
-    cargo build
-
-To create the binary file in _target/debug_.
-
-==== Build dependencies
-The agent depends on native systemd libraries to communicate with systemd.
-For the build process to work these need to be installed on the build system.
-
-
-
-|===
-|Distribution |Package Names
-
-|Ubuntu
-a|- pkg-config
-- libsystemd-dev
-
-|Centos
-a|- pkg-config
-- systemd-devel
-
-|===
-
-
-
-=== Download binary
-We do not at this time provide pre-compiled binaries, as we are still in the process of setting up the build jobs to create these.
-This readme will be updated as soon as binary downloads are available!
-
-=== OS Packages
-We do not at this time provide OS packages, that is due to change in the near future and this readme will be updated accordingly!
-
-== Configuration
-
-=== Command Line Parameters
-The agent accepts the following command line parameters:
-
-include::documentation/commandline_args.adoc[]
-
-=== Config File
-In addition to directly specifying them on the command line, the agent allows specifying a config file via the environment variable `CONFIG_FILE`. Values specified in the file will have to adhere to the format `--parameter=value`.
-
-This file can contain all command line parameters and will be parsed before the actual command line.
-For parameters that are present in the file and on the command line, the command line will take precedence, unless it is a parameter that can be specified multiple times, in which case parameters from both, file and commandline, will be merged.
-
-.Example config file
-    --package-directory=/opt/stackable/agent/work/packages
-    --config-directory=/etc/stackable/agent
-    --server-cert-file=/etc/stackable/agent/secure/cert.crt
-    --server-key-file=/etc/stackable/agent/secure/key.key
-
-=== Kubernetes Config
-The agent uses the default way of looking for a kube-apiserver, so if your system is already set up to connect to Kubernetes with kubectl you should be good to go right of the bat.
-
-The default location for the Kubernetes client config is `~/.kube/config`, if you want to change this location you can override this via the `KUBECONFIG` environment variable.
-
-    export KUBECONFIG=/etc/stackable/agent/kubeconfig
-
-
-=== Certificates
-The agent requires a keypair and signed certificate to start a webserver which can be used to handle callbacks.
-If these are not specified on the commandline, the agent will create a keypair, upload a certificate signing request to Kubernetes and wait for the certificate before continuing.
-These steps require a certificate manager to be set up and running in your Kubernetes cluster, which may or may not be the case.
-
-You can also manually create these files and specify them on the command line.
-The following example shows how to create these files using https://github.com/OpenVPN/easy-rsa[easy-rsa], but this can be done in any number of different ways as well.
-
-    ./easyrsa init-pki
-    ./easyrsa build-ca
-    ./easyrsa gen-req krustlet1
-    ./easyrsa import-req pki/reqs/krustlet1.req krustlet1-req
-    ./easyrsa sign-req serverClient krustlet1-req
-    # Convert key to pksc8 format
-    openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pki/private/krustlet1.key -out pkcs8.key
-
-== Contributing
-The agent is developed as an open source tool and we absolutely welcome any and all contributions!
-Don't hesitate to drop us a line at info@stackable.de or reach out directly to any of our committers / contributors.
-
-We will run a bi-weekly dev call during which we will discuss current development, issues, our children and the general state of the world.
-Please feel free to drop in if you have the time!
-
-Dial in info coming soon!
+It is written by https://www.stackable.de[Stackable] in Rust, and it is supposed to be used with the https://github.com/stackabletech/agent[Stackable Agent] instead of the Kubernetes kubelet.
 
+The docs can be found in the `docs` subdirectory, and they are published together with docs for all other Stackable products at https://docs.stackable.tech.

docs/antora.yml

@@ -0,0 +1,5 @@
+name: agent
+version: master
+title: Stackable Agent
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,4 @@
+* Installation
+** xref:installation/building.adoc[]
+** xref:installation/binaries.adoc[]
+* xref:configuration.adoc[]

docs/modules/ROOT/pages/configuration.adoc

@@ -0,0 +1,42 @@
+= Configuration
+
+== Command Line Parameters
+The agent accepts the following command line parameters:
+
+include::commandline_args.adoc[]
+
+== Config File
+In addition to directly specifying them on the command line, the agent allows specifying a config file via the environment variable `CONFIG_FILE`. Values specified in the file will have to adhere to the format `--parameter=value`.
+
+This file can contain all command line parameters and will be parsed before the actual command line.
+For parameters that are present in the file and on the command line, the command line will take precedence, unless it is a parameter that can be specified multiple times, in which case parameters from both, file and commandline, will be merged.
+
+.Example config file
+    --package-directory=/opt/stackable/agent/work/packages
+    --config-directory=/etc/stackable/agent
+    --server-cert-file=/etc/stackable/agent/secure/cert.crt
+    --server-key-file=/etc/stackable/agent/secure/key.key
+
+== Kubernetes Config
+The agent uses the default way of looking for a kube-apiserver, so if your system is already set up to connect to Kubernetes with kubectl you should be good to go right of the bat.
+
+The default location for the Kubernetes client config is `~/.kube/config`, if you want to change this location you can override this via the `KUBECONFIG` environment variable.
+
+    export KUBECONFIG=/etc/stackable/agent/kubeconfig
+
+
+== Certificates
+The agent requires a keypair and signed certificate to start a webserver which can be used to handle callbacks.
+If these are not specified on the commandline, the agent will create a keypair, upload a certificate signing request to Kubernetes and wait for the certificate before continuing.
+These steps require a certificate manager to be set up and running in your Kubernetes cluster, which may or may not be the case.
+
+You can also manually create these files and specify them on the command line.
+The following example shows how to create these files using https://github.com/OpenVPN/easy-rsa[easy-rsa], but this can be done in any number of different ways as well.
+
+    ./easyrsa init-pki
+    ./easyrsa build-ca
+    ./easyrsa gen-req krustlet1
+    ./easyrsa import-req pki/reqs/krustlet1.req krustlet1-req
+    ./easyrsa sign-req serverClient krustlet1-req
+    # Convert key to pksc8 format
+    openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pki/private/krustlet1.key -out pkcs8.key

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,25 @@
+= Stackable Agent
+
+The Stackable Agent is an alternative to the Kubernetes Kubelet that executes Pods not in containers but using systemd as its backend.
+It is implemented in Rust as a https://github.com/deislabs/krustlet[Krustlet] provider.
+
+The agent registers itself as a node with a kube-apiserver and will be considered by the Kubernetes scheduler for workloads (pods).
+To avoid _normal_ Kubernetes pods being scheduled on the Stackable agent (it would not know what to do with these) the agent assigns the following taints to its `Node` object:
+
+|===
+|Taint |Type|Value
+
+|kubernetes.io/arch
+|NoSchedule
+|stackable-linux
+
+|kubernetes.io/arch
+|NoExecute
+|stackable-linux
+|===
+
+These taints _suggest_ to the Kubernetes scheduler that only pods with matching tolerations should be scheduled on this node.
+
+== Contributing
+The agent is developed as an open source tool, and we absolutely welcome any and all contributions!
+Don't hesitate to drop us a line at info@stackable.de or reach out directly to any of our committers / contributors.

docs/modules/ROOT/pages/installation/binaries.adoc

@@ -0,0 +1,15 @@
+= Binaries & Packages
+
+== Download binary
+We do not at this time provide pre-compiled binaries, as we are still in the process of setting up the build jobs to create these.
+This readme will be updated as soon as binary downloads are available!
+
+== OS Packages
+
+We provide OS packages for RHEL/CentOS 7 & 8 as well as Debian 10 (buster).
+
+* EL7: https://repo.stackable.tech/repository/rpm-release/el7/
+* EL8: https://repo.stackable.tech/repository/rpm-release/el8/
+* Debian 10: https://repo.stackable.tech/repository/deb-release
+
+Add these repositories to your OS and then install the `stackable-agent` package.

docs/modules/ROOT/pages/installation/building.adoc

@@ -0,0 +1,29 @@
+= Building from source
+
+Building from source is fairly straightforward if you have the rust toolchain installed, our CI chain tests against the latest stable version at the time the checks are run.
+If you need to install this, generally the recommended way is to use https://rustup.rs/[rustup].
+
+After rust is installed simply run
+
+    cargo build
+
+To create the binary file in _target/debug_.
+
+== Build dependencies
+The agent depends on native systemd libraries to communicate with systemd.
+For the build process to work these need to be installed on the build system.
+
+
+
+|===
+|Distribution |Package Names
+
+|Ubuntu
+a|- pkg-config
+- libsystemd-dev
+
+|Centos
+a|- pkg-config
+- systemd-devel
+
+|===

src/bin/generate_doc.rs

@@ -10,7 +10,7 @@ fn main() {
     use stackable_agent::config::AgentConfig;
     use std::fs;
 
-    let target_file = "documentation/commandline_args.adoc";
+    let target_file = "docs/modules/ROOT/pages/commandline_args.adoc";
     fs::write(target_file, AgentConfig::get_documentation()).unwrap_or_else(|err| {
         panic!(
             "Could not write documentation to [{}]: {}",