7 Migrating to OCCM Managed Certificates

Caution:

  • It is expected that there will be downtime when the services are migrated to use the new certificates generated by the OCCM. The amount of downtime will depend on the method of migration performed as described below.
  • This procedure is applicable when certificates are being migrated within the same release.
  • Consumer Adapter certificate migration is not supported. Hence, after certificate migration, make sure to delete and recreate all the Data Feeds with the same name and select "Resume from point of failure" in the "Handle Failure" page.

This section provides information on how to migrate the certificates initially created by following the section "Configuring SSL or TLS Certificates" during OCNADD installation.

There are two methods of migrating OCNADD to use certificates created by OCCM:

  1. Uninstalling and Reinstalling the Helm Charts: No configuration, or the existing data will be lost. Expected downtime will be equal to the sum of time taken to uninstall the worker group, the time taken to install the worker group, and the time taken to create all worker group certificates.
  2. Creating Certificates Manually and Upgrading the Helm Charts: It is essential that certificates are created before attempting an upgrade. Expected downtime will be equal to the sum of time taken to upgrade the worker group, the time taken to upgrade the consumer adapter and correlation, and the time taken for the Kafka-broker and Zookeeper to stabilize.

On average, creating certificates manually and upgrading OCNADD will result in more downtime. Downtime can be expected only after uninstalling the worker group or after upgrading the worker group. Untouched worker groups can accept traffic, provided the producer NF still trusts the Kafka-broker certificates and/or its issuer.

7.1 Uninstalling and Reinstalling the Helm Charts

  1. Follow the steps to create secrets for OCCM for each Management and Worker group namespace as specified in the OCCM Prerequisites for Installing OCNADD section.
  2. Uninstall the Management group Helm chart:
    helm uninstall <management-release-name> --namespace <management-group-namespace>
    For example:
    helm uninstall ocnadd-mgmt --namespace dd-mgmt-group
  3. Install the Management group using the newer release Helm charts with OCCM enabled. Refer to the Helm Parameter Configuration for OCCM section for a description of the Helm parameters required for enabling OCCM:
    helm install <management-release-name> -f ocnadd-custom-values-<mgmt-group>.yaml --namespace <management-group-namespace> <helm_chart>
    For example:
    helm install ocnadd-mgmt -f ocnadd-custom-values-mgmt-group.yaml --namespace dd-mgmt-group ocnadd_mgmt

    Note:

    The Admin service restart is expected until the Worker group certificate migrations are completed.
  4. Uninstall the Worker group Helm chart of the older release:
    helm uninstall <worker-group-release-name> --namespace <worker-group-namespace>
    For example:
    helm uninstall ocnadd-wg1 --namespace dd-worker-group1
  5. Install the Worker group using the newer release Helm charts with OCCM enabled:
    helm install <worker-group-release-name> -f ocnadd-custom-values-<wg-group>.yaml --namespace <worker-group-namespace> <helm_chart>
    For example:
    helm install ocnadd-wg1 -f ocnadd-custom-values-wg1-group.yaml --namespace dd-worker-group1 ocnadd_wg1
  6. Update the Worker group namespace in global.env.admin.OCNADD_UPGRADE_WG_NS of the Management group custom-values.yaml file:
    global:
  env:
    admin:
      OCNADD_UPGRADE_WG_NS: ocnadd-wg-1         # Where ocnadd-wg-1 is the namespace of the worker group service
  7. Perform the Helm upgrade using the Management group charts:
    helm upgrade <management-group-release-name> -f <management-group-custom-values> -n <management-group-ns> <ocnadd-helm-chart-location> --set global.env.admin.OCNADD_INGRESS_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_CORR_UPGRADE_ENABLE=true,global.env.admin.OCNADD_STORAGE_ADAPTER_UPGRADE_ENABLE=true
    For example:
    helm upgrade ocnadd-mgmt -f ocnadd-custom-values-mgmt-group.yaml -n dd-mgmt-group ocnadd_mgmt --set global.env.admin.OCNADD_INGRESS_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_CORR_UPGRADE_ENABLE=true,global.env.admin.OCNADD_STORAGE_ADAPTER_UPGRADE_ENABLE=true
  8. Now, delete and re-create all the Data Feeds with the same name and select "Resume from point of failure" in the "Handle Failure" page.
  9. If multiple Worker groups are present, repeat steps 4 to 7 for each Worker group.

