Docs: Add Managed Config Files documentation

Issue: RELENG-3723
Signed-off-by: Andrew Grimberg <agrimberg@linuxfoundation.org>
Change-Id: Ibf62456b748f150cdf491ffe793bfaee1925c9c2
Signed-off-by: Andrew Grimberg <agrimberg@linuxfoundation.org>

diff --git a/docs/_static/managed_config-examples/custom-config-params.yaml b/docs/_static/managed_config-examples/custom-config-params.yaml
new file mode 100644 (file)
index 0000000..db6f63f
--- /dev/null
+++ b/docs/_static/managed_config-examples/custom-config-params.yaml
@@ -0,0 +1,3 @@
+---
+name: "My Custom File"
+comment: "An example custom file"

diff --git a/docs/_static/managed_config-examples/custom-content b/docs/_static/managed_config-examples/custom-content
new file mode 100644 (file)
index 0000000..0f8131c
--- /dev/null
+++ b/docs/_static/managed_config-examples/custom-content
@@ -0,0 +1,5 @@
+This is just an example custom config file
+
+The user for the EXAMPLE token is: $EXAMPLE_USR
+The password for the EXAMPLE token is: $EXAMPLE_PSW
+The user:pass for the EXAMPLE token is: $EXAMPLE

diff --git a/docs/_static/managed_config-examples/custom-customizedCredentialMappings.sandbox.yaml b/docs/_static/managed_config-examples/custom-customizedCredentialMappings.sandbox.yaml
new file mode 100644 (file)
index 0000000..81c453f
--- /dev/null
+++ b/docs/_static/managed_config-examples/custom-customizedCredentialMappings.sandbox.yaml
@@ -0,0 +1,4 @@
+---
+customizedCredentialMappings:
+  - credentialsId: "dummy"
+    tokenKey: "EXAMPLE"

diff --git a/docs/_static/managed_config-examples/custom-customizedCredentialMappings.yaml b/docs/_static/managed_config-examples/custom-customizedCredentialMappings.yaml
new file mode 100644 (file)
index 0000000..898ba39
--- /dev/null
+++ b/docs/_static/managed_config-examples/custom-customizedCredentialMappings.yaml
@@ -0,0 +1,4 @@
+---
+customizedCredentialMappings:
+  - credentialsId: "example_username"
+    tokenKey: "EXAMPLE"

diff --git a/docs/jenkins.rst b/docs/jenkins.rst
index a9dcdf0..d8cc700 100644 (file)
--- a/docs/jenkins.rst
+++ b/docs/jenkins.rst
@@ -200,6 +200,87 @@ This section points to each LF project's build agents availability and flavors.
 
 .. _jenkins-log-server:
 
+Managed Config Files
+====================
+
+Jobs in Jenkins make extensive use of Managed Config Files for different types
+of files that store configuration or credentials. These files live in the
+ci-management repository along side of the rest of the community configurable
+components under the ``jenkins-admin/managed-config-files`` directory tree.
+
+This directory tree has the following case sensitive format:
+::
+
+   ci-mangement
+   |- jenkins-admin
+      |- managed-config-files
+         |- <config_type>
+            |- <file_id>
+               |- config-params.yaml
+               |- content
+               |- ??CredentialMappings.yaml
+               |- ??CrednetialMappings.sandbox.yaml
+         ...
+
+Configuration of credentials for production Jenkins systems come from the
+??CredentialMappings.yaml file.
+
+Configuration of credentials for sandbox Jenkins systems come from the
+??CredentialMappings.sandbox.yaml file.
+
+The config_type will correspond to the type that is under management as per how
+JCasC itself defines the file type.
+
+Common types in the LF environment are:
+
+* custom
+* globalMavenSettings
+* json
+* mavenSettings
+* openstackUserData
+* properties
+
+The file_id is precisely what the ID of the file should be for reference. The
+LF Release Engineering pratice is to always set a human readable / relatable
+ID.
+
+config-params.yaml are all the parameters related to this particular file that
+are _not_ the content of it or the credential mappings or the file content.
+
+The content file is the actual file that is under management. This must be a
+non-escaped version of the content for the field. It will be appropriately
+escaped when converted into the corresponding JCasC yaml.
+
+The two double ? in the name of the CredentialMappings files must have the
+appropriate mapping definition.
+
+The mapping type will use a verbatim copy when converting to the JCasC so it
+should be properly configured to match the config_type.
+
+The known breakdown of config_type to CredentialMappings is:
+
+* custom -> customizedCredentialMappings
+* mavenSetings -> serverCredentialMappings
+* properties -> propertiesCredentialMappings
+
+The following is the layout for a custom file with the ID of example
+
+.. literalinclude:: _static/managed_config-examples/custom-config-params.yaml
+   :language: yaml
+   :caption: custom/example/config-params.yaml
+
+.. literalinclude:: _static/managed_config-examples/custom-content
+   :language: bash
+   :caption: custom/example/content
+
+.. literalinclude:: _static/managed_config-examples/custom-customizedCredentialMappings.yaml
+   :language: bash
+   :caption: custom/example/customizedCredentialMappings.yaml
+
+.. literalinclude:: _static/managed_config-examples/custom-customizedCredentialMappings.sandbox.yaml
+   :language: bash
+   :caption: custom/example/customizedCredentialMappings.sandbox.yaml
+
 Log Server
 ==========