From 484f6212f3e80508ee9a0ef7885c1116f0acaaf7 Mon Sep 17 00:00:00 2001 From: Ken Sipe Date: Fri, 6 Mar 2020 17:10:59 -0600 Subject: [PATCH] KEP-0009 and KEP-0010 Updates with Examples and TOC (#847) Signed-off-by: Ken Sipe --- keps/0009-operator-toolkit.md | 140 ++++++++++++++++++++++------------ keps/0010-package-manager.md | 102 ++++++++++++++++++++----- 2 files changed, 176 insertions(+), 66 deletions(-) diff --git a/keps/0009-operator-toolkit.md b/keps/0009-operator-toolkit.md index 9106bcd89..325afcea9 100644 --- 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 - - Alice -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 index c1ffa36a8..8e0856a16 100644 --- 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 \ No newline at end of file +* CLI needs to adopt the standards developed here