Adding provisioning and server db config docs (#2322)

* Adding provisioning and server db config docs Adding provisioning and server db config docs * Update docs/docs/configuration/provisioning.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/provisioning.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/sidebars.js Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update docs/docs/configuration/server.md Co-authored-by: Adnan Rahić <adnan@kubeshop.io> * Update server.md * Update docs/docs/configuration/provisioning.md Co-authored-by: Jorge Padilla <jorge.esteban.padilla@gmail.com> * Update server.md --------- Co-authored-by: Julianne Fermi <julianne@kubeshop.io> Co-authored-by: Adnan Rahić <adnan@kubeshop.io> Co-authored-by: Jorge Padilla <jorge.esteban.padilla@gmail.com>
kubeshop · Apr 6, 2023 · dd8be94 · dd8be94
1 parent 49e3d60
commit dd8be94
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 5 deletions.
diff --git a/docs/docs/configuration/overview.md b/docs/docs/configuration/overview.md
@@ -1,10 +1,8 @@
 # Configuration Overview
 
-There is one way you can set configuration options in Tracetest. By using a configuration file, commonly known as the `tracetest.config.yaml` file.
-
-When using Docker, ensure that the configuration file is mounted to `/app/config.yaml` within the Tracetest Docker container.
-
-<!-- To view all the configuration options see the [config file reference page](./config-file-reference). -->
+There are several configuration options with Tracetest:
+- [Server configuration](./server) to set database connection information needed to connect to required PostgreSQL instance.
+- [Provisioning configuration](./provisioning) to 'preload' the Tracetest server with resources when first running the Tracetest server.
 
 ## Supported Trace Data Stores
 

diff --git a/docs/docs/configuration/provisioning.md b/docs/docs/configuration/provisioning.md
@@ -0,0 +1,49 @@
+# Provisioning server
+
+Tracetest allows a server to be provisioned the first time a new Tracetest server is installed and launched. Provisioning sets certain resources in the server to the specified values, allowing you to configure the server. It is convenient in a CI/CD flow where you want to launch a server with a specified configuration. 
+
+The server is provisioned by specifying a series of YAML snippets which will configure various resources. Each snippet is separated with the YAML separator, `---`.
+
+Currently, the following resources can be provisioned: 
+- DataStore
+- PollingProfile
+- Config
+- Demo
+
+For Docker-based installs, the provisioning file is placed in the `./tracetest/tracetest-provisioning.yaml` file by default when you run the `tracetest server install` command and select the `Using Docker Compose` option. The first time you start Tracetest with a `docker compose -f tracetest/docker-compose.yaml  up -d` command, the server will use the contents of this file to provision the server. To provision differently, you would alter the contents of the `tracetest-provisioning.yaml` file before launching Tracetest in Docker.
+
+This is an example of a `tracetest-provisioning.yaml` file:
+
+```yaml
+---
+type: DataStore
+spec:
+  name: otlp
+  type: otlp
+  isdefault: true
+---
+type: Config
+spec:
+  analyticsEnabled: true
+---
+type: PollingProfile
+spec:
+  name: Custom Profile
+  strategy: periodic
+  default: true
+  periodic:
+    timeout: 2m
+    retryDelay: 3s
+---
+type: Demo
+spec:
+  name: pokeshop
+  type: pokeshop
+  enabled: true
+  pokeshop:
+    httpEndpoint: http://demo-api:8081
+    grpcEndpoint: demo-api:8082
+```
+
+Alternatively, we support setting an environment variable called `TRACETEST_PROVISIONING` to provision the server when it is first started. Base64 encode the provisioning YAML you want to utilize and set the `TRACETEST_PROVISIONING` environment variable with the result. The Tracetest server will then provision based on the Base64 encoded provisioning data in this environment variable the first time it is launched.
+
diff --git a/docs/docs/configuration/server.md b/docs/docs/configuration/server.md
@@ -0,0 +1,31 @@
+# Configuring the Tracetest Server
+
+Tracetest requires a very minimal configuration to be launched, needing just the connection information to connect with the PostgreSQL database which is installed as part of the server install. There are a couple of ways to provide this database connection information.
+
+For Docker-based installs, the server configuration file is placed in the `./tracetest/tracetest.yaml` file by default when you run the `tracetest server install` command and select the `Using Docker Compose` option. The configuration file is mounted to `/app/config.yaml` within the Tracetest Docker container. When Tracetest is run with a `docker compose -f tracetest/docker-compose.yaml  up -d` command, the server will use the contents of this file to connect to the Postgres database. All other configuration data is stored in the Postgres instance.
+
+This is an example of a `tracetest.yaml` file:
+
+```yaml
+postgres:
+  host: postgres
+  user: postgres
+  password: postgres
+  port: 5432
+  dbname: postgres
+  params: sslmode=disable
+```
+
+Alternatively, we support setting a series of environment variables which can contain the connection information for the Postgres instance. If these environment variables are set, they will be used by the Tracetest server to connect to the database.
+
+The list of environment variables and example values is:
+- `TRACETEST_POSTGRES_HOST: "postgres"`
+- `TRACETEST_POSTGRES_PORT: "5432"`
+- `TRACETEST_POSTGRES_DBNAME: "postgres"`
+- `TRACETEST_POSTGRES_USER: "postgres"`
+- `TRACETEST_POSTGRES_PASSWORD: "postgres"`
+- `TRACETEST_POSTGRES_PARAMS: ""`
+
+
+You can also intitalize the server with a number of resources the first time it is launched by using [provisioning](./provisioning).
+
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -119,6 +119,16 @@ const sidebars = {
           id: "configuration/opentelemetry-collector-configuration-file-reference",
           label: "OpenTelemetry Collector Configuration File Reference",
         },
+        {
+          type: "doc",
+          id: "configuration/server",
+          label: "Tracetest Server Configuration",
+        },
+        {
+          type: "doc",
+          id: "configuration/provisioning",
+          label: "Provisioning a Tracetest Server",
+        },
         {
           type: "doc",
           id: "configuration/trace-polling",