7.2 Manually Creating Certificates for OCNADD and Upgrading the Helm Charts

To manually create certificates for OCNADD, follow these steps:

  1. Follow the steps to create secrets for OCCM for each management and worker group namespace as specified in the OCCM Prerequisites for Installing OCNADD section.
  2. Manually create certificates for each service using OCCM either through the UI or using the REST API as per the instructions given in the Oracle Communication Certificate Manager User Guide. And for more details on the certificates, see OCNADD Certificates Detail for OCCM section below.
  3. Enable the OCCM based certificate management in the Management and Worker group custom-values. For descriptions of the Helm parameters required for enabling OCCM, see Helm Parameter Configuration for OCCM.
  4. Upgrade the Management group helm chart:
    helm upgrade <management-release-name> -f ocnadd-custom-values-<mgmt-group>.yaml --namespace <management-group-namespace> <helm_chart>
    For example:
    helm upgrade ocnadd-mgmt -f ocnadd-custom-values-mgmt-group.yaml --namespace dd-mgmt-group ocnadd_mgmt

    Note:

    The Admin service restart is expected until the Worker group certificate migrations are completed.
  5. Upgrade the Worker group helm chart:
    helm upgrade <worker-group-release-name> -f ocnadd-custom-values-<wg-group>.yaml --namespace <worker-group-namespace> <helm_chart>
    For example:
    helm upgrade ocnadd-wg1 -f ocnadd-custom-values-wg1-group.yaml --namespace dd-worker-group1 ocnadd_wg1
  6. Update the Worker group namespace in global.env.admin.OCNADD_UPGRADE_WG_NS of the Manamgment group custom-values.yaml file:
    global:
  env:
    admin:
      OCNADD_UPGRADE_WG_NS: dd-worker-group1                                  # Where dd-worker-group1 is the namespace of the worker group service
  7. Perform helm upgrade using the Management group charts:
    helm upgrade <management-group-release-name> -f <management-group-custom-values> -n <management-group-ns> <ocnadd-helm-chart-location> --set global.env.admin.OCNADD_INGRESS_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_CORR_UPGRADE_ENABLE=true,global.env.admin.OCNADD_STORAGE_ADAPTER_UPGRADE_ENABLE=true
    For example:
    helm upgrade ocnadd-mgmt -f ocnadd-custom-values-mgmt-group.yaml -n dd-mgmt-group ocnadd_mgmt --set global.env.admin.OCNADD_INGRESS_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_ADAPTER_UPGRADE_ENABLE=true,global.env.admin.OCNADD_CORR_UPGRADE_ENABLE=true,global.env.admin.OCNADD_STORAGE_ADAPTER_UPGRADE_ENABLE=true
  8. Now, delete and re-create all the Data Feeds with the same name and select "Resume from point of failure" in the "Handle Failure" page.
  9. If multiple Worker groups are present, repeat steps 5 to 7 for each Worker group.

OCNADD Certificates Detail for OCCM

This section provides information of the certificate details required for OCNADD

