Merge pull request #76 from aserto-dev/config-doc

Add topaz configuration document

docs/config.md

@@ -0,0 +1,182 @@
+# Topaz configuration
+The main configuration for Topaz can be devided in 3 main sections:
+1. Common configuration
+2. Auth configuration - optional
+3. Decision logger configuration - optional
+
+## Topaz configuration environment variables
+
+---
+> The topaz service configuration is built using the [spf13/viper](https://github.com/spf13/viper) library so all configuration parameters can be passed to the topazd service as environment variable with the **TOPAZ_** prefix. 
+---
+
+If you use topaz CLI to generate your configuration file by default it will add the TOPAZ_DIR environment variable to the path configurations. By default this is empty and considered an NOP addition, but it can easily allow you to specify the desired value to the run/start topaz CLI command with the `-e` flag. 
+
+By default if you run/start the topaz container using the topaz CLI the following environment variables will be set in your topaz container:
+- TOPAZ_CERTS_DIR - default $HOME/.config/topaz - the directory where topaz will load/generate the certs
+- TOPAZ_CFG_DIR - default $HOME/.config/topaz - the directory from where topaz will load the configuration file
+- TOPAZ_EDS_DIR - default $HOME/.config/topaz - the directory where topaz will store the edge directory DB
+
+Both run and start topaz CLI commands allow passing optional environment variables to your running container using the -e flag. This will allow you to use any desired environment variable in your configuration file as long as you pass it to the container. 
+
+## 1. Common configuration
+
+### a. Logging
+The [logging mechanism](https://github.com/aserto-dev/logger) for topaz is based on [zerolog](https://github.com/rs/zerolog) and has the following available settings:
+ - *prod* - boolean - if set to false the entire log output will be written using a zerolog ConsoleWriter, setting this to true will write the errors to the stderr output and other logs to the stdout 
+ - *log_level* - string - this value is parsed by zerolog to match desired logging level (default: info), available levels: trace, debug, info, warn, error, fatal and panic
+ - *grpc_log_level* - string - same as above available values, however this is specific for the logged grpc messages, having the default value set to warn
+
+```
+logging:
+  prod: true
+  log_level: debug
+```
+
+### b. API
+The API configuration is divided in 3 sections:
+#### 1. grpc
+The grpc section allows configuring the listen address, the connection timeout and the certificates. 
+- *listen_address* - string - allows the topaz GRPC server to spin up on the requested port (default: "0.0.0.0:8282")
+- *connection_timeout_seconds* - uint32 - sets the timeout for a [connection establishment](https://pkg.go.dev/google.golang.org/grpc#ConnectionTimeout) (default: 120)
+- *certs* - certs.TLSCredsConfig - based on [aserto-dev/certs](https://github.com/aserto-dev/certs) package allows setting the paths of your certificate files. If you do not have your certificates in the specified paths, topaz will generate self-signed certificates for you. By default topaz will generate the certificates in ` ~/.config/topaz/certs/` path
+Example:
+```
+grpc:
+  listen_address: "localhost:8282"
+  connection_timeout_seconds: 160 
+  certs:
+    tls_cert_path: "/app/grpc.crt"
+    tls_key_path: "/app/grpc.key"
+    tls_ca_cert_path: "/app/grpc-ca.crt"
+```
+
+#### 2. gateway
+The gateway section allows configuring the [grpc gateway](https://github.com/grpc-ecosystem/grpc-gateway) for your topaz authorizer. 
+
+- *listen_address* - string - allows the topaz Gateway server to spin up on the requested port (default: "0.0.0.0:8383")
+- *http* - boolean - when set to true it allows the gateway service to respond to plain http request (default: false)
+- *certs* - certs.TLSCredsConfig - based on [aserto-dev/certs](https://github.com/aserto-dev/certs) package allows setting the paths of your certificate files. If you do not have your certificates in the specified paths, topaz will generate self-signed certificates for you. By default topaz will generate the certificates in ` ~/.config/topaz/certs/` path
+- *allowed_origins* - []string - allows setting the paths for the [CORS handler](https://github.com/rs/cors)
+
+Detailed information about the gateway http server timeout configuration is available [here](https://pkg.go.dev/net/http#Server)
+- *read_timeout* - time.Duration - default value set to 2 * time.Second (default: 2000000000) 
+- *read_header_timeout* - time.Duration - default value set to 2 * time.Second (default: 2000000000) 
+- *write_timeout* - time.Duration - default value set to 2 * time.Second (default: 2000000000) 
+- *idle_timeout* - time.Duration - default is set to 30 * time.Second (default: 30000000000)
+
+Example:
+```
+gateway:
+  listen_address: "localhost:8383"
+  http: false
+  certs:
+    tls_cert_path: "/app/gateway.crt"
+    tls_key_path: "/app/gateway.key"
+    tls_ca_cert_path: "/app/gateway-ca.crt"
+  allowed_origins:
+  - https://*.aserto.com
+  - https://*aserto-console.netlify.app
+  - https://*aserto-playground.netlify.app
+```
+
+#### 3. health
+The health is the simplest of these section as it only allows to set the listen address of the health server. By default the listen address is set to 0.0.0.0:8484
+
+To check the health of your service you can use the available [grpc-health-probe](https://github.com/grpc-ecosystem/grpc-health-probe) 
+Example:
+```
+grpc-health-probe --addr=localhost:8484
+status: SERVING
+```
+
+### c. Directory Service
+
+Topaz is able to communicate with a directory service based on the [pb-directory proto](https://github.com/aserto-dev/pb-directory) definitions. When the remote address is configured to localhost, topaz is able to spin-up a grpc [edge directory service](https://github.com/aserto-dev/go-edge-ds) based on [bbolt](https://pkg.go.dev/go.etcd.io/bbolt)
+
+The remote address can also be configured to a service that implements the proto definitions (for example, the Postgres-based Aserto directory service). In this case, Topaz will NOT spin-up a local edge directory service, and instead send all directory requests to this remote service.
+- *address* - string - address:port of the remote directory service
+- *api_key* - string - API key for the directory
+- *tenant_id* - string - the directory tenant ID 
+
+Example (using the hosted Aserto directory):
+```
+directory_service:
+  remote:
+    address: "directory.prod.aserto.com:8443"
+    api_key: <Your Aserto Directory Access Key>
+    tenant_id: <Your Aserto Tenant ID>
+```
+
+### d. OPA
+
+The OPA configuration section represent the [runtime configuration](https://github.com/aserto-dev/runtime/blob/main/config.go). The main elements of the runtime configuration are:
+- *local_bundles* - runtime.LocalBundlesConfig - allows the runtime to run with a local bundle (local path or local policy OCI image)
+- *instance_id* - string - represent the unique identifier of the runtime 
+- *plugins_error_limit* - int - represents the maximum number of errors that an OPA plugin can trigger before killing the runtime
+- *graceful_shutdown_period_seconds* - int - passed to the runtime plugin manager, this represents the allowed time to stop the running plugins gracefully
+- *max_plugin_wait_time_seconds* - int -  passed to the runtime plugin manager, this represents the maximum wait time for a plugin to spin-up (default: 30)
+- *flags* - runtime.Flags - currently only the boolean *enable_status_plugin* is available. When set to true the runtime status is affected by the OPA status plugin 
+- *config* - runtime.OPAConfig - the details of the [OPA configuration](https://www.openpolicyagent.org/docs/latest/configuration/)
+
+For more details regarding the OPA configuration see [examples folder](/docs/examples/)
+
+### e. JWT
+
+The JWT section allows setting a custom *acceptable_time_skew_seconds* - int - this specifies the duration in which exp (Expiry) and nbf (Not Before) claims may differ by (default: 5).
+
+
+## 2. Auth configuration (optional)
+By default Topaz authentication configuration is disabled, however if you want to configure API key basic authentication this section of the configuration allows you to set this up. 
+
+The options section allows you to specify overrides for specific paths if you want to enable the api key authentication or/and the anonymous authentication for these.
+
+Example:
+```
+auth:
+  api_keys:
+    dc8a1524dec311eda1ff8bd042196110: myuser@email.com
+  options:
+    default:
+      enable_api_key: true
+      enable_anonymous: false
+    overrides:
+      paths:
+        - /aserto.authorizer.v2.Authorizer/Info
+      override:
+        enable_anonymous: true
+        enable_api_key: false
+    
+```
+
+## 3. Decision logger configuration (optional)
+
+By default Topaz does not initiate a decision logger, however if you need to keep a history of the decisions taken by the **IS** API call a rolling logger based on [lumberjack](https://github.com/natefinch/lumberjack) is available to keep decision logs in a file.
+
+Example configuration:
+```
+decision_logger:
+  log_file_path: /tmp/mytopaz.log
+  max_file_size_mb: 50
+  max_file_count: 2
+```
+
+To use the decision logger the OPA configuration must contain the [configuration information](https://github.com/aserto-dev/topaz/blob/main/decision_log/plugin/plugin.go#L23) for the decision log plugin.
+
+Example of the decision log plugin configuration:
+```
+opa:
+ instance_id: "-"
+ graceful_shutdown_period_seconds: 2
+ local_bundles:
+   paths: []
+   skip_verification: true
+ config:
+   plugins:
+     aserto_decision_log:
+       enabled: true 
+       policy_info:
+         registry_service: 'ghcr.io'
+         registry_image: 'aserto-policies/policy-peoplefinder-rbac'
+         digest: 'b36c9fac3c4f3a20e524ef4eca4ac3170e30281fe003b80a499591043299c898'
+```

docs/examples/config-local-image.yaml

@@ -0,0 +1,45 @@
+# If you follow the [topaz quickstart guide](https://github.com/aserto-dev/topaz#quickstart) and you wish to run an local image that you built with [policy CLI](https://github.com/opcr-io/policy) you can use the `topaz configure -d -s -l ghcr.io/default:latest` to generate this example configuration.
+# In this case the `ghcr.io/default:latest` policy image is set as your *local_policy_image*. In this example this values is set with the assumption that you [build your policy image](https://openpolicycontainers.com/docs/cli/build) without setting a custom tag.
+# Using topaz with a local policy image gives you an easier method to ensure that your policies work as you desire before pushing an image to an upstream container registry. 
+# If you have started topaz with this configuration, if you rebuild the image, any changes will be reflected in your topaz runtime bundle. 
+---
+logging:
+  prod: true
+  log_level: info
+
+directory_service:
+  edge:
+    db_path: ${TOPAZ_DIR}/db/directory.db
+    seed_metadata: true
+
+  remote:
+    address: "0.0.0.0:9292"
+    insecure: true
+
+api:
+  grpc:
+    connection_timeout_seconds: 2
+    listen_address: "0.0.0.0:8282"
+    certs:
+      tls_key_path: "${TOPAZ_DIR}/certs/grpc.key"
+      tls_cert_path: "${TOPAZ_DIR}/certs/grpc.crt"
+      tls_ca_cert_path: "${TOPAZ_DIR}/certs/grpc-ca.crt"
+  gateway:
+    listen_address: "0.0.0.0:8383"
+    allowed_origins:
+    - https://*.aserto.com
+    - https://*aserto-console.netlify.app
+    certs:
+      tls_key_path: "${TOPAZ_DIR}/certs/gateway.key"
+      tls_cert_path: "${TOPAZ_DIR}/certs/gateway.crt"
+      tls_ca_cert_path: "${TOPAZ_DIR}/certs/gateway-ca.crt"
+  health:
+    listen_address: "0.0.0.0:8484"
+
+opa:
+  instance_id: "-"
+  graceful_shutdown_period_seconds: 2
+  local_bundles:
+    local_policy_image: ghcr.io/default:latest
+    watch: true
+    skip_verification: true

docs/examples/config-private-ghcr.yaml

@@ -0,0 +1,49 @@
+# To use a private policy image you need to fill the following configuation with the required information:
+# 1. Github PAT with the available rights to access private packages.
+# 2. Your organization
+# 3. Your policy image name and label
+---
+logging:
+  prod: true
+  log_level: debug
+
+directory_service:
+  edge:
+    db_path: ${TOPAZ_DIR}/db/directory.db
+    seed_metadata: false
+  remote:
+    address: "localhost:9292"
+    insecure: true
+
+api:
+  gateway:
+    allowed_origins:
+    - https://locahost
+  grpc:
+    connection_timeout_seconds: 2
+
+opa:
+  instance_id: "-"
+  graceful_shutdown_period_seconds: 2
+  local_bundles:
+    paths: []
+    skip_verification: true
+  config:
+    services:
+      acmecorp:
+        url: https://ghcr.io/
+        type: "oci"
+        response_header_timeout_seconds: 5
+        credentials:
+          bearer:
+            schema: "Bearer"
+            token: "<your_pat>"
+    bundles:
+      peoplefinder:
+        service: acmecorp
+        resource: "ghcr.io/<org>/<policy image name>:<policy image tag>"
+        persist: false
+        config:
+          polling:
+            min_delay_seconds: 60
+            max_delay_seconds: 120

docs/examples/config-public-ghcr.yaml

@@ -0,0 +1,56 @@
+# If you follow the [topaz quickstart guide](https://github.com/aserto-dev/topaz#quickstart) this is the configuration generated by the `topaz configure -d -s -r ghcr.io/aserto-policies/policy-todo-rebac:latest -n todo` command. 
+---
+logging:
+  prod: true
+  log_level: info
+
+directory_service:
+  edge:
+    db_path: ${TOPAZ_DIR}/db/directory.db
+    seed_metadata: true
+
+  remote:
+    address: "0.0.0.0:9292"
+    insecure: true
+
+api:
+  grpc:
+    connection_timeout_seconds: 2
+    listen_address: "0.0.0.0:8282"
+    certs:
+      tls_key_path: "${TOPAZ_DIR}/certs/grpc.key"
+      tls_cert_path: "${TOPAZ_DIR}/certs/grpc.crt"
+      tls_ca_cert_path: "${TOPAZ_DIR}/certs/grpc-ca.crt"
+  gateway:
+    listen_address: "0.0.0.0:8383"
+    allowed_origins:
+    - https://*.aserto.com
+    - https://*aserto-console.netlify.app
+    certs:
+      tls_key_path: "${TOPAZ_DIR}/certs/gateway.key"
+      tls_cert_path: "${TOPAZ_DIR}/certs/gateway.crt"
+      tls_ca_cert_path: "${TOPAZ_DIR}/certs/gateway-ca.crt"
+  health:
+    listen_address: "0.0.0.0:8484"
+
+opa:
+  instance_id: "-"
+  graceful_shutdown_period_seconds: 2
+  local_bundles:
+    paths: []
+    skip_verification: true
+  config:
+    services:
+      ghcr:
+        url: https://ghcr.io
+        type: "oci"
+        response_header_timeout_seconds: 5
+    bundles:
+      todo:
+        service: ghcr
+        resource: "ghcr.io/aserto-policies/policy-todo-rebac:latest"
+        persist: false
+        config:
+          polling:
+            min_delay_seconds: 60
+            max_delay_seconds: 120

docs/examples/config-remote-dir.yaml

@@ -0,0 +1,43 @@
+# In this example configuration to allow topaz to interact with the Aserto Directory service you will need to fill in your directory access key and your tenant ID. 
+# You can find these values in the Aserto Console: for the directory access key you will find these values in the connections tab for Aserto Directory and to you will find the tenant ID in your account settings. 
+# In this example, as we use the policy todo image, we recommend setting up a Demo Citadel IDP connection to exercise the example policy paths with the users that have the correct permissions. 
+
+---
+logging:
+  prod: true
+  log_level: debug
+
+directory_service:
+  remote:
+    address: "directory.prod.aserto.com:8443"
+    api_key: <Your Aserto Directory Access Key>
+    tenant_id: <Your Aserto Tenant ID>
+
+api:
+  gateway:
+    allowed_origins:
+    - https://locahost
+  grpc:
+    connection_timeout_seconds: 2
+
+opa:
+  instance_id: "-"
+  graceful_shutdown_period_seconds: 2
+  local_bundles:
+    paths: []
+    skip_verification: true
+  config:
+    services:
+      acmecorp:
+        url: https://ghcr.io/
+        type: "oci"
+        response_header_timeout_seconds: 5
+    bundles:
+      peoplefinder:
+        service: acmecorp
+        resource: "ghcr.io/aserto-policies/policy-todo-rebac:latest"
+        persist: false
+        config:
+          polling:
+            min_delay_seconds: 60
+            max_delay_seconds: 120