kudobuilder/kudo.dev

https://kudo.dev

kudo.dev's Issues

Sections for operator parameters. How parameters work in KUDO.

🛬 Write "What is KUDO" introductory section

Name

"What is KUDO" introductory section

Description

The landing page needs to immediately appeal to all types of users:

• Beginners who don’t know what an operator is - Newbies
• Human operators who want to run their application - Application operators
• Kubernetes experts who know about operators - Operator developers

The introductory section should speak to all of these, and include at least the following concepts at a high (yet specific) level:

• Operator pattern and the problems it addresses
• Stateless vs. stateful
• Operator development tooling
• How does KUDO help

Estimated Length

• Short (300-500 words, possibly a few code snippets)

Metadata

• Difficulty Level:
• Categories:
• Persona:

KUDO Comparison to Infrastructure as Code tools (Ansible, Terraform)

As a user of IaaC tooling, why should I use a tool like KUDO?

What should I expect to learn?

By the end of this article, I will understand how KUDO and IaaC tooling can work together, and why operators are important to extending the capabilities existing IaaC tools.

What pre-requisite knowledge am I expected to have?

Base understanding of tooling such as Chef, Ansible, Terraform, Puppet, etc.

Estimated Length

• Medium (500-700 words, complex)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona:

[Zookeeper] Backup/Restore Runbook

Link code snippets from existing examples in KUDO

What would you like to be added:
Currently, the example YAMLs in, e.g., Developing Operators are part of the documentation. To always ensure their correctness, they should be code snippets taken from the examples provided by KUDO instead. This could be done by adding a pinned version of KUDO as a Git submodule to this repository.

Why is this needed:
This will ensure that the examples in the documentation work. Especially once their correctness is ensured with integration tests (e.g., kudobuilder/kudo#828).

Create sections for KUDO concepts that have features. Also provides YAML and examples.

• Operator
• Instance
• Plans
• Phase
• Step
• Tasks
  • Pipe Task
  • Apply Task
  • Delete Task

Remove mentions of planexecution, update commands/outputs in cli.md

Which page is affected?:

• content/docs/concepts.md
• content/docs/faq.md
• content/docs/cli.md
• content/docs/deployment/10-crds.yaml

What exactly is broken?:

The concept of PlanExecutions was removed on KUDO 0.7.2. Having it on the documentation is confusing.

Docs say `kubectl kudo` plugin is optional but doesn't describe how to use KUDO without it

What would you like to be added: Provide details on how to use KUDO without the kubectl kudo plugin or no longer mention that the plugin is optional.

Elastic Runbooks:

KUDO Cassandra comparison for Cassandra users (Cassandra Operators, AWS Managed Cassandra, DyanmoDB, IaaC, Hand Managed)

Description

As a Cassandra user, I want to understand how the KUDO Cassandra operator stacks up to other other ways of running it.

What should I expect to learn?

By the end of this article, I will know how KUDO and KUDO Cassandra benefits my application stack.

What pre-requisite knowledge am I expected to have?

Working knowledge of Cassandra

Estimated Length

• Long (700+ words)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona: End User

🛬 Write secondary sections

Name

Write secondary sections expanding on:

• How do I get started?
• How do I write an operator?
• How do I deploy an application?
• Why do folks love KUDO?

Description

Describe the KUDO 'lifestyle' and why it makes things better for the problems it's designed to solve.

Some brief one or two line code snippets per context that get folks up
and running immediately with KUDO might be worthwhile here.

Possibly a short demo.

Links that hand off to other sections and salient bits of content.

Estimated Length

• Medium (500-700 words, complex)

Metadata

• Difficulty Level:
• Categories:
• Persona:

🛬 Who is using KUDO?

Name

Who is using KUDO?

Description

We need another section that highlights customers that are using KUDO
right now for various use-cases. These could be technology companies
that are developing operators for their own services, as well as
companies that are using KUDO to manage other applications.

These should be companies that inspire confidence in anyone
potentially interested in KUDO.

• MayaData
• ArangoDB
• Salesforce
• Replicated.com

We might need a CTA via Slack.

Estimated Length

• Short (300-500 words, possibly a few code snippets)

Metadata

• Difficulty Level:
• Categories:
• Persona:

KUDO vs. Custom Controller (Kubernetes clients, Kubebuilder, Operator SDK)

Description

As an operator developer, I want to understand the difference between KUDO and code oriented operator tools

What should I expect to learn?

By the end of this article, I will understand how KUDO enables productivity and understandability for operator developers and when to use a code oriented tool versus a high level framework such as KUDO

What pre-requisite knowledge am I expected to have?

Kubernetes basics and an understanding of what an operator is

Estimated Length

• Medium (500-700 words, complex)

Metadata

• Difficulty Level: Beginning
• Categories:
• Persona:

Spark Runbooks:

• Launch a Spark Job
• Viewing Spark Job output

[Zookeeper] Vertical Scale Runbook

Create a section that provides an overview over the components of a KUDO operator and how they relate to each other.

Plans, tasks, trigger, CRs that get created when deploying an operator, ...

KUDO Admin Runbooks

• How to create an operator from scratch (first operator)
• How to debug an operator installation
• How to uninstall kudo
• How to uninstall an operator
• How to add a repo to a client
• Create a operator repo
• How to add an operator to a repo
• How to air gap kudo
• How to secure kudo (sa)

recipes?

• How to create a daemon job

Rename repository to kudo.dev

Just a thought - it's a bit more descriptive of which www we're actually talking about. :)

