Providing a custom certificate for analytics offload

Optionally configure a private or self-signed certificate to secure the connections between IBM® API Connect Analytics and your external offload endpoint.

1. Create a Kubernetes secret to contain the certificates, and then apply it to the cluster where the Analytics subsystem runs.
   1. Log in to a server that has kubectl access to the Kubernetes cluster where API Connect Analytics is deployed.

      For OVA deployments, you must log in to one of the running Analytics VMs as a user with kubectl access.

   2. Encode the certificates file in base64.

      For offload certificates, you only need to provide the certificates that your endpoint requires. Some offload plugins require certificates as JKS files and others accept text-based files such as PEM files; use the format that is appropriate for your plugin.

      Attention: If you use a JKS file for certificates, then this step is required because the non-text JKS file must be encoded in advance. If you use a text-based file such as PEM, then you can choose between encoding the file now or skipping this step and adding the keys to the secret in the next step.

      There are several ways to encode the file. If cat and base64 are available, then you can run the following command to encode the file:

      cat keystore.jks | base64

      Copy the output so that you can paste it into the secret in the next step.

   3. Create a Kubernetes secret and add the certificate.
      1. Create a YAML file to contain the secret; for example, you can call the file offload_certs.yaml. The secret's name that you specify in the file does not have to match the file name. In this example, the secret's name is offload-certificates.

         Add as many keys as you want, using any field names that you want. For each key, a file based on the corresponding field name is created in the container at ${OFFLOAD_CERTS_DIR}, and you can use it in your offload plugin's configuration. For example, if you paste a certificate in the cacert field as shown in the following example, then a file named cacert is stored in the ${OFFLOAD_CERTS_DIR} location.

         apiVersion: v1
         kind: Secret
         metadata:
           # Change value of name to be whatever you wish secret to be called
           name: offload-certificates
         # Only base64 encoded data should be placed in data section; JKS keys would go here
         data:
           keystore.jks: "output_of_base64_encoded_jks"
         stringData:
           cacert: |-
             -----BEGIN CERTIFICATE-----
             MIIDIDCCAomgAwIBAgIENd70zzANBgkqhkiG9w0BAQUFADBOMQswCQYDVQQGEwJVUzEQMA4GA1UE
             ChMHRXF1aWZheDEtMCsGA1UECxMkRXF1aWZheCBTZWN1cmUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5
             MB4XDTk4MDgyMjE2NDE1MVoXDTE4MDgyMjE2NDE1MVowTjELMAkGA1UEBhMCVVMxEDAOBgNVBAoT
             B0VxdWlmYXgxLTArBgNVBAsTJEVxdWlmYXggU2VjdXJlIENlcnRpZmljYXRlIEF1dGhvcml0eTCB
             nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwV2xWGcIYu6gmi0fCG2RFGiYCh7+2gRvE4RiIcPR
             fM6fBeC4AfBONOziipUEZKzxa1NfBbPLZ4C/QgKO/t0BCezhABRP/PvwDN1Dulsr4R+AcJkVV5MW
             8Q+XarfCaCMczE1ZMKxRHjuvK9buY0V7xdlfUNLjUA86iOe/FP3gx7kCAwEAAaOCAQkwggEFMHAG
             A1UdHwRpMGcwZaBjoGGkXzBdMQswCQYDVQQGEwJVUzEQMA4GA1UEChMHRXF1aWZheDEtMCsGA1UE
             CxMkRXF1aWZheCBTZWN1cmUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MQ0wCwYDVQQDEwRDUkwxMBoG
             A1UdEAQTMBGBDzIwMTgwODIyMTY0MTUxWjALBgNVHQ8EBAMCAQYwHwYDVR0jBBgwFoAUSOZo+SvS
             spXXR9gjIBBPM5iQn9QwHQYDVR0OBBYEFEjmaPkr0rKV10fYIyAQTzOYkJ/UMAwGA1UdEwQFMAMB
             Af8wGgYJKoZIhvZ9B0EABA0wCxsFVjMuMGMDAgbAMA0GCSqGSIb3DQEBBQUAA4GBAFjOKer89961
             zgK5F7WF0bnj4JXMJTENAKaSbn+2kmOeUJXRmm/kEd5jhW6Y7qj/WsjTVbJmcVfewCHrPSqnI0kB
             BIZCe/zuf6IWUrVnZ9NA2zsmWLIodz2uFHdh1voqZiegDfqnc1zqcPGUIWVEX/r87yloqaKHee95
             70+sB3c4
             -----END CERTIFICATE-----

      2. Paste the certificate into the file.
         The method for adding the certificate to the secret depends on whether you encoded the file in the previous step:

         • Base64-encoded file: In the data section of the secret, type a name for the field (you can choose the name). Paste the encoded output from the previous step (enclosed in "") as the value.
         • Plain text file: In the stringDdata section of the secret, type a name for the key or certificate (you can choose the name), and paste the value.
      3. Save the file.
   4. Update the cluster with the new certificate.
      Run the following command to update the cluster:

      kubectl apply -f offload_certs.yaml -n your_namespace

      where:

      • offload_certs.yaml is the secret's file name (not the name of the secret).
      • your_namespace is the name of your deployment's namespace. The namespace is only needed for Kubernetes deployments.

        For OVA deployments, you can omit the entire -n your_namespace parameter from the command. By default, kubectl is already configured to match the namespace where your Analytics resources are deployed.

   5. Optionally create another Kubernetes secret, which can be used in environment variables.

      If you have sensitive data such as a certificate passphrase that must be available in text format, you can store it in another secret.

      If your passphrase is not sensitive (such as the JKS default passphrase), then you can supply it directly in the logstash configuration, and skip this step.

      1. Create a new YAML file; for example, call the file offload_env_var.yaml. The secret's name that you specify in the file does not have to match the file name. In this example, the secret's name is offload-environment.
      2. Paste the environment variable name and the passphrase (in plain text) into the stringData section of the file as shown in the following code example:

         apiVersion: v1
         kind: Secret
         metadata:
           name: offload-environment
         stringData:
           # Example environment variable names, you'll reference these from within logstash
           OFFLOAD_JKS_PASSWORD: password123

      3. Run the following command to update the cluster:

         kubectl apply -f offload_env_var.yaml -n your_namespace

         where offload_env_var.yaml is the secret's file name.

