Revise router customization documentation #3779

pecameron · 2017-02-17T20:42:02Z

OSE 3.5 (May end up in 3.4, 3.3)

General revision of the router customization doc,
Add section on how to work with the template.

Signed-off-by: Phil Cameron [email protected]

pecameron · 2017-02-17T20:43:44Z

@rajatchopra @ramr @JacobTanenbaum @imcsk8
Here is the first pass at describing how to work with templates. PTAL

pecameron · 2017-02-17T20:55:49Z

@ahardin-rh I am thinking of further revisions to the router docs beyond this. Do you know of any work that is being done on router docs? I would like to coordinate what I do to make things flow easier. I can delay doing anything while the docs team is making changes. Thanks!
PTAL if you have the time.

ahardin-rh · 2017-02-20T22:15:47Z

install_config/router/customized_haproxy_router.adoc

-setup to xref:using-stick-tables[use stick-tables] that synchronizes between
-peers. The router plug-in provides all the facilities necessary to make this
-customization.
+The default haproxy router is intended to satisfy the needs of most users.


Thanks, I will change it everywhere.

ahardin-rh · 2017-02-20T22:17:09Z

install_config/router/customized_haproxy_router.adoc

+xref:using-stick-tables[stick-tables] that synchronizes between peers. The
+router plug-in provides all the facilities necessary to make this customization.
+
+The router pod uses a template file to create the needed HAProxy config file.


s/config/configuration

OK, went through and fixed them all.

ahardin-rh · 2017-02-20T22:20:19Z

install_config/router/customized_haproxy_router.adoc

 endif::[]
 ifdef::openshift-origin[]
 # docker run --rm --interactive=true --tty --entrypoint=cat \
    openshift/origin-haproxy-router haproxy-config.template
 endif::[]
 ----

+Where the image name is from "docker images"
+or by running this on master referencing the router pod:


master, referencing

ahardin-rh · 2017-02-20T22:21:14Z

install_config/router/customized_haproxy_router.adoc

+The default haproxy router is intended to satisfy the needs of most users.
+However, it does not expose all of the capability of HAProxy and users
+may need to modify the router for their own needs.  Here is how to go
+about customizing the router.


Should we remove this last line (Here is how...) and perhaps rename this section to be Customizing the Router?

Deleted the last sentence. The whole section is how to do this.

ahardin-rh · 2017-02-20T22:22:29Z

install_config/router/customized_haproxy_router.adoc

+may need to modify the router for their own needs.  Here is how to go
+about customizing the router.
+
+One common need might be implementing new features within the


You may need to implement new features within the application back-ends, or modify the current operation.

Changed. Nice wording.

ahardin-rh · 2017-02-20T22:24:45Z

install_config/router/customized_haproxy_router.adoc

+The router pod uses a template file to create the needed HAProxy config file.
+The template file is a
+link:http://golang.org/pkg/text/template/[*golang* template].
+When processing the template the router has access to {product-title}


template, the router has access to {product-title} information, including the router's deployment configuration, the set of admitted routes, and some helper functions.

Ah yes, the missing comma

ahardin-rh · 2017-02-20T22:25:55Z

install_config/router/customized_haproxy_router.adoc

+information including the router's deployment configuration,
+the set of admitted routes and some helper functions.
+
+When the router pod starts and every time it reloads it creates a HAProxy


reloads, it creates an HAProxy configuration file, and then

ahardin-rh · 2017-02-20T22:27:28Z

install_config/router/customized_haproxy_router.adoc

+configuration file.
+
+A *ConfigMap* can be used to add the new template to the router pod. With
+this approach the router deployment configuration is modified mount the


approach, the router

is modified and mounts?

I forgot some words here. modified to mount

ahardin-rh · 2017-02-20T22:29:07Z

install_config/router/customized_haproxy_router.adoc

+this approach the router deployment configuration is modified mount the
+xref:using-configmap-replace-template[*configMap*] as a volume in the router
+pod.  The *TEMPLATE_FILE* environment
+varuable is set to the full path name of the file in the router pod.


`TEMPLATE_FILE` environment variable

I will change all environment variables to this markup VAR.

ahardin-rh · 2017-02-20T22:30:08Z

install_config/router/customized_haproxy_router.adoc

+configuration *image:* field is updated with the new name. When the cluster is
+updated the image needs to be rebuilt and pushed.
+
+In either case it starts with the template file.


In either case, the process starts with the template file ?

ahardin-rh · 2017-02-20T22:30:42Z

