Skip to content
This repository was archived by the owner on Dec 21, 2021. It is now read-only.

Commit dc8d0c6

Browse files
lfranckesiegfriedweber
lfrancke
and
siegfriedweber
authored
Move to Antora for documentation (#165)
Co-authored-by: Siegfried Weber <mail@siegfriedweber.net>
1 parent 370e787 commit dc8d0c6

File tree

9 files changed

+123
-116
lines changed

9 files changed

+123
-116
lines changed

‎README.adoc

+2-115
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,7 @@
11
= Stackable Agent
22

3-
== Purpose
43
The Stackable Agent is an alternative to the Kubernetes Kubelet that executes Pods not in containers but using systemd as its backend.
5-
It is implemented in Rust as a https://github.com/deislabs/krustlet[Krustlet] provider.
64

7-
In principle this behavior is similar to that of the the https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet] project.
8-
More specifically the functionality of this agent closely resembles that of https://github.com/virtual-kubelet/systemk[systemk].
9-
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.
10-
11-
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]
12-
13-
The agent registers itself as a node with a kube-apiserver and will be considered by the Kubernetes scheduler for workloads (pods).
14-
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:
15-
16-
|===
17-
|Taint |Type|Value
18-
19-
|kubernetes.io/arch
20-
|NoSchedule
21-
|stackable-linux
22-
23-
|kubernetes.io/arch
24-
|NoExecute
25-
|stackable-linux
26-
|===
27-
28-
These taints _suggest_ to the Kubernetes scheduler that only pods with matching tolerations should be scheduled on this node.
29-
30-
== Installation
31-
=== Build from source
32-
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.
33-
If you need to install this, generally the recommended way is to use https://rustup.rs/[rustup].
34-
35-
After rust is installed simply run
36-
37-
cargo build
38-
39-
To create the binary file in _target/debug_.
40-
41-
==== Build dependencies
42-
The agent depends on native systemd libraries to communicate with systemd.
43-
For the build process to work these need to be installed on the build system.
44-
45-
46-
47-
|===
48-
|Distribution |Package Names
49-
50-
|Ubuntu
51-
a|- pkg-config
52-
- libsystemd-dev
53-
54-
|Centos
55-
a|- pkg-config
56-
- systemd-devel
57-
58-
|===
59-
60-
61-
62-
=== Download binary
63-
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.
64-
This readme will be updated as soon as binary downloads are available!
65-
66-
=== OS Packages
67-
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!
68-
69-
== Configuration
70-
71-
=== Command Line Parameters
72-
The agent accepts the following command line parameters:
73-
74-
include::documentation/commandline_args.adoc[]
75-
76-
=== Config File
77-
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`.
78-
79-
This file can contain all command line parameters and will be parsed before the actual command line.
80-
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.
81-
82-
.Example config file
83-
--package-directory=/opt/stackable/agent/work/packages
84-
--config-directory=/etc/stackable/agent
85-
--server-cert-file=/etc/stackable/agent/secure/cert.crt
86-
--server-key-file=/etc/stackable/agent/secure/key.key
87-
88-
=== Kubernetes Config
89-
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.
90-
91-
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.
92-
93-
export KUBECONFIG=/etc/stackable/agent/kubeconfig
94-
95-
96-
=== Certificates
97-
The agent requires a keypair and signed certificate to start a webserver which can be used to handle callbacks.
98-
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.
99-
These steps require a certificate manager to be set up and running in your Kubernetes cluster, which may or may not be the case.
100-
101-
You can also manually create these files and specify them on the command line.
102-
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.
103-
104-
./easyrsa init-pki
105-
./easyrsa build-ca
106-
./easyrsa gen-req krustlet1
107-
./easyrsa import-req pki/reqs/krustlet1.req krustlet1-req
108-
./easyrsa sign-req serverClient krustlet1-req
109-
# Convert key to pksc8 format
110-
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pki/private/krustlet1.key -out pkcs8.key
111-
112-
== Contributing
113-
The agent is developed as an open source tool and we absolutely welcome any and all contributions!
114-
Don't hesitate to drop us a line at info@stackable.de or reach out directly to any of our committers / contributors.
115-
116-
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.
117-
Please feel free to drop in if you have the time!
118-
119-
Dial in info coming soon!
5+
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.
1206

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

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
name: agent
2+
version: master
3+
title: Stackable Agent
4+
nav:
5+
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/nav.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
* Installation
2+
** xref:installation/building.adoc[]
3+
** xref:installation/binaries.adoc[]
4+
* xref:configuration.adoc[]

‎documentation/commandline_args.adoc renamed to ‎docs/modules/ROOT/pages/commandline_args.adoc

File renamed without changes.

‎docs/modules/ROOT/pages/configuration.adoc

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
= Configuration
2+
3+
== Command Line Parameters
4+
The agent accepts the following command line parameters:
5+
6+
include::commandline_args.adoc[]
7+
8+
== Config File
9+
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`.
10+
11+
This file can contain all command line parameters and will be parsed before the actual command line.
12+
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.
13+
14+
.Example config file
15+
--package-directory=/opt/stackable/agent/work/packages
16+
--config-directory=/etc/stackable/agent
17+
--server-cert-file=/etc/stackable/agent/secure/cert.crt
18+
--server-key-file=/etc/stackable/agent/secure/key.key
19+
20+
== Kubernetes Config
21+
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.
22+
23+
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.
24+
25+
export KUBECONFIG=/etc/stackable/agent/kubeconfig
26+
27+
28+
== Certificates
29+
The agent requires a keypair and signed certificate to start a webserver which can be used to handle callbacks.
30+
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.
31+
These steps require a certificate manager to be set up and running in your Kubernetes cluster, which may or may not be the case.
32+
33+
You can also manually create these files and specify them on the command line.
34+
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.
35+
36+
./easyrsa init-pki
37+
./easyrsa build-ca
38+
./easyrsa gen-req krustlet1
39+
./easyrsa import-req pki/reqs/krustlet1.req krustlet1-req
40+
./easyrsa sign-req serverClient krustlet1-req
41+
# Convert key to pksc8 format
42+
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pki/private/krustlet1.key -out pkcs8.key