2. Update the Analytics subsystem so that it can use the new secrets.
   1. Create an extra-values.yaml file that specifies the names of your certificate and environment variables secret files.
      Include the following lines in the extra-values.yaml file, making sure to use the names of your Kubernetes secrets (value the of the name field in the metadata section of the secret, which might not match the file's name):

      
      apic-analytics-ingestion:
        # offloadSecretEnv will mount all objects in specified secret name provided as environment variables
        offloadSecretEnv: offload-environment
        # offloadSecretCerts will mount all objects in specified secret as files on containers, using key as file name
        offloadSecretCerts: offload-certificates

      where:

      • The offloadSecretEnv setting provides the name of the secret that is used by environment variables (to contain the certificate passphrase, for example). Keys provided in this file are made available as environment variables. The sample offload_env_var.yaml file in step 1 uses offload-environment as the secret's name.
      • The offloadSecretCerts setting provides the name of the secret that contains the certificates needed for connecting to the offload endpoint. Keys provided in this file are stored as files in the ${OFFLOAD_CERTS_DIR} directory. The sample offload_certs.yaml file in step 1 uses offload-certificates as the certificates secret's name.
   2. Update the Analytics subsystem.
      1. Log in to the server where you run apicup, and navigate to the project directory.

         In Kubernetes deployments this is probably the same server that you used for step 1, but for OVA deployments it is a different server.

      2. Run the following apicup commands to reinstall the Analytics subsystem using the configuration settings in the extra-values.yaml file.

         apicup subsys set analytics extra-values-file=~/extra-values.yaml
         apicup subsys install analytics

3. Update the logstash configuration to use the new secret.
   Modify the logstash configuration and replace the references to the certificate file with references to the new secret:

   • Items specified in the secret provided to offloadSecretEnv are available to use in logstash config files as environment variables; for example: ${OFFLOAD_JKS_PASSWORD}.
   • Keys from offloadSecretCerts are stored as files in ${OFFLOAD_CERTS_DIR}. The path and file name can be referenced in the logstash configuration; for example, ${OFFLOAD_CERTS_DIR}/keystore.jks for a JKS file or ${OFFLOAD_CERTS_DIR}/cacert for a PEM file.
   • For information on configuring the logstash plugins, see Configuring output plugins for analytics offload.