Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Try to improve concepts docs #473

Merged
merged 10 commits into from
Jul 4, 2019
Merged

Try to improve concepts docs #473

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
d3f5ecf
Try to improve concepts docs
alenkacz Jul 1, 2019
a7619c9
Update docs/concepts.md
alenkacz Jul 2, 2019
0665f93
Update docs/concepts.md
alenkacz Jul 2, 2019
25d0477
Update docs/concepts.md
alenkacz Jul 2, 2019
9748adb
Update docs/concepts.md
alenkacz Jul 2, 2019
7291b98
Update docs/concepts.md
alenkacz Jul 2, 2019
ad09bc6
Update docs/concepts.md
alenkacz Jul 2, 2019
efda4e3
Merge branch 'master' into av/concepts
kensipe Jul 2, 2019
c60e941
Update docs/concepts.md
alenkacz Jul 3, 2019
6f28128
Merge branch 'master' into av/concepts
alenkacz Jul 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions docs/concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,34 @@ menu: docs

# Concepts

## Application

Any kind of software that you would want to run in your Kubernetes cluster. It can be as simple as cleanup job or as complex as distributed system like Kafka.

## Operator

High-level description of a deployable application. Contains metadata about the application (e.g., [Apache Kafka](https://github.com/kudobuilder/kudo/blob/master/config/samples/kafka-operator.yaml)).
High-level description of a deployable application to be run in a k8s cluster. Contains metadata about the application (e.g., [Apache Kafka](https://github.com/kudobuilder/kudo/blob/master/config/samples/kafka-operator.yaml)).
You can have multiple versions of Kafka ready to be installed in your cluster, all will belong to the same Operator.

## OperatorVersion

Specific version of a deployable application, including configuration and lifecycle hooks for deployments, upgrades, and rollbacks (e.g., [Kafka version 2.4.0](https://github.com/kudobuilder/kudo/blob/master/config/samples/kafka-operatorversion.yaml)).
This is already complete definition of application to be installed (except overridable parameters). By adding OperatorVersion to your cluster, no application is running yet.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This is already complete definition of application to be installed (except overridable parameters). By adding OperatorVersion to your cluster, no application is running yet.
This is already a complete definition of an application to be installed (except overridable parameters). By adding OperatorVersion to your cluster, no application is running yet.

What do you mean by By adding OperatorVersion to your cluster, no application is running yet. ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that there are not pods or anything running. You have to create instance to actually run the application (= to actually run kafka)


## Instance

Resource created to manage an instance of specific OperatorVersion. Instances are pets and have the same name throughout its entire lifecycle. (e.g., [Kafka 2.4.0 cluster with 1 broker](https://github.com/kudobuilder/kudo/blob/master/config/samples/kafka-instance.yaml)).
When you create an instance, you provide missing parameters for the installed OperatorVersion. Creating an instance typically causes rendering of those parameters in your templates, such as services, pods or statefulsets. Once rendered these objects will then be applied with the given parameters to your cluster.
Instances have the same name throughout its entire lifecycle. (e.g., [Kafka 2.4.0 cluster with 1 broker](https://github.com/kudobuilder/kudo/blob/master/config/samples/kafka-instance.yaml)).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also mention that we add random strings #437 ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you think this is the right place? 🤔 not sure, but no strong opinion as well.

You can create multiple instance of an OperatorVersion in your cluster (e.g. different Kafka instances for different teams).

## Plan

Plans capture the individual steps of operational tasks such as a deploy, backup/restore, or version upgrade. Think of them as runbooks written in a structured way that can be executed by software. Plans are made up of phases, and phases have one or more steps.
Operator typically define several plans. Plans capture the individual steps of operational tasks. Think of them as runbooks written in a structured way that can be executed by software. Plans are made up of phases, and phases have one or more steps.

Every OperatorVersion must contain a `deploy` plan which is the default plan to deploy an application to the cluster. For more complex systems, you would want to define a plan for backup and restore or upgrade.

## PlanExecution

Kudo-managed resource defining the inputs and status of an instance’s executable plans (e.g., upgrade kafka from version 2.4.0 -> 2.4.1).
Every time a plan is executed, the corresponding PlanExecution CRD is stored with inputs and status of the plan (e.g., when you upgrade Kafka from version 2.4.0 -> 2.4.1).
You can query the status of any plan via the CLI.