Updates to the Readme files
Updated the Kubernetes Readme file to explain the way the scripts run
the Kubernetes launcher. Added a new README file to the Templates
directory. Used this new README to explain what the templates are used
for and to explain where the variables are coming from.
Change-Id: Ibdd9cf2c76e7a14838fba220803a4648cd731f92
Signed-off-by: Alanny Lopez <alanny.lopez@ibm.com>
diff --git a/kubernetes/README.md b/kubernetes/README.md
index 39a5601..a409f84 100644
--- a/kubernetes/README.md
+++ b/kubernetes/README.md
@@ -1,19 +1,36 @@
-Running OpenBMC Builds on Kubernetes
+Running Builds Script with Kubernetes
=====================================
-To do a run of an OpenBMC build in the Kubernetes cloud it is a good idea to understand containers
-and to get some understanding of Kubernetes. Kubernetes clusters can be created on most cloud
-service providers and are currently in beta on Bluemix. They can also exist as VM's and Bare Metal
-machines.
-Steps required to do an OpenBMC build on Kubernetes:
-1. Obtain Access to a Kubernetes Cluster
-2. Install Kubectl to the machine you are running the script from
-3. Login/Configure the Kubectl to connect to your cluster
-4. Ensure NFS mount exists for the build container to use (see [./storage-setup.sh](https://github.com/openbmc/openbmc-build-scripts/kubernetes/storage-setup.sh))
- best to mount one directory and have one subdirectory for work and another for shared-state cache
-5. Run the [./build-setup.sh](https://github.com/openbmc/openbmc-build-scripts/kubernetes/storage-setup.sh)
- to launch the build container as a Kubernetes job
-6. Stream the log using "kubectl logs -f ${Name of Pod}"
+The following are required to run scripts with Kubernetes integration:
+- Access to a Kubernetes cluster.
+- External storage that is mountable to the Kubernetes cluster.
+- Kubectl installed and configured on the machine running the scripts.
+
+All the scripts use a similar formula to launch to Kubernetes:
+1. The script is run with a valid launch variable in the environment.
+2. The script then invokes the [kubernetes-launch.sh](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/kubernetes-launch.sh)
+ script by sourcing it.
+3. The launch script then uses the template to generate the appropriate YAML file.
+4. The generated YAML is then used to launch the object into the specified Kubernetes cluster.
+5. Once the object is launched the script will end or will do optional tailing of the logs or
+ deletion of the object from the API once Docker container run completes.
+
+The steps to run the script with Kubernetes integration are also similar for all scripts:
+1. Look at the variables used by the script and by the templates.
+2. Export the variables that you would like to be different from the defaults in the script,
+ kubernetes-launch-script, and template. Alternatively, you can edit the defaults in the files
+ locally.
+3. Run the script.
+
+## OpenBMC Build
+- Script: [build-setup.sh](https://github.com/openbmc/openbmc-build-scripts/blob/master/build-setup.sh)
+- Templates: [OpenBMC-build-job.yaml](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/Templates/OpenBMC-build-job.yaml)
+ or [OpenBMC-build-pod.yaml](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/Templates/OpenBMC-build-pod.yaml)
+
+## QEMU build
+- Script: [qemu-build.sh](https://github.com/openbmc/openbmc-build-scripts/blob/master/qemu-build.sh)
+- Templates: [QEMU-build-job.yaml](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/Templates/QEMU-build-job.yaml)
+ or [QEMU-build-pod.yaml](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/Templates/QEMU-build-pod.yaml)
## Useful links:
Kubernetes (K8s) is an open source container orchestration system.
@@ -35,4 +52,3 @@
be mounted to an external file system.
- [Persitent Volume (pv)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes)
- [Persistent Volume Claim (pvc)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)
-
diff --git a/kubernetes/Templates/README.md b/kubernetes/Templates/README.md
new file mode 100644
index 0000000..f96abb3
--- /dev/null
+++ b/kubernetes/Templates/README.md
@@ -0,0 +1,53 @@
+Kubernetes YAML Templates for OpenBMC
+=====================================
+
+This directory holds the templates that are used by the [kubernetes-launch.sh](https://github.com/openbmc/openbmc-build-scripts/tree/master/kubernetes/kubernetes-launch.sh)
+to launch objects into the Kubernetes API. Certain templates have different types such as job and
+pod. To understand the difference between the different types of objects please refer to the
+[Kubernetes Documentation](https://kubernetes.io/docs/concepts/).
+
+The templates within this directory all have variables that the kubernetes-launch.sh script fills
+in. Below is a listing of all the variables that each template uses and where its expected defaults
+come from. However there are some variables that are not template specific, those will be addressed
+first. Below, "initial script" refers to whatever script from the parent [openbmc-build-scripts](https://github.com/openbmc/openbmc-build-scripts)
+repo was used and "launch script" refers to the kubernetes-launch.sh.
+
+##Non-Template Specific Variables
+- **ARCH**: The desired architecture for the machine the container is expected to run on. This is
+ defined in the initial script. Since the initial script will build the container.
+- **namespace**: The namespaces the container will be launched within Kubernetes, defined in the
+ launch script.
+- **WORKSPACE**: The workspace, this stems from our use of Jenkins, defined in the initial script.
+- **HOME**: The home directory path of the user that ran the initial script.
+- **imgname**: Name of the image used to launch the container, carried from the initial script and
+ updated in the launch script so that it also includes the registry in the front.
+- **BUILD\_ID**: This is a variable that is carried by our Jenkins integration. Can be ignored.
+ Normally exported before the initial script.
+- **imgplsec**: The image pull secret used to access the registry the images are stored in. This is
+ defined in the launch script.
+- **podname**: The name of the pod, as will be seen in the Kubernetes API. Defined in the launch
+ script.
+
+##OpenBMC-Build
+- **target**: The build target for the OpenBMC-Build. Defined in the build-setup.sh script.
+- **hclaim**: The "home" PVC, the external mount for the home directory. Defined in the launch
+ script.
+- **sclaim**: The "shared-state" PVC, the external mount for the shared state cache directory used
+ to reduce the time it takes to do the build using cache. Defined in the launch script.
+- **oclaim**: The "openbmc-cache" PVC, the external mount for the OpenBMC directory that is used for
+ the build. This is done to allow for us to use this for testing were we use a specific checkout of
+ a git repo. Defined in the launch script.
+- **obmcdir**: The OpenBMC directory path that is used internally in the container to do the build.
+ Defined in the build-setup.sh script.
+- **sscdir**: The shared state cache directory used to speed up build times. Defined in the
+ build-setup.sh script. This is where the container will mount the sclaim.
+- **obmcext**: The OpenBMC directory path that is used to create the internal copy. This is the path
+ to which the oclaim will be mounted to. Defined in the build-setup.sh script.
+
+##QEMU-Build
+- **hclaim**: The "home" PVC, the external mount for the home directory. Defined in the launch
+ script.
+- **qclaim**: The "qemu" PVC, external mount that holds the QEMU repository used to create the
+ image. Defined in the launch script.
+- **qemudir**: The qemu directory path to which the qclaim will be mounted to. Defined in the
+ qemu-build.sh script.