fix: remarks (#2066)

* fix: remarks Signed-off-by: Michal Maléř <[email protected]> Co-authored-by: Michal Maléř <[email protected]>
eclipse-che · Jul 23, 2021 · 1132f42 · 1132f42
1 parent e818be0
commit 1132f42
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 113 deletions.
diff --git a/...embly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc b/...embly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc
@@ -10,11 +10,10 @@ Secrets are {platforms-name} objects that store sensitive data such as:
 * usernames
 * passwords
 * authentication tokens
-* and configurations
 
 in an encrypted form.
 
-Users can mount a {platforms-name} Secret that contains sensitive data or a ConfigMap in a {prod-short} container as:
+Users can mount a {platforms-name} Secret that contains sensitive data or a ConfigMap that contains configuration in a {prod-short} managed containers as:
 
 * a file
 * an environment variable

diff --git a/.../partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc b/.../partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc
@@ -2,71 +2,25 @@
 //
 // mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container
 
+
 [id="mounting-a-secret-or-a-configmap-as-a-file-into-a-container_{context}"]
 = Mounting a Secret or a ConfigMap as a file into a {prod-short} container
 
+
 .Prerequisites
 
-* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}.
+* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}.
 
 .Procedure
 
-. Create a new {platforms-name} Secret or a ConfigMap in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the object that is about to be created must match the set of labels:
-+
-* `app.kubernetes.io/part-of: che.eclipse.org`
-* `app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>`
-+
-* The `<DEPLOYMENT_NAME>` coresponds to the one following deployments:
-
-** `postgres`
-** `keycloak`
-** `devfile-registry`
-** `plugin-registry`
-** `{prod-deployment}` 
-+
-and
-+
-* `<OBJECT_KIND>` is either:
-+
-** `secret`
-+
-or
-+ 
-** `configmap`
+include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1]
 
-// The following content is downstream friendly
+Annotations must indicate that the given object is mounted as a file.
 
-.Example:
-====
-[source,yaml,subs="+attributes"]
-----
-apiVersion: v1
-kind: Secret
-metadata:
-  name: custom-data
-  labels:
-    app.kubernetes.io/part-of: che.eclipse.org
-    app.kubernetes.io/component: {prod-deployment}-secret
-...
-----
-or
-[source,yaml,subs="+attributes"]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: custom-data
-  labels:
-    app.kubernetes.io/part-of: che.eclipse.org
-    app.kubernetes.io/component: {prod-deployment}-configmap
-...
-----
-====
-
-Annotations must indicate that the given object is mounted as a file. Configure the annotation values:
-
-* `che.eclipse.org/mount-as: file` - to indicate that a object is mounted as a file
-* `che.eclipse.org/mount-path: _<FOO_ENV>_` - to provide a required mount path
+. Configure the annotation values:
++
+* `che.eclipse.org/mount-as: file` - To indicate that a object is mounted as a file.
+* `che.eclipse.org/mount-path: _<TARGET_PATH>_` - To provide a required mount path.
 
 .Example:
 ====
@@ -77,8 +31,8 @@ kind: Secret
 metadata:
   name: custom-data
   annotations:
-    che.eclipse.org/mount-path: /data
     che.eclipse.org/mount-as: file
+    che.eclipse.org/mount-path: /data
   labels:
 ...
 ----
@@ -90,8 +44,8 @@ kind: ConfigMap
 metadata:
   name: custom-data
   annotations:
-    che.eclipse.org/mount-path: /data
     che.eclipse.org/mount-as: file
+    che.eclipse.org/mount-path: /data
   labels:
 ...
 ----
@@ -111,8 +65,8 @@ metadata:
     app.kubernetes.io/part-of: che.eclipse.org
     app.kubernetes.io/component: {prod-deployment}-secret
   annotations:
-    che.eclipse.org/mount-path: /data
     che.eclipse.org/mount-as: file
+    che.eclipse.org/mount-path: /data
 data:
   ca.crt: __<base64 encoded data content here>__
 ----
@@ -127,10 +81,13 @@ metadata:
     app.kubernetes.io/part-of: che.eclipse.org
     app.kubernetes.io/component: {prod-deployment}-configmap
   annotations:
-    che.eclipse.org/mount-path: /data
     che.eclipse.org/mount-as: file
