Porting Marathon Networking Doc to DC/OS #1066

sascala · 2017-05-19T11:57:29Z

Description

@jdef I'm assigning this to you because it's related to the Marathon networking doc you authored. I'm porting it over to the DC/OS site and I have some related questions. I also moved some information from the examples section up into the reference section because it seemed pretty important.

Urgency

Blocker
High
Medium

Requirements

Test all commands and procedures.
Build content locally and test for formatting/links.
Add redirects to dcos-website/redirect-files.
Change all affected versions (e.g. 1.7, 1.8, and 1.9).
See the contribution guidelines.

sascala · 2017-05-23T23:08:30Z

1.9/networking/service-and-pod-networking.md

+---
+
+This document describes how to specify networking modes and assign ports in the service definition for a DC/OS Service you are creating.
+


Do DC/OS users need to know about the networking API changes? it's only relevant if they've modified their native marathon instances AFAIK.

yes, DCOS users need to know about the marathon networking API changes. for example, they may have built external tooling that depends on the old (deprecated) APIs that are no longer emitted by Marathon

sascala · 2017-05-23T23:30:37Z

1.9/networking/service-and-pod-networking.md

+```
+
+In this example, we specify three dynamically assigned host ports, which would then be available to our command via the environment variables `$PORT_HTTP`, `$PORT_HTTPS` and `$PORT_MON`.
+


What's meant by "command" here? Is it that they're available to the app/service?

sascala · 2017-05-23T23:33:02Z

1.9/networking/service-and-pod-networking.md

+
+If there is a `--default_network_name` configured for Marathon, then specifying a network name for the `container` network is optional:
+`container` networks with an unspecified (`null`) `name` will inherit the value of the `--default_network_name` flag.
+


I don't think this is needed for DC/OS users?

There's a DCOS configuration for controlling the value of this root Marathon command line flag.

It's called dcos_overlay_network_default_name as per:
https://github.com/dcos/dcos/blob/ca564b4b90f069b6336cd445e36e9b83ddbabd6c/gen/calc.py#L943

(pretty sure we added this back in 1.9)

sascala · 2017-05-23T23:33:44Z

1.9/networking/service-and-pod-networking.md

+Similar to `container` networking, an application should be allocated its own network namespace and IP address;
+Mesos CNI provides a special `mesos-bridge` that application containers are attached to.
+When using the Docker containerizer, this translates to the Docker "default bridge" network.
+


I don't understand this part well enough to know if all of this is relevant for DC/OS users.

yes, it's relevant. it used to be called docker BRIDGE mode networking. there was not previously a Mesos (UCR) equivalent, so it's new functionality for UCR consumers

sascala · 2017-05-23T23:34:55Z

1.9/networking/service-and-pod-networking.md

+In container networking, an application should be allocated its own network namespace and IP address;
+Mesos network isolators are responsible for providing backend support for this.
+When using the Docker containerizer, this translates to a Docker "user" network. You can name your container network in the `networks.container` parameter of your service definition. If you do not provide a name for your container network, it will have the default container network name, `DEFAULT NAME`.
+


I don't understand this part well enough to know if all of this is relevant for DC/OS users.

yes, it's relevant. this went by various names before: docker USER mode networking, or Mesos IP/CT networking. now that we've consolidated the API it's simply container Networking

jdef

almost feels like the app ports section should be split off into a separate page. so then this page becomes the "app and pod services networking" page. with links to "app port configuration" and "pod endpoint configuration" pages. thoughts?

jdef · 2017-07-11T01:07:54Z

1.9/networking/service-and-pod-networking.md

+---
+
+This document describes how to specify networking modes and assign ports in the service definition for a DC/OS Service you are creating.
+


yes, DCOS users need to know about the marathon networking API changes. for example, they may have built external tooling that depends on the old (deprecated) APIs that are no longer emitted by Marathon

jdef · 2017-07-11T01:08:48Z

1.9/networking/service-and-pod-networking.md

+In container networking, an application should be allocated its own network namespace and IP address;
+Mesos network isolators are responsible for providing backend support for this.
+When using the Docker containerizer, this translates to a Docker "user" network. You can name your container network in the `networks.container` parameter of your service definition. If you do not provide a name for your container network, it will have the default container network name, `DEFAULT NAME`.
+


yes, it's relevant. this went by various names before: docker USER mode networking, or Mesos IP/CT networking. now that we've consolidated the API it's simply container Networking

jdef · 2017-07-11T01:09:34Z

1.9/networking/service-and-pod-networking.md

+Similar to `container` networking, an application should be allocated its own network namespace and IP address;
+Mesos CNI provides a special `mesos-bridge` that application containers are attached to.
+When using the Docker containerizer, this translates to the Docker "default bridge" network.
+


yes, it's relevant. it used to be called docker BRIDGE mode networking. there was not previously a Mesos (UCR) equivalent, so it's new functionality for UCR consumers

jdef · 2017-07-11T01:10:12Z

1.9/networking/service-and-pod-networking.md

+```
+
+In this example, we specify three dynamically assigned host ports, which would then be available to our command via the environment variables `$PORT_HTTP`, `$PORT_HTTPS` and `$PORT_MON`.
+