install_config/router/customized_haproxy_router.adoc


 [[obtaining-router-configuration-template]]
 == Obtaining the Router Configuration Template

-You can obtain a new *_haproxy-config.template_* file from the latest router
-image by running:
+The HAProxy template file is fairly large and complex. For some changes it may


changes, it may

ahardin-rh · 2017-02-20T22:32:30Z

install_config/router/customized_haproxy_router.adoc

+As the template is processed anything not surrounded by "{{" something "}}"
+is directly copied to the config file. Passages that are surrounded by "{{"
+something "}}" are evaluated and the resulting text, if any, is copied to the
+config file.


s/config/configuration

ahardin-rh · 2017-02-20T22:36:24Z

@pecameron Thanks! I started to make a few comments, but I can always follow-up with some edits in a separate PR.

@aheslin Do you know of any planned docs work regarding router content?

ahardin-rh · 2017-02-20T22:38:11Z

install_config/router/customized_haproxy_router.adoc

+=== Go Template Constructs
+
+The following excerpts are from the
+link:https://golang.org/pkg/text/template/[go template]


@aheslin any thoughts on how we should handle excerpts like this?

I did copy from the referenced doc, just giving credit and pointing to a more through discussion.

pecameron

@ahardin-rh
Does this come across clearly? Could you use it to actually customize the router? I can rewrite whatever is needed to improve this.

pecameron · 2017-02-21T18:27:31Z

install_config/router/customized_haproxy_router.adoc

+The default haproxy router is intended to satisfy the needs of most users.
+However, it does not expose all of the capability of HAProxy and users
+may need to modify the router for their own needs.  Here is how to go
+about customizing the router.


Deleted the last sentence. The whole section is how to do this.

pecameron · 2017-02-21T18:29:04Z

install_config/router/customized_haproxy_router.adoc

+may need to modify the router for their own needs.  Here is how to go
+about customizing the router.
+
+One common need might be implementing new features within the


Changed. Nice wording.

pecameron · 2017-02-21T18:31:30Z

install_config/router/customized_haproxy_router.adoc

+xref:using-stick-tables[stick-tables] that synchronizes between peers. The
+router plug-in provides all the facilities necessary to make this customization.
+
+The router pod uses a template file to create the needed HAProxy config file.


OK, went through and fixed them all.

pecameron · 2017-02-21T18:33:49Z

install_config/router/customized_haproxy_router.adoc

+The router pod uses a template file to create the needed HAProxy config file.
+The template file is a
+link:http://golang.org/pkg/text/template/[*golang* template].
+When processing the template the router has access to {product-title}


Ah yes, the missing comma

pecameron · 2017-02-21T18:34:37Z

install_config/router/customized_haproxy_router.adoc

+information including the router's deployment configuration,
+the set of admitted routes and some helper functions.
+
+When the router pod starts and every time it reloads it creates a HAProxy


pecameron · 2017-02-21T18:39:04Z

install_config/router/customized_haproxy_router.adoc

+this approach the router deployment configuration is modified mount the
+xref:using-configmap-replace-template[*configMap*] as a volume in the router
+pod.  The *TEMPLATE_FILE* environment
+varuable is set to the full path name of the file in the router pod.


I will change all environment variables to this markup VAR.

pecameron · 2017-02-21T18:42:06Z

install_config/router/customized_haproxy_router.adoc

+configuration *image:* field is updated with the new name. When the cluster is
+updated the image needs to be rebuilt and pushed.
+
+In either case it starts with the template file.


pecameron · 2017-02-21T18:43:17Z

install_config/router/customized_haproxy_router.adoc


 [[obtaining-router-configuration-template]]
 == Obtaining the Router Configuration Template

-You can obtain a new *_haproxy-config.template_* file from the latest router
-image by running:
+The HAProxy template file is fairly large and complex. For some changes it may


pecameron · 2017-02-21T18:44:19Z

install_config/router/customized_haproxy_router.adoc

+As the template is processed anything not surrounded by "{{" something "}}"
+is directly copied to the config file. Passages that are surrounded by "{{"
+something "}}" are evaluated and the resulting text, if any, is copied to the
+config file.


pecameron · 2017-02-21T18:45:28Z

install_config/router/customized_haproxy_router.adoc

+=== Go Template Constructs
+
+The following excerpts are from the
+link:https://golang.org/pkg/text/template/[go template]


I did copy from the referenced doc, just giving credit and pointing to a more through discussion.

rajatchopra · 2017-02-21T19:56:49Z

