-
Notifications
You must be signed in to change notification settings - Fork 103
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
KEP-0009 and KEP-0010 Updates with Examples and TOC (#847)
Signed-off-by: Ken Sipe <[email protected]>
- Loading branch information
Showing
2 changed files
with
176 additions
and
66 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 <[email protected]> | ||
- Alice <[email protected]> | ||
url: https://github.com/myoperator/myoperator | ||
- name: "Billy Bob" | ||
email: "[email protected]" | ||
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: [email protected] | ||
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 | ||
``` | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: "[email protected]" | ||
digest: 94d436c2e7ee70c3b63c2b76b653f09fd326bc756a018e10f761261d17516eec | ||
generated: "2020-02-21T14:02:36.57755-06:00" | ||
``` | ||
An example looks like: | ||
```yaml | ||
apiVersion: v1 | ||
entries: | ||
elastic: | ||
- digest: 98beef6e771a64e42275b34059cde0bcf5244493a6511d1229bf3dd8f44c4791 | ||
maintainers: | ||
- email: [email protected] | ||
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: [email protected] | ||
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: [email protected] | ||
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: [email protected] | ||
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 |