Gardener Project Documentation Material

[g-pavlov]

Documentation Types overview

The following table summarizes the planned types of documentation.

Gardener Content Type	Definition	Example
How-to Guide	Describes how to perform a complex, task that requires to complete smaller tasks.	Upgrading kubeadm clusters
Tutorial	A step-by-step description that allows users to complete an example task with the goal to learn the details of a given feature.	Stateless Applications
Concept	Introduce a functionality or concept, covers background information.	Services
Trial	[Planned] Collection of all other content types to cover a big topic. (Currently it's not possible to reuse content, for example, a tutorial used in a trial must be copied to the trial.)	Custom Networking
Reference	Provide a reference, for example, list all command line options of gardenctl and what they are used for.	Overview of kubectl

See the Documentation Contributors Guide for more details on documentation types, how to produce and contribute them.

Target Audience

• Gardener operators/SRE (Operators): Operate a public or private service or service in "fenced" environment. Their scope is primarily installation, update/upgrade and operation of the service and its key components, tools references.
• Gardener (extension) developers (Developers): Develop extensions for Gardener for e.g. more cloud or DNS providers. Their scope is Gardener's architecture and extensibility framework.
• Gardener cluster users (Users): Use the Gardener managed service to create and operate clusters on demand. Primary concerns are day1/day2 operations in a cluster. Includes also automated operators, although they deserve special attention and sections as in fact that's the predominant way that the service will be used beyond trying it out (manually).

Kubernetes Application Developers role is not in scope for the technical documentation, but is most welcome in technical blogs as long as Gardener is concerned as a topic.

Call for content

Guides

• Concepts
  • Overview (Kubernetes managing Kubenetes, applying k8s principles to cluster management, controller (operator) pattern, control plane hosting, key components, garden, seeds and shoots)
  • Gardener Cluster Management Control Plane
    • API server
    • Scheduler
    • Controller Manager
  • Gardenlet
  • Seed admission controller
  • Seed Bootstrapping
  • Infrastructure Providers
  • Networking
    • Network policies
    • Reverse shoot to seed tunneling
    • SNI passthrough proxy for kube-apiservers
  • Worker Nodes Management
  • DNS and certificates management
  • Scaling
  • Control plane migration
  • Backup and Restore
• Installation [new|tbd] how to use the new Gardener landscaper
  • Local installation
  • Public hyperscalers
    • ...
  • Private hyperscalers
    • ...
  • Manual installation
    • Gardener
    • Gardenlet
    • Add nodes
    • Setting up seed cluster
    • Hardening the community setup
  • Feature gates
  • Container images
• Operations ops guide + Troubleshooting
• Usage
  • Client tools
    • Authenticating with Identity Provider
    • ...
  • Account onboarding incl. non-managed account resources
  • Working with projects [new] in a project in dashboard UI.
  • Organizing access control [new] in a project in dashboard UI.
  • Setting up ingress [new] (also with custom domain) Usually, that's one of the first tasks to do for a new cluster. There's a tutorial that shows that with istio but a simpler and focused guide may help too and also complete the learning trail.
  • External DNS management [new] - based on that but we need extended operations only here. See also Update DNS guide for devs #119
  • Certificates management
  • Monitoring and alerts [new] what is monitored, how to find the monitoring ui (grafana), how to make best use of it and for what.
  • Logging
  • Hibernation [update]
  • Working with worker pools: describe shortly how worker nodes relate to account resources, how to use them in dashboard, how to manage them manually. Autoscaling can be merged here if not too large.
  • Autoscaling - describe how to influence it to benefit and in what ways, and how not to get in its way
  • Cluster maintenance
  • Trigger shoot operations
  • Kubeconfig rotation why would users need that and how to do it in the Dashboard
  • Operating with kubectl [new] - command line tasks with Gardener clusters - projects, access control, ...
  • Web Terminal [new] - a short use of the web terminal feature
• Extensions
  • Overview
  • Extension controller registration
  • Cluster
  • Extension Points
    • ...
  • Project roles
• Development
  • Code contributors guidelines [needs update]
  • Gardener Enhancement Process
  • Gardener Enhancement Proposals
    • ...
  • Integration testing
  • ...

All material except those in "Concepts" are How-to Guides.
"Concepts" are Concept type of material.

Tutorials

• Developing your first extension
• Create clusters in restricted environment
• Gardener 101
  • Installing your first Gardener in cluster
  • Registering a seed cluster (?)
  • Working with projects
  • Creating your first shoot cluster
  • Deploying a Kubernetes application
  • ...
• ...

[gardener-robot]

@g-pavlov You have mentioned internal references in the public. Please check.

[gardener-robot]

@g-pavlov You have mentioned internal references in the public. Please check.

[vlerenc]

I am not quite sure where the difference is between "How-to Guide" and "Tutorial" and why we would add "Trial".

[Kristian-ZH]

As we had changed the documentation structure in the past and now the website is structured by components, I do not think that this issue is still relevant

/close