The Cisco Prime Cable Provisioning (PCP) 7.4 CDU Quick Start Guide describes the concepts and configurations of Central Distribution Unit (CDU). CDU acts as single point to configure multiple RDU instances.

All the relevant configurations applicable to RDU can be added to CDU and then applied to RDU.

CDU was introduced as part of PCP 7.2 release as a management component. More features was added as part of PCP 7.3. That makes CDU 7.3 work properly only with regular PCP 7.3 components (RESTPWS, RDU, DPE and CPNR_EP). CDU does not work with the containerized PCP components.

Note	CDU 7.4 is tested with PCP 7.4 components only. CDU 7.4 is not compatible with older versions of PCP.

There are two Docker container images provided with PCP 7.4 release:

• Application container: pcp-cdu-app:7.4

  This is backend of CDU which exposes REST APIs as configuration interface.

• User Interface: pcp-cdu-webui:7.4

  This serves the client web application (frontend) to connect to CDU application (backend).

This image should be run on a Kubernetes cluster. You can download the Prime Cable Provisioning CDU Container Docker image and relevant manifests for Prime Cable Provisioning 7.4 from the Download Software page, Download Software.

1. Download the following software images:

   • pcp-cdu-app_7.4.tar.gz

   • pcp-cdu-webui_7.4.tar.gz

2. Extract the files with .tar.gz extension:

   # tar -zxvf pcp-cdu-app_7.4.tar.gz

   The utility creates the following artifacts:

   a. pcp-cdu-app.tar: A tar archive of pcp-cdu-app:7.4 Docker image.

   b. manifests: A directory with manifests needed for deploying pcp-cdu-app container.

   # tar -zxvf pcp-cdu-webui_7.4.tar.gz

   The utility creates the following artifacts:

   a. pcp-cdu-webui.tar: A tar archive of pcp-cdu-webui:7.4 Docker image.

   b. manifests: A directory with manifests needed for deploying pcp-cdu-webui container.

3. To load the Docker images:

   # docker load -i pcp-cdu-app.tar

   # docker load -i pcp-cdu-webui.tar

4. To list the Docker image:

   # docker image ls

It is recommended to verify the signature of the images you received. Your premises verification script can contact Cisco to download root and subCA certs. Python(3) needs to be installed.

1. Download the image_verification.tar.gz image and extract files:

   # tar -zxvf image_verification.tar.gz

2. Extract the public key from the public cert:

   $ openssl x509 -pubkey -noout -in PCP_RELEASE_7X-CCO_RELEASE.pem > PCP_RELEASE_7X-CCO_RELEASE.pubkey

3. To check whether the verify script is using the public key and signature files:

   $ openssl dgst -sha512 -verify PCP_RELEASE_7X-CCO_RELEASE.pubkey -signature cisco_x509_verify_release.py3.signature cisco_x509_verify_release.py3
   Verified OK

4. Verify the product image:

   $ python3 cisco_x509_verify_release.py3 -e PCP_RELEASE_7X-CCO_RELEASE.pem -s pcp-cdu-app_7.4.tar.gz.signature -i pcp-cdu-app_7.4.tar.gz -v dgst -sha512
   $ python3 cisco_x509_verify_release.py3 -e PCP_RELEASE_7X-CCO_RELEASE.pem -s pcp-cdu-webui_7.4.tar.gz.signature -i pcp-cdu-webui_7.4.tar.gz -v dgst -sha512

CDU has the following infrastructure requirements:

1. A Kubernetes Cluster with Calico CNI installed.

2. PostgreSQL Database Server:

   CDU application container acts as a client application connecting to PostgreSQL database server.

   The Database Administrator is responsible to configure and tune the PostgreSQL database server to be used by the CDU application container.

   1. A database has to be created (SQL: CREATE DATABASE) for CDU application container to store its data. CDU container uses 'public' schema.

   2. A database user with password has to be created (SQL: CREATE USER) which CDU application container uses to connect to the above created database. It is recommended that the user be the owner of the database.

   3. Configure PostgreSQL client authentication (pg_hba.conf) to allow connections to the database created in (a) by user created in (b) from the IP addresses of worker nodes in the Kubernetes cluster.

      CDU application container supports password-based authentication methods (scram-sha-256, md5, password) configured on PostgreSQL database server.

Example:

An entry in pg_hba.conf:

'cduuser' database user is allowed to connect to 'cdudb' database from worker nodes in 10.0.0.0/26 network if password is correctly supplied

Note	Cisco has tested PCP 7.4 CDU Container with PostgreSQL 14 running on Linux.

In a single Kubernetes cluster, you can run more than one CDU application containers to provide high-availability. CDU application container uses PostgreSQL as its database.

Note

Database is not part of the PCP software image. You need to download, install, configure, and maintain it, so that it can be used by the CDU container. Please see: https://www.postgresql.org/download/linux/redhat/ We recommend you to configure and use replication feature of PostgreSQL, so that the data is available on the Secondary server if the Primary is lost.

