# Grafbase API

This reference documents the Kubernetes configuration options for the Grafbase API, which provides a GraphQL interface to the Grafbase platform. The chart provides all the needed services to run the API, including ClickHouse, PostgreSQL, and the MinIO S3 API.

The API chart also includes the object-storage service. It is a small stateless server that is responsible for serving an S3-compatible bucket populated by the api-web service with uploaded trusted documents, composed schemas, etc. When you use the `--graph-ref` argument or trusted documents, the gateway contacts that service.

## image

[Kubernetes Image Pull Policy](https://kubernetes.io/docs/concepts/containers/images/#updating-images)

**Defaults**:

```yaml
image:
  # Controls container image pulls
  pullPolicy: IfNotPresent
  # Container image repository
  repository: docker.io/grafbase/api
  # Image tag to use
  tag: latest
```

## autoscaling

[Kubernetes Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)

**Defaults**:

```yaml
autoscaling:
  # Enables autoscaling
  enabled: true
  # Minimum number of replicas
  minReplicas: 1
  # Maximum number of replicas
  maxReplicas: 2
  # Target CPU utilization percentage
  targetCPUUtilizationPercentage: 50
```

## ingress

[Kubernetes Ingress Docs](https://kubernetes.io/docs/concepts/services-networking/ingress/)

**Defaults**:

```yaml
ingress:
  # Enables ingress
  enabled: false
  # Ingress class
  className: 'nginx'
  hosts:
    # Hostnames and paths for the ingress
    - host: api.local
      paths:
        - path: /*
          pathType: ImplementationSpecific
          backend:
            serviceName: api
            servicePort: 8080
```

## serviceAccount

[Kubernetes Service Account Docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/)

**Defaults**:

```yaml
serviceAccount:
  # Controls service account creation
  create: true
  # Annotations to add to the service account
  annotations: {}
  # Service account name. Uses default if not set
  name: ''
```

## service

[Kubernetes Service Types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types)

**Defaults**:

```yaml
service:
  type: ClusterIP
  port: 80
  targetPort: 8080
  name: http
  nodePort: 30080
```

## objectStorageService

Configures the service for the object-storage pod, that is backed by a bucket, and allows authenticated resolution of graph refs and trusted documents.

[Kubernetes Service Types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types)

**Defaults**:

```yaml
objectStorageService:
  type: ClusterIP
  port: 80
  targetPort: 8080
  name: http
  nodePort: 30082
```

## configmap

Configuration values for the cluster configmap.

**Defaults**:

```yaml
configmap:
  # Enables configmap creation and env var mounting
  enabled: true
  name: ''
  values:
    # The port the service will expose
    PORT_WEB: 8080
    # The port the worker service will expose
    PORT_WORKER: 8080
    # The port the object-storage service will listen on
    PORT_OBJECT_STORAGE: 8080
    # Logging level configuration
    RUST_LOG: info
    # Connection URL for ClickHouse database
    CLICKHOUSE_URL: clickhouse://grafbase-enterprise-platform-clickhouse:9000
    # ClickHouse database name
    CLICKHOUSE_DB: analytics
    # ClickHouse username
    CLICKHOUSE_USER: grafbase
    # ClickHouse connection timeout in seconds
    CLICKHOUSE_TIMEOUT_SECS: 5
    # Maximum number of PostgreSQL connections
    PG_MAX_CONNECTIONS: 10
    # Minimum number of PostgreSQL connections
    PG_MIN_CONNECTIONS: 1
    # PostgreSQL connection timeout in seconds
    PG_CONNECT_TIMEOUT_SECS: 1
    # PostgreSQL connection acquisition timeout in seconds
    PG_ACQUIRE_TIMEOUT_SECS: 1
    # PostgreSQL idle connection timeout in seconds
    PG_IDLE_TIMEOUT_SECS: 300
    # Maximum lifetime of PostgreSQL connections in seconds
    PG_CONNECTION_MAX_LIFETIME_SECS: 3600
    # Enable or disable tracing
    ENABLE_TRACING: true
    # The base URL to use for links for Slack notifications and invite emails. Should point to the Grafbase dashboard.
    FRONTEND_URL: https://app.grafbase.com
    # Allowed CORS origins for the API
    CORS_ALLOWED_ORIGINS: "https://grafbase.com,https://app.grafbase.com"

    # The name of the bucket that will contain schemas, trusted documents, etc.
    GRAFBASE_OBJECT_STORAGE_S3_BUCKET_NAME: grafbase
    # The endpoint of the S3 compatible object store for the object-storage service. Optional.
    #
    # Use http://grafbase-enterprise-platform-minio:9000 for the opt-in minio here.
    GRAFBASE_OBJECT_STORAGE_S3_ENDPOINT: null
    # The access key id for the S3 compatible object store that backs the object-storage service. This is optional if AWS_ACCESS_KEY is set. It can be used to override it. Optional.
    GRAFBASE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: null
    # The region of the bucket used by object storage. Defaults to the default aws environment variables, and falls back to us-east-1. Optional.
    GRAFBASE_OBJECT_STORAGE_S3_REGION: null

    # === Authentication ===

    # The OpenID Connect issuer you want to accept id tokens from. This should match the issuer you configured for the dashoard. The JWKS endpoint will be discovered using the standard mechanisms from this issuer URL.
    GRAFBASE_OIDC_ISSUER: null
    # Optionally specify an OIDC client ID. The only effect of this setting is making the API validate this client ID is contained in the `aud` claim of incoming id token JWTs (those with GRAFBASE_OIDC_ISSUER as the issuer).
    GRAFBASE_OIDC_CLIENT_ID: null

    # === PostgreSQL with RDS ===

    # The following group of environment variables is an alternative to PG_CONNECTION_STRING to define how to connect to Postgres if you use AWS Aurora RDS. If defined, the API will use the AWS SDK to periodically generate a connection string, assuming it can find appropriate AWS credentials using the standard mechanisms.
    GRAFBASE_RDS_DATABASE_NAME: grafbase
    GRAFBASE_RDS_HOST: <from your aws dashboard>
    GRAFBASE_RDS_PORT: 5432
    GRAFBASE_RDS_REGION: us-east-1
    GRAFBASE_RDS_SEARCH_PATH: public
    GRAFBASE_RDS_USERNAME: grafbase
```

## secrets

Configuration values for the cluster secret.

**Defaults**:

```yaml
secrets:
  # Enables secret creation and env var mounting
  enabled: true
  name: ''
  values:
    # The secret key for symmetric encryption (access tokens)
    SYMMETRIC_ENCRYPTION_SECRET: thisisaverysecurekeythatis32byte
    # Password for ClickHouse database access
    CLICKHOUSE_PASSWORD: grafbase
    # PostgreSQL connection string. This will be ignored if RDS credentials are defined.
    PG_CONNECTION_STRING: postgresql://postgres:grafbase@grafbase-enterprise-platform-postgresql:5432/grafbase
    # The secret access key for the S3 compatible object store that backs the object-storage service. This is optional if AWS_SECRET_ACCESS_KEY is set. It can be used to override it. Optional.
    GRAFBASE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: null
```

## objectStorage

Configuration values for the object-storage pods.

```yaml
objectStorage:
  replicaCount: 1
  port: 8080
  resources:
    requests:
      cpu: 100m
      memory: 50Mi
    limits:
      cpu: 200m
      memory: 100Mi
```

## worker

Configuration values for the API background worker worker.

**Defaults**:

```yaml
worker:
  replicaCount: 1
  port: 8080
  resources: {}
```