Configuring offload server certificates on Kubernetes and OpenShift

Configure your analytics subsystem to trust your offload endpoint.

Before you begin

You must have the offload target's server certificate in either of these formats:

Base64 encoded pem file.
JKS file. If you are using a JKS file, encode the contents in Base64:
```
cat <JKS certificate filename> | base64
```

About this task

The ingestion pod of your analytics subsystem sends your API event data to your offload target. If your offload target uses TLS, then your ingestion pod must be configured to trust the offload target. The steps in this procedure insert the server certificate in the ingestion pod's offload certificates directory, so that the ingestion pod can validate the certificate it receives from the offload endpoint.

Procedure

Create a file called analytics_offload_certificates.yaml, and paste in the following contents:

If you are using a JKS file, then in the data section of the secret, paste the encoded JKS string as shown:

apiVersion: v1
kind: Secret
metadata:
  name: offload-certificates
data:
  keystore.jks: "<base64 encoded JKS string>"

If you are using a PEM file, then in the stringData.cacert section paste the contents of the PEM file.

apiVersion: v1
kind: Secret
metadata:
  name: offload-certificates
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-----

Note: If you have multiple offload targets, then add the certificates for each target with a unique name. For example:

stringData:
  certname_target1: |-
    -----BEGIN CERTIFICATE-----
    ...
  certname_target2: |-
    -----BEGIN CERTIFICATE-----
    ...

Create the offload-secret in your analytics namespace, from the analytics_offload_certificates.yaml file.
```
kubectl -n <namespace> apply -f analytics_offload_certificates.yaml
```
Verify that the offload-secret was created:
```
kubectl -n <namespace> get secrets
```
If the output plugin you are configuring supports the use of an offload-secret and you plan to utilize a password-protected keystore to store the CA certificate for the target offload server, create a Kubernetes secret to securely store the keystore's password:
```
kubectl -n <namespace> create secret generic offload-credentials --from-literal=keystore_password='<KeystorePassword>'
```
Edit your analytics CR:
```
kubectl edit a7s
```
Note: If you are using the OpenShift top-level CR deployment, edit your APIConnectCluster CR instead. Updates should be made in the spec.analytics section.
Add the new property spec.external.offload.secretName, and set it to offload-secret (the secret you created in step 2).
```
offload:
  enabled: true
  secretName: offload-secret
  output: |
    ...
```
When your ingestion pod restarts, it copies the contents of the offload-secret into its /etc/velox/external_certs/offload directory.
If you want to use a password-protected keystore, also include the property spec.offload.passwordSecretName and set it to offload-credentials (the secret you created in step 3):
```
offload:
  enabled: true
  secretName: offload-secret
  passwordSecretName: offload-credentials
  output: |
    ... 
```
Update your plugin properties to include the path to the server certificate. The property name for the endpoint server certificate depends on your output target. For HTTP the property name is ssl_certificate_authorities. Consult the Logstash documentation to confirm the property name used by other plugin types such as Syslog and Elasticsearch.
Example HTTP output plugin:
```
...
      output: |
        http {          
          url => "https://example.com"
          http_method => "post"
          id => "API Connect analytics event data"
          ssl_certificate_authorities => "/etc/velox/external_certs/offload/<certname>"
        }
```
where <certname> is the name that you specified in the analytics_offload_certificates.yaml file in step 1, either cacert or keystore.jks depending on the format of certificate used.
If you want to use a password protected keystore, configure the relevant properties of your desired plugin type to point to the keystore location and password. Example HTTP output plugin:
```
...
      output: |
        http {          
          url => "https://example.com"
          http_method => "post"
          id => "API Connect analytics event data"   
          ssl_truststore_password => "${keystore_password}"
          ssl_truststore_path => "/etc/velox/external_certs/offload/keystore.jks"
         } 
```
Save the updated analytics CR.
When you save the updated CR, your ingestion pod restarts itself automatically and detects the new secretName in the CR. On startup, the ingestion pod copies the certificate from the specified secretName to its /etc/velox/external_certs/offload directory. You can verify that the certificate was successfully imported with:
```
kubectl exec -ti <ingestion pod> -- bash -ic "ls /etc/velox/external_certs/offload"
```
This command should return the certificate name that you specified in the analytics_offload_certificates.yaml file, either cacert or keystore.jks depending on the format of certificate used.
When your ingestion pod communicates with your HTTPS endpoint, it verifies the server certificate that the endpoint returns against the certificate that is stored in /etc/velox/external_certs/offload.
Ensure that you take a backup of your offload secret and your updated analytics CR. For more information about backups, see Backup, restore, and disaster recovery