jdef · 2017-07-11T01:13:08Z

1.9/networking/service-and-pod-networking.md

+
+If there is a `--default_network_name` configured for Marathon, then specifying a network name for the `container` network is optional:
+`container` networks with an unspecified (`null`) `name` will inherit the value of the `--default_network_name` flag.
+


There's a DCOS configuration for controlling the value of this root Marathon command line flag.

It's called dcos_overlay_network_default_name as per:
https://github.com/dcos/dcos/blob/ca564b4b90f069b6336cd445e36e9b83ddbabd6c/gen/calc.py#L943

(pretty sure we added this back in 1.9)

joel-hamill

This topic seems to be all over the place organizationally. There seems to be a lot of cases where Marathon properties and command syntax are used instead of the higher level concept (e.g. container/bridge Networking, rather than Bridge Networking). There isn't any place that explains that all of these command-sytnax terms are actual Marathon properties. The topic mixes reference, usage, and examples and duplicates much of the reference content here: https://dcos.io/docs/1.9/deploying-services/marathon-parameters/.

In revising this topic, I would suggest making it a practical task topic that walks the user through configuring their networks and ports - and points off to reference topic when appropriate.

joel-hamill · 2017-07-12T20:43:49Z

1.9/networking/service-and-pod-networking.md

+menu_order: 0.5
+---
+
+This document describes how to specify networking modes and assign ports in the service definition for a DC/OS Service you are creating.


You can choose networking modes and assign ports in your DC/OS service definitions.

joel-hamill · 2017-07-12T20:44:10Z

1.9/networking/service-and-pod-networking.md

+
+# VIPs
+
+We recommend using [virtual addresses (VIPs)](/docs/1.9/usage/service-discovery/virtual-ip-addresses/) to make ports management easier. VIPs map traffic from a single virtual address to multiple IP addresses and ports. They simplify inter-app communication and implement a reliable service-oriented architecture.


port management

joel-hamill · 2017-07-12T20:44:37Z

1.9/networking/service-and-pod-networking.md

+
+# Networking Modes
+
+DC/OS services and pods declare `networks` the same way. Three modes of networking are supported:


why use command syntax for "networks"?

joel-hamill · 2017-07-12T20:45:14Z

1.9/networking/service-and-pod-networking.md

+
+# Networking Modes
+
+DC/OS services and pods declare `networks` the same way. Three modes of networking are supported:


suggest not using three since it's somewhat arbitrary: These networking modes are supported:

joel-hamill · 2017-07-12T20:45:36Z

1.9/networking/service-and-pod-networking.md

+
+DC/OS services and pods declare `networks` the same way. Three modes of networking are supported:
+
+## `host` Networking


Host Networking - without command syntax?

joel-hamill · 2017-07-12T21:00:22Z

1.9/networking/service-and-pod-networking.md

+Mesos network isolators are responsible for providing backend support for this.
+When using the Docker containerizer, this translates to a Docker "user" network. You can name your container network in the `networks.container` parameter of your service definition. If you do not provide a name for your container network, it will have the default container network name, `DEFAULT NAME`.
+
+## `container/bridge` Networking


can this title simply be Bridge Networking?

joel-hamill · 2017-07-12T21:01:12Z

1.9/networking/service-and-pod-networking.md

+
+# Ports for Services
+
+DC/OS services declare ports differently than pods. The following section is only relevant to services.


replace these two sentences with: This section describes how to declare ports for services.

joel-hamill · 2017-07-12T21:02:33Z

1.9/networking/service-and-pod-networking.md

+
+**Note:** Pods (endpoints) do not support service ports.
+
+### Declaring ports in an application


...in a service?

joel-hamill · 2017-07-12T21:03:47Z

1.9/networking/service-and-pod-networking.md

+
+### Referencing Ports
+
+You can reference the *host-port*s in the Dockerfile for our fictitious app as follows:


...for our sample app as follows:

joel-hamill · 2017-07-12T21:05:21Z

1.9/networking/service-and-pod-networking.md

@@ -0,0 +1,422 @@
+---
+post_title: Service and Pod Networking


