Service topology alpha documentation #17459

johnbelamaric · 2019-11-06T19:12:26Z

Placeholder docs PR for kubernetes/enhancements#536

/sig network

k8sio-netlify-preview-bot · 2019-11-06T19:12:35Z

Deploy preview for kubernetes-io-vnext-staging processing.

Building with commit 461c486

https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/5dd8613bac0d5700091ad7ee

johnbelamaric · 2019-11-06T19:13:01Z

/hold

sftim · 2019-11-07T06:45:36Z

content/en/docs/concepts/services-networking/service-topology.md

+
+{{% capture whatsnext %}}
+
+* [Enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)


Suggested change

* [Enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)

* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology/)

imroc · 2019-11-07T08:42:47Z

Can you add me as collaborator to your repo? I can help to write the docs, push commit to your remote branch. Or maybe I can just request change to add suggested content.

imroc · 2019-11-07T12:45:03Z

Prerequisites

The following prerequisites are needed in order to enable topology aware service routing:

Kubernetes 1.17 or later
Kube-proxy running in mode IPVS or Iptables
Enable Endpoint Slices (enabled by default since v1.17)

imroc · 2019-11-07T12:45:49Z

Enable Service Topology

To enable service topology, enable the ServiceTopology feature gate for the kube-proxy:

--feature-gates="ServiceTopology=true"

johnbelamaric · 2019-11-07T21:37:44Z

You can submit PRs against my fork if you want. Or I can incorporate your suggestions.

imroc · 2019-11-08T01:55:19Z

You can submit PRs against my fork if you want. Or I can incorporate your suggestions.

I'm going to submit PRs against your fork.

daminisatya · 2019-11-20T09:33:47Z

@imroc @johnbelamaric Just a reminder about the last Docs deadline - 22nd Nov, by which this PR needs to be merged!

imroc · 2019-11-21T03:00:46Z

Sorry for the delay. I think I can just comment the suggestions to this PR, and @johnbelamaric write to the commits.

imroc · 2019-11-21T03:44:41Z

Motivation

Figure out a generic way to implement the "local service" route, say "topology aware routing of service", simply call it "service topology".

Locality is defined by user, it can be any topology-related thing. "Local" means the "same topology level", e.g. same node, same rack, same failure zone, same failure region, same cloud provider etc. Two nodes are considered "local" if they have the same value for a particular label, called the "topology key".

imroc · 2019-11-21T04:08:24Z

Topology Keys

If your cluster has Service Topology enabled, you can create Services with topology keys by setting a field: .spec.topologyKeys.

topologyKeys is a preference-order list of topology keys which implementations of services should use to preferentially sort endpoints when accessing this Service, it can not be used at the same time as externalTrafficPolicy=Local. Topology keys must be valid label keys and at most 16 keys may be specified. Endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value "*" may be used to mean "any topology". This catch-all value, if used, only makes sense as the last value in the list. If topologyKeys is not specified or empty, no topology constraints will be applied.

imroc · 2019-11-21T09:01:50Z

Can I fire another PR on this? I can respond quickly to the review, help to make the service topology documentation gets merged before Docs deadline.

johnbelamaric · 2019-11-21T20:45:56Z

If you want that's fine with me, I am at KubeCon. Otherwise I can get to this later tonight or tomorrow morning.

imroc · 2019-11-22T01:20:32Z

Just using this PR then. I am a little busy too, try to take the time to write the doc.

imroc · 2019-11-22T12:20:17Z

Introduction

Service Topology makes it possible for network traffic of service to be forwarded nearby, reducing network hops and improving network performance. It uses topology keys to decide the preferred topological domains to be used, e.g. node, rack, zone, region, etc.

imroc · 2019-11-22T12:39:36Z

Using Topology Keys

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: ClusterIP
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  topologyKeys: ["kubernetes.io/hostname", "topology.kubernetes.io/zone", "*"]

please help to describe this 😅

daminisatya · 2019-11-22T17:04:27Z

@johnbelamaric Update on this PR?

johnbelamaric · 2019-11-22T18:39:28Z

