From fdeb2e4b72d5b7a0aa258bd0337656f3a00ee619 Mon Sep 17 00:00:00 2001 From: Jonathan Whitaker Date: Mon, 3 Apr 2023 09:08:59 -0600 Subject: [PATCH] docs: improve OpenFGA Chart documentation with`values.schema.json` (#6) --- charts/openfga/Chart.yaml | 2 +- charts/openfga/README.md | 3 +- charts/openfga/templates/deployment.yaml | 54 ++++-- charts/openfga/templates/service.yaml | 4 +- charts/openfga/values.schema.json | 210 ++++++++++++++++++++++- charts/openfga/values.yaml | 64 +++---- 6 files changed, 283 insertions(+), 54 deletions(-) diff --git a/charts/openfga/Chart.yaml b/charts/openfga/Chart.yaml index 704a6b5..063b639 100644 --- a/charts/openfga/Chart.yaml +++ b/charts/openfga/Chart.yaml @@ -3,7 +3,7 @@ name: openfga description: A Kubernetes Helm chart for the OpenFGA project. type: application -version: 0.1.7 +version: 0.1.8 appVersion: "v0.4.2" home: "https://openfga.github.io/helm-charts/charts/openfga" diff --git a/charts/openfga/README.md b/charts/openfga/README.md index 42fe4db..1e0c96e 100644 --- a/charts/openfga/README.md +++ b/charts/openfga/README.md @@ -56,4 +56,5 @@ To uninstall/delete the `openfga` deployment: $ helm uninstall openfga ``` -## Parameters +## Chart Parameters +Take a look at the Chart [values schema reference](https://artifacthub.io/packages/helm/openfga/openfga?modal=values-schema) for more information on the chart values that can be configured. Chart values that are null will default to the server specific default values. For more information on the server defaults please see the [official server configuration documentation](https://openfga.dev/docs/getting-started/setup-openfga/docker#configuring-the-server). diff --git a/charts/openfga/templates/deployment.yaml b/charts/openfga/templates/deployment.yaml index a961de7..3e34a41 100644 --- a/charts/openfga/templates/deployment.yaml +++ b/charts/openfga/templates/deployment.yaml @@ -19,7 +19,7 @@ spec: {{- end }} prometheus.io/scrape: "true" prometheus.io/path: /metrics - prometheus.io/port: "{{ .Values.metrics.port }}" + prometheus.io/port: "{{ (split ":" .Values.telemetry.metrics.addr)._1 }}" labels: {{- include "openfga.selectorLabels" . | nindent 8 }} spec: @@ -56,12 +56,12 @@ spec: protocol: TCP - name: playground - containerPort: {{ (split ":" .Values.profiler.addr)._1 }} + containerPort: {{ .Values.playground.port }} protocol: TCP - {{- if .Values.metrics.enabled }} + {{- if .Values.telemetry.metrics.enabled }} - name: metrics - containerPort: {{ .Values.metrics.port }} + containerPort: {{ (split ":" .Values.telemetry.metrics.addr)._1 }} protocol: TCP {{- end }} @@ -129,7 +129,7 @@ spec: {{- if .Values.http.addr }} - name: OPENFGA_HTTP_ADDR - value: {{ .Values.http.addr }} + value: "{{ .Values.http.addr }}" {{- end }} {{- if .Values.http.tls.enabled }} @@ -212,7 +212,7 @@ spec: {{- if .Values.changelogHorizonOffset }} - name: OPENFGA_CHANGELOG_HORIZON_OFFSET - value: "{{ .Values.changelogHorizonOffset }}"" + value: "{{ .Values.changelogHorizonOffset }}" {{- end }} {{- if .Values.resolveNodeLimit }} @@ -230,14 +230,44 @@ spec: value: "{{ .Values.listObjectsMaxResults }}" {{- end }} - {{- if .Values.otel.metrics.endpoint }} - - name: OPENFGA_OTEL_METRICS_ENDPOINT - value: {{ .Values.otel.metrics.endpoint }} + {{- if .Values.allowWriting1_0Models }} + - name: OPENFGA_ALLOW_WRITING_1_0_MODELS + value: "{{ .Values.allowWriting1_0Models }}" + {{- end }} + + {{- if .Values.allowEvaluating1_0Models }} + - name: OPENFGA_ALLOW_EVALUATING_1_0_MODELS + value: "{{ .Values.allowEvaluating1_0Models }}" + {{- end }} + + {{- if .Values.telemetry.metrics.enabled }} + - name: OPENFGA_METRICS_ENABLED + value: "{{ .Values.telemetry.metrics.enabled }}" + {{- end }} + + {{- if .Values.telemetry.metrics.addr }} + - name: OPENFGA_METRICS_ADDR + value: "{{ .Values.telemetry.metrics.addr }}" + {{- end }} + + {{- if .Values.telemetry.metrics.enableRPCHistograms }} + - name: OPENFGA_METRICS_ENABLE_RPC_HISTOGRAMS + value: "{{ .Values.telemetry.metrics.enableRPCHistograms }}" + {{- end }} + + {{- if .Values.telemetry.trace.enabled }} + - name: OPENFGA_TRACE_ENABLED + value: "{{ .Values.telemetry.trace.enabled }}" + {{- end }} + + {{- if .Values.telemetry.trace.otlp.endpoint }} + - name: OPENFGA_TRACE_OTLP_ENDPOINT + value: {{ .Values.telemetry.trace.otlp.endpoint }} {{- end }} - {{- if .Values.otel.metrics.protocol }} - - name: OPENFGA_OTEL_METRICS_PROTOCOL - value: {{ .Values.otel.metrics.protocol }} + {{- if .Values.telemetry.trace.sampleRatio }} + - name: OPENFGA_TRACE_SAMPLE_RATIO + value: "{{ .Values.telemetry.trace.sampleRatio }}" {{- end }} readinessProbe: diff --git a/charts/openfga/templates/service.yaml b/charts/openfga/templates/service.yaml index deebcb9..017e05a 100644 --- a/charts/openfga/templates/service.yaml +++ b/charts/openfga/templates/service.yaml @@ -33,9 +33,9 @@ spec: protocol: TCP {{- end }} - {{- if .Values.metrics.enabled }} + {{- if .Values.telemetry.metrics.enabled }} - name: metrics - port: {{ .Values.metrics.port }} + port: {{ (split ":" .Values.telemetry.metrics.addr)._1 }} targetPort: metrics protocol: TCP {{- end }} diff --git a/charts/openfga/values.schema.json b/charts/openfga/values.schema.json index addac65..0b8fc6d 100644 --- a/charts/openfga/values.schema.json +++ b/charts/openfga/values.schema.json @@ -2,6 +2,54 @@ "$schema": "http://json-schema.org/schema#", "type": "object", "properties": { + "telemetry": { + "type": "object", + "properties": { + "trace": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "enable tracing", + "default": "false" + }, + "otlp": { + "type": "object", + "properties": { + "endpoint": { + "type": ["string", "null"], + "description": "the grpc endpoint of the OpenTelemetry 'otlp' trace collector" + } + } + }, + "sampleRatio": { + "type": ["number", "null"], + "description": "the fraction of traces to sample. 1 means all, 0 means none.", + "default": null + } + } + }, + "metrics": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "enable/disable prometheus metrics on the '/metrics' endpoint", + "default": true + }, + "addr": { + "type": "string", + "description": "the host:port address to serve the prometheus metrics server on", + "default": "0.0.0.0:2112" + }, + "enableRPCHistograms": { + "type": ["boolean", "null"], + "description": "enables prometheus histogram metrics for RPC latency distributions" + } + } + } + } + }, "datastore": { "type": "object", "properties": { @@ -12,6 +60,50 @@ }, "uri": { "type":["string", "null"] + }, + "maxCacheSize": { + "type": ["integer", "null"], + "description": "the maximum number of cache keys that the storage cache can store before evicting old keys" + }, + "maxOpenConns": { + "type": ["integer", "null"], + "description": "the maximum number of open connections to the datastore" + }, + "maxIdleConns": { + "type": ["integer", "null"], + "description": "the maximum number of connections to the datastore in the idle connection pool" + }, + "connMaxIdleTime": { + "type": ["string", "null"], + "description": "the maximum amount of time (as a duration) a connection to the datastore may be idle", + "format": "duration", + "examples": ["30s", "1m", "200ms"] + }, + "connMaxLifetime": { + "type": ["string", "null"], + "description": "the maximum amount of time (as a duration) a connection to the datastore may be reused", + "format": "duration", + "examples": ["30s", "1m", "200ms"] + } + } + }, + "postgres": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "enable the bitnami/postgresql subchart and deploy Postgres", + "default": false + } + } + }, + "mysql": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "enable the bitnami/mysql subchart and deploy MySQL", + "default": false } } }, @@ -20,6 +112,7 @@ "properties": { "addr": { "type": "string", + "description": "the host:port address to serve the grpc server on.", "default": "0.0.0.0:8081" }, "tls": { @@ -27,7 +120,16 @@ "properties": { "enabled": { "type": "boolean", + "description": "enables or disables transport layer security (TLS)", "default": false + }, + "cert": { + "type": ["string", "null"], + "description": "the (absolute) file path of the certificate to use for the TLS connection" + }, + "key": { + "type": ["string", "null"], + "description": "the (absolute) file path of the TLS key that should be used for the TLS connection" } } } @@ -38,10 +140,12 @@ "properties": { "enabled": { "type": "boolean", + "description": "enables or disables the OpenFGA HTTP server. If this is set to true then 'grpc.enabled' must be set to true", "default": true }, "addr": { "type": "string", + "description": "the host:port address to serve the HTTP server on", "default": "0.0.0.0:8080" }, "tls": { @@ -49,24 +153,38 @@ "properties": { "enabled": { "type": "boolean", + "description": "enables or disables transport layer security (TLS)", "default": false + }, + "cert": { + "type": ["string", "null"], + "description": "the (absolute) file path of the certificate to use for the TLS connection" + }, + "key": { + "type": ["string", "null"], + "description": "the (absolute) file path of the TLS key that should be used for the TLS connection" } } }, "upstreamTimeout": { - "type": "string" + "type": ["string", "null"], + "description": "the timeout duration for proxying HTTP requests upstream to the grpc endpoint.", + "format": "duration", + "examples": ["5s", "1m", "200ms"] }, "corsAllowedOrigins": { "type": "array", "items": { "type": "string" - } + }, + "default": ["*"] }, "corsAllowedHeaders": { "type": "array", "items": { "type": "string" - } + }, + "default": ["*"] } } }, @@ -74,14 +192,16 @@ "type": "object", "properties": { "method": { - "type": "string", - "enum": ["none", "preshared", "oidc"] + "type": ["string", "null"], + "description": "the authentication method to use", + "enum": [null, "none", "preshared", "oidc"] }, "preshared": { "type": "object", "properties": { "keys": { "type": "array", + "description": "one or more preshared keys to use for authentication (must be set if `authn.method=preshared')", "items": { "type": "string", "minItems": 1 @@ -93,10 +213,12 @@ "type": "object", "properties": { "audience": { - "type": ["string", "null"] + "type": ["string", "null"], + "description": "the OIDC 'audience' which tokens will be validated against (must be set if `authn.method=oidc`)" }, "issuer": { - "type": ["string", "null"] + "type": ["string", "null"], + "description": "the OIDC 'issuer' which tokens will be validated against (must be set if `authn.method=oidc`)" } } } @@ -107,16 +229,86 @@ "properties": { "enabled": { "type": "boolean", + "description": "enable/disable the OpenFGA Playground", "default": true }, "port": { "type": "number", + "description": "the port to serve the local OpenFGA Playground on", "default": 3000 } } }, - "metrics": { - "type": "object" + "profiler": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "enable/disable pprof profiling", + "default": false + }, + "addr": { + "type": "string", + "description": "the host:port address to serve the pprof profiler server on", + "default": "0.0.0.0:3001" + } + } + }, + "log": { + "type": "object", + "properties": { + "level": { + "type": "string", + "description": "the log level to set (for production we recommend 'info' level)", + "enum": ["debug", "info", "warn", "error", "panic", "fatal"], + "default": "info" + }, + "format": { + "type": "string", + "description": "the log format to output logs in (for production we recommend 'json' format)", + "enum": ["text", "json"], + "default": "json" + } + } + }, + "experimentals": { + "type": "array", + "description": "a list of experimental features to enable", + "default": [] + }, + "maxTuplesPerWrite": { + "type": ["integer", "null"], + "description": "the maximum allowed number of tuples per Write transaction" + }, + "maxTypesPerAuthorizationModel": { + "type": ["integer", "null"], + "description": "the maximum allowed number of type definitions per authorization model" + }, + "changelogHorizonOffset": { + "type": ["integer", "null"], + "description": "the offset (in minutes) from the current time - changes that occur after this offset will not be included in the response of ReadChanges." + }, + "resolveNodeLimit": { + "type": ["integer", "null"], + "description": "defines how deeply nested an authorization model can be" + }, + "listObjectsDeadline": { + "type": ["string", "null"], + "description": "the timeout deadline (as a duration) for serving ListObjects requests", + "format": "duration", + "examples": ["3s", "1m", "200ms"] + }, + "listObjectsMaxResults": { + "type": ["integer", "null"], + "description": "the maximum results to return in ListObjects responses" + }, + "allowWriting1_0Models": { + "type": ["boolean", "null"], + "description": "allow calling WriteAuthorizationModel with models that have 1.0 schema version" + }, + "allowEvaluating1_0Models": { + "type": ["boolean", "null"], + "description": "allow calling Check, Expand, ListObjects, Write Assertions with models that have 1.0 schema version" } } } \ No newline at end of file diff --git a/charts/openfga/values.yaml b/charts/openfga/values.yaml index 1b6746e..abace21 100644 --- a/charts/openfga/values.yaml +++ b/charts/openfga/values.yaml @@ -36,36 +36,45 @@ service: type: ClusterIP port: 8080 -metrics: - ## @param metrics.enabled Expose OpenFGA metrics - ## - enabled: true +telemetry: + trace: + enabled: false + otlp: + endpoint: + sampleRatio: + + metrics: + ## @param telemetry.metrics.enabled enable/disable prometheus metrics on the '/metrics' endpoint + ## + enabled: true - ## @param metrics.port The port the '/metrics' endpoint is served on - ## - port: 2112 + ## @param telemetry.metrics.addr the host:port address to serve the Metrics server on + addr: 0.0.0.0:2112 - ## @param metrics.podAnnotations [object] Annotations for the Prometheus metrics on etcd pods - ## - podAnnotations: - prometheus.io/scrape: "true" - prometheus.io/port: "{{ .Values.containerPorts.prometheus }}" + ## @param telemetry.metrics.enableRPCHistograms enables prometheus histogram metrics for RPC latency distributions + enableRPCHistograms: + + ## @param telemetry.metrics.podAnnotations [object] Annotations for the Prometheus metrics on etcd pods + ## + podAnnotations: + prometheus.io/scrape: "true" + prometheus.io/port: "{{ .Values.containerPorts.prometheus }}" datastore: engine: memory uri: - maxCacheSize: 100000 + maxCacheSize: maxOpenConns: maxIdleConns: connMaxIdleTime: connMaxLifetime: postgres: - ## @param postgres.enabled Enable the bitnami/postgresql subchart and deploy Postgres + ## @param postgres.enabled enable the bitnami/postgresql subchart and deploy Postgres enabled: false mysql: - ## @param mysql.enabled Enable the bitnami/mysql subchart and deploy MySQL + ## @param mysql.enabled enable the bitnami/mysql subchart and deploy MySQL enabled: false grpc: @@ -82,12 +91,12 @@ http: enabled: false cert: key: - upstreamTimeout: 5s + upstreamTimeout: corsAllowedOrigins: ["*"] corsAllowedHeaders: ["*"] authn: - method: none + method: preshared: keys: [] oidc: @@ -104,21 +113,18 @@ profiler: log: level: info - format: text + format: json experimentals: [] -maxTuplesPerWrite: 100 -maxTypesPerAuthorizationModel: 100 -changelogHorizonOffset: 0 -resolveNodeLimit: 25 -listObjectsDeadline: 3s -listObjectsMaxResults: 1000 - -otel: - metrics: - endpoint: 0.0.0.0:4317 - protocol: grpc +maxTuplesPerWrite: +maxTypesPerAuthorizationModel: +changelogHorizonOffset: +resolveNodeLimit: +listObjectsDeadline: +listObjectsMaxResults: +allowWriting1_0Models: +allowEvaluating1_0Models: ingress: enabled: false