Add ADR to define default paths used by OS packages and agent

adr/ADR011-directory_structure.adoc

@@ -0,0 +1,81 @@
+= ADR011: Directory Structure Used by Stackable Components on Managed Hosts
+Sönke Liebau <soenke.liebau@stackable.de>
+v0.1, 12.03.2021
+:status: accepted
+
+* Status: accepted
+* Deciders:
+** Sönke Liebau
+* Date: 12.03.2021
+
+== Context and Problem Statement
+
+To run the Stackable platforms some components will need to be installed on the managed servers.
+We will offer OS packages for some distributions, currently deb and RPM packages are available.
+To make the components behave the same we would like to agree on some default directories and what content we will put there.
+
+This ADR is less to document alternative solutions, but rather to document the directory structure we agreed on, hence there are no alternative options discussed.
+Instead I have added excerpts from the https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html[Filesystem Hierarchy Standard] to illustrate why I think the chosen paths are the correct ones.
+
+== Decision
+
+----
+/
+├── etc
+│   └── opt
+│   └── stackable
+│   ├── agent
+│   │   └── secure
+│   ├── serviceconfig
+│   └── zookeeper-operator
+├── opt
+│   └── stackable
+│   ├── agent
+│   ├── packages
+│   └── zookeeper-operator
+└── var
+ ├── log
+ │   └── stackable
+ │   └── servicelogs
+ └── opt
+ └── stackable
+ └── agent
+----
+
+=== Binaries for Stackable Components
+
+In accordance with https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html#optAddonApplicationSoftwarePackages[3.13.1] we will install the binaries for our components under `/opt/stackable/<packagename>/binaryfile.
+
+In the example above there are subdirectories for the agent and the ZooKeeper operator which contain the executable files for these components.
+
+=== Packages
+
+For worker servers which are under management by our agent, we will need to install packages that contain the upstream software that is being rolled out by the agent.
+As this is is also third party software but being used by Stackable we will install these under `/opt/stackable/' as well, but put them under a subdirectory `packages`
+
+This only refers to the default setting the agent is configured with though, this path can be freely chosen by the user.
+
+=== Configuration Files for Stackable Components
+
+According to https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html#etcoptConfigurationFilesForOpt[3.7.4], if our binaries are kept under `/opt` we should keep the associated config files in `/etc/opt` and replicate the same folder structure here that can be found in `/opt`.
+
+Out of the current components, only the agent requires a config file that will be kept here.
+The agent also requires TLS keys, these will by default be kept in a `/etc/opt/stackable/agent/secret` - but this setting can be overridden in the agent config.
+
+=== Service Configuration
+Following the logic from above, config files that are written for the actual services that are managed by Stackable (Apache Kafka, Apache Hadoop, ...) should also reside in `/etc/opt/stackable`
+It doesn't make sense to call the containing directory `packages`, like the parent directory for the binaries, so instead I have renamed it to `serviceconfig` to better express what it actually contains.
+
+This only refers to the default setting the agent is configured with though, this path can be freely chosen by the user.
+
+=== Agent Working Directory
+The agent keeps a working directory on disk, in which it can sometimes place state, depending on configuration and used features.
+This directory can be configured in the agent, and will default to `/var/opt/stackable/agent` following https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html#varoptVariableDataForOpt[5.12.1]
+
+=== Log File
+
+Stackable components that have been installed from OS packages write their logs directly to the systemd journal.
+These need not have a log directory on disk by default.
+
+For the services that are managed by Stackable, log directories will be kept in per-service subdirectories under `/var/log/stackable/servicelogs`.
+This can be configured in the agent and is just the default value.