KEP-0009 and KEP-0010 Updates with Examples and TOC (#847)

Signed-off-by: Ken Sipe <kensipe@gmail.com>
kudobuilder · Mar 6, 2020 · 484f621 · 484f621
1 parent 9a84b71
commit 484f621
Show file tree

Hide file tree

Showing 2 changed files with 176 additions and 66 deletions.
diff --git a/keps/0009-operator-toolkit.md b/keps/0009-operator-toolkit.md
@@ -22,34 +22,28 @@ see-also:
 
 ## Table of Contents
 
-- [New KUDO package format](#new-kudo-package-format)
-  - [Table of Contents](#table-of-contents)
-  - [Summary](#summary)
-  - [Motivation](#motivation)
-  - [Goals](#goals)
-  - [Proposal](#proposal)
-    - [Definitions](#definitions)
-    - [Operator Organization](#operator-organization)
-      - [operator.yaml](#operatoryaml)
-      - [params.yaml](#paramsyaml)
-      - [common/](#common)
-      - [templates/](#templates)
-    - [Plans](#plans)
-    - [Steps](#steps)
-    - [Tasks](#tasks)
-      - [Files](#files)
-      - [Resources vs. Patches](#resources-vs-patches)
-      - [Task Application](#task-application)
-    - [Parameters](#parameters)
-    - [Templates](#templates-1)
-  - [Extensions and Bases](#extensions-and-bases)
-    - [Task Extensions](#task-extensions)
-    - [Plan Extensions](#plan-extensions)
-    - [Example Operator Extension](#example-operator-extension)
-      - [operator.yaml](#operatoryaml-1)
-      - [params.yaml](#paramsyaml-1)
-  - [Future Work](#future-work)
-    - [Allow for other templating engines](#allow-for-other-templating-engines)
+* [New KUDO package format](#new-kudo-package-format)
+   * [Table of Contents](#table-of-contents)
+   * [Summary](#summary)
+   * [Motivation](#motivation)
+   * [Goals](#goals)
+   * [Proposal](#proposal)
+      * [Definitions](#definitions)
+      * [Operator Organization](#operator-organization)
+         * [operator.yaml](#operatoryaml)
+         * [params.yaml](#paramsyaml)
+         * [common/](#common)
+         * [templates/](#templates)
+      * [Plans](#plans)
+      * [Steps](#steps)
+      * [Tasks](#tasks)
+         * [Files](#files)
+         * [Resources vs. Patches](#resources-vs-patches)
+         * [Task Application](#task-application)
+      * [Parameters](#parameters)
+      * [Templates](#templates-1)
+   * [Future Work](#future-work)
+      * [Allow for other templating engines](#allow-for-other-templating-engines)
 
 ## Summary
 
@@ -107,18 +101,52 @@ An operator package is a folder that contains all of the manifests needed to cre
 
 #### operator.yaml
 
-`operator.yaml` is the base definition of an operator. It follows the following format, extracted from the MySQL example:
+`operator.yaml` is the base definition of an operator.  It follows the following reference format.
 
 ```yaml
-name: operator
-description: operator
-version: "5.7"
-kudoVersion: ">= 0.2.0"
-kubeVersion: ">= 1.14"
+name: "operator"
+description: "operator desc"
+version: "0.3.0"
+appVersion: "v1.0-rc2"
+kudoVersion: "0.8.0"
+kubernetesVersion: "1.16"
 maintainers:
-  - Bob <bob@example.com>
-  - Alice <alice@example.com>
-url: https://github.com/myoperator/myoperator
+  - name: "Billy Bob"
+    email: "bb@kudo.dev"
+url: "kudo.dev"
+tasks:
+  deploy:
+    resources:
+      - pvc.yaml
+      - deployment.yaml
+  validation:
+    resources:
+      - validation.yaml
+plans:
+  deploy:
+    strategy: serial
+    phases:
+      - name: zookeeper
+        strategy: parallel
+        steps:
+         - name: validation
+           tasks:
+             - validation
+           delete: true
+```
+
+An example looks like:
+
+```
+name: "zookeeper"
+version: 0.2.0
+kudoVersion: 0.5.0
+appVersion: 3.4.14
+kubernetesVersion: 1.15.0
+maintainers:
+  - name: Tom Runyon
+    email: runyontr@gmail.com
+url: https://zookeeper.apache.org/
 tasks:
   - name: deploy
     kind: Apply
@@ -239,16 +267,34 @@ This file undergoes a Go template pass on Instance instantiation before being pa
 The `params.yaml` file is a struct that defines parameters for operator. This can articulate descriptions, defaults, and triggers, etc. In the MySQL example, this looks like:
 
 ```yaml
-backupFile:
-  description: "The name of the backup file"
-  default: backup.sql
-password:
-  default: password
-  description: "Password for the mysql instance"
-  displayName: "Password"
-  trigger: deploy
-notrequiredparam:
-  description: "This parameter is not required"
+apiVersion: kudo.dev/v1beta1
+parameters:
+  - name: "parameter_name"
+    displayName: "parameter display"
+    description: "parameter desc"
+    required: true
+    default: "param default"
+    trigger: "backup"    
+```
+
+An example looks like:
+
+```yaml
+NODE_COUNT:
+  description: "Number of nodes spun up for Zookeeper"
+  default: 3
+  displayName: "Node Count"
+
+MEMORY:
+  description: Amount of memory to provide to Zookeeper pods
+  default: "1Gi"
+
+CPUS:
+  description: Amount of cpu to provide to Zookeeper pods
+  default: "0.25"
+
+STORAGE_CLASS:
+  description: "The storage class to be used in volumeClaimTemplates. By default its not required and the default storage class is used."
   required: false
 ```
 

diff --git a/keps/0010-package-manager.md b/keps/0010-package-manager.md
@@ -5,11 +5,11 @@ short-desc: KUDO Packages and basic repository description
 authors:
   - "@alenkacz"
   - "@fabianbaier"
-  - "@gkleiman"
+  - "@kensipe"
 owners:
   - "@alenkacz"
   - "@fabianbaier"
-  - "@gkleiman"
+  - "@kensipe"
 editor: TBD
 creation-date: 2019-05-16
 status: implementable
@@ -20,19 +20,20 @@ status: implementable
 ## Table of Contents
 
 * [Table of Contents](#table-of-contents)
-* [Summary](#summary)
-* [Motivation](#motivation)
- * [Goals](#goals)
- * [Non-Goals](#non-goals)
-* [Proposal](#proposal)
- * [User Stories](#user-stories)
-    * [Operator Developer](#operator-developer)
-    * [Cluster Administrator](#cluster-administrator)
- * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
- * [Risks and Mitigations](#risks-and-mitigations)
-* [Graduation Criteria](#graduation-criteria)
-* [Implementation History](#implementation-history)
-* [Infrastructure Needed](#infrastructure-needed)
+  * [Summary](#summary)
+  * [Motivation](#motivation)
+     * [Goals](#goals)
+     * [Non-Goals](#non-goals)
+  * [Proposal](#proposal)
+     * [User Stories](#user-stories)
+        * [Operator Developer](#operator-developer)
+        * [Cluster Administrator](#cluster-administrator)
+     * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+     * [Index File Specification](#index-file-specification)
+     * [Risks and Mitigations](#risks-and-mitigations)
+  * [Graduation Criteria](#graduation-criteria)
+  * [Implementation History](#implementation-history)
+  * [Infrastructure Needed](#infrastructure-needed)
 
 ## Summary
 
@@ -145,10 +146,10 @@ In the long term it will conform with KEP-0009 and have the following structure:
 
 The advantage of having a flat structure withing the hosted repo environment is, that for distribution the opinionated structure within the `.tgz` file is not much of importance and can be subject to change without breaking other assumptions.
 
-For example, the `/kafka/2.2.0` folder (with whatever underlying structure) is zipped to `kafka-2.2.0.tgz`, where `2.2.0` is the current SemVer version of the Package. 
+For example, the `/kafka/2.2.0` folder (with whatever underlying structure) is zipped to `kafka-2.2.0.tgz`, where `2.2.0` is the current SemVer version of the Package.
 
 The version of a Package (e.g., `kafka-0.1.0` or `kafka-0.2.0`) does not have to match the current version of KUDO itself but it follows its own SemVer timeline. The zipped Operator, called Package, is made available through any HTTP Server.
- 
+
 Our official repository is hosted on Google Cloud Storage and following a flat structure:
 
 ```bash
@@ -167,12 +168,75 @@ Our official repository is hosted on Google Cloud Storage and following a flat s
 
 We rely on just an HTTP Server, e.g. the out-of-the-box solution that Google Cloud Storage provides, that serves operator `tgz` files and makes them available to users.
 
-The logic for keeping the operators in sync should live in the CLI and is not defined on this KEP . That way the HTTP server only has to serve the index and the Package `tgz` files, without having to implement any business logic. 
+The logic for keeping the operators in sync should live in the CLI and is not defined on this KEP . That way the HTTP server only has to serve the index and the Package `tgz` files, without having to implement any business logic.
 
 The proposed structure is fairly easy to replicate and highly customizable.
 
 Safety when distributing our Packages is another concern. As we continue working on this KEP we will add more details on how we can verify and prevent `Arbitrary software installation`, `Vulnerability to key compromises`, etc. For now using HTTPS to fetch the index and Packages is considered sufficient.
 
+### Index File Specification
+
+`index.yaml` is the base definition of a repository.  It follows the following reference format.
+
+```yaml
+apiVersion: v1
+entries:
+  zookeeper:
+  - name:  zookeeper
+    version: "1.0.0"
+    appVersion: "3.10.5"
+    description: "description"
+    maintainers: 
+    - name: "Billy Bob"
+      email: "bb@kudo.dev"
+    digest: 94d436c2e7ee70c3b63c2b76b653f09fd326bc756a018e10f761261d17516eec
+generated: "2020-02-21T14:02:36.57755-06:00"
+```
+
+An example looks like:
+```yaml
+apiVersion: v1
+entries:
+  elastic:
+  - digest: 98beef6e771a64e42275b34059cde0bcf5244493a6511d1229bf3dd8f44c4791
+    maintainers:
+    - email: michael.beisiegel@gmail.com
+      name: Michael Beisiegel
+    name: elastic
+    urls:
+    - https://kudo-repository.storage.googleapis.com/0.7.0/elastic-0.1.0.tgz
+    version: 0.1.0
+  kafka:
+  - appVersion: 2.3.0
+    digest: e80c7b783d327190d489159e89e0a005a6a8b00610bdb7e8b1bea73c49bf485a
+    maintainers:
+    - email: zmalikshxil@gmail.com
+      name: Zain Malik
+    name: kafka
+    urls:
+    - https://kudo-repository.storage.googleapis.com/0.7.0/kafka-0.2.0.tgz
+    version: 0.2.0
+  - appVersion: 2.2.1
+    digest: 3d0996ac19b9ff25c8d41f0b60ad686be8b1f73dd4d3d0139c6cdd1b1c4ae3e7
+    maintainers:
+    - email: zmalikshxil@gmail.com
+      name: Zain Malik
+    name: kafka
+    urls:
+    - https://kudo-repository.storage.googleapis.com/0.7.0/kafka-0.1.2.tgz
+    version: 0.1.2
+  - appVersion: 2.2.1
+    digest: f576f92b0bd931a7792a0a0266865e8f20509c9b32b7f4d7d7b8856bf3bd1275
+    maintainers:
+    - email: zmalikshxil@gmail.com
+      name: Zain Malik
+    name: kafka
+    urls:
+    - https://kudo-repository.storage.googleapis.com/0.7.0/kafka-0.1.0.tgz
+    version: 0.1.0
+generated: "2019-09-16T10:26:23.331123-05:00"
+```
+
 ### Risks and Mitigations
 
 The changes proposed in this KEP are not necessarily backwards compatible and might prevent older versions of the CLI from installing Operators.
@@ -203,4 +267,4 @@ Infrastructure that will be affected is:
 
 * https://github.com/kudobuilder/operators
 * Our CICD Pipeline for publishing Operators
-* CLI needs to adopt the standards developed here
+* CLI needs to adopt the standards developed here