From b22947afc31e1b2c8c96d6ed6385e19f8516ba72 Mon Sep 17 00:00:00 2001 From: Jessica Yao Date: Thu, 12 Oct 2017 16:12:38 -0700 Subject: [PATCH] [docs][glossary] Add page that lists all standardized k8s terms (#5657) * Add comprehensive glossary page Additional Authors: * Andrew Chen * Steve Perry * incorporate Tim's feedback * address zach's comments * address more comments * add additional crosslinking * Add platform developer, tweak formatting for disambiguation cases or multiparagraph definitions. --- _data/canonical-tags.yml | 12 -- _data/canonical-tags/architecture.yaml | 3 + _data/canonical-tags/community.yaml | 3 + _data/canonical-tags/core-object.yaml | 3 + _data/canonical-tags/extension.yaml | 3 + _data/canonical-tags/fundamental.yaml | 3 + _data/canonical-tags/networking.yaml | 3 + _data/canonical-tags/operation.yaml | 3 + _data/canonical-tags/security.yaml | 3 + _data/canonical-tags/storage.yaml | 3 + _data/canonical-tags/tool.yaml | 3 + _data/canonical-tags/user-type.yaml | 3 + _data/canonical-tags/workload.yaml | 3 + _data/glossary/_example.yml | 8 +- _data/glossary/application-architect.yaml | 11 ++ _data/glossary/application-developer.yaml | 11 ++ _data/glossary/approver.yaml | 10 ++ _data/glossary/cla.yaml | 8 + _data/glossary/cluster-architect.yaml | 12 ++ _data/glossary/cluster-operator.yaml | 16 ++ _data/glossary/cluster.yaml | 9 ++ _data/glossary/code-contributor.yaml | 11 ++ _data/glossary/container.yaml | 9 ++ _data/glossary/contributor.yaml | 8 + _data/glossary/cronjob.yaml | 9 ++ _data/glossary/deployment.yaml | 10 ++ _data/glossary/developer.yaml | 15 ++ _data/glossary/downstream.yaml | 11 ++ _data/glossary/helm-chart.yaml | 9 ++ _data/glossary/ingress.yaml | 10 ++ _data/glossary/istio.yaml | 12 ++ _data/glossary/kops.yaml | 18 +++ _data/glossary/kubeadm.yaml | 9 ++ _data/glossary/kubectl.yaml | 9 ++ _data/glossary/kubernetes-api.yaml | 12 ++ _data/glossary/maintainer.yaml | 8 + _data/glossary/member.yaml | 10 ++ _data/glossary/minikube.yaml | 9 ++ _data/glossary/platform-developer.yaml | 10 ++ _data/glossary/pod.yaml | 16 ++ _data/glossary/rbac.yaml | 9 ++ _data/glossary/reviewer.yaml | 8 + _data/glossary/service.yaml | 9 ++ _data/glossary/sig.yaml | 11 ++ _data/glossary/statefulset.yml | 18 +-- _data/glossary/upstream.yaml | 11 ++ _data/glossary/wg.yaml | 10 ++ _data/reference.yml | 3 +- _includes/templates/glossary/README.md | 16 +- _layouts/docwithnav.html | 4 +- css/glossary.css | 64 ++++++++ docs/reference/glossary.md | 66 ++++++++ images/link.png | Bin 0 -> 1666 bytes js/glossary.js | 181 ++++++++++++++++++++++ test/glossary_test.go | 45 ++++-- 55 files changed, 743 insertions(+), 50 deletions(-) delete mode 100644 _data/canonical-tags.yml create mode 100644 _data/canonical-tags/architecture.yaml create mode 100644 _data/canonical-tags/community.yaml create mode 100644 _data/canonical-tags/core-object.yaml create mode 100644 _data/canonical-tags/extension.yaml create mode 100644 _data/canonical-tags/fundamental.yaml create mode 100644 _data/canonical-tags/networking.yaml create mode 100644 _data/canonical-tags/operation.yaml create mode 100644 _data/canonical-tags/security.yaml create mode 100644 _data/canonical-tags/storage.yaml create mode 100644 _data/canonical-tags/tool.yaml create mode 100644 _data/canonical-tags/user-type.yaml create mode 100644 _data/canonical-tags/workload.yaml create mode 100644 _data/glossary/application-architect.yaml create mode 100644 _data/glossary/application-developer.yaml create mode 100644 _data/glossary/approver.yaml create mode 100644 _data/glossary/cla.yaml create mode 100644 _data/glossary/cluster-architect.yaml create mode 100644 _data/glossary/cluster-operator.yaml create mode 100644 _data/glossary/cluster.yaml create mode 100644 _data/glossary/code-contributor.yaml create mode 100644 _data/glossary/container.yaml create mode 100644 _data/glossary/contributor.yaml create mode 100644 _data/glossary/cronjob.yaml create mode 100644 _data/glossary/deployment.yaml create mode 100644 _data/glossary/developer.yaml create mode 100644 _data/glossary/downstream.yaml create mode 100644 _data/glossary/helm-chart.yaml create mode 100644 _data/glossary/ingress.yaml create mode 100644 _data/glossary/istio.yaml create mode 100644 _data/glossary/kops.yaml create mode 100644 _data/glossary/kubeadm.yaml create mode 100644 _data/glossary/kubectl.yaml create mode 100644 _data/glossary/kubernetes-api.yaml create mode 100644 _data/glossary/maintainer.yaml create mode 100644 _data/glossary/member.yaml create mode 100644 _data/glossary/minikube.yaml create mode 100644 _data/glossary/platform-developer.yaml create mode 100644 _data/glossary/pod.yaml create mode 100644 _data/glossary/rbac.yaml create mode 100644 _data/glossary/reviewer.yaml create mode 100644 _data/glossary/service.yaml create mode 100644 _data/glossary/sig.yaml create mode 100644 _data/glossary/upstream.yaml create mode 100644 _data/glossary/wg.yaml create mode 100644 css/glossary.css create mode 100644 docs/reference/glossary.md create mode 100644 images/link.png create mode 100644 js/glossary.js diff --git a/_data/canonical-tags.yml b/_data/canonical-tags.yml deleted file mode 100644 index d5c4bcfdec..0000000000 --- a/_data/canonical-tags.yml +++ /dev/null @@ -1,12 +0,0 @@ -- Fundamental -- API Object -- Metadata -- Configuration -- Security -- Networking -- Storage -- Operation -- Workload -- Component -- API -- Extension diff --git a/_data/canonical-tags/architecture.yaml b/_data/canonical-tags/architecture.yaml new file mode 100644 index 0000000000..369aa36cc0 --- /dev/null +++ b/_data/canonical-tags/architecture.yaml @@ -0,0 +1,3 @@ +id: architecture +name: Architecture +description: The inner components of Kubernetes. diff --git a/_data/canonical-tags/community.yaml b/_data/canonical-tags/community.yaml new file mode 100644 index 0000000000..34a60b5df2 --- /dev/null +++ b/_data/canonical-tags/community.yaml @@ -0,0 +1,3 @@ +id: community +name: Community +description: Related to Kubernetes open-source development. diff --git a/_data/canonical-tags/core-object.yaml b/_data/canonical-tags/core-object.yaml new file mode 100644 index 0000000000..c816013899 --- /dev/null +++ b/_data/canonical-tags/core-object.yaml @@ -0,0 +1,3 @@ +id: core-object +name: Core Object +description: A resource type that Kubernetes supports by default. diff --git a/_data/canonical-tags/extension.yaml b/_data/canonical-tags/extension.yaml new file mode 100644 index 0000000000..6aacd8dac9 --- /dev/null +++ b/_data/canonical-tags/extension.yaml @@ -0,0 +1,3 @@ +id: extension +name: Extension +description: Supported customizations of Kubernetes. diff --git a/_data/canonical-tags/fundamental.yaml b/_data/canonical-tags/fundamental.yaml new file mode 100644 index 0000000000..f9dc8f2398 --- /dev/null +++ b/_data/canonical-tags/fundamental.yaml @@ -0,0 +1,3 @@ +id: fundamental +name: Fundamental +description: Relevant for a first-time user of Kubernetes. diff --git a/_data/canonical-tags/networking.yaml b/_data/canonical-tags/networking.yaml new file mode 100644 index 0000000000..481c02c50a --- /dev/null +++ b/_data/canonical-tags/networking.yaml @@ -0,0 +1,3 @@ +id: networking +name: Networking +description: How Kubernetes components talk to each other (and to programs outside the cluster). diff --git a/_data/canonical-tags/operation.yaml b/_data/canonical-tags/operation.yaml new file mode 100644 index 0000000000..140be06e0c --- /dev/null +++ b/_data/canonical-tags/operation.yaml @@ -0,0 +1,3 @@ +id: operation +name: Operation +description: Starting and maintaining Kubernetes. diff --git a/_data/canonical-tags/security.yaml b/_data/canonical-tags/security.yaml new file mode 100644 index 0000000000..4bb7191a6f --- /dev/null +++ b/_data/canonical-tags/security.yaml @@ -0,0 +1,3 @@ +id: security +name: Security +description: Keeping Kubernetes applications safe and secure. diff --git a/_data/canonical-tags/storage.yaml b/_data/canonical-tags/storage.yaml new file mode 100644 index 0000000000..e98d797b6e --- /dev/null +++ b/_data/canonical-tags/storage.yaml @@ -0,0 +1,3 @@ +id: storage +name: Storage +description: How Kubernetes applications handle persistent data. diff --git a/_data/canonical-tags/tool.yaml b/_data/canonical-tags/tool.yaml new file mode 100644 index 0000000000..943d1ba4b0 --- /dev/null +++ b/_data/canonical-tags/tool.yaml @@ -0,0 +1,3 @@ +id: tool +name: Tool +description: Software that makes Kubernetes easier or better to use. diff --git a/_data/canonical-tags/user-type.yaml b/_data/canonical-tags/user-type.yaml new file mode 100644 index 0000000000..8f38725720 --- /dev/null +++ b/_data/canonical-tags/user-type.yaml @@ -0,0 +1,3 @@ +id: user-type +name: User Type +description: Represents a common type of Kubernetes user. diff --git a/_data/canonical-tags/workload.yaml b/_data/canonical-tags/workload.yaml new file mode 100644 index 0000000000..4b18a36443 --- /dev/null +++ b/_data/canonical-tags/workload.yaml @@ -0,0 +1,3 @@ +id: workload +name: Workload +description: Applications running on Kubernetes. diff --git a/_data/glossary/_example.yml b/_data/glossary/_example.yml index d939c91f3c..34268a07c3 100644 --- a/_data/glossary/_example.yml +++ b/_data/glossary/_example.yml @@ -1,13 +1,13 @@ id: _example name: Example K8s Term -formerly: +aka: - Slang K8s Term - Misnomer - Formerly Known as Prince related: -- Less Fancy K8s Term -- Tangential Term -- Commonly Used With +- id-of-less-fancy-k8s-term +- id-of-tangential-term +- id-of-commonly-used-with-term tags: - Some Tag short-description: | diff --git a/_data/glossary/application-architect.yaml b/_data/glossary/application-architect.yaml new file mode 100644 index 0000000000..ad14229720 --- /dev/null +++ b/_data/glossary/application-architect.yaml @@ -0,0 +1,11 @@ +id: application-architect +name: Application Architect +related: + - application-developer +tags: + - user-type +short-description: | + A person responsible for the high-level design of an application. +long-description: > + An architect ensures that an app's implementation allows it to interact with its surrounding components in a scalable, maintainable way. + Surrounding components include databases, logging infrastructure, and other microservices. diff --git a/_data/glossary/application-developer.yaml b/_data/glossary/application-developer.yaml new file mode 100644 index 0000000000..5fc2fa9f80 --- /dev/null +++ b/_data/glossary/application-developer.yaml @@ -0,0 +1,11 @@ +id: application-developer +name: Application Developer +related: + - application-architect +tags: + - user-type +short-description: | + A person who writes an application that runs in a Kubernetes cluster. +long-description: > + An application developer focuses on one part of an application. + The scale of their focus may vary significantly in size. diff --git a/_data/glossary/approver.yaml b/_data/glossary/approver.yaml new file mode 100644 index 0000000000..5047a78283 --- /dev/null +++ b/_data/glossary/approver.yaml @@ -0,0 +1,10 @@ +id: approver +name: Approver +tags: +- community +short-description: | + A person who can review and approve Kubernetes code contributions. +long-description: > + While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution. + Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others. + Approver status is scoped to a part of the codebase. diff --git a/_data/glossary/cla.yaml b/_data/glossary/cla.yaml new file mode 100644 index 0000000000..75dd5408d3 --- /dev/null +++ b/_data/glossary/cla.yaml @@ -0,0 +1,8 @@ +id: cla +name: CLA (Contributor License Agreement) +tags: +- community +short-description: | + Terms under which a [contributor](#term-contributor) grants a license to an open source project for their contributions. +long-description: | + CLAs help resolve legal disputes involving contributed material and intellectual property (IP). diff --git a/_data/glossary/cluster-architect.yaml b/_data/glossary/cluster-architect.yaml new file mode 100644 index 0000000000..9cec933e93 --- /dev/null +++ b/_data/glossary/cluster-architect.yaml @@ -0,0 +1,12 @@ +id: cluster-architect +name: Cluster Architect +related: + - cluster + - cluster-operator +tags: + - user-type +short-description: | + A person who designs infrastructure that involves one or more Kubernetes clusters. + +long-description: | + Cluster architects are concerned with best practices for distributed systems, for example: high availability and security. diff --git a/_data/glossary/cluster-operator.yaml b/_data/glossary/cluster-operator.yaml new file mode 100644 index 0000000000..8224517881 --- /dev/null +++ b/_data/glossary/cluster-operator.yaml @@ -0,0 +1,16 @@ +id: cluster-operator +name: Cluster Operator +aka: + - Cluster Administrator +related: + - cluster + - cluster-architect +tags: + - user-type +short-description: | + A person who configures, controls, and monitors clusters. + +long-description: | + Their primary responsibility is keeping a cluster up and running, which may involve periodic maintenance activities or upgrades.
+ + **NOTE:** Cluster operators are different from the [Operator pattern](https://coreos.com/operators) that extends the Kubernetes API. diff --git a/_data/glossary/cluster.yaml b/_data/glossary/cluster.yaml new file mode 100644 index 0000000000..a85ce8d2f6 --- /dev/null +++ b/_data/glossary/cluster.yaml @@ -0,0 +1,9 @@ +id: cluster +name: Cluster +tags: +- fundamental +- operation +short-description: | + A set of machines, called nodes, that run containerized applications managed by Kubernetes. +long-description: | + A cluster has several worker nodes and at least one master node. diff --git a/_data/glossary/code-contributor.yaml b/_data/glossary/code-contributor.yaml new file mode 100644 index 0000000000..acc9878863 --- /dev/null +++ b/_data/glossary/code-contributor.yaml @@ -0,0 +1,11 @@ +id: code-contributor +name: Code Contributor +aka: + - Community Developer +tags: +- community +- user-type +short-description: | + A person who develops and contributes code to the Kubernetes open source codebase. +long-description: | + They are also an active [community member](#term-community-member) who participates in one or more [Special Interest Groups (SIGs)](#term-sig). diff --git a/_data/glossary/container.yaml b/_data/glossary/container.yaml new file mode 100644 index 0000000000..4cc786f7b3 --- /dev/null +++ b/_data/glossary/container.yaml @@ -0,0 +1,9 @@ +id: container +name: Container +tags: +- fundamental +- workload +short-description: | + A lightweight and portable executable image that contains software and all of its dependencies. +long-description: | + Containers decouple applications from underlying host infrastructure to make deployment easier in different cloud or OS environments, and for easier scaling. diff --git a/_data/glossary/contributor.yaml b/_data/glossary/contributor.yaml new file mode 100644 index 0000000000..333244466d --- /dev/null +++ b/_data/glossary/contributor.yaml @@ -0,0 +1,8 @@ +id: contributor +name: Contributor +tags: +- community +short-description: | + Someone who donates code, documentation, or their time to help the Kubernetes project or community. +long-description: | + Contributions include pull requests (PRs), issues, feedback, [special interest group (SIG)](#term-sig) participation, or organizing community events. diff --git a/_data/glossary/cronjob.yaml b/_data/glossary/cronjob.yaml new file mode 100644 index 0000000000..c220a38f75 --- /dev/null +++ b/_data/glossary/cronjob.yaml @@ -0,0 +1,9 @@ +id: cronjob +name: CronJob +tags: +- core-object +- workload +short-description: | + Manages a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) that runs on a periodic schedule. +long-description: | + Similar to a line in a *crontab* file, a [CronJob](/docs/concepts/workloads/controllers/cron-jobs/#writing-a-cron-job-spec) object specifies a schedule using the [Cron](https://en.wikipedia.org/wiki/Cron) format. diff --git a/_data/glossary/deployment.yaml b/_data/glossary/deployment.yaml new file mode 100644 index 0000000000..773f2c1518 --- /dev/null +++ b/_data/glossary/deployment.yaml @@ -0,0 +1,10 @@ +id: deployment +name: Deployment +tags: +- fundamental +- core-object +- workload +short-description: | + An API object that manages a replicated application. +long-description: | + Each replica is represented by a [Pod](#term-pod), and the Pods are distributed among the nodes of a cluster. diff --git a/_data/glossary/developer.yaml b/_data/glossary/developer.yaml new file mode 100644 index 0000000000..eb1a68526c --- /dev/null +++ b/_data/glossary/developer.yaml @@ -0,0 +1,15 @@ +id: developer +name: Developer (disambiguation) +aka: + - Kubernetes Developer +tags: +- community +- user-type +short-description: | + May refer to: [*Application Developer*](#term-application-developer), [*Code Contributor*](#term-code-contributor), or [*Platform Developer*](#term-platform-developer). +long-description: | + This overloaded term may have different meanings depending on the context. It could mean: + + * [**Application Developer**](#term-application-developer): A person who writes an application that runs in a Kubernetes cluster. + * [**Code Contributor**](#term-code-contributor): A person who develops and contributes code to the Kubernetes open source codebase. + * [**Platform Developer**](#term-platform-developer): A person who customizes the Kubernetes platform to fit the needs of their project—for example, by extending the API. diff --git a/_data/glossary/downstream.yaml b/_data/glossary/downstream.yaml new file mode 100644 index 0000000000..2abdd79fbc --- /dev/null +++ b/_data/glossary/downstream.yaml @@ -0,0 +1,11 @@ +id: downstream +name: Downstream (disambiguation) +related: +- upstream +tags: +- community +short-description: | + May refer to: code in the Kubernetes ecosystem that depends upon the core Kubernetes codebase or a forked repo. +long-description: | + * In the **Kubernetes Community**: Conversations often use *downstream* to mean the ecosystem, code, or third-party tools that rely on the core Kubernetes codebase. For example, a new feature in Kubernetes may be adopted by applications *downstream* to improve their functionality. + * In **GitHub** or **git**: The convention is to refer to a forked repo as *downstream*, whereas the source repo is considered *upstream*. diff --git a/_data/glossary/helm-chart.yaml b/_data/glossary/helm-chart.yaml new file mode 100644 index 0000000000..9688a6f716 --- /dev/null +++ b/_data/glossary/helm-chart.yaml @@ -0,0 +1,9 @@ +id: helm-chart +name: Helm Chart +tags: +- tool +short-description: | + A package of pre-configured Kubernetes resources that can be managed with the Helm tool. +long-description: | + Charts provide a reproducible way of creating and sharing Kubernetes applications. + A single chart can be used to deploy something simple, like a memcached Pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. diff --git a/_data/glossary/ingress.yaml b/_data/glossary/ingress.yaml new file mode 100644 index 0000000000..06864f8bcb --- /dev/null +++ b/_data/glossary/ingress.yaml @@ -0,0 +1,10 @@ +id: ingress +name: Ingress +tags: +- networking +- architecture +- extension +short-description: | + An API object that manages external access to the services in a cluster, typically HTTP. +long-description: | + Ingress can provide load balancing, SSL termination and name-based virtual hosting. diff --git a/_data/glossary/istio.yaml b/_data/glossary/istio.yaml new file mode 100644 index 0000000000..81056cfac4 --- /dev/null +++ b/_data/glossary/istio.yaml @@ -0,0 +1,12 @@ +id: istio +name: Istio +tags: +- networking +- architecture +- extension +short-description: | + An open platform (not Kubernetes-specific) that provides a uniform way to integrate microservices, manage traffic flow, enforce policies, and aggregate telemetry data. +long-description: > + Adding Istio does not require changing application code. + It is a layer of infrastructure between a service and the network, which when combined with service deployments, is commonly referred to as a service mesh. + Istio's control plane abstracts away the underlying cluster management platform, which may be Kubernetes, Mesosphere, etc. diff --git a/_data/glossary/kops.yaml b/_data/glossary/kops.yaml new file mode 100644 index 0000000000..b431e40616 --- /dev/null +++ b/_data/glossary/kops.yaml @@ -0,0 +1,18 @@ +id: kops +name: Kops +tags: +- tool +- operation +short-description: | + A CLI tool that helps you create, destroy, upgrade and maintain production-grade, highly available, Kubernetes clusters. *NOTE: Officially supports AWS only, with GCE and VMware vSphere in alpha*. +long-description: | + `kops` provisions your cluster with: + + * Fully automated installation + * DNS-based cluster identification + * Self-healing: everything runs in Auto-Scaling Groups + * Limited OS support (Debian preferred, Ubuntu 16.04 supported, early support for CentOS & RHEL) + * High availability (HA) support + * The ability to directly provision, or generate terraform manifests + + You can also build your own cluster using [`kubeadm`](#term-kubeadm) as a building block. `kops` builds on the kubeadm work. diff --git a/_data/glossary/kubeadm.yaml b/_data/glossary/kubeadm.yaml new file mode 100644 index 0000000000..ce2a6524d5 --- /dev/null +++ b/_data/glossary/kubeadm.yaml @@ -0,0 +1,9 @@ +id: kubeadm +name: Kubeadm +tags: +- tool +- operation +short-description: | + A tool for quickly installing Kubernetes and setting up a secure cluster. +long-description: | + You can use kubeadm to install both the control plane and the worker node components. diff --git a/_data/glossary/kubectl.yaml b/_data/glossary/kubectl.yaml new file mode 100644 index 0000000000..05711e8013 --- /dev/null +++ b/_data/glossary/kubectl.yaml @@ -0,0 +1,9 @@ +id: kubectl +name: Kubectl +tags: +- tool +- fundamental +short-description: | + A command line tool for communicating with a [Kubernetes API](#term-kubernetes-api) server. +long-description: | + You can use kubectl to create, inspect, update, and delete Kubernetes objects. diff --git a/_data/glossary/kubernetes-api.yaml b/_data/glossary/kubernetes-api.yaml new file mode 100644 index 0000000000..74169970bf --- /dev/null +++ b/_data/glossary/kubernetes-api.yaml @@ -0,0 +1,12 @@ +id: kubernetes-api +name: Kubernetes API +tags: +- fundamental +- architecture +short-description: | + The application that serves Kubernetes functionality through a RESTful interface and stores the state of the cluster. +long-description: > + Kubernetes resources and "records of intent" are all stored as API objects, and modified via RESTful calls to the API. + The API allows configuration to be managed in a declarative way. + Users can interact with the Kubernetes API directly, or via tools like `kubectl`. + The core Kubernetes API is flexible and can also be extended to support custom resources. diff --git a/_data/glossary/maintainer.yaml b/_data/glossary/maintainer.yaml new file mode 100644 index 0000000000..fabfb6551c --- /dev/null +++ b/_data/glossary/maintainer.yaml @@ -0,0 +1,8 @@ +id: maintainer +name: Maintainer +tags: +- community +short-description: | + A highly experienced [contributor](#term-contributor), active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository. +long-description: | + Maintainers work holistically across the project to maintain its health and success and have made substantial contributions, both through code development and broader organizational efforts. diff --git a/_data/glossary/member.yaml b/_data/glossary/member.yaml new file mode 100644 index 0000000000..3e4866625f --- /dev/null +++ b/_data/glossary/member.yaml @@ -0,0 +1,10 @@ +id: member +name: Member +tags: +- community +short-description: | + A continuously active [contributor](#term-contributor) in the K8s community. +long-description: > + Members can have issues and PRs assigned to them and participate in [special interest groups (SIGs)](#term-sig) through GitHub teams. + Pre-submit tests are automatically run for members' PRs. + A member is expected to remain an active contributor to the community. diff --git a/_data/glossary/minikube.yaml b/_data/glossary/minikube.yaml new file mode 100644 index 0000000000..eccbabadd9 --- /dev/null +++ b/_data/glossary/minikube.yaml @@ -0,0 +1,9 @@ +id: minikube +name: Minikube +tags: +- fundamental +- tool +short-description: | + A tool for running Kubernetes locally. +long-description: | + Minikube runs a single-node cluster inside a VM on your computer. diff --git a/_data/glossary/platform-developer.yaml b/_data/glossary/platform-developer.yaml new file mode 100644 index 0000000000..ef4352c98e --- /dev/null +++ b/_data/glossary/platform-developer.yaml @@ -0,0 +1,10 @@ +id: platform-developer +name: Platform Developer +aka: + - Kubernetes Developer +tags: + - user-type +short-description: | + A person who customizes the Kubernetes platform to fit the needs of their project. +long-description: > + A platform developer may, for example, use [Custom Resources](/docs/concepts/api-extension/custom-resources/) or [Extend the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) to add functionality to their instance of Kubernetes, specifically for their application. diff --git a/_data/glossary/pod.yaml b/_data/glossary/pod.yaml new file mode 100644 index 0000000000..2a22384697 --- /dev/null +++ b/_data/glossary/pod.yaml @@ -0,0 +1,16 @@ +id: pod +name: Pod +related: +- container +- sidecar +- deployment +- statefulset +tags: +- core-object +- fundamental +short-description: | + The smallest and simplest Kubernetes object. A Pod represents a set of running [containers](#term-container) on your cluster. +long-description: > + A Pod is typically set up to run a single primary container. + It can also run optional sidecar containers that add supplementary features like logging. + Pods are commonly managed by a [Deployment](#term-deployment). diff --git a/_data/glossary/rbac.yaml b/_data/glossary/rbac.yaml new file mode 100644 index 0000000000..af158dc54e --- /dev/null +++ b/_data/glossary/rbac.yaml @@ -0,0 +1,9 @@ +id: rbac +name: RBAC (Role-Based Access Control) +tags: +- security +- fundamental +short-description: | + Manages authorization decisions, allowing admins to dynamically configure access policies through the [Kubernetes API](#term-kubernetes-api). +long-description: | + RBAC utilizes *roles*, which contain permission rules, and *role bindings*, which grant the permissions defined in a role to a set of users. diff --git a/_data/glossary/reviewer.yaml b/_data/glossary/reviewer.yaml new file mode 100644 index 0000000000..50b189d117 --- /dev/null +++ b/_data/glossary/reviewer.yaml @@ -0,0 +1,8 @@ +id: reviewer +name: Reviewer +tags: +- community +short-description: | + A person who reviews code for quality and correctness on some part of the project. +long-description: | + Reviewers are knowledgeable about both the codebase and software engineering principles. Reviewer status is scoped to a part of the codebase. diff --git a/_data/glossary/service.yaml b/_data/glossary/service.yaml new file mode 100644 index 0000000000..82f3998f6b --- /dev/null +++ b/_data/glossary/service.yaml @@ -0,0 +1,9 @@ +id: service +name: Service +tags: +- fundamental +- core-object +short-description: | + An API object that describes how to access applications, such as a set of [Pods](#term-pod), and can describe ports and load-balancers. +long-description: | + The access point can be internal or external to the cluster. diff --git a/_data/glossary/sig.yaml b/_data/glossary/sig.yaml new file mode 100644 index 0000000000..bc365e677f --- /dev/null +++ b/_data/glossary/sig.yaml @@ -0,0 +1,11 @@ +id: sig +name: SIG (special interest group) +tags: +- community +short-description: | + [Members](#term-member) who collectively manage an ongoing piece or aspect of the larger Kubernetes open source project. +long-description: > + Members within a SIG have a shared interest in advancing a specific area, such as architecture, API machinery, or documentation. + SIGs must follow the [SIG Governance](https://github.com/kubernetes/community/blob/master/sig-governance.md) guidelines but can have their own contribution policy and channels of communication. + + For more information, see the [kubernetes/community](https://github.com/kubernetes/community) repo and the current list of [SIGs and Working Groups](https://github.com/kubernetes/community/blob/master/sig-list.md). diff --git a/_data/glossary/statefulset.yml b/_data/glossary/statefulset.yml index 3f05200012..c6bc43cb71 100644 --- a/_data/glossary/statefulset.yml +++ b/_data/glossary/statefulset.yml @@ -1,18 +1,18 @@ id: statefulset name: StatefulSet -formerly: +aka: - PetSet related: -- Deployment -- Pod +- deployment +- pod tags: -- Storage -- Workload -- API Object +- core-object +- workload +- storage short-description: | - Manage the deployment and scaling of a set of Pods, *and provide guarantees about ordering*. They do so by maintaining a *unique*, sticky identity for each of their Pods. + Manages the deployment and scaling of a set of [Pods](#term-pod), *and provides guarantees about the ordering and uniqueness* of these Pods. long-description: | - Like Deployments, StatefulSets manage Pods that are based on an identical container spec. However, although their specs are the same, the Pods in a StatefulSet are not interchangeable. Each Pod has a persistent identifier that it maintains across any rescheduling. + Like a [Deployment](#term-deployment), a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable: each has a persistent identifier that it maintains across any rescheduling. - StatefulSets also operate according to the Controller pattern. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to the get there from the current state. + A StatefulSet operates under the same pattern as any other Controller. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to get there from the current state. diff --git a/_data/glossary/upstream.yaml b/_data/glossary/upstream.yaml new file mode 100644 index 0000000000..70b3e4cef4 --- /dev/null +++ b/_data/glossary/upstream.yaml @@ -0,0 +1,11 @@ +id: upstream +name: Upstream (disambiguation) +related: +- downstream +tags: +- community +short-description: | + May refer to: core Kubernetes or the source repo from which a repo was forked. +long-description: | + * In the **Kubernetes Community**: Conversations often use *upstream* to mean the core Kubernetes codebase, which the general ecosystem, other code, or third-party tools relies upon. For example, [community members](#term-member) may suggest that a feature is moved upstream so that it is in the core codebase instead of in a plugin or third-party tool. + * In **GitHub** or **git**: The convention is to refer to a source repo as *upstream*, whereas the forked repo is considered *downstream*. diff --git a/_data/glossary/wg.yaml b/_data/glossary/wg.yaml new file mode 100644 index 0000000000..5d7e5ee28e --- /dev/null +++ b/_data/glossary/wg.yaml @@ -0,0 +1,10 @@ +id: wg +name: WG (working group) +tags: +- community +short-description: | + Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, [SIG](#term-sig), or cross-SIG effort. +long-description: | + Working groups are a way of organizing people to accomplish a discrete task, and are relatively easy to create and deprecate when inactive. + + For more information, see the [kubernetes/community](https://github.com/kubernetes/community) repo and the current list of [SIGs and working groups](https://github.com/kubernetes/community/blob/master/sig-list.md). diff --git a/_data/reference.yml b/_data/reference.yml index 28e2d81f03..48abc0b2d6 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -2,6 +2,7 @@ bigheader: "Reference Documentation" abstract: "Design docs, concept definitions, and references for APIs and CLIs." toc: - docs/reference/index.md +- docs/reference/glossary.md - title: Using the API section: @@ -108,5 +109,3 @@ toc: - title: Kubernetes Issue Tracker on GitHub path: https://github.com/kubernetes/kubernetes/issues/ - docs/reference/security.md - - diff --git a/_includes/templates/glossary/README.md b/_includes/templates/glossary/README.md index 9d3d49d48e..453c23fdc7 100644 --- a/_includes/templates/glossary/README.md +++ b/_includes/templates/glossary/README.md @@ -2,17 +2,19 @@ To write a glossary snippet, start with a copy of the template, [`/_data/glossary/_example.yml`](/_data/glossary/_example.yml). Make sure to provide (or omit) values for the following fields: -* (Required) `id`. +* (Required) `id` * This field must match the name of the glossary file itself (without the `*.yml` extension). It is *not* intended to be displayed to users, and is only used programmatically. -* (Required) `name`. +* (Required) `name` * The name of the term. -* (Required) `tags`. +* (Required) `tags` * Must be one of the tags listed in kubernetes.github.io/_data/canonical-terms-tags.yml. -* (Required) `short description`. +* (Required) `short description` * Make sure to replace the instructional text in the template with your content. -* (Optional) `formerly` and `related`. - * If you do not provide these values, remove the fields. -* (Optional) `long description`. +* (Optional) `aka` + * These synonyms do not need to be glossary terms themselves (if they are deprecated), and can include spaces. +* (Optional) `related` + * These should be the `id`s (not the `names`) of related glossary terms. +* (Optional) `long description` * If you do not provide a long description, remove the field -- that is, the complete key-value pair. The `_example.yml` template also contains basic information about how to write your snippet. For additional guidance, continue reading this readme. diff --git a/_layouts/docwithnav.html b/_layouts/docwithnav.html index b57af76f74..f10f958bec 100755 --- a/_layouts/docwithnav.html +++ b/_layouts/docwithnav.html @@ -67,7 +67,9 @@ Create an Issue - Edit this Page + {% unless page.noedit %} + Edit this Page + {% endunless %} {% endif %} diff --git a/css/glossary.css b/css/glossary.css new file mode 100644 index 0000000000..67d536ccf9 --- /dev/null +++ b/css/glossary.css @@ -0,0 +1,64 @@ +.preview-text p { + display: inline; +} + +.no-underline { + text-decoration: none !important; +} + +.hide { + display: none !important; +} + +.permalink { + background-image: url(../images/link.png); + background-repeat: no-repeat; + display: inline-block; + color: transparent; + width: 20px; + margin-left: 10px; +} + +.term-anchor { + display: block; + position: relative; + top: -90px; + visibility: hidden; +} + +.tag-option { + padding: 5px; + margin: 10px; + float:left; +} + +.canonical-tag { + color: white; + background-color: #b7c8e8; +} + +.canonical-tag a { + color: inherit; + text-decoration: none !important; +} + +.active-tag { + background-color: #3371e3; +} + +.invisible { + visibility: hidden; +} + +#tag-container { + float: left; + border-top: 1px solid #8c8c8c; + border-bottom: 1px solid #8c8c8c; + padding: 7px 0px; + margin: 25px 0px; +} + +.tag-description { + text-align: center; + margin: 5px 0px; +} diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md new file mode 100644 index 0000000000..ceb1dc4dd3 --- /dev/null +++ b/docs/reference/glossary.md @@ -0,0 +1,66 @@ +--- +approvers: +- chenopis +- abiogenesis-now +title: Standardized Glossary +noedit: true +default_active_tag: fundamental +--- + + + +

This glossary is intended to be a comprehensive, standardized list of Kubernetes terminology. It includes technical terms that are specific to K8s, as well as more general terms that provide useful context.

+ +
+

Filter terms according to their tags:

+ +{% for tag in site.data.canonical-tags %} +{% assign tag_info = tag[1] %} +
+{{ tag_info.description }} +
+{% endfor %} + +{% assign sorted_tags = site.data.canonical-tags | where_exp: "tag", "true" | sort: 'name' %} +{% for tag_info in sorted_tags %} + +{% assign tag_state_class = "" %} + +{% assign fullTagName = tag_info.id | prepend: "tag-" %} + +{{ tag_info.name }} + +{% endfor %} +Select all +Deselect all +
+ +

Click on the [+] indicators below to get a longer explanation for any particular term.

+ +{% assign glossary_terms = site.data.glossary | where_exp: "term", "term.id != '_example'" | sort: 'name' %} + +
    +{% for term in glossary_terms %} + +{% assign tag_classes = term.tags | join: " tag-" | prepend: "tag-" %} + +{% assign term_visibility_class = "hide" %} +{% assign show_count = 0 %} +{% assign term_identifier = term.id | prepend: 'term-' %} + +
  • +
    +
    +
    {{ term.name }}
    +{% if term.aka %} +Also known as: {{ term.aka | join: ", " }} +
    +{% endif %} +{{ term.short-description | markdownify }} [+] +
    +{{ term.long-description | markdownify }} +
    +
    +
    • +{% endfor %} +
diff --git a/images/link.png b/images/link.png new file mode 100644 index 0000000000000000000000000000000000000000..048e2dd88dab939f6f8383ddc213621a1281e07c GIT binary patch literal 1666 zcmY*Z3p~?X96vKN7ON51Q z(QBz`J=HvJod9^l z0)S8gfEl;!%1WYU!+=W-=L0asMB5Qyf0;P|i15TvhJZl}AjG6_@KLcT(Q){64p+kl zfS69ugq%1*6qL?MO6C*Ny=^BM1Wl}kVOwaDB3SEf%b?Mrr765P$PMp`ce3@tKoCUa z#l{nYeV6@6*Q~s469fV-0fvP_Azru$pTc9q&R$+#u#*ey;^L@bIP%vg3!>5;llim1 zi~OVG8^@2~C2|FcDanvlH!3QDOeVmDt%>Q9Oe2B2t{6B~JUg;#NDb)u4S5GSIA)6>c0V z;~y+5UU7FKss04Xt~M(B9jP~B4(Sv{9iF|zG~eT?=sx@Uv_|g#E|jNAq!c zjmxULfUJ|W#LcAN^!)gKbeW_A3SXldxuB`q5g{|L1Zp2i8sew&X8f(IXu`~1PSCPA1 zAC2AQS?ISIk4(uZaOV8D+?pLAuQ#)&bTVaG8T>%YsqsguMB?>uL?+oW-TmRC0T4r{H+#FULqt zWBv;ir+wyRsmxBo7xoGgH;fyU7fV=)wY-_3mZ~81`~0eks)UZ7Vb)^5?wgVr z(Z2fv(gt4YwBsGujpj$hde}rf+Xy;OZ(d$`o_NwEjq#Gu>MFU=*jOslZJsfoQ}Zl) z$*dQ>DELKgooT}Jo_11&*|`Z(C~~CtDn*|$vdV_-Xl-CBDM6;bot8EJJSU1#vVbNs zl(TfZ%<>}9Y~0x_p&Vg#Rk)pM|IIG~%Nd?^5z+822ko-Pa=PB(uX5I~@}a~=lHZ5< zh;0U|_YMoc^e5g65i@Qm0j+>*HCTNO(`8?-n){&PrI{4xUV{3HW9rP?}?!jUCYAA0w51SeS`M@Q@)G#sJJEIK3IJi0X_jG@Sz6s#gtQ@lrb=kmio$tAIb3VKK8G+;2wHsiqA7B8N8#ZccV4<;e1ls; z8KoD`7=PLlq9Pcgub9|y5}XuWGj1Un70QZ=UBgQT{qS> zdV6L{+ZA(2zSxoUW#AAgGHHvcU#^~X5v|s+_H>lGvY>^wZDGrisTAH}BEmt4?6h%U znv3=xsJG6jmk*$uB)J*-Jsl)MH&&6R^PwioIMNioZl=uSr zFTlnzk*9Jy$Mqi> 0) { + $(this).removeClass("hide"); + } + }); + activeTags[tagName] = true; + if (activeTags[deselectAllKey]) { + delete activeTags[deselectAllKey]; + } + }; + + // Shows/hides glossary terms when their relevant tags are clicked + $(".canonical-tag").each(function(){ + var placeholder = $("#placeholder"); + var targetTag = $(this).data("target"); + $(this).mouseenter(function(){ + var tagDescription = $("#" + targetTag + "-description").html(); + placeholder.html(tagDescription); + placeholder.removeClass('invisible'); + }).mouseleave(function(){ + placeholder.addClass('invisible'); + }); + + $(this).click(function(){ + var shouldHide = $(this).hasClass("active-tag"); + if (shouldHide) { + deactivateTagTerms($(this)); + } else { + activateTagTerms($(this)); + } + urlParamLib.updateParams(activeTags); + }); + }); + + // Adds functionality to "select all tags" link + $("#select-all-tags").click(function(){ + $(".canonical-tag").each(function(){ + var shouldActivate = !$(this).hasClass("active-tag"); + if (shouldActivate) { + activateTagTerms($(this)); + } + }); + queryParams = {} + queryParams[selectAllKey] = true; + urlParamLib.updateParams(queryParams); + }); + + // Adds functionality to "deselect all tags" link + $("#deselect-all-tags").click(function(){ + $(".canonical-tag").each(function(){ + var shouldHide = $(this).hasClass("active-tag"); + if (shouldHide) { + deactivateTagTerms($(this)); + } + }); + queryParams = {} + queryParams[deselectAllKey] = true; + urlParamLib.updateParams(queryParams); + }); + + // Expands/hides glossary term definitions when [+] button is clicked + $(".click-controller").each(function(){ + $(this).click(function() { + var targetId = $(this).data("target"); + var shouldExpand = $(this).html() == expandText; + + if (shouldExpand) { + $("#" + targetId).removeClass('hide'); + $(this).html(closeText); + } else { + $("#" + targetId).addClass('hide'); + $(this).html(expandText); + } + }); + }); + + // Shows permalink when term name is hovered over + $(".term-name").each(function() { + var permalink = $($(this).parent().find(".permalink")[0]); + $(this).mouseenter(function(){ + permalink.removeClass("hide"); + }).mouseleave(function(){ + permalink.addClass("hide"); + });; + }); + }; + + function initActiveTags() { + if (activeTags[selectAllKey]) { + $("#select-all-tags").click(); + } else if (activeTags[deselectAllKey]) { + $("#deselect-all-tags").click(); + } else { + for (var tagId in activeTags) { + $("#tag-" + tagId).find("a")[0].click(); + } + } + } + + initClickFunctions(); + activeTags = urlParamLib.initParams(); + initActiveTags(); + +}); diff --git a/test/glossary_test.go b/test/glossary_test.go index df51025278..dc8984a295 100644 --- a/test/glossary_test.go +++ b/test/glossary_test.go @@ -29,41 +29,53 @@ import ( type GlossaryTerm struct { Id string `yaml: "id"` Name string `yaml: "name"` - Formerly []string `yaml: "formerly"` + Aka []string `yaml: "aka"` Related []string `yaml: "related"` Tags []string `yaml: "tags"` } +// Not unmarshaling other fields (for simplicity) +type CanonicalTag struct { + Id string `yaml: "id"` +} + // Checks that all glossary files (../_data/glossary/*) contain valid tags // that are present in the canonical set. func TestCanonicalTags(t *testing.T) { - canonicalTagsFile := "../_data/canonical-tags.yml" - data, err := ioutil.ReadFile(canonicalTagsFile) + canonicalTagsDir := "../_data/canonical-tags" + files, err := ioutil.ReadDir(canonicalTagsDir) if err != nil { - t.Errorf("Unable to read file %s: %v", canonicalTagsFile, err) - return - } - var tagList []string - err = yaml.Unmarshal(data, &tagList) - if err != nil { - t.Errorf("Unable to unmarshal file %s: %v", tagList, err) + t.Errorf("Unable to read directory %s: %v", canonicalTagsDir, err) return } canonicalTagsSet := make(map[string]bool) - for _, tag := range tagList { - canonicalTagsSet[tag] = true + var tag CanonicalTag + for _, f := range files { + filePath := path.Join(canonicalTagsDir, f.Name()) + data, err := ioutil.ReadFile(filePath) + if err != nil { + t.Errorf("Unable to read file %s: %v", filePath, err) + continue + } + err = yaml.Unmarshal(data, &tag) + if err != nil { + t.Errorf("Unable to unmarshal file %s: %v", filePath, err) + continue + } + + canonicalTagsSet[tag.Id] = true } glossaryDir := "../_data/glossary" - files, err := ioutil.ReadDir(glossaryDir) + files, err = ioutil.ReadDir(glossaryDir) if err != nil { t.Errorf("Unable to read directory %s: %v", glossaryDir, err) return } - var term GlossaryTerm for _, f := range files { + var term GlossaryTerm // skip validation of example files if (strings.HasPrefix(f.Name(), "_")) { continue @@ -81,9 +93,12 @@ func TestCanonicalTags(t *testing.T) { continue } + if (len(term.Tags) == 0) { + t.Errorf("Glossary term \"%s\" requires at least one tag. See %s for the list of valid tags.", term.Name, canonicalTagsDir) + } for _, tag := range term.Tags { if _, present := canonicalTagsSet[tag]; !present { - t.Errorf("Glossary term \"%s\" has invalid tag \"%s\". See %s for the list of valid tags.", term.Name, tag, canonicalTagsFile) + t.Errorf("Glossary term \"%s\" has invalid tag \"%s\". See %s for the list of valid tags.", term.Name, tag, canonicalTagsDir) continue } }