You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by ra...@apache.org on 2019/03/11 18:29:52 UTC
[trafficcontrol] branch master updated: Static dns entry example
documentation (#3379)
This is an automated email from the ASF dual-hosted git repository.
rawlin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 1e5d658 Static dns entry example documentation (#3379)
1e5d658 is described below
commit 1e5d6582b1225e9bf686953704d1f91cdf65a480
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Mon Mar 11 12:29:47 2019 -0600
Static dns entry example documentation (#3379)
* Added a quick-how-to guide for Delivery Service static dns entries
* Quality of life improvements to static dns entry forms
Also changes "View" in Delivery Service details pages' "More" dropdown
(except for "View Charts") to the more accurate "Manage".
* 'Fixed' docs compilation warnings due to Pygments not being able to handle missing HTTP reason phrases
* Fixed incorrect DNS names and bad example
* Changed example IP address to one that's reserved for documentation
* prefer 'record' to 'entry' (mostly)
* Rewording the '.. note'
* Changed example address 192.0.2.0 -> 192.0.2.1
* moved docs for static DNS on DSes from TO to TP
* reword opening statement
* Replaced s on required field labels
---
docs/source/admin/quick_howto/index.rst | 11 +--
docs/source/admin/quick_howto/static_dns.rst | 77 +++++++++++++++++++++
docs/source/admin/quick_howto/static_dns/00.png | Bin 0 -> 39724 bytes
docs/source/admin/quick_howto/static_dns/01.png | Bin 0 -> 37201 bytes
docs/source/admin/traffic_ops/using.rst | 9 ---
.../admin/traffic_portal/usingtrafficportal.rst | 5 ++
.../traffic_router/traffic_router_api.rst | 6 +-
.../form.deliveryService.DNS.tpl.html | 10 +--
.../form.deliveryService.HTTP.tpl.html | 10 +--
.../form.deliveryService.Steering.tpl.html | 8 +--
.../form.deliveryService.anyMap.tpl.html | 8 +--
.../form.deliveryServiceStaticDnsEntry.tpl.html | 26 +++----
12 files changed, 122 insertions(+), 48 deletions(-)
diff --git a/docs/source/admin/quick_howto/index.rst b/docs/source/admin/quick_howto/index.rst
index 171779d..01a46c8 100644
--- a/docs/source/admin/quick_howto/index.rst
+++ b/docs/source/admin/quick_howto/index.rst
@@ -20,12 +20,13 @@ Traffic Control is a complicated system, and documenting it is not trivial. Some
.. toctree::
- multi_site
- federations
- regionalgeo
anonymous_blocking
+ cachegroup_fallback
+ ciab
dnssec
ds_requests
+ federations
+ multi_site
+ regionalgeo
+ static_dns
steering
- ciab
- cachegroup_fallback
\ No newline at end of file
diff --git a/docs/source/admin/quick_howto/static_dns.rst b/docs/source/admin/quick_howto/static_dns.rst
new file mode 100644
index 0000000..6f6df8f
--- /dev/null
+++ b/docs/source/admin/quick_howto/static_dns.rst
@@ -0,0 +1,77 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _static-dns-qht:
+
+******************************
+Configuring Static DNS Entries
+******************************
+Static DNS records (historically "entries") can be configured within the DNS subdomain of a given :term:`Delivery Service`. In a typical scenario, the :term:`Delivery Service` will have DNS records automatically generated based on its "xml_id" and "routing name", and the name and subdomain of the CDN to which it belongs. For example, in the :ref:`ciab` default environment, the "demo1" :term:`Delivery Service` has an automatically generated DNS record for ``video.demo1.mycdn.ciab.test``. [...]
+
+.. note:: It's only possible to create static DNS records within a :term:`Delivery Service`'s subdomain. That is, one could not create an ``A`` record for ``foo.bar.mycdn.ciab.test`` on the :ref:`ciab` :term:`Delivery Service` "demo1", since "demo1"'s subdomain is ``demo1.mycdn.ciab.test``.
+
+.. seealso:: This guide covers how to set up static DNS records using Traffic Portal. It's also possible to do so directly using the :ref:`to-api` endpoint :ref:`to-api-staticdnsentries`.
+
+Example
+=======
+To set up the aforementioned rule, follow these steps.
+
+#. In Traffic Portal, expand the :ref:`tp-services` sidebar menu and select :guilabel:`Delivery Services`.
+#. From the now-displayed table of :term:`Delivery Service`\ s, select the desired one for static DNS record configuration.
+#. From the :guilabel:`More` drop-down menu, select :guilabel:`Static DNS Entries`. The displayed table will probably be empty.
+
+ .. figure:: static_dns/00.png
+ :alt: The static DNS entries table page
+ :align: center
+
+ The Static DNS Entries Table Page
+
+#. Click on the blue :guilabel:`+` button to add a new static DNS Entry
+#. Fill in all of the fields.
+
+ Host
+ This is the lowest-level DNS label that will be used in the DNS record. In the :ref:`ciab` scenario, for example, entering ``foo`` here will result in a full DNS name of ``foo.demo1.mycdn.ciab.test``.
+ Type
+ Indicates the type of DNS record that will be created. The available types are
+
+ * A
+ * AAAA
+ * CNAME
+ * TXT
+
+ TTL
+ The :abbr:`TTL (Time To Live)` of the DNS record, after which clients will be expected to re-request name resolution.
+ Address
+ The meaning of this field depends on the value of the "Type" field.
+
+ * If the "Type" is ``A``, this must be a valid IPv4 address
+ * If the "Type" is ``AAAA``, this must be a valid IPv6 address
+ * If the "Type" is ``CNAME``, this must be a valid DNS name - **not** an IP address at all
+ * If the "Type" is ``TXT``, no restrictions are placed on the content whatsoever
+
+ .. figure:: static_dns/01.png
+ :alt: An example static DNS entry form
+ :align: center
+
+ An Example Static DNS Entry Form
+
+#. Click on the green :guilabel:`Create` button to finalize the changes.
+#. At this point, although the static DNS record has been created, it will have no effect until a new CDN :term:`Snapshot` is taken. Once that is done (and enough time has passed for Traffic Router to poll for the changes), the new DNS record should be usable through the CDN's designated Traffic Router.
+
+ .. code-block:: console
+ :caption: Example DNS Query to Test a New Static DNS Entry within :ref:`ciab`
+
+ $ docker exec cdninabox_enroller_1 dig +noall +answer foo.demo1.mycdn.ciab.test
+ foo.demo1.mycdn.ciab.test. 42 IN A 192.0.2.1
diff --git a/docs/source/admin/quick_howto/static_dns/00.png b/docs/source/admin/quick_howto/static_dns/00.png
new file mode 100644
index 0000000..6773d8f
Binary files /dev/null and b/docs/source/admin/quick_howto/static_dns/00.png differ
diff --git a/docs/source/admin/quick_howto/static_dns/01.png b/docs/source/admin/quick_howto/static_dns/01.png
new file mode 100644
index 0000000..37b4b79
Binary files /dev/null and b/docs/source/admin/quick_howto/static_dns/01.png differ
diff --git a/docs/source/admin/traffic_ops/using.rst b/docs/source/admin/traffic_ops/using.rst
index 8fd38c4..20cdaf4 100644
--- a/docs/source/admin/traffic_ops/using.rst
+++ b/docs/source/admin/traffic_ops/using.rst
@@ -905,15 +905,6 @@ The **Order** entry defines the order in which the regular expressions get evalu
.. Note:: In most cases is is sufficient to have just one entry in this table that has a ``HOST_REGEXP`` Type, and Order ``0``. For the *movies* delivery service in the Kabletown CDN, the entry is simply single ``HOST_REGEXP`` set to ``.*\.movies\..*``. This will match every url that has a hostname that ends with ``movies.cdn1.kabletown.net``, since ``cdn1.kabletown.net`` is the Kabletown CDN's DNS domain.
.. index::
- Static DNS Entries
-
-.. _static-dns:
-
-Static DNS Entries
-------------------
-Static DNS entries allow you to create other names *under* the delivery service domain. You can enter any valid hostname, and create a CNAME, A or AAAA record for it by clicking the **Static DNS** button at the bottom of the delivery service details screen.
-
-.. index::
Server Assignments
.. _assign-edges:
diff --git a/docs/source/admin/traffic_portal/usingtrafficportal.rst b/docs/source/admin/traffic_portal/usingtrafficportal.rst
index 692b573..bfd883d 100644
--- a/docs/source/admin/traffic_portal/usingtrafficportal.rst
+++ b/docs/source/admin/traffic_portal/usingtrafficportal.rst
@@ -131,6 +131,8 @@ A table showing the results of the periodic :ref:`to-check-ext` that are run. Th
:Connections: Number of connections to this :term:`cache server` or :term:`Cache Group`
:MbpsOut: Data flow rate outward from the CDN (toward client) in Megabits per second
+.. _tp-services:
+
Services
========
:guilabel:`Services` groups the functionality to modify :term:`Delivery Service`\ s - for those users with the necessary permissions - or make Requests for such changes - for uses without necessary permissions.
@@ -195,6 +197,9 @@ This page contains a table displaying all :term:`Delivery Service`\ s visible to
- create, update and delete :term:`Delivery Service` regular expressions
- view and create :term:`Delivery Service` invalidate content jobs
- manage steering targets
+- view and manage static DNS records within a :term:`Delivery Service` subdomain
+
+ .. seealso:: :ref:`static-dns-qht`
Delivery Service Requests
-------------------------
diff --git a/docs/source/development/traffic_router/traffic_router_api.rst b/docs/source/development/traffic_router/traffic_router_api.rst
index ab11d63..bbf0378 100644
--- a/docs/source/development/traffic_router/traffic_router_api.rst
+++ b/docs/source/development/traffic_router/traffic_router_api.rst
@@ -501,7 +501,7 @@ Response Structure
.. code-block:: http
:caption: Response Example
- HTTP/1.1 200
+ HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 15 Feb 2019 22:06:53 GMT
@@ -541,7 +541,7 @@ Response Structure
.. code-block:: http
:caption: Response Example
- HTTP/1.1 200
+ HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 15 Feb 2019 22:12:38 GMT
@@ -572,4 +572,4 @@ Request Structure
Response Structure
------------------
-TBD
\ No newline at end of file
+TBD
diff --git a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.DNS.tpl.html b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.DNS.tpl.html
index b4b4a8e..257acab 100644
--- a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.DNS.tpl.html
+++ b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.DNS.tpl.html
@@ -53,11 +53,11 @@ under the License.
<li role="menuitem"><a ng-click="manageUrlSigKeys()">Manage URL Sig Keys</a></li>
<li role="menuitem"><a ng-click="manageUriSigningKeys()">Manage URI Signing Keys</a></li>
<hr class="divider"/>
- <li role="menuitem"><a ng-click="viewOrigins()">View Origins</a></li>
- <li role="menuitem"><a ng-click="viewServers()">View Servers</a></li>
- <li role="menuitem"><a ng-click="viewRegexes()">View Regexes</a></li>
- <li role="menuitem"><a ng-click="viewJobs()">View Invalidation Requests</a></li>
- <li role="menuitem"><a ng-click="viewStaticDnsEntries()">View Static DNS Entries</a></li>
+ <li role="menuitem"><a ng-click="viewOrigins()">Manage Origins</a></li>
+ <li role="menuitem"><a ng-click="viewServers()">Manage Servers</a></li>
+ <li role="menuitem"><a ng-click="viewRegexes()">Manage Regexes</a></li>
+ <li role="menuitem"><a ng-click="viewJobs()">Manage Invalidation Requests</a></li>
+ <li role="menuitem"><a ng-click="viewStaticDnsEntries()">Manage Static DNS Entries</a></li>
</ul>
</div>
</div>
diff --git a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.HTTP.tpl.html b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.HTTP.tpl.html
index 2a10d0f..82c0d5f 100644
--- a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.HTTP.tpl.html
+++ b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.HTTP.tpl.html
@@ -53,11 +53,11 @@ under the License.
<li role="menuitem"><a ng-click="manageUrlSigKeys()">Manage URL Sig Keys</a></li>
<li role="menuitem"><a ng-click="manageUriSigningKeys()">Manage URI Signing Keys</a></li>
<hr class="divider"/>
- <li role="menuitem"><a ng-click="viewOrigins()">View Origins</a></li>
- <li role="menuitem"><a ng-click="viewServers()">View Servers</a></li>
- <li role="menuitem"><a ng-click="viewRegexes()">View Regexes</a></li>
- <li role="menuitem"><a ng-click="viewJobs()">View Invalidation Requests</a></li>
- <li role="menuitem"><a ng-click="viewStaticDnsEntries()">View Static DNS Entries</a></li>
+ <li role="menuitem"><a ng-click="viewOrigins()">Manage Origins</a></li>
+ <li role="menuitem"><a ng-click="viewServers()">Manage Servers</a></li>
+ <li role="menuitem"><a ng-click="viewRegexes()">Manage Regexes</a></li>
+ <li role="menuitem"><a ng-click="viewJobs()">Manage Invalidation Requests</a></li>
+ <li role="menuitem"><a ng-click="viewStaticDnsEntries()">Manage Static DNS Entries</a></li>
</ul>
</div>
</div>
diff --git a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.Steering.tpl.html b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.Steering.tpl.html
index dc8cae3..52a7326 100644
--- a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.Steering.tpl.html
+++ b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.Steering.tpl.html
@@ -51,10 +51,10 @@ under the License.
<hr class="divider"/>
<li role="menuitem"><a ng-click="manageSslKeys()">Manage SSL Keys</a></li>
<hr class="divider"/>
- <li role="menuitem"><a ng-click="viewTargets()">View Targets</a></li>
- <li role="menuitem"><a ng-click="viewRegexes()">View Regexes</a></li>
- <li role="menuitem"><a ng-click="viewJobs()">View Invalidation Requests</a></li>
- <li role="menuitem"><a ng-click="viewStaticDnsEntries()">View Static DNS Entries</a></li>
+ <li role="menuitem"><a ng-click="viewTargets()">Manage Targets</a></li>
+ <li role="menuitem"><a ng-click="viewRegexes()">Manage Regexes</a></li>
+ <li role="menuitem"><a ng-click="viewJobs()">Manage Invalidation Requests</a></li>
+ <li role="menuitem"><a ng-click="viewStaticDnsEntries()">Manage Static DNS Entries</a></li>
</ul>
</div>
</div>
diff --git a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.anyMap.tpl.html b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.anyMap.tpl.html
index 9fadecd..94215c6 100644
--- a/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.anyMap.tpl.html
+++ b/traffic_portal/app/src/common/modules/form/deliveryService/form.deliveryService.anyMap.tpl.html
@@ -49,10 +49,10 @@ under the License.
<hr class="divider"/>
<li role="menuitem"><a ng-click="viewCharts()">View Charts</a></li>
<hr class="divider"/>
- <li role="menuitem"><a ng-click="viewServers()">View Servers</a></li>
- <li role="menuitem"><a ng-click="viewRegexes()">View Regexes</a></li>
- <li role="menuitem"><a ng-click="viewJobs()">View Invalidation Requests</a></li>
- <li role="menuitem"><a ng-click="viewStaticDnsEntries()">View Static DNS Entries</a></li>
+ <li role="menuitem"><a ng-click="viewServers()">Manage Servers</a></li>
+ <li role="menuitem"><a ng-click="viewRegexes()">Manage Regexes</a></li>
+ <li role="menuitem"><a ng-click="viewJobs()">Manage Invalidation Requests</a></li>
+ <li role="menuitem"><a ng-click="viewStaticDnsEntries()">Manage Static DNS Entries</a></li>
</ul>
</div>
</div>
diff --git a/traffic_portal/app/src/common/modules/form/deliveryServiceStaticDnsEntry/form.deliveryServiceStaticDnsEntry.tpl.html b/traffic_portal/app/src/common/modules/form/deliveryServiceStaticDnsEntry/form.deliveryServiceStaticDnsEntry.tpl.html
index 374a7cf..2519630 100644
--- a/traffic_portal/app/src/common/modules/form/deliveryServiceStaticDnsEntry/form.deliveryServiceStaticDnsEntry.tpl.html
+++ b/traffic_portal/app/src/common/modules/form/deliveryServiceStaticDnsEntry/form.deliveryServiceStaticDnsEntry.tpl.html
@@ -29,44 +29,44 @@ under the License.
</div>
<div class="x_content">
<br>
- <form name="dsStaticDnsEntryForm" class="form-horizontal form-label-left" novalidate>
+ <form name="dsStaticDnsEntryForm" class="form-horizontal form-label-left">
<div class="form-group" ng-class="{'has-error': hasError(dsStaticDnsEntryForm.host), 'has-feedback': hasError(dsStaticDnsEntryForm.host)}">
- <label class="control-label col-md-2 col-sm-2 col-xs-12">Host *</label>
+ <label for="host" class="control-label col-md-2 col-sm-2 col-xs-12">Host *</label>
<div class="col-md-10 col-sm-10 col-xs-12">
- <input name="host" type="text" class="form-control" ng-model="staticDnsEntry.host" required autofocus>
+ <input id="host" name="host" type="text" class="form-control" ng-model="staticDnsEntry.host" required autofocus>
<small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.host, 'required')">Required</small>
<span ng-show="hasError(dsStaticDnsEntryForm.host)" class="form-control-feedback"><i class="fa fa-times"></i></span>
</div>
</div>
<div class="form-group" ng-class="{'has-error': hasError(dsStaticDnsEntryForm.typeId), 'has-feedback': hasError(dsStaticDnsEntryForm.typeId)}">
- <label class="control-label col-md-2 col-sm-2 col-xs-12">Type *</label>
+ <label for="typeId" class="control-label col-md-2 col-sm-2 col-xs-12">Type *</label>
<div class="col-md-10 col-sm-10 col-xs-12">
- <select name="typeId" class="form-control" ng-model="staticDnsEntry.typeId" ng-options="type.id as type.name for type in types" required>
- <option value="">Select...</option>
+ <select id="typeId" name="typeId" class="form-control" ng-model="staticDnsEntry.typeId" ng-options="type.id as type.name for type in types" required>
+ <option disabled hidden value="">Select...</option>
</select>
<small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.typeId, 'required')">Required</small>
</div>
</div>
<div class="form-group" ng-class="{'has-error': hasError(dsStaticDnsEntryForm.ttl), 'has-feedback': hasError(dsStaticDnsEntryForm.ttl)}">
- <label class="control-label col-md-2 col-sm-2 col-xs-12">TTL *</label>
+ <label for="ttl" class="control-label col-md-2 col-sm-2 col-xs-12">TTL *</label>
<div class="col-md-10 col-sm-10 col-xs-12">
- <input name="ttl" type="number" class="form-control" ng-model="staticDnsEntry.ttl" ng-pattern="/^\d+$/" required autofocus>
- <small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.ttl, 'required')">Required Whole Number</small>
- <small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.ttl, 'pattern')">Whole Number</small>
+ <input id="ttl" name="ttl" type="number" class="form-control" ng-model="staticDnsEntry.ttl" min="0" step="1" required>
+ <small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.ttl, 'required')">Required</small>
+ <small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.ttl, 'step') || hasPropertyError(dsStaticDnsEntryForm.ttl, 'min')">Whole Number</small>
<span ng-show="hasError(dsStaticDnsEntryForm.ttl)" class="form-control-feedback"><i class="fa fa-times"></i></span>
</div>
</div>
<div class="form-group" ng-class="{'has-error': hasError(dsStaticDnsEntryForm.address), 'has-feedback': hasError(dsStaticDnsEntryForm.address)}">
- <label class="control-label col-md-2 col-sm-2 col-xs-12">Address *</label>
+ <label for="address" class="control-label col-md-2 col-sm-2 col-xs-12">Address *</label>
<div class="col-md-10 col-sm-10 col-xs-12">
- <input name="address" type="text" class="form-control" ng-model="staticDnsEntry.address" required autofocus>
+ <input id="address" name="address" type="text" class="form-control" ng-model="staticDnsEntry.address" required>
<small class="input-error" ng-show="hasPropertyError(dsStaticDnsEntryForm.address, 'required')">Required</small>
<span ng-show="hasError(dsStaticDnsEntryForm.address)" class="form-control-feedback"><i class="fa fa-times"></i></span>
</div>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-danger" ng-show="!settings.isNew" ng-click="confirmDelete(staticDnsEntry)">Delete</button>
- <button type="button" class="btn btn-success" ng-disabled="dsStaticDnsEntryForm.$pristine || dsStaticDnsEntryForm.$invalid" ng-click="save(deliveryService.id, staticDnsEntry)">{{settings.saveLabel}}</button>
+ <button class="btn btn-success" ng-disabled="dsStaticDnsEntryForm.$pristine || dsStaticDnsEntryForm.$invalid" ng-click="save(deliveryService.id, staticDnsEntry)">{{settings.saveLabel}}</button>
</div>
</form>
</div>