When intraTLS is enabled for OCNADD, every service requires two sets of certificate and private key pairs: one for server communications and another for client communications. The server and client certificates are created in OCCM using the following templates:

  • client_req.json
    {
"name": "<SERVICE>-SECRET-CLIENT-<NAMESPACE>",
     "lcmType": "AUTOMATIC",
     "certType": "OTHER",
     "renewBefore": "<RENEW_BEFORE>",
     "certPurpose": "OCNADD <SERVICE> SECRET",
     "issuer": "<ISSUER>",
     "privateKey": {
         "keyAlgo": "RSA",
         "keySize": "KEYSIZE_2048",
         "keyEncoding": "PEM",
         "ecCurve":"",
         "privateKeyK8sSecretOut": {
             "namespace": "<NAMESPACE>",
             "name": "<CN>-secret-client",
             "key": "<CN>-clientprivatekey.pem"
     }
     },
    "csr": {
         "extendedKeyUsage": {
             "critical" : true,
             "extendedKeyUsageValues" : [
                 "CLIENT_AUTH",
                 "SERVER_AUTH"
         ]
         },
        "keyUsage": {
             "critical" : true,
             "keyUsageValues" : [
           "DIGITAL_SIGNATURE",
           "KEY_ENCIPHERMENT"
        ]

    },
         "basicConstraints": {
             "critical" : true,
             "basicConstraintsValue" : "END_ENTITY"
         },
         "subject": {
             "country": "<COUNTRY>",
             "state": "<STATE>",
             "location": "<LOCATION>",
             "organization": "<ORG>",
             "organizationUnit": "<OU>",
             "commonName": "<CN>"
         },
         "days": "<DAYS>",
         "subjectAltName": {
             "critical" : true,
             "ipAddress": [],
             "dns": [
                "<CN>",
                "<CN>.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "<CN>.<NAMESPACE>"
            ],
             "uriIdUrn": [],
             "uriIdApiRoot": [
             ]
         },
      "certK8sSecretOut": {
         "namespace": "<NAMESPACE>",
         "name": "<CN>-secret-client",
         "key": "<CN>-clientcert.pem"
     },
     "certChainK8sSecretOut": {
         "namespace": "",
         "name": "",
         "key": ""
     }
     },

     "caBundleK8sSecretIn": {
         "namespace": "",
         "name": "",
         "key": ""
     },

     "nf": "OCNADD-<SERVICE>",
     "overrideSecret": true
 }
  • server_req.json
    {
"name": "<SERVICE>-SECRET-SERVER-<NAMESPACE>",
     "lcmType": "AUTOMATIC",
     "certType": "OTHER",
     "renewBefore": "<RENEW_BEFORE>",
     "certPurpose": "OCNADD <SERVICE> SECRET",
     "issuer": "<ISSUER>",
     "privateKey": {
         "keyAlgo": "RSA",
         "keySize": "KEYSIZE_2048",
         "keyEncoding": "PEM",
         "ecCurve":"",
         "privateKeyK8sSecretOut": {
             "namespace": "<NAMESPACE>",
             "name": "<CN>-secret-server",
             "key": "<CN>-serverprivatekey.pem"
     }
     },
    "csr": {
         "extendedKeyUsage": {
             "critical" : true,
             "extendedKeyUsageValues" : [
                 "CLIENT_AUTH",
                 "SERVER_AUTH"
         ]
         },
        "keyUsage": {
             "critical" : true,
             "keyUsageValues" : [
           "DIGITAL_SIGNATURE",
           "KEY_ENCIPHERMENT"
        ]

    },
         "basicConstraints": {
             "critical" : true,
             "basicConstraintsValue" : "END_ENTITY"
         },
         "subject": {
             "country": "<COUNTRY>",
             "state": "<STATE>",
             "location": "<LOCATION>",
             "organization": "<ORG>",
             "organizationUnit": "<OU>",
             "commonName": "<CN>"
         },
         "days": "<DAYS>",
         "subjectAltName": {
             "critical" : true,
             "ipAddress": [],
             "dns": [
                "<CN>",
                "<CN>.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "<CN>.<NAMESPACE>"
            ],
             "uriIdUrn": [],
             "uriIdApiRoot": [
             ]
         },
      "certK8sSecretOut": {
         "namespace": "<NAMESPACE>",
         "name": "<CN>-secret-server",
         "key": "<CN>-servercert.pem"
     },
     "certChainK8sSecretOut": {
         "namespace": "",
         "name": "",
         "key": ""
     }
     },

     "caBundleK8sSecretIn": {
         "namespace": "",
         "name": "",
         "key": ""
     },

     "nf": "OCNADD-<SERVICE>",
     "overrideSecret": true
 }

