gRPC Secrets¶
Overview¶
The SPK 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.
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 Controller and Service Proxy TMM Pods to begin using the new Secrets. To replace existing Secrets, refer to the Restarting section of this guide.
Important: Restarting the Service Proxy TMM Pods impacts traffic processing.
Procedures¶
Creating the Secrets¶
Use the following steps to generate the gRPC SSL/TLS keys and certificates.
Change into the directory with the SPK files:
cd <directory>
In this example, the SPK files are in the spkinstall directory:
cd spkinstall
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
Create the gRPC Certificate Authority (CA) signing key and certificate:
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"
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
Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed certificate:
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
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
Create the gRPC client key, CSR and signed certificate:
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.
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
The following code creates the K8S Secret object used to store SSL/TLS keys:
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
The following code creates the K8S Secret object used to store the SSL/TLS certificates:
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
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
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
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
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 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.
Important: Restarting the Service Proxy TMM Pods impacts traffic processing.
Switch to the Service Proxy TMM Project:
oc project <project>
In this example, the spk-ingress Project is selected:
oc project spk-ingress
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
Scale the number of Service Proxy Pods to 0:
oc scale deploy f5-tmm --replicas=0
Ensure 0 of the f5-tmm Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 0/0 0
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
Ensure 3 of the f5-tmm Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 3/3 3
Scale the Controller to 0:
oc scale deployment <name> --replicas=0
For example:
oc scale deploy f5ingress-f5ingress --replicas=0
Ensure 0 of the Controller Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 0/0 0 f5-tmm 3/3 3
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
Ensure the Controller Pod is AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 3/3 3
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¶
- The list of commands used to create the Secrets.
- Introduction to gRPC
- Kubernetes Secrets