Note	All the non-confidential properties required by the cdu-app pods have to be provided in these manifests: cdu-app-cm.yaml and cdu-app-logging-cm.yaml. All the confidential properties required by cdu-app pods have to be provided in these manifests: cdu-app-secrets.yaml and cdu-app-ca-secrets.yaml.

Following Kubernetes resources and manifests are used to run pcp-cdu-app container. Please create all these resources by applying the manifests:

1. cdu-app-deployment: Deployment object is to run the desired number of cdu-app pod replicas with the pcp-cdu-app:7.4 image.

   Manifest: cdu-app-deployment.yaml

   Minimum resources recommended by Cisco to run a cdu-app pod with are:

   • Memory = 2500Mi, CPU = 1. This can be tuned by

     .spec.template.spec.containers[0].resources.requests.memory and

     .spec.template.spec.containers[0].resources.requests.cpu fields.

   • Min and max Java heap = 2048M. This is configured via environment variable named CDU_JVM_OPTS (.spec.template.spec.containers[0].env)

2. cdu-app-cm: ConfigMap object is to store configuration used by cdu-app pods.

   Manifest: cdu-app-cm.yaml

   The cdu-app pods consume ConfigMap as configuration files in a volume.

   Note	The minimum configuration set in ConfigMap needed by cdu-app container are the following: cdu.database.url cdu.database.username cors.urls

3. cdu-app-logging-cm: A separate ConfigMap object to store logging configuration of cdu-app pods.

   Manifest: cdu-app-logging-cm.yaml

   The cdu-app pods consume ConfigMap as configuration file in a volume. You can configure log4j2 configuration (used by cdu-app) using this ConfigMap object. It is recommended to configure console logging mandatorily, file logging is optional.

4. cdu-app-secrets: Secret object to store sensitive data like password, keys and certificates used (served) by cdu-app pods.

   Manifest: cdu-app-secrets.yaml

   cdu-app pods consume Secret as configuration files in a volume.

   Use this Secret object to provide PostgreSQL database password, private key and public certificate used by REST interface. Values of all the items have to be provided as base64-encoded strings i.e. PEM encoded CDU certificate should further be base64-encoded.

5. cdu-app-ca-secrets: Secret object to store certificates used (trusted) by cdu-app pods.

   Manifest: cdu-app-ca-secrets.yaml

   cdu-app pods consume Secret as configuration files in a volume.

   CDU can be configured to communicate with RDU, REST PWS and DPE on TLS/HTTPS. So, it needs to trust the end-entity certificates or CA certificates used to sign certificates of those servers. Use this Secret object to provide certificates to be trusted by CDU. Values of all the items have to be provided as base64-encoded strings i.e. PEM encoded CDU certificate should further be base64-encoded.

6. cdu-app-service: Network services offered by CDU (HTTPS on TCP port 9443) have to be exposed. Kubernetes service object of type = NodePort is used to expose cdu-app pods for external communication.

   Manifest: cdu-app-service.yaml

   Note	These manifests are provided as a reference and tested by Cisco. We recommend you to use a copy of these, should you require modification for your Kubernetes cluster.

CDU application container configuration is externalized to Kubernetes ConfigMap and Secret objects. All cdu-app pods use the same ConfigMap and Secrets objects and hence operate with the same configuration. To make a configuration change, update these objects and restart the cdu-app pods, which can be achieved by using restart features provided by Kubernetes Deployment. You can set appropriate Rolling Update strategy in Deployment object.

Following Kubernetes resources and manifests are used to run pcp-cdu-webui container. Please create all these resources by applying the manifests :

1. cdu-webui-deployment: Deployment object is to run the desired number of cdu-webui pod replicas with the pcp-cdu-webui:7.4 image.

   Manifest: cdu-webui-deployment.yaml

   Minimum resources recommended by Cisco to run a cdu-webui pod with are:

   • Memory = 500Mi, CPU = 500m. This can be tuned by

     .spec.template.spec.containers[0].resources.requests.memory and

     .spec.template.spec.containers[0].resources.requests.cpu fields.

2. cdu-webui-cm: ConfigMap object is to store application configuration used by cdu-webui pods.

   Manifest: cdu-webui-cm.yaml

   The cdu-webui pods consume ConfigMap as configuration files in a volume.

   Use the ConfigMap object to configure the values of the following two items:

   a. URL of the CDU Application REST interface used by the web client (e.g. browser)

   b. Page size used by the web interface to list the items.

3. nginx-cm: CDU web UI uses nginx web server to serve content. This ConfigMap object is used to configure nginx (/etc/nginx/nginx.conf)

   Manifest: nginx-cm.yaml

4. cdu-webui-secrets: Secret object to store sensitive data like keys and certificates used (served) by cdu-webui pods.

   Manifest: cdu-webui-secrets.yaml

   cdu-webui pods consume Secret as configuration files in a volume.

   Use this Secret object to provide private key and public certificate used by Web UI. Values of all the items have to be provided as base64-encoded strings i.e. PEM encoded CDU certificate should further be base64-encoded.

5. cdu-webui-service: Network services offered by CDU Web UI (HTTPS on TCP port 10443) have to be exposed. Kubernetes service object of type = NodePort is used to expose cdu-webui pods for external communication.

   Manifest: cdu-webui-service.yaml

   Note	These manifests are provided as a reference and tested by Cisco. We recommend you to use a copy of these, should you require modification for your Kubernetes cluster.

CORS (Cross-Origin Resource Sharing) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain.

From browser's perspective, cdu-pcp-webui could be served from one origin and cdu-pcp-app be served from a different origin (cross-origin).

To allow such cross-origin requests, you should configure cors.urls in cdu-app-cm.yaml. With that, cdu-pcp-app pods will allow requests from browser which run CDU web UI application.

1. Create Secrets object with base-64 encoded TLS material (key and certificate) and database password.

   # kubectl apply -f cdu-app-secrets.yaml

2. Create ConfigMap object with appropriate configuration.

   # kubectl apply -f cdu-app-cm.yaml

3. Create NodePort Service object.

   # kubectl apply -f cdu-app-service.yaml

4. Create Deployment object.

   # kubectl apply -f cdu-app-deployment.yaml

5. Identify node port allocated to cdu-app-service.

   # export CDUPORT=$(kubectl get svc cdu-app-service -o=jsonpath='{.spec.ports[0].nodePort}')

6. Obtain a valid CDU license.

7. Use REST API to load license and add CDU super user by sending HTTP POST request:

   • To the endpoint https://<worker_node_IP>:<CDUPORT>/apis/core/v1/initialUserLicense

   • With the following request body:

     {
       "username": "cduadmin",
       "password": "cduadmin",
       "licenseData":"<Base64 encoded contents of CDU license file>"
     }

8. Login to CDU application by providing username and password of super user created in previous step and receive a short-lived access token.

   Send HTTP POST request:

   • To the endpoint https://<worker_node_IP>:<CDUPORT>/apis/core/v1/login

   • With the following request body:

     {
       "username": "cduadmin",
       "password": "cduadmin",
     }

9. REST APIs of CDU support Bearer Token Authorization. Use the access token received in previous step as Authorization Header.

   After the token expires, re-authenticate at /apis/core/v1/login endpoint to receive a new token.

10. For details of other APIs, you can access CDU OpenAPI (Swagger) documentation at:

    https://<worker_node_IP>:<CDUPORT>/apis/swagger-ui/index.html.

1. Create Secrets object with base-64 encoded TLS material: private key (cduweb.key) and certificate (cduweb.crt)

   # kubectl apply -f cdu-webui-secrets.yaml

2. Create ConfigMap object with appropriate configuration. You need to configure CDU_API_URL with URL of externally reachable cdu-app-service.

   # kubectl apply -f cdu-webui-cm.yaml

3. Create NodePort Service object. The sample manifest exposes the service at NodePort = 443.

   # kubectl apply -f cdu-webui-service.yaml

4. Create Deployment object.

   # kubectl apply -f cdu-webui-deployment.yaml

5. Connect to web UI:

   https://<worker_node_fqdn>:443

CDU operates on two logical databases:

1. Core : This database holds the configuration objects which are owned by CDU application.

   Administrator has privileges to create/update/delete/read this data.

   Any configuration that exists in core database can be pushed to RDUs servers.

2. Replica : This database holds the configuration objects which are owned by RDUs servers and then pulled into CDU.

   Administrator has read-only privileges to this data. In order to make any changes to this data, the specific object has to be merged into Core database.

The features provided by CDU are:

1. Inventory Management :

   • Add PCP components (RESTPWS, RDU, DPE, CPNR servers).

   • Discover PCP components:

     i. After you have added RDU server, use /generateTopology endpoint to discover inventory of PCP components connected to that RDU. This will lead to discovery of Provisioning Group, DPE server and CPNR servers connected to that RDU.

     ii. After you have added RESTPWS server, use /generateTopology endpoint to discover inventory of RDU servers added to that RESTPWS.

     Further, PCP components connected to each RDU will be discovered.

     The discovered PCP components are automatically added to CDU inventory. You can see the discovered PCP components using /showTopology endpoint.

   • Fetch statistics of RDU, DPE, CPNR servers using /pullStats endpoint of RDU.

   • Pull license keys on RDU using /pullLicenseKey endpoint of RDU and show license utilization status using /licenseUtilization endpoint of RDU.

2. Configuration Management :

   • RESTPWS - CDU can manage the list of RDU servers configured on a RESTPWS server.

   • RDU - Create configuration objects like DHCP Criteria, Class of Services etc in CDU's core configuration database and push those to RDU.

     Further, configuration objects can be updated and deleted (reclaimed) from RDU.

   • DPE - Send DPE CLI configuration commands to DPE from CDU. You can start/stop/reload DPE using CDU. This uses DPE HTTP API interface.

3. Data Replication :

   • Configuration - Pull the configuration objects like DHCP Criteria, Class of Services etc on RDU into CDU's configuration replica database.

     Optionally merge specific data into configuration replica database, make any changes and push it back to any RDU.

   • Devices - Pull devices objects and discovered data into CDU's configuration replica database.

   Note	Data Replication requires fetching a lot of data from RDU to CDU. It can be intensive operation on RDU and take long time.

The following tables lists the open bugs in CDU.