How do I configure a generic mediator?

Purpose

Use this procedure to install or uninstall a generic mediator to connect to an external controller. A generic mediator will handle authentication to the controller, allowing a call to be made to the controller from NSP without the need to provide credentials.

You can configure as many generic mediators as required, with different external controller parameters. The latest Helm chart and docker images are contained in the nsp configurator tar package with the name “nsp-mdt-generic-mediator”.

To provide generic mediator parameters to the NSP you must create a values.yaml file; see the Generic Mediator Configuration information in the Intent Based Management Framework tutorial on the Network Developer Portal.

Naming

Each generic mediator must have a unique name.

Names must be unique in the following areas:

  • the name of the instance in Helm

    You can allow Helm to autogenerate a unique name, however, using the -n option when installing the Helm chart will allow you to use a meaningful user identifiable name.

  • the name of the pod and Kubernetes configuration

    This is specified in the values.yaml file using the mediator_name value. When the name is given, the Kubernetes structures will be given a name like nsp-mdt-<name>-mediator. For example, to name the mediator SF1, enter the mediator_name: "SF1" in the values.yaml file. This will produce a pod and Kubernetes structures prefixed with nsp-mdt-SF1-mediator. If multiple words are in the name, they must be separated with a dash character (-).

The Helm instance name and the mediator_name do not have to be the same, however, using the same name may make alignment simpler.

Authentication information

Authentication information for the generic mediator is stored in a secret in the Kubernetes cluster. You need to create the secret before installing the generic mediator.

For information about the values to include in the secret, see the Generic Mediator Configuration information in the Intent Based Management Framework tutorial on the Network Developer Portal.

Certs files

Certs files may need to be copied into the pod for requests and authentication to work properly. This is done using a combination of the copy_certs and certsFileName properties, and the --set-file flag on the helm command.

When copy_certs is set to true, the NSP will attempt to copy a certs file into the pod in the /opt/nsp/os/ssl/certs/custom directory. Since the name of the certs file might be important and the mediator itself will not be aware of this, the file name to give this file is specified in the certsFileName value.

For example, if you have these values in the values.yaml file:

  • copy_certs: true

  • certsFileName: "ca.pem"

A file named ca.pem is created in the /opt/nsp/os/ssl/certs/custom directory.

If you specify copy_certs: true in the values.yaml file but do not add the --set-file flag to the helm command, the pod cannot initialize.

Steps
Perform Helm installation
 
1 

Log in as the root or NSP admin user on the NSP cluster host.

2 

Open a console window.

3 

Create an NSP Kubernetes secret, see How do I add an NSP Kubernetes secret?.

4 

Create a values.yaml file.

Ensure that the name of the secret created in Step 3 is configured in the external_auth_secret_name value.

5 

Obtain the Helm repository name and URL; enter the following:

# helm repo list ↵

Output like the following is displayed:

NAME           URL

repository name    repository URL

6 

Obtain the chart version for the nsp-mdt-generic-mediator chart; enter the following:

# helm search repo repository URL/repository name/nsp-mdt-generic-mediator --versions↵

Output like the following is displayed:

NAME CHART VERSION APP VERSION DESCRIPTION                                      

repository name/nsp-mdt-generic-mediator    chart_version   app_version Helm Chart for nsp-mdt-generic-mediator

7 

Execute the Helm installation based on the following example:

# helm install mediator-instance-name repository URL/repository name/nsp-mdt-generic-mediator --namespace namespace--version chart_version -f values file --set-file externalControllerConfig.externalControllerAuth.certsFile=certs file ↵

where

mediator instance name is the unique Helm instance name for the mediator, for example, generic-mediator-one

repository URL and repository name are the values obtained in Step 5

chart_version is the value obtained in Step 6

namespace is the Kubernetes namespace in use for existing mediators

values file is the path to the values.yaml file

certs file is the path to the certs file

If you do not want to copy certs files to the pod, the --set-file flag is not required.

Perform Helm uninstallation
 
8 

To uninstall a generic mediator, you must delete them using Helm. Execute the following:

# helm uninstall mediator-instance-name --namespace namespace ↵

where

mediator instance name is the mediator instance, for example, generic-mediator-one

namespace is the Kubernetes namespace

9 

Close the console window.

End of steps