Recommend using conditionals for TLS-everywhere

The documentation used to recommend having a nested template; however,
due to issues with nested stack limits and optimizations, several
commits changed the current services to use conditionals instead [1].

This patch reflects this change by recommending deployers to use
conditionals.

[1] https://review.openstack.org/#/q/status:merged+project:openstack/tripleo-heat-templates+branch:master+topic:conditional-instead-of-stack

Change-Id: I21e23e33faaeb8c4a212f3d450e80c7594f61b3a

doc/source/developer/tht_walkthrough/tls_for_services.rst

@@ -423,59 +423,69 @@ you.
 
 In `tripleo-heat-templates`_ we'll need to specify the specs for doing the
 certificate request, and we'll need to get the appropriate information to
-generate a service principal. In order to make this composable, one usually
+generate a service principal. To make this optional, you should add the
-creates another template where this is done, this template is initialized to
+following to your service's base template::
-``OS::Heat::None`` and is only defined when internal TLS is enabled.
-
-This would be a template that we could use for this::
-
-    heat_template_version: ocata
-
-    description: >
-      My Service configurations for using TLS via certmonger.
 
     parameters:
-      ServiceNetMap:
+      ...
-        default: {}
+      EnableInternalTLS:
-        description: Mapping of service_name -> network name. Typically set
+        type: boolean
-                     via parameter_defaults in the resource registry.  This
+        default: false
-                     mapping overrides those in ServiceNetMapDefaults.
-        type: json
-      # The following parameters are not needed by the template but are
-      # required to pass the pep8 tests
-      DefaultPasswords:
-        default: {}
-        type: json
-      EndpointMap:
-        default: {}
-        description: Mapping of service endpoint -> protocol. Typically set
-                     via parameter_defaults in the resource registry.
-        type: json
 
-    outputs:
+    conditions:
-      role_data:
+
-        description: My Service configurations for using TLS via certmonger.
+      internal_tls_enabled: {equals: [{get_param: EnableInternalTLS}, true]}
-        value:
+      ...
-          service_name: my_service_internal_tls_certmonger
+    ...
-          config_settings:
+
-            generate_service_certificates: true
+* ``EnableInternalTLS`` is a parameter that's passed via ``parameter_defaults``
-            my_service_certificate_specs:
+  which tells the templates that we want to use TLS in the internal network.
-              service_certificate: '/etc/pki/tls/certs/my_service.crt'
+
-              service_key: '/etc/pki/tls/private/my_service.key'
+* ``internal_tls_enabled`` is a condition that we'll furtherly use to add the
-              hostname:
+  relevant bits to the output.
-                str_replace:
+
-                  template: "%{hiera('fqdn_NETWORK')}"
+The next thing to do is to add the certificate specs, the relevant hieradata
-                  params:
+and the required metadata to the output. In the ``roles_data`` output, lets
-                    NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
+modify the ``config_settings`` to add what we need::
-              principal:
+
-                str_replace:
+      config_settings:
-                  template: "myservice/%{hiera('fqdn_NETWORK')}"
+        map_merge:
-                  params:
+          -
-                    NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
+            # The regular hieradata for your service goes here.
-          metadata_settings:
+            ...
-            - service: myservice
+          -
+            if:
+            - internal_tls_enabled
+            - generate_service_certificates: true
+              my_service_certificate_specs:
+                service_certificate: '/etc/pki/tls/certs/my_service.crt'
+                service_key: '/etc/pki/tls/private/my_service.key'
+                hostname:
+                  str_replace:
+                    template: "%{hiera('fqdn_NETWORK')}"
+                    params:
+                      NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
+                principal:
+                  str_replace:
+                    template: "my_service/%{hiera('fqdn_NETWORK')}"
+                    params:
+                      NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
+            - {}
+      ...
+      metadata_settings:
+        if:
+          - internal_tls_enabled
+          -
+            - service: my_service
               network: {get_param: [ServiceNetMap, MyServiceNetwork]}
               type: node
+          - null
+
+* The conditional mentioned above is used in the ``config_settings``. So, if
+  ``internal_tls_enabled`` evaluates to ``true``, the hieradata necessary to
+  enable TLS in the internal network for your service will be added. Else, we
+  output ``{}``, which won't affect the ``map_merge`` and won't add anything
+  to the regular hieradata for your service.
 
 * For this case, we are only requesting one certificate for the service.
 
