[docs][glossary] Add page that lists all standardized k8s terms (#5657)
* Add comprehensive glossary page Additional Authors: * Andrew Chen <chenopis@users.noreply.github.com> * Steve Perry <steveperry-53@users.noreply.github.com> * 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.pull/5857/head^2
Jessica Yao
Zach Corleissen
parent
8da72ca938
commit
b22947afc3
|
|
@ -1,12 +0,0 @@
|
|||
- Fundamental
|
||||
- API Object
|
||||
- Metadata
|
||||
- Configuration
|
||||
- Security
|
||||
- Networking
|
||||
- Storage
|
||||
- Operation
|
||||
- Workload
|
||||
- Component
|
||||
- API
|
||||
- Extension
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: architecture
|
||||
name: Architecture
|
||||
description: The inner components of Kubernetes.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: community
|
||||
name: Community
|
||||
description: Related to Kubernetes open-source development.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: core-object
|
||||
name: Core Object
|
||||
description: A resource type that Kubernetes supports by default.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: extension
|
||||
name: Extension
|
||||
description: Supported customizations of Kubernetes.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: fundamental
|
||||
name: Fundamental
|
||||
description: Relevant for a first-time user of Kubernetes.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: networking
|
||||
name: Networking
|
||||
description: How Kubernetes components talk to each other (and to programs outside the cluster).
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: operation
|
||||
name: Operation
|
||||
description: Starting and maintaining Kubernetes.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: security
|
||||
name: Security
|
||||
description: Keeping Kubernetes applications safe and secure.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: storage
|
||||
name: Storage
|
||||
description: How Kubernetes applications handle persistent data.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: tool
|
||||
name: Tool
|
||||
description: Software that makes Kubernetes easier or better to use.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: user-type
|
||||
name: User Type
|
||||
description: Represents a common type of Kubernetes user.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
id: workload
|
||||
name: Workload
|
||||
description: Applications running on Kubernetes.
|
||||
|
|
@ -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: |
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.<br>
|
||||
|
||||
**NOTE:** Cluster operators are different from the [Operator pattern](https://coreos.com/operators) that extends the Kubernetes API.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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*.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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*.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -67,7 +67,9 @@
|
|||
</script>
|
||||
<a href="" onclick="window.open('https://github.com/kubernetes/kubernetes.github.io/issues/new?title=Issue%20with%20' +
|
||||
'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
|
||||
<a href="/editdocs#{{ page.path }}" class="button issue">Edit this Page</a>
|
||||
{% unless page.noedit %}
|
||||
<a href="/editdocs#{{ page.path }}" class="button issue">Edit this Page</a>
|
||||
{% endunless %}
|
||||
{% endif %}
|
||||
</div>
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
approvers:
|
||||
- chenopis
|
||||
- abiogenesis-now
|
||||
title: Standardized Glossary
|
||||
noedit: true
|
||||
default_active_tag: fundamental
|
||||
---
|
||||
<link href="/css/glossary.css" rel="stylesheet">
|
||||
<script src="/js/glossary.js"></script>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<div id="tag-container">
|
||||
<p>Filter terms according to their tags:</p>
|
||||
<div class="tag-description invisible" id="placeholder">.</div>
|
||||
{% for tag in site.data.canonical-tags %}
|
||||
{% assign tag_info = tag[1] %}
|
||||
<div class="tag-description hide" id="{{ tag_info.id | prepend: "tag-" | append: "-description" }}">
|
||||
<i>{{ tag_info.description }}</i>
|
||||
</div>
|
||||
{% 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-" %}
|
||||
<span id="{{ fullTagName }}" class="tag-option canonical-tag {{ tag_state_class }}" data-target="{{ fullTagName }}">
|
||||
<a href="javascript:void(0)">{{ tag_info.name }}</a>
|
||||
</span>
|
||||
{% endfor %}
|
||||
<span class="tag-option"><a id="select-all-tags" href="javascript:void(0)">Select all</a></span>
|
||||
<span class="tag-option"><a id="deselect-all-tags" href="javascript:void(0)">Deselect all</a></span>
|
||||
</div>
|
||||
|
||||
<p>Click on the <a href="javascript:void(0)" class="no-underline">[+]</a> indicators below to get a longer explanation for any particular term.</p>
|
||||
|
||||
{% assign glossary_terms = site.data.glossary | where_exp: "term", "term.id != '_example'" | sort: 'name' %}
|
||||
|
||||
<ul>
|
||||
{% 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-' %}
|
||||
|
||||
<li class="{{ tag_classes }} {{ term_visibility_class }}" data-show-count="{{ show_count }}">
|
||||
<div id="{{ term_identifier }}" class="term-anchor"></div>
|
||||
<div>
|
||||
<div class="term-name"><b>{{ term.name }}</b><a href="{{ term_identifier | prepend: '#' }}" class="permalink hide">LINK</a></div>
|
||||
{% if term.aka %}
|
||||
Also known as: <i>{{ term.aka | join: ", " }}</i>
|
||||
<br>
|
||||
{% endif %}
|
||||
<span class="preview-text">{{ term.short-description | markdownify }} <a href="javascript:void(0)" class="click-controller no-underline" data-target="{{ term.id }}">[+]</a></span>
|
||||
<div id="{{ term.id }}" class="hide">
|
||||
{{ term.long-description | markdownify }}
|
||||
</div>
|
||||
</div>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.6 KiB |
|
|
@ -0,0 +1,181 @@
|
|||
// TODO (long-term): Would be easier to manage all this state with React
|
||||
|
||||
$( document ).ready(function() {
|
||||
var expandText = "[+]";
|
||||
var closeText = "[-]";
|
||||
var selectAllKey = "all";
|
||||
var deselectAllKey = "none";
|
||||
|
||||
var defaultActiveTag = "fundamental";
|
||||
var activeTags = {};
|
||||
|
||||
var paramSize = function(paramHash) {
|
||||
return Object.keys(paramHash).length;
|
||||
}
|
||||
|
||||
// "Lib" for acquiring parameters from the URL
|
||||
var urlParamLib = function() {
|
||||
function initParams() {
|
||||
var sPageURL = decodeURIComponent(window.location.search.substring(1)),
|
||||
sURLVariables = sPageURL.split('&'),
|
||||
sParameterName,
|
||||
i;
|
||||
|
||||
var paramHash = {};
|
||||
for (i = 0; i < sURLVariables.length; i++) {
|
||||
sParameterName = sURLVariables[i].split('=');
|
||||
if (sParameterName[0] != "")
|
||||
paramHash[sParameterName[0]] = sParameterName[1];
|
||||
}
|
||||
|
||||
if (paramSize(paramHash) == 0) {
|
||||
paramHash[defaultActiveTag] = true;
|
||||
}
|
||||
|
||||
return paramHash;
|
||||
}
|
||||
|
||||
function updateParams(paramHash) {
|
||||
var urlWithoutQuery = window.location.href.split('?')[0];
|
||||
var urlHash = window.location.hash;
|
||||
window.history.pushState(null,null, urlWithoutQuery + "?" + $.param(paramHash) + window.location.hash);
|
||||
}
|
||||
|
||||
return {
|
||||
initParams: initParams,
|
||||
updateParams: updateParams,
|
||||
};
|
||||
}();
|
||||
|
||||
var initClickFunctions = function() {
|
||||
|
||||
var deactivateTagTerms = function(elt) {
|
||||
var targetTag = elt.data("target");
|
||||
var targetClass = "." + targetTag;
|
||||
var tagName = targetTag.split('tag-')[1];
|
||||
|
||||
elt.removeClass("active-tag");
|
||||
$(targetClass).each(function(){
|
||||
var showCount = $(this).data("show-count");
|
||||
var newShowCount = showCount - 1;
|
||||
$(this).data("show-count", newShowCount);
|
||||
if (newShowCount < 1) {
|
||||
$(this).addClass("hide");
|
||||
}
|
||||
});
|
||||
delete activeTags[tagName];
|
||||
};
|
||||
|
||||
var activateTagTerms = function(elt) {
|
||||
var targetTag = elt.data("target");
|
||||
var targetClass = "." + targetTag;
|
||||
var tagName = targetTag.split('tag-')[1];
|
||||
|
||||
elt.addClass("active-tag");
|
||||
$(targetClass).each(function(){
|
||||
var showCount = $(this).data("show-count");
|
||||
var newShowCount = showCount + 1;
|
||||
$(this).data("show-count", newShowCount);
|
||||
if (newShowCount > 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();
|
||||
|
||||
});
|
||||
|
|
@ -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
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue