diff options
| -rw-r--r-- | docs/sections/dcaeservice_helm_template.rst | 73 | ||||
| -rw-r--r-- | docs/sections/tls_enablement.rst | 283 |
2 files changed, 12 insertions, 344 deletions
diff --git a/docs/sections/dcaeservice_helm_template.rst b/docs/sections/dcaeservice_helm_template.rst index b3dc29aa..60adee68 100644 --- a/docs/sections/dcaeservice_helm_template.rst +++ b/docs/sections/dcaeservice_helm_template.rst @@ -15,21 +15,17 @@ Kubernetes API to create the Kubernetes resources (including a Kubernetes Deployment and a Kubernetes Service) that make up a running instance of the microservice. -Beginning with the Honolulu release, DCAE is migrating to a new approach -for deploying DCAE microservices. Instead of using Cloudify with a -Cloudify blueprint for each microservice, DCAE will use Helm to deploy -microservices. Each microservice will have a Helm chart instead of a -Cloudify blueprint. In the Honolulu release, four DCAE microservices -(the VES and HV-VES collectors, the PNF registration handler, and the -TCA Gen2 analytics service) moved to Helm deployment. All four of these -are deployed “statically”–that is, they are deployed when DCAE is -installed and run continuously. +In the Honolulu release, DCAE began migrating to a new approach for +deploying DCAE microservices. Instead of using Cloudify with a +Cloudify blueprint for each microservice, DCAE began using Helm to +deploy microservices. This migration is now complete, and all +DCAE microservices have a Helm chart instead of a Cloudify blueprint. DCAE Service Templates - Introduction ------------------------------------- It would be possible to write a Helm chart for each microservice, each -completely unrelated. We are taking a different approach. We are +completely unrelated to the others. We are taking a different approach. We are providing shared Helm templates that (approximately) create the same Kubernetes resources that the Cloudify plugin created when it processed a blueprint. Creating a Helm chart for a microservice involves setting @@ -202,17 +198,6 @@ with keys and values as needed for the specific microservice. It will be converted to JSON before being pushed to Consul or mounted as a file. If not present, defaults to an empty object ({}). -*Note: Due to a bug in the Honolulu release (DCAEGEN2-2782), it is -necessary to supply an ``applicationConfig`` in the ``values.yaml`` for -a microservice even if the microservice does not have any configuration. -The workaround is to supply an empty configuration:* - -:: - - applicationConfig: {} - -*This is being fixed in the Istanbul release.* - **applicationEnv:** Microservice-specific environment variables to be @@ -306,7 +291,7 @@ external volumes will be set up for the microservice. **certDirectory:** Path to the directory in the microservice’s -container file system where TLS-certificate information from AAF should +container file system where TLS-certificate information from CMPv2 should be mounted. This is an optional field. When it is present, the dcaegen2-services-common deployment template will set up an initContainer that retrieves the certificate information into a shared @@ -319,16 +304,6 @@ Example: certDirectory: /etc/ves-hv/ssl -**tlsServer:** - -Boolean flag. If set to ``true``, the -dcaegen2-services-common deployment will configure the initContainer -described above to fetch a server certificate for the microservice. If -set to ``false``, the initContainer will fetch only a CA certificate for -the AAF certificate authority. ``tlsServer`` is optional. The value -defaults to ``false``. ``tlsServer`` is ignored if ``certDirectory`` is -not set. - **logDirectory:** Path to the directory where the microservice writes @@ -388,40 +363,6 @@ Example: dcaePolicySyncImage: onap/org.onap.dcaegen2.deployments.dcae-services-policy-sync:1.0.1 -**consulLoaderImage:** - -Name and tag of the consul loader image to be -used. Required. The consul loader image runs in an initContainer that -loads application configuration information into Consul. The image -repository is set using the OOM common -``repositoryGenerator.repository`` template. Normally this points to the -ONAP image repository, but it can be overridden on a global basis or a -per-chart basis. See the OOM documentation for more details. - -Example: - -:: - - consulLoaderImage: onap/org.onap.dcaegen2.deployments.consul-loader-container:1.1.0 - -**tlsImage:** - -Name and tag of the TLS initialization image to be used. -Required if the microservice is configured to act as a TLS client and/or -server using AAF certificates. The TLS initialization image runs in an -initContainer and pulls TLS certificate information from AAF and stores -it in a volume on the microservice’s pod. The image repository is set -using the OOM common ``repositoryGenerator.repository`` template. -Normally this points to the ONAP image repository, but it can be -overridden on a global basis or a per-chart basis. See the OOM -documentation for more details. - -Example: - -:: - - tlsImage: onap/org.onap.dcaegen2.deployments.tls-init-container:2.1.0 - **certProcessorImage:** Name and tag of the CMPv2 certificate diff --git a/docs/sections/tls_enablement.rst b/docs/sections/tls_enablement.rst index e5dc3d50..ed496f6e 100644 --- a/docs/sections/tls_enablement.rst +++ b/docs/sections/tls_enablement.rst @@ -5,282 +5,9 @@ TLS Support =========== -To comply with ONAP security requirement, all services exposing external API required TLS support using AAF generated certificates. DCAE Platform was updated in R3 to enable certificate distribution mechanism for services needing TLS support. For R6, we have moved from generating certificates manually to retrieving certificates from AAF at deployment time. +Beginning with the London release, ONAP is using a service mesh (Istio) to encrypt and authenticate traffic between ONAP components. In earlier releases, each component was responsible for protecting its HTTP interfaces with TLS, +using certificates generated by the (now obsolete) AAF component. -Solution overview ------------------ -1. Certificate setup: - - AAF requires setting up certificate details in AAF manually before a certificate is generated. - This step is currently done using a test AAF instance in POD25. - Required namespace, DCAE identity (dcae@dcae.onap.org), roles and Subject Alternative Names for all components are set in the test instance. - We use a single certificate for all DCAE components, with a long list of Subject Alternative Names (SANs). - - Current SAN listing:: - - bbs-event-processor, bbs-event-processor.onap, bbs-event-processor.onap.svc.cluster.local, config-binding-service, config-binding-service.onap, config-binding-service.onap.svc.cluster.local, dcae-cloudify-manager, dcae-cloudify-manager.onap, dcae-cloudify-manager.onap.svc.cluster.local, dcae-datafile-collector, dcae-datafile-collector.onap, dcae-datafile-collector.onap.svc.cluster.local, dcae-hv-ves-collector, dcae-hv-ves-collector.onap, dcae-hv-ves-collector.onap.svc.cluster.local, dcae-pm-mapper, dcae-pm-mapper.onap, dcae-pm-mapper.onap.svc.cluster.local, dcae-prh, dcae-prh.onap, dcae-prh.onap.svc.cluster.local, dcae-tca-analytics, dcae-tca-analytics.onap, dcae-tca-analytics.onap.svc.cluster.local, dcae-ves-collector, dcae-ves-collector.onap, dcae-ves-collector.onap.svc.cluster.local, deployment-handler, deployment-handler.onap, deployment-handler.onap.svc.cluster.local, holmes-engine-mgmt, holmes-engine-mgmt.onap, holmes-engine-mgmt.onap.svc.cluster.local, holmes-rule-mgmt, holmes-rules-mgmt.onap, holmes-rules-mgmt.onap.svc.cluster.local, inventory, inventory.onap, inventory.onap.svc.cluster.local, policy-handler, policy-handler.onap, policy-handler.onap.svc.cluster.local - -2. Certificate generation and retrieval: - - When a DCAE component that needs a TLS certificate is launched, a Kubernetes init container runs before the main - component container is launched. The init container contacts the AAF certificate manager server. The AAF certificate - management server generates a certificate based on the information previously set up in step 1 above and sends the certificate - (in several formats) along with keys and passwords to the init container. The init container renames the files to conform to - DCAE naming conventions and creates some additional formats. It stores the results into a volume that's shared with - the main component container. - - DCAE platform components are deployed via ONAP OOM. The Helm chart for each deployment includes the init container - and sets up the shared volume. - - DCAE service components (sometimes called "microservices") are deployed via Cloudify using blueprints. This is described - in more detail in the next section. - -3. Plugin and Blueprint: - The blueprint for a component that needs a TLS certificate needs to include the node property called "tls_info" in - the node properties for the component. The property is a dictionary with two elements: - - * A boolean (``use_tls``) that indicates whether the component uses TLS. - * A string (``cert_directory``) that indicates where the component expects to find certificate artifacts. - - Example - -.. code-block:: yaml - - tls_info: - cert_directory: '/opt/app/dh/etc/cert' - use_tls: true - -(Note that the ``cert_directory`` value does not include a trailing ``/``.) - -For this example the certificates are mounted into ``/opt/app/dh/etc/cert`` directory within the container. - - During deployment Kubernetes plugin (referenced in blueprint) will check if the ``tls_info`` property is set and ``use_tls`` is set to true, then the plugin will add some elements to the Kubernetes Deployment for the component: - * A Kubernetes volume (``tls-info``) that will hold the certificate artifacts - * A Kubernetes initContainer (``tls-init``) - * A Kubernetes volumeMount for the initContainer that mounts the ``tls-info`` volume at ``/opt/app/osaaf``. - * A Kubernetes volumeMount for the main container that mounts the ``tls-info`` volume at the mount point specified in the ``cert_directory`` property. - -Service components that act as HTTPS clients only need access to the root CA certificate used by AAF. For R6, such -components should set up a tls_info property as described above. See below for a note about an alternative approach -that is available in R6 but is not currently being used. - -4. Certificate artifacts - - The certificate directory mounted on the container will include the following files: - * ``cert.jks``: A Java keystore containing the DCAE certificate. - * ``jks.pass``: A text file with a single line that contains the password for the ``cert.jks`` keystore. - * ``trust.jks``: A Java truststore containing the AAF CA certificate. (Needed by clients that access TLS-protected servers.) - * ``trust.pass``: A text file with a single line that contains the password for the ``trust.jks`` keystore. - * ``cert.p12``: The DCAE certificate and private key packaged in PKCS12 form. - * ``p12.pass``: A text file with a single line that contains the password for ``cert.p12`` file. - * ``cert.pem``: The DCAE certificate concatenated with the intermediate CA certficate from AAF, in PEM form. - * ``key.pem``: The private key for the DCAE certificate. The key is not encrypted. - * ``cacert.pem``: The AAF CA certificate, in PEM form. (Needed by clients that access TLS-protected servers.) - -5. Alternative for getting CA certificate only - - The certificates generated by AAF are signed by AAF, not by a recognized certificate authority (CA). If a component acts - as a client and makes an HTTPS request to another component, it will not be able to validate the other component's - server certificate because it will not recognize the CA. Most HTTPS client library software will raise an error - and drop the connection. To prevent this, the client component needs to have a copy of the AAF CA certificate. - As noted in section 3 above, one way to do this is to set up the tls_info property as described in section 3 above. - - There are alternatives. In R6, two versions of the DCAE k8splugin are available: version 1.7.2 and version 2.0.0. - They behave differently with respect to setting up the CA certs. - - * k8splugin version 1.7.2 will automatically mount the CA certificate, in PEM format, at ``/opt/dcae/cacert/cacert.pem``. - It is not necessary to add anything to the blueprint. To get the CA certificate in PEM format in a different directory, - add a ``tls_info`` property to the blueprint, set ``use_tls`` to ``false``, and set ``cert_directory`` to the directory - where the CA cert is needed. For example: - - .. code-block:: yaml - - tls_info: - cert_directory: '/opt/app/certs' - use_tls: false - - For this example, the CA certificate would be mounted at ``/opt/app/certs/cacert.pem``. - - k8splugin version 1.7.2 uses a configmap, rather than an init container, to supply the CA certificate. - - * k8splugin version 2.0.0 will automatically mount the CA certificate, in PEM and JKS formats, in the directory ``/opt/dcae/cacert``. - It is not necessary to add anything to the blueprint. To get the CA certificates in a different directory, add a ``tls_info`` property to the blueprint, set ``use_tls`` to ``false``, and set ``cert_directory`` to the directory - where the CA certs are needed. Whatever directory is used, the following files will be available: - - * ``trust.jks``: A Java truststore containing the AAF CA certificate. (Needed by clients that access TLS-protected servers.) - * ``trust.pass``: A text file with a single line that contains the password for the ``trust.jks`` keystore. - * ``cacert.pem``: The AAF CA certificate, in PEM form. (Needed by clients that access TLS-protected servers.) - - k8splugin version 2.0.0 uses an init container to supply the CA certificates. - -External TLS Support - using Cloudify -------------------------------------- - -External TLS support was introduced in order to integrate DCAE with CertService to acquire operator certificates meant to protect external traffic between DCAE's components (VES collector, HV-VES, RestConf collector and DFC) and xNFs. For that reason K8s plugin which creates K8s resources from Cloudify blueprints was enhanced with new TLS properties support. New TLS properties are meant to control CertService's client call in init containers section and environment variables which are passed to it. - -This external TLS support doesn't influence ONAP internal traffic which is protected by certificates issued by AAF's CertMan. External TLS Support was introduced in k8splugin 3.1.0. - -From k8splugin 3.4.1 when external TLS is enabled (use_external_tls=true), keystore contains only certificate from CMPv2 server. Keystore issued by CertMan has appended .bak extension and is not used. - -1. Certificate setup: - - To create certificate artifacts, OOM CertService must obtain the certificate details. Common name and list of Subject Alternative Names (SANs) are set in blueprint as described in step 3. - The following parameters with default values are stored in OOM in k8splugin configuration file (k8splugin.json) in group ``external_cert``: - - * A string ``image_tag`` that indicates CertService client image name and version - * A string ``request_url`` that indicates URL to Cert Service API - * A string ``timeout`` that indicates request timeout. - * A string ``country`` that indicates country name in ISO 3166-1 alpha-2 format, for which certificate will be created - * A string ``organization`` that indicates organization name, for which certificate will be created. - * A string ``state`` that indicates state name, for which certificate will be created. - * A string ``organizational_unit`` that indicates organizational unit name, for which certificate will be created. - * A string ``location`` that indicates location name, for which certificate will be created. - * A string ``keystore_password`` that indicates keystore password. - * A string ``truststore_password`` that indicates truststore password. - - Group ``external_cert`` from k8splugin.json with default values: - - .. code-block:: JSON - - { - "image_tag": "nexus3.onap.org:10001/onap/org.onap.oom.platform.certservice.oom-certservice-client:$VERSION", - "request_url": "https://oom-cert-service:8443/v1/certificate/", - "timeout": "30000", - "country": "US", - "organization": "Linux-Foundation", - "state": "California", - "organizational_unit": "ONAP", - "location": "San-Francisco", - "keystore_password": "secret", - "truststore_password": "secret" - } - - - Parameters configured in k8splugin are propagated via Helm Charts to Kubernetes ConfigMap and finally they are transfered to Consul. - Blueprint, during start of execution, reads k8splugin.json configuration from Consul and applies it. - -2. Certificate generation and retrieval: - - When a DCAE component that needs an external TLS certificate is launched, a Kubernetes init container runs before the main - component container is launched. The init container contacts the OOM CertService. - - DCAE service components (sometimes called "microservices") are deployed via Cloudify using blueprints. This is described - in more detail in the next section. - -3. Plugin and Blueprint: - The blueprint for a component that needs an external TLS certificate needs to include the node property called "external_cert" in - the node properties for the component. The property is a dictionary with following elements: - - * A boolean (``use_external_tls``) that indicates whether the component uses TLS in external traffic. - * A string (``external_cert_directory``) that indicates where the component expects to find operator certificate and trusted certs. - * A string (``ca_name``) that indicates name of Certificate Authority configured on CertService side (in cmpServers.json). - * A string (``output_type``) that indicates certificate output type. - * A dictionary (``external_certificate_parameters``) with two elements: - * A string (``common_name``) that indicates common name which should be present in certificate. Specific for every blueprint (e.g. dcae-ves-collector for VES). - * A string (``sans``) that indicates list of Subject Alternative Names (SANs) which should be present in certificate. Delimiter - , Should contain common_name value and other FQDNs under which given component is accessible. The following SANs types are supported: DNS names, IPs, URIs, emails. - - As a final step of the plugin the generated CMPv2 truststore entries will be appended to AAF CA truststore (see certificate artifacts below). - - Example - - .. code-block:: yaml - - external_cert: - external_cert_directory: /opt/app/dcae-certificate/ - use_external_tls: true - ca_name: "RA" - cert_type: "P12" - external_certificate_parameters: - common_name: "simpledemo.onap.org" - sans: "simpledemo.onap.org,ves.simpledemo.onap.org,ves.onap.org" - - For this example the certificates are mounted into ``/opt/app/dcae-certificate/external`` directory within the container. - - During deployment Kubernetes plugin (referenced in blueprint) will check if the ``external_cert`` property is set and ``use_external_tls`` is set to true, then the plugin will add some elements to the Kubernetes Deployment for the component: - * A Kubernetes volume (``tls-volume``) that will hold the certificate artifacts - * A Kubernetes initContainer (``cert-service-client``) - * A Kubernetes volumeMount for the initContainer that mounts the ``tls-volume`` volume at ``/etc/onap/oom/certservice/certs/``. - * A Kubernetes volumeMount for the main container that mounts the ``tls-info`` volume at the mount point specified in the ``external_cert_directory`` property. - - Kurbernetes volumeMount tls-info is shared with TLS init container for internal traffic. - -4. Certificate artifacts - - The certificate directory mounted on the container will include the following: - * Directory ``external`` with files: - * ``keystore.p12``: A keystore containing the operator certificate. - * ``keystore.pass``: A text file with a single line that contains the password for the ``keystore.p12`` keystore. - * ``truststore.p12``: A truststore containing the operator certificate. (Needed by clients that access TLS-protected servers in external traffic.) - * ``truststore.pass``: A text file with a single line that contains the password for the ``truststore.p12`` keystore. - * ``trust.jks``: A file with the AAF CA certificate and CMPv2 certificate with private key packaged in Java form. - * ``trust.jks.bak``: The (original) file with the AAF CA certificate only. - * ``trust.pass``: A text file with a single line that contains the password for ``trust.jks`` and ``trust.jks.bak`` file. - * ``cacert.pem``: The AAF CA certificate, in PEM form. - -.. _external-tls-helm: - -External TLS Support - Helm based deployment --------------------------------------------- - -CMPv2 certificates can be enabled and configured via helm values. The feature is switched on only when: - * ``global.cmpv2Enabled`` flag is set to true - * ``certDirectory`` directory where TLS certs should be stored is set (in a specific component) - * flag ``useCmpv2Certificates`` is set to true (in a specific component) - -Default values for certificates are defined in ``global.certificate.default`` and can be overriden during onap installation process. - - .. code-block:: yaml - - global: - certificate: - default: - renewBefore: 720h #30 days - duration: 8760h #365 days - subject: - organization: "Linux-Foundation" - country: "US" - locality: "San-Francisco" - province: "California" - organizationalUnit: "ONAP" - issuer: - group: certmanager.onap.org - kind: CMPv2Issuer - name: cmpv2-issuer-onap - -CMPv2 settings can be changed in Helm values. - * ``mountPath`` - the directory within the container where certificates should be mounted - * ``commonName`` - indicates common name which should be present in certificate - * ``dnsNames`` - list of DNS names which should be present in certificate - * ``ipAddresses`` - list of IP addresses which should be present in certificate - * ``uris`` - list of uris which should be present in certificate - * ``emailAddresses`` - list of email addresses which should be present in certificate - * ``outputType`` - indicates certificate output type (jks or p12) - - .. code-block:: yaml - - certificates: - - mountPath: <PATH> - commonName: <COMMON-NAME> - dnsNames: - - <DNS-NAME-1> - - <DNS-NAME-2> - ... - ipAddresses: - ... - uris: - ... - emailAddresses: - ... - keystore: - outputType: - - <OUTPUT-TYPE> - passwordSecretRef: - name: <SECRET-NAME> - key: <PASSWORD-KEY> - create: <SHOULD-CREATE> - -The values can be changed by upgrading a component with modified values, eg. - - .. code-block:: bash - - helm -n onap upgrade <deploymant name> --values <path to updated values> +Some DCAE components offer HTTP interfaces to clients outside the ONAP Kubernetes cluster. In earlier releases, ONAP offered a mechanism allowing components to obtain +TLS certificates from an external source using the CMPv2 protocol. (See `these design notes <https://wiki.onap.org/display/DW/DCAE+CertService+integration>`_ for details on how that approach worked in conjunction with AAF.) +Beginning with the London release, external HTTP interfaces should be exposed via the Istio Gateway. The gateway can terminate TLS and can be configured with the necessary certificates. |