SPK Secrets

Overview

The SPK Controller, Service Proxy Traffic Management Microkernel (TMM), and optional OTEL Statistics containers communicate over secure channels using the gRPC (remote procedure call) framework. To secure the gRPC channel, SSL/TLS keys and certificates must be generated and stored as Secrets in the cluster.

_images/spk_info.png Note: The gRCP channel is established over TCP service port 8750.

This document guides you through understanding, generating and installing the SPK Secrets.

Validity period

SSL/TLS certificates are valid for a specific period of time, and once they expire, secure connections fail when attempting to validate the certificate. When creating new SSL/TLS certificates for the gRPC channel, it is recommended that you choose a period of one year, or two years to avoid connection failures.

Example SSL Certificate validity period:

Validity
    Not Before: Jan 1  10:30:00 2021 GMT
    Not After : Jan 1  10:30:00 2022 GMT

Updating Secrets

When planning to replace previously installed SPK Secrets, you must restart the Controller and Service Proxy TMM Pods to begin using the new Secrets. To replace existing Secrets, refer to the Restarting section of this guide.

_images/spk_warn.png Important: Restarting the Service Proxy TMM Pods impacts traffic processing.

Requirements

Ensure you have:

  • An OpenShift cluster.
  • A workstation with OpenSSL installed.

Procedures

Creating the Secrets

Use the following steps to generate the gRPC SSL/TLS keys and certificates.

Note: The commands used to generate the Secrets can be downloaded here.

  1. Change into the directory with the SPK files:

    cd <directory>
    

    In this example, the SPK files are in the spkinstall directory:

    cd spkinstall
    
  2. Create a new directory for the Secret SSL/TLS keys and certificates, and change into the directory:

    mkdir <directory>
    
    cd <directory>
    

    In this example, a new directory named grpc_secrets is created and changed into:

    mkdir grpc_secrets
    
    cd grpc_secrets
    
  3. Create the gRPC Certificate Authority (CA) signing key and certificate:

    _images/spk_info.png Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.

    openssl genrsa -out grpc-ca.key 4096
    
    openssl req -x509 -new -nodes -key grpc-ca.key -sha256 -days 365 -out grpc-ca.crt \
    -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=Dev/CN=ca"
    
  4. The following code creates a new file named server.ext with the required SSL/TLS attributes:

    echo "[req_ext]" > server.ext
    echo " " >> server.ext
    echo "subjectAltName = @alt_names" >> server.ext
    echo " " >> server.ext
    echo "[alt_names]" >> server.ext
    echo " " >> server.ext
    echo "DNS.1 = grpc-svc" >> server.ext
    echo "DNS.2 = otel-collector" >> server.ext
    

    The server.ext file should contain the following SSL/TLS attributes:

    [req_ext]
    
    subjectAltName = @alt_names
    
    [alt_names]
    
    DNS.1 = grpc-svc
    DNS.2 = otel-collector
    
  5. Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed certificate for the Controller and TMM channel:

    _images/spk_info.png Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.

    openssl genrsa -out grpc-server.key 4096
    
    openssl req -new -key grpc-server.key -out grpc-server.csr \
    -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
    
    openssl x509 -req -in grpc-server.csr -CA grpc-ca.crt -CAkey grpc-ca.key \
    -CAcreateserial -out grpc-server.crt -extensions req_ext -days 365 -sha256 \
    -extfile server.ext
    
  6. Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed certificate for the Controller, TMM and OTEL channel:

    _images/spk_info.png Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.

    openssl genrsa -out grpc-otel-server.key 4096
    
    openssl req -new -key grpc-otel-server.key -out grpc-otel-server.csr \
    -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
    
    openssl x509 -req -in grpc-otel-server.csr -CA grpc-ca.crt -CAkey grpc-ca.key \
    -set_serial 101 -outform PEM -out grpc-otel-server.crt -extensions req_ext -days 365 \
    -sha256 -extfile server.ext
    
  7. The following code creates a new file named client.ext with the required SSL/TLS attributes:

    echo "[req_ext]" > client.ext
    echo " " >> client.ext
    echo "subjectAltName = @alt_names" >> client.ext
    echo " " >> client.ext
    echo "[alt_names]" >> client.ext
    echo " " >> client.ext
    echo "email.1 = clientcert@f5net.com" >> client.ext
    

    The client.ext file should contain the following SSL/TLS attributes:

    [req_ext]
    
    subjectAltName = @alt_names
    
    [alt_names]
    
    email.1 = clientcert@f5net.com
    
  8. Create the gRPC client key, CSR and signed certificate for the Controller and TMM channel:

    _images/spk_info.png Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.

    openssl genrsa -out grpc-client.key 4096
    
    openssl req -new -key grpc-client.key -out grpc-client.csr \
    -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
    
    openssl x509 -req -in grpc-client.csr -CA grpc-ca.crt -CAkey grpc-ca.key \
    -set_serial 101 -outform PEM -out grpc-client.crt -extensions req_ext -days 365 \
    -sha256 -extfile client.ext
    
  9. Create the gRPC client key, CSR and signed certificate for the Controller, TMM and OTEL channel:

    _images/spk_info.png Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.

    openssl genrsa -out grpc-otel-client.key 4096
    
    openssl req -new -key grpc-otel-client.key -out grpc-otel-client.csr \
    -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
    
    openssl x509 -req -in grpc-otel-client.csr -CA grpc-ca.crt -CAkey grpc-ca.key \
    -set_serial 101 -outform PEM -out grpc-otel-client.crt -extensions req_ext -days 365 \
    -sha256 -extfile client.ext
    