@@ -490,7 +500,7 @@ This would be a template that we could use for this::
   network and if used under the ``config_settings`` section, it will be
   replaced by the actual IP. Else, it will just be the network name.
 
-* tripleo-heat-templates generates automatically hieradata that contains the
+* tripleo-heat-templates automatically generates hieradata that contains the
   different network-dependant hostnames. They keys are in the following
   format::
 
@@ -539,32 +549,27 @@ This would be a template that we could use for this::
     in the :ref:`internal-tls-for-your-service` for the SANs.
 
   Note that this is a list, which can be useful if we'll be creating several
-  service principals (which is not the case for our example).
+  service principals (which is not the case for our example). Also, if
+  ``internal_tls_enabled`` evaluates to ``false``, we then output ``null``.
+
+* Remember to set any relevant flags or parameters that your service might
+  need as hieradata in ``config_settings``. These might be things that
+  explicitly enable TLS such as flags or paths. But these details depend on the
+  puppet module that deploys your service.
 
 .. note:: **VIP-based hostname case**
 
    If your service requires the certificate to contain a VIP-based hostname, as
    is the case for MariaDB. It would instead look like the following::
 
-       config_settings:
+      metadata_settings:
-         generate_service_certificates: true
+        if:
-         my_service_certificate_specs:
+          - internal_tls_enabled
-           service_certificate: '/etc/pki/tls/certs/my_service.crt'
+          -
-           service_key: '/etc/pki/tls/private/my_service.key'
+            - service: my_service
-           hostname:
+              network: {get_param: [ServiceNetMap, MyServiceNetwork]}
-             str_replace:
+              type: vip
-               template: "%{hiera('cloud_name_NETWORK')}"
+          - null
-               params:
-                 NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
-           principal:
-             str_replace:
-               template: "my_service/%{hiera('cloud_name_NETWORK')}"
-               params:
-                 NETWORK: {get_param: [ServiceNetMap, MyServiceNetwork]}
-       metadata_settings:
-         - service: my_service
-           network: {get_param: [ServiceNetMap, MyServiceNetwork]}
-           type: vip
 
    * One can get the hostname for the VIP in a similar fashion as we got the
      hostname for the node. The VIP hostnames are also network based, and one
@@ -574,56 +579,6 @@ This would be a template that we could use for this::
 
    * The ``type`` in the ``metadata_settings`` entry is ``vip``.
 
-Now that we have template, lets add it to the default resource registry in
-**overcloud-resource-registry-puppet.j2.yaml**::
-
-    OS::TripleO::Services::MyServiceTLS: OS::Heat::None
-
-And add the override to the **enable-internal-tls.yaml** enable this when we
-deploy TLS everywhere::
-
-    resource_registry:
-      OS::TripleO::Services::MyServiceTLS: ../puppet/services/my-service-internal-tls-certmonger.yaml
-
-We can now use it in our service's base template. So we need to add the
-following::
-
-    parameters:
-      ...
-      EnableInternalTLS:
-        type: boolean
-        default: false
-
-    resources:
-      ...
-      MyServiceTLS:
-        type: OS::TripleO::Services::MyServiceTLS
-        properties:
-          ServiceNetMap: {get_param: ServiceNetMap}
-          DefaultPasswords: {get_param: DefaultPasswords}
-          EndpointMap: {get_param: EndpointMap}
-      ...
-
-* ``EnableInternalTLS`` is a parameter that's passed via ``parameter_defaults``
-  which tells the templates that we want to use TLS in the internal network.
-
-* ``MyServiceTLS`` is a resource where we'll get the ``config_settings`` which
-  contain the certificate specs, and the ``metadata_settings`` which contain
-  the entries to generate the kerberos principal. Note that the type has to
-  match what we set in the resource registry. We should make sure that we
-  combine our service's hieradata with the hieradata coming from this resource
-  by doing a ``map_merge`` with the ``config_settings``::
-
-      ...
-      config_settings:
-        map_merge:
-          - get_attr: [MyServiceTLS, role_data, config_settings]
-          - # Here goes our service's metadata
-            ...
-
-Remember to set any relevant flags or parameters that your service might
-need to be configured with TLS.
-
 In `puppet-tripleo`_ We'll create a class that does the actual certificate
 request and add it to the resource that gets the certificates for all the
 services.