diff --git a/README.adoc b/README.adoc index f28688c..2758ee7 100644 --- a/README.adoc +++ b/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. diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..605ef43 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,5 @@ +name: agent +version: master +title: Stackable Agent +nav: + - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..4a884e4 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,4 @@ +* Installation +** xref:installation/building.adoc[] +** xref:installation/binaries.adoc[] +* xref:configuration.adoc[] diff --git a/documentation/commandline_args.adoc b/docs/modules/ROOT/pages/commandline_args.adoc similarity index 100% rename from documentation/commandline_args.adoc rename to docs/modules/ROOT/pages/commandline_args.adoc diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc new file mode 100644 index 0000000..39fdb23 --- /dev/null +++ b/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 diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..18b5650 --- /dev/null +++ b/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. diff --git a/docs/modules/ROOT/pages/installation/binaries.adoc b/docs/modules/ROOT/pages/installation/binaries.adoc new file mode 100644 index 0000000..77f4db6 --- /dev/null +++ b/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. diff --git a/docs/modules/ROOT/pages/installation/building.adoc b/docs/modules/ROOT/pages/installation/building.adoc new file mode 100644 index 0000000..c37eab4 --- /dev/null +++ b/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 + +|=== diff --git a/src/bin/generate_doc.rs b/src/bin/generate_doc.rs index e161fe1..8f7927d 100644 --- a/src/bin/generate_doc.rs +++ b/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 [{}]: {}",