diff --git a/assemblies/assembly-provisioning-a-custom-configuration.adoc b/assemblies/assembly-provisioning-a-custom-configuration.adoc index d77f7ad440..6cf7c60d1c 100644 --- a/assemblies/assembly-provisioning-a-custom-configuration.adoc +++ b/assemblies/assembly-provisioning-a-custom-configuration.adoc @@ -24,7 +24,7 @@ include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[le include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1] -include::modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc[leveloffset=+2] +include::modules/configuring/proc-injecting-custom-files-and-environment-variables-into-backstage-containers.adoc[leveloffset=+2] include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1] diff --git a/modules/configuring/proc-injecting-custom-files-and-environment-variables-into-backstage-containers.adoc b/modules/configuring/proc-injecting-custom-files-and-environment-variables-into-backstage-containers.adoc new file mode 100644 index 0000000000..58013b3ef9 --- /dev/null +++ b/modules/configuring/proc-injecting-custom-files-and-environment-variables-into-backstage-containers.adoc @@ -0,0 +1,143 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-injecting-custom-files-and-environment-variables-into-backstage-containers"] += Injecting extra files and environment variables into {backstage} containers + +By default, files mount only to the `backstage-backend` container. If the `containers` field is not specified, the volume mounts only to the `backstage-backend` container. You can also specify other targets, including a list of containers by name (such as `dynamic-plugin-install` or `selectcustom` sidecars) or select all containers in the {backstage} Pod. + +The `mountPath` field specifies the location where a ConfigMap or Secret is mounted. +The behavior of the mount, whether it includes or excludes a `subPath`, depends on the specification of the `key` or `mountPath` fields. + +* If `key` and `mountPath` are not specified: Each key or value is mounted as a `filename` or content with a `subPath`. +* If `key` is specified with or without `mountPath`: The specified key or value is mounted with a `subPath`. +* If only `mountPath` is specified: A directory containing all the keys or values is mounted without a `subPath`. + +[NOTE] +==== +* {ocp-short} does not automatically update a volume mounted with `subPath`. By default, the {product-very-short} Operator monitors these ConfigMaps or Secrets and refreshes the {product-very-short} Pod when changes occur. +* For security purposes, {product} does not give the Operator Service Account read access to Secrets. As a result, mounting files from Secrets without specifying both mountPath and key is not supported. +==== + +.Procedure + +. Apply the configuration to your `{product-custom-resource-type} custom resource (CR)`. The following code block is an example: ++ +[source,yaml] +---- +spec: + application: + extraFiles: + mountPath: __ + configMaps: + - name: __ + - name: __ + key: __ + containers: + - "*" + - name: __ + mountPath: __ + containers: + - backstage-backend + - install-dynamic-plugins + secrets: + - name: __ + key: __ + containers: + - install-dynamic-plugins + - name: __ + mountPath: __ + pvcs: + - name: __ + - name: __ + mountPath: __ + extraEnvs: + configMaps: + - name: __ + key: __ + containers: + - "*" + secrets: + - name: __ + envs: + - name: __ + value: "__" + containers: + - install-dynamic-plugins +---- +where: + +`spec.application.extraFiles.mountPath`:: Specifies the default base mount path for files if no specific `mountPath` is set for a resource (for example, `/`). +`spec.application.extraFiles.configMaps.name`:: Mounts all entries from `` to the default mount path. +`spec.application.extraFiles.configMaps.key`:: Mounts **only the specified key (for example, `.txt`) from the ConfigMap. +`spec.application.extraFiles.configMaps.containers`:: Targets all containers (`"*"`) for mounting. +`spec.application.extraFiles.configMaps.mountPath`:: Overrides the default and mounts all ConfigMap entries as a directory at the specified path (for example, `/`). +`spec.application.extraFiles.secrets.key`:: Mounts only a specific key from the Secret. +`spec.application.extraFiles.secrets.mountPath`:: Overrides the default and mounts all Secret entries as a directory at the specified path (for example, `/`). +`spec.application.extraFiles.pvcs.name`:: Mounts the PVC to the default mount path, appending the PVC name (for example, `//`). +`spec.application.extraFiles.pvcs.mountPath`:: Overrides the default and mounts the PVC to the specified path (for example, `/`). +`spec.application.extraEnvs.configMaps.containers`:: Injects the specified ConfigMap key as an environment variable into all containers (`"*"`). +`spec.application.extraEnvs.secrets.name`:: Injects all keys from the Secret as environment variables into the default container. +`spec.application.envs.containers`:: Targets only the listed container for the static environment variable injection. + +[NOTE] +==== +The following explicit options are supported: + +* *No* or an empty field: Mounts only to the `backstage-backend` container. +* `*` (asterisk) as the first and only array element: Mounts to all containers. +* Explicit container names, for example, `install-dynamic-plugins`: Mounts only to the listed containers. +==== + +.Verification + +The files are mounted with the following correct paths and container targets: + +[cols="1,2,3,2", options="header"] +|=== +| Resource | Target type | Path(s) or name(s) | Container(s) + +| ConfigMap (``) +| File +| `//`, `//` +| `backstage-backend` + +| ConfigMap (``) +| File +| `//.txt` +| All + +| ConfigMap (``) +| Directory +| `//` +| `backstage-backend`, `install-dynamic-plugins` + +| Secret (``) +| File +| `//.txt` +| `install-dynamic-plugins` + +| Secret (``) +| Directory +| `//` +| `backstage-backend` + +| PVC (``) +| Directory +| `//` +| `backstage-backend` + +| ConfigMap (``) +| Env Var +| `` +| All + +| Secret (``) +| Env Var +| ``, `` +| `backstage-backend` + +| CRD (`envs`) +| Env Var +| ` = ` +| `install-dynamic-plugins` +|=== \ No newline at end of file diff --git a/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc b/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc deleted file mode 100644 index a80c9f6fe2..0000000000 --- a/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc +++ /dev/null @@ -1,81 +0,0 @@ -:_mod-docs-content-type: PROCEDURE - -[id="mounting-additional-files-in-your-custom-configuration-using-rhdh-operator"] -= Mounting additional files in your custom configuration by using the {product} Operator - -You can use the {product-short} Operator to mount extra files, such as a ConfigMap or Secret, to the container in a preferred location. - -The `mountPath` field specifies the location where a ConfigMap or Secret is mounted. -The behavior of the mount, whether it includes or excludes a `subPath`, depends on the specification of the `key` or `mountPath` fields. - -* If `key` and `mountPath` are not specified: Each key or value is mounted as a `filename` or content with a `subPath`. -* If `key` is specified with or without `mountPath`: The specified key or value is mounted with a `subPath`. -* If only `mountPath` is specified: A directory containing all the keys or values is mounted without a `subPath`. - -[NOTE] -==== -* {ocp-short} does not automatically update a volume mounted with `subPath`. By default, the {product-very-short} Operator monitors these ConfigMaps or Secrets and refreshes the {product-very-short} Pod when changes occur. -* For security purposes, {product} does not give the Operator Service Account read access to Secrets. As a result, mounting files from Secrets without specifying both mountPath and key is not supported. -==== - -.Prerequisites -* You have developer permissions to access the {ocp-short} cluster containing your {product-short} instance using the {openshift-cli}. -* {installing-on-ocp-book-link}[Your {ocp-short} administrator has installed the {product} Operator in {ocp-short}]. - -.Procedure -. In {ocp-short}, create your ConfigMap or Secret with the following YAML codes: -+ -Minimal `{my-extra-file-configmap}` ConfigMap example: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: {my-extra-file-configmap} -data: - file11.txt: | - My file11 content - file 12.txt: | - My file12 content ----- -+ -Minimal {product} Secret example: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: `__` -StringData: - secret11.txt: | - secret-content ----- -+ -For more information, see xref:provisioning-your-custom-configuration[Provisioning and using your custom {product} configuration]. - -. Set the value of the `configMaps name` to the name of the ConfigMap or `secrets name` to the name of the Secret in your `{product-custom-resource-type}` CR. -For example: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -spec: - application: - extraFiles: - mountPath: /my/path - configMaps: - - name: {my-extra-file-configmap} - key: file12.txt - mountPath: /my/my-rhdh-config-map/path - secrets: - - name: `__` - key: secret11.txt - mountPath: /my/my-rhdh-secret/path - ----- -+ -[NOTE] -==== -`__` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}. -====