Installing the Secrets

Use the following steps to encode, and store the SSL/TLS keys and certificates as Secrets in the cluster.

  1. The following code performs a Base64 encoding of the keys and certificates:

    openssl base64 -A -in grpc-ca.crt -out grpc-ca-encode.crt
    openssl base64 -A -in grpc-server.crt -out grpc-server-encode.crt
    openssl base64 -A -in grpc-client.crt -out grpc-client-encode.crt
    openssl base64 -A -in grpc-server.key -out grpc-server-encode.key
    openssl base64 -A -in grpc-ca.key -out grpc-ca-encode.key
    openssl base64 -A -in grpc-client.key -out  grpc-client-encode.key
    openssl base64 -A -in grpc-otel-client.crt -out grpc-otel-client-encode.crt
    openssl base64 -A -in grpc-otel-server.crt -out grpc-otel-server-encode.crt
    openssl base64 -A -in grpc-otel-client.key -out grpc-otel-client-encode.key
    openssl base64 -A -in grpc-otel-server.key -out grpc-otel-server-encode.key
    
  2. The following code creates the K8S Secret object used to store SSL/TLS keys:

    _images/spk_warn.png Important: The syntax in the bottom three lines; grpc-svc.key, priv.key, and f5-ing-demo-f5ingress.key, must be set as in the example.

    echo "apiVersion: v1" > keys-secret.yaml
    echo "kind: Secret" >> keys-secret.yaml
    echo "metadata:" >> keys-secret.yaml
    echo " name: keys-secret" >> keys-secret.yaml
    echo "data:" >> keys-secret.yaml
    echo -n " priv.key: " >> keys-secret.yaml; cat grpc-ca-encode.key >> keys-secret.yaml 
    echo "" >> keys-secret.yaml
    echo -n " grpc-svc.key: " >> keys-secret.yaml; cat grpc-server-encode.key >> keys-secret.yaml
    echo "" >> keys-secret.yaml
    echo -n " f5-ing-demo-f5ingress.key: " >> keys-secret.yaml; cat grpc-client-encode.key >> keys-secret.yaml
    echo "" >> keys-secret.yaml
    echo -n " grpc-otel-client.key: " >> keys-secret.yaml; cat grpc-otel-client-encode.key >> keys-secret.yaml
    echo "" >> keys-secret.yaml
    echo -n " grpc-otel-server.key: " >> keys-secret.yaml; cat grpc-otel-server-encode.key >> keys-secret.yaml
    
  3. The following code creates the K8S Secret object used to store the SSL/TLS certificates:

    _images/spk_warn.png Important: The syntax in the bottom three lines; grpc-svc.crt, ca_root.crt, and f5-ing-demo-f5ingress.crt, must be set as in the example.

    echo "apiVersion: v1" > certs-secret.yaml
    echo "kind: Secret" >> certs-secret.yaml
    echo "metadata:" >> certs-secret.yaml
    echo " name: certs-secret" >> certs-secret.yaml
    echo "data:" >> certs-secret.yaml
    echo -n " ca_root.crt: " >> certs-secret.yaml; cat grpc-ca-encode.crt >> certs-secret.yaml 
    echo "" >> certs-secret.yaml
    echo -n " grpc-svc.crt: " >> certs-secret.yaml; cat grpc-server-encode.crt >> certs-secret.yaml
    echo "" >> certs-secret.yaml
    echo -n " f5-ing-demo-f5ingress.crt: " >> certs-secret.yaml; cat grpc-client-encode.crt >> certs-secret.yaml
    echo "" >> certs-secret.yaml
    echo -n " grpc-otel-client.crt: " >> certs-secret.yaml; cat grpc-otel-client-encode.crt >> certs-secret.yaml
    echo "" >> certs-secret.yaml
    echo -n " grpc-otel-server.crt: " >> certs-secret.yaml; cat grpc-otel-server-encode.crt >> certs-secret.yaml
    
  4. Create a new Project for the Controller and Service Proxy deployments:

    oc new-project <project>
    

    In this example, a new Project named spk-ingress is created:

    oc new-project spk-ingress
    
  5. Add the ServiceAccount for the Project to the privileged security context constraint (SCC):

    A. Add the default ServiceAccount:

    _images/spk_info.png Note: See step 6 and to add a custom ServiceAccount to the privileged SCC.

    oc adm policy add-scc-to-user privileged -n <project> -z default
    

    In this example, the default ServiceAccount for the spk-ingress Project is added to the privileged SCC:

    oc adm policy add-scc-to-user privileged -n spk-ingress -z default
    

    B. Use a custom ServiceAccount, and update the SPK Controller Helm values file:

    In this example, the custom spk-ingress ServiceAccount is added to the privileged SCC.

    oc adm policy add-scc-to-user privileged -n spk-ingress -z spk-utils
    

    In this example, the custom spk-ingress ServiceAccount is added to the Controller Helm values file.

    tmm:
      serviceAccount:
      name: spk-ingress
    
  6. Install the Secret key and certificate objects:

    In this example, the Secrets install to the spk-ingress Project:

    oc apply -f keys-secret.yaml -n spk-ingress
    oc apply -f certs-secret.yaml -n spk-ingress
    

    The command responses should state the Secrets have been created:

    secret/keys-secret created
    secret/certs-secret created
    
  7. The new Secrets will now be used to secure the gRPC channel.

