gRPC Secrets

Overview

The Ingress Controller and Service Proxy Traffic Management Microkernel (TMM) containers communicate over a secure channel 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 gRPC 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 gRPC Secrets, you must restart the Ingress Controller and Service Proxy TMM Pods to begin using the new Secrets. To restart the dSSM and Service Proxy TMM Pods, 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.

  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 gRPC Secret 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
    

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

    [req_ext]
    
    subjectAltName = @alt_names
    
    [alt_names]
    
    DNS.1 = grpc-svc
    
  5. Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed 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-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. 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
    
  7. Create the gRPC client key, CSR and signed 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-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
    

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:

    cat grpc-ca.crt | base64 -w 0 >  grpc-ca-encode.crt
    cat grpc-server.crt | base64 -w 0 > grpc-server-encode.crt
    cat grpc-client.crt | base64 -w 0 > grpc-client-encode.crt
    cat grpc-server.key | base64 -w 0 > grpc-server-encode.key
    cat grpc-ca.key | base64 -w 0 >  grpc-ca-encode.key
    cat grpc-client.key | base64 -w 0 > grpc-client-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 " grpc-svc.key: `cat grpc-server-encode.key`" >> keys-secret.yaml
    echo " priv.key: `cat grpc-ca-encode.key`" >> keys-secret.yaml
    echo " f5-ing-demo-f5ingress.key: `cat grpc-client-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 " grpc-svc.crt: `cat grpc-server-encode.crt`" >> certs-secret.yaml
    echo " ca_root.crt: `cat grpc-ca-encode.crt`" >> certs-secret.yaml
    echo " f5-ing-demo-f5ingress.crt: `cat grpc-client-encode.crt`" >> certs-secret.yaml
    
  4. Create a new Project for the Ingress 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 default ServiceAccount for the Project to the privileged security context constraint (SCC):

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

    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
    
  6. Install the Secret key and certificate objects:

    oc apply -f keys-secret.yaml
    oc apply -f certs-secret.yaml
    

    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:

Restarting

This procedure assumes that you have deployed the Ingress 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 Ingress 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 Ingress Controller and Service Proxy TMM Pods:

    oc get pods 
    

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

    oc get deploy | grep f5-tmm
    
    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 Ingress Controller to 0:

    oc scale deployment <name> --replicas=0 
    

    For example:

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

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

    oc scale deployment <name> --replicas=1 
    

    In this example the Ingress Controller is scaled back to 1:

    oc scale deployment f5ingress-f5ingress --replicas=1
    
  10. Ensure the Ingress 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