I am working on this now and will have an update within the hour. Thanks for your patience, it's been a hectic week!

johnbelamaric · 2019-11-22T20:40:02Z

/assign @robscott

robscott

Thanks for all the work on these docs! I just caught a few small things.

content/en/docs/concepts/services-networking/service-topology.md

johnbelamaric · 2019-11-22T22:29:58Z

Thanks @robscott for the review! @daminisatya I think we are good to go now, assuming Rob can LGTM with the latest.

robscott · 2019-11-22T22:50:15Z

Thanks!

/lgtm

imroc

Thanks for all the work on this. Almost is lgtm, only one small thing needs confirmation.

imroc · 2019-11-23T01:50:44Z

content/en/docs/concepts/services-networking/service-topology.md

+
+{{% capture whatsnext %}}
+
+* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)


nit: enabling --> Enabling

And currently the doc Enabling Service Topology is not exists, will it be added in later commit or another PR?

Added in this PR #17808 PTAL

johnbelamaric · 2019-11-23T02:43:26Z

Oops...do we need it, since it’s in this doc?

…

On Fri, Nov 22, 2019 at 5:50 PM roc ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In content/en/docs/concepts/services-networking/service-topology.md <#17459 (comment)>: > + +* Valid topology keys are currently limited to `kubernetes.io/hostname` <http://kubernetes.io/hostname>, + `topology.kubernetes.io/zone` <http://topology.kubernetes.io/zone>, and `topology.kubernetes.io/region` <http://topology.kubernetes.io/region>, but will + be generalized to other node labels in the future. + +* Topology keys must be valid label keys and at most 16 keys may be specified. + +* The catch-all value, `"*"`, must be the last value in the topology keys, if + it is used. + + +{{% /capture %}} + +{{% capture whatsnext %}} + +* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology) nit: enabling --> Enabling And currently the doc Enabling Service Topology is not exists, will be added in later commit or another PR? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17459?email_source=notifications&email_token=ACIHRMZ6RWX4ALFBIKFE5ZDQVCD7NA5CNFSM4JJ3DV4KYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCMXZPCA#pullrequestreview-321886088>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACIHRMZ7ZUGKA3IRTXNK233QVCD7NANCNFSM4JJ3DV4A> .

imroc · 2019-11-23T02:52:48Z

Maybe we don't need it, just add an simple Service example in this doc?

daminisatya · 2019-11-24T05:48:15Z

/lgtm

@johnbelamaric Thank you for the PR. let me know once it is final, I will approve it.

andrewsykim

/lgtm

andrewsykim · 2019-11-25T17:02:19Z

content/en/docs/concepts/services-networking/service-topology.md

+feature:
+  title: Service Topology
+  description: >
+    Routing of service traffice based upon cluster topology.


s/traffice/traffic

^ I can fix this in a follow-up PR, I have some other changes I'd like to add :)

daminisatya · 2019-11-26T05:17:57Z

@johnbelamaric Kindly update the PR with these small review comments ASAP!

daminisatya · 2019-11-26T05:27:34Z

/lgtm
/approve

k8s-ci-robot · 2019-11-26T05:27:55Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: daminisatya

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [daminisatya]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

andrewsykim · 2019-11-26T05:30:16Z

/hold cancel

johnbelamaric · 2019-11-28T00:15:37Z

Thanks all for following up on this, I was OOO and had very limited network access the last few days!

