chore(docs): Add deploying to fly.io section to the docs

Signed-off-by: Oğuzhan Durgun <oguzhandurgun95@gmail.com>
cerbos · Mar 11, 2024 · 374ec11 · 374ec11
1 parent 3a67a29
commit 374ec11
Show file tree

Hide file tree

Showing 2 changed files with 223 additions and 0 deletions.
diff --git a/docs/modules/configuration/pages/index.adoc b/docs/modules/configuration/pages/index.adoc
@@ -16,6 +16,7 @@ The Cerbos server is configured with a YAML file, conventionally named `.cerbos.
 NOTE: Config values can reference environment variables by enclosing them between `${}`, for example `$$${HOME}$$`. Defaults can be set using `$$${VAR:default}$$`.
 
 
+[id="minimal-configuration"]
 == Minimal Configuration
 At a minimum, Cerbos requires a storage driver to be configured. If no explicit configuration is provided using the `--config` flag, Cerbos defaults to a `disk` driver configured to  look for policies in a directory named `policies` in the current working directory.
 
@@ -42,6 +43,7 @@ storage:
 ----
 
 
+[id="full-configuration"]
 == Full Configuration
 Cerbos has many configuration options that are either optional or has reasonable defaults built-in. The following section describes all user-configurable options and their defaults.
 

diff --git a/docs/modules/deployment/pages/serverless-faas.adoc b/docs/modules/deployment/pages/serverless-faas.adoc
@@ -8,3 +8,224 @@ include::ROOT:partial$version-check.adoc[]
 == AWS Lambda
 
 You can deploy Cerbos to AWS Lambda by building a special container image that includes the Lambda runtime and the Cerbos binary. See https://github.com/cerbos/cerbos-aws-lambda for an example. The repository also contains an example of an AWS Lambda function that creates an AWS API Gateway endpoint to communicate with Cerbos over the HTTP protocol.
+
+== Fly.io
+
+You can deploy Cerbos with link:https://fly.io/docs/apps[Fly Launch] by installing
+link:https://fly.io/docs/hands-on/install-flyctl[flyctl], creating a `fly.toml` configuration file and executing the
+command `flyctl launch` at the directory `fly.toml` file rests.
+
+An example `fly.toml` configuration to deploy Cerbos which gives access to the Cerbos default HTTP port 3592 and the
+gRPC port 3593, and enables the healthchecks and metrics:
+[source,toml,linenums]
+----
+app = '<APPLICATION_NAME>' <1>
+primary_region = 'lhr'
+
+[build]
+  image = 'ghcr.io/cerbos/cerbos:{app-version}'
+
+[[mounts]]
+  source = 'policies'
+  destination = '/policies'
+  initial_size = '1GB'
+
+[[services]]
+  protocol = ''
+  internal_port = 3592
+
+[[services.ports]]
+    port = 3592
+    handlers = ['tls', 'http']
+
+[[services.http_checks]]
+    interval = '5s'
+    timeout = '2s'
+    grace_period = '5s'
+    method = 'get'
+    path = '/_cerbos/health'
+    protocol = 'http'
+
+[[services]]
+  protocol = ''
+  internal_port = 3593
+
+[[services.ports]]
+    port = 3593
+    handlers = ['tls']
+
+    [services.ports.tls_options]
+      alpn = ['h2']
+
+[[vm]]
+  memory = '1gb'
+  cpu_kind = 'shared'
+  cpus = 1
+
+[metrics]
+  port = 3592
+  path = "/_cerbos/metrics"
+----
+<1> The name of the link:https://fly.io/docs/apps[Fly App]
+
+The configuration example above launches a Cerbos instance with the
+xref:configuration:index.adoc#minimal-configuration[minimal configuration]. In the minimal configuration the
+driver is set to xref:configuration:storage.adoc#disk-driver[disk] and Cerbos reads the policies from the directory
+`/policies`. In the production environments using xref:configuration:storage.adoc#blob-driver[blob] or
+xref:configuration:storage.adoc#git-driver[git] drivers are preferable. It is possible to override the Cerbos configuration to
+use other storage drivers by overriding `cmd` and `entrypoint` of the image using
+link:https://fly.io/docs/reference/configuration/#the-experimental-section[experimental section] of the `fly.toml` file.
+
+=== Blob
+
+The same `fly.toml` example above with docker `cmd` and `entrypoint` overridden using
+link:https://fly.io/docs/reference/configuration/#the-experimental-section[experimental section] to set the Cerbos
+configuration parameters to use the xref:configuration:storage.adoc#blob-driver[blob] storage driver:
+[source,toml,linenums]
+----
+app = '<APPLICATION_NAME>' <1>
+primary_region = 'lhr'
+
+[build]
+  image = 'ghcr.io/cerbos/cerbos:{app-version}'
+
+[experimental]
+  cmd = [
+    'server',
+    '--set', 'storage.driver=blob',
+    '--set', 'storage.blob.bucket=s3://<BUCKET_NAME>?region=us-east-2', <2>
+    '--set', 'storage.blob.downloadTimeout=30s',
+    '--set', 'storage.blob.prefix=policies',
+    '--set', 'storage.blob.updatePollInterval=15s'
+  ]
+  entrypoint = ['/cerbos']
+
+[[mounts]]
+  source = 'policies'
+  destination = '/policies'
+  initial_size = '1GB'
+
+[[services]]
+  protocol = ''
+  internal_port = 3592
+  auto_stop_machines = true
+
+[[services.ports]]
+    port = 3592
+    handlers = ['tls', 'http']
+
+[[services.http_checks]]
+    interval = '5s'
+    timeout = '2s'
+    grace_period = '5s'
+    method = 'get'
+    path = '/_cerbos/health'
+    protocol = 'http'
+
+[[services]]
+  protocol = ''
+  internal_port = 3593
+  auto_stop_machines = true
+
+[[services.ports]]
+    port = 3593
+    handlers = ['tls']
+
+    [services.ports.tls_options]
+      alpn = ['h2']
+
+[[vm]]
+  memory = '1gb'
+  cpu_kind = 'shared'
+  cpus = 1
+
+[metrics]
+  port = 3592
+  path = "/_cerbos/metrics"
+----
+<1> The name of the link:https://fly.io/docs/apps[Fly App]
+<2> Bucket name
+
+link:https://fly.io/docs/hands-on/install-flyctl[flyctl] has `secrets` command to provide secrets to the application
+as environment variables. This feature is needed to provide the required AWS credentials like this:
+[source,bash]
+----
+flyctl secrets set AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
+flyctl secrets set AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
+----
+
+NOTE: See the page xref:configuration:storage.adoc#blob-driver[blob] for more details on what
+environment variables are required depending on the blob storage type.
+
+link:https://fly.io[Fly.io] has support for the S3-compatible
+link:https://fly.io/docs/reference/tigris[Tigris Global Object Storage]. As
+link:https://fly.io/docs/reference/tigris[Tigris] is S3 compatible, Cerbos is able to use
+link:https://fly.io/docs/reference/tigris[Tigris] as a xref:configuration:storage.adoc#blob-driver[blob] storage driver
+too.
+
+An example `fly.toml` to use xref:configuration:storage.adoc#blob-driver[blob] storage driver to utilize
+link:https://fly.io/docs/reference/tigris[Tigris Global Object Storage].
+[source,toml,linenums]
+----
+app = '<APPLICATION_NAME>' <1>
+primary_region = 'lhr'
+
+[build]
+  image = 'ghcr.io/cerbos/cerbos:{app-version}'
+
+[experimental]
+  cmd = [
+    'server',
+    '--set', 'storage.driver=blob',
+    '--set', 'storage.blob.bucket=s3://<BUCKET_NAME>?endpoint=fly.storage.tigris.dev&region=auto', <2>
+    '--set', 'storage.blob.downloadTimeout=30s',
+    '--set', 'storage.blob.prefix=policies',
+    '--set', 'storage.blob.updatePollInterval=15s'
+  ]
+  entrypoint = ['/cerbos']
+
+[[mounts]]
+  source = 'policies'
+  destination = '/policies'
+  initial_size = '1GB'
+
+[[services]]
+  protocol = ''
+  internal_port = 3592
+  auto_stop_machines = true
+
+[[services.ports]]
+    port = 3592
+    handlers = ['tls', 'http']
+
+[[services.http_checks]]
+    interval = '5s'
+    timeout = '2s'
+    grace_period = '5s'
+    method = 'get'
+    path = '/_cerbos/health'
+    protocol = 'http'
+
+[[services]]
+  protocol = ''
+  internal_port = 3593
+  auto_stop_machines = true
+
+[[services.ports]]
+    port = 3593
+    handlers = ['tls']
+
+    [services.ports.tls_options]
+      alpn = ['h2']
+
+[[vm]]
+  memory = '1gb'
+  cpu_kind = 'shared'
+  cpus = 1
+
+[metrics]
+  port = 3592
+  path = "/_cerbos/metrics"
+----
+<1> The name of the link:https://fly.io/docs/apps[Fly App]
+<2> Bucket name