Next step

Continue to one of the following guides listed by installation precedence:

  • Optional: Install the Fluentd Logging collector to centralize SPK container logging.
  • Optional: Install the OTEL Statistics collector to centralize SPK container statistics.
  • Optional: Install the dSSM Database to store session-state information.
  • Required: Install the SPK Controller and Service Proxy TMM Pods.

Restarting

This procedure assumes that you have deployed the Controller and Service Proxy Pods, and have created a new set of Secrets to replace the existing Secrets. New Secrets will not be used until the Controller and TMM Pods have been restarted.

_images/spk_warn.png Important: Restarting the Service Proxy TMM Pods impacts traffic processing.

  1. Switch to the Service Proxy TMM Project:

    oc project <project>
    

    In this example, the spk-ingress Project is selected:

    oc project spk-ingress
    
  2. Obtain the name and number of SPK Controller and Service Proxy TMM Pods:

    oc get deploy 
    

    In this example, there is 1 Controller and 3 Service Proxy TMM Pods:

    NAME                  READY   AVAILABLE
    f5ingress-f5ingress   1/1     1
    f5-tmm                3/3     3      
    
  3. Scale the number of Service Proxy Pods to 0:

    oc scale deploy f5-tmm --replicas=0 
    
  4. Ensure 0 of the f5-tmm Pods are AVAILABLE:

    NAME                  READY   AVAILABLE 
    f5ingress-f5ingress   1/1     1
    f5-tmm                0/0     0
    
  5. Scale the TMM Pods back to the previous number:

    oc scale deploy f5-tmm --replicas=<number>
    

    In this example the TMM Pods are scaled back to 3:

    oc scale deployment f5-tmm --replicas=3 
    
  6. Ensure 3 of the f5-tmm Pods are AVAILABLE:

    NAME                  READY   AVAILABLE 
    f5ingress-f5ingress   1/1     1
    f5-tmm                3/3     3
    
  7. Scale the Controller to 0:

    oc scale deployment <name> --replicas=0 
    

    For example:

    oc scale deploy f5ingress-f5ingress --replicas=0
    
  8. Ensure 0 of the Controller Pods are AVAILABLE:

    NAME                  READY   AVAILABLE 
    f5ingress-f5ingress   0/0     0
    f5-tmm                3/3     3
    
  9. Scale the Controller back to the previous number:

    oc scale deployment <name> --replicas=1 
    

    In this example the Controller is scaled back to 1:

    oc scale deployment f5ingress-f5ingress --replicas=1
    
  10. Ensure the Controller Pod is AVAILABLE:

    NAME                  READY   AVAILABLE 
    f5ingress-f5ingress   1/1     1
    f5-tmm                3/3     3
    
  11. The new Secrets should now be used to secure the gRPC channel.

Feedback

Provide feedback to improve this document by emailing spkdocs@f5.com.

Supplemental Information