Bug 1412824 - [Docs] Improve egress documentation / examples or usecase information.
Summary: [Docs] Improve egress documentation / examples or usecase information.
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation
Version: 3.4.0
Hardware: Unspecified
OS: Unspecified
medium
high
Target Milestone: ---
: ---
Assignee: brice
QA Contact: zhaozhanqi
Vikram Goyal
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-01-12 21:52 UTC by Eric Rich
Modified: 2020-04-15 15:05 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-03-22 03:33:34 UTC
Target Upstream Version:


Attachments (Terms of Use)
more detailed diagram (1.47 MB, image/png)
2017-02-17 17:31 UTC, Dan Winship
no flags Details

Description Eric Rich 2017-01-12 21:52:59 UTC
Document URL: https://docs.openshift.com/container-platform/3.3/admin_guide/managing_pods.html#admin-guide-controlling-egress-traffic

Section Number and Name: Controlling Egress Traffic

Describe the issue: The basic explanation/wording given in the egress documentation, provides the assumption that the egress router and egress firewall provide the same functionality or usecase. 

> !!! This is not the case !!!

The egress router: is used to provide external entities a uniquely identify address (ip address) for the the dynamic endpoints (pods with in OpenShift, that can have undeterministic ip address or be comprised of multiple ip address - from multiple pods), so that external source can treat the traffic as coming from a known source. 

The egress firewall: is used to enforce acceptable (outbound) traffic policies. So that an organization can define, acceptable endpoints or ranges that dynamic endpoints (pods with in OpenShift) can talk to. 

Suggestions for improvement: 

1: The description of egress traffic controls provided by the {{Document URL}}, needs to clearly state / outline the usecases for each functional service. 

2. Examples, for each functional service should be provided: 

>> The egress router: If you have a database server (off on the internet or in your network) that has security restrictions where only predefined IP address can connect to.

>> The egress firewall: If you want to restrict developers from pulling updates from (python) pip mirrors, and force updates to come from corporate defined sources. 

Additional information:

Comment 1 brice 2017-01-31 05:05:28 UTC
Eric,

I've created a PR for this BZ: https://github.com/openshift/openshift-docs/pull/3625

Can I ask if this fulfills what you wanted from this BZ? I tried to make the two different egress methods sound different in the intro paragraph, and added a little more context into the following sections. Some of the stuff you suggested was already in there in some form, but I added to it where I could.

Let me know if you see any issues. And thanks!

Comment 3 brice 2017-02-01 04:59:03 UTC
Eric,

Thanks for the comment. I've made a change to that section to be more like what you suggested:

https://github.com/openshift/openshift-docs/pull/3625

As for the thread and the picture, I'm not sure what information is missing. The relevant stuff is either too behind-the-scenes context, or in the docs already in some form.

I asked a networking guy here in the Brisbane office, and he suggested that the OpenStack docs have some good info on this. Are you after something like this:

https://access.redhat.com/documentation/en/red-hat-openstack-platform/10/single/networking-guide#the_flow_of_outgoing_traffic_2

Comment 4 Eric Rich 2017-02-01 14:29:34 UTC
(In reply to brice from comment #3)
> Eric,
> 
> Thanks for the comment. I've made a change to that section to be more like
> what you suggested:
> 
> https://github.com/openshift/openshift-docs/pull/3625
> 
> As for the thread and the picture, I'm not sure what information is missing.
> The relevant stuff is either too behind-the-scenes context, or in the docs
> already in some form.

IMO, the docs we have around the topic of egress, throw data at our customers. Here, this is what this does. 
But it does not do a good job of explaining why, I would want to use one method over another, or what value / purpose each method serves. 

While you have added that in 1-2 sentences, it may still leave the reader desiring more information, or examples. 

The thread helps with this type of information.  

> 
> I asked a networking guy here in the Brisbane office, and he suggested that
> the OpenStack docs have some good info on this. Are you after something like
> this:
> 
> https://access.redhat.com/documentation/en/red-hat-openstack-platform/10/
> single/networking-guide#the_flow_of_outgoing_traffic_2

We have something like that in our docs too: https://docs.openshift.com/container-platform/3.4/architecture/additional_concepts/sdn.html#sdn-packet-flow 

However the OpenStack docs are better (IMO) as the picture helps make it more clear, what exactly is happening with the traffic flow.

Comment 7 Dan Winship 2017-02-17 17:31:25 UTC
Created attachment 1254911 [details]
more detailed diagram

Here's a more detailed diagram, trying to make clear how the EGRESS_SOURCE / EGRESS_GATEWAY work. Feel free to take this and do anything with it.

Comment 10 openshift-github-bot 2017-02-27 23:57:38 UTC
Commit pushed to master at https://github.com/openshift/openshift-docs

https://github.com/openshift/openshift-docs/commit/98b25bf8b92facd295fbee08ce118392141ea0fe
Merge pull request #3625 from bfallonf/egress_1412824

Bug 1412824 Added context to egress router section


Note You need to log in before you can comment on or make changes to this bug.