Hide Forgot
I.4.2. Service Parameters "The data store service, authentication service, and DNS server are implemented as plug-ins to the broker." The data store service isn't really a plugin. The messaging is, though there's no alternative at this time. So, should probably read: "The messaging service, authentication service, and DNS server are implemented as plug-ins to the broker. I.4.3. DNS Information --- The DNS update service negotiates with the owner of a domain so that a sub-domain can be allocated. It also establishes authentication credentials to allow automatic updates. The sample configuration uses a private DNS service to allow the OpenShift Enterprise service to publish new host names without requiring access to an official DNS service. ==> Somewhere along the way this got confused. Negotiation and establishment of credentials are done by humans in accord with whatever IT policies are in effect for them. Try: === Enabling DNS updates may require that you work with the administrator of your intended domain so that a domain can be allocated for OpenShift applications and authentication credentials established to allow automatic updates. The sample configuration uses a private DNS service to allow the OpenShift Enterprise service to publish new host names without requiring access to update an official DNS service. --- Next paragraph The process of creating a private DNS service and establishing a delegation agreement with your IT department are beyond the scope of this guide. ==> Not sure public and private are the right distinctions to make here, but it would probably be clearest if this said "public" rather than private.
4.2 Implemented suggested wording. 4.3 Changed to: "The host names of new applications are published to DNS by the OpenShift Enterprise service. Consult the administrator of your intended domain to enable DNS updates. This will mean that the domain can then be assigned applications and the authentication credentials will allow automatic updates. The sample configuration uses a private DNS service to allow OpenShift Enterprise to publish new host names without requiring access to update an official DNS service. The application host names are only visible on the OpenShift Enterprise hosts and any workstation configured to use the same DNS service, unless properly delegated by a public DNS service." Luke, do you agree with the change? Also implemented suggested change in the second para.
Re 4.3, I don't think that quite captures it. This is a little tricky to explain, and frankly, most people don't know a lot about how this works, so I do want to go to some pains to get it right. DNS works by a series of referrals. OpenShift can set up a DNS server to handle any domain it wants, but it won't be used unless other DNS servers refer to it as authoritative for that domain. The "private" DNS server we install becomes "public" (I'd rather say "authoritative") simply by getting a referral from a server that's authoritative for the domain that contains it. In general, that means going to the owner of <company.com> (hopefully your local IT staff, but often some random service provider) and saying "look, I want to put up <openshift.company.com> and have it updated by OpenShift - do you want to give me credentials to update an existing DNS server that will handle that domain, or are you going to delegate to this DNS server we've set up just for OpenShift to update? Either way, need you to do something" - it's going to be a conversation. There's no real technical difference as far as OpenShift is concerned, but they need to know there's likely to be a conversation to decide the path to take and get it all properly referred to by whomever handles their DNS. Unless their setup is so simple that they just need to register a new domain name with some registrar and set the nameserver themselves - also possible. There are a number of options here so I don't really want to present any one path as "here is what you do" because it will be exclusive of necessary options and it all depends on their local politics / choice of domain. So how about: "OpenShift Enterprise requires the ability to dynamically publish the DNS host names of applications under a domain of your choosing. This documentation demonstrates configuring a DNS service to allow OpenShift Enterprise to publish host names, but that service can only be made authoritative by an external authority. Unless delegated by an authoritative DNS service, these application host names are only visible on the OpenShift Enterprise hosts and any workstation configured to use the same DNS service. Alternatively, OpenShift can publish to an existing authoritative service if given the necessary credentials for the domain." - And then proceed to the next paragraph with: "The process of creating an authoritative DNS service and/or establishing a delegation agreement with your IT department are beyond the scope of this guide."
Changed to: "The sample documentation configures a DNS service to allow OpenShift Enterprise to dynamically publish DNS host names of applications within your chosen domain. This can only be made authoritative by a external authority, such as your system administrator, or service provider. If OpenShift Enterprise is not made authoritative by your DNS provider, application host names are visible only on the OpenShift Enterprise host, or any workstation configured to use the same DNS service. Alternatively, OpenShift Enterprise can publish to an existing authoritative service if given the necessary credentials for the domain." Luke, let me know if you don't think it's meaningful enough. Also changed the 'public' in the second para to 'authoritative'.
Pretty meaningful. I would suggest these minor adjustments: "If OpenShift Enterprise is not made authoritative by your DNS provider" => "If the OpenShift Enterprise name server is not ..." "application host names are visible only on the OpenShift Enterprise host" => hosts "The delegation requirements must be discussed with the appropriate personnel" => won't necessarily be a delegation... how about just "The requirements" I think this will help put the situation in the right context so people understand why we can't just hook in automatically to existing DNS, one of the major problem points for many. Thanks!
Easy fixes. If there's nothing else, putting this BZ on QA. Thanks, Luke.