From da6d61e1769e815c0204d99ba5e89805f6820472 Mon Sep 17 00:00:00 2001 From: shahargl Date: Sun, 13 Oct 2024 15:14:53 +0300 Subject: [PATCH 1/2] feat: better docs --- docs/deployment/configuration.mdx | 242 ++++++++++++++++++++++++++ docs/deployment/gke.mdx | 2 +- docs/deployment/kubernetes.mdx | 273 +++++++++++++++++++++++++++++- docs/mint.json | 1 + 4 files changed, 511 insertions(+), 7 deletions(-) create mode 100644 docs/deployment/configuration.mdx diff --git a/docs/deployment/configuration.mdx b/docs/deployment/configuration.mdx new file mode 100644 index 0000000000..2d423fea09 --- /dev/null +++ b/docs/deployment/configuration.mdx @@ -0,0 +1,242 @@ +--- +title: "Configuration" +sidebarTitle: "Configuration" +--- + +## Background + +Keep is highly configurable through environment variables. This allows you to customize various aspects of both the backend and frontend components without modifying the code. Environment variables can be set in your deployment environment, such as in your Kubernetes configuration, Docker Compose file, or directly on your host system. + + +## Backend Environment Variables + +### General + +General configuration variables control the core behavior of the Keep server. These settings determine fundamental aspects such as the server's host, port, and whether certain components like the scheduler and consumer are enabled. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **KEEP_HOST** | Specifies the host for the Keep server | No | "0.0.0.0" | Valid hostname or IP address | +| **PORT** | Specifies the port on which the backend server runs | No | 8080 | Any valid port number | +| **SCHEDULER** | Enables or disables the workflow scheduler | No | "true" | "true" or "false" | +| **CONSUMER** | Enables or disables the consumer | No | "true" | "true" or "false" | +| **KEEP_VERSION** | Specifies the Keep version | No | "unknown" | Valid version string | +| **KEEP_API_URL** | Specifies the Keep API URL | No | Constructed from HOST and PORT | Valid URL | +| **KEEP_STORE_RAW_ALERTS** | Enables storing of raw alerts | No | "false" | "true" or "false" | +| **TENANT_CONFIGURATION_RELOAD_TIME** | Time in minutes to reload tenant configurations | No | 5 | Positive integer | + +### Logging and Environment + +Logging and environment configuration determines how Keep generates and formats log output. These settings are crucial for debugging, monitoring, and understanding the behavior of your Keep instance in different environments. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **LOG_LEVEL** | Sets the logging level for the application | No | "INFO" | "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL" | +| **ENVIRONMENT** | Specifies the environment the application is running in | No | "production" | "development", "staging", "production" | +| **LOG_FORMAT** | Specifies the log format | No | "open_telemetry" | "open_telemetry", "dev_terminal" | +| **LOG_AUTH_PAYLOAD** | Enables logging of authentication payload | No | "false" | "true" or "false" | + + +### Database + +Database configuration is crucial for Keep's data persistence. Keep supports various database backends through SQLAlchemy, allowing flexibility in choosing and configuring your preferred database system. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **DATABASE_CONNECTION_STRING** | Specifies the database connection URL | Yes | None | Valid SQLAlchemy connection string | +| **DATABASE_POOL_SIZE** | Sets the database connection pool size | No | 5 | Positive integer | +| **DATABASE_MAX_OVERFLOW** | Sets the maximum overflow for the connection pool | No | 10 | Positive integer | +| **DATABASE_ECHO** | Enables SQLAlchemy echo mode for debugging | No | False | Boolean (True/False) | +| **DB_CONNECTION_NAME** | Specifies the Cloud SQL connection name | No | "keephq-sandbox:us-central1:keep" | Valid Cloud SQL connection string | +| **DB_SERVICE_ACCOUNT** | Service account for database impersonation | No | None | Valid service account email | +| **SKIP_DB_CREATION** | Skips database creation and migrations | No | "false" | "true" or "false" | + +### Resource Provisioning + +Resource provisioning settings control how Keep sets up initial resources. This configuration is particularly important for automating the setup process and ensuring that necessary resources are available when Keep starts. + +To elaborate on resource provisioning and its configuration, please see [provisioning docs](provision/overview). + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **PROVISION_RESOURCES** | Enables or disables resource provisioning | No | "true" | "true" or "false" | + + +### Authentication + +Authentication configuration determines how Keep verifies user identities and manages access control. These settings are essential for securing your Keep instance and integrating with various authentication providers. + +For specifc authentication type configuration, please see [authentication docs](authentication/overview). + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **AUTH_TYPE** | Specifies the authentication type | No | "noauth" | "auth0", "keycloak", "db", "noauth", "oauth2proxy" | +| **JWT_SECRET** | Secret key for JWT token generation and validation | Yes | None | Any strong secret string | +| **JWT_ALGORITHM** | Algorithm used for JWT | No | "HS256" | Any valid JWT algorithm | +| **KEEP_DEFAULT_USERNAME** | Default username for the admin user | No | "keep" | Any valid username string | +| **KEEP_DEFAULT_PASSWORD** | Default password for the admin user | No | "keep" | Any strong password string | +| **KEEP_FORCE_RESET_DEFAULT_PASSWORD** | Forces reset of default user password | No | "false" | "true" or "false" | +| **KEEP_DEFAULT_API_KEYS** | Comma-separated list of default API keys to provision | No | "" | Format: "name:role:secret,name:role:secret" | + +### Secrets Management + +Secrets Management configuration specifies how Keep handles sensitive information. This is crucial for securely storing and accessing confidential data such as API keys and integrations credentials. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **SECRET_MANAGER_TYPE** | Defines the type of secret manager to use | Yes | "FILE" | "FILE", "GCP", "K8S", "VAULT" | +| **SECRET_MANAGER_DIRECTORY** | Directory for storing secrets when using file-based secret management | No | "/state" | Any valid directory path | + +### OpenTelemetry + +OpenTelemetry configuration enables comprehensive observability for Keep. These settings allow you to integrate Keep with various monitoring and tracing systems, enhancing your ability to debug and optimize performance. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **OTEL_SERVICE_NAME** | OpenTelemetry service name | No | "keep-api" | Valid service name string | +| **SERVICE_NAME** | Alternative for OTEL_SERVICE_NAME | No | "keep-api" | Valid service name string | +| **OTEL_EXPORTER_OTLP_ENDPOINT** | OpenTelemetry collector endpoint | No | None | Valid URL | +| **OTLP_ENDPOINT** | Alternative for OTEL_EXPORTER_OTLP_ENDPOINT | No | None | Valid URL | +| **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | OpenTelemetry traces endpoint | No | None | Valid URL | +| **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | OpenTelemetry logs endpoint | No | None | Valid URL | +| **OTEL_EXPORTER_OTLP_METRICS_ENDPOINT** | OpenTelemetry metrics endpoint | No | None | Valid URL | +| **CLOUD_TRACE_ENABLED** | Enables Google Cloud Trace exporter | No | "false" | "true" or "false" | +| **METRIC_OTEL_ENABLED** | Enables OpenTelemetry metrics | No | "" | "true" or "false" | + +### WebSocket Server (Pusher/Soketi) + +WebSocket server configuration controls real-time communication capabilities in Keep. These settings are important for enabling features that require instant updates and notifications. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **PUSHER_DISABLED** | Disables Pusher integration | No | "false" | "true" or "false" | +| **PUSHER_HOST** | Hostname of the Pusher server | No | None | Valid hostname or IP address | +| **PUSHER_PORT** | Port of the Pusher server | No | None | Any valid port number | +| **PUSHER_APP_ID** | Pusher application ID | Yes (if using Pusher) | None | Valid Pusher App ID | +| **PUSHER_APP_KEY** | Pusher application key | Yes (if using Pusher) | None | Valid Pusher App Key | +| **PUSHER_APP_SECRET** | Pusher application secret | Yes (if using Pusher) | None | Valid Pusher App Secret | +| **PUSHER_USE_SSL** | Enables SSL for Pusher connection | No | False | Boolean (True/False) | +| **PUSHER_CLUSTER** | Pusher cluster | No | None | Valid Pusher cluster name | + + +### OpenAPI + +OpenAPI configuration is used for integrating with OpenAI services. These settings are important if you're utilizing OpenAI capabilities within Keep for tasks such as natural language processing or AI-assisted operations. + + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **OPENAI_API_KEY** | API key for OpenAI services | No | None | Valid OpenAI API key | + + +### Posthog + +Posthog configuration controls Keep's integration with the Posthog analytics platform. These settings are useful for tracking usage patterns and gathering insights about how your Keep instance is being used. + + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **POSTHOG_API_KEY** | API key for PostHog analytics | No | "phc_muk9qE3TfZsX3SZ9XxX52kCGJBclrjhkP9JxAQcm1PZ" | Valid PostHog API key | +| **ENABLE_POSTHOG_API** | Enables or disables PostHog API | No | "false" | "true" or "false" | +| **DISABLE_POSTHOG** | Disables PostHog integration | No | "false" | "true" or "false" | + +### Ngrok + +Ngrok configuration enables secure tunneling to your Keep instance. These settings are particularly useful for development or when you need to expose your local Keep instance to the internet securely. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **USE_NGROK** | Enables ngrok for tunneling | No | "false" | "true" or "false" | +| **NGROK_AUTH_TOKEN** | Authentication token for ngrok | No | None | Valid ngrok auth token | +| **NGROK_DOMAIN** | Custom domain for ngrok | No | None | Valid domain name | + + +### Elasticsearch + +Elasticsearch configuration controls Keep's integration with Elasticsearch for advanced search capabilities. These settings are important if you're using Elasticsearch to enhance Keep's search functionality and performance. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **ELASTIC_ENABLED** | Enables Elasticsearch integration | No | "false" | "true" or "false" | +| **ELASTIC_API_KEY** | API key for Elasticsearch | Yes (if using Elasticsearch) | None | Valid Elasticsearch API key | +| **ELASTIC_HOSTS** | Comma-separated list of Elasticsearch hosts | Yes (if using Elasticsearch) | None | Valid Elasticsearch host URLs | +| **ELASTIC_USER** | Username for Elasticsearch basic auth | No | None | Valid username | +| **ELASTIC_PASSWORD** | Password for Elasticsearch basic auth | No | None | Valid password | +| **ELASTIC_INDEX_SUFFIX** | Suffix for Elasticsearch index names | Yes (for single tenant) | None | Any valid string | + +### Redis Configuration + +Redis configuration specifies the connection details for Keep's Redis instance. Redis is used for various caching and queueing purposes, making these settings important for optimizing Keep's performance and scalability. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **REDIS_HOST** | Redis server hostname | No | "localhost" | Valid hostname or IP address | +| **REDIS_PORT** | Redis server port | No | 6379 | Valid port number | +| **REDIS_USERNAME** | Redis username | No | None | Valid username string | +| **REDIS_PASSWORD** | Redis password | No | None | Valid password string | + +### ARQ Configuration + +ARQ (Asynchronous Task Queue) configuration controls Keep's background task processing. These settings are crucial for managing how Keep handles long-running or scheduled tasks, ensuring efficient resource utilization and responsiveness. + + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **ARQ_BACKGROUND_FUNCTIONS** | Comma-separated list of background functions to run | No | None | Valid function names | +| **ARQ_KEEP_RESULT** | Duration to keep job results (in seconds) | No | 3600 | Positive integer | +| **ARQ_EXPIRES** | Default job expiration time (in seconds) | No | 3600 | Positive integer | +| **ARQ_EXPIRES_AI** | AI job expiration time (in seconds) | No | 3600000 | Positive integer | + +## Frontend Environment Variables + +Frontend configuration variables control the behavior and features of Keep's user interface. These settings are crucial for customizing the frontend's appearance, functionality, and integration with the backend services. + + +### General + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **API_URL** | Specifies the URL of the Keep backend API | Yes | None | Valid URL | + +### Authentication + +Authentication configuration determines how Keep verifies user identities and manages access control. These settings are essential for securing your Keep instance and integrating with various authentication providers. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **AUTH_TYPE** | Specifies the authentication type | No | "noauth" | "auth0", "keycloak", "db", "noauth", "oauth2proxy" | +| **NEXTAUTH_URL** | URL for NextAuth authentication | Yes | None | Valid URL | +| **NEXTAUTH_SECRET** | Secret key for NextAuth | Yes | None | Strong secret string + +### Posthog +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **POSTHOG_KEY** | PostHog API key for frontend analytics | No | None | Valid PostHog API key | +| **POSTHOG_HOST** | PostHog Host for frontend analytics | No | None | Valid PostHog Host | + +### Pusher + +Pusher configuration is essential for enabling real-time updates and communication in Keep's frontend. These settings allow the frontend to establish a WebSocket connection with the Pusher server, facilitating instant updates and notifications. + + +| Env var | Purpose | Required | Default Value | Valid options | +|:-------------------:|:-------:|:----------:|:-------------:|:-------------:| +| **PUSHER_DISABLED** | Disables Pusher integration | No | "false" | "true" or "false" | +| **PUSHER_HOST** | Hostname of the Pusher server | No | "localhost" | Valid hostname or IP address | +| **PUSHER_PORT** | Port of the Pusher server | No | 6001 | Valid port number | +| **PUSHER_APP_KEY** | Pusher application key | Yes (if Pusher enabled) | "keepappkey" | Valid Pusher App Key | +| **PUSHER_CLUSTER** | Pusher cluster | No | None | Valid Pusher cluster name | diff --git a/docs/deployment/gke.mdx b/docs/deployment/gke.mdx index 3eea2b7db7..dad98f3cd8 100644 --- a/docs/deployment/gke.mdx +++ b/docs/deployment/gke.mdx @@ -119,7 +119,7 @@ This ingress supports real-time communication and push updates for the frontend -### Prerequisits +### Prerequisites #### Domain e.g. keep.yourcomapny.com will be used to access Keep UI. diff --git a/docs/deployment/kubernetes.mdx b/docs/deployment/kubernetes.mdx index 593cd15ae4..ec62a8cd71 100644 --- a/docs/deployment/kubernetes.mdx +++ b/docs/deployment/kubernetes.mdx @@ -3,25 +3,286 @@ title: "Kubernetes" sidebarTitle: "Kubernetes" --- -Keep can be installed via Helm Chart. -First, add the Helm repository of Keep and pull the latest version of the chart: +## Overview + +### High Level Architecture +Keep architecture composes of two main components: + +1. **Keep API** (aka keep backend) - a pythonic server (FastAPI) which serves as Keep's backend +2. **Keep Frontend** - (aka keep ui) - a nextjs server which serves as Keep's frontend + +Keep is also using the following (optional) components: + +3. **Websocket Server** - a soketi server serves as the websocket server to allow real time updates from the server to the browser without refreshing the page +4. **Database Server** - a database which Keep reads/writes for persistency. Keep currently supports sqlite, postgres, mysql and sql server (enterprise) + +### Kubernetes Architecture +Keep's Kubernetes architecture is composed of several components, each with its own set of Kubernetes resources. Here's a detailed breakdown of each component and its associated resources: + +#### General Components +Keep uses kubernetes secret manager to store secrets such as integrations credentials. + +| Kubernetes Resource | Purpose | Required/Optional | Source | +|:-------------------:|:-------:|:-----------------:|:------:| +| ServiceAccount | Provides an identity for processes that run in a Pod. Used mainly for Keep API to access kubernetes secret manager | Required | [serviceaccount.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/serviceaccount.yaml) | +| Role | Defines permissions for the ServiceAccount to manage secrets | Required | [role-secret-manager.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/role-secret-manager.yaml) | +| RoleBinding | Associates the Role with the ServiceAccount | Required | [role-binding-secret-manager.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/role-binding-secret-manager.yaml) | +| Secret Deletion Job | Cleans up Keep-related secrets when the Helm release is deleted | Required | [delete-secret-job.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/delete-secret-job.yaml) | + +#### Frontend Components + +| Kubernetes Resource | Purpose | Required/Optional | Source | +|:-------------------:|:-------:|:-----------------:|:------:| +| Frontend Deployment | Manages the frontend application containers | Required | [frontend.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/frontend.yaml) | +| Frontend Service | Exposes the frontend deployment within the cluster | Required | [frontend-service.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/frontend-service.yaml) | +| Frontend Ingress | Exposes the frontend service to external traffic | Optional | [frontend-ingress.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/frontend-ingress.yaml) | +| Frontend Route (OpenShift) | Exposes the frontend service to external traffic on OpenShift | Optional | [frontend-route.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/frontend-route.yaml) | +| Frontend HorizontalPodAutoscaler | Automatically scales the number of frontend pods | Optional | [frontend-hpa.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/frontend-hpa.yaml) | +| Frontend BackendConfig (GKE) | Configures health checks for Google Cloud Load Balancing | Optional (GKE only) | [backendconfig.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/gke/frontend-gke-healthcheck-config.yaml) | + +#### Backend Components + +| Kubernetes Resource | Purpose | Required/Optional | Source | +|:-------------------:|:-------:|:-----------------:|:------:| +| Backend Deployment | Manages the backend application containers | Required (if backend enabled) | [backend.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/backend.yaml) | +| Backend Service | Exposes the backend deployment within the cluster | Required (if backend enabled) | [backend-service.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/backend-service.yaml) | +| Backend Ingress | Exposes the backend service to external traffic | Optional | [backend-ingress.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/backend-ingress.yaml) | +| Backend Route (OpenShift) | Exposes the backend service to external traffic on OpenShift | Optional | [backend-route.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/backend-route.yaml) | +| Backend HorizontalPodAutoscaler | Automatically scales the number of backend pods | Optional | [backend-hpa.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/backend-hpa.yaml) | +| BackendConfig (GKE) | Configures health checks for Google Cloud Load Balancing | Optional (GKE only) | [backendconfig.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/gke/backend-gke-healthcheck-config.yaml) | + +#### Database Components +Database components are optional. You can spin up Keep with external database that doesn't by Keep or event not deployed in Kubernetes + +| Kubernetes Resource | Purpose | Required/Optional | Source | +|:-------------------:|:-------:|:-----------------:|:------:| +| Database Deployment | Manages the database containers (e.g. MySQL or Postgres) | Optional | [db.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/db.yaml) | +| Database Service | Exposes the database deployment within the cluster | Required (if deployment enabled) | [db-service.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/db-service.yaml) | +| Database PersistentVolume | Provides persistent storage for the database | Optional | [db-pv.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/db-pv.yaml) | +| Database PersistentVolumeClaim | Claims the persistent storage for the database | Optional | [db-pvc.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/db-pvc.yaml) | + +#### WebSocket Components +WebSocket components are optional. You can spin up Keep with external database that doesn't by Keep or event not deployed in Kubernetes + +| Kubernetes Resource | Purpose | Required/Optional | Source | +|:-------------------:|:-------:|:-----------------:|:------:| +| WebSocket Deployment | Manages the WebSocket server containers (Soketi) | Optional | [websocket-server.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/websocket-server.yaml) | +| WebSocket Service | Exposes the WebSocket deployment within the cluster | Required (if WebSocket enabled) | [websocket-server-service.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/websocket-server-service.yaml) | +| WebSocket Ingress | Exposes the WebSocket service to external traffic | Optional | [websocket-server-ingress.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/websocket-server-ingress.yaml) | +| WebSocket Route (OpenShift) | Exposes the WebSocket service to external traffic on OpenShift | Optional | [websocket-server-route.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/websocket-server-route.yaml) | +| WebSocket HorizontalPodAutoscaler | Automatically scales the number of WebSocket server pods | Optional | [websocket-server-hpa.yaml](https://github.com/keephq/helm-charts/blob/main/charts/keep/templates/websocket-server-hpa.yaml) | + +These tables provide a comprehensive overview of the Kubernetes resources used in the Keep architecture, organized by component type. Each table describes the purpose of each resource, indicates whether it's required or optional, and provides a direct link to the source template in the Keep Helm charts GitHub repository. + + +### Kubernetes Configuration +This sections covers only kubernetes-specific configuration. To learn about Keep-specific configuration, controlled by environment variables, see [Keep Configuration](/deployment/configuration) + +Each of these components can be customized via the `values.yaml` file in the Helm chart. + + +Below are key configurations that can be adjusted for each component. + +#### 1. Frontend Configuration +```yaml +frontend: + enabled: true # Enable or disable the frontend deployment. + replicaCount: 1 # Number of frontend replicas. + image: + repository: us-central1-docker.pkg.dev/keephq/keep/keep-ui + pullPolicy: Always # Image pull policy (Always, IfNotPresent). + tag: latest + serviceAccount: + create: true # Create a new service account. + name: "" # Service account name (empty for default). + podAnnotations: {} # Annotations for frontend pods. + podSecurityContext: {} # Security context for the frontend pods. + securityContext: {} # Security context for the containers. + service: + type: ClusterIP # Service type (ClusterIP, NodePort, LoadBalancer). + port: 3000 # Port on which the frontend service is exposed. + # Enable or disable frontend ingress. + ingress: + enabled: true + hosts: + - host: keep.yourcompany.com + paths: + - path: / + pathType: Prefix + tls: + - hosts: + - keep.yourcompany.com + secretName: frontend-tls # Secret for TLS certificates. +``` + +#### 2. Backend Configuration +```yaml +backend: + enabled: true # Enable or disable the backend deployment. + replicaCount: 1 # Number of backend replicas. + image: + repository: us-central1-docker.pkg.dev/keephq/keep/keep-api + pullPolicy: Always # Image pull policy (Always, IfNotPresent). + serviceAccount: + create: true # Create a new service account. + name: "" # Service account name (empty for default). + podAnnotations: {} # Annotations for backend pods. + podSecurityContext: {} # Security context for backend pods. + securityContext: {} # Security context for containers. + service: + type: ClusterIP # Service type (ClusterIP, NodePort, LoadBalancer). + port: 8080 # Port on which the backend API is exposed. + ingress: + enabled: true # Enable or disable backend ingress. + hosts: + - paths: + - path: / + pathType: Prefix ``` + +#### 3. WebSocket Server Configuration +Keep uses Soketi as its websocket server. To learn how to configure it, please see [Soketi docs](https://github.com/soketi/charts/tree/master/charts/soketi). + + +#### 4. Database Configuration +Keep supports plenty of database (e.g. postgresql, mysql, sqlite, etc). It is out of scope to describe here how to deploy all of them to k8s. If you have specific questions - [contact us](https://slack.keephq.dev) and we will be happy to help. + + + +## Installation +The recommended way to install Keep in kubernetes is via Helm Chart. + +First, add the Helm repository of Keep and pull the latest version of the chart: +```bash helm repo add keephq https://keephq.github.io/helm-charts helm pull keephq/keep ``` -Next, install using: -``` -helm install keep keephq/keep +Next, install Keep using: +```bash + +# it is always recommended to install Keep in a seperate namespace +kubectl create ns keep + +helm install -n keep keep keephq/keep --set namespace=keep ``` + +## Expose Keep with port-forward Notice for it to work locally, you'll need this port forwarding: ``` # expose the UI -kubectl port-forward svc/keep-frontend 3000:3000 +kubectl -n keep port-forward svc/keep-frontend 3000:3000 +``` + +## Expose Keep with ingress (HTTP) +Once you are ready to expose Keep to the outer world, Keep's helm chart comes with pre-configured ingress + +```bash +kubectl -n keep get ingress +NAME CLASS HOSTS ADDRESS PORTS AGE +keep-backend 34.54.XXX.XXX 80 75m +keep-frontend 34.54.XXX.XXX 80 70m +``` + +## Expose Keep with ingress (HTTPS) + +#### Prerequisites + +1. Domain -e.g. keep.yourcomapny.com will be used to access Keep UI. +2. Certificate - both private key (.pem) and certificate (.crt) + +#### Store the certificate as kubernetes secret +Assuming the private key stored as `tls.key` and the certificate stored as `tls.crt`: + +```bash +kubectl create secret tls frontend-tls --cert=./tls.crt --key=./tls.key -n keep + +# you should see: +secret/frontend-tls created +``` + +#### Upgrade Keep to use TLS + +Create this `values.yaml`: +** Note to change keep.yourcomapny.com to your domain ** + +```yaml +namespace: keep +frontend: + ingress: + enabled: true + hosts: + - host: keep.yourcompany.com + paths: + - path: / + pathType: Prefix + tls: + - hosts: + - keep.yourcompany.com + secretName: frontend-tls + env: + - name: NEXTAUTH_SECRET + value: secret + # Changed the NEXTAUTH_URL + - name: NEXTAUTH_URL + value: https://keep.yourcompany.com + # https://github.com/nextauthjs/next-auth/issues/600 + - name: VERCEL + value: 1 + - name: API_URL + value: http://keep-backend:8080 + - name: NEXT_PUBLIC_POSTHOG_KEY + value: "phc_muk9qE3TfZsX3SZ9XxX52kCGJBclrjhkP9JxAQcm1PZ" + - name: NEXT_PUBLIC_POSTHOG_HOST + value: https://app.posthog.com + - name: ENV + value: development + - name: NODE_ENV + value: development + - name: HOSTNAME + value: 0.0.0.0 + - name: PUSHER_HOST + value: keep-websocket.default.svc.cluster.local + - name: PUSHER_PORT + value: 6001 + - name: PUSHER_APP_KEY + value: "keepappkey" + +backend: + env: + # Added the KEEP_API_URL + - name: KEEP_API_URL + value: https://keep.yourcompany.com/backend + - name: DATABASE_CONNECTION_STRING + value: mysql+pymysql://root@keep-database:3306/keep + - name: SECRET_MANAGER_TYPE + value: k8s + - name: PORT + value: "8080" + - name: PUSHER_APP_ID + value: 1 + - name: PUSHER_APP_KEY + value: keepappkey + - name: PUSHER_APP_SECRET + value: keepappsecret + - name: PUSHER_HOST + value: keep-websocket + - name: PUSHER_PORT + value: 6001 +database: + # this is needed since o/w helm install fails. if you are using different storageClass, edit the value here. + pvc: + storageClass: "standard-rwo" ``` +Now, update Keep: +``` +helm upgrade -n keep keep keephq/keep -f values.yaml +``` + + To learn more about Keep's helm chart, see https://github.com/keephq/helm-charts/blob/main/README.md To discover about how to configure Keep using Helm, see auto generated helm-docs at https://github.com/keephq/helm-charts/blob/main/charts/keep/README.md diff --git a/docs/mint.json b/docs/mint.json index 2ac0189330..d1518d4ddf 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -56,6 +56,7 @@ { "group": "Deployment", "pages": [ + "deployment/configuration", { "group": "Authentication", "pages": [ From 6f9c465fe9df28dcd9fa0a3696de708046722e8a Mon Sep 17 00:00:00 2001 From: shahargl Date: Sun, 13 Oct 2024 15:22:06 +0300 Subject: [PATCH 2/2] feat: fix --- docs/deployment/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/deployment/configuration.mdx b/docs/deployment/configuration.mdx index 2d423fea09..bf73f00f32 100644 --- a/docs/deployment/configuration.mdx +++ b/docs/deployment/configuration.mdx @@ -58,7 +58,7 @@ Database configuration is crucial for Keep's data persistence. Keep supports var Resource provisioning settings control how Keep sets up initial resources. This configuration is particularly important for automating the setup process and ensuring that necessary resources are available when Keep starts. -To elaborate on resource provisioning and its configuration, please see [provisioning docs](provision/overview). +To elaborate on resource provisioning and its configuration, please see [provisioning docs](/deployment/provision/overview). | Env var | Purpose | Required | Default Value | Valid options | |:-------------------:|:-------:|:----------:|:-------------:|:-------------:| @@ -69,7 +69,7 @@ Resource provisioning settings control how Keep sets up initial resources. This Authentication configuration determines how Keep verifies user identities and manages access control. These settings are essential for securing your Keep instance and integrating with various authentication providers. -For specifc authentication type configuration, please see [authentication docs](authentication/overview). +For specifc authentication type configuration, please see [authentication docs](/deployment/authentication/overview). | Env var | Purpose | Required | Default Value | Valid options |