change title to: Configuring Networks and Ports

jdef · 2017-08-15T17:56:29Z

1.9/networking/service-and-pod-networking.md

@@ -17,6 +17,8 @@ DC/OS services and pods declare `networks` the same way. Three modes of networki

 In `host` networking, an application shares the network namespace of the Mesos agent process, typically the host network namespace.

+**Note:** The `Network.name` parameter cannot be used with `host` networking.


so .. it's actually only useful for container mode. not host and not container/bridge.

jdef · 2017-08-15T20:24:53Z

1.9/networking/service-and-pod-networking.md

+**Notes:**:
+
+- The UCR and Docker Containerizer support all network modes.
+- The `Network.name` parameter is only supported with `container` networking.


sascala · 2018-01-18T06:52:59Z

@pavisandhu This is a work in progress. We need to incorporate the marathon networking doc into the dc/os site however you think it's best.

Porting Marathon Networking Doc to DC/OS

6b3ff85

sascala added the work-in-progress label May 19, 2017

sascala self-assigned this May 19, 2017

sascala added 3 commits May 19, 2017 14:02

rename doc

adb8e0c

rename again

95d430b

moved important info in examples section higher in the doc

8dee1eb

sascala commented May 23, 2017

View reviewed changes

sascala requested a review from jdef May 23, 2017 23:49

jdef reviewed Jul 11, 2017

View reviewed changes

joel-hamill suggested changes Jul 12, 2017

View reviewed changes

Update service-and-pod-networking.md

7935109

jdef reviewed Aug 15, 2017

View reviewed changes

Update service-and-pod-networking.md

09554ed

jdef reviewed Aug 15, 2017

View reviewed changes

sascala assigned pavisandhu and unassigned sascala Jan 18, 2018

mesosphere-backup unassigned pavisandhu Oct 16, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Porting Marathon Networking Doc to DC/OS #1066

Porting Marathon Networking Doc to DC/OS #1066

sascala commented May 19, 2017 •

edited

Loading

sascala May 23, 2017

jdef Jul 11, 2017

sascala Jul 11, 2017

sascala May 23, 2017

jdef Jul 11, 2017

sascala May 23, 2017

jdef Jul 11, 2017

sascala May 23, 2017

jdef Jul 11, 2017

sascala May 23, 2017

jdef Jul 11, 2017

jdef left a comment

jdef Jul 11, 2017

jdef Jul 11, 2017

jdef Jul 11, 2017

jdef Jul 11, 2017

jdef Jul 11, 2017

joel-hamill left a comment

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

joel-hamill Jul 12, 2017

jdef Aug 15, 2017

jdef Aug 15, 2017

sascala commented Jan 18, 2018

		---

		This document describes how to specify networking modes and assign ports in the service definition for a DC/OS Service you are creating.

		```

		In this example, we specify three dynamically assigned host ports, which would then be available to our command via the environment variables `$PORT_HTTP`, `$PORT_HTTPS` and `$PORT_MON`.


		If there is a `--default_network_name` configured for Marathon, then specifying a network name for the `container` network is optional:
		`container` networks with an unspecified (`null`) `name` will inherit the value of the `--default_network_name` flag.


		# VIPs

		We recommend using [virtual addresses (VIPs)](/docs/1.9/usage/service-discovery/virtual-ip-addresses/) to make ports management easier. VIPs map traffic from a single virtual address to multiple IP addresses and ports. They simplify inter-app communication and implement a reliable service-oriented architecture.


		# Networking Modes

		DC/OS services and pods declare `networks` the same way. Three modes of networking are supported:


		DC/OS services and pods declare `networks` the same way. Three modes of networking are supported:

		## `host` Networking


		# Ports for Services

		DC/OS services declare ports differently than pods. The following section is only relevant to services.


		Note: Pods (endpoints) do not support service ports.

		### Declaring ports in an application


		### Referencing Ports

		You can reference the host-ports in the Dockerfile for our fictitious app as follows:

		@@ -17,6 +17,8 @@ DC/OS services and pods declare `networks` the same way. Three modes of networki

		In `host` networking, an application shares the network namespace of the Mesos agent process, typically the host network namespace.

		Note: The `Network.name` parameter cannot be used with `host` networking.

Porting Marathon Networking Doc to DC/OS #1066

Are you sure you want to change the base?

Porting Marathon Networking Doc to DC/OS #1066

Conversation

sascala commented May 19, 2017 • edited Loading

Description

Urgency

Requirements

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdef left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joel-hamill left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sascala commented Jan 18, 2018

sascala commented May 19, 2017 •

edited

Loading