Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

chore: update terminology list content and add ref link. #18968

Merged
merged 1 commit into from
Feb 11, 2020
Merged

chore: update terminology list content and add ref link. #18968

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 8 additions & 16 deletions content/en/docs/concepts/services-networking/ingress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,24 +17,15 @@ weight: 40

For clarity, this guide defines the following terms:

Node
: A worker machine in Kubernetes, part of a cluster.

Cluster
: A set of Nodes that run containerized applications managed by Kubernetes. For this example, and in most common Kubernetes deployments, nodes in the cluster are not part of the public internet.

Edge router
: A router that enforces the firewall policy for your cluster. This could be a gateway managed by a cloud provider or a physical piece of hardware.

Cluster network
: A set of links, logical or physical, that facilitate communication within a cluster according to the Kubernetes [networking model](/docs/concepts/cluster-administration/networking/).

Service
: A Kubernetes {{< glossary_tooltip term_id="service" >}} that identifies a set of Pods using {{< glossary_tooltip text="label" term_id="label" >}} selectors. Unless mentioned otherwise, Services are assumed to have virtual IPs only routable within the cluster network.
* Node: A worker machine in Kubernetes, part of a cluster.
Copy link
Contributor

Choose a reason for hiding this comment

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

Lines 20 - 33 are set up as an inlined glossary.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I checked the documentation content guide, I didn't see any guide about inline glossary suggestion, instead, some pages like this, it list terms by markdown list, which is more clear to our users.

The first time I saw this page, I got an inconsistent feeling about this part, so I'd like to change this part in this PR.

Copy link
Contributor

Choose a reason for hiding this comment

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

Hello @Colstuwjx .
I agree that this page may be the only page with a Definition List. Would the rendered list be acceptable to you if styled? The styling for the Definition List could be improved (indent the <dd> element, add a top margin for the <dl> element, use a quieter font for the <dd> element, update font size). I made a few quick changes as a test:

image

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@kbhawkey Could you please share your suggested change in comment? So that I could also confirm about this change. BTW, if it looks hacky to do this change, I'd like to keep my PR suggested way, since we still don't have a official content style about this, adding a hacky way should be problematic.

Thanks!

Copy link
Contributor

Choose a reason for hiding this comment

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

Hello @Colstuwjx,
I create PR #19034 as an example of styling options for definition lists (definitely not hacky 😄 ).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@kbhawkey I have been checked this change locally, it LGTM!
Shall we take this change in this PR after we all agreed in #19034?

* Cluster: A set of Nodes that run containerized applications managed by Kubernetes. For this example, and in most common Kubernetes deployments, nodes in the cluster are not part of the public internet.
* Edge router: A router that enforces the firewall policy for your cluster. This could be a gateway managed by a cloud provider or a physical piece of hardware.
* Cluster network: A set of links, logical or physical, that facilitate communication within a cluster according to the Kubernetes [networking model](/docs/concepts/cluster-administration/networking/).
* Service: A Kubernetes {{< glossary_tooltip term_id="service" >}} that identifies a set of Pods using {{< glossary_tooltip text="label" term_id="label" >}} selectors. Unless mentioned otherwise, Services are assumed to have virtual IPs only routable within the cluster network.

## What is Ingress?

Ingress exposes HTTP and HTTPS routes from outside the cluster to
[Ingress](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#ingress-v1beta1-networking-k8s-io) exposes HTTP and HTTPS routes from outside the cluster to
Copy link
Contributor

Choose a reason for hiding this comment

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

Line 28, I wonder whether this link is needed here? Provide the link to the resource API in the What's next section.
Line 468, suggested edit: Learn about the Ingress resource OR Learn about the Ingress API

Copy link
Contributor Author

Choose a reason for hiding this comment

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

For line 28, I think it's nice to have, our users see What is Ingress section and could easily visit the detail api fields via this link.

For line 468, I'm ok to do this change.

Copy link
Contributor

Choose a reason for hiding this comment

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

Hello @Colstuwjx, A couple of thoughts:
Personally, I am not a big fan of starting a paragraph with linked text (and the link to the API is listed with the other reference links at the bottom of the page).
I think your updates to the formatting of the terminology section is OK (granted the current docs UI
does not provide custom styling for this type of component).
Since the docs are in the process of changing to a new theme/UI, this page section will hopefully
get an improved look when that change lands.
/lgtm

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Okay, I got the point, thanks for your suggestions!

{{< link text="services" url="/docs/concepts/services-networking/service/" >}} within the cluster.
Traffic routing is controlled by rules defined on the Ingress resource.

Expand Down Expand Up @@ -474,6 +465,7 @@ You can expose a Service in multiple ways that don't directly involve the Ingres
{{% /capture %}}

{{% capture whatsnext %}}
* Learn about [ingress controllers](/docs/concepts/services-networking/ingress-controllers/)
* Learn about the [Ingress API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#ingress-v1beta1-networking-k8s-io)
* Learn about [Ingress Controllers](/docs/concepts/services-networking/ingress-controllers/)
* [Set up Ingress on Minikube with the NGINX Controller](/docs/tasks/access-application-cluster/ingress-minikube)
{{% /capture %}}