KUDO Comparison for Operator Developers

Description

As a developer wanting to enable my users to deploy my application to Kubernetes, I want to compare the options for deploying software to Kubernetes clusters, so I can choose KUDO.

Each subsection of this document will have it's own task separated by paradigm, with example tools under that paradigm in a subheading.

What should I expect to learn?

By the end of the article, you will understand the differences between KUDO and other tools in the market, and where KUDO differentiates itself.

What pre-requisite knowledge am I expected to have?

General knowledge of what Kubernetes and config management concepts

Estimated Length

• Long (700+ words)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona:

Don't provide deployment YAMLs for KUDO as part of the docs, but as part of KUDO instead.

In https://kudo.dev/docs/#install-kudo-into-your-cluster the YAMLs to deploy KUDO are provided as part of the docs. They should be distributed by https://github.com/kudobuilder/kudo instead to allow users to install them directly from a checked-out repo or tarball and to have developers change them directly in the repo.

Overview page for KUDO concepts.

• Overview
• Motivation for KUDO existence
• Main concepts:
  Short description relations between:
  • Operator Package
  • Operator Repository
  • KUDO Manager
  • Plans
  • Operator Parameters
  • Default plans (deploy, upgrade, cleanup)
• Under the hood:
  • KUDO CRDs
    • Operator
    • OperatorVersion
    • Instance

Dates for community events is wrong for some users, based on their TZ

Which page is affected?:
https://kudo.dev/community/events.html

What exactly is broken?:
The dates listed on this page might be wrong if the user's TZ is set to something other than UTC.

For example, we've had someone complain that all dates are out by -1 - e.g the Arkansas meetup being shown as on the 16th instead of the 17th.

Add a note about comparison to Tekton to the docs

What would you like to be added:
Comparison page should mention how we differ from Tekton. This was one of the questions raised during the webinar.

Why is this needed:

KUDO comparison versus Static Definition Formats (Helm v2, v3, raw YAML, Kustomize)

Description

As a Kubernetes developer, I want to understand the difference between controller/operator-managed tools versus static definition formats.

What should I expect to learn?

Where static definitions fall short and where operator tooling shines.

What pre-requisite knowledge am I expected to have?

A working knowledge of Kubernetes YAML

Estimated Length

• Short (300-500 words, possibly a few code snippets)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona: Operator Developer

Restructure the KUDO documentation to explain concepts and features

Description

