Add documentation for DeploymentRuntimeConfig

Signed-off-by: Hasan Turken <turkenh@gmail.com>

content/master/concepts/managed-resources.md

@@ -490,7 +490,7 @@ secrets store like [HashiCorp Vault](https://www.vaultproject.io/).
 
 Using `publishConnectionDetailsTo` requires enabling Crossplane 
 External Secrets Stores (ESS). Enable ESS inside a Provider with a
-[ControllerConfig]({{<ref "providers#controller-configuration" >}}) and
+[DeploymentRuntimeConfig]({{<ref "providers#runtime-configuration" >}}) and
 in Crossplane with the `--enable-external-secret-stores` argument.
 
 {{< hint "note" >}}

content/master/concepts/pods.md

@@ -30,7 +30,7 @@ defining webhook configurations.
 The core CRDs installed by the init container include: 
 * CompositeResourceDefinitions, Compositions, Configurations and Providers
 * Locks to manage package dependencies
-* ControllerConfigs to apply settings to installed Providers
+* DeploymentRuntimeConfigs to apply settings to installed Providers
 * StoreConfigs for connecting external secret stores like 
 [HashiCorp Vault](https://www.vaultproject.io/)
 

content/master/concepts/providers.md

@@ -310,11 +310,8 @@ The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
 indicate that no further enhancements will be made to it.
 Applying a Controller configuration generates a deprecation warning.
 
-Controller configurations are still supported until there is a replacement type
-in a future Crossplane version. You can read more about the design of
-[Package Runtime Config](https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md)
-which will replace it in the future.
-
+[Runtime configuration]({{<ref "runtime-configuration" >}}) is the
+replacement for Controller configuration and is available in v1.14+.
 {{< /hint >}}
 
 Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
@@ -329,6 +326,100 @@ for a Provider.
 
 Each Provider determines their supported set of `args`.
 
+### Runtime configuration
+
+{{<hint "important" >}}
+Deployment runtime configs are a beta feature. It is on by default and could be
+disabled by passing `--enable-deployment-runtime-configs=false` to the Crossplane
+deployment.
+{{< /hint >}}
+
+[Runtime configuration]({{<ref "runtime-configuration" >}}) is a generalized
+mechanism for configuring runtime for Crossplane packages with a
+runtime, e.g. `Providers` and `Functions`. It replaces the deprecated
+`ControllerConfig` type and is available in v1.14+.
+
+With its default configuration, Crossplane uses Kubernetes Deployments to
+deploy runtimes for packages, more specifically, a controller for a `Provider`
+or a gRPC server for a `Function`. It is possible to configure the runtime
+manifest by applying a `DeploymentRuntimeConfig` and referencing it in the
+`Provider` or `Function` object.
+
+Different than `ControllerConfig`, `DeploymentRuntimeConfig` embed the whole
+Kubernetes Deployment spec, which allows for more flexibility in configuring
+the runtime. Refer to the [design document](https://github.com/crossplane/crossplane/blob/2c5e7f07ba9e3d83d1c85169bbde685de8514ab8/design/one-pager-package-runtime-config.md)
+for more details.
+
+As an example, to enable the external secret stores alpha feature for a `Provider`
+by adding the `--enable-external-secret-stores` argument to the controller,
+one can apply the following:
+
+```yaml
+apiVersion: pkg.crossplane.io/v1
+kind: Provider
+metadata:
+  name: provider-gcp-iam
+spec:
+  package: xpkg.upbound.io/upbound/provider-gcp-iam:v0.37.0
+  runtimeConfigRef:
+    name: enable-ess
+---
+apiVersion: pkg.crossplane.io/v1beta1
+kind: DeploymentRuntimeConfig
+metadata:
+  name: enable-ess
+spec:
+  deploymentTemplate:
+    spec:
+      selector: {}
+      template:
+        spec:
+          containers:
+            - name: package-runtime
+              args:
+                - --enable-external-secret-stores
+```
+
+Please note that, the container name `package-runtime` is reserved for the
+package runtime container. If you are using a different container name, it
+will be introduced as a sidecar container instead of the modifying the
+package runtime container.
+
+The package manager will be opiniated about some of the fields to ensure
+the runtime is working properly and overlay them on top of what is provided
+in the runtime config. For example, it will default the replica count
+to 1 if not set or override the label selectors to make sure the Deployment
+and Service match. It will also inject any necessary environment variables,
+ports as well as volumes and volume mounts.
+
+The `Provider` or `Functions`'s `spec.runtimeConfigRef.name` field defaults
+to `default`, which means the default runtime configuration will be used if
+not specified. Crossplane will ensure there is always a default runtime
+configuration in the cluster, but not modify it if it already exists. This
+will allow users to customize the default runtime configuration to their needs.
+
+{{<hint "tip" >}}
+
+Since `DeploymentRuntimeConfig` uses the same schema as K8s' `Deployment` spec,
+you may need to pass empty objects to satisfy the schema validation.
+For example, if you just want to change the `replicas` field, you would
+need to pass the following and it is fine:
+
+```yaml
+apiVersion: pkg.crossplane.io/v1beta1
+kind: DeploymentRuntimeConfig
+metadata:
+  name: multi-replicas
+spec:
+  deploymentTemplate:
+    spec:
+      replicas: 2
+      selector: {}
+      template: {}
+```
+
+{{< /hint >}}
+
 ### Provider configuration
 
 The `ProviderConfig` determines settings the Provider uses communicating to the

content/master/getting-started/introduction.md

@@ -57,18 +57,23 @@ After installing Crossplane use `kubectl get crds` to view the Crossplane
 installed CRDs.
 
 ```shell
-kubectl get crds
-NAME                                                     
-compositeresourcedefinitions.apiextensions.crossplane.io 
-compositionrevisions.apiextensions.crossplane.io         
-compositions.apiextensions.crossplane.io                 
-configurationrevisions.pkg.crossplane.io                 
-configurations.pkg.crossplane.io                         
-controllerconfigs.pkg.crossplane.io                      
-locks.pkg.crossplane.io                                  
-providerrevisions.pkg.crossplane.io                      
-providers.pkg.crossplane.io                              
-storeconfigs.secrets.crossplane.io                       
+❯ kubectl get crd
+NAME                                                    
+compositeresourcedefinitions.apiextensions.crossplane.io
+compositionrevisions.apiextensions.crossplane.io        
+compositions.apiextensions.crossplane.io                
+configurationrevisions.pkg.crossplane.io                
+configurations.pkg.crossplane.io                        
+controllerconfigs.pkg.crossplane.io                     
+deploymentruntimeconfigs.pkg.crossplane.io              
+environmentconfigs.apiextensions.crossplane.io          
+functionrevisions.pkg.crossplane.io                     
+functions.pkg.crossplane.io                             
+locks.pkg.crossplane.io                                 
+providerrevisions.pkg.crossplane.io                     
+providers.pkg.crossplane.io                             
+storeconfigs.secrets.crossplane.io                      
+usages.apiextensions.crossplane.io                                        
 ```
 {{< /expand >}}
 

content/master/software/install.md

@@ -264,7 +264,8 @@ at the table below.
 {{< table caption="Feature flags" >}}
 | Status | Flag | Description |
 | --- | --- | --- |
-| Beta | `--enable-composition-revisions` |Enable support for CompositionRevisions |
+| Beta | `--enable-composition-revisions` |Enable support for CompositionRevisions. |
+| Beta | `--enable-deployment-runtime-configs` |Enable support for Deployment Runtime Configs. |
 | Alpha | `--enable-composition-functions` | Enable support for Composition Functions. |
 | Alpha | `--enable-composition-webhook-schema-validation` | Enable Composition validation using schemas. |
 | Alpha | `--enable-environment-configs` | Enable support for EnvironmentConfigs. |