* feat: graduate TaintNodesByCondition to GA (#17073) * Promote StartupProbe to beta (enabled by default). (#17164) * Watch bookmarks to GA (#17026) * feat: graduate ScheduleDaemonSetPods to GA (#17350) * Update Docker installation instructions (#17405) * Use exact version numbers for installing Docker in Ubuntu (#17428) * Move CSIMigration and CSIMigrationGCE to Beta in Kubernetes v1.17 (#17478) * Promote NodeLease feature to GA (#17189) * Update docs for csi topology ga (#17408) * Update RunAsUsername to beta (#17460) * doc:Update RunAsUsername to beta * doc: update samples - kubernetes.io/os is no longer beta * Updating based on review feedback * Promote Node-specific volume limits to GA (#17432) * Promote PodShareProcessNamespace to stable (#17192) * Promote PodShareProcessNamespace to stable * Add for_k8s_version to feature-state label Co-Authored-By: Tim Bannister <tim@scalefactory.com> * Readd version-check to shareProcessNamespace task * Update service load balancer finalizer doc for GA (#17438) * Update Topology Manager docs (#17451) * Added information on how device plugins can take advantage of Topology Manager * Updated the Topology Manager documentation to include additionalinformation and update some out of date sections * Fix broken Topology Manager link (#17746) Part of What's Next Device Plugin section * Update CRD defaulting docs for GA (#17450) * Add documentation for VolumeSnapshot Beta (#17233) * Updating EndpointSlice documentation for beta release in 1.17 (#17411) * (docs/dualstack): v1.17 updates (#17457) * Add placehold doc updates for dualstack in 1.17 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Add Downward API and /etc/hosts Pod IP validation Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * remove addressed known issue via k/k pr 85246 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Remove known issue and add flag as part of k/k 79993 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * remove follow up placeholders Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update verbiage Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Make IP addressing consistent throughout the task Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update to status.podIPs Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update content/en/docs/tasks/network/validate-dual-stack.md Use set instead of env Co-Authored-By: Khaled Henidak (Kal) <khnidk@outlook.com> * add topology.kubernetes.io/zone, topology.kubernetes.io/region and node.kubernetes.io/instance-type labels to docs (#17498) Signed-off-by: Andrew Sy Kim <kiman@vmware.com> * Service topology alpha documentation (#17459) * Update list of feature flags for in-tree plugins migrated to CSI (#17533) Signed-off-by: Deep Debroy <ddebroy@docker.com> * Update Node concept for TaintNodesByCondition going GA (#17577) * feat: graduate ResourceQuotaScopeSelectors to GA in 1.17 (#17554) * kubeadm: update the upgrade documentation for 1.17 (#17587) * doc: Simplify Windows deployments with RuntimeClass (#16697) * doc: Simplify Windows deployments with RuntimeClass * Updating on review feedback * doc: Adding windows-build label from enhancement 1301 * update doc for kubelet option --reserved-cpus (#17648) * feat: update TaintNodesByCondition in feature gates table (#17377) * Update docs for v1 resource quota configuration (#17547) * AdmissionConfiguration v1 (#17548) * Update WebhookAdmissionConfiguration examples (#17549) * Update AWS EBS Migration Feature state (#16126) * Add resource version section to api-concepts documentation (#16910) * Add Resource Version semantics section to api concepts * Clarify risks of going back in time, add details about compaction and watch cache sizes * Apply suggestions from liggitt Co-Authored-By: Jordan Liggitt <jordan@liggitt.net> * remove pesudocode, apply feedback * Fix typo * Clarify equality rules * Cleanup kubectl generators docs (#17609) * Write ReplicationController without a space * Drop mentioning unsupported cluster versions * Fix capitalization for “API group” * Tweak wording * Avoid using deprecated generator in example * add Antrea description in dev-1.17 (#17919) * Promote VolumeSubpathEnvExpansion to GA * Reference Documentation for the Kubernetes API for 1.17 (#18019) * Update feature-gates.md (#18033) * Reference Documentation for kubectl Commands for 1.17 (#18017) * Update for v1.17 (#18034) * Update config.toml(release-1.17) for 1.17 (#18031)

k8s-ci-robot added sig/network Categorizes an issue or PR as relevant to SIG Network. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Nov 6, 2019

k8s-ci-robot added language/en Issues or PRs related to English language size/M Denotes a PR that changes 30-99 lines, ignoring generated files. sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Nov 6, 2019

k8s-ci-robot requested review from Rajakavitha1 and sftim November 6, 2019 19:12

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Nov 6, 2019

johnbelamaric mentioned this pull request Nov 6, 2019

Service Topology implementation for Kubernetes kubernetes/kubernetes#72046

Merged

tengqm added this to the 1.17 milestone Nov 7, 2019

sftim reviewed Nov 7, 2019

View reviewed changes

johnbelamaric force-pushed the service-topology-docs branch from 3be8dce to 36dbcdd Compare November 22, 2019 19:37

k8s-ci-robot assigned imroc Nov 22, 2019

k8s-ci-robot assigned robscott Nov 22, 2019

robscott reviewed Nov 22, 2019

View reviewed changes

Service topology alpha documentation

461c486

johnbelamaric force-pushed the service-topology-docs branch from 535314c to 461c486 Compare November 22, 2019 22:29

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 22, 2019

imroc reviewed Nov 23, 2019

View reviewed changes

k8s-ci-robot assigned daminisatya Nov 24, 2019

andrewsykim reviewed Nov 26, 2019

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 26, 2019

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Nov 26, 2019

k8s-ci-robot merged commit 4ff6d5e into kubernetes:dev-1.17 Nov 26, 2019

andrewsykim mentioned this pull request Nov 26, 2019

Add common examples to Service Topology documentation #17808

Closed

johnbelamaric deleted the service-topology-docs branch November 28, 2019 00:15

mrbobbytables pushed a commit that referenced this pull request Dec 6, 2019

Service topology alpha documentation (#17459)

d8ee209

ysyukr mentioned this pull request Dec 19, 2019

Translate services-networking/service-topology.md in Korean. #18096

Merged

andrewsykim mentioned this pull request Jan 15, 2020

Add common examples to Service Topology documentation #18712

Merged


		{{% capture whatsnext %}}

		* [Enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)

	* [Enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)
	* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology/)

Service topology alpha documentation #17459

Service topology alpha documentation #17459

Conversation

johnbelamaric commented Nov 6, 2019

k8sio-netlify-preview-bot commented Nov 6, 2019 • edited Loading

johnbelamaric commented Nov 6, 2019

sftim Nov 7, 2019

Choose a reason for hiding this comment

imroc commented Nov 7, 2019 • edited Loading

imroc commented Nov 7, 2019 • edited Loading

Prerequisites

imroc commented Nov 7, 2019

Enable Service Topology

johnbelamaric commented Nov 7, 2019

imroc commented Nov 8, 2019 • edited Loading

daminisatya commented Nov 20, 2019

imroc commented Nov 21, 2019 • edited Loading

imroc commented Nov 21, 2019

Motivation

imroc commented Nov 21, 2019

Topology Keys

imroc commented Nov 21, 2019

johnbelamaric commented Nov 21, 2019

imroc commented Nov 22, 2019

imroc commented Nov 22, 2019

Introduction

imroc commented Nov 22, 2019

Using Topology Keys

daminisatya commented Nov 22, 2019

johnbelamaric commented Nov 22, 2019

johnbelamaric commented Nov 22, 2019

robscott left a comment

Choose a reason for hiding this comment

johnbelamaric commented Nov 22, 2019

robscott commented Nov 22, 2019

imroc left a comment • edited Loading

Choose a reason for hiding this comment

imroc Nov 23, 2019 • edited Loading

Choose a reason for hiding this comment

andrewsykim Nov 26, 2019

Choose a reason for hiding this comment

johnbelamaric commented Nov 23, 2019 via email

imroc commented Nov 23, 2019

daminisatya commented Nov 24, 2019

andrewsykim left a comment

Choose a reason for hiding this comment

andrewsykim Nov 25, 2019

Choose a reason for hiding this comment

andrewsykim Nov 26, 2019

Choose a reason for hiding this comment

daminisatya commented Nov 26, 2019

daminisatya commented Nov 26, 2019

k8s-ci-robot commented Nov 26, 2019

andrewsykim commented Nov 26, 2019

johnbelamaric commented Nov 28, 2019

k8sio-netlify-preview-bot commented Nov 6, 2019 •

edited

Loading

imroc commented Nov 7, 2019 •

edited

Loading

imroc commented Nov 7, 2019 •

edited

Loading

imroc commented Nov 8, 2019 •

edited

Loading

imroc commented Nov 21, 2019 •

edited

Loading

imroc left a comment •

edited

Loading

imroc Nov 23, 2019 •

edited

Loading