Structure Concepts and Features to allow user to drill down from higher level descriptions to actual features.
A section that explains the concepts of KUDO will provide an overview of what makes an operator, i.e. tasks, plans, triggers.
Then the actual features are sections for tasks, plans, triggers going into more detail.

What should I expect to learn?

Tell me what I should expect to learn by the end of reading this content?

What pre-requisite knowledge am I expected to have?

What do I need to know to succeed with this content? If external, ideally link prior art for this knowledge here.

Estimated Length

• Long (700+ words)

Metadata

• Difficulty Level:
• Categories:
• *Persona:

Enhance comparison between kudo and similar tools

What would you like to be added:
At the moment the comparison table page does nicely compare the base features of KUDO vs other known tools however extra points could be added to clear up the context and explain how KUDO is unique versus the other tools.

In addition a tools such as kapitan may not be seen initially as a direct competitor but I believe that it is in that region, so extension of that table with Kapitan would be rather useful

Why is this needed:

Having headings such as: Project, Definition Language, Uses CRDs | Dependencies, Multi Step, Parameters without proper explanation of the context and why each feature is useful is making it difficult to understand from prospective user's perspective.

The more summarised context the better it is to understand, a fine balance between the amount of information (detail) and how informative and appropriate this information is, is rather necessary.

Create a section for cluster operators that provides an overview how KUDO runs on a cluster. Architecture overview, security (RBAC)

KUDO Kafka Comparison vs. Competitors (Strimzi and other operators), AWS Managed Kafka Service, Infra as Code managed Kafka, and hand deployed Kafka

Description

As an end user, I want to understand how KUDO Kafka stacks for all levels of running Kafka, from hand-managed to operator on Kubernetes.

What should I expect to learn?

By the end of this article, I should understand why KUDO believes operators are a Good Thing™ and the benefits KUDO providers over other forms of running Kafka on Kubernetes.

What pre-requisite knowledge am I expected to have?

An understanding of Kafka

Estimated Length

• Long (700+ words)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona: Kafka Developer

Runbook: upgrade KUDO Kafka version

mailing list link broken

Which page is affected?:

https://kudo.dev/community/

What exactly is broken?:

Mailing List link goes to a non-existent or private group. I receive the alert: "This group either doesn't exist, or you don't have permission to access it. If you're sure this group exists, contact the Owner of the group and ask them to give you access." Here's a screenshot:

Which device do you use?:

Chrome browser on Mac.

Update/upgrade docs

What would you like to be added:
Add docs about how to update and upgrade your operator under features docs section. Make sure to explain what are update and upgrade plans and how to use them through CLI.

Why is this needed:

Nit: `kubectl kudo install` supports multiple installation methods

Which page is affected?: https://kudo.dev/docs/cli.html#commands

What exactly is broken?: The description of kubectl kudo install says that it installs operators from the operators repository. But it also allows for other installation methods as described in https://kudo.dev/docs/cli.html#examples

Tracking issue for reloader docs

So we don't forget to document the work we did in kudobuilder/kudo#996.

What is KUDO? for landing page

KUDO vs. Other High Level Controller Frameworks (metacontroller)

Description

As an operator developer, I want to understand the difference between KUDO and other declarative tools in the same class, such as metacontroller.

What should I expect to learn?

By the end of this article, I will understand how KUDO's declarative approach provides advantages over mixed software like metacontroller.

What pre-requisite knowledge am I expected to have?

Basic knowledge of Kubernetes concepts, and a base understanding of operators

Estimated Length

• Medium (500-700 words, complex)

Metadata

• Difficulty Level: Beginner
• Categories:
• Persona:

Kafka Runbooks

• Upgrade Kafka version @zmalik
• Expose Kafka external to the cluster @zmalik
• How to debug Kafka instance @zmalik
• Install multiple Kafkas in a cluster (multi ns, in same ns) @porridge kudobuilder/operators#199
• Mirroring Kafka Cluster @porridge kudobuilder/operators#202
• Securing Kafka (distributing custom certs/service accounts)
• Bootstrap scripts
• (*) Distribute Certificates (Pipelines tasks)
• Dummy workload
• Add service monitor to Kafka
• Update parameter used in CM

