From 2b95ea26834e0de90bfa7c436c23b9ef25d8f075 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Tue, 19 Jan 2021 11:33:44 +0100 Subject: [PATCH 01/10] Added first version of Readme --- README.adoc | 98 ++++++++++++++++++++++++++++++++ config/commandline_args.adoc | 106 +++++++++++++++++++++++++++++++++++ src/agentconfig.rs | 51 +++++++++++++++-- 3 files changed, 249 insertions(+), 6 deletions(-) create mode 100644 README.adoc create mode 100644 config/commandline_args.adoc diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..9c83833 --- /dev/null +++ b/README.adoc @@ -0,0 +1,98 @@ +# Stackable Agent + +## Purpose +This agent is the component in the Stackable stack which is run locally on all nodes to enact changes that are necessary to deploy and manager the software components that are managed by Stackable. + +The agent behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. +Instead it is based on the https://github.com/deislabs/krustlet[Krustlet], which is under active development by Microsoft. + +The agent registers itself as a node with a kube-apiserver 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. +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_. + +### 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 + +WARNING: Due to https://github.com/stackabletech/agent/issues/34[#34] it is not currently possible to specify these parameters directly on the commandline, please use a config file instead. + +The agent accepts the following command line parameters: + +include::config/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 as well 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 paramaters from both, file and commandline, will be used. + +.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! + diff --git a/config/commandline_args.adoc b/config/commandline_args.adoc new file mode 100644 index 0000000..f96758f --- /dev/null +++ b/config/commandline_args.adoc @@ -0,0 +1,106 @@ + + + +### config-directory + +*Default value*: /opt/stackable/config + +*Required*: false + +*Multiple values:*: false + + +This directory will serve as starting point for all log files which this service creates.Every service will get its own subdirectories created within this directory - for every service start a new subdirectory will be created to show a full history of configuration that was used for this service. +ConfigMaps that are mounted into the pod that describes this service will be created relative to these run directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory. + +The agent will need full access to this directory and tries to create it if it does not exist. + + +### no-config + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +If this option is specified, any file referenced in AGENT_CONF environment variable will be ignored. + + +### server-bind-ip + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +The local IP to register as the node's ip with the apiserver. Will be automatically set to the first address of the first non-loopback interface if not specified. + + +### tag + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: true + + +Tags are the main way of identifying nodes to assign services to later on. + + +### server-cert-file + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +The certificate file for the local webserver which the Krustlet starts. + + +### server-key-file + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +Private key file (in PKCS8 format) to use for the local webserver the Krustlet starts. + + +### package-directory + +*Default value*: /opt/stackable/packages + +*Required*: false + +*Multiple values:*: false + + +This directory will serve as starting point for packages that are needed by pods assigned to this node. + Packages will be downloaded into the "_download" folder at thetop level of this folder as archives and remain there for potential future use. +Archives will the be extracted directly into this folder in subdirectories following the namingscheme of "productname-productversion". + The agent will need full access to this directory and tries to create it if it does not exist. + + +### log-directory + +*Default value*: /opt/stackable/logs + +*Required*: false + +*Multiple values:*: false + + +This directory will serve as starting point for all log files which this service creates.Every service will get its own subdirectory created within this directory. +Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory. + +The agent will need full access to this directory and tries to create it if it does not exist. \ No newline at end of file diff --git a/src/agentconfig.rs b/src/agentconfig.rs index e455176..fa835e0 100644 --- a/src/agentconfig.rs +++ b/src/agentconfig.rs @@ -67,10 +67,10 @@ impl AgentConfig { takes_argument: true, help: "The base directory under which installed packages will be stored.", documentation: "This directory will serve as starting point for packages that are needed by \ - pods assigned to this node.\n Packages will be downloaded into the \"_download\" folder at the -top level of this folder as archives and remain there for potential future use.\n\ - Archives will the be extracted directly into this folder in subdirectories following the naming -scheme of \"productname-productversion\". + pods assigned to this node.\n Packages will be downloaded into the \"_download\" folder at the\ + top level of this folder as archives and remain there for potential future use.\n\ + Archives will the be extracted directly into this folder in subdirectories following the naming\ + scheme of \"productname-productversion\". The agent will need full access to this directory and tries to create it if it does not exist.", list: false, }; @@ -83,7 +83,7 @@ scheme of \"productname-productversion\". help: "The base directory under which configuration will be generated for all executed services.", documentation: "This directory will serve as starting point for all log files which this service creates.\ Every service will get its own subdirectories created within this directory - for every service start a \ - new subdirectory will be created to show a full history of configuration that was used for this service.\n + new subdirectory will be created to show a full history of configuration that was used for this service.\n\ ConfigMaps that are mounted into the pod that describes this service will be created relative to these run \ directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory.\n\n\ The agent will need full access to this directory and tries to create it if it does not exist.", @@ -97,7 +97,7 @@ scheme of \"productname-productversion\". takes_argument: true, help: "The base directory under which log files will be placed for all services.", documentation: "This directory will serve as starting point for all log files which this service creates.\ - Every service will get its own subdirectory created within this directory.\n + Every service will get its own subdirectory created within this directory.\n\ Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory.\n\n\ The agent will need full access to this directory and tries to create it if it does not exist.", list: false, @@ -201,10 +201,49 @@ scheme of \"productname-productversion\". }; None } + + pub fn get_documentation() -> Result { + let mut doc_string = String::new(); + for option in AgentConfig::get_options() { + doc_string.push_str(&format!("\n\n\n### {}\n\n", option.name)); + doc_string.push_str(&format!( + "*Default value*: {}\n\n", + option.default.unwrap_or("No default value") + )); + doc_string.push_str(&format!("*Required*: {}\n\n", option.required)); + doc_string.push_str(&format!("*Multiple values:*: {}\n\n\n", option.list)); + + // We have not yet specified a documentation string for all options, as an interim + // solution we use the help string for the docs, if no proper doc has been written yet. + if option.documentation.is_empty() { + doc_string.push_str(&option.help); + } else { + doc_string.push_str(&option.documentation); + } + } + Ok(doc_string) + } + + fn gen_docs() { + // TODO: this needs to be moved to a build.rs type of thing + use std::env; + use std::fs; + use std::path::PathBuf; + + let target_file = PathBuf::from("config/commandline_args.adoc"); + + // We have unwraps in here, as this is supposed to be called during the build process, + // it shouldn't even be part of the codebase itself. + // Once this is moved out the unwraps are fine, because a failure during build is ok if + // something is wrong. + let test = AgentConfig::get_documentation().unwrap(); + fs::write(&target_file, test).unwrap(); + } } impl Configurable for AgentConfig { fn get_config_description() -> Configuration { + AgentConfig::gen_docs(); Configuration { name: "Stackable Agent", version: "0.1", From bd729c14632e0f9560af158654319da3c7825f92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 14:06:36 +0100 Subject: [PATCH 02/10] Added more context to readme intro. --- README.adoc | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/README.adoc b/README.adoc index 9c83833..c07853d 100644 --- a/README.adoc +++ b/README.adoc @@ -1,11 +1,19 @@ -# Stackable Agent += Stackable Agent -## Purpose -This agent is the component in the Stackable stack which is run locally on all nodes to enact changes that are necessary to deploy and manager the software components that are managed by Stackable. +== Purpose +The purpose of the Stackable architecture, if I had to put it in one sentence is to "run Kubernetes workloads without containers". -The agent behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. +This agent is the component in stack which registers itself with Kubernetes as an executor for workloads and then locally runs the assigned tasks - without using containers. +Instead components are installed locally on the host filesystem and executed via systemd units. + +The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. Instead it is based on the https://github.com/deislabs/krustlet[Krustlet], which is under active development by Microsoft. +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. + +We are currently evaluating whether or not we should instead use systemk and contribute to that project instead of building our own agent under issue + The agent registers itself as a node with a kube-apiserver 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: @@ -23,8 +31,8 @@ To avoid _normal_ Kubernetes pods being scheduled on the Stackable agent (it wou These taints _suggest_ to the Kubernetes scheduler that only pods with matching tolerations should be scheduled on this node. -## Installation -### Build from source +== Installation +=== Build from source Building from source is fairly straightforward if you have the rust toolchain installed. If you need to install this, generally the recommended way is to use https://rustup.rs/[rustup]. @@ -34,16 +42,16 @@ After rust is installed simply run To create the binary file in _target/debug_. -### Download binary +=== 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 +=== 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 +== Configuration -### Command Line Parameters +=== Command Line Parameters WARNING: Due to https://github.com/stackabletech/agent/issues/34[#34] it is not currently possible to specify these parameters directly on the commandline, please use a config file instead. @@ -51,7 +59,7 @@ The agent accepts the following command line parameters: include::config/commandline_args.adoc[] -### Config File +=== 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 as well and will be parsed before the actual command line. @@ -63,7 +71,7 @@ For parameters that are present in the file and on the command line, the command --server-cert-file=/etc/stackable/agent/secure/cert.crt --server-key-file=/etc/stackable/agent/secure/key.key -### Kubernetes Config +=== 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. @@ -71,7 +79,7 @@ The default location for the Kubernetes client config is _~/.kube/config_, if yo export KUBECONFIG=/etc/stackable/agent/kubeconfig -### Certificates +=== 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. @@ -87,7 +95,7 @@ The following example shows how to create these files using https://github.com/O # Convert key to pksc8 format openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in pki/private/krustlet1.key -out pkcs8.key -## Contributing +== 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. From 93f1858c40949b659aaa173d293333e86d1aa39d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 16:39:12 +0100 Subject: [PATCH 03/10] Refactored crate to be a lib instead of a binary crate and moved binaries to src/bin folder. Added additional binary to generate command line documentation. Moved agentconfig to own module directory. --- README.adoc | 7 +- .../commandline_args.adoc | 100 ++++++++++++++---- .../config_documentation/bootstrap_file.adoc | 0 .../config_directory.adoc | 0 .../config_documentation/data_directory.adoc | 0 .../config_documentation/hostname.adoc | 0 .../config_documentation/log_directory.adoc | 0 .../config_documentation/no_config.adoc | 0 .../package_directory.adoc | 0 .../plugin_directory.adoc | 0 .../server_cert_file.adoc | 0 .../server_ip_address.adoc | 0 .../config_documentation/server_key_file.adoc | 0 .../config_documentation/server_port.adoc | 0 .../config_documentation/tags.adoc | 0 src/{agentconfig.rs => agentconfig/mod.rs} | 17 --- src/{main.rs => bin/agent.rs} | 7 +- src/bin/generate_doc.rs | 12 +++ src/lib.rs | 2 + 19 files changed, 98 insertions(+), 47 deletions(-) rename {config => documentation}/commandline_args.adoc (50%) rename src/{ => agentconfig}/config_documentation/bootstrap_file.adoc (100%) rename src/{ => agentconfig}/config_documentation/config_directory.adoc (100%) rename src/{ => agentconfig}/config_documentation/data_directory.adoc (100%) rename src/{ => agentconfig}/config_documentation/hostname.adoc (100%) rename src/{ => agentconfig}/config_documentation/log_directory.adoc (100%) rename src/{ => agentconfig}/config_documentation/no_config.adoc (100%) rename src/{ => agentconfig}/config_documentation/package_directory.adoc (100%) rename src/{ => agentconfig}/config_documentation/plugin_directory.adoc (100%) rename src/{ => agentconfig}/config_documentation/server_cert_file.adoc (100%) rename src/{ => agentconfig}/config_documentation/server_ip_address.adoc (100%) rename src/{ => agentconfig}/config_documentation/server_key_file.adoc (100%) rename src/{ => agentconfig}/config_documentation/server_port.adoc (100%) rename src/{ => agentconfig}/config_documentation/tags.adoc (100%) rename src/{agentconfig.rs => agentconfig/mod.rs} (96%) rename src/{main.rs => bin/agent.rs} (97%) create mode 100644 src/bin/generate_doc.rs create mode 100644 src/lib.rs diff --git a/README.adoc b/README.adoc index c07853d..2eafb48 100644 --- a/README.adoc +++ b/README.adoc @@ -3,7 +3,7 @@ == Purpose The purpose of the Stackable architecture, if I had to put it in one sentence is to "run Kubernetes workloads without containers". -This agent is the component in stack which registers itself with Kubernetes as an executor for workloads and then locally runs the assigned tasks - without using containers. +This agent is the component in our stack which registers itself with Kubernetes as an executor for workloads and then locally runs the assigned tasks - without using containers. Instead components are installed locally on the host filesystem and executed via systemd units. The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. @@ -52,12 +52,9 @@ We do not at this time provide os packages, that is due to change in the near fu == Configuration === Command Line Parameters - -WARNING: Due to https://github.com/stackabletech/agent/issues/34[#34] it is not currently possible to specify these parameters directly on the commandline, please use a config file instead. - The agent accepts the following command line parameters: -include::config/commandline_args.adoc[] +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_. diff --git a/config/commandline_args.adoc b/documentation/commandline_args.adoc similarity index 50% rename from config/commandline_args.adoc rename to documentation/commandline_args.adoc index f96758f..9291423 100644 --- a/config/commandline_args.adoc +++ b/documentation/commandline_args.adoc @@ -1,6 +1,30 @@ +### hostname + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +The hostname to register the node under in Kubernetes - defaults to system hostname. + + +### server-cert-file + +*Default value*: No default value + +*Required*: false + +*Multiple values:*: false + + +The certificate file for the local webserver which the Krustlet starts. + + ### config-directory *Default value*: /opt/stackable/config @@ -10,34 +34,45 @@ *Multiple values:*: false -This directory will serve as starting point for all log files which this service creates.Every service will get its own subdirectories created within this directory - for every service start a new subdirectory will be created to show a full history of configuration that was used for this service. -ConfigMaps that are mounted into the pod that describes this service will be created relative to these run directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory. +This directory will serve as starting point for all log files which this service creates. + +Every service will get its own subdirectories created within this directory - for every service start a +new subdirectory will be created to show a full history of configuration that was used for this service. + +ConfigMaps which are specified in the pod that describes this service will be created relative to these run +directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory. + +WARNING: This allows anybody who can specify pods more or less full access to the file system on the machine running the agent! The agent will need full access to this directory and tries to create it if it does not exist. -### no-config +### data-directory -*Default value*: No default value +*Default value*: /var/stackable/agent/data *Required*: false *Multiple values:*: false -If this option is specified, any file referenced in AGENT_CONF environment variable will be ignored. +The directory where the stackable agent should keep its working data. -### server-bind-ip +### log-directory -*Default value*: No default value +*Default value*: /opt/stackable/logs *Required*: false *Multiple values:*: false -The local IP to register as the node's ip with the apiserver. Will be automatically set to the first address of the first non-loopback interface if not specified. +This directory will serve as starting point for all log files which this service creates. +Every service will get its own subdirectory created within this directory. +Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory. + +The agent will need full access to this directory and tries to create it if it does not exist. ### tag @@ -49,10 +84,12 @@ The local IP to register as the node's ip with the apiserver. Will be automatica *Multiple values:*: true +A "key=value" pair that should be assigned to this agent as tag. This can be specified multiple times to assign additional tags. + Tags are the main way of identifying nodes to assign services to later on. -### server-cert-file +### no-config *Default value*: No default value @@ -61,7 +98,31 @@ Tags are the main way of identifying nodes to assign services to later on. *Multiple values:*: false -The certificate file for the local webserver which the Krustlet starts. +If this option is specified, any file referenced in AGENT_CONF environment variable will be ignored. + + +### server-port + +*Default value*: 3000 + +*Required*: false + +*Multiple values:*: false + + +Port to listen on for callbacks. + + +### bootstrap-file + +*Default value*: /etc/kubernetes/bootstrap-kubelet.conf + +*Required*: false + +*Multiple values:*: false + + +The bootstrap file to use in case Kubernetes bootstraping is used to add the agent. ### server-key-file @@ -76,31 +137,30 @@ The certificate file for the local webserver which the Krustlet starts. Private key file (in PKCS8 format) to use for the local webserver the Krustlet starts. -### package-directory +### server-bind-ip -*Default value*: /opt/stackable/packages +*Default value*: No default value *Required*: false *Multiple values:*: false -This directory will serve as starting point for packages that are needed by pods assigned to this node. - Packages will be downloaded into the "_download" folder at thetop level of this folder as archives and remain there for potential future use. -Archives will the be extracted directly into this folder in subdirectories following the namingscheme of "productname-productversion". - The agent will need full access to this directory and tries to create it if it does not exist. +The local IP to register as the node's ip with the apiserver. Will be automatically set to the first address of the first non-loopback interface if not specified. -### log-directory +### package-directory -*Default value*: /opt/stackable/logs +*Default value*: /opt/stackable/packages *Required*: false *Multiple values:*: false -This directory will serve as starting point for all log files which this service creates.Every service will get its own subdirectory created within this directory. -Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory. +This directory will serve as starting point for packages that are needed by pods assigned to this node.\n Packages will be downloaded into the "_download" folder at the top level of this folder as archives and remain there for potential future use. + +Archives will the be extracted directly into this folder in subdirectories following the naming +scheme of "productname-productversion". The agent will need full access to this directory and tries to create it if it does not exist. \ No newline at end of file diff --git a/src/config_documentation/bootstrap_file.adoc b/src/agentconfig/config_documentation/bootstrap_file.adoc similarity index 100% rename from src/config_documentation/bootstrap_file.adoc rename to src/agentconfig/config_documentation/bootstrap_file.adoc diff --git a/src/config_documentation/config_directory.adoc b/src/agentconfig/config_documentation/config_directory.adoc similarity index 100% rename from src/config_documentation/config_directory.adoc rename to src/agentconfig/config_documentation/config_directory.adoc diff --git a/src/config_documentation/data_directory.adoc b/src/agentconfig/config_documentation/data_directory.adoc similarity index 100% rename from src/config_documentation/data_directory.adoc rename to src/agentconfig/config_documentation/data_directory.adoc diff --git a/src/config_documentation/hostname.adoc b/src/agentconfig/config_documentation/hostname.adoc similarity index 100% rename from src/config_documentation/hostname.adoc rename to src/agentconfig/config_documentation/hostname.adoc diff --git a/src/config_documentation/log_directory.adoc b/src/agentconfig/config_documentation/log_directory.adoc similarity index 100% rename from src/config_documentation/log_directory.adoc rename to src/agentconfig/config_documentation/log_directory.adoc diff --git a/src/config_documentation/no_config.adoc b/src/agentconfig/config_documentation/no_config.adoc similarity index 100% rename from src/config_documentation/no_config.adoc rename to src/agentconfig/config_documentation/no_config.adoc diff --git a/src/config_documentation/package_directory.adoc b/src/agentconfig/config_documentation/package_directory.adoc similarity index 100% rename from src/config_documentation/package_directory.adoc rename to src/agentconfig/config_documentation/package_directory.adoc diff --git a/src/config_documentation/plugin_directory.adoc b/src/agentconfig/config_documentation/plugin_directory.adoc similarity index 100% rename from src/config_documentation/plugin_directory.adoc rename to src/agentconfig/config_documentation/plugin_directory.adoc diff --git a/src/config_documentation/server_cert_file.adoc b/src/agentconfig/config_documentation/server_cert_file.adoc similarity index 100% rename from src/config_documentation/server_cert_file.adoc rename to src/agentconfig/config_documentation/server_cert_file.adoc diff --git a/src/config_documentation/server_ip_address.adoc b/src/agentconfig/config_documentation/server_ip_address.adoc similarity index 100% rename from src/config_documentation/server_ip_address.adoc rename to src/agentconfig/config_documentation/server_ip_address.adoc diff --git a/src/config_documentation/server_key_file.adoc b/src/agentconfig/config_documentation/server_key_file.adoc similarity index 100% rename from src/config_documentation/server_key_file.adoc rename to src/agentconfig/config_documentation/server_key_file.adoc diff --git a/src/config_documentation/server_port.adoc b/src/agentconfig/config_documentation/server_port.adoc similarity index 100% rename from src/config_documentation/server_port.adoc rename to src/agentconfig/config_documentation/server_port.adoc diff --git a/src/config_documentation/tags.adoc b/src/agentconfig/config_documentation/tags.adoc similarity index 100% rename from src/config_documentation/tags.adoc rename to src/agentconfig/config_documentation/tags.adoc diff --git a/src/agentconfig.rs b/src/agentconfig/mod.rs similarity index 96% rename from src/agentconfig.rs rename to src/agentconfig/mod.rs index 1b0fbc3..eb29805 100644 --- a/src/agentconfig.rs +++ b/src/agentconfig/mod.rs @@ -300,27 +300,10 @@ impl AgentConfig { } Ok(doc_string) } - - fn gen_docs() { - // TODO: this needs to be moved to a build.rs type of thing - use std::env; - use std::fs; - use std::path::PathBuf; - - let target_file = PathBuf::from("config/commandline_args.adoc"); - - // We have unwraps in here, as this is supposed to be called during the build process, - // it shouldn't even be part of the codebase itself. - // Once this is moved out the unwraps are fine, because a failure during build is ok if - // something is wrong. - let test = AgentConfig::get_documentation().unwrap(); - fs::write(&target_file, test).unwrap(); - } } impl Configurable for AgentConfig { fn get_config_description() -> Configuration { - AgentConfig::gen_docs(); Configuration { name: "Stackable Agent", version: "0.1", diff --git a/src/main.rs b/src/bin/agent.rs similarity index 97% rename from src/main.rs rename to src/bin/agent.rs index 2d3d0d1..d00859d 100644 --- a/src/main.rs +++ b/src/bin/agent.rs @@ -8,11 +8,8 @@ use kubelet::Kubelet; use log::{info, warn}; use stackable_config::ConfigBuilder; -use crate::agentconfig::AgentConfig; -use crate::provider::StackableProvider; - -mod agentconfig; -mod provider; +use stackable_agent::agentconfig::AgentConfig; +use stackable_agent::provider::StackableProvider; #[tokio::main(threaded_scheduler)] async fn main() -> anyhow::Result<()> { diff --git a/src/bin/generate_doc.rs b/src/bin/generate_doc.rs new file mode 100644 index 0000000..4dd6408 --- /dev/null +++ b/src/bin/generate_doc.rs @@ -0,0 +1,12 @@ +fn main() { + use stackable_agent::agentconfig::AgentConfig; + use std::env; + use std::fs; + use std::path::PathBuf; + + let target_file = PathBuf::from("documentation/commandline_args.adoc"); + + // Unwrap should be fine here, this will currently get called + let test = AgentConfig::get_documentation().unwrap(); + fs::write(&target_file, test).unwrap(); +} diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..3d25c5b --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,2 @@ +pub mod agentconfig; +pub mod provider; From 94338cdc62d5ecc048e1fcb95d612717cb5cf31c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 16:42:21 +0100 Subject: [PATCH 04/10] Fixed double colon in generated docs --- src/agentconfig/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/agentconfig/mod.rs b/src/agentconfig/mod.rs index eb29805..24321ae 100644 --- a/src/agentconfig/mod.rs +++ b/src/agentconfig/mod.rs @@ -288,7 +288,7 @@ impl AgentConfig { option.default.unwrap_or("No default value") )); doc_string.push_str(&format!("*Required*: {}\n\n", option.required)); - doc_string.push_str(&format!("*Multiple values:*: {}\n\n\n", option.list)); + doc_string.push_str(&format!("*Multiple values:* {}\n\n\n", option.list)); // We have not yet specified a documentation string for all options, as an interim // solution we use the help string for the docs, if no proper doc has been written yet. From 6a4336678c97f647c50ed8c47d88d8e5af37deaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 16:45:33 +0100 Subject: [PATCH 05/10] Expanded on what exactly the purpose of this project is. --- README.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.adoc b/README.adoc index 2eafb48..17944ad 100644 --- a/README.adoc +++ b/README.adoc @@ -6,6 +6,9 @@ The purpose of the Stackable architecture, if I had to put it in one sentence is This agent is the component in our stack which registers itself with Kubernetes as an executor for workloads and then locally runs the assigned tasks - without using containers. Instead components are installed locally on the host filesystem and executed via systemd units. +This allows using the fabulous orchestration options offered by Kubernetes to describe the necessary infrastructure while leaving aside the extra overhead and complexity that are added by running services in containers. +Additionally, as we are already using a Kubernetes cluster, this will fairly easily allow defining hybrid scenarios where some services run on pure Kubernetes and others are orchestrated on bare-metal. + The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. Instead it is based on the https://github.com/deislabs/krustlet[Krustlet], which is under active development by Microsoft. From c3c87f36625c77ed0cdcdc8d8944ee83ad074934 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 16:46:58 +0100 Subject: [PATCH 06/10] Fixed heading characters in generated doc. --- src/agentconfig/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/agentconfig/mod.rs b/src/agentconfig/mod.rs index 24321ae..bb13d86 100644 --- a/src/agentconfig/mod.rs +++ b/src/agentconfig/mod.rs @@ -282,7 +282,7 @@ impl AgentConfig { pub fn get_documentation() -> Result { let mut doc_string = String::new(); for option in AgentConfig::get_options() { - doc_string.push_str(&format!("\n\n\n### {}\n\n", option.name)); + doc_string.push_str(&format!("\n\n\n=== {}\n\n", option.name)); doc_string.push_str(&format!( "*Default value*: {}\n\n", option.default.unwrap_or("No default value") From 9d557deab2e1519f2f714c1a50466a0f5a4c5ca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 16:58:51 +0100 Subject: [PATCH 07/10] Adressed last batch of comments I missed. --- README.adoc | 4 ++-- src/bin/generate_doc.rs | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.adoc b/README.adoc index 17944ad..dc1559e 100644 --- a/README.adoc +++ b/README.adoc @@ -9,7 +9,7 @@ Instead components are installed locally on the host filesystem and executed via This allows using the fabulous orchestration options offered by Kubernetes to describe the necessary infrastructure while leaving aside the extra overhead and complexity that are added by running services in containers. Additionally, as we are already using a Kubernetes cluster, this will fairly easily allow defining hybrid scenarios where some services run on pure Kubernetes and others are orchestrated on bare-metal. -The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. +The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. Instead it is based on the https://github.com/deislabs/krustlet[Krustlet], which is under active development by Microsoft. More specifically the functionality of this agent closely resembles that of https://github.com/virtual-kubelet/systemk[systemk]. @@ -17,7 +17,7 @@ The reason why both projects currently exist is simply that systemk was not arou We are currently evaluating whether or not we should instead use systemk and contribute to that project instead of building our own agent under issue -The agent registers itself as a node with a kube-apiserver will be considered by the Kubernetes scheduler for workloads (pods). +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: |=== diff --git a/src/bin/generate_doc.rs b/src/bin/generate_doc.rs index 4dd6408..7b6573f 100644 --- a/src/bin/generate_doc.rs +++ b/src/bin/generate_doc.rs @@ -7,6 +7,5 @@ fn main() { let target_file = PathBuf::from("documentation/commandline_args.adoc"); // Unwrap should be fine here, this will currently get called - let test = AgentConfig::get_documentation().unwrap(); - fs::write(&target_file, test).unwrap(); + fs::write(&target_file, AgentConfig::get_documentation().unwrap()).unwrap(); } From bb230759d4dbf1e9d924978eed7352d80b3d6ac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Fri, 22 Jan 2021 22:58:54 +0100 Subject: [PATCH 08/10] Adressed comments from Sigi. Also renamed agentconfig module to config as this was repeated verbatim in the struct name AgentConfig. --- documentation/commandline_args.adoc | 112 +++++++++--------- src/bin/agent.rs | 2 +- src/bin/generate_doc.rs | 23 ++-- .../config_documentation/bootstrap_file.adoc | 0 .../config_directory.adoc | 0 .../config_documentation/data_directory.adoc | 0 .../config_documentation/hostname.adoc | 0 .../config_documentation/log_directory.adoc | 0 .../config_documentation/no_config.adoc | 0 .../package_directory.adoc | 0 .../plugin_directory.adoc | 0 .../server_cert_file.adoc | 0 .../server_ip_address.adoc | 0 .../config_documentation/server_key_file.adoc | 0 .../config_documentation/server_port.adoc | 0 .../config_documentation/tags.adoc | 0 src/{agentconfig => config}/mod.rs | 6 +- src/lib.rs | 2 +- 18 files changed, 77 insertions(+), 68 deletions(-) rename src/{agentconfig => config}/config_documentation/bootstrap_file.adoc (100%) rename src/{agentconfig => config}/config_documentation/config_directory.adoc (100%) rename src/{agentconfig => config}/config_documentation/data_directory.adoc (100%) rename src/{agentconfig => config}/config_documentation/hostname.adoc (100%) rename src/{agentconfig => config}/config_documentation/log_directory.adoc (100%) rename src/{agentconfig => config}/config_documentation/no_config.adoc (100%) rename src/{agentconfig => config}/config_documentation/package_directory.adoc (100%) rename src/{agentconfig => config}/config_documentation/plugin_directory.adoc (100%) rename src/{agentconfig => config}/config_documentation/server_cert_file.adoc (100%) rename src/{agentconfig => config}/config_documentation/server_ip_address.adoc (100%) rename src/{agentconfig => config}/config_documentation/server_key_file.adoc (100%) rename src/{agentconfig => config}/config_documentation/server_port.adoc (100%) rename src/{agentconfig => config}/config_documentation/tags.adoc (100%) rename src/{agentconfig => config}/mod.rs (98%) diff --git a/documentation/commandline_args.adoc b/documentation/commandline_args.adoc index 9291423..f3f6ec7 100644 --- a/documentation/commandline_args.adoc +++ b/documentation/commandline_args.adoc @@ -1,161 +1,161 @@ -### hostname +=== tag *Default value*: No default value *Required*: false -*Multiple values:*: false +*Multiple values:* true -The hostname to register the node under in Kubernetes - defaults to system hostname. +A "key=value" pair that should be assigned to this agent as tag. This can be specified multiple times to assign additional tags. + +Tags are the main way of identifying nodes to assign services to later on. -### server-cert-file +=== server-key-file *Default value*: No default value *Required*: false -*Multiple values:*: false +*Multiple values:* false -The certificate file for the local webserver which the Krustlet starts. +Private key file (in PKCS8 format) to use for the local webserver the Krustlet starts. -### config-directory +=== log-directory -*Default value*: /opt/stackable/config +*Default value*: /opt/stackable/logs *Required*: false -*Multiple values:*: false +*Multiple values:* false This directory will serve as starting point for all log files which this service creates. - -Every service will get its own subdirectories created within this directory - for every service start a -new subdirectory will be created to show a full history of configuration that was used for this service. - -ConfigMaps which are specified in the pod that describes this service will be created relative to these run -directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory. - -WARNING: This allows anybody who can specify pods more or less full access to the file system on the machine running the agent! +Every service will get its own subdirectory created within this directory. +Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory. The agent will need full access to this directory and tries to create it if it does not exist. -### data-directory +=== hostname -*Default value*: /var/stackable/agent/data +*Default value*: No default value *Required*: false -*Multiple values:*: false +*Multiple values:* false -The directory where the stackable agent should keep its working data. +The hostname to register the node under in Kubernetes - defaults to system hostname. -### log-directory +=== server-cert-file -*Default value*: /opt/stackable/logs +*Default value*: No default value *Required*: false -*Multiple values:*: false +*Multiple values:* false -This directory will serve as starting point for all log files which this service creates. -Every service will get its own subdirectory created within this directory. -Anything that is then specified in the log4j config or similar files will be resolved relatively to this directory. - -The agent will need full access to this directory and tries to create it if it does not exist. +The certificate file for the local webserver which the Krustlet starts. -### tag +=== no-config *Default value*: No default value *Required*: false -*Multiple values:*: true +*Multiple values:* false -A "key=value" pair that should be assigned to this agent as tag. This can be specified multiple times to assign additional tags. - -Tags are the main way of identifying nodes to assign services to later on. +If this option is specified, any file referenced in AGENT_CONF environment variable will be ignored. -### no-config +=== bootstrap-file -*Default value*: No default value +*Default value*: /etc/kubernetes/bootstrap-kubelet.conf *Required*: false -*Multiple values:*: false +*Multiple values:* false -If this option is specified, any file referenced in AGENT_CONF environment variable will be ignored. +The bootstrap file to use in case Kubernetes bootstraping is used to add the agent. -### server-port +=== server-bind-ip -*Default value*: 3000 +*Default value*: No default value *Required*: false -*Multiple values:*: false +*Multiple values:* false -Port to listen on for callbacks. +The local IP to register as the node's ip with the apiserver. Will be automatically set to the first address of the first non-loopback interface if not specified. -### bootstrap-file +=== data-directory -*Default value*: /etc/kubernetes/bootstrap-kubelet.conf +*Default value*: /var/stackable/agent/data *Required*: false -*Multiple values:*: false +*Multiple values:* false -The bootstrap file to use in case Kubernetes bootstraping is used to add the agent. +The directory where the stackable agent should keep its working data. -### server-key-file +=== config-directory -*Default value*: No default value +*Default value*: /opt/stackable/config *Required*: false -*Multiple values:*: false +*Multiple values:* false -Private key file (in PKCS8 format) to use for the local webserver the Krustlet starts. +This directory will serve as starting point for all log files which this service creates. +Every service will get its own subdirectories created within this directory - for every service start a +new subdirectory will be created to show a full history of configuration that was used for this service. -### server-bind-ip +ConfigMaps which are specified in the pod that describes this service will be created relative to these run +directories - unless the mounts specify an absolute path, in which case it is allowed to break out of this directory. -*Default value*: No default value +WARNING: This allows anybody who can specify pods more or less full access to the file system on the machine running the agent! + +The agent will need full access to this directory and tries to create it if it does not exist. + + +=== server-port + +*Default value*: 3000 *Required*: false -*Multiple values:*: false +*Multiple values:* false -The local IP to register as the node's ip with the apiserver. Will be automatically set to the first address of the first non-loopback interface if not specified. +Port to listen on for callbacks. -### package-directory +=== package-directory *Default value*: /opt/stackable/packages *Required*: false -*Multiple values:*: false +*Multiple values:* false This directory will serve as starting point for packages that are needed by pods assigned to this node.\n Packages will be downloaded into the "_download" folder at the top level of this folder as archives and remain there for potential future use. diff --git a/src/bin/agent.rs b/src/bin/agent.rs index d00859d..74f8641 100644 --- a/src/bin/agent.rs +++ b/src/bin/agent.rs @@ -8,7 +8,7 @@ use kubelet::Kubelet; use log::{info, warn}; use stackable_config::ConfigBuilder; -use stackable_agent::agentconfig::AgentConfig; +use stackable_agent::config::AgentConfig; use stackable_agent::provider::StackableProvider; #[tokio::main(threaded_scheduler)] diff --git a/src/bin/generate_doc.rs b/src/bin/generate_doc.rs index 7b6573f..eaa0962 100644 --- a/src/bin/generate_doc.rs +++ b/src/bin/generate_doc.rs @@ -1,11 +1,20 @@ +/// This is a helper binary which generates the file _documentation/commandline_args.adoc_ which +/// contains documentation of the available command line options for the agent binary. +/// +/// It gets the content by calling get_documontation from the AgentConfig struct. +/// +/// * Panics +/// This will panic if an error occurs when trying to write the file. + fn main() { - use stackable_agent::agentconfig::AgentConfig; - use std::env; + use stackable_agent::config::AgentConfig; use std::fs; - use std::path::PathBuf; - - let target_file = PathBuf::from("documentation/commandline_args.adoc"); - // Unwrap should be fine here, this will currently get called - fs::write(&target_file, AgentConfig::get_documentation().unwrap()).unwrap(); + let target_file = "documentation/commandline_args.adoc"; + fs::write(target_file, AgentConfig::get_documentation()).unwrap_or_else(|err| { + panic!( + "Could not write documentation to [{}]: {}", + target_file, err + ) + }); } diff --git a/src/agentconfig/config_documentation/bootstrap_file.adoc b/src/config/config_documentation/bootstrap_file.adoc similarity index 100% rename from src/agentconfig/config_documentation/bootstrap_file.adoc rename to src/config/config_documentation/bootstrap_file.adoc diff --git a/src/agentconfig/config_documentation/config_directory.adoc b/src/config/config_documentation/config_directory.adoc similarity index 100% rename from src/agentconfig/config_documentation/config_directory.adoc rename to src/config/config_documentation/config_directory.adoc diff --git a/src/agentconfig/config_documentation/data_directory.adoc b/src/config/config_documentation/data_directory.adoc similarity index 100% rename from src/agentconfig/config_documentation/data_directory.adoc rename to src/config/config_documentation/data_directory.adoc diff --git a/src/agentconfig/config_documentation/hostname.adoc b/src/config/config_documentation/hostname.adoc similarity index 100% rename from src/agentconfig/config_documentation/hostname.adoc rename to src/config/config_documentation/hostname.adoc diff --git a/src/agentconfig/config_documentation/log_directory.adoc b/src/config/config_documentation/log_directory.adoc similarity index 100% rename from src/agentconfig/config_documentation/log_directory.adoc rename to src/config/config_documentation/log_directory.adoc diff --git a/src/agentconfig/config_documentation/no_config.adoc b/src/config/config_documentation/no_config.adoc similarity index 100% rename from src/agentconfig/config_documentation/no_config.adoc rename to src/config/config_documentation/no_config.adoc diff --git a/src/agentconfig/config_documentation/package_directory.adoc b/src/config/config_documentation/package_directory.adoc similarity index 100% rename from src/agentconfig/config_documentation/package_directory.adoc rename to src/config/config_documentation/package_directory.adoc diff --git a/src/agentconfig/config_documentation/plugin_directory.adoc b/src/config/config_documentation/plugin_directory.adoc similarity index 100% rename from src/agentconfig/config_documentation/plugin_directory.adoc rename to src/config/config_documentation/plugin_directory.adoc diff --git a/src/agentconfig/config_documentation/server_cert_file.adoc b/src/config/config_documentation/server_cert_file.adoc similarity index 100% rename from src/agentconfig/config_documentation/server_cert_file.adoc rename to src/config/config_documentation/server_cert_file.adoc diff --git a/src/agentconfig/config_documentation/server_ip_address.adoc b/src/config/config_documentation/server_ip_address.adoc similarity index 100% rename from src/agentconfig/config_documentation/server_ip_address.adoc rename to src/config/config_documentation/server_ip_address.adoc diff --git a/src/agentconfig/config_documentation/server_key_file.adoc b/src/config/config_documentation/server_key_file.adoc similarity index 100% rename from src/agentconfig/config_documentation/server_key_file.adoc rename to src/config/config_documentation/server_key_file.adoc diff --git a/src/agentconfig/config_documentation/server_port.adoc b/src/config/config_documentation/server_port.adoc similarity index 100% rename from src/agentconfig/config_documentation/server_port.adoc rename to src/config/config_documentation/server_port.adoc diff --git a/src/agentconfig/config_documentation/tags.adoc b/src/config/config_documentation/tags.adoc similarity index 100% rename from src/agentconfig/config_documentation/tags.adoc rename to src/config/config_documentation/tags.adoc diff --git a/src/agentconfig/mod.rs b/src/config/mod.rs similarity index 98% rename from src/agentconfig/mod.rs rename to src/config/mod.rs index bb13d86..ace92c2 100644 --- a/src/agentconfig/mod.rs +++ b/src/config/mod.rs @@ -10,7 +10,7 @@ use pnet::datalink; use stackable_config::{ConfigOption, Configurable, Configuration}; use thiserror::Error; -use crate::agentconfig::AgentConfigError::{ArgumentParseError, WrongArgumentCount}; +use crate::config::AgentConfigError::{ArgumentParseError, WrongArgumentCount}; #[derive(Error, Debug)] pub enum AgentConfigError { @@ -279,7 +279,7 @@ impl AgentConfig { .map_err(|_| anyhow::anyhow!("invalid utf-8 hostname string")) } - pub fn get_documentation() -> Result { + pub fn get_documentation() -> String { let mut doc_string = String::new(); for option in AgentConfig::get_options() { doc_string.push_str(&format!("\n\n\n=== {}\n\n", option.name)); @@ -298,7 +298,7 @@ impl AgentConfig { doc_string.push_str(&option.documentation); } } - Ok(doc_string) + doc_string } } diff --git a/src/lib.rs b/src/lib.rs index 3d25c5b..84c6e89 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,2 +1,2 @@ -pub mod agentconfig; +pub mod config; pub mod provider; From 7fb1d53c4caf32c0e78ab13dab60c0f560e6a497 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 25 Jan 2021 17:36:03 +0100 Subject: [PATCH 09/10] Adressed Lars' comments. --- README.adoc | 15 ++++----------- src/bin/generate_doc.rs | 4 ++-- src/config/mod.rs | 2 +- 3 files changed, 7 insertions(+), 14 deletions(-) diff --git a/README.adoc b/README.adoc index dc1559e..86b1f9d 100644 --- a/README.adoc +++ b/README.adoc @@ -1,21 +1,14 @@ = Stackable Agent == Purpose -The purpose of the Stackable architecture, if I had to put it in one sentence is to "run Kubernetes workloads without containers". - -This agent is the component in our stack which registers itself with Kubernetes as an executor for workloads and then locally runs the assigned tasks - without using containers. -Instead components are installed locally on the host filesystem and executed via systemd units. - -This allows using the fabulous orchestration options offered by Kubernetes to describe the necessary infrastructure while leaving aside the extra overhead and complexity that are added by running services in containers. -Additionally, as we are already using a Kubernetes cluster, this will fairly easily allow defining hybrid scenarios where some services run on pure Kubernetes and others are orchestrated on bare-metal. - -The agent in principle behaves similar to a https://github.com/virtual-kubelet/virtual-kubelet[virtual kubelet], but is not implemented using the virtual kubelet framework. -Instead it is based on the https://github.com/deislabs/krustlet[Krustlet], which is under active development by Microsoft. +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. -We are currently evaluating whether or not we should instead use systemk and contribute to that project instead of building our own agent under issue +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[#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: diff --git a/src/bin/generate_doc.rs b/src/bin/generate_doc.rs index eaa0962..7396294 100644 --- a/src/bin/generate_doc.rs +++ b/src/bin/generate_doc.rs @@ -1,9 +1,9 @@ /// This is a helper binary which generates the file _documentation/commandline_args.adoc_ which /// contains documentation of the available command line options for the agent binary. /// -/// It gets the content by calling get_documontation from the AgentConfig struct. +/// It gets the content by calling [`stackable_agent::config::AgentConfig::get_documentation()`] /// -/// * Panics +/// # Panics /// This will panic if an error occurs when trying to write the file. fn main() { diff --git a/src/config/mod.rs b/src/config/mod.rs index ace92c2..ab7923b 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -284,7 +284,7 @@ impl AgentConfig { for option in AgentConfig::get_options() { doc_string.push_str(&format!("\n\n\n=== {}\n\n", option.name)); doc_string.push_str(&format!( - "*Default value*: {}\n\n", + "*Default value*: `{}`\n\n", option.default.unwrap_or("No default value") )); doc_string.push_str(&format!("*Required*: {}\n\n", option.required)); From 8b926400bdf0e33bf959ed60eb6ae5f144114acf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 25 Jan 2021 21:08:42 +0100 Subject: [PATCH 10/10] Missed a few comments. --- README.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.adoc b/README.adoc index 86b1f9d..aa7f496 100644 --- a/README.adoc +++ b/README.adoc @@ -8,7 +8,7 @@ In principle this behavior is similar to that of the the https://github.com/virt 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[#42] +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: @@ -29,7 +29,7 @@ These taints _suggest_ to the Kubernetes scheduler that only pods with matching == Installation === Build from source -Building from source is fairly straightforward if you have the rust toolchain installed. +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 @@ -43,7 +43,7 @@ We do not at this time provide pre-compiled binaries, as we are still in the pro 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! +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 @@ -53,10 +53,10 @@ 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_. +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 as well 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 paramaters from both, file and commandline, will be used. +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 @@ -67,7 +67,7 @@ For parameters that are present in the file and on the command line, the command === 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. +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