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.
About this task
If you configure Analytics for offloading and your endpoint requires a particular certificate, you can configure the certificate now and then reference it in the offload plugin when you complete the next task.
Procedure
-
Create a Kubernetes secret to contain the certificates, and then apply it to the cluster where
the Analytics subsystem runs.
-
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.
-
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. Ifcat
andbase64
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.
-
Create a Kubernetes secret and add the certificate.
- 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 thecacert
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-----
- 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.
- Base64-encoded file: In the
- Save the file.
- 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
-
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.
-
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.
- 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
. - 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
- 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.
- 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
-
Log in to a server that has kubectl access to the Kubernetes cluster where API Connect Analytics is
deployed.
-
Update the Analytics subsystem so that it can use the new secrets.
-
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 themetadata
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 usesoffload-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 usesoffload-certificates
as the certificates secret's name.
- The
-
Update the Analytics subsystem.
- 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.
- 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
- Log in to the server where you run
-
Create an extra-values.yaml file that specifies the names of your
certificate and environment variables secret files.
-
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.
- Items specified in the secret provided to