🛬 What kind of workloads can you run with KUDO right now?

Name

What kind of workloads can you run with KUDO right now?

We should emphasise and promote high-quality KUDO Operators that already exist.

Description

The landing page needs a section with logos of what can you run with
KUDO:

• Cassandra
• Spark
• Kafka
• Flink
• Zookeeper

Should be a bunch of logos with links to various projects.

Estimated Length

• Short (300-500 words, possibly a few code snippets)

Metadata

• Difficulty Level:
• Categories:
• Persona:

Document pipes for 0.9.0 release

What would you like to be added:
Write a doc explaining what are pipes and how to use them for our docs for 0.9.0 release. Features section under https://kudo.dev/docs/features.html would be a good place I think.

Why is this needed:

Updates for Community Content section

What would you like to be added:
There's been a bunch of KUDO-related content (videos etc.) created by the likes of @djannot and @kensipe. It'd be great to get these collected and added to the website, maybe under the 'Community Content' section.

Cassandra Runbooks

• Accessing Cassandra from within the cluster and externally @porridge mesosphere/kudo-cassandra-operator#39
• Upgrading a KUDO Cassandra instance @porridge mesosphere/kudo-cassandra-operator#32
• Enabling metrics with Prometheus and Grafana @porridge mesosphere/kudo-cassandra-operator#35
• Running a cassandra-stress workload @mpereira
• Running nodetool status @mpereira
• (*) Backup / Restore (still needs to be implemented)

Many pages don't show up in the navigation

Which page is affected?: Many, among them the examples, e.g. for Apache Kafka, the whole testing folder, the contributing page

What exactly is broken?: These pages aren't shown in the left-side menu but are part of the documentation repo. Some of these pages are actually rendered and reachable under their intended URL, e.g. https://kudo.dev/docs/contributing.html.

Provide copy&paste for developing operators tutorial

What would you like to be added:
As requested here
https://github.com/kudobuilder/www/pull/84/files#r346814591

Why is this needed:

provide a way to order menu links

What would you like to be added:
Some control over the menu links order for runbooks so we can group related docs together like runbooks or release notes above

Why is this needed:
To provide a better UX for users when navigating docs for an operator

Document cleanup plan for 0.9.0

What would you like to be added:
Write a section about purpose of cleanup plans and when and how are they executed for 0.9.0 release. Putting it under features might be a good idea https://kudo.dev/docs/features.html

Why is this needed:

Create automation for checking for broken URLs

I've used this in the past with great success: https://wummel.github.io/linkchecker/

We can initially just make it available via a make target or something, and eventually add it to a CI job.

Anatomy of an operator

Describe that an operator consists of operator.yaml, params and templates. Link to concepts, templates, ... pages

Add support for RSS

What would you like to be added:

Support for RSS, in particular for the Community / Events section.

Why is this needed:

This has been requested by a couple of people as an easy way of being notified of any new or upcoming KUDO-related activities.

🛬 Landing page restructuring

Name

Landing page restructuring

Description

The landing page needs restructuring to priorise content:

• Immediately explain what KUDO is and the problems it's designed to solve
• What someone can do with KUDO
• Workloads you can run with KUDO
• Who uses KUDO - should inspire confidence in the tool and its community

Estimated Length

• Short (300-500 words, possibly a few code snippets)

Metadata

• Difficulty Level:
• Categories:
• Persona:

Section for template parameters. Describes the template engine of KUDO and its features.

Document large cluster workflow for operator deployment involving multiple teams

What would you like to be added:
With the help of kudo install --skip-instance, only the Operator and OperatorVersion of a package can be installed. This can be used in larger cluster by cluster ops teams preparing operators for other teams. I.e., this allows a workflow where specific teams are allowed to create instances from OperatorVersions already in the cluster, giving cluster ops more control on what is being deployed on a cluster.

Why is this needed:
KUDO's support for this workflow helps in large cluster deployments managed by multiple teams with different roles.