+    che.eclipse.org/mount-path: /data
 data:
   ca.crt: __<data content here>__
 ----
 ====
+
 This results in a file named `ca.crt` being mounted at the `/data` path of {prod-short} container.
+
+IMPORTANT: To make the changes in a {prod-short} container visible, recreate the object entirely. 
diff --git a/...unting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc b/...unting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc
@@ -2,68 +2,23 @@
 //
 // mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container
 
+
 [id="mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container_{context}"]
 = Mounting a Secret or a ConfigMap as an environment variable into a {prod-short} container
 
+
 .Prerequisites
 
 * A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}.
 
 .Procedure
 
-. Create a new {platforms-name} Secret or a ConfigMap in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the object that is about to be created must match the set of labels:
-+
-* `app.kubernetes.io/part-of: che.eclipse.org`
-* `app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>`
-+
-* The `<DEPLOYMENT_NAME>` coresponds to the one following deployments:
-
-** `postgres`
-** `keycloak`
-** `devfile-registry`
-** `plugin-registry`
-** `{prod-deployment}` 
-+
-and
-+
-* `<OBJECT_KIND>` is either:
-+
-** `secret`
-+
-or
-+ 
-** `configmap`
+include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1]
 
-// The following content is downstream friendly
-
-.Example:
-====
-[source,yaml,subs="+quotes,attributes"]
-----
-apiVersion: v1
-kind: Secret
-metadata:
-  name: custom-settings
-  labels:
-    app.kubernetes.io/part-of: che.eclipse.org
-    app.kubernetes.io/component: {prod-deployment}-secret
-...
-----
-or
-[source,yaml,subs="+quotes,attributes"]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: custom-settings
-  labels:
-    app.kubernetes.io/part-of: che.eclipse.org
-    app.kubernetes.io/component: {prod-deployment}-secret
-...
-----
-====
-Annotations must indicate that the given object is mounted as a environment variable. Configure the annotation values:
+Annotations must indicate that the given object is mounted as a environment variable.
 
+. Configure the annotation values:
++
 * `che.eclipse.org/mount-as: env` - to indicate that a object is mounted as an environment variable
 * `che.eclipse.org/env-name: _<FOO_ENV>_` - to provide an environment variable name, which is required to mount a object key value
 
@@ -100,7 +55,13 @@ data:
 ----
 ====
 
-This results in the environment variable named `FOO_ENV` and the value `myvalue` being provisioned into a {prod-short} container.
+This results in two environment variables:
+
+* `FOO_ENV`
+
+* `myvalue`
+
+being provisioned into a {prod-short} container.
 
 If the object provides more than one data item, the environment variable name must be provided for each of the data keys as follows:
 
@@ -144,8 +105,11 @@ data:
 This results in two environment variables:
 
 * `FOO_ENV`
+
 * `OTHER_ENV`
 
 being provisioned into a {prod-short} container.
 
 NOTE: The maximum length of annotation names in a {orch-name} object is 63 characters, where 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the object.
+
+IMPORTANT: To make the changes in a {prod-short} container visible, recreate the object entirely.
diff --git a/...tion-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc b/...tion-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc
@@ -0,0 +1,57 @@
+// Module included in the following procedures:
+//
+// mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container
+// mounting-a-secret-or-a-configmap-as-a-file-into-a-container
+
+
+. Create a new {platforms-name} Secret or a ConfigMap in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the object that is about to be created must match the set of labels:
++
+* `app.kubernetes.io/part-of: che.eclipse.org`
+* `app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>`
++
+* The `<DEPLOYMENT_NAME>` corresponds to the one following deployments:
+
+** `postgres`
+** `keycloak`
+** `devfile-registry`
+** `plugin-registry`
+** `{prod-deployment}`
++
+and
++
+* `<OBJECT_KIND>` is either:
++
+** `secret`
++
+or
++
+** `configmap`
+
+// The following content is downstream friendly
+
+.Example:
+====
+[source,yaml,subs="+quotes,attributes"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: custom-settings
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: {prod-deployment}-secret
+...
+----
+or
+[source,yaml,subs="+quotes,attributes"]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: custom-settings
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: {prod-deployment}-configmap
+...
+----
+====