‎docs/modules/ROOT/pages/index.adoc

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
= Stackable Agent
2+
3+
The Stackable Agent is an alternative to the Kubernetes Kubelet that executes Pods not in containers but using systemd as its backend.
4+
It is implemented in Rust as a https://github.com/deislabs/krustlet[Krustlet] provider.
5+
6+
The agent registers itself as a node with a kube-apiserver and will be considered by the Kubernetes scheduler for workloads (pods).
7+
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:
8+
9+
|===
10+
|Taint |Type|Value
11+
12+
|kubernetes.io/arch
13+
|NoSchedule
14+
|stackable-linux
15+
16+
|kubernetes.io/arch
17+
|NoExecute
18+
|stackable-linux
19+
|===
20+
21+
These taints _suggest_ to the Kubernetes scheduler that only pods with matching tolerations should be scheduled on this node.
22+
23+
== Contributing
24+
The agent is developed as an open source tool, and we absolutely welcome any and all contributions!
25+
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

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
= Binaries & Packages
2+
3+
== Download binary
4+
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.
5+
This readme will be updated as soon as binary downloads are available!
6+
7+
== OS Packages
8+
9+
We provide OS packages for RHEL/CentOS 7 & 8 as well as Debian 10 (buster).
10+
11+
* EL7: https://repo.stackable.tech/repository/rpm-release/el7/
12+
* EL8: https://repo.stackable.tech/repository/rpm-release/el8/
13+
* Debian 10: https://repo.stackable.tech/repository/deb-release
14+
15+
Add these repositories to your OS and then install the `stackable-agent` package.

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

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
= Building from source
2+
3+
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.
4+
If you need to install this, generally the recommended way is to use https://rustup.rs/[rustup].
5+
6+
After rust is installed simply run
7+
8+
cargo build
9+
10+
To create the binary file in _target/debug_.
11+
12+
== Build dependencies
13+
The agent depends on native systemd libraries to communicate with systemd.
14+
For the build process to work these need to be installed on the build system.
15+
16+
17+
18+
|===
19+
|Distribution |Package Names
20+
21+
|Ubuntu
22+
a|- pkg-config
23+
- libsystemd-dev
24+
25+
|Centos
26+
a|- pkg-config
27+
- systemd-devel
28+
29+
|===

‎src/bin/generate_doc.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ fn main() {
1010
use stackable_agent::config::AgentConfig;
1111
use std::fs;
1212

13-
let target_file = "documentation/commandline_args.adoc";
13+
let target_file = "docs/modules/ROOT/pages/commandline_args.adoc";
1414
fs::write(target_file, AgentConfig::get_documentation()).unwrap_or_else(|err| {
1515
panic!(
1616
"Could not write documentation to [{}]: {}",

0 commit comments

Comments
 (0)