install_config/router/customized_haproxy_router.adoc

+The HAProxy template file is fairly large and complex. For some changes, it may
+be easier to modify the existing template rather than writing a complete
+replacement.  You can obtain a *_haproxy-config.template_* file from a running
+router by logging onto the node that is running the router:


I always do a 'oc rsh' to view any files on a running router. Much easier. May want to add that as an on option.

@rajatchopra reversed docker/oc examples.

rajatchopra · 2017-02-21T19:57:59Z

install_config/router/customized_haproxy_router.adoc


 ----
 ifdef::openshift-enterprise[]
 # docker run --rm --interactive=true --tty --entrypoint=cat \
-    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.0.2.0 haproxy-config.template
+    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.5.0.0 haproxy-config.template


Write $version here instead, maybe?

Yeah, its easier to just get it from a current running pod and use the oc set. Maybe:
oc rsh <router-pod-name> cat haproxy-config.template > localdir/haproxy-config.template ?

Aah, never mind see that you have it below.

rajatchopra · 2017-02-21T20:00:24Z

install_config/router/customized_haproxy_router.adoc

+  balance $balanceAlgo
+{{ end }}
+----
+Here when $balanceAlgo is not *nill*, "balance $balanceAlgo" is copied to the


rajatchopra · 2017-02-21T20:02:41Z

install_config/router/customized_haproxy_router.adoc

+----
+matchPattern "[1-9][0-9]*(us|ms|s|m|h|d)?" $value
+----
+This would accept "5000ms" but not "7y". This results can be used in a test.


'The results' or 'This result' or 'The result'

the nitpicker :)

Fixed (love to fix nit picks)

ramr

Minor comments - LGTM

ramr · 2017-02-22T02:51:20Z

install_config/router/customized_haproxy_router.adoc

+
+An alternative approach is to modify the *haproxy-template.config* file
+and xref:rebuilding-your-router[rebuild] the router image. The new image
+is pushed to the the cluster repositiory and the routers deployment


typo: repository

ramr · 2017-02-22T02:54:27Z

install_config/router/customized_haproxy_router.adoc


 ----
 ifdef::openshift-enterprise[]
 # docker run --rm --interactive=true --tty --entrypoint=cat \
-    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.0.2.0 haproxy-config.template
+    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.5.0.0 haproxy-config.template


Yeah, its easier to just get it from a current running pod and use the oc set. Maybe:
oc rsh <router-pod-name> cat haproxy-config.template > localdir/haproxy-config.template ?

ramr · 2017-02-22T02:55:00Z

install_config/router/customized_haproxy_router.adoc


 ----
 ifdef::openshift-enterprise[]
 # docker run --rm --interactive=true --tty --entrypoint=cat \
-    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.0.2.0 haproxy-config.template
+    registry.access.redhat.com/openshift3/ose-haproxy-router:v3.5.0.0 haproxy-config.template


Aah, never mind see that you have it below.

ramr · 2017-02-22T02:57:59Z

install_config/router/customized_haproxy_router.adoc

+|`*endpointsForAlias*` | returns the list of valid endpoints
+|`*env*` | tries to get the named environment variable from the pod if it
+can't it returns the second argument.
+|`*matchPattern*` | the firt argument is a string that contains the regular


typo: first

ramr · 2017-02-22T02:58:58Z

install_config/router/customized_haproxy_router.adoc

+|`*genCertificateHostName*` | generates host name to use for serving/matching
+certificates.  First argument is the host name and the second is the wildcard
+bolean.
+|===


Wonder if providing like a function signature out here would be useful - that way the arguments/return types are shown/readable?

genCertificateHostName is only used in writing the "/var/lib/haproxy/conf/cert_config.map" file.
{{ define "/var/lib/haproxy/conf/cert_config.map" }}
{{ $workingDir := .WorkingDir }}
{{ range $idx, $cfg := .State }}
{{ if and (ne $cfg.Host "") (or (eq $cfg.TLSTermination "edge") (eq $cfg.TLSTermination "reencrypt")) }}
{{ $cert := index $cfg.Certificates $cfg.Host }}
{{ if ne $cert.Contents "" }}
{{$workingDir}}/certs/{{$idx}}.pem {{genCertificateHostName $cfg.Host $cfg.IsWildcard}}
{{ end }}
{{ end }}
{{ end }}
{{ end }}{{/* end cert_config map template */}}

No I meant like a golang function signature for all the helper functions ala:
func env(name, defaultValue string) string
func matchPattern(pattern, s string) bool

etc. and add some info re: the function (or just point to the examples you have below) ... might be a good resource for someone who understands golang.

I agree with ramr

OK, I was concerned that the func strings would be too long and distort the table.

ramr · 2017-02-22T03:02:51Z

install_config/router/customized_haproxy_router.adoc

+
+Route Annotations, *$cfg.Annotations*, is also a map with the annotation
+name as the key and the content string as the value.  The route can have
+as many annotitions as desired and the use is defined by the developer.


typo: annotations

ramr · 2017-02-22T03:05:59Z

@pecameron this is great info. 👍

pecameron · 2017-02-22T16:35:13Z

@ramr @rajatchopra Thenks for the review. I made the suggested changes. @ahardin-rh PTAL

pecameron · 2017-02-22T18:56:52Z

@openshift/team-documentation tech review complete PTAL

pecameron · 2017-03-30T18:49:42Z

@ahardin-rh Is this ready to merge?

ahardin-rh · 2017-03-30T19:33:27Z

@pecameron Yes, if I have any other nits, I will follow up in a separate follow-up PR. Can you clarify the time-frame for this? Should this be targeting OCP 3.5, or is it okay to get pulled in now to 3.4 and 3.3? I can adjust my labels/milestone accordingly.

pecameron · 2017-04-04T13:49:16Z

@knobunc I think the template descriptions can go in 3.4 do you think it can go in 3.3? It has Jake's route annotations. Not sure where they went in.
@ahardin-rh

pecameron · 2017-04-05T13:53:15Z

@ahardin-rh This can go in 3.3, 3.4, 3.5

ahardin-rh · 2017-04-11T17:16:05Z

Thank you, all!

ahardin-rh · 2017-04-11T17:43:42Z

[rev_history]
|xref:../architecture/core_concepts/routes.adoc#architecture-core-concepts-routes[Core Concepts -> Routes]
|Updated router customization details.
%
|xref:../install_config/router/customized_haproxy_router.adoc#install-config-router-customized-haproxy[Setting up a Router -> Deploying a Customized HAProxy Router]
|Expanded details in the xref:../install_config/router/customized_haproxy_router.adoc#rebuilding-your-router[Rebuilding Your Router] section.
%

pecameron force-pushed the template branch from 8c846c2 to 5a506ef Compare February 17, 2017 20:49

ahardin-rh added this to the Next Release milestone Feb 20, 2017

ahardin-rh added branch/enterprise-3.3 branch/enterprise-3.4 labels Feb 20, 2017

ahardin-rh self-assigned this Feb 20, 2017

ahardin-rh reviewed Feb 20, 2017

View reviewed changes

pecameron commented Feb 21, 2017

View reviewed changes

pecameron force-pushed the template branch from 5a506ef to 9bac597 Compare February 21, 2017 19:04

rajatchopra suggested changes Feb 21, 2017

View reviewed changes

ramr approved these changes Feb 22, 2017

View reviewed changes

pecameron force-pushed the template branch from 9bac597 to 9be4c83 Compare February 22, 2017 16:33

pecameron force-pushed the template branch from 9be4c83 to 1edfb0b Compare February 23, 2017 14:02

pecameron force-pushed the template branch from 7209ce7 to 3ec1143 Compare March 30, 2017 14:44

bmcelvee modified the milestones: Next Release, Staging Apr 3, 2017

sdodson mentioned this pull request Apr 4, 2017

Need to add ROUTER_METRICS_TYPE during router upgrades openshift/openshift-ansible#3845

Closed

bmcelvee modified the milestones: Staging, Next Release Apr 6, 2017

ahardin-rh added branch/dedicated branch/online labels Apr 11, 2017

ahardin-rh merged commit 9cbac8e into openshift:master Apr 11, 2017

ahardin-rh added the branch/enterprise-3.5 label Apr 11, 2017

pecameron deleted the template branch April 11, 2017 18:33

ahardin-rh mentioned this pull request Apr 11, 2017

Follow-up edits to PR#3779 #4126

Merged

vikram-redhat modified the milestones: Next Release, Staging, Published - 04/12/2017 Apr 12, 2017

Revise router customization documentation #3779

Revise router customization documentation #3779

Uh oh!

Conversation

pecameron commented Feb 17, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pecameron commented Feb 17, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pecameron commented Feb 17, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahardin-rh commented Feb 20, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pecameron left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

pecameron commented Feb 17, 2017 •

edited

Loading

pecameron commented Feb 17, 2017 •

edited

Loading