website: add more blueprint docs, 2022.8 release notes

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>

website/developer-docs/blueprints/index.md

@@ -7,3 +7,24 @@ Requires authentik 2022.8
 :::
 
 Blueprints offer a new way to template, automate and distribute authentik configuration. Blueprints can be used to automatically configure instances, manage config as code without any external tools, and to distribute application configs.
+
+## Types
+
+Blueprints are yaml files, whose format is described further in [File structure](./v1/structure). Blueprints can be applied in one of two ways:
+
+-   As a Blueprint instance, which is a YAML file mounted into the authentik (worker) container. This file is read and applied regularly (every 60 minutes). Multiple instances can be created for a single blueprint file, and instances can be given context key:value attributes to configure the blueprint.
+-   As a Flow import, which is a YAML file uploaded via the Browser/API. This file is validated and applied directly after being uploaded, but is not further monitored/applied.
+
+Starting with authentik 2022.8, blueprints are used to manage authentik default flows and other system objects. These blueprints can be disabled/replaced with custom blueprints in certain circumstances.
+
+## Usage
+
+The authentik container by default looks for blueprints in `/blueprints`. Underneath this directory, there are a couple default subdirectories:
+
+-   `/blueprints/default`: Default blueprints for default flows, tenants, etc
+-   `/blueprints/example`: Example blueprints for common configurations and flows
+-   `/blueprints/system`: System blueprints for authentik managed Property mappings, etc
+
+Any additional `.yaml` file in `/blueprints` will be discovered and automatically instantiated, depending on their labels.
+
+To disable existing blueprints, an empty file can be mounted over the existing blueprint.

website/developer-docs/blueprints/v1/structure.md

@@ -1,32 +1,7 @@
----
-title: File structure
----
+# File structure
 
 Blueprints are YAML files, which can use some additional tags to ease blueprint creation.
 
-## Additional Tags
-
-#### `!KeyOf`
-
-Example: `policy: !KeyOf my-policy-id`
-
-Resolves to the primary key of the model instance defined by id _my-policy-id_.
-
-If no matching entry can be found, an error is raised and the blueprint is invalid.
-
-#### `!Find`
-
-Example: `configure_flow: !Find [authentik_flows.flow, [slug, default-password-change]]`
-
-Looks up any model and resolves to the the matches' primary key.
-First argument is the model to be queried, remaining arguments are expected to be pairs of key=value pairs to query for.
-
-#### `!Context`
-
-Example: `configure_flow: !Context foo`
-
-Find values from the context. Can optionally be called with a default like `!Context [foo, default-value]`.
-
 ## Structure
 
 ```yaml
@@ -65,6 +40,6 @@ entries:
 
 Used by authentik's packaged blueprints to keep globals up-to-date. Should only be removed in special cases.
 
-#### `blueprints.goauthentik.io/example`:
+#### `blueprints.goauthentik.io/instantiate`:
 
-Blueprints with this label are not automatically imported. They are still available when creating a new instance.
+Configure if this blueprint should automatically be instantiated (defaults to `"true"`). When set to `"false"`, blueprints are listed and available to be instantiated via API/Browser.

website/developer-docs/blueprints/v1/tags.md

@@ -0,0 +1,28 @@
+# YAML Tags
+
+#### `!KeyOf`
+
+Example: `policy: !KeyOf my-policy-id`
+
+Resolves to the primary key of the model instance defined by id _my-policy-id_.
+
+If no matching entry can be found, an error is raised and the blueprint is invalid.
+
+#### `!Find`
+
+Example: `configure_flow: !Find [authentik_flows.flow, [slug, default-password-change]]`
+
+Looks up any model and resolves to the the matches' primary key.
+First argument is the model to be queried, remaining arguments are expected to be pairs of key=value pairs to query for.
+
+#### `!Context`
+
+Example: `configure_flow: !Context foo`
+
+Find values from the context. Can optionally be called with a default like `!Context [foo, default-value]`.
+
+#### `!Format`
+
+Example: `name: !Format [my-policy-%s, !Context instance_name]`
+
+Format a string using python's % formatting. First argument is the format string, any remaining arguments are used for formatting.