The common parameters for all certificates are as follows:

  • <ISSUER>
  • <RENEW_BEFORE>
  • <DAYS>
  • <COUNTRY>
  • <STATE>
  • <LOCATION>
  • <ORG>
  • <OU>
  • <DOMAIN_NAME>

The following table lists the remaining parameters for each service, considering ocnadd-mgmt is the management group namespace and ocnadd-wg-1 is the worker group namespace:

Table 7-1 OCNADD Certificates Detail for OCCM

Service Name Namespace Certificate Name
ADMINSSVC ocnadd-mgmt ocnaddadminservice
ALARM ocnadd-mgmt ocnaddalarm
BACKUPRESTORE ocnadd-mgmt ocnaddbackuprestore
CONFIGURATION ocnadd-mgmt ocnaddconfiguration
EXPORTSVC ocnadd-mgmt ocnaddexport
HEALTHMONITORING ocnadd-mgmt ocnaddhealthmonitoring
OCNADDHOOK

ocnadd-mgmt

ocnadd-wg-1

 ocnaddhook
REDUNDANCYAGENT ocnadd-mgmt ocnaddredundancyagent
UIROUTER ocnadd-mgmt ocnadduirouter
CONSUMERADAPTER ocnadd-wg-1 adapter
CORRELATION ocnadd-wg-1 ocnaddcorrelation
FILTER ocnadd-wg-1 ocnaddfilter
INGRESSADAPTER ocnadd-wg-1 ocnaddingressadapter
KAFKABROKER ocnadd-wg-1 kafka-broker
NONORACLEAGGREGATION ocnadd-wg-1 ocnaddnonoracleaggregation
NRFAGGREGATION ocnadd-wg-1 ocnaddnrfaggregation
SCPAGGREGATION ocnadd-wg-1 ocnaddscpaggregation
SEPPAGGREGATION ocnadd-wg-1 ocnaddseppaggregation
STORAGEADAPTER ocnadd-wg-1 ocnaddstorageadapter
ZOOKEEPER ocnadd-wg-1 zookeeper

Note:

  • Separate certificates need to be created for ocnaddhook for the management namespace and for each worker group namespace.
  • In the case of kafka-broker, additional DNS entries for SAN are required depending on the number of replicas. For example, considering 4 Kafka brokers, the following DNS entries are required for their server and client certificates:
    {
    "csr": {
        "subjectAltName": {
            "dns": [
                "kafka-broker",
                "kafka-broker.<NAMESPACE>",
                "kafka-broker.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "kafka-broker-0.kafka-broker",
                "kafka-broker-0.kafka-broker.<NAMESPACE>",
                "kafka-broker-0.kafka-broker.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "kafka-broker-1.kafka-broker",
                "kafka-broker-1.kafka-broker.<NAMESPACE>",
                "kafka-broker-1.kafka-broker.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "kafka-broker-2.kafka-broker",
                "kafka-broker-2.kafka-broker.<NAMESPACE>",
                "kafka-broker-2.kafka-broker.<NAMESPACE>.svc.<DOMAIN_NAME>",
                "kafka-broker-3.kafka-broker",
                "kafka-broker-3.kafka-broker.<NAMESPACE>",
                "kafka-broker-3.kafka-broker.<NAMESPACE>.svc.<DOMAIN_NAME>"
            ]
        }
    }
}
  • If load-balancer IPs are statically configured for kafka-brokers, redundancy agents, and/or ingress adapters, then those IPs should be provided in the IP address field in SAN while creating certificates. For example, considering 4 Kafka brokers, the following IP address entries are required for their server and client certificates:
    {
    "csr": {
        "subjectAltName": {
            "ipAddress": [
                "10.10.10.10",
                "10.10.10.11",
                "10.10.10.12",
                "10.10.